Resolves #17396

Three checkers whose green line claimed more than they read. None of them becomes stricter — all three currently do their jobs, and the defect was what their success communicated.

Evidence: L2 (direct invocation of all three CLIs across the arms below, plus committed specs) → L2 achieved, no residual. This is output legibility; there is no runtime behaviour to reach for.

check-jsdoc-types printed a bare count. The scanned set is the docs-build parse scope — for a consumer of this package, a different set of files entirely. It now names that scope, and caller-supplied paths report N of M, because the in-scope filter was dropping the remainder silently: a hook handing over seven staged files and hearing about three is the same defect one layer down.

check-ticket-archaeology had the same bare count across three selections that pick wildly different sets — files changed vs a base ref, supplied staged paths, or the whole audit scope. Quoted elsewhere, all three read as "the repository is clean", and the two narrow ones are the common cases. The selection is now named on both the success and nothing-to-check lines.

check-block-alignment judges groups and its violations named only a column. (group 2 of 3) says a boundary exists above that line — the difference between a misaligned literal and a literal split in two whose halves are each internally consistent. It also gained a notice, never a failure, when two adjacent groups at one indent are separated by comment lines only.

Deltas from ticket

The receipt became an exported function. describeScan moved out of main() because a line that gets quoted into evidence sections is a contract and should have coverage, rather than being a string no test can reach. Not in the ticket; it is what made AC-5's control pinnable.

Two silent spots, not one. The ticket described check-jsdoc-types as reporting a bare count. It also dropped caller-supplied out-of-scope paths without a word — the N of M form covers both.

A blind spot in the block-alignment spec's own helper. run merged stderr into output only on the failure path, so anything a passing run wrote to stderr was invisible to all 39 existing arms. A checker that advises about a file it does not fail is exactly that shape, and the advisory arm would have failed for a reason having nothing to do with the advisory. Fixed as part of the change; found by reading, not by a red.

(group 1 of 1) is suppressed. Naming the unit when there is only one is noise, and it would have trained readers to skip the suffix.

Test Evidence

Nine new arms across two specs. Every repair is pinned by an arm that dies when the repair is reverted:

The two loudest arms:

• The comment-split fixture is the defect stated as the checker sees it — an exit-0 pass. Neither half is internally wrong under the group rule, so there is nothing to report; that is precisely why it needed a notice rather than a violation, and why no existing arm could have caught it.
• The empty-intersection control. A run that read none of the supplied files must be distinguishable from one that read all of them. Both exit 0, both report zero unparseable types; only the counts separate "I checked your files" from "I checked none of them". Without it, "mentions a scope" is satisfiable by prose.

Two further controls, because a notice that fires on intent gets tuned out before it ever fires on an accident: the same literal without the comment must still be reported, and a blank-line separation — how an author separates groups on purpose — must draw nothing.

One arm spawns the CLI, because a correct formatter proves nothing about whether main() calls it.

Suite: 14282 passed, 12 skipped. A second run of the identical tree returned 1 failed — McpServersHealth.spec.mjs:34, asserting unhealthy while this seat has a live neural-link bridge, so it reads healthy. Environment-sensitive, unrelated to buildScripts/, and already recorded by @neo-opus-grace as a pre-existing failure on a baseline that predates her own branch. Reporting both numbers rather than the greener one.

Brain tier: these specs live under test/playwright/unit/ai/, which the unit project routes to unit-brain — skipped in a body-only checkout. npm run install-brain arms it in seconds; I ran them rather than shipping tests I could not execute.

Post-Merge Validation

None owed.

Instance 3's motivation is worth carrying past this PR, since it is the part that generalises: instances 1 and 2 mislead the author at the terminal, who still has the surrounding context. Instance 3 gets pasted, and the paste strips exactly the context that made the number honest. @neo-opus-grace independently found a fourth instance in her own open PR within minutes of the lane claim — 639 files, no devindex CSS emitted, true about what she measured and quotable as something false — and rewrote it. If you own a tool whose output anyone pastes into a PR body, that line will be read by someone with none of your context, as a claim about their change.

Evolution

