fix(qa): close the platform-checklist traps vocabulary against RUNNER.md, with a parser that refuses rather than fails open

[claude]

Fixes#10647

check-platform-checklist enforced a closed vocabulary for status, priority, surface, oracle and blocked.by — and never read traps at all. The string did not appear in the file. So an item could carry any trap name and the validator stayed green, which is how eight undocumented values drifted in (#10416), and how a typo in a documented one lands as simply a twentieth trap that no runner rules out.

Counts re-derived on this tree

Parsing all 15 docs/qa/platform-checklist/areas/*.json (205 items) against RUNNER.md's ### Trap vocabulary table, post-#10650: 19 documented / 19 distinct in use / 0 used-but-undocumented / 0 documented-but-unused. As the brief predicted. hydration-race is on 79 of the 205 items; 197 items carry a traps list, 8 carry none. The gate now prints the pair on its own OK line, so the number is re-derived on every run instead of recalled.

Both harms, before and after

harm	current validator	this PR
(a) an invented trap (totally-invented-trap added to cli.build-own-contract)	OK — 15 areas, 205 items … exit 0	exit 1 — traps[1] `totally-invented-trap` is not in RUNNER.md's `### Trap vocabulary` table
(b) a typo in a documented one (hydration-race → hydration-races on records-forms.crud-roundtrip)	OK — 15 areas, 205 items … exit 0	exit 1 — traps[0] `hydration-races` … — did you mean `hydration-race`?

Both mutations were confirmed on disk by anchor count before each run (0 → 1 for the injected spelling), never by an editor's exit code.

Why this is not a sixth Set, and not a generator either

• A hardcoded TRAPS set reintroduces the same drift one level up — between this script and RUNNER.md — with nothing watching that seam. Rejected in the card, and it is the wrong answer for the same reason the eight arrived.
• Inverting it (generate the table from a declared set) means moving all of the table's authored prose — two columns, several rows a paragraph long — into a JS/JSON source and generating RUNNER.md, or splitting one row across two homes. RUNNER.md is a hand-written process document other people execute, and this gate runs on a manual cadence with no CI wiring; adding a "regenerate and commit" ratchet to it buys one source at the cost of restructuring the document. Rejected on scope and on posture.
• Parse the table is what landed — but the parser is not the load-bearing part. The positive control is.

A markdown-table extractor has one failure mode that matters: it reads zero rows and every item then validates against an empty allow-list. Zero violations, and a green indistinguishable from a working parse. So extractTrapVocabularyrefuses — it never returns an empty vocabulary with no complaint — and a 22-assertion fixture battery proves the refusal still fires. The battery runs inline on every invocation, not only behind --self-test, because a --self-test here would execute nowhere: this gate is not CI-wired by maintainer decision (README "Operating cadence") and its pnpm alias lives in root package.json, fenced territory of the @changesets/cli v3 lane (#9465). A self-test nothing runs is the documented defect of #10574/#10573.

The fail-open control

Making the table unreadable, four ways, each confirmed on disk by anchor count (19 trap rows → 4 non-trap rows elsewhere in the file; heading count 1 → 0; backticked row 1 → 0):

RUNNER.md mutation	result
all 19 rows deleted (header + separator remain)	exit 1 — has a header but ZERO rows … this is a refusal — never an empty allow-list
heading renamed to ### Traps you may hit	exit 1 — the "### Trap vocabulary" heading is not in the file — renamed, moved or removed
one row loses its backticks	exit 1 — 1 row(s) … do not name a single backticked trap in the first cell — e.g. "| wrong-panel | …"
header row replaced by a different table's	exit 1 — is not the trap table — expected a "| trap | … |" header row

And the counterfactual, which is what makes the above load-bearing. A copy of this same file with the refusal downgraded to an empty set, the positive control neutered, and the natural defensive guard (if (vocabulary.size > 0 && !vocabulary.has(name))), run against the emptied table:

--- shipped check: EXIT=1 cannot read the trap vocabulary out of … RUNNER.md — … ZERO rows …
--- fail-open counterfactual: EXIT=0 OK — 15 areas, 205 items (205 active); … traps: 0 documented, 19 in use

That green is the defect, exactly as the card describes it.

Ablations

Every new assertion broken, driven red, restored. Mutation confirmed on disk by anchor count each time; the prediction was written before the run.

ablation	predicted	observed
AB-1a: trapProblems' vocabulary branch disabled, control intact	control red	✅ exit 1, exactly 3 failures: C3, C4, C5
AB-1b: same, plus the control neutered, harm (a) planted	green — isolating the source of the red	✅ exit 0, and the OK line reads 19 documented, 20 in use
AB-2: documented-but-unused — an unused row planted in RUNNER.md	red, then green when the loop is disabled	✅ exit 1 naming never-used-trap; ablated → exit 0, 20 documented, 19 in use
AB-4: extractTrapVocabulary's refusal neutered, control intact	control red, exactly 9 failures (R1–R8 + R9)	✅ exit 1, exactly 9

AB-1a is worth reading twice: the first attempt at this ablation predicted that harm (a) would flip to green, and it did not — the inline control caught the deleted assertion before the run ever reached real data. That is the design working. Isolating the data-side red needed AB-1b, where the control had to be removed too. The shipped assertion cannot be quietly deleted.

Verification

Everything below on 1538eb4c — the final commit — with the gate union re-derived on that same HEAD.

node scripts/pm/dispatch-gates.mjs (no paths; derives its own change set from the merge base)
→ 2 path(s) vs merge base 55809a09a
→ pnpm check:cross-package-test-inputs [lint.yml] via scripts/**
→ node scripts/check-cross-package-test-inputs.mjs [ci.yml]
check:cross-package-test-inputs OK: 13 package(s) read outside themselves, all declared …
check:nul-bytes OK (scanned 6215 text file(s) … no raw ASCII control bytes)
check:entry-guard ✓ 123 scripts/ file(s) — every entry guard goes through invoked-as.mjs
check:parse-guard ✓ 122 scripts/ file(s) — every TypeScript parse goes through ts-parse.mjs
check:doc-authoring ✓ 389 files clean — no bare metadata literals (ROOTS includes `docs`)
check:platform-checklist OK — 15 areas, 205 items (205 active); coverage: 30 kinds mapped,
0 waived; traps: 19 documented, 19 in use (extractor control: 22 assertions)
--self-test ✓ 22 assertions
checklist-select --self-test ✓ 17 cases pass

check:doc-authoring was added by hand, not by the derivation — the brief flagged that it reads docs/** and is invisible to dispatch-gates until #10662 declares it, and this diff edits docs/qa/platform-checklist/README.md. The other hand cross-check went the other way: check:doc-anchors is genuinely irrelevant here, not merely unrun. Its population is content/** plus the repo-root README.md and ARCHITECTURE.md only, and its own docblock says a same-named file inside a subtree "is not reached — which is correct". So the derivation's silence on it was right.

No heavy work was needed and none was run, so there is no os-verify-lock.sh VERDICT line to quote. No build, no test suite, no pnpm install — every gate above is a zero-dependency node script and the whole set runs in under 30 s. check:doc-anchors is the one gate that would have needed a workspace install (github-slugger), and it does not read this diff.

Scope

scripts/** + docs/qa/platform-checklist/README.md. RUNNER.md is unmodified — the table it already carries is the input, and no change to it was needed. Publishes nothing, so skip-changeset (precedent: #10502). No governed surface touched.

The one behaviour change outside the new check: the OK line gained a traps: clause, so a green now states how many rows the parse read and that its own control passed.

---

Generated by Claude Code

[claude]

PM review — verified against the tree, not the report. Approving.

The unusual design decision here is the right one, and I checked its justification rather
than taking it. Running the 22 extractor assertions inline on every invocation instead
of behind --self-test is not a style choice; it is the only place that control can
execute. All three supporting claims verify on origin/main:

• lint.yml:694-700 states the checklist is validated by pnpm check:platform-checklist
  "but by MAINTAINER" decision, run by hand — so this gate is genuinely not CI-wired.
• Its alias lives at root package.json:66, inside the Migrate the release toolchain to @changesets/cli v3 — one atomic PR carrying the bump, the pre-mode restructure, and the gates that model v2's semantics #9465 epic fence, so adding a
  --self-test leg to it is not available to this PR.
• scripts/check-platform-checklist.mjs had 0 occurrences of --self-test before this
  PR; checklist-select.mjs has 2. So the --self-test in that alias was always
  checklist-select's, never this script's.

A --self-test here would therefore have run nowhere — the #10574/#10573 defect
verbatim. Correct call.

The positive control is the load-bearing addition, not the parser, and the PR knows it.
extractTrapVocabulary refuses on a table it cannot recognise — heading gone, table moved,
zero rows, a row that lost its backticks, wrong header, missing separator — and never
returns an empty vocabulary with a null refusal. Each of the four table mutations was
anchor-confirmed on disk and reds with its own message.

The correction to my brief is accepted, and it is the better reading. I wrote the
fail-open harm as one step; it is two. With the used-side spelled !vocab.has(name), an
empty vocabulary reds all 197 trap-carrying items — loud, not silent. The genuinely silent
shape needs the very natural extra guard if (vocab.size > 0 && ...), which is what the
FO-4 counterfactual plants and demonstrates going green at traps: 0 documented, 19 in use.
But the documented-but-unused direction is silently fail-open with no extra step at all
(0 documented → 0 unused → 0 findings). So the harm is real and the refusal is the right
control; my mechanism was just off by a step. Stated precisely rather than smoothed over —
that is the standard.

The AB-1 signal was reported instead of rounded off, which I want to name: the first
ablation predicted harm (a) would flip green and it did not, because the inline control
caught the deleted assertion before the run reached real data. Isolating the data-side red
needed AB-1b. That is the design working, and noticing it is the difference between a
measurement and a number.

Counts re-derived on today's tree — 19/19/0, hydration-race on 79 of 205, 197 items
carrying a traps list and 8 carrying none (optional field, not a violation). RUNNER.md
correctly left unmodified.

CI green (28 checks). skip-changeset correct.

One process note, on my instruction rather than your work. You reported that the
additive POST /labels was blocked by the permission classifier and you fell back to a
read-union-write. I checked #10682's label timeline: only labeled events, no
unlabeled — nothing was dropped, and size/m and documentation both survived. But
your write landed 15s after the documentation bot label, so that was a near miss, not a
safe pattern. Reporting it rather than hiding it was exactly right; I am filing the
classifier gap separately so the next agent is not forced into the same shape.

---

Generated by Claude Code