fix(tooling): error-status gate names the real cause when a code leaves the ungraded set (#9563)

[os-steve]

Fixes #9563

check-error-status-conformance.mjs's nowPinnedMessage() computed the
ratchet-down trigger as a subtraction (baselined \ result.unpinned) but
hard-coded a single cause for it: "a producer now declares its status."
result.unpinned drops a code for either of two unrelated reasons —
reconcile()'s own branch at documented.has(code) shows why:

if (runtime.size > 0) {
  reconciledCodes++;
  ...
} else if (documented.has(code)) {
  unpinned.push(code);
}

A baselined code leaves unpinned because a producer appeared
(runtime.size > 0), or because its doc entry was removed
(!documented.has(code), with no producer either). Only the first cause had
a sentence.

Before — the false diagnosis, reproduced

Per the issue's counterfactual: temporarily deleted the ## Batch Operation Errors section from content/docs/api/error-catalog.mdx (its three entries
— BATCH_PARTIAL_FAILURE, BATCH_COMPLETE_FAILURE, TRANSACTION_FAILED —
are all in scripts/error-status-unpinned-baseline.json and none has a real
producer) and ran the gate on main, before this fix:

$ node scripts/check-error-status-conformance.mjs
  unpinned: 34 documented code(s) with no derivable producer (baselined: 37).

  x BATCH_COMPLETE_FAILURE: baselined as unpinned, but a producer now declares its status — ratchet the baseline down with --update.
  x BATCH_PARTIAL_FAILURE: baselined as unpinned, but a producer now declares its status — ratchet the baseline down with --update.
  x TRANSACTION_FAILED: baselined as unpinned, but a producer now declares its status — ratchet the baseline down with --update.

x check:error-status-conformance — 3 finding(s).

No producer declares a status for any of the three (verified by grep across
packages/, examples/, apps/ — the only hits outside the enum
declaration are two spec tests). The message is simply false on this route.
Restored the doc file (git restore --source=HEAD) before touching any code.

After — the same counterfactual, this fix applied

$ node scripts/check-error-status-conformance.mjs
  unpinned: 34 documented code(s) with no derivable producer (baselined: 37).

  x BATCH_COMPLETE_FAILURE: baselined as unpinned, but its doc entry was removed, so nothing claims a status for it any more — ratchet the baseline down with --update.
  x BATCH_PARTIAL_FAILURE: baselined as unpinned, but its doc entry was removed, so nothing claims a status for it any more — ratchet the baseline down with --update.
  x TRANSACTION_FAILED: baselined as unpinned, but its doc entry was removed, so nothing claims a status for it any more — ratchet the baseline down with --update.

x check:error-status-conformance — 3 finding(s).

Truthful now, and --update is still the correct remedy either way — the
ratchet direction and remedy are unchanged, only the stated cause. Doc file
restored to a clean tree again afterward; git status --porcelain is empty
on main HEAD for that path throughout.

What changed (scripts/ only)

• nowPinnedMessage() -> split into nowPinnedProducerMessage() and
  nowPinnedDocRemovedMessage(), each naming its real cause.
• New pure nowPinned({ baselined, unpinned, vocabulary, documented }),
  placed beside reconcile(): derives { code, reason }[] at the same
  documented.has(code) juncture reconcile() branches on, so the message
  selection isn't guessing — it reuses the same fact reconcile() already
  computed.
• runFixture() now also returns documented (the parsed doc-side set), so
  fixture-level self-tests can call nowPinned() directly.
• No baseline semantics change, no catalog change, no grading-model change —
  diagnosis text + self-tests only.

Self-test — 2 new cases per branch (36 -> 40)

• 21 / 21b — producer branch: a baselined code that gains a producer
  while remaining documented is named reason: 'producer', and
  nowPinnedProducerMessage() names a producer, not a doc removal.
• 22 / 22b — doc-removed branch: the [finding] error-catalog.mdx publishes some error statuses only in prose or a JSON example, so check:error-status-conformance grades them as nothing — three entries publish no status it can read at all #9266 / check:error-status-conformance's nowPinnedMessage misdiagnoses the retirement route — it says "a producer now declares its status" when the real cause is the catalog entry being removed #9563 counterfactual
  reduced to a fixture (no producer, doc entry gone) is named
  reason: 'doc-removed', and nowPinnedDocRemovedMessage() names a removed
  doc entry, not a producer.
• 11b updated to assert the ratchet-authority convention on both
  ratchet-down messages (neither carries the MAINTAINER-ONLY marker).

check-error-status-conformance --self-test: 40 cases pass — …

Reverse verification

Committed the fix, then temporarily forced nowPinned()'s branch to always
return reason: 'producer' (reverting only the causal split, keeping the new
self-test cases) and re-ran --self-test. Predicted: case 22 (doc-removed
branch) goes red, everything else stays green. Observed exactly that:

  x self-test: 22 nowPinned names the doc-removed branch when nothing documents the code any more — [{"code":"TRANSACTION_FAILED","reason":"producer"}]

x check-error-status-conformance --self-test: 1/40 case(s) failed.

Restored the fix from the branch (git checkout claude/issue-9563-gate-diagnosis-split -- scripts/check-error-status-conformance.mjs); re-ran --self-test, back to 40/40 green.

Gates

• node scripts/pm/dispatch-gates.mjs scripts/check-error-status-conformance.mjs
  -> 1 matched family: pnpm check:error-status-conformance (lint.yml).
• pnpm check:error-status-conformance (self-test + real run) — green, at
  head f173b99db:

  check-error-status-conformance --self-test: 40 cases pass — …
  every derivable runtime status is documented, and every documented status is reachable.
  

• pnpm check:nul-bytes (self-test + real run, under the shared
  /tmp/os-heavy-verify.lock) — green: check-nul-bytes: OK (scanned 6157 text file(s) … no raw ASCII control bytes).
• No changeset: git log --oneline -- scripts/check-error-status-conformance.mjs
  shows the file's last two substantive commits (fix(scripts): six source-scanning gates share one string-aware comment masker #9445, fix(gates): reconcile the HTTP status the docs publish for ledger error codes, and report an entry heading the parser cannot read #9268) shipped
  without one — root-level scripts/ tooling isn't part of any package in
  .changeset/config.json's fixed list. Followed the house convention.

Serial constraint (#9266)

#9266 (needs-user-decision, same file's subject matter) is still open with
no linked PR as of this branch's base — no re-run of the observation was
needed. No content/docs/releases/ edits, no baseline rewrite, no catalog
edit landed by this PR.

---

Generated by Claude Code