From 1dc839743ec2f99b898160cfe5c22707a65aa623 Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Thu, 30 Jul 2026 18:09:31 -0700 Subject: [PATCH] census: tell the reader where a DELIBERATE-LITERAL marker has to go (#2909) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A `DELIBERATE-LITERAL` marker in the wrong **position** is indistinguishable from no marker, and the miss is silent until CI. **Measured on #2883:** the marker sat inline in the middle of a conditional expression, so it attached to the wrong AST node and three reviewed literals scored as new debt (`self-healing.ts` 86 → 89). The message the tool printed at the time said *"record why at the site with a `DELIBERATE-LITERAL` marker"* — which I had done. Nothing in the output suggested placement was the problem. Two lines added to the failure message: - Markers are read from a node's **leading** comments, so put one on the declaration and hoist the literal into a named helper if needed. - **`pnpm lint` does not run this census** — CI's Lint job does. That is why the usual "lint passed locally, push" loop cannot catch either mistake, and why the tool itself is the only place a reader sees this in time. ## Verified, not assumed I induced a real failure (a temporary `t.column === "in-review"` guard in `self-healing.ts`) and read the printed output rather than trusting that the string lands in the right branch — the message has two branches and only one is the guard-count-rose path: ``` packages/engine/src/self-healing.ts: 89 -> 90 Resolve a lifecycle column from the task's own workflow (…) correct, record why at the site with a DELIBERATE-LITERAL marker. Put the DELIBERATE-LITERAL marker in the DECLARATION's leading comments, not inline in an expression: markers are read from a node's leading comments, so a mid-expression one attaches to the wrong node and is silently ignored. Hoist the literal into a named helper if you need to. Note that `pnpm lint` does NOT run this census — run it explicitly before pushing. ``` Guidance only — no scanner behaviour changes, so no counts move. ## Verification `pnpm test:gate` 161 + 487 + 13 + 71; `pnpm lint` and census `--strict` clean. --- scripts/lifecycle-column-census.mjs | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/scripts/lifecycle-column-census.mjs b/scripts/lifecycle-column-census.mjs index e6f507b3c0..d5136d6fb1 100644 --- a/scripts/lifecycle-column-census.mjs +++ b/scripts/lifecycle-column-census.mjs @@ -545,7 +545,20 @@ if (regressions.length > 0) { " node scripts/lifecycle-column-census.mjs --strict --update-baseline\n" : "\nResolve a lifecycle column from the task's own workflow (resolveLifecycleColumns /\n" + "resolveTaskLifecycleColumns) instead of comparing its name. If the literal is genuinely\n" + - `correct, record why at the site with a ${"DELIBERATE-LITERAL"} marker.\n`, + `correct, record why at the site with a ${"DELIBERATE-LITERAL"} marker.\n` + + /* + FNXC:LifecycleColumnCensus 2026-07-31-09:10 (placement is the failure nobody sees): + A marker in the wrong POSITION is indistinguishable from no marker, and the miss is silent until + CI. Measured on #2883: the marker sat inline in the middle of a conditional expression, attached + to the wrong node, and three reviewed literals scored as new debt (self-healing.ts 86 -> 89). + + The second line is here because `pnpm lint` does NOT run this script — CI's Lint job does — so + the usual "lint passed locally" loop cannot catch either mistake. + */ + `\nPut the ${"DELIBERATE-LITERAL"} marker in the DECLARATION's leading comments, not inline in an\n` + + "expression: markers are read from a node's leading comments, so a mid-expression one attaches to\n" + + "the wrong node and is silently ignored. Hoist the literal into a named helper if you need to.\n" + + "Note that `pnpm lint` does NOT run this census — run it explicitly before pushing.\n", ); process.exit(1); }