docs(spec): the major-18 conversions docblock places the import, not the definition - #30643

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/conversions/registry.ts), 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)).

domain:spec#2 · os-sales · session_01L6bhgVugtCCwBs98FeR27P

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6943445b89f637352585ead984a2fd63d4e4fe37
Local-runs: none
Scope: packages/spec/src/conversions/registry.ts + packages/spec/scripts/conversions-major18-merge.test.ts (the gate that enforces the rule), packages/spec/src/conversions/entries/18/*.ts (the 95 modules the docblock describes), .claude/skills/spec-property-retirement/SKILL.md on main after PR #30109 (the same steps, read for agreement), AGENTS.md Post-Task Checklist step 3, scripts/check-empty-changeset.mjs, packages/spec/package.json files[] and packages/spec/tsup.config.ts (read for ②)

Inputs: card #29994 (body; comments 6619509152, 6619532361, 6632322266, 6634099014, 6666793161, 6668036951), PR #30643 (body, file list, net diff against main at 778aedf666), the check-runs on the head read at 2026-11-05T20:14Z: 23 completed success (among them Check Changeset, Governed Surface Queue Guard, PR-body guards, Spec property liveness, Flag docs affected by code changes, Plan Test Core shards, every Lint · lane, Lint · PM dispatch-gates, Type Check · consumer gates, Type Check · debt ledger, Type Check · source gates, Dogfood Regression Gate), 14 skipped by path filter, 0 failed; 29 still in progress at read time (Build Core, Test Core 1–8 — which carry conversions-major18-merge.test.ts — Test UI 1–16, Type Check UI, Type Check · workspace, Build & E2E UI, Live E2E UI). This verdict reads the completed conclusions; a later failure among the in-progress runs is a new fact for the queue, not covered here

① Derived judgments

• No code line of registry.ts changed — right. The net diff is 9+/5− lines and every changed line is a * line inside the one block comment that opens at L160 and closes at L189 on main (L193 on the head); nothing outside that comment is touched, so the comment-stripped bytes of the file equal main's. The imports (L24–135), OrderedConversion (L146–151), inApplicationOrder (L154–158), the 95 entries of MAJOR_18_CONVERSIONS (L194–296), CONVERSIONS_BY_MAJOR (L326–349) and ALL_CONVERSIONS (L355–358) are byte-identical to main.
• Public surface: none — right. MAJOR_18_CONVERSIONS is a non-exported const; the exported CONVERSIONS_BY_MAJOR and ALL_CONVERSIONS and their docblocks are unchanged, so dist/*.d.ts, api-surface and every schema-derived generated artifact are unaffected.
• Accept-set: unchanged — right. The docblock now states the rule conversions-major18-merge.test.ts already enforces (④); the test, the PLACED_BEFORE_THE_RULE exemption (46 names) and every other gate are untouched, so nothing becomes accepted or refused that was not before.
• Fixes #29994 — right. The card's two deliverables are the SKILL.md steps (landed in PR docs(skills): point spec-property-retirement at the split conversions layout #30109, partial landing 6634099014) and this docblock (scope addition 6619532361); this PR closes the remainder.

② Semver level

• skip-changeset (label on the PR; Check Changeset success) — right. AGENTS.md step 3 reserves the label for "a diff that publishes nothing from any released package". @objectstack/spec's files[] are dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface, spec-changes.json, protocol-upgrade-guide.md. registry.ts is not a *.zod.ts; the docblock sits on a non-exported const, so no .d.ts carries it; tsup.config.ts sets no legalComments, so esbuild drops a /** */ block that carries no @license/@preserve (the file's @__PURE__ annotations are not in the hunk); the sourcemaps ship without sourcesContent (check:sourcemap-no-sources-content). The changed text reaches no published artifact, so there is nothing a changeset could describe.
• scripts/check-empty-changeset.mjs: no .changeset/*.md is added, modified or deleted — both of its rules are vacuous here; green.
• Clause-②: no, Metadata-protocol: none — right: nothing an author can write, and no export, changes.

③ Boundary flags

• Dev flag (PR body; report 6668036951): the test anchors a last-sorting import after the last ./entries/18/ import, not on OrderedConversion. Confirmed. definitionsTail (test L149–154) returns the line after the last DEFINITION match (L62, which recognises ./entries/18/ID.js imports only), and placementFindings (L170–186) demands that the last entry's import have no ./entries/18/ import after it (the want === undefined arm, L182–183). OrderedConversion appears nowhere in the test. Today the last such import (L135) is also the last import of the file, two lines above OrderedConversion's docblock (L137), so both anchors coincide; the new sentence names the one the test reads. Answered.
• open_questions: [] — none.
• Dev deviations (the attribution HTML comment as the PR body's first line; the dispatch prompt's two-line footer): PR-body form only; PR-body guards success. Accepted.
• Docs Drift Check comment 6668037579 ("1 changed file yielded no anchor"): a comment-only hunk in a file no docs page anchors; Flag docs affected by code changes success. No action.
• The seat claim's ⛔ list (6666793161: no code line of registry.ts, no edit to the merge test, no .claude/**) held — the file list is registry.ts alone and ① shows no code line moved.
• Triage 6619509152 ("no @objectstack/skills changeset applies") covered the skill half; the spec half is judged in ②.

④ Design judgment

packages/spec/src/conversions/registry.ts L181–189, read against packages/spec/scripts/conversions-major18-merge.test.ts on main (unchanged since PR #29993's split, d79eecfe5b), the 95 modules under src/conversions/entries/18/, and SKILL.md on main (28ce3d1bfa).

Each sentence against what enforces it:

• "DEFINE it in a module of its own, ./entries/18/ID.ts, the file named for the conversion's id" — definitionsOf (L144–146) takes the id from the import path, MODULE_PATH (L64) resolves entries/18/${id}.ts, and definitionInModule (L157–161) requires id: 'ID' inside that file: the file name IS the id, and the test refuses any other. 95/95 modules on main have that shape (const IDENT: MetadataConversion = {, an id: equal to the file name, export { IDENT }; as the last line).
• "exporting it by name (export { IDENTIFIER };)" — definitionInModule requires the module to end with exactly that statement; the form the docblock prints is the form the test accepts.
• "A new file never conflicts" — test header L26–27; git conflicts only on edits to one path.
• "IMPORT it directly above the import of the entry that follows it in this list, so the conversion imported next after it is that entry" — placementFindings L174–185: for a non-exempt entry at list index i, the next ./entries/18/ import after its own must be the entry at i+1. definitionSite (L204–210), which builds the accepted retirement, inserts at docStart of the successor's import — the same instruction. Walked by hand: a conversion sorting first (successor actionAriaRemoved, import L119); one between two exempt neighbours; one between a rule-placed predecessor and that predecessor's successor (the predecessor's next import becomes the new one, which is now the entry that follows it — the test's own neighbour case, L404–413); two successive last-sorting ones (the second goes after the first, which then precedes it in the list too). All accepted.
• "One that sorts last is imported after every other ./entries/18/ import" — definitionsTail L149–154 and the want === undefined arm of L182–183. Holds (③).
• "The imports stand where the definitions stood before the split" — the file's codemod note L20–23 and the test header L29–31.
• "their end is one gap too: importing every new conversion there conflicts exactly as appending here did" — the lit control L442–446 (definitions-end-a × definitions-end-b must conflict) built by retireAtDefinitionsEnd L232–235.
• The unchanged bullets still match: insert where the identifier sorts (sortFindings L164–167, the list-end control L436–440); order one more than the highest (NEXT_ORDER L313); equal order applies in id order (inApplicationOrder L154–158, applicationOrder L238–244, asserted L426). The closing pointer to the test is true: the test holds the sort rule and the placement rule for every entry outside the exemption.

Skill agreement: SKILL.md L176–177 (entries/TOMAJOR/ID.ts, 文件名即 id, 按名 export; registry.ts 加 import 与列表项) and L215–218 (18 步: 照其头注按标识符插入 { conversion, order }; import 插在后继条目的 import 正上方; 尾部追加被 merge 测试拒收) say what the docblock now says; no sentence of either contradicts the other. The skill's gloss "(头注的「定义」拆分后即 import)" explained the OLD bullet and is now redundant rather than wrong — .claude/**, outside this card's remaining surface; nothing owed here.

Break attempts — a literal follower of the docblock against the test:

• S1 — should-fix, registry.ts L181–182. The docblock names the module ./entries/18/ID.ts and says "IMPORT it" but never says the import specifier is spelled ./entries/18/ID.js. DEFINITION (test L62) recognises only from './entries/18/ID.js'; an import spelled .ts is reported by placementFindings as "no import of IDENT from its module in the file" (L177) and fails L335–342 — and tsc refuses it first (allowImportingTsExtensions is set only in packages/spec/tsconfig.scripts.json, not for src). The 95 neighbouring imports show the spelling, so an author who copies a neighbour is safe; one clause ("imported as ./entries/18/ID.js") closes it for one who does not.
• S2 — should-fix, registry.ts L181–183. "exporting it by name" is also satisfied, in TypeScript's vocabulary, by export const IDENTIFIER: MetadataConversion = {, which definitionInModule refuses: it wants a bare const IDENTIFIER: MetadataConversion = { with id then toMajor: 18 as the first two keys, and export { IDENTIFIER }; as the module's final line. The parenthetical prints the accepted form, so a literal follower passes; saying the export is a separate last statement, or "as every module under entries/18/ is written", stops the other reading before the test does.
• No sentence of the new text is false of the test or of the tree; no must-fix.

Implemented-by: claude/issue-29994-conversions-placement-docblock
Reviewed-by: session_01L6bhgVugtCCwBs98FeR27P

VERDICT: PASS

Generated by Claude Code

domain:spec#2 · os-sales · session_01L6bhgVugtCCwBs98FeR27P

维护者速读

• 改了什么：packages/spec/src/conversions/registry.ts 里 MAJOR_18_CONVERSIONS 上方的注释改成拆分后的真实做法：新转换写在自己的模块 ./entries/18/<id>.ts 里，在 registry.ts 只加一行 import（放在列表里紧随它那条的 import 之上）和一行列表项。只改注释，没有代码变化。
• 为什么改：PR refactor(spec): codemod split of conversions/registry.ts into per-entry modules (#29987) #29993 把转换拆成每条一个模块后，这段注释还在教人把定义写进 registry.ts，照做的人要么手改索引，要么把转换塞回已经清空的文件。技能文件那一半已由 PR docs(skills): point spec-property-retirement at the split conversions layout #30109 改好，这是剩下的一半。
• 风险与回滚：只改一段注释，不进任何发布产物，所以不带 changeset（skip-changeset）。回滚即 revert 本 PR。
• 先看：packages/spec/src/conversions/registry.ts L181-189 → 对照 packages/spec/scripts/conversions-major18-merge.test.ts 的 definitionInModule 与 placementFindings。
• 两分钟验证：pnpm --filter @objectstack/spec exec vitest run scripts/conversions-major18-merge.test.ts，预期 12 条全过。
• 需要你做的：无，席位落地。
• 席位意见：接受。契约面达档复核 PASS（comment 6668217294，Head-sha 6943445b），没有 must-fix；两条 should-fix 是注释还可以再补的写法细节，不采纳，理由见第 5 项。

席位核对

ACCEPT · head 6943445b89f637352585ead984a2fd63d4e4fe37 · 2026-11-05T20:15Z

1. 形态：draft，base main，正文 Fixes #29994，全文只有这一个闭合关键词。只改 1 个文件，在认领文件面内，而且只动注释块；导入、列表项、函数、合并测试、.claude/**、skills/**、docs/adr/**、AGENTS.md 都没碰。标签 skip-changeset。
2. 前提实测：在 origin/main 上，PR refactor(spec): codemod split of conversions/registry.ts into per-entry modules (#29987) #29993（d79eecfe）已把每个转换拆到 src/conversions/entries/18/ 下的模块里，registry.ts 只 import 它们；注释还写着 “DEFINE it directly above the definition of the entry that follows it … directly above OrderedConversion”。合并测试的头注（L26-31）早已按拆分后的规则判。前提成立。
3. 门禁 check-runs：
   • head 6943445b 上读到 24 success、14 skipped、0 failure，另有 28 条仍在跑（Build Core、Test Core 1-8、Test UI 1-16 等）。全部跑完且无红，才 pr_ready + automerge_enable。
   • 契约复核 6668217294 在 Served-tier: CONTRACT_REVIEW_TIER 下 PASS，Scope 覆盖 hits（registry.ts）以及合并测试、entries/18/ 的 95 个模块和 main 上的技能文件。
   • dev 本地 67 条派生门禁 --ran 0 NOT-MEASURED，只证本地子集；三条首轮 exit 3 是前置包没构建，全量构建后重跑都是 0。合并测试本地 12/12。
   • 注释改动不欠 pin，也没有消融可做。
4. 席位自读（TIER_DEFAULT，hits 之外的部分）：本 PR 没有 hits 之外的文件。席位读了 diff：14 行全在一个块注释里，另两条规则（按标识符排序插入、order 的取法）和冲突说明原样保留。
5. 接受的偏差：
   • 复核 S1：注释没说 import 的说明符要写成 ./entries/18/<id>.js。不采纳：写成 .ts 时 tsc 先报错，合并测试也会报 “no import of IDENT from its module”，两处都当场指出，不会悄悄合进去。
   • 复核 S2：“exporting it by name” 也能读成 export const …，而测试要的是裸 const 加文件末尾的 export { … };。不采纳：注释括号里给出的正是被接受的写法，照着写就能过；写成别的形式，测试会当场拒绝。
   • 这两处都是注释还能写得更细，不是写错。为此挪 head 还要再复核一次，不划算。
   • 新注释把 “排在最后的那条” 锚在最后一个 ./entries/18/ import 之后，而不是 OrderedConversion 之上，这是跟着测试写的，复核已核对。
6. 范围外去向和 Skills-docs:：
   • 种类是 none，没有 (narrowing)，不欠 Skills-docs: 行。
   • 复核提到技能文件 L176-177 里 “头注的「定义」拆分后即 import” 这句现在多余但没错，不在本卡文件面内，不立卡。
7. 落地条款：check-governed-merges.mjs --pr 30643 已在本 head 读过：1 个路径 0 个命中 governed 登记，14 行（+9 / -5）≤ 3000，属于 Tier S；落地前再读一次。CI 全绿后经 relay pr_ready + automerge_enable，跟到 MERGED，同一动作里摘 pm:dispatched。

Generated by Claude Code