docs(spec): re-anchor the dead tracker citations in migrations/entries to the commits that decided them (stage 10) (#20750)

Part of #20234

Clause-②: no

Stage 10 of the dead-citation sweep: the migration registry's
hand-written entries. Every tracker number in
`packages/spec/src/migrations/entries/**` that no longer exists on the
board now cites the commit that decided it, in ruling C+D form C (ruling
`5749154545` on #19123). Where the number alone carried the meaning, the
line now says what was decided. That is 131 sites over 21 numbers. All
of them are comments; the entries' string literals carry no dead number.
`migrations/registry.ts` moves only by `gen:migration-registry`. No
entry id, literal, order, `conversionIds` or code token moves, and no
live citation is removed.

## Boundary

- **In:** all of `entries/**`. The gate's census reads 117 sites there,
under the claim's ~120 slicing threshold, so there is no slice. My raw
walk finds 14 more comment sites that the census does not count (see
*Census* below), which gives 131 in total. They are the same dead card
on the line after a counted site, plus one README line, so they are
rewritten with it.
- **Regenerated only:** `migrations/registry.ts`, 128 lines.
`spec-changes.json` and `docs/protocol-upgrade-guide.md` do not move,
because entry comments are never projected into them. Both `check:`
scripts pass with no regeneration.
- **Out, per the claim:** `registry.ts`'s hand-written parts. They still
hold 13 dead sites, listed under Acceptance notes. The six
`18.*-unit-in-key.ts` entries that PR #20706 edits carry no dead site,
and I did not touch them. I did not touch `conversions/` or other lanes'
sites.

## The anchors (one per number, reused from earlier stages where they
anchored the same number)

| number | sites | anchor | what the rewritten line says it decided |
|---|---|---|---|
| #13135 | 26 (13 are `re-charter #13135`) | commit 9e0ba21 | retires
the paper metadata-customization protocol; re-charter of #12057, which
stays |
| #8495 | 23 | commit 4bfe1a5 (PR #8666 kept) | the precedent: the
first 17.x-line narrowing registered under protocol 18 (its own second
commit says so) |
| #8715 | 16 | commit 2c86fe3 | the ApiKeySchema retirement; its
message names the "route 3" kit (no carrier key, no tombstone, no D2) |
| #14691 | 11 | commit b3a63d3 | retires the ten inert
`RestServerConfig` keys |
| #10724 | 11 | commit be21955 | retires the nine dead `contributes`
members |
| #14369 | 10 | commit a3d5724 | the liveness census that recorded the
15 `dead` rows |
| #10485 | 6 | commit 35ad101 | retires the `themes` carrier and
`ThemeSchema` |
| #11846 | 5 | commit 0c2334f | retires preview mode; its own text
carries the ruling record (#12428 kept) |
| #14676 | 5 | commit 13c48c2 | retires `connector.errorMapping` |
| #11332 | 3 | commit dce5cd4 | retires the manifest's three dead
containers |
| #6361 | 2 | commit 90bbf25 | retires the notification-list `cursor`
on both halves |
| #10627 | 2 | commit be21955 | that commit records the controlled
monorepo census |
| #14365 | 2 | commit f60ab90 | the open `z.partialRecord` proposal
that commit's changeset recorded; the retirement leaves no record to
reshape |
| #14526 | 2 | commit db16b94 | the landing of the client envelope
convergence (anchor block, and the README's measured case) |
| #6363 | 1 | commit 17d0954 | "ruled jointly with the `unreadCount`
fix" |
| #6239 | 1 | commit f549a0d | the ViewProtocol retirement sweep |
| #10726 | 1 | commit bc56e18 | retires `contributes.routes` (Option
B) |
| #10812 | 1 | commit be21955 | "the cloud census", whose 2026-08-24
reading @5b5925a that commit's message records |
| #9041 | 1 | commit d491625 | the url-branch refinement (#9147, live,
stays) |
| #14996 | 1 | commit db16b94 | the ADR-0087 registration, which
landed in the same squash (its body: "Registration requested on #14996")
|
| #14312 | 1 | commit e944fdb | the `oauth.*` binding, which left
`applications.delete` out as a behaviour change (PR #15445 kept) |

Two lines change without a number, so the sentence still reads:
`patterns`' follow-on line and the `oauth` anchor block's continuation
line. In total 133 lines are removed and 133 added in 86 files, and
every file is balanced.

## Verification record (final head `1ee5841c09`; base `fbec216e2d`)

**Census** (the gate's own `check-issue-citations.mjs --census --json`,
board enumerated, 186 pages):

| subtree | base (00:21Z, frontier #20740) | head (01:18Z, frontier
#20743) |
|---|---|---|
| `entries/retired-keys` | 73 | 0 |
| `entries/retired-defs` | 40 | 0 |
| `entries/semantic` | 4 | 0 |
| `registry.ts`, generated regions | 114 | 0 |
| `registry.ts`, hand-written parts | 2 | 2 |
| `chain.ts`, `types.ts`, `index.ts`, `spec-changes.ts`, tests | 0 | 0 |
| **`migrations/`** | **233** | **2** |
| `packages/spec/src` | 235 | 4 |

- **Site-set difference:** 254 sites are only at base. 231 are this
diff's (117 plus 114 copies). The other 23 are `plugin-audit`'s, from
`main`'s #20737. 0 sites are only at head.
- **Kind** (every census site is a comment): a TypeScript 6.0.3 walker
classes all 131 entry sites as comments. It also finds 13 dead string
sites, all in `registry.ts`'s hand-written rationale (see Acceptance
notes).
- **Probe:** REST `issues/N` without following redirects, over all 302
distinct in-repo numbers of 100 or more in `migrations/`. 277 answer 200
and 25 answer 404. Controls were read at start, every 50 and end: lit
#20234 200 (8/8), dead #8710 404 (8/8).
- **Blind spots:** the census does not count 14 of the 131 entry sites.
- 13 are `re-charter #13135`, because `NON_CITATION_HEADS` reads
`re-charter #N` as an ordinal.
- 1 is in `entries/README.md`, which is outside the gate's
`packages/**/src/**/*.ts` surface.
- **Numbers:** no tracker number is added. The only numbers on added
lines are the live ones kept from the same lines: #8666, #12057, #8586,
#12428, #9147 and #15445. The diff-scoped gate judges them: "every
citation this change adds resolves".

**Residue** (scratch walker over the TypeScript parser, per file, base
vs head, 86 `.ts` files):
- The file with every comment range cut out, everything else byte for
byte, is IDENTICAL.
- The leaf-token stream is IDENTICAL: 38,417 tokens, aggregate
`67c1f6db944e93ed`.
- **Controls** mutate the head text in memory only, 259 of 259 as
expected:
  - Expected identical: a comment insertion in every file.
- Expected to differ: a string-literal edit, a template-literal edit, a
regex-literal edit (where the file has one) and an appended declaration.

**Regeneration** (`gen:migration-registry`):
- `check:migration-registry` exits 1 before and 0 after.
- The registry diff is 128 lines out and 128 in. As (old, new) pairs
they equal the entry diff's pairs, re-indented by four spaces.
- 0 changed lines fall outside the generated regions.
- 5 entry pairs are deliberately not carried: the README line, and the
semantic "Anchors" header lines, which sit above a blank line and so are
not in the carried comment run.
- `check:spec-changes` and `check:upgrade-guide` exit 0 with no
regeneration.

**Build and tests** (under `os-verify-lock`):
- Build: `turbo run build` over `./packages/*` and `./packages/*/*`, 71
of 71, at `845e90fea4` and again at `1ee5841c09`.
- `check:generated`: all 15 artifacts up to date, at both heads.
- spec `local` project: 576 files, 16,991 passed and 1 todo, at both
heads.
- spec `repo` project: 41 of its 45 files, 666 passed, at both heads.
- spec `typecheck`: exit 0; 53 files / 251 errors / 138 pinned
signatures held.

**Gates:** `dispatch-gates --commands` derives 82 gates, and the
derivation is identical before and after the second merge. At
`1ee5841c09` all 82 exit 0. `--ran` reconciles: 82 derived, 82 run, 0
NOT-MEASURED, a derived zero.

**Lint** (a proven narrowing):
- `eslint --no-inline-config --format json` over the 86 touched `.ts`
files: 86 files, 0 errors, 0 warnings.
- `isPathIgnored` is false for all 86.
- `eslint.config.mjs:327-328` states that type-aware linting is never
enabled, so a comment edit cannot move an untouched file's verdict.

**Changeset:** `patch`.
- In the built `dist`, the new wording (for example "the precedent of
commit 4bfe1a5, PR #8666") appears in `dist/migrations/index.js` and
`.mjs`, and the old wording appears in 0 files.
- Control: an unchanged phrase appears in the same 2 files.
- So the published `@objectstack/spec/migrations` entry carries these
comments.

**Merges:** `origin/main` was merged twice through
`scripts/pm/os-regen-merge.sh`. Neither merge left a regeneration to
commit.
- Since then, `main` has advanced to `97005aed04`, and none of those
commits touches `packages/spec`.
- Driver-free `merge-tree` probes (from a bare `--shared` scratch clone
with no `merge.*` config) exit 0 against that `main` and against PR
#20706's head `d8bac3877d`.

## Acceptance notes

- **The next stage for this card: 13 dead sites left in `registry.ts`'s
hand-written parts.** They are outside this claim, which says
`registry.ts` is regenerated only.
  - **Comments (form C), 2:**
- `:5940` #8495, the step-18 doc comment on the persistence placeholder
refusal.
    - `:22819` #6239, the `RETIRED_DEFS_BY_MAJOR[17]` doc comment.
  - **Author-shown rationale strings (form D), 11:**
- Step 17's `:344` #6345. It projects into
`docs/protocol-upgrade-guide.md:68`, so that stage regenerates the
guide.
- Step 18's fragments: `:5121` #14676, `:5455` #12868, `:5526` #10329,
`:5544` #8495, `:5555` #13135, `:5742` #10724, `:5745` #10627, `:5752`
#10726, `:5799` #10485, `:5816` #10926. These are not projected into
either artifact yet.
- **Census blind spots, measured here and not filed** (a coverage
boundary, not one of the three filing classes; new gates default to no):
- `NON_CITATION_HEADS` skips `re-charter #N` even where N is a tracker
card.
  - `.md` files under `packages/**/src` are outside the surface.
- **NOT MEASURED locally, left to CI:**
- `scripts/build-schemas-check-mode.test.ts` hit the foreground cap
alone (exit 124 after 560 s, no output). It parses `registry.ts`'s
source; the residue check above shows that source's code and string
tokens are unchanged.
- The other three heavy `repo`-project files (`def-key-collisions`,
`publish-smoke-boot-failure`, `publish-smoke-port-collision`) were not
run, as in stages 8 and 9.
- **Hypothesis 6's baseline half is falsified by construction.**
`scripts/doc-authoring-prose-id.baseline.json` has no `packages/spec`
row, because its leg excludes `packages/spec`. `check:doc-authoring`
reads strings only, so a comment-only diff cannot move it. It read 808
sites across 229 files at `845e90fea4` and 794 across 227 at
`1ee5841c09`. The difference is `main`'s own re-anchor commits; this
diff touches no row.

---
_Generated by [Claude
Code](https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/spec-migration-entries-provenance-anchors.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+The ADR-0087 migration entries cite the commit that decided each retirement instead of a tracker number that no longer resolves
+
+Clause-②: no
+
+The source comments of the migration registry's retired-key, retired-def and semantic
+entries named GitHub issues that no longer exist, so a reader could not tell a rule kept
+on purpose from one nobody could explain. Each of those comments now names the commit
+that made the decision and, where the number alone carried the meaning, says what was
+decided. The compiled `@objectstack/spec/migrations` entry carries these comments, which
+is why this is a release note at all. Comment text only: no entry id, retired key or def,
+prescription, projected upgrade-guide text, schema, export or runtime behaviour changes.

packages/spec/src/migrations/entries/README.md

@@ -82,7 +82,7 @@ into the registry; the run of `//` comments immediately above `export const entr
   sentence once here and once there. This tree's one code/prose separator masks
   **comments** and leaves **string literals** intact on purpose, so to every scan built
   on it a quoted example is code — which is how prose in `packages/spec` turns
-  **another package's** test red. Measured on #14526: the new entry named four retired
+  **another package's** test red. Measured while landing commit db16b9424: the new entry named four retired
   call sites in their call spelling — the method with its opening parenthesis —
   `packages/client/src/envelope-caller-census.test.ts` counted 46 against the 28 it
   pins (nine mentions, each counted twice) and `Test Core` went red; respelling them

packages/spec/src/migrations/entries/retired-defs/17.api__CreateViewRequest.ts

@@ -1,4 +1,4 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #6239 — api/protocol.zod.ts view-management operations
+// Commit f549a0d4a — api/protocol.zod.ts view-management operations
 export const entry = 'api/CreateViewRequest';

packages/spec/src/migrations/entries/retired-defs/18.api__CrudEndpointPattern.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #14691 — `api/CrudEndpointPattern` (the `{ method, path, summary, description }`
+// Commit b3a63d32c — `api/CrudEndpointPattern` (the `{ method, path, summary, description }`
 // value shape of `crud.patterns`) leaves with its carrier key: its ONLY consumer
 // was `CrudEndpointsConfigSchema.patterns`, tombstoned in the same change under
 // ADR-0049 enforce-or-remove, and an exported value schema with no consumer

packages/spec/src/migrations/entries/retired-defs/18.api__MetadataEffectiveResponse.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #13135 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
-// #12057: retirement adopted, re-scope rejected; re-charter #13135 executes
+// Commit 9e0ba21a1 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
+// #12057: retirement adopted, re-scope rejected; re-chartered, that commit executes
 // the widened surface). Part of the whole-module removal of
 // `kernel/metadata-customization.zod.ts` — the paper three-layer
 // customization protocol ADR-0126 §6 wall 4 supersedes on the record
@@ -21,6 +21,6 @@
 // boundary where `migrate meta` users look. No carrier key survives for
 // these defs and no authored document embedded them, so no tombstone and no
 // D2 conversion — this table plus the D3 semantic entry
-// `metadata-customization-protocol-retired` ARE the declaration (the #8715
+// `metadata-customization-protocol-retired` ARE the declaration (commit 2c86fe3ea's
 // route-3 shape).
 export const entry = 'api/MetadataEffectiveResponse';

packages/spec/src/migrations/entries/retired-defs/18.api__MetadataOverlayResponse.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #13135 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
-// #12057: retirement adopted, re-scope rejected; re-charter #13135 executes
+// Commit 9e0ba21a1 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
+// #12057: retirement adopted, re-scope rejected; re-chartered, that commit executes
 // the widened surface). Part of the whole-module removal of
 // `kernel/metadata-customization.zod.ts` — the paper three-layer
 // customization protocol ADR-0126 §6 wall 4 supersedes on the record
@@ -20,6 +20,6 @@
 // boundary where `migrate meta` users look. No carrier key survives for
 // these defs and no authored document embedded them, so no tombstone and no
 // D2 conversion — this table plus the D3 semantic entry
-// `metadata-customization-protocol-retired` ARE the declaration (the #8715
+// `metadata-customization-protocol-retired` ARE the declaration (commit 2c86fe3ea's
 // route-3 shape).
 export const entry = 'api/MetadataOverlayResponse';

packages/spec/src/migrations/entries/retired-defs/18.api__MetadataOverlaySaveRequest.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #13135 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
-// #12057: retirement adopted, re-scope rejected; re-charter #13135 executes
+// Commit 9e0ba21a1 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-29 on
+// #12057: retirement adopted, re-scope rejected; re-chartered, that commit executes
 // the widened surface). Part of the whole-module removal of
 // `kernel/metadata-customization.zod.ts` — the paper three-layer
 // customization protocol ADR-0126 §6 wall 4 supersedes on the record
@@ -19,6 +19,6 @@
 // boundary where `migrate meta` users look. No carrier key survives for
 // these defs and no authored document embedded them, so no tombstone and no
 // D2 conversion — this table plus the D3 semantic entry
-// `metadata-customization-protocol-retired` ARE the declaration (the #8715
+// `metadata-customization-protocol-retired` ARE the declaration (commit 2c86fe3ea's
 // route-3 shape).
 export const entry = 'api/MetadataOverlaySaveRequest';

packages/spec/src/migrations/entries/retired-defs/18.api__PackageRollbackResponse.ts

@@ -12,13 +12,13 @@
 // §5.2): only its own unit test and the #11925 negative guard, both updated
 // in the retiring PR. No carrier key, no authored document, so no tombstone
 // and no D2 conversion — this table plus the D3 semantic entry
-// `package-rollback-response-retired` ARE the declaration (the #8715 route-3
+// `package-rollback-response-retired` ARE the declaration (commit 2c86fe3ea's route-3
 // shape). The live route's true contract is
 // `RollbackToPackageCommitResponseSchema` (`api/package-lifecycle.zod.ts`),
 // authored in the same PR AFTER this retirement per the ruling's sequencing.
 //
 // Registered under 18, not 17: v17.0.0 was cut before this landed, so the
 // removal ships on the 17.x line (launch-window convention: accept-set
 // narrowings ride minor releases) and the prescription lives at the major
-// boundary where `migrate meta` users look (the #8586 / #8715 precedent).
+// boundary where `migrate meta` users look (the #8586 / commit 2c86fe3ea precedent).
 export const entry = 'api/PackageRollbackResponse';

packages/spec/src/migrations/entries/retired-defs/18.identity__ApiKey.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #8715 — identity/identity.zod.ts `ApiKeySchema`, retired whole (ADR-0049
+// Commit 2c86fe3ea — identity/identity.zod.ts `ApiKeySchema`, retired whole (ADR-0049
 // enforce-or-remove; maintainer ruling 2026-08-15, disposition B: delete).
 // The schema documented better-auth's `apiKey` PLUGIN shape — a plugin this
 // platform does not load: `start`, `lastRefetchAt`, `enabled` (the real

packages/spec/src/migrations/entries/retired-defs/18.integration__ConnectorErrorCategory.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
-// #14676 — `integration/ConnectorErrorCategory` (the 8-value connector-side
+// Commit 13c48c2a5 — `integration/ConnectorErrorCategory` (the 8-value connector-side
 // error category enum) left with its two carriers: `ErrorMappingRule.targetCategory`
 // and `ErrorMappingConfig.defaultCategory`, both retired in this same major
 // (`RETIRED_DEFS_BY_MAJOR[18]`). Measured before removal: outside the declaring