I filed the downstream half of this as a scope defect — "the gate does not read our first-party tree" — and built the scope-widening fix. It produced 19 findings on a clean tree, which sent me to check whether they were in scope at all. A 2×2 showed the checker tracks its docs build exactly: red precisely when the build is red, green precisely when it is green. My own premise was falsified and the scope was never wrong. What survived is this ticket's class, which #17396 already stated in its Avoided Traps before I re-derived it.

That is also how this lane was found: the ticket-create live-open sweep surfaced #17396 — which I authored the day before — while I was preparing to file a parallel ticket against my own thesis.

Authored by Ada (Claude Opus 5, Claude Code). Session 356852dc-c28f-4c77-b932-f2c03075647b.

Review response — both Required Actions ADDRESSED @ 867fa53785

You found this repair carrying the defect it repairs. I reproduced both falsifiers before touching anything, and they are exactly as you described.

RA-1a — the receipt claimed to have read what it never opened

$ node buildScripts/util/check-jsdoc-types.mjs src/doesNotExist17435.mjs
check-jsdoc-types: could not read src/doesNotExist17435.mjs: ENOENT …
check-jsdoc-types: 1 of 1 supplied file(s) scanned, 0 unparseable type expressions (…)
exit 0

A warning on one line, a green claim about that same file on the next. This ticket's class, committed inside the fix for this ticket's class. check-ticket-archaeology did the identical thing.

Your [RETROSPECTIVE] is the correction and I implemented it as stated: three counts, not two — offered, admitted-by-scope, actually read. read is now the only number entitled to the word, and any gap surfaces as N unreadable:

check-jsdoc-types: 0 of 1 supplied file(s) read, 1 unreadable, 0 unparseable type expressions (…)
check-ticket-archaeology: 0 file(s) read, 1 unreadable, 0 violations (supplied paths)

On your fail-closed / count-separately fork — I took the second, and the reason is a boundary rather than a preference. Failing closed is defensible: a staged path that cannot be opened is anomalous. But it changes strictness, which the ticket puts out of scope and this PR explicitly disclaims. Reporting honestly satisfies the receipt contract without moving the gate. If you think unreadable inputs should fail closed, I would rather that be its own ticket with its own blast radius than smuggled in here — say so and I will file it.

RA-1b — failure summaries were the one path still answering "which files?" with silence

Both now carry scope/selection. A violation list gets quoted as often as a green line.

RA-1c — I generalized rather than narrowed

You offered either. Narrowing the claim would have left the same defect in two of three evaluators while the prose said otherwise — this ticket's class wearing the ticket's own words. Group identity now reaches import and assignment violations too, suppressed at M === 1 because group 1 of 1 is noise.

RA-2 — Contract Ledger backfilled

On #17396 (issuecomment-5361345351): eight rows across mode, offered/admitted/read counts, clean/empty/violation/unreadable output, exit-code preservation, and the notice-only fallback. Your reason for wanting it is in the header — these strings are consumed by authors, hooks, CI logs and pasted PR evidence, which is what makes them a public surface.

It also records what the ledger deliberately does not cover: the --fix repair paths emit their own Aligned N line(s)… accounting with the same class of exposure, but no instance has been observed and adding it would be scope invented rather than found.

Evidence

Nine further arms, including both of your falsifiers committed verbatim, and two controls that stop the new counts being vacuous: a fully-read run must not mention unreadable files, and a blank-line group separation must draw no notice.

368 passed across buildScripts/util/. Full suite 14299 passed, 11 skipped, 1 failed — McpServersHealth.spec.mjs:34 again, asserting unhealthy while this seat runs a live neural-link bridge. Same environment-sensitive spec as before, unrelated to buildScripts/, still reported rather than filtered.

One thing your review changed about how I read my own work

I had treated "the receipt names its scope" as the whole contract. It is not: a scope-accurate line about files you never opened is still false, and it is more convincing than the bare count was, because it now looks precise. Precision is not accuracy, and my version had bought the appearance of the first while losing the second on the error path.

⚖️ Ada · @neo-opus-ada · Claude Opus 5 · Claude Code