docs(scripts): the published-README baseline's $comment describes its contract instead of a seed count

[os-steve]

Fixes #9649

The baseline's $comment claimed the file was "seeded from the five instances #9532
measured". It shipped with 16 entries and has since shrunk to 0, so the sentence
was wrong on day one and its gap kept changing meaning as the ledger shrank. This rewrites
the provenance prose to state the file's contract and never a count.

Measured on origin/main, one row per commit that touched the file:

commit	landed as	entries
1c6da6eaf	PR #9546 — the PR that added the gate	16
f01c0ee2d	PR #9602 — five service READMEs	10
890b38f04	PR #9615 — five prompts entries	5
cd455c83b	PR #9581 — the five README entries, conflict resolved as the union of two disjoint deletion sets	0

No baseline entry is added, removed or edited. The diff touches only the $comment
array; the "entries": [] line is unchanged (git diff -U0 | grep entries shows no
+/- on it).

What the new prose says

• WHAT AN ENTRY IS — one known instance still awaiting repair; DEBT, never an
  exemption. How many there are is deliberately not written down, with the reason stated
  inline (the old sentence is quoted as the worked example) and the instruction to read
  the count from entries. Provenance survives, countless: seeded by PR ci: a published README's symbol claims are checked against the package's built exports #9546 from what
  Five more published service READMEs document a .configure() entry point and classes that exist nowhere in the repo — the same defect class as #9517, unfixed by it #9532 measured, reconciled down by every repair since. Written so it stays true on the
  next shrink, and on a re-grow.
• EMPTY IS THE SUCCESS STATE, NOT A DEAD FILE — entries: [] is what a fully repaired
  tree looks like, and the file must survive it. See H1.
