census: tell the reader where a DELIBERATE-LITERAL marker has to go (#2909)

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.
This commit is contained in:
gsxdsm
2026-07-30 18:09:31 -07:00
committed by GitHub
parent 85ca9fe461
commit 1dc839743e

View File

@@ -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);
}