ci(lint): scan instruction surfaces for stale required-context names, budgeted for in-flight renames

[claude]

Fixes#9491

What this adds

scripts/check-required-contexts.mjs already pins the workflow name: literals that branch protection matches check-runs by. This PR extends the same file to the instruction surfaces — the files that state the required set as operative prose and tell a review seat which check-runs to confirm before flipping a PR ready / arming auto-merge / enqueuing. The card's measurement: replacing the job name in the review checklist with Nonexistent Job Name left the file's whole derived gate union green.

Two mechanisms, both registry-driven, both pure-function judged so the self-test exercises the real decision:

1. A retired-name ledger with per-file occurrence budgets (RETIRED_CONTEXT_NAMES). A rename PR must add a row recording the old literal, what replaced it, and the occurrence counts of the sites stale at that moment. Above budget is red (a dead name written fresh); at or below budget is green with a printed notice. Budgets only ratchet down. A row whose budgets are trimmed away becomes a standing ban on the dead name.
2. A naming requirement (mustName in INSTRUCTION_SURFACES). The two surfaces that state the required set — AGENTS.md and the pm-dispatch review checklist — must contain each blocking context literal: the current name, or a ledgered former name while its rename is in flight (renameInFlight: true).

The scan set was derived, not assumed: every *.md under AGENTS.md, CLAUDE.md, .claude/ and docs/ naming any registered context, case-sensitive, with a positive control run on the zero hits. That adds three scan-only surfaces beyond the card's two: .claude/skills/spec-property-retirement/SKILL.md, docs/launch-readiness.md, docs/releases-maintenance.md. Deliberately excluded: docs/adr/** and package CHANGELOGs (point-in-time records a rename must not retro-edit — scanning them would demand exactly that), plus this script and the workflows themselves (the ledger and the pinned half; old names live there as history by design).

The actual design problem: satisfiable at every intermediate state

A rename cannot land atomically: the Settings entry is maintainer-only, and the instruction files are split across seat tiers (.claude/skills/pm-dispatch/** is a maintainer-merge surface a dev seat may not edit — the reason the checklist half of the #9325 rename is its own card, #9420). Today's mainis that intermediate state: the registry says Lint & Repo Gates, the checklist still says ESLint, and the fix (PR #9490) is open. The card's literal direction 2 goes red at rest on today's main and blocks every PR in the repo, including the fix itself.

What I chose, and why:

• Occurrence budgets instead of a ban. Measured, not assumed: PR docs(pm-dispatch): review checklist names the renamed Lint & Repo Gates check run (#9420) #9490's own fixed line deliberately keeps one ESLint as a historical mention ("改名前的 PR 仍列旧名"). A ban would go red the moment the fix merges. The budget for the checklist is 1 across both states on purpose.
• renameInFlight grace on the naming requirement. During the window, the old literal satisfies mustName. Flipping it off later is self-ordering: the flip PR is red while any required-set surface still leans on the grace, so it cannot merge before the instruction fixes do — it never races them.
• The ledger cannot be forgotten. An un-ledgered registry rename is red on the rename PR itself (the naming guard's remedy names the ledger), and an under-enumerated staleSites is red per site with the real count. Both directions are pinned in the self-test.
• What it costs. (a) The scanned instruction files are now load-bearing for a gate; every red states its remedy, and every remedy is a same-PR dev-tier edit in scripts/. (b) The grace means a ledgered former name satisfies mustName until the flip — bounded by the budget half, and closed by the follow-up filed below. (c) A time-based grace was rejected outright: it turns red at rest on a date with no causing PR.

Direction 2 vs direction 1, tested rather than inherited

Recognition of a "required-context-shaped literal" in bilingual prose is not reliably buildable without markers in the instruction files — which are exactly the files split across seat tiers. So recognition here is lexicon-only (registry + ledger), which is blind to a never-existed name written fresh. That case is covered from the other side: mustName is direction 1 reduced to identifier presence — rewording-tolerant (any sentence shape passes as long as the literal appears; the name is a contract identifier, not prose) — and it reds when garbage replaces a real name, because the file then no longer contains the required literal under any recognised spelling. The self-test ablates the guard and shows the vacuous file passes without it: the guard is load-bearing, not decorative. Residuals recorded, not implied covered: paraphrase drift (e.g. "Lint & Type Check" in docs/launch-readiness.md) is invisible to both halves; after a shortening rename (new name a substring of the old), an old-literal mention would satisfy the new name's presence check by substring — the budget half still bounds staleness there.

Compatibility with the in-flight fix PR, in both merge orders

• This PR first: docs(pm-dispatch): review checklist names the renamed Lint & Repo Gates check run (#9420) #9490's merge-queue run sees current names present plus one budgeted historical ESLint — green, with the flip-to-false notice. The self-test pins that exact post-fix line shape green.
• docs(pm-dispatch): review checklist names the renamed Lint & Repo Gates check run (#9420) #9490 first: this PR's baseline assertions read the tree as it is (budget 1 covers occurrence counts of 1 or 0; a trimmed count prints the trim notice).
• Self-test fixtures are deliberately additive or fully synthetic — no fixture anchors into the checklist line docs(pm-dispatch): review checklist names the renamed Lint & Repo Gates check run (#9420) #9490 rewrites, because an anchored fixture would let this self-test eject that PR from the merge queue: the block-the-sitting failure in a second skin.

Verification

Self-test grew 55 → 85 assertions; both directions pinned for every new behaviour (stale-beyond-budget red / rewording-with-current-names green; vacuous red / guard-ablated green; window green / flip-early red; ledgered rename green / un-ledgered red; hygiene reds for malformed ledger shapes; #4690 never-read reds; wiring assertions that main() actually runs the surface scan).

Reverse verification by ablation at the shipped level, from a committed state, direction predicted before each leg (this gate runs from source — scripts/*.mjs, no dist build involved, so no dist preflight applies; the pre-change control was copied from origin/main into scripts/ so its own root resolution held):

leg	mutation	predicted	observed
A	append a fresh ESLint mention to the checklist (count 2, budget 1)	red, budget message	exit 1, names file + budget + replacement
B	the card's measurement: ESLint replaced with Nonexistent Job Name	red via naming guard	exit 1, "no longer names 'Lint & Repo Gates'"
C	leg B's tree judged by the pre-change script from origin/main	green (the measured hole)	exit 0

Mutations restored via git checkout against the committed branch; git status --porcelain and git diff HEAD both empty afterwards; self-test re-run green.

Derived gate union (node scripts/pm/dispatch-gates.mjs scripts/check-required-contexts.mjs → pnpm check:required-contexts, plus the any-edit check:nul-bytes), run after the final commit at HEAD 661d90c85: both green — 85 assertions, 9 contexts pinned, 5 surfaces scanned, 1 in-budget notice for the live intermediate state.

Tests/tooling only (scripts/ — not a published package): no changeset; skip-changeset label applied per this repo's mechanism.

Out of scope, follow-up filed

Post-transition ledger housekeeping (flip renameInFlight off once the checklist half lands; re-check the budget) is filed as its own card, blocked by #9420. #9420 and #9490 are not addressed here and remain open; #9421 and #9325 landed the workflow + registry half and are untouched.

Generated by Claude Code

---

Generated by Claude Code