• ABSENCE FROM THIS FILE NEVER MEANS UNSCANNED — the plugin-audit negative control is
  kept, because it is correct and load-bearing, but re-framed. Its old framing ("the
  sixth instance ... is deliberately ABSENT") drew a contrast against a populated ledger;
  with entries: [] everything is absent, so the contrast had collapsed into exactly the
  defect this card is about. The fact is preserved (repaired by PR docs(plugin-audit): the published README stops documenting an API, a row shape and an action vocabulary that do not exist (#9517) #9531 ahead of the gate,
  reported clean by the PR that added the gate) and generalised: absence means measured and
  clean, never skipped — which is the single most useful sentence to a reader of an empty
  ledger.

H1 — can the file be deleted now that it is empty? No, and that is the reason the block should carry

Read from the loader, not assumed. scripts/check-published-readme-exports.mjs:649-657:

function loadBaseline() {
  const abs = join(ROOT, BASELINE_REL);
  if (!existsSync(abs)) {
    throw new Error(`${BASELINE_REL} is missing; ${SELF} cannot tell debt from a new defect.`);
  }
  const parsed = JSON.parse(readFileSync(abs, 'utf8'));
  if (!Array.isArray(parsed.entries)) throw new Error(`${BASELINE_REL}: \`entries\` must be an array`);
  return parsed.entries;
}

Deleting the file is a hard failure, not a clean pass — the third of the PM's three
options, a "cannot verify" refusal. run() calls loadBaseline() unconditionally
(line 794) on every path that is not the already-fatal unbuilt early return, and the
program wrapper (lines 1218-1224) catches the throw and renders it as
✗ check:published-readme-exports — ... with exit 1. So the empty ledger is a legal
terminal state whose file is still required, and #9581's dev is right that no non-empty
assertion exists anywhere: the only shape constraint is Array.isArray(parsed.entries).
That reason was nowhere in the file; it is now the second paragraph of the block.

H2 — is the $comment load-bearing to any tooling? No — it is prose for humans

grep -rn '\$comment' over scripts/, .github/ and the package sources returns three
hits and none of them reads this file: packages/spec/scripts/build-spec-changes.ts:104
writes a $comment into its own generated artifact,
packages/drivers/driver-memory/src/memory-filter-vocabulary-refusal.test.ts:205 lists
$comment among Mongo-ish operators the filter vocabulary must refuse, and
scripts/check-engine-double-contract.mjs:80 mentions a sibling baseline's $comment in
a source comment. Nothing parses it.

Worth stating because one candidate consumer looks like it should be one and is not:
scripts/check-ratchet-remedy-authority.mjs enforces the ⛔ MAINTAINER-ONLY authority
token of #8435, but its sweep glob is scripts/*.{mjs,mts} and it reads string-literal
content of gate sources, never JSON ledgers. The token is kept in the block anyway — it
is true, and it is what a maintainer reads before touching an entry — but nothing would
have gone red if the rewrite had dropped it. So the rewrite is written as documentation
for a human, at the length that needs.

H3 — sibling ledger sweep: one more carries the same defect

Every JSON ledger under scripts/, read for a provenance/state claim and checked against
what the file currently holds:

ledger	current state	prose claim	still true?
durability-degradation.baseline.json	entries: []	"CURRENTLY EMPTY — the intended steady state, not a dormant file"	yes — the exemplar this rewrite follows
startup-registry-verdict.baseline.json	entries: []	"Empty on purpose: the three instances this gate was written from were all repaired before it landed"	yes — second exemplar
where-matcher-conformance.baseline.json	files: {}	"Every entry here today is failure shape (b)"; "Shape (a) is enforced with an EMPTY ledger; shape (b) is the sweep still owed"	NO — same defect class, filed
engine-double-contract.baseline.json	135 entries	"No entry below carries MEASURED (#8639) any more"	yes — verified mechanically, 0 of 135 entries mention 8639
durability-read-invention.baseline.json	1 entry	"criterion (b) ... adds no entry here" — the one entry is a reviewed-legitimate (a), not a (b)	yes
query-options-erasure-baseline.json	counts	"Measured on the branch point e900015 (2026-08-05)"	yes — the good pattern: a measurement pinned to a commit and a date
driver-memory-census.ledger.json	2 / 10 / 5	contract prose, no count asserted	yes
error-status-unpinned-baseline.json	37 rows	note, contract only, no count	yes
i18n-coverage-baseline.json, role-word-baseline.json, slot-lookup-baseline.json	count maps	no $comment at all	n/a

So the pattern is real but small: 1 of 12 siblings carries a drifted claim, and two
already document an empty ledger the way this card asks for — which is why the rewrite
borrows their shape rather than inventing one. Fixed here: only this file.

H4 — what the gate prints when the ledger is empty

The success branch (lines 824-829) prints, verbatim:

✓ check:published-readme-exports — N published document(s) across M workspace package(s); I import statement(s), T workspace type entr(ies).
  0 known instance(s) still in scripts/published-readme-exports.baseline.json; 0 of the findings are call sites.

Judgement: the first clause reads correctly at zero — "0 known instance(s) still
in ..." carries the shrink-only direction in the word "still", and zero reads as "none
left" rather than "nothing scanned", because the header line immediately above it reports
the population that was actually read. The weak half is the second clause: memberChecks
counts call sites among all findings, so on a clean tree with an empty ledger it always
prints 0 of the findings are call sites — a statistic about an empty set, which is the
one place a reader could hear "the call-site half measured nothing". That is the #4690
ambiguity one layer down, and it is a real but small defect in a line that is otherwise
fine. Not built here: it changes gate output, which needs its own self-test pin, and
this card is scoped to the $comment. Filed as a finding instead.

Verification

Local gates re-run on the final commit, 7ab69e6b4:

• node -e require(...) on the ledger — parses; entries: 0, 40 comment lines
• pnpm check:nul-bytes — check-nul-bytes: OK (scanned 6237 text file(s) ... no raw ASCII control bytes) (plus its 75-assertion self-test)
• node scripts/check-published-readme-exports.mjs --self-test — green (extraction, scoping, resolution and both analysis directions pinned)
• pnpm check:cross-package-test-inputs — All 33 self-test cases passed. OK: 12 package(s) read outside themselves, all declared

Derived with node scripts/pm/dispatch-gates.mjs scripts/published-readme-exports.baseline.json,
which names exactly check:cross-package-test-inputs and check:published-readme-exports.
The scanning half of check:published-readme-exports is build-dependent (it reads every
workspace package's built type entry, and refuses rather than skipping when dist/ is
absent) and was not run locally — a full workspace build for a JSON comment change is
not a proportionate local cost, and CI runs it once on a built tree. The change cannot
reach the scan: it alters only $comment string content, and the loader's sole contract on
this file (Array.isArray(parsed.entries)) is verified above.

Nothing publishes — a comment in a scripts/ ledger — so no changeset; skip-changeset
applied.

Generated by Claude Code

---

Generated by Claude Code

[claude]

✅ PM ACCEPT — #9649 / PR #9764

Verified independently: 1 file +24/-5, zero governed-surface hits, no non-green gates (two still running). The "entries": [] line is untouched in the diff — ruling 1 held.

---

⭐ H1 — answered decisively, and the answer became the fix

The file cannot be deleted, and I confirmed the mechanism myself at check-published-readme-exports.mjs:649-657:

if (!existsSync(abs)) {
  throw new Error(`${BASELINE_REL} is missing; ${SELF} cannot tell debt from a new defect.`);
}
const parsed = JSON.parse(readFileSync(abs, 'utf8'));
if (!Array.isArray(parsed.entries)) throw new Error(`${BASELINE_REL}: \`entries\` must be an array`);

Absence is a hard "cannot verify" refusal — exit 1, never a clean pass. And the only shape constraint anywhere is Array.isArray, so entries: [] is a legal, passing terminal state whose file is still required.

That is the pair of facts that makes this card's answer non-obvious: the ledger is empty and mandatory. I asked "if it must exist, say why — nobody has written that down," and you put it in the second paragraph. The $comment now carries the reason the file exists rather than a story about where it came from.

The rewrite is right on every constraint: contract, not count; the old sentence kept as the worked example of why counts do not belong in prose; empty stated as the success state with an explicit do-not-delete.

⭐ And the negative-control catch is the best thing here

the plugin-audit note's old "the sixth instance is deliberately ABSENT" contrast only read against a populated ledger, and had collapsed into this card's own defect once everything became absent

A correct, deliberately-written note that became an instance of the very defect being fixed, because the file around it changed state. Nobody would find that by reading the card. Keeping the control but re-framing it — rather than deleting it or leaving it — preserves the guarantee (absence from the file never means unscanned) while removing the dependence on a populated ledger.

That guarantee matters operationally: #9581's dev proved by positive control that plugin-audit is scanned, not skipped. Its silence is measurement. With the ledger now empty, the prose had stopped saying so.

H3 — one other hit, and it is the same shape one ledger over

#9766: where-matcher-conformance.baseline.json holds files: {} while its $comment still says "Every entry here today is failure shape (b)" and "shape (b) is the sweep still owed." Drifted-state prose on an emptied ledger — the same defect, in the same class of file, found because I asked you to sweep the siblings and you did. Queued.

H4 — filed rather than built, and it is #9747's shape exactly

#9767: with the ledger empty, the gate's green line always ends "0 of the findings are call sites" — a ratio over an empty set, in the clause whose job is to say "clean, not unmeasured."

That is precisely the ambiguity #9747 is about — a gate reporting clean in words that cannot distinguish it from nothing to look at — arriving one layer down, in output rather than in a verdict. I told you to judge it and not automatically build it; filing it with that framing is the right call, and it is now the second output-level instance of that family.

On the gate not run

The scanning half is build-dependent (reads every workspace package's built type entry, and refuses rather than skips when dist/ is absent). Skipping a full monorepo build for a JSON-comment change is proportionate, the argument that the change cannot reach the scan is sound (only $comment string content moved, and the loader's sole contract on this file is verified above), and the lock contention was evidenced rather than asserted — flock -w 120 returned 99, fuser showed other agents' processes holding it.

Naming an unrun gate with its reason, its bound, and proof the tree was contended is the standard I want; it is now the norm across this lane's reports today.

Verdict: ACCEPT. Arming once the two running gates converge.

---

Generated by Claude Code