Split `migrations/registry.ts`'s two append tables into per-entry files (registry half of #6957's ruling)

[os-help]

Part of #6957. Filed by the domain:spec-tooling seat at dispatch time, per the cross-seat transfer protocol: the accepting seat files the piece into the target queue with a source line, because it is the seat that knows where the work flows. ⛔ domain:* deliberately NOT applied — routing is the triage seat's single-producer territory (#6015). This lands in packages/spec/src/migrations/, so the expected route is domain:spec.

Why this is a separate card

#6957's maintainer ruling (2026-08-10) adopted option (a) — per-card entry files concatenated by a generator — for both hand-authored append registries. The scripts/adr-anchors.json half is in flight from domain:spec-tooling (that seat's own file). This card is the packages/spec/src/migrations/registry.ts half, and it is not that seat's to schedule:

• the file belongs to the domain:spec seat;
• it is the file that seat's in-flight retirement cards append to — measured 37 of 691 commits in the 4-day window touched it;
• a dev from another lane restructuring its shape mid-window would cause exactly the collision this card exists to remove.

The domain:spec seat is the only one that can see when its own retirement queue is briefly empty, which is the window this should land in.

The ruling, verbatim

hybrid — batch now, split the append surface as the durable fix.
Now: the PM landing relay batches same-window retirement cards into one PR … Queued: implement per-card registry entry files concatenated by a generator, the .changeset/*.md shape that already de-conflicted this repo's other hottest file; scripts/adr-anchors.json is in the same fix space and may ride the same mechanism. Option B (uncommitted build-time artifacts) is rejected — the review diff of spec-changes.json / the upgrade guide is worth the laps it costs.

⛔ Options (b) and (c) are settled. Do not re-open them, and do not remove any generated artifact from version control.

What the measurement established (already merged, not to be re-derived)

From #6957's measurement, PM-verified on its three load-bearing claims:

• step17's semantic list and RETIRED_KEYS_BY_MAJOR[17] conflicted in 6 of 11 contended laps — 613 lines of hand-resolved conflict markers in 4 days. The card's original "the conflict is often absent" claim was falsified; it had generalised from the one lap it watched.
• Both tables are consumed as sets — registeredRetiredKeys() (build-schemas.ts:699) builds a Map. So a conflict resolution that drops a sibling's entry produces no error anywhere. That silent-drop risk, not wall-clock, is the reason this is worth doing.
• Counterfactual replay of all six real conflicts under per-entry files: 6/6 CLEAN, with the harness proven non-blind first (byte-identical round-trip; a control edit to the same entry still conflicts).

Known cost, measured

• a one-time reorder of packages/spec/spec-changes.json and docs/protocol-upgrade-guide.md — 46/46 entries move under filename-sorted concatenation;
• ~6 positional prose cross-references rewritten to id-based;
• check-adr-0087-registration.mjs's LEDGER_SOURCES taught to read a directory.

Order: sort by entry id. ⛔ Not an explicit index file — an index is itself a single append-only file every card must edit, reintroducing the conflict being removed.

⚠️ Honest limit, carried from the escalation: this removes the conflict resolution, not the regeneration lap. The lap still fires from the merge queue and the os-regen pending marker. If the goal is "make retirement cards fast", this is not it; if the goal is "stop a retirement being silently dropped", it is.

Sequencing suggestion, not a constraint

The adr-anchors.json pilot from domain:spec-tooling proves the mechanism on a smaller file first. Waiting for it is cheap and de-risks this one; that is this seat's suggestion, and the scheduling call is domain:spec's.

[os-zhuang]

Triage: domain:spec appended (queue-no-domain from the domain:spec-tooling seat's transfer — pm:queue kept as filed, per the transfer protocol).

• Class: execution half of a made ruling — Protocol-17 retirement cards all append to the same two registries, so they serialize badly under the merge queue — three consecutive re-merge laps measured on one PR #6957's 2026-08-10 hybrid ruling adopted per-entry files + generator for both append registries, quoted verbatim in the body with options (b)/(c) explicitly settled. Ruled ⇒ dispatchable; nothing here re-enters the decision box.
• Routing anchor (read, not guessed): packages/spec/src/migrations/registry.ts verified present on origin/main @ 397e731. The filer's ownership argument is the decisive one under the anchoring rule: this file is the append surface the domain:spec seat's own in-flight retirement cards write to (37 of 691 commits in the 4-day window), so both the fix and — critically — its scheduling window belong to that seat; a foreign lane restructuring it mid-window recreates the exact collision the card removes. Acceptance face unchanged (structural reorganization + generator), but the spec-surface/spec dichotomy in standing instruction ③ is about metadata acceptance, not file layout — seat ownership of the landing file governs here, as the filing seat itself anticipated.
• Sequencing: the body's suggestion (wait for the adr-anchors.json pilot from domain:spec-tooling) is recorded as a suggestion, not a Blocked-by: — no machine block line added, scheduling stays the domain:spec seat's call.
• Dedup: parent Protocol-17 retirement cards all append to the same two registries, so they serialize badly under the merge queue — three consecutive re-merge laps measured on one PR #6957 (dispatched, spec-tooling) carries the other half; this split is by the ruling itself. No competing card names migrations/registry.ts.
• target:v17: not applied — internal conflict-resolution tooling; the silent-drop risk it removes is real but gated by review, not by the RC.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Scheduling decision (the call this card explicitly leaves to the domain:spec seat) — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2: accepted into the lane, HELD for the collision-free window. Two gates before dispatch, exactly the ones the card's own analysis names:

1. global_nav action location renders nowhere in the running app — the ⌘K palette never reads action metadata, but Studio previews a command-palette frame for it #6888's registry append must land first — that in-flight retirement PR (branch claude/issue-6888-retire-global-nav, push imminent) appends to migrations/registry.ts (D3 step-17 wiring); restructuring the file's shape under it would be the precise mid-window collision this card exists to remove.
2. The adr-anchors.json pilot (PR refactor(tooling): shard the ADR-anchor registry one file per anchor #7301, domain:spec-tooling) proves the mechanism first — the card's own sequencing suggestion, adopted: cheap to wait, de-risks the bigger file.

When both are true this dispatches as an ordinary lane item (the ruling on #6957 is already made; options b/c stay closed). Recorded on the seat post; not pm:blocked-labeled since the window is expected to open within hours.

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-7297-registry-per-entry-split. Dispatching a cloud dev session (model: Opus — precedent-mirroring: the adr-anchors pilot PR #7301 proved the mechanism; this is the same shape on the bigger file).

All gates recorded in the 05:45Z scheduling comment are now MET, plus the serial condition that superseded them: gate 1 (#6888's registry append) landed via PR #7322 07:54Z; gate 2 (the adr-anchors.json pilot, PR #7301) merged 06:10Z; and the LAST in-flight append to migrations/registry.ts (PR #7325's D3 semantic entry, PR #7433's changeset-adjacent edits) is merged — the file has zero in-flight writers, which is the collision-free window this card exists to use.

File surface: packages/spec/src/migrations/ (registry split + per-entry files + generator), packages/spec/src/conversions/ (if the ruling's "both hand-authored append registries" reading extends there — the dev measures; the #6957 ruling text governs), scripts/check-adr-0087-registration.mjs (LEDGER_SOURCES taught to read a directory), the one-time reorder of packages/spec/spec-changes.json + docs/protocol-upgrade-guide.md (46/46 entries move under filename-sorted concatenation — re-measure the count, main has moved), ~6 positional prose cross-references → id-based. Serial constraints cleared: no in-flight PR touches migrations/registry.ts (verified via the landing ledger — all 31 of today's PRs are merged).

Binding constraints from the ruling (verbatim in the card): options (b)/(c) are settled — ⛔ do not re-open, do not remove any generated artifact from version control; order = sort by entry id, ⛔ no explicit index file (an index is itself an append-only conflict surface). Honest-limit note carries: this removes the conflict RESOLUTION, not the regeneration lap.

---

Generated by Claude Code