docs(skills): point spec-property-retirement at the split conversions layout (#30109)

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

<!-- claude-projects-attribution: {"github_login":"huangyiirene"} -->
_Requested by **Irene** · [project
thread](https://claude.ai/code/project/chan_01TJXtQ1tVD26ecLDZxFS67x?thread=cmsg_01TJXtQ1tVD26ecLDZxFS67x7awHcehzTyBghDMuazAhzx)_

Part of #29994

Clause-②: no
Metadata-protocol: none

The maintainer waived the model-tier mandate for governed rule text
while that tier had no quota; this PR was developed below it.

## 维护者速读

- 改了什么:`.claude/skills/spec-property-retirement/SKILL.md` §3 的两步改指
#29993 拆分后的布局。conversion 那步写明「单独一个模块
`conversions/entries/<toMajor>/<id>.ts`,按名 export;手写、无生成器的 `registry.ts`
加 import 与列表项」;18 步那句写明在 `MAJOR_18_CONVERSIONS` 按标识符插入 `{ conversion,
order }`,import 放在后继条目的 import 正上方。
- 为什么改:#29993 把 `conversions/registry.ts` 拆成每条一个模块后,技能仍教人在 `registry.ts`
里写 conversion 本体。
- 风险与回滚:只改内部技能文字(Tier S,不进 `@objectstack/skills`),行数仍 337(上限 337);回滚即
revert。
- 先看:L176-180 与 L216-217;以及为守行数上限删掉的 §4 L263 一行(见下)。
- 需要你做的:无。`.claude/**` 属 Tier S,由所属席位在合同评审记录与全绿检查之上经队列落地,不需要
`GOVERNED_APPROVERS` 批准。`registry.ts` 里 `MAJOR_18_CONVERSIONS` 头注的改写留在
#29994 上,归 spec 车道。

## What changes

`.claude/skills/spec-property-retirement/SKILL.md`, §3 (registration
surface):

- **The `MetadataConversion` step (L176-180).** It used to say the
conversion is written in `packages/spec/src/conversions/registry.ts`. It
now says each conversion is a module of its own at
`packages/spec/src/conversions/entries/<toMajor>/<id>.ts`, the file
named for the `id` and the conversion exported by name, and that
`registry.ts` gains its import and its list entry. It also says
`registry.ts` is hand-written, with no generator. The shared `stripKeys`
helper is now located at `entries/shared.ts`. The rest of the step (id
suffix, `emit` per key, `fixture.expectedNotices`, the walkers in
`walk.ts`, copy-on-write) is unchanged. These five lines were re-flowed
because their content changed; L181 is byte-identical.
- **The step-18 note in the D3 chain step (L216-217).** It used to say
"insert into `MAJOR_18_CONVERSIONS` sorted by identifier". It now names
the line, `{ conversion, order }`, inserted by identifier as the list's
header says, and where its import goes: directly above the import of the
entry that follows it. The header comment still speaks of the
*definition's* place; since the split, the merge test reads that place
as the import (`packages/spec/scripts/conversions-major18-merge.test.ts`
L25-31), so the line says so. L215 and L218 onward are byte-identical.

Read off `main` at `f68b47ca`: the layout of `conversions/entries/`, the
codemod `scripts/codemod-split-conversions-registry.mjs` (one-shot, not
a generator: `entries/<toMajor>/<id>.ts` read off the conversion's own
`id` literal), the `MAJOR_18_CONVERSIONS` header comment, and the merge
test's header. Unlike the migrations registry the step above describes
(`registry.ts.template` + `gen:migration-registry`, git-ignored output),
the conversions `registry.ts` is committed and hand-edited (the merge
test: "The file is hand-written, so nothing regenerates it").

**Line ceiling.** `check-skill-line-ratchet.mjs` pins this file at 337
lines with 0 headroom. The step-18 note grew by one line, which is paid
by deleting §4's L263 「「改了 X → 重新生成 Y」的表见 AGENTS.md。」. That is a
duplicate pointer: L33-35 already sends the reader to AGENTS.md
§"Touched `packages/spec`?", which is where that table lives (AGENTS.md
L650-665), and L330 points there again. No line was re-wrapped to make
room.

**Changeset.** `node scripts/check-empty-changeset.mjs --base
origin/main` exits 0 with no changeset. The diff is `.claude/**` only
and releases nothing, so this PR takes `skip-changeset`
(pr-automation.yml route 2).

## Why

PR #29993 (#29987) split `conversions/registry.ts` into per-entry
modules and filed this follow-up in its body: the skill still tells devs
to write a new conversion inside `registry.ts`.

## Verification

Head `22e2202b`, two commits on `f68b47ca`: `68373420` (the edit) and
`22e2202b` (review S1: L177 names both `registry.ts` lines, 「加 import
与列表项」, 119 bytes, line count unchanged).

<details><summary>Local gates on 22e2202: 19 derived, 19 run with exit
0, 0 NOT MEASURED (`dispatch-gates --ran`)</summary>

- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 19 commands for the one changed
file. All ran after `pnpm install --frozen-lockfile` and a `turbo run
build` of `@objectstack/formula`, `@objectstack/lint` and
`@objectstack/objectql` (both exit 0, on the first head; the S1 re-run
reused that tree), each under a 900 s timeout with its exit code
captured before any pipe.
- All 19 exited 0, among them `check-comment-mask-corpus.mjs`,
`check:pm-skill-ratchet`, `check:skill-frame-sync`,
`check:doc-authoring`, `check:cross-package-test-inputs` and
`check:ci-filter-parity`.
- The artifact rosters `pnpm check:pm-settings-deny-roster` (roster
under `.claude`) and `pnpm check:pm-governed-prose` both exited 0.
- `packages/spec/src/shared/retired-key-migrate-sentence.test.ts`, which
reads this SKILL.md: 15 of 15 passed.
- `node scripts/pm/check-skill-line-ratchet.mjs`: exit 0 (337 lines,
ceiling 337).
- `--ran` printed: `19 derived famil(ies) accounted for — 19 run, 0
NOT-MEASURED`.
- `node scripts/check-empty-changeset.mjs --base origin/main` and `node
scripts/check-commit-card-trailers.mjs --range origin/main..HEAD`: exit
0.

</details>

## Human Minimum

- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(Not touched.)
- [x] 2. Every name I added uses the casing for its kind. (No names
added.)
- [x] 3. No formatter ran.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset. (Publishes
nothing: `.claude/**` only; `skip-changeset`.)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (Not touched.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English. (The 维护者速读 section and
the skill text are Chinese, as the file is.)
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01J8VVAnsgwGBowbBtYDCHyu

---------

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

Author: objectstack-fleet[bot]

.claude/skills/spec-property-retirement/SKILL.md

@@ -173,11 +173,11 @@ conversion 已不再覆盖的那位。
 ⚠ **这是三个独立义务,其中只有一个是字符串匹配。** registry 条目是门禁读的;
 conversion 是消费者跟的;D3 条目是升级方的 agent 读的。三个都要写。
 
-- [ ] **一条 `MetadataConversion`**,在 `packages/spec/src/conversions/registry.ts`:
-      kebab-case 的 `id` 以 `-removed` 结尾、`toMajor`、每键一条
-      `emit({ from, to: '(removed)', path })`(用共享的 `stripKeys` helper),以及一
-      个 `fixture`,其 `expectedNotices` 等于**键**数,不是条目数。walker
-      (`mapCollection`、`mapFlowNodes`、`renameKey`)住在 `conversions/walk.ts`,
+- [ ] **一条 `MetadataConversion`**,单独一个模块 `packages/spec/src/conversions/entries/<toMajor>/<id>.ts`
+      (文件名即 `id`,按名 `export`);手写、无生成器的 `conversions/registry.ts` 加 import 与列表项。
+      kebab-case 的 `id` 以 `-removed` 结尾、`toMajor`、每键一条 `emit({ from, to: '(removed)', path })`
+      (共享的 `stripKeys` 住 `entries/shared.ts`),以及一个 `fixture`,其 `expectedNotices` 等于**键**数,
+      不是条目数。walker(`mapCollection`、`mapFlowNodes`、`renameKey`)住在 `conversions/walk.ts`,
       copy-on-write —— 没命中就原样返回输入引用。
 - [ ] **一条 `RETIRED_KEYS_BY_MAJOR` 条目**,在 `packages/spec/src/migrations/entries/retired-keys/`
       加一个文件(命名见 `entries/README.md`),再跑 `pnpm --filter @objectstack/spec gen:migration-registry`
@@ -213,7 +213,8 @@ conversion 是消费者跟的;D3 条目是升级方的 agent 读的。三个都
 - [ ] **一步 D3 链**,在 `packages/spec/src/migrations/registry.ts.template`(`registry.ts` 由
       `gen:migration-registry` 从它与 `entries/` 整文件生成并被 git 忽略,在 `registry.ts` 里手改不会
       进提交);`conversion.toMajor` **必须等于**该步的 major。**18 步**:conversion 只进
-      `conversions/registry.ts` 的 `MAJOR_18_CONVERSIONS`,照其头注按标识符排序插入,本步 `conversionIds`
+      `conversions/registry.ts` 的 `MAJOR_18_CONVERSIONS`:照其头注按标识符插入 `{ conversion, order }`;
+      其 import 插在后继条目的 import 正上方(头注的「定义」拆分后即 import),本步 `conversionIds`
       由它派生;`rationale` 只加一个 `STEP18_RATIONALE` 片段,按其头注插在你 D3 semantic id 的排序
       位;尾部追加被两处头注点名的 merge 测试拒收。
       **更早的步**:id 加进 `MIGRATIONS_BY_MAJOR[N].conversionIds`,扩写该步 `rationale`。⚠ 没有东西
@@ -260,7 +261,6 @@ conversion 是消费者跟的;D3 条目是升级方的 agent 读的。三个都
       `json-schema.manifest/<category>.json`。#5837 起两者都按 category 分片 —— 门
       禁把整个目录读成一个集合,退役流程不变;变的只是那一行住在哪个文件。然后
       `gen:api-surface`、`gen:docs`;新条目跑 `gen:migration-registry`;D4 投影不提交,本地不重生成。
-      「改了 X → 重新生成 Y」的表见 AGENTS.md。
 - [ ] **Forms** —— 从 `packages/spec/src/**/*.form.ts` 剪掉 `{ field: '<key>' }` 输
       入。未强制能力的表单输入是假合规的 UI 半边。原位留一行注释。
 - [ ] **i18n bundle** —— 剪掉表单输入会改变抽取出的标签:`pnpm i18n:extract` 重新生