fix(spec): os migrate meta guidance states the contract-first rule in words and drops a sweep batch ordinal (stage 10, the last)

[objectstack-fleet]

Fixes #20233
Stage 10, the last: the two dangling contributor-guide rule references and one sweep batch ordinal left in the author-shown text of the ADR-0087 semantic entries.

Clause-②: no

os migrate meta prints each semantic entry's surface, replacement, reason and acceptanceCriteria to the author. Stage 9 left every entry at 0 tracker ids in those fields. Three sentences still sent the reader to something they would have to look up:

• ui-list-view-grouping-field-padded-refused and ui-list-view-groupbyfield-padded-refused said a trimming schema is "the consumer-tolerance direction AGENTS.md #0.1 refuses". That number is rule 0.1 of the renderer repository's contributor guide, "Fix the metadata, not the renderer (contract-first)", which the ruling behind these entries cited as its governing text: fix the producer, do not teach the renderer to tolerate. It names nothing in this repository's AGENTS.md, and an author's project has neither guide. Both reason fields now state the rule itself: fix the metadata, not the renderer; off-spec metadata is refused where it is authored, never coerced into working.

• ui-notification-action-embed-config-retired named "its ui/ batch 14" of the v17 unknown-key strictness sweep. The same sentence already says what that batch measured (each ui/ file checked for an authoring door first; these two shapes three ways on 2026-08-03) and what it decided (not to close them with .strict(), and to leave the disposition to ADR-0049's enforce-or-remove). So the ordinal only pointed at a row of the campaign's plan. It is dropped, and the later "That batch" now reads "The sweep". Stage 6 dropped the same campaign's other batch labels the same way.

• Text only: a base-vs-head AST comparison over the 3 entry files and registry.ts finds 0 non-prose changes. 6 reason fields changed (3 per copy), with no id, surface, replacement, acceptanceCriteria, from / to, matcher, import, comment or token-skeleton change. Its self-test detects an id, comment, surface, skeleton and import mutation, and stays dark on a prose-only one.

• Census (stage 9's AST instrument, whole tree, 318 entries): base a918fe7fd0 has 0 prose sites, 0 surface sites and 10 short numbers. Head has 0 / 0 / 8. The 8 left are references to this repository's Prime Directives 2, 10 and 12, which stay. Before it was trusted, the instrument reproduced all 7 recorded readings from stages 5 to 9. Comment lines with a tracker id: 126 in semantic/ and 838 across entries/, the same at base and head.

• Generated: registry.ts, spec-changes.json and docs/protocol-upgrade-guide.md, by their generators. A second fresh regeneration leaves the tree clean. The two protocol-18 entries are not in the two projections, which carry released majors only. patch changeset.

Verification (head fa949a84f2)

• Build: turbo run build --concurrency=2 --filter=@objectstack/cli^...: 58 of 58 tasks succeeded, and the tree was clean afterwards.
• Tests (one lock turn at this head):
  • spec --project local: 575 of 575 files passed (16915 tests passed, 1 todo).
  • spec --project repo: 43 of 43 files passed (761 tests).
  • CLI --project integration, three files: the guidance pin test/migrate-meta-engine-guidance.test.ts, test/migrate-meta-default-range.test.ts, and src/commands/migrate/meta.stored-flow-resolution.integration.test.ts. All 3 files passed (13 tests passed, 1 skipped by the default-range file's own skipIf).
  • spec typecheck: exit 0, and the test-layer debt held (53 files, 251 errors).
  • The guidance pin, run again alone with the verbose reporter: all 3 of its tests passed.
• Gates: dispatch-gates.mjs --commands derives 83 families, and all 83 ran after the last commit. 82 exit 0. Among them: check:doc-authoring (16803 customer-facing strings clean), check:generated (all 15 artifacts up to date), check:migration-registry, check:spec-changes, check:upgrade-guide, check:issue-citations, check:nul-bytes, check:api-surface (unchanged), check:authorable-surface and check:adr-0087-registration (no declared-breaking changeset).
  • check:dual-build-cjs-loads is NOT MEASURED. Its prerequisite is not met: 9 packages outside the CLI closure have no dist/. Build Core runs it.
  • --ran reconciliation: 83 accounted for, 82 run, 1 NOT MEASURED, 0 unrun.
• Lint: eslint --no-inline-config --format json over the 4 changed .ts files: 4 files read, with 0 errors and 0 warnings. The population comes from eslint.config.mjs. The config enables no type-aware rules, so this diff cannot change the verdict for any file it does not touch.
• Mergeability: a driver-free merge-tree onto origin/main 3f45b6cc13 is clean. The one commit on main since the base touches none of these paths.

The dev report on #20233 has the sources each sentence was read from, the census readings and the AST-comparison record.

Acceptance notes

• This is the last stage, so the PR says Fixes #20233. After it, the card's population is 0: no tracker id and no dangling rule number in any semantic entry's printed fields.
• AGENTS.md #0.1 also appears outside this card's positions: in code comments (two docblocks in ui/view.zod.ts, one in ui/component.zod.ts, and two comments in ui/view.test.ts), and in four released packages/spec/CHANGELOG.md entries. Comments are form C, 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. The changelog is release-owned and never edited in a code PR. None of these is printed by os migrate meta.
• The pin's detector reads # plus four or five digits. A batch ordinal with no #, like the one removed here, is held by review, not by the pin.
• Two more batch tokens appear in printed prose, and both are file names, not plan ordinals. authoring-schemas-strict-unknown-keys lists the changeset file names its batches shipped under. ui-widget-i18n-family-retired names a test file. Both are outside this claim and untouched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 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. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

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
• 2 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 f1e921ab8ebfe061baec70b6113dee12b6360b4f → packageMentionDocs.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: fa949a84f2d0ac28cce7af4d1706d03c06d02431
Local-runs: none

Read-only review of PR #20642 (stage 10 of #20233, the last) at the head above, against main at the merge base a918fe7fd0, rendered 2026-09-29T12:55Z. Inputs: the card's body and all 37 comments (in particular stage 9's landing 5889476387, the stage-10 claim 5889494040 and the stage-10 report 5890543205), stage 9's PR #20630 and its at-tier record 5889122134, ruling C+D on #19123 (5749154545), the sources the new sentences read from (card #17360, objectui#7347 analysis 5615378321 and ruling record 5615810454, objectui's AGENTS.md rule 0.1 at blob 534a8ee514, card #4001 comments 5165088968 / 5171124152 / 5173360676), the PR's body, its one comment, its 7-file list and the net diff, and the head's check-runs read once. Every count below is my own reading of git show objects through a scratch tokenizer (no checkout, no build, no test, no gate); every sentence judgment is against the cited record, not the dev's prose.

① Derived judgments

1. Accept set: unchanged — RIGHT. The diff touches no Zod schema, conversion, matcher, id, surface, replacement, acceptanceCriteria, from / to, import or comment. My token-skeleton comparison of all 318 semantic entry files at base and head (every string literal collapsed, adjacent concatenations merged, comments dropped) reports 0 structural differences. A per-field extraction of the three entries' five fields at base and head finds exactly three fields changed, all reason; the other twelve are byte-equal. registry.ts parses to 367 entries at both refs with exactly three changed fields, the same three reasons, and each registry copy equals its entry copy byte-for-byte at head (lengths 3640 / 2204 / 1792).
2. Public surface: author-shown guidance text only — RIGHT. @objectstack/spec ships the registry, so the why: line os migrate meta prints changes for three entries and nothing else; no export is added or removed (Build Core and Type Check · source gates are green at this head; check:api-surface unchanged per the dev, judged by the still-running Type Check and Lint jobs).
3. The three projections are exact — RIGHT. The four registry.ts hunks sit inside the reason fields of ui-notification-action-embed-config-retired (two hunks), ui-list-view-groupbyfield-padded-refused and ui-list-view-grouping-field-padded-refused, verified by the nearest preceding id: and key. spec-changes.json (both its aggregate and perMajor copies) and docs/protocol-upgrade-guide.md carry the notification entry's head text: batch 14 and That batch read 2 / 1 at base and 0 / 0 at head in the two files. The two protocol-18 entries are absent from both projections at base and at head (0 hits on either id), as the released-majors-only design says; AGENTS.md #0.1 reads 0 in both at both refs, so nothing there was ever stale.
4. Census — reproduced. Whole tree, 318 entries, four printed fields: base a918fe7fd0 0 tracker ids (# plus 4-5 digits) in every field, 0 in surface, 10 short numbers, all in reason: #10 x4, #12 x3, #2 x1 and #0.1 x2. Head: 0 / 0 / 8, the same eight Prime Directive references in the same eight entries; the two #0.1 are gone. Tracker ids inside comment tokens read 143 at both refs (an occurrence count, so not the dev's 126-line figure, and equal on both sides). This repository's AGENTS.md carries #0.1 0 times at base and at head, so the reference was dangling here exactly as the stage-9 review escalated.
5. The two ui-list-view-* sentences — RIGHT, true to the source, nothing lost, nothing added. The number named rule 0.1 of objectui's contributor guide, «Fix the metadata, not the renderer (contract-first)», which card spec: GroupingFieldSchema.field accepts a padded field name that three objectui readers bucket wrong — refuse non-trimmed names at the producer (ruling C on objectui#7347) #17360's body cites as the governing text («fix the producer, do not teach the renderer to tolerate») and which the batch-110 item-5 analysis names as its governing text before the maintainer's 「其他同意」. The new parenthetical says: fix the metadata, not the renderer — the rule's title; off-spec metadata is refused where it is authored — the rule's «fix it at the producer (and have it rejected at authoring/publish)»; never coerced into working — the rule's «do not add a lenient fallback/alias in the renderer (… coercing a malformed shape …) to make non-compliant metadata work». Each clause maps to a clause of the source and none goes beyond it. The ruling record's own operative sentence (refuse at the producer with a non-padded pattern, not .trim() because that makes the padded and unpadded spellings silently equivalent) is the sentence these reasons already carried and still carry, untouched around the edit. Consistency with stage 9: the address- entry reads «(contract-first — fix the metadata, not the runtime)», this repository's Prime Directive 12 title; these two read «the contract-first rule … (fix the metadata, not the renderer: …)», objectui's rule title. Same form (the rule named as contract-first and stated in words, no number), each in the wording of the source its ruling actually cited; for entries whose subject is the renderer's readers and objectui's harvester trim, «renderer» is the truer word. The dev's offered two-line swap to the stage-9 parenthetical is not needed; it is the seat's taste if it wants one spelling.
6. The batch ordinal — RIGHT under form D, and the edited sentence is still true. «its ui/ batch 14» is row 14 of the plan table in card 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001's comment 5165088968 (action + notification + sharing + report + dataset + dashboard), claimed in 5171124152 and accepted in 5173360676. That is a pointer into a tracker object, which is the dependency form D removes (5749154545: «the lesson is written into the text»), and the claim's keep-arm («if it names nothing an author must look up») does not apply because a plan row is exactly something to look up. What the batch measured and decided is already in the sentence and I read it back against the source: 5171124152 dispatches the batch with «逐文件先测门（承载键 + BFS 可达 + parse 站点）» — the door measured per file, three ways, before any closing; 5173360676 (2026-08-04) accepts 9 tightened and 2 reclassified as no-door (EmbedConfig «全仓零提及改判») and routes ADR-0049 定去留:NotificationActionSchema / EmbedConfigSchema 实测没有授权门(#4001 批 14 改判的两个站点) #5015 (NotificationAction / EmbedConfig 无门退役) to REMOVE. So «did NOT close them with .strict() … left the disposition to ADR-0049's enforce-or-remove, which came back REMOVE on 2026-08-04» holds. Re-pointing «That batch» to «The sweep» keeps it true: the batch is part of the sweep, and the relative clause «which measured each ui/ file for an authoring door before closing any shape» was already attached to the sweep at base, so its reach is unchanged by the edit. Precedent: stage 6's report 5881313353 dropped the same campaign's «批 20» the same way. The two remaining batch tokens in printed prose at head are file names (-ui-batch13 etc. as changeset file names in authoring-schemas-strict-unknown-keys, and spec-symbol-batch7.test.ts in ui-widget-i18n-family-retired), not plan ordinals, and outside this claim.
7. Scope — RIGHT. The 7 files are the three entries the stage-9 landing named, their three projections, and one changeset: the claim's surface and nothing wider. No .claude/**, docs/adr/**, AGENTS.md, skills/** or NORTH-STAR path; Governed Surface Queue Guard is green. Head repo equals base repo; draft; assignee os-tesla equals the card's; 42 / 11 lines.

② Semver level

@objectstack/spec patch, Clause-②: no — RIGHT. Author-shown guidance text in a published package changes, so skip-changeset would be wrong; no accept set, export or authorable key moves, so minor is not owed and no widening / narrowing arm applies. The changeset body carries the standalone Clause-②: no line and the PR body carries it as its own line; the changeset names the three entries, says text only, and carries no tracker number and no model identifier. Check Changeset is green.

③ Boundary flags

• Dev deviation 1 (batch ordinal: DROP rather than keep or restate): answered in ①.6 — right; the restatement the claim's first arm asked for was already in the sentence.
• Dev deviation 2 (rule stated from objectui's rule 0.1 rather than this repository's Prime Directive 12): answered in ①.5 — right; no swap required.
• Dev deviation 3 (stage-9 instruments reused): their readings are reproduced here by an independent tokenizer (0 / 0 / 10 to 0 / 0 / 8; 3 fields; 0 skeleton changes).
• Dev deviations 4-8 (lock holds, CLI unit and typecheck not run locally, attribution form, no label writes, main not merged, teardown): bookkeeping. CLI unit and typecheck are Test Core's and Type Check's readings, still running at read time; registry.ts moved on main only under paths this diff does not touch per the dev's driver-free merge-tree, and GitHub reports the PR mergeable. If the queue reports a conflict there, regenerate, never hand-merge.
• Out-of-scope finding: five code comments citing AGENTS.md #0.1 (ui/view.zod.ts x2, ui/component.zod.ts x1, ui/view.test.ts x2, verified by git grep on the head tree): not printed by os migrate meta, so outside this card's positions; a comment's reader is a contributor with the sibling checkout, and the reference is a rule number, not a tracker number, so it is not 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 population either — at most a cosmetic «objectui's» that lane may add when it touches those lines. Nothing owed here. For completeness the same string also stands in packages/console/CHANGELOG.md (1) and docs/audits/2026-07-unknown-key-strictness-ledger.md (1), which the dev's list does not name; both are records, equally outside.
• Out-of-scope finding: four released packages/spec/CHANGELOG.md entries carry the same string (count verified 4): release-owned, never edited in a code PR, not printed by the migrator; not a factual error, so no docs-only PR is owed. Correctly left.
• Out-of-scope finding: the pin's detector reads # plus 4-5 digits only: as stage 9's record already held, a batch ordinal without # is held by review, which is what this review did. Not this card's.
• Out-of-scope finding: changeset file names in authoring-schemas-strict-unknown-keys's reason: file names, not numbers, outside the card's rule and the claim; if the seat treats «provenance an author cannot open» as its own class, that is a bare card, not a hold on this one.
• The eight Prime Directive references that stay: the claim fences them and the stage-9 record judged them contributor-guide rule references, not tracker ids; they resolve in this repository's AGENTS.md, which is the distinction from the dangling #0.1. Outside the card's population. Noted only: an author's own project holds neither guide, so if the seat ever wants those eight in words too, it is a separate card.
• Card population and closing keyword: the card's defect is tracker numbers in the printed fields of the semantic entries; that population is 0 at base and at head, and the three items stage 9's landing record named as «what is left on this card» are the three this diff delivers. Fixes #20233 is the shape the claim set for the last stage; the card's newest Claim: names this branch and the claim-parity check is green. Nothing else is owed on the card. Closing it is the seat's landing act with a closing record.
• Check-runs, read once: 32 on the head: 14 success, 3 skipped by design at this path set (Console Pin Gate, Build Docs, Packed-tarball smoke), 0 failing, 15 not concluded at read time: Test Core 1/6 through 6/6 (the CLI guidance pin and the spec suites), Dogfood Regression Gate 1/3 through 3/3, Dogfood Verify CLI, Temporal Conformance, Type Check · workspace, · consumer gates, · debt ledger, and Lint & Repo Gates (check:doc-authoring, check:migration-registry, check:spec-changes, check:upgrade-guide, check:issue-citations, check:generated). Green: Build Core (which also answers the dev's one NOT MEASURED family, check:dual-build-cjs-loads), Type Check · source gates, Check Changeset, Governed Surface Queue Guard, Spec property liveness, the card-claims-this-branch and Part-of checks, the same-issue and single-writer-path checks, Check PR Size, Check Documentation Links, Flag docs affected, Auto Label and filter. This verdict judges the diff; landing still waits for every required context to conclude green.

Implemented-by: claude/issue-20233-migrate-meta-last-references
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code