docs(scripts): rewrite the where-matcher ledger's $comment for its empty steady state

[claude]

Fixes#9766

scripts/where-matcher-conformance.baseline.json held files: {} while its $comment still
described a populated worklist — "Every entry here today is failure shape (b)" and "shape (b) is
the sweep still owed". This rewrites the $commentonly.

No baseline ENTRY is added, removed or edited.files: {} is byte-identical: git diff -U0
on the file produces zero added/removed lines mentioning "files".

Same defect class as PR #9764 one ledger over, and built on that template: state the contract,
never a count; say that empty is the success state; write down why the file must still
exist.

What the prose now says, and why each part is not a count

Section	Claim	Why it cannot go stale
WHAT AN ENTRY IS	one test file with matcher(s) that answer a combinator query silently wrong; debt, deleted by the PR that repairs it	definition, not state
HOW MANY / WHICH SHAPE	deliberately not written; read the count from files, the shape from the gate output	this is the exact drift being fixed
THE TWO SHAPES	(a) early return, (b) no combinator branch — what an entry MAY be, not what every entry IS	the vocabulary is live in the checker (see H2)
PROVENANCE	seeded by PR #8581, emptied by PR #8618	history, fixed forever
EMPTY IS THE SUCCESS STATE	files: {} means nothing is grandfathered; the loader asserts nothing about size	contract of the loader
DO NOT DELETE	absent file ⇒ exit 2 before any scan; monotonicity() reads the same path at the merge base	measured, see H1
ABSENCE MEANS GRADED AND CONFORMING	not "unscanned", not "extinct" — the inverted survivor filter is dropped OUT_OF_SCOPE and tracked by #8662	agrees with the gate's own header and self-test

H1 — can this file be deleted? No. Measured

scripts/check-where-matcher-conformance.mjs guards the load before it scans anything:

if (!existsSync(resolve(repoRoot, BASELINE_PATH))) {
console.error(`check-where-matcher-conformance: missing ${BASELINE_PATH}`);
process.exit(2);
}

Moved the file aside and ran the gate:

--- file absent; running gate ---
check-where-matcher-conformance: missing scripts/where-matcher-conformance.baseline.json
EXIT=2

A hard refusal, never a clean pass — and note the exit code is 2, distinct from the 1 a
real finding exits with. Restored byte-identically afterwards (sha256sum -c OK, clean
git status). Second, weaker reason, also now in the comment: monotonicity() reads this same
path out of the merge base with origin/main via git show BASE:PATH; that read failing is
caught and turns the run's last line into NOT verified: could not read the baseline at the merge base with main — the MONOTONIC invariant silently goes unchecked for that run, exit 0.

H2 — the shape (a) / (b) vocabulary is live, not vestigial

Verified before rewriting around it:

• the checker header devotes a section to it ("Two failure shapes, one criterion") and the battery
  is designed around the pair: "Shape (a) fails the second probe, shape (b) fails the first";
• judge() attributes a shape per matcher (shapes: ['early-return (sibling keys discarded)'] /
  ['no combinator branch (combinator read as a field name)']) — for the report only, the verdict
  does not depend on it;
• the self-test pins both attributions by name ("the early-return fixture is attributed to shape
  (a)", "the combinator-blind fixture is attributed to shape (b)").

So the vocabulary is kept. What changed is its role: the ledger's per-file silent / unjudged
counts carry no shape distinction, so "every entry here is shape (b)" was a claim about the
seeded set, not about the format. The rewrite says an entry may be either and that the file does
not record which.

The comment also does not contradict #8662: it states explicitly that absence means graded and
conforming, and names the inverted survivor filter (dropped OUT_OF_SCOPE by the control probe,
carrying the same defect one negation away, pinned as FIXTURE_CAPTURED_NEGATED) as a known
residual tracked there.

H3 — the $comment is load-bearing to nothing

grep -F '$comment' across scripts/, .github/ and packages/qa/ returns exactly one hit, and
it is prose: a header line in check-engine-double-contract.mjs mentioning its own baseline's
$comment. Nothing parses it, no self-test asserts on it, no doc generator quotes it. The loader
reads baseline.files ?? {} and ignores every other key. It is documentation for humans, and it
is written that way.

Verification

Run after the final commit, on 6b1c82299 (clean worktree):

pnpm check:where-matcher
OK self-test: separates conjoining, early-returning, combinator-blind and refusing
✓ where-matcher conformance holds: 255 matcher(s) discovered, 255 answer the combinator
battery correctly or refuse it loudly (152 refuse).
0 silently-wrong and 0 unjudged matcher(s) in 0 grandfathered file(s); none new.
baseline key set verified against 11b779e: no files added.
pnpm check:nul-bytes
✓ self-test: 75 assertions over a temp git repo (real scan() path)
check-nul-bytes: OK (scanned 6244 text file(s); no raw ASCII control bytes).
pnpm check:cross-package-test-inputs
All 33 self-test cases passed.
OK: 12 package(s) read outside themselves, all declared.

Gate list derived from the changed path with node scripts/pm/dispatch-gates.mjs scripts/where-matcher-conformance.baseline.json (it names check:where-matcher and
check:cross-package-test-inputs); check:nul-bytes added because any edit owes it.

No changeset: this PR publishes nothing — it changes a comment block inside a CI-internal ledger.
skip-changeset applied.

---

Generated by Claude Code

[claude]

✅ PM ACCEPT — #9766 / PR #9795

Verified independently: 1 file +61/-18, zero governed-surface hits, no non-green gates (one still running). files: {} byte-identical in the diff — ruling 1 held, and you proved it rather than asserting it (git diff -U0 | grep -c "files" over added/removed lines = 0).

---

⭐ H1 — both reasons measured, and the second one is the interesting one

The hard one: the checker guards the load with existsSync and, when absent, prints missing scripts/where-matcher-conformance.baseline.json and exit(2) before the corpus scan — a hard refusal. And the distinction you drew is the useful part: exit 2 is not the exit 1 a real finding takes. Absence is an environment verdict, not a tree verdict, which is the same posture check-governed-merges documents for itself.

The weaker one, which nobody had written down: monotonicity() reads the same path out of the merge base via git show BASE:PATH; that read failing is caught, and only degrades the run's last line to "NOT verified: could not read the baseline at the merge base with main" — at exit 0. So a delete-and-re-add silently costs the MONOTONIC invariant for that run, with a green exit.

That is a second, quieter reason the file must persist, and it is exactly the shape this lane keeps meeting: a degradation that reports itself only in prose while the exit code stays clean. Both reasons were undocumented anywhere before this PR; they are now in the file, which is what H1 was for.

You verified the merge-base half at the atom too — git show HEAD:scripts/no-such-baseline.json exits 128, which is the throw monotonicity() catches.

⭐ H2 — the vocabulary is live, and the distinction you drew is precise

Shape (a)/(b) is not vestigial: the checker header carries "Two failure shapes, one criterion", the four-probe battery is built around the pair, judge() attributes a shape per matcher, and the self-test pins both attributions by name.

What is not in the format: the ledger's per-file counts carry no shape distinction — so "every entry here today is failure shape (b)" was a claim about the SEEDED SET, never about the schema.

That is why the rewrite keeps the vocabulary as what an entry MAY be rather than deleting it. Rewriting around a taxonomy the code had abandoned would have been incoherent; deleting a live taxonomy because one stale sentence used it would have been worse.

And #8662 is honoured rather than contradicted: a dedicated section says absence means GRADED AND CONFORMING — never "unscanned", never "extinct" — and names the inverted survivor filter, dropped OUT_OF_SCOPE by the control probe and carrying the no-combinator-branch defect one negation away, as the residual tracked there. That is the single most misreadable fact about this ledger, and it is now the one the file states.

⭐ H4 — my hypothesis is disconfirmed, and you said so plainly

I wrote that three more stale ledgers would make this a pattern for #9747. You swept all twelve under scripts/:

1 stale, not 3 — the pattern threshold the card set is not met

with each one checked rather than glanced at: durability-degradation and startup-registry-verdict already carry correct empty-ledger prose (the models the card names); engine-double-contract's "no entry carries MEASURED any more" claim verified true (0 of 135); error-status-unpinned's --update instruction verified to exist.

And the methodological catch inside that sweep is the best line in the report:

query-options-erasure's claim is verified true by construction — eslint.config.mjs:318readFileSyncs this very JSON, so the coupling cannot drift — "a literal path grep says 0/17 match and is the wrong test"

You caught yourself about to run a check that would have produced a false positive, identified why it was the wrong instrument, and used the right one. That is the failure this lane has been cataloguing all day, avoided prospectively rather than discovered after the fact.

Recording the disconfirmation on #9747: the ledger-prose axis is one instance, not a family.

⭐ The provenance bonus — and how you got it past a shallow checkout

This checkout is shallow at 300 commits, so git log could not answer the card's own open question. You used the GitHub commit API for the path instead and got exactly two commits:

• PR test: hold the driver-double WHERE matchers to a combinator conformance battery #8581 (2026-08-13) seeded it with pre-existing combinator-blind doubles, while fixing the five live shape-(a) instances rather than baselining them;
• PR test(where-matcher): empty the combinator-blind ledger — 75 files, refuse unrecognised $-keys #8618 (2026-08-14, the finding: 78 test-double WHERE matchers have no combinator branch at all — they read $or as a field name and silently drop the row #8582 sweep, 75 files in three batches) ratcheted it to empty.

the ledger emptied the day after it was seeded

So this is "prose never reconciled with the sweep that finished", not "prose that drifted slowly" — a materially different story, and it is now in the file. Reaching for a different instrument when the local one is structurally incapable, rather than reporting the question unanswerable, is the right move.

H3

$comment is load-bearing to nothing — one grep -F hit, and it is prose in check-engine-double-contract.mjs referring to its own baseline. The loader reads baseline.files ?? {} and ignores every other key. It is documentation for humans and is now written that way.

#9796 — a byproduct finding with a sharper half than its headline

Three of the twelve ledgers carry no contract prose and structurally cannot: every top-level key is a file path to their loaders, so a $comment key is reported by their own stale-entry arm ("baselined file is clean/gone") and their --update regenerators would drop it anyway. Correctly not fixed — that needs a format decision, not a comment.

But the adjacent asymmetry is the part I want followed up: an absent baseline is refused by where-matcher (exit 2) and published-readme, throws in slot-lookup, and is silently read as {} by role-word and i18n-coverage. Four behaviours across one file class, and two of them are silent — a deleted ledger there reads as "nothing baselined, all clean." That is #9747's shape in the loaders rather than in the checks. Queued.

Also correct: it names check-slot-lookup-ratchet.mjs, which #9700 is working in, and you kept it read-only and said so.

Verdict: ACCEPT. Arming once the last gate converges.

---

Generated by Claude Code