fix(spec): os migrate meta guidance for the remaining migration-entry families states each lesson in words, not tracker numbers (stage 9)

[objectstack-fleet]

Part of #20233
Stage 9: the remaining semantic-entry families, meaning every ADR-0087 semantic entry that still cited a tracker number.

Clause-②: no

os migrate meta prints each ADR-0087 semantic entry's surface, replacement, reason and acceptanceCriteria to the author. This stage covers the 44 entries that still cited a tracker, pull-request, decision-batch or cross-repository number: 39 with a four- or five-digit id, and 5 with a decision-batch number only. In each of them, every sentence now says what the cited ruling, measurement or fix decided (form D). ADR ids stay, and so do the contributor-guide rule references, which are not tracker ids. The address-location-value-unknown-keys-refused replacement cited AGENTS.md #0.1, which names nothing in AGENTS.md today. It now states the rule it copied from the 2026-09-01 ruling: a consumer-side alias for an off-spec key stays forbidden.

• Text only: a base-vs-head AST comparison over the 45 changed entry files and registry.ts finds no change outside replacement / reason / acceptanceCriteria. That is 48 prose fields per copy, and no surface, id, comment, import or token-skeleton change.
• Census (AST instrument, whole tree): base 682873f201 has 76 prose sites in 39 entries (replacement 3 / reason 73 / acceptanceCriteria 0), 0 surface sites and 28 short numbers. Head has 0 / 0 / 10. The 10 short numbers left are contributor-guide rule references.
• Pin: packages/cli/test/migrate-meta-engine-guidance.test.ts now holds every semantic entry instead of a prefix list, so an entry added later in any family is held on arrival. REWRITTEN goes from 203 to 247. Ablation: putting one removed id back into the turso- entry (a family the pin did not cover before) turned the pin red; restoring it turned the pin green.
• Generated: registry.ts, spec-changes.json and docs/protocol-upgrade-guide.md, by their generators. patch changeset.

Verification (head 96b994e472)

• Tests:
  • spec --project local: 575/575 files (16917 passed, 1 todo).
  • spec --project repo: 42/42 files (745 passed).
  • CLI --project unit: 234/234 files (3342 passed).
  • CLI --project integration, the three migrate-meta files: 3/3 (13 passed, 1 skipped by the default-range file's own skipIf).
  • spec and CLI typecheck: exit 0, test-layer debt held.
• Gates: dispatch-gates.mjs --commands derives 89 families. 88 exit 0, among them check:doc-authoring, check:generated, check:migration-registry, check:spec-changes, check:upgrade-guide, check:issue-citations, check:nul-bytes, check:api-surface and check:authorable-surface.
  • check:dual-build-cjs-loads is NOT MEASURED: its prerequisite is not met, because packages outside the CLI closure have no dist/. Build Core runs it.
  • --ran reconciliation: 89 accounted, 88 run, 1 NOT MEASURED.
• Lint: eslint over the 47 changed source files: 0 errors, 0 warnings.
• Mergeability: a driver-free merge-tree onto origin/main b80ab579d8 is clean. Main's new commits touch none of these paths.

The census method and controls, the source of every citation, and the ablation record are in the dev report on #20233.

Acceptance notes

• Four verbatim ruling quotes carried a card or batch number: 「217 同意」, 「9266 同意 A」, 「146 同意」, and one reply that also answered another card. Each now keeps only its operative words, or states the decision instead.
• The claim fenced off four entries. Two of them are not on main: they arrive with PR feat(spec)!: $empty joins FILTER_OPERATORS, and is_empty / is_not_empty lower to it (#20446) #20570 and PR feat(spec)!: retire the connector triggers array — the ConnectorTrigger shape nothing registered, polled or received (#20287) #20587. The two on main carry no site. PR feat(spec)!: $empty joins FILTER_OPERATORS, and is_empty / is_not_empty lower to it (#20446) #20570's incoming filter-is-empty-lowers-to-empty-operator carries six tracker ids in reason, and the filter- family was already held by this pin before this stage.
• ui-list-view-groupbyfield-padded-refused and ui-list-view-grouping-field-padded-refused still cite AGENTS.md #0.1 in reason. That is the same dangling number the address- entry had. Both entries are outside this stage's claim and are untouched.
• ui-notification-action-embed-config-retired names "its ui/ batch 14" of the strictness sweep, a batch number without #. It is outside this stage and untouched.
• Comment and docblock lines of the entries still cite tracker ids: 127 lines in semantic/, 839 across entries/. They are form C's, under packages/spec/src: 1,277 comment lines still cite 170 deleted tracker numbers (1,295 sites) — the staged remainder of ruling C+D on #19123, measured by PR #20226 #20234, and are untouched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/spec-changes.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/kernel/services-checklist.mdx (via /api/v1/workflow (route, a path literal in reason; a path literal in semantic))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via /api/v1/workflow (route, a path literal in reason; a path literal in semantic))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/spec-changes.json) — pages documenting those are invisible to this run
• 3 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json b80ab579d8bdd7499805612104ce95d931b0f03e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 619ee3e31cc279c3993f4aec32a7e1bb26781a9a — the merge of head 96b994e472ba988aa9fae42e3b3c1fde2437e591 into base b80ab579d8bdd7499805612104ce95d931b0f03e, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 619ee3e31cc279c3993f4aec32a7e1bb26781a9a && git checkout 619ee3e31cc279c3993f4aec32a7e1bb26781a9a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin b80ab579d8bdd7499805612104ce95d931b0f03e 96b994e472ba988aa9fae42e3b3c1fde2437e591 && git checkout -B drift-repro b80ab579d8bdd7499805612104ce95d931b0f03e && git merge --no-ff 96b994e472ba988aa9fae42e3b3c1fde2437e591

node scripts/docs-audit/affected-docs.mjs --json b80ab579d8bdd7499805612104ce95d931b0f03e

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs b80ab579d8bdd7499805612104ce95d931b0f03e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 96b994e472ba988aa9fae42e3b3c1fde2437e591
Local-runs: none

Read-only review of PR #20630 (stage 9 of #20233) at the head above, against main at the merge base 682873f201 and against origin/main 542670da as read in this act. Inputs: the card's body and all 33 comments (triage 5856629820, ruling A on surface in 5858839916, stage 8's report 5886017515 and landing 5886769122, the stage-9 claim 5887268542 and report 5888773479), ruling C+D on #19123 (5749154545), the PR's body, comments, 50-file list and net diff, the cited sources, and the head's check-runs read once. Nothing from the dev's prose was adopted without a reading of my own: every count below comes from a scratch tokenizer run over git show objects (no checkout, no build, no test, no gate), and every sentence judgment from the cited record.

① Derived judgments

1. Accept set: unchanged — RIGHT. No Zod schema, conversion, matcher, id, surface, from / to, import or comment moves. My token-skeleton comparison of the 45 entry files at base and head (string runs collapsed, every comment and every non-prose string compared by value in order) reports 0 non-prose changes and exactly 48 prose fields changed: 44 reason, 4 replacement, 0 acceptanceCriteria, 0 surface. Semantic entries carry no from / to or matcher.
2. Public surface: author-shown text only — RIGHT. @objectstack/spec ships the registry, so the why: / verify: lines os migrate meta prints (meta.ts:523-525 prints surface, replacement, reason, acceptanceCriteria) change for 45 entries; no export is added or removed (check:api-surface unchanged per the dev; Build Core and Type Check source gates are green at this head).
3. The three projections are exact — RIGHT. The removed and added line multisets of registry.ts's diff equal the 45 entry files' diff (85 removed / 143 added, both sides). spec-changes.json (both its aggregate and perMajor copies) and docs/protocol-upgrade-guide.md carry the head reason / replacement / surface for all nine changed protocol-17 entries byte-equal; the 36 protocol-18 entries are absent from both by design (released majors only). The 138 tracker ids still in spec-changes.json sit in conversion rows' to fields, outside this card's positions.
4. Census — reproduced. Base 682873f201: 76 prose sites (replacement 3 / reason 73 / acceptanceCriteria 0) in 39 entries, 0 surface sites, 28 short numbers. Head: 0 / 0 / 10; the 10 are Prime Directive chore: version packages #10 (x4), Add comprehensive test suite for Zod schema validation #12 (x3), ✨ Set up Copilot instructions #2 (x1) and AGENTS.md #0.1 in the two ui-list-view-* entries. origin/main 542670da outside the PR's 45 files reads 0 tracker sites and the same 10 short numbers; the one entry added there since the base (connector-triggers-retired, PR feat(spec)!: retire the connector triggers array — the ConnectorTrigger shape nothing registered, polled or received (#20287) #20587 merged) reads 0 in all four fields. So the merged population is 0. None of the four fenced entries is in the file list.
5. Sentence truth — RIGHT, no invented claim found. Read from source for: turso- (driver-turso: a remote url plus syncUrl is classified replica and handed a :memory: Knex connection, so every write lands in process memory and never reaches the remote #19893, driver-turso: a url whose scheme the classifier does not recognise (an uppercase LIBSQL://, a bare path) and no mode falls through to local on a :memory: Knex engine, so every write is lost on restart #19976 bodies; driver-turso: new TursoDriver accepts syncUrl / sync under mode: 'remote' and ignores them — isSyncEnabled() answers true, no sync runs, and sync() rejects SYNC_NOT_SUPPORTED #20200's constructor refusals via PR fix(driver-turso)!: new TursoDriver refuses syncUrl under a forced remote mode, and sync with no syncUrl (#20200) #20447's report), cbp- (A controlled_by_parent object may declare its master reference without required, so the master-access guard is the only thing preventing an unreachable orphan detail row #8772 is 404: read from commit 75b7c240a3 and card spec builder: force required: true on a master_detail reference under controlled_by_parent (ruled Direction 2 of #8772) #9138, which name Direction 2 as the builder forcing required: true and lint staying warning until the v18 sibling; the sentence keeps the base's Direction-1 attribution and adds nothing), autonumber- (hotcrm#1301 is 403: autonumber 业务标识字段默认不唯一,可铸重号 —— 裁定:默认唯一(租户复合形状),显式退出才不唯一 #13894's body carries the nine-field measurement, eight duplicable, and the 2026-08-31 ruling), cluster- (cloud#1626 is 403: the spec CHANGELOG entry for c85a265 carries the 2026-08-24 option-B ruling and its rider), structured- (batch 145 C 5714239196 and batch 146 禁 / A 5714974100 / 5714974443 are both dated 2026-09-17; batch 153 D 5724940095 is 2026-09-18), admin-scope- (5793356837: A, refuse blank at parse, stored rows untouched), wait-node- (objectui#9354 5651579637: batch 127 item 5, 2026-09-13, and that record itself states 「其他同意」 covers this item), address- (5494663475 item 5 is the source of AGENTS.md #0.1: consumer-side alias stays forbidden), plus approval- (C, 2026-08-27, the declared default moves to the truth), batch-row- (fix(metadata-protocol): deleteManyData has the same fake-atomic as batchData, updateManyData ignores atomic entirely #4620 fix; fix(metadata-protocol)!: batch 逐行结果迁移到 BatchOperationResultSchema 形状 —— 方案 B 已拍板,硬切 + 诚实迁移说明(Blocked-by #4620) #4793 plan B hard cut ruled 2026-08-03), standard-error-code-batch- (5328254030: 「9266 同意 A」 = retire the three codes), standard-error-code-concurrent- (A 2026-09-13, narrowed 2026-09-24), cel- (A 2026-09-24, comparand is a literal or { $field }), memory- (direction 2, 2026-08-13), schedule- (A′ 2026-09-16), logging- (A 2026-09-11, gate lands last), ai- / device- / websocket- / epoch- (B 2026-09-02 and the 2026-09-05 population ruling 5548763981), change- / incident- / training- / esignature- (A 2026-09-02 per family; batch 40 answered no roadmap on 2026-09-05), assembled- (A 2026-09-04), translation- (② 2026-09-13, B 2026-09-22), observability- / screen- / ui-bulk-action- (A 2026-09-18, A′ 2026-09-13, A 2026-09-17 via their landing PRs), auth- (2026-08-11 stop-advertising; objectui#4179 closed not_planned), and the own-card drops (send-, time-, job-, enhanced-, connector-inline-, position-, ups-, workflow-, audience-, admin-export-, branded- / event-name-) whose titles state what the sentence now says. Where a number was dropped without replacement the surrounding sentence already carried the lesson (e.g. discovery 的 workflow / graphql 槽位还声明着两条无人挂载的 route —— #4318 同款,但目前"上了膛没击发" #4451, [#14478 stack 1/6] declare the two exemption classes ON THE SCHEMA — a shared EpochMs for the 6 epoch instants and a .meta({ externalVocabulary }) marker on the 13 external-standard keys, honoured by check:duration-unit-keys and printed by the docs generator #15676/[#14478 stack 2/6] api/: the 12 remaining duration keys carry their unit in the key name — ADR-0087 conversions with readers, ApiError.retryAfter with its own BREAKING note #15677/[#14478 stack 5/6] data/ · ui/ · ai/ · integration/: the 7 remaining duration keys carry their unit in the key name — ADR-0087 conversions with readers #15680 trailing ids, [finding] SendTemplateInput.org is declared ("Tenant id for org-overlay resolution (when supported)") but no implementation reads it #11832 own card); no lesson was lost.
6. Verbatim maintainer quotes — RIGHT. Form D (5749154545, 「保留 issue id没有意义」) forbids a number in author-shown text, so a quotation whose only content beyond assent is a card or batch number cannot stay as written. 「217 同意」 and 「146 同意」 are dropped, not rewritten, with the decision stated in words and the date kept; 「9266 同意 A」 is replaced by the option the ruling record itself spells out; the wait-node reply keeps its clause for this item 「其他同意」 untranslated, cut at the sentence boundary, exactly the reading the recording comment gives. AGENTS.md forbids translating or rewording a quoted ruling; excerpting the clause that answers this item is neither. The quotes that carry no number (「同意,其他也同意」, 「其他同意」, 「同意」, 「Breaking for authored metadata」) are untouched.
7. Scope reading of the five batch-only entries — RIGHT. Triage's direction is 「no number, dead or alive」 in form D; stage 8 already rewrote decision-batch and summon numbers under a PASS record and left only contributor-guide rule references, and the claim's 「still carries one」 reads on that classification. A batch number sends the reader to a director-summon record outside this repository, which is the defect. Including observability-, screen-, translation-, ui-bulk-action- and wait-node- is the consistent reading; the census is 0 either way.
8. The pin — RIGHT, non-vacuous, and no family loses its hold. FAMILY is now every semantic entry of every major, a superset of the old prefix-filtered set, so every block asserted before is still asserted; each block is asserted present in stdout before it is asserted tracker-free; REWRITTEN 203 to 247 (44 added; address- was already listed from stage 8) and the containment assertion stays. The one dropped assertion (each prefix selects at least one entry) existed to stop an emptied prefix making the loop vacuous; 247 required ids do that job now. The claim allowed the whole directory once the census read 0. Subtracting the fenced entries would have loosened filter-, held since stage 4 (COVERED_PREFIXES at base names it). PR feat(spec)!: $empty joins FILTER_OPERATORS, and is_empty / is_not_empty lower to it (#20446) #20570's filter-is-empty-lowers-to-empty-operator therefore meets the same demand before and after this diff; at its current head a1402a37 its four printed fields carry 0 tracker ids (two remain in comment lines only), so it meets it either way. Ablation not re-run here; the dev's red-then-green on turso- is consistent with the detector # plus 4-5 digits.
9. Not governed. No .claude/**, docs/adr/**, AGENTS.md, skills/** or NORTH-STAR path in the 50 files; Governed Surface Queue Guard is green.

② Semver level

@objectstack/spec patch, Clause-②: no — RIGHT. The published package's author-shown guidance text changes, so skip-changeset would be wrong; no accept set, export or authorable key moves, so minor is not owed and no arm applies. The changeset body carries the standalone Clause-②: no line, says text only, names the families and the address- rule restatement, and states that no id, surface, from / to or matching logic changes. Check Changeset is green.

③ Boundary flags

• Dev deviation 1 (batch numbers counted as tracker numbers): answered in ①.7 — right; no file leaves the PR.
• Dev deviation 2 (four verbatim quotes trimmed or replaced): answered in ①.6 — right under form D; no ruling misrepresented.
• Dev deviation 3 (pin holds the whole directory, no fence subtraction): answered in ①.8 — right.
• Dev deviation 4 (census and astdiff rewritten): their readings are reproduced here by an independent reader (76 / 0 / 28 to 0 / 0 / 10; 48 prose fields; 0 non-prose changes).
• Dev deviation 5 (no deletion leg): acceptable — the dispatch did not ask for one; stage 8's leg found only the tool-pin fragments, all still present in this head's text, and the full spec and CLI runs at head are the dev's; CI's Test Core is the reading of record.
• Dev deviations 6-10 (background waits, attribution form, no label writes, main not merged, teardown): bookkeeping, nothing to rule. registry.ts moved on main under PR feat(spec)!: retire the connector triggers array — the ConnectorTrigger shape nothing registered, polled or received (#20287) #20587; GitHub reports the PR mergeable (not dirty) at read time. If the queue reports a conflict there, regenerate, never hand-merge.
• Out-of-scope finding: ui-list-view-groupbyfield-padded-refused and ui-list-view-grouping-field-padded-refused cite AGENTS.md #0.1 in reason — ESCALATED to the seat. Not a tracker number, so outside this card's population and outside the stage-9 claim; but it is the same dangling rule reference the stage-8 review escalated and this seat took into stage 9 for address-. The consistent disposition is a two-sentence follow-up under this card before it closes, or a bare card. Not a defect of this diff.
• Out-of-scope finding: ui-notification-action-embed-config-retired names 「its ui/ batch 14」 (no #): a sweep batch label, not a tracker number, not caught by the pin's detector, family covered since stage 2. Noted; the seat may fold it into the same follow-up.
• Out-of-scope finding: PR feat(spec)!: $empty joins FILTER_OPERATORS, and is_empty / is_not_empty lower to it (#20446) #20570's incoming entry: resolved on its own — 0 tracker ids in its four fields at a1402a37.
• Out-of-scope findings: packages/spec/src: 1,277 comment lines still cite 170 deleted tracker numbers (1,295 sites) — the staged remainder of ruling C+D on #19123, measured by PR #20226 #20234's comment lines (127 / 839) and the detector's 1-3-digit blind spot: theirs and not this card's; correctly left.
• Card population and closing keyword: the population this card names (tracker numbers in the four printed fields of the semantic entries) is 0 on this head and on the merged state. Part of #20233 is the shape the claim set for a staged card and the Part-of check is green; closing the card is the seat's landing act with a closing record, after it decides the escalated AGENTS.md #0.1 pair. No body edit is required by this record.
• Check-runs, read once: 32 on the head: 17 success, 3 skipped (Console Pin Gate, Build Docs, Packed-tarball smoke — skip-by-design at this path set), 0 failing, 12 not concluded at read time: Test Core 1/6 through 6/6 (the CLI test script is vitest run over both projects, so the pin runs there), Lint & Repo Gates (check:doc-authoring, check:migration-registry, check:spec-changes, check:upgrade-guide, check:issue-citations, check:generated), Type Check · workspace, Type Check · consumer gates, Temporal Conformance, Dogfood Regression Gate 1/3 and 3/3. Green so far: Build Core, Type Check · source gates and · debt ledger, Check Changeset, Spec property liveness, Governed Surface Queue Guard, Part-of and claim checks, single-writer path, Check Documentation Links, Dogfood Verify CLI, Dogfood Regression Gate 2/3. This verdict judges the diff; landing still waits for every check to conclude green.

Implemented-by: claude/issue-20233-migrate-meta-tracker-free-stage-9
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code