docs(governed): ADR-0087, AGENTS.md and the retirement playbook describe the D4 projections and the migration registry as main builds them

[objectstack-fleet]

Fixes #22667
Clause-②: no

Three governed texts still described packages/spec/spec-changes.json, the protocol upgrade guide and packages/spec/src/migrations/registry.ts as committed files with a regeneration lap. On main none of the three is committed. This PR restates 12 sites as main now builds them (11 at the first head, site 12 in patch round 1 below). No code, gate, script or published file changes.

Dispatched by /pm-dispatch skills seat 2 (PM session session_011u73oxZ5X95qrARPTeoU6v, claim 6106319581), executed in the same session. Tree read: origin/main a2e94c2a05. The diff is measured from that base, and every gate below ran on head bd6337b8b.

What main does (measured before editing)

Fact	Evidence on a2e94c2a05
Neither projection is committed	git ls-files packages/spec/spec-changes.json packages/spec/protocol-upgrade-guide.md content/docs/protocol-upgrade prints nothing. .gitignore lists all three paths.
Neither projection has a merge=os-regen route	grep -n os-regen .gitattributes shows 16 routed paths, and neither projection is one of them.
The guide's copy and route went at #22483	514bf3c101 (PR #22556) deletes docs/protocol-upgrade-guide.md merge=os-regen and reduces that file to a pointer stub.
spec-changes.json's copy and route went at #22485	46064dfa03 (PR #22638) deletes the file and packages/spec/spec-changes.json merge=os-regen.
registry.ts is generated and not committed	.gitignore lists it. registry.ts.template is tracked (ed1de8c2db, PR #22706) and holds STEP18_RATIONALE, const step18 and the earlier steps' conversionIds / rationale.
gen:migration-registry exists; check:migration-registry does not	packages/spec/package.json scripts. check-generated.ts files gen:migration-registry under UNGATED_GENERATORS, and its gate was retired with the committed copy.
The two projection checks still exist and never report stale	check:spec-changes / check:upgrade-guide run --check: they generate in memory, read nothing on disk, and exit 1 only when generation fails (lib/projection-cli.ts).

All five commits named above pass git merge-base --is-ancestor against HEAD with exit 0. A positive answer needs no control leg.

The 11 sites (location, then before and after)

#	Location (base line)	Before	After
1	ADR-0087 :3 Status	"which says what has landed and which cards carry the rest"	"which says what is generated where and where each part landed"
2	ADR-0087 :207-:208 (2026-08-06 note)	"spec-changes.json is deliberately unsharded"	"was left deliberately unsharded … That call was about merging its committed copy, which #22485 deleted (PR #22638)"
3	ADR-0087 :258-:273 (D4 note)	"The ruled end state, and the cards that still carry it … #22485, which lands last … Until #22485 lands the committed copies stay in the tree"	"The ruled end state, landed": #22483 as 514bf3c101 (PR #22556), #22485 as 46064dfa03 (PR #22638). No committed copy remains, and a registry entry's PR regenerates neither projection.
4	ADR-0087 :283-:284	"which #22485 removes"	"which #22485 removed"
5	ADR-0087 :431-:432 (P2 bullet)	"is ruled to become a pointer stub … which #22483 carries"	"became a pointer stub … the docs site's per-major pages (#22483, PR #22556)"
6	ADR-0087 :438-:442 (P2 amendment)	"Those copies stay in the tree until #22485 deletes them … what #22483 and #22485 still carry"	"Those copies are gone … generate in memory and compare nothing … where each part landed"
7	AGENTS.md :706	"eight checked-in generated artifacts"	"six"
8	AGENTS.md :717 (regenerate table)	ADR-0087 row: regenerate with gen:spec-changes, gen:upgrade-guide	Gates: the same two, in memory, red only when the registries do not project. Regenerate: nothing to commit; gen:migration-registry (install, build and test run it too) writes the gitignored registry.ts.
9	playbook :213-:216 (D3 step)	"在 packages/spec/src/migrations/registry.ts"	"在 packages/spec/src/migrations/registry.ts.template(registry.ts 由 gen:migration-registry 从它与 entries/ 整文件生成并被 git 忽略,在 registry.ts 里手改不会进提交)", which is the wording proposed in 6100582202
10	playbook :260	"gen:spec-changes、gen:upgrade-guide、gen:api-surface、gen:docs。"	"gen:api-surface、gen:docs;新条目跑 gen:migration-registry;D4 投影不提交,本地不重生成。"
11	playbook :335-:337	"只改 conversion 的 summary 也会过期 … 所以纯散文改动也要 gen:spec-changes + gen:upgrade-guide"	"只改 conversion 的 summary 不欠重生成。它逐字进两条 D4 投影,都不提交;PR 渲染其 diff。"

The card lists sites 2, 3, 4 and 6 to 11, with site 9 coming from 6100582202. The dispatch's same-class sweep of ADR-0087 found sites 1 and 5, which describe unlanded work in the same way. The verbatim ruling quotation at ADR-0087 :219-:220 is unchanged, and so is ADR-0120 :459-:460, which triage ruled to be history. The PR contains nothing beyond these 11 sites: git diff --stat a2e94c2a05 HEAD shows 3 files, +37 / -31.

How site 7's count was measured: the table's "Gate that fails" column names eight gates, and six of them still guard tracked artifacts.

• check:docs: content/docs/references/ (225 tracked files)
• check:api-surface: packages/spec/api-surface/ (19)
• check:authorable-surface: packages/spec/authorable-surface/ (14), plus json-schema.manifest/ (14)
• check:skill-docs: skills/README.md, content/docs/ai/skills-reference.mdx
• check:skill-refs: skills/*/references/_index.md (9)
• check:react-blocks: skills/objectstack-ui/references/react-blocks.md

check:spec-changes and check:upgrade-guide are the other two, and their projections have 0 tracked files.

Site 8 differs from the card. The card proposed check:migration-registry, but PR #22706 (ed1de8c2db) removed that gate after the card was filed. The row therefore names the two gates that do exist and states that there is nothing to commit.

Site 11 differs from the card too. No committed artifact carries a conversion's summary any more. It is read only by the two in-memory projections (spec-changes.ts to, build-upgrade-guide.ts table rows) and by their rendered PR diff. A summary-only edit therefore owes no regeneration.

Line budget

• AGENTS.md: 1108 lines before and 1108 after, with net 0 on the two edited lines. Ratchet line: ✓ check-skill-line-ratchet: AGENTS.md is 1108 lines (ceiling 1116; headroom 8). The widest table row is 768 bytes (pin 768).
• .claude/skills/spec-property-retirement/SKILL.md: 337 lines before and 337 after. Ratchet line: ✓ check-skill-line-ratchet: .claude/skills/spec-property-retirement/SKILL.md is 337 lines (ceiling 337; headroom 0). Site 9 adds +2 lines for its new parenthetical. Site 11 pays for them with -2 lines by deleting the false regenerate instruction. That is a content deletion, not a re-wrap. Site 10 swaps one line for one line. Every new line is at most 120 bytes (largest 119). Breaks fall only where the ratchet's own breakLegal allows one.
• ADR-0087 carries no ceiling (+27 / -21).

Gates

The gate list came from node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack with no paths: 31 commands derived from the merge base a2e94c2a0. All 31 exited 0 on head bd6337b8b. dispatch-gates --ran reports: ✓ dispatch-gates --ran: 31 derived famil(ies) accounted for — 31 run, 0 NOT-MEASURED (a DERIVED zero — all 31 recorded an exit code and none of them is 3).

The first run of pnpm --filter @objectstack/lint run check:doc-formula-expressions refused with exit 3 (PREREQUISITE NOT MET: @objectstack/formula and @objectstack/lint were unbuilt). I built both under the verify lock (VERDICT command-exit 0) and re-ran it: exit 0.

Gates the dispatch named, with their verdict lines:

• check-adr-0087-registration --base origin/main: "this PR adds no declared-breaking changeset". Its --self-test passes 463 assertions.
• check:adr-anchors: OK (64 anchored files, 43489 citations resolve).
• check-adr-links: 725 relative link destinations resolve.
• check-adr-symbol-anchors: 2309 anchors across 142 records resolve.
• check:pm-governed-prose: 2 surfaces name all 6 governed surfaces.
• check:pm-governed-merges: passes.
• check:pm-skill-ratchet: the two lines above.
• check:skill-frame-sync: coherent.
• check:pm-prior-rulings: 155 cases pass.
• check:future-spec-major: passes.
• check:docs-audit-scope: in sync.
• check:doc-authoring: clean.
• check:pm-skill-id-lint: 34 files clean.
• check:nul-bytes: OK (10817 files, no raw control bytes).
• check-ci-filter-parity: OK.

The diff touches no package, so no package build or test is owed. CI runs the rest.

Changeset: none. The diff touches only docs/adr/**, .claude/** and the private root's AGENTS.md, and no package's files[] ships any of them. The PR therefore takes skip-changeset.

Acceptance notes

• AGENTS.md section "Touched packages/spec?" still says "Two generators have no gate at all — gen:openapi and gen:sbom". check:generated --reconcile-only on this tree prints "3 ungated generators", because gen:migration-registry joined the list at PR build(spec): the migration registry is generated at build and leaves git #22706. It is the same family as this card, but it lies outside the AGENTS.md lines this claim declared, so it is not edited here and goes back to the seat.
• The same section's "All of them live in one job — TypeScript Type Check … runs its gates sequentially" predates this card. Five of the six gates run in Type Check · source gates, and check:api-surface runs in Type Check · consumer gates. Both lanes sit behind the required TypeScript Type Check aggregate. Noted only.
• ADR-0120 :459-:460 and :560 record what that PR ran, and stay untouched as history.

Patch round 1 (written by the PM seat from the diff on origin and the dev's report; head 6cb0d8ecd)

• Site 12 — AGENTS.md base :761–:762, the same "Touched packages/spec?" section. Before: "Two generators have no gate at all — gen:openapi and gen:sbom. Nothing verifies their output is current; the wrapper reports that each run rather than staying silent." After: "Three generators have no gate at all. Nothing verifies gen:openapi and gen:sbom are current, and gen:migration-registry writes gitignored output that install, build and test regenerate; the wrapper reports all three each run rather than staying silent." Evidence: packages/spec/scripts/check-generated.ts lists gen:migration-registry under UNGATED_GENERATORS since PR build(spec): the migration registry is generated at build and leaves git #22706 (ed1de8c2db), and pnpm --filter @objectstack/spec check:generated --reconcile-only prints "3 ungated generators". The claim's AGENTS.md surface was widened to the whole section on the card (comment 6106593221) before the edit.
• Incremental diff bd6337b8b..6cb0d8ecd: AGENTS.md +3/−2, nothing else. Whole PR against base a2e94c2a05: 3 files, +40/−33.
• Line budget after the patch: AGENTS.md 1109 lines (ceiling 1116; headroom 7), +1 for the sentence's third line; the playbook and ADR-0087 are unchanged from the first head.
• The first Acceptance note below is resolved by this round; the other two stand.

维护者速读(草稿)

改了什么:三份给 agent 读的受管文本是 ADR-0087 的 D4 进度注、AGENTS.md「改了 packages/spec 要重生成什么」一节和属性退役 playbook。里面还有句子把 spec-changes.json、升级指南和迁移注册表 registry.ts 当作提交在仓里的文件来写。本 PR 把这 12 处改成 main 现在的样子:两条投影只在发布或文档构建时生成，PR 上只在内存里生成并展示 diff;registry.ts 在安装和构建时由模板加条目文件生成，不提交。改动只有文字，不碰代码、门禁和发布内容。

为什么改:旧句子会让下一个改 spec 迁移的 agent 去跑一圈已经不存在的重生成。本周已有三个 dev 重生成后又回退。旧句子还会让人把 step-18 的说明手改进一个不会被提交的生成文件，改动在下一次构建时静默丢失。

风险与代价(含回滚):不发布任何包，不改任何门禁或脚本。ADR-0087 里维护者裁决的逐字引文没有动。回滚就是 revert 这一个 PR。代价是 playbook 删掉了一条已失效的陷阱说明(3 行压成 1 行)，用来抵付新增的模板说明，行数棘轮不变。

席位意见:

你要做的:看一遍上面的 11 项清单和补丁轮 1 的第 12 项。同意就给一个 APPROVED review,落地由席位来做。

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6cb0d8ecd8532b6e108369f8c52d3a069d440db5
Local-runs: none

Reviewed by the skills seat 2 in seat (session_011u73oxZ5X95qrARPTeoU6v, served model equal to the constant's value at get_session, re-read for this record), on the diff a2e94c2a0..6cb0d8ecd fetched from origin, the card #22667 with its triage and same-family notes, and the head's check-runs. Written 2026-10-11T07:41Z.

① Derived judgments

• Faces touched: governed rule text only — docs/adr/0087-metadata-protocol-upgrade-contract.md (+27/−21), AGENTS.md (+5/−4 across two rounds), .claude/skills/spec-property-retirement/SKILL.md (+8/−8). No packages/spec/src/**, no package exports, no error code, no schema: the published accept set and the public surface are unchanged. Clause-②: no is correct.
• Every rewritten sentence was checked against the tree it describes: 514bf3c101 (docs(spec): the protocol upgrade guide gets a public address, and docs/protocol-upgrade-guide.md stays as a committed pointer stub so the published pointers keep resolving (#22449 B′, condition 2) #22483, PR docs(spec): the protocol upgrade guide's public address is one docs-site page per protocol major; docs/protocol-upgrade-guide.md becomes a pointer stub (#22449 B′, condition 2) #22556), 46064dfa03 (spec(changes): delete the committed spec-changes per-major projection and the upgrade guide copy, with their two merge=os-regen routes, once generation at publish has landed (#22449 B′) #22485, PR spec(changes): delete the committed spec-changes.json and its merge=os-regen route; both projections are gitignored and generated at publish only (#22449 B′, card ③) #22638) and ed1de8c2db ([Decision] the migration registry registry.ts is the last committed generated aggregate on the ADR-0087 D3 path: keep it and finish B′, or generate it at build #22554, PR build(spec): the migration registry is generated at build and leaves git #22706) are ancestors of origin/main (exit 0); packages/spec/spec-changes.json, packages/spec/protocol-upgrade-guide.md, content/docs/protocol-upgrade/ and packages/spec/src/migrations/registry.ts are gitignored and untracked; registry.ts.template is tracked; docs/protocol-upgrade-guide.md is a 15-line pointer stub; packages/spec/package.json has gen:migration-registry, check:spec-changes and check:upgrade-guide and no check:migration-registry; UNGATED_GENERATORS in check-generated.ts lists gen:migration-registry, and the wrapper reports "3 ungated generators". The AGENTS.md count "six" matches the six gates whose artifacts stay tracked (docs, api-surface, authorable-surface, skill-docs, skill-refs, react-blocks).
• The verbatim ruling quotation at ADR-0087 (the "committed copies and their two merge=os-regen routes are deleted" block) and ADR-0120's dated record are unchanged on the head, as triage ruled.
• Playbook :213 carries the wording the spec seat proposed in 6100582202; :260 names gen:migration-registry for a new entry and no projection lap; the summary-only trap now says no regeneration is owed, which follows from both projections being generated in memory at PR time and at publish. Every new line is at most 119 bytes; the file stays 337/337, paid by deleting the false instruction (content, not re-wrap).

② Semver level

No published package is touched; skip-changeset is the correct declaration (docs/adr/**, .claude/** and the repo-root AGENTS.md ship in no package's files[]). The label is on the PR.

③ Boundary flags

• Dev flag: the same section's "All of them live in one job … sequentially" sentence predates the card (five gates run in Type Check · source gates, one in Type Check · consumer gates, both behind the required aggregate). Pre-existing, outside this card; noted, not filed.
• Dev deviation: the commit trailer is the repository's model-free pair, which the pre-push hook requires. Accepted.
• Seat note: the two same-class sites the dev swept in (the Status line and the P2 bullet) and site 12 (patch round 1, claim widened on the card at 6106593221) are the same defect as the filed lines.
• Tier: docs/adr/** and AGENTS.md are Tier H — this record is the review of record; the landing waits for an authorized APPROVED review and is then the seat's.
• Check-runs on this head: 38 check-runs on 6cb0d8ecd: 27 success, 11 skipped, none red (read 2026-10-11T07:40Z). The skips are path-filtered or opt-in on a docs-only diff: Build Core, Temporal Conformance (live PG + MySQL), Check Changeset (twice), Console Pin Gate, Build Docs, Dogfood Verify CLI, the dogfood shard placeholder, Auto Label, Check PR Size, Packed-tarball smoke (opt-in). Required contexts: TypeScript Type Check, Lint & Repo Gates, Test Core, Dogfood Regression Gate, Governed Surface Queue Guard success; Build Core and Temporal Conformance skipped by path filter, to be judged by check-expected-skips --pr 22796 before the enqueue.

Implemented-by: claude/issue-22667-governed-text-after-22485
Reviewed-by: session_011u73oxZ5X95qrARPTeoU6v

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

维护者速读(终稿)· PR #22796 · #22667

席位 2(session_011u73oxZ5X95qrARPTeoU6v,zhuangjianguo)对照自己读的 diff(a2e94c2a0..6cb0d8ecd,3 文件 +40/−33)校正 dev 草稿后定稿 · 2026-10-11T07:42Z。

改了什么:三份给 agent 读的受管文本里,12 处把 spec-changes.json、协议升级指南、迁移注册表 registry.ts 当作「提交在仓里、要本地重生成」的句子,改成 main 现在的样子:两条投影只在发布和文档构建时生成、PR 上只在内存里生成并展示 diff;registry.ts 由模板加条目文件在安装/构建时生成,不提交。文件:ADR-0087 的 D4 进度注与两处状态句、AGENTS.md「改了 packages/spec 要重生成什么」一节(产物计数 8→6、ADR-0087 那一行、无门禁生成器 2→3)、属性退役 playbook 三处(step-18 手改落点改到 registry.ts.template、重生成清单、summary 陷阱条)。只改文字,不碰代码、门禁、发布内容。

为什么改:旧句子把下一个改 spec 迁移的 agent 送进一圈已不存在的重生成;本周三个 dev 已经重生成后又回退。旧 playbook 还会让人把 step-18 说明手改进一个生成文件,下一次构建静默丢失。

风险与代价(含回滚):零发布面、零门禁改动;ADR-0087 里你的裁决逐字引文没动;ADR-0120 的历史记录没动。代价:playbook 删掉一条已失效的陷阱说明(3 行压 1 行)来抵付新增模板说明,行数棘轮 337/337 不动;AGENTS.md 1108→1109(上限 1116)。回滚 = revert 本 PR。

席位意见:ACCEPT。每句都对着树核过(三个落地 commit 是 origin/main 祖先;四个路径确在 .gitignore;check:migration-registry 确已不存在,所以 AGENTS.md 那一行写的是现存的两个内存门禁;check:generated --reconcile-only 确报 3 个无门禁生成器)。契约复核记录(达档、在席)已贴在本 PR。CI 在本 head 全绿(见复核记录)。

你要做的:同意即给一个 APPROVED review;落地由席位走队列。

---

Generated by Claude Code