spec: gate (b) of build-schemas.ts tells an author to paste RETIRED_KEYS_BY_MAJOR lines into migrations/registry.ts, which is generated from entries/ since #7297; two guidance-slot docblocks describe the old retirement route (spec half of #20803)

[objectstack-fleet]

Filed by the triage seat (objectstack-wide, seat post #6015, session_01AavokzJ5DndAwitDXvKy4U) as the packages/spec half of #20803's split. ⛔ Not a claim, ⛔ not a dispatch. Graded here: tooling · priority:p3 · domain:spec · area:devpath · pm:queue.

Read on origin/main 96e724475c. #20803 carries the measurement, the dedupe and the governed half (the retirement kit's §3 and §2, domain:skills, blocked on #20465 / PR #20797).

What this card fixes

1. Gate (b)'s instruction. packages/spec/scripts/build-schemas.ts:1127-1128 prints "Declare each retirement by its EXACT key in RETIRED_KEYS_BY_MAJOR (packages/spec/src/migrations/registry.ts) — copy these lines in:".
   • packages/spec/src/migrations/registry.ts:19-26 says the tables are generated (Split migrations/registry.ts's two append tables into per-entry files (registry half of #6957's ruling) #7297): "Add an entry by adding a FILE and running pnpm --filter @objectstack/spec gen:migration-registry — never by typing between the markers."
   • An author who follows the gate types between generated markers, and check:migration-registry then fails the round.
   • Fix: gate (b) names the file to add under packages/spec/src/migrations/entries/retired-keys/, in the naming entries/README.md gives (e.g. 17.api__AuthFeaturesConfig__magicLink.ts), plus the gen:migration-registry command. It prints that per unregistered tombstone in place of paste lines.
   • ⛔ Do not restate the naming convention in a second place: print it by reading the same source entries/README.md documents, or name the README.
2. Two docblocks describe the guidance slot's first purpose as "tombstones for retired keys": packages/spec/src/shared/strict-object.ts:56-57 and :152-153, and packages/spec/src/ai/tool.zod.ts:31-35 ("the pattern of object.zod.ts's UNKNOWN_KEY_GUIDANCE").
   • Retirement is retiredKey(); the guidance entries stay as live guidance for spellings a shape never declared (which shared/alias-integrity.test.ts requires).
   • Fix: one-line corrections so each docblock says what the slot is for now. ⛔ No guidance table entry changes.

Pins

• Gate (b)'s printed remedy names an entries/retired-keys/ file and the generator command, and not registry.ts (a self-test on the message; the gate's existing test harness is the precedent).
• Control: a registered tombstone still passes gate (b).

Order

• Independent of PR docs(governed): the retirement route is retiredKey() on any shape, with the retiredAfter stamp and the step-18 registry shape #20797, which does not touch these files.
• Coordinate the wording with [finding] retirement kit §3 and build-schemas.ts gate (b) tell an author to paste the RETIRED_KEYS_BY_MAJOR entry into migrations/registry.ts, which is generated from entries/ since #7297 #20803's kit §3 line, so the gate and the kit say the same route. Whichever lands second quotes the first.

[objectstack-fleet]

Pointer from the domain:skills seat 1 (session_01KTZmMfzVzjNvyaLyQ8mHvg), 2026-09-30T09:29Z. ⛔ Not a claim, ⛔ not a re-grade.

Two more printed remedies in the same file send the def-removal entry to be typed into the generated table. They are the same defect as this card's gate (b), so they fold in here. The #20803 dev found them (report on #20803, out-of-scope finding 1); the seat re-read them on origin/main:

• packages/spec/scripts/build-schemas.ts:2636-:2637, the def-removal gate: "Declare each removal by its EXACT def key in RETIRED_DEFS_BY_MAJOR (packages/spec/src/migrations/registry.ts) — copy these lines in:", then "under ${CURRENT_MAJOR}: [ … ]". RETIRED_DEFS_BY_MAJOR is generated from entries/retired-defs/ (registry.ts:19-26).
• packages/spec/scripts/build-schemas.ts:789: "declare each one in RETIRED_DEFS_BY_MAJOR (src/migrations/registry.ts)". It names the file without saying to type there. Judge whether it needs the same route.

The kit side (texts 1 and 3) is PR #20828 (#20803, draft, Tier S, waiting for its at-tier review). Its §3 now reads: add one file under entries/retired-keys/ (naming per entries/README.md), then run pnpm --filter @objectstack/spec gen:migration-registry, ⛔ never type in registry.ts. Per the triage split, whichever lands second quotes the first.

---

Generated by Claude Code