docs(skills): objectstack-data says what os migrate meta --from 16 does: lists the edits, --write applies the proven sites

[objectstack-fleet]

Fixes #22144

Clause-②: no

Two published lines in the objectstack-data skill said os migrate meta --from 16 strips the retired index keys type and partial ("to strip them automatically" at rules/indexing.md:31, "strips them" at SKILL.md:377). Neither was true of the tool: the default run writes no authored source file, and --write rewrites only the sites it can prove. Both lines now carry the house sentence. The closing enumeration of every os migrate meta sentence in skills/** is below; every other hit reads true and is left byte-for-byte alone.

Family: #22120 is landed (PR #22122, the upgrade skill) and #22123 is landed (PR #22145, the --from 10 example); this PR is the family's closing card. #9591 (PR #22142, spec lane) is referenced only: it moves the spec tombstones to the same sentence and holds the class pin.

The tool, re-taken on this tree (0aa5205228, cut from origin/main at 1e5d322c1e)

• packages/cli/src/commands/migrate/meta.ts:762-769, the flag declaration, verbatim:

  write: Flags.boolean({
    description:
      'Rewrite the authored source files in place for each mechanical change traced to one literal in one '
      + 'project file; every other change is listed with the reason it was not written. Never writes the '
      + 'manual (semantic) changes.',
    default: false,
    exclusive: ['stored'],
  }),

• packages/cli/src/utils/authored-source-codemod.ts (module header): --write writes a diff change only when its path leads, through the authored modules' syntax, to ONE object or array literal in ONE project file and the loaded value agrees with that literal; anything else is refused by a named reason and stays on the list for the author.

• packages/spec/src/migrations/registry.ts:79: export const MIGRATION_SUPPORT_FLOOR = 16; — applyMetaMigrations throws MigrationFloorError for any --from under it (meta.ts:713-716).

• packages/spec/src/conversions/registry.ts:3906: id: 'object-index-type-partial-removed' — the 16 → 17 step carries the conversion, so "lists the mechanical edits" is true of these two keys specifically, not only in general.

• House sentence (packages/spec/src/shared/retired-key.ts: "It must be TRUE of the tool"). The tombstones on main close with "Run os migrate meta --from 16 to list the mechanical edits for existing sources; apply them by hand." (packages/spec/src/data/object.zod.ts:558,567); PR fix(spec): the retirement sentence names --write: it applies the edits it can prove, you apply the rest #22142 moves that to "… --write applies the ones it can prove, and you apply the rest by hand."; the upgrade skill says "By default os migrate meta rewrites no source file" (skills/objectstack-upgrade/SKILL.md:153) and "--write … rewrite the proven sites in place" (:132). No third vocabulary is introduced here.

The two edits

skills/objectstack-data/rules/indexing.md:31-33 (headroom 1058 tokens before):

• before: "… run os migrate meta --from 16 to strip them automatically. What to do instead is the subject of "Access methods and partial indexes" below."
• after: "… run os migrate meta --from 16 to list the mechanical edits; --write applies the ones it can prove, and you apply the rest by hand. What to do instead is the subject of "Access methods and partial indexes" below."

skills/objectstack-data/SKILL.md:377-378 (ceiling 6128, headroom 0 before — the shortest form that stays true):

• before: "Both are now a tsc error and a parse error; os migrate meta --from 16 strips them. Access methods and partial predicates are database-layer migrations."
• after: "Both are now a tsc error and a parse error; os migrate meta --from 16 lists the edits; --write applies the ones it can prove, the rest by hand."

Token ratchet payment (node scripts/check-skills-token-ratchet.mjs, ceil(utf8 bytes / 4) per file)

The new sentence in SKILL.md costs 63 bytes over the old one. It is paid by deleting one clause the same section restates — never by re-wrapping, never by touching the ceiling:

• deleted (SKILL.md:377-378): "Access methods and partial predicates are database-layer migrations." (70 bytes with its leading space);
• where its content survives, same file: SKILL.md:387-388 "See rules/indexing.md for composite indexes, unique scope, and how to build partial / gin / gist indexes at the database layer." and SKILL.md:44 "Index Strategy (rules/indexing.md) — btree/gin/gist/fulltext, composite indexes, partial indexes"; and in rules/indexing.md § "Access methods and partial indexes", the section the retirement callout points at;
• net: 24512 → 24506 bytes, 6128 → 6127 tokens, headroom 0 → 1. The ceiling row in scripts/check-skills-token-ratchet.mjs is not touched (see Acceptance notes).

skills/** readings — lines, and tokens as the ratchet counts them

File	Before	After
skills/objectstack-data/SKILL.md	469 lines · 24512 bytes · 6128 tokens (ceiling 6128, headroom 0)	469 lines · 24506 bytes · 6127 tokens (headroom 1)
skills/objectstack-data/rules/indexing.md	229 lines · 8729 bytes · 2183 tokens (ceiling 3241)	230 lines · 8805 bytes · 2202 tokens
Whole package — every skills/**/SKILL.md summed	4408 lines · 210279 bytes	4408 lines · 210273 bytes
Whole shipped bundle — the ratchet's own "bundle total" line	154833 tokens (the gate run in a detached worktree at 1e5d322c1e)	154851 tokens (+18: −1 and +19)

No eval under skills/objectstack-data/evals/ quotes either sentence (grep -rn strip skills/objectstack-data/evals/ — 0 hits). Frontmatter untouched; check:skill-docs and check:skill-refs both report in sync.

Closing enumeration — every os migrate meta sentence in skills/**

git grep -n "os migrate meta" -- skills/ on 0aa5205228: 30 hits in 5 files (objectstack-data/SKILL.md 1, objectstack-data/rules/indexing.md 1, objectstack-upgrade/SKILL.md 21, objectstack-upgrade/evals/protocol-major-upgrade.json 5, objectstack-upgrade/references/examples-upgrade.md 2) — the same lines as on origin/main, since only the two data-skill lines moved. A widened git grep -n "migrate meta" -- skills/ adds one bare hit (objectstack-upgrade/SKILL.md:466), judged too. Three tests per hit: (a) the default run lists and writes no source; (b) --write rewrites only the provable sites; (c) --from N is at or above MIGRATION_SUPPORT_FLOOR (16). A line is changed only when it is false.

File:line	Sentence (abridged)	Reading	Changed?
objectstack-data/SKILL.md:377	"os migrate meta --from 16 strips them."	FALSE on (a) and (b): the default run strips nothing; --write strips only the proven sites	yes
objectstack-data/rules/indexing.md:31	"run os migrate meta --from 16 to strip them automatically."	FALSE on (a) and (b)	yes
objectstack-upgrade/SKILL.md:64-66	Quickstart: --from 16 --step, --from 16 --json, --from 16 --out …, under the comment "replay the chain (writes only --out; --write also rewrites the sites it can prove)"	true: (a) listing runs, --out is a snapshot and not a source; (b) stated; (c) 16	no
objectstack-upgrade/SKILL.md:74	"os migrate meta --from 17 --json — applied must be []"	true: the replay from the target major; (c) 17 ≥ 16	no
objectstack-upgrade/SKILL.md:103	"os migrate meta --from 16 replays every step in order … down to the chain's support floor, 16 today"	true: (c) the floor constant is 16	no
objectstack-upgrade/SKILL.md:124-133	"What os migrate meta actually does" and its command block (--out "write the canonicalized stack", --write "rewrite the proven sites in place")	true on (a), (b), (c)	no
objectstack-upgrade/SKILL.md:153	"By default os migrate meta rewrites no source file … --write rewrites in place each edit it can trace to one literal in one project file, lists every other with the reason …"	true: matches the flag description	no
objectstack-upgrade/SKILL.md:177-179	--stored preview, --stored --type … narrowing, --stored --apply --yes	true of the stored pass (write is exclusive: ['stored']; --apply is the only writer there)	no
objectstack-upgrade/SKILL.md:215	"os migrate meta --from N --json → .specChanges"	true: the JSON face carries specChanges (meta.ts:881,928); N is bounded by the floor sentence at :103	no
objectstack-upgrade/SKILL.md:313	"os migrate meta --from 16 --json" piped into node -e, reading .todos	true: (a) a listing run; todos is the key (meta.ts:459)	no
objectstack-upgrade/SKILL.md:404	"os migrate meta --from TARGET_MAJOR --json — applied must be []" (the placeholder is spelled out here)	true: (a); (c) by construction	no
objectstack-upgrade/SKILL.md:449	"os migrate meta --stored --json — 0 = every row canonical, 1 = work left"	true of the stored pass: read-only, exit 1 while rows are pending (storedMigrationClean)	no
objectstack-upgrade/SKILL.md:466	"migrate meta reports changes, but the files are unchanged — working as designed, the default run only lists — pass --write, or port the printed edits by hand"	true on (a) and (b)	no
objectstack-upgrade/evals/protocol-major-upgrade.json:7	"--step, --json, and --out … — the command rewrites nothing on disk, so port the printed edits into the sources"	true of the invoked forms (none carries --write; --out writes a new snapshot and rewrites no source)	no
objectstack-upgrade/evals/protocol-major-upgrade.json:10,20	must_contain token lists	not behaviour claims	no
objectstack-upgrade/evals/protocol-major-upgrade.json:17	"runs os migrate meta --from AUTHORED_MAJOR to attribute the site to its conversionId, ports requiredWhen …" (placeholder spelled out)	true: (a) the listing attributes; the port is by hand	no
objectstack-upgrade/evals/protocol-major-upgrade.json:37	"Replays os migrate meta --from 17 --json and reads applied … runs os migrate meta --stored (read-only) then --stored --apply --yes"	true on (a), (c), and of the stored pass	no
objectstack-upgrade/references/examples-upgrade.md:57	"Ported into sources from os migrate meta --out."	true: hand-ported from the snapshot	no
objectstack-upgrade/references/examples-upgrade.md:79	"os migrate meta --stored --apply — rows rehydrate correctly today; this makes it durable."	true of the stored pass	no

Local verification (tree 0aa5205228; every exit code captured before any pipe)

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (no paths; the tool took the changeset from the merge-base itself): 24 commands. Run after the final commit as one union with the tool's own loop idiom, recorded as cmd :: exit N, and reconciled: dispatch-gates --ran — "24 derived, 24 run, 0 NOT-MEASURED, 0 UNRUN". All 24 exit 0:

check-ci-filter-parity · check-closing-keyword-parity (+ --self-test) · check-comment-mask-corpus · check-doc-route-spelling --advisory (+ --self-test) · check-skills-token-ratchet (+ --self-test) · @objectstack/lint check:doc-formula-expressions · @objectstack/spec check:skill-docs · check:agent-test-spelling · check:corpus-claim-drift · check:cross-package-test-inputs · check:doc-authoring · check:driver-memory-census · check:gitlink-declared · check:nul-bytes · check:pm-governed-merges · check:refd-timer-probe · check:role-word · check:skill-compatibility · check:skill-frame-sync · check:skill-identifier-liveness · check:watch-hint-literal.

• check:doc-formula-expressions first answered exit 3 (PREREQUISITE NOT MET — @objectstack/formula and @objectstack/lint were unbuilt; nothing measured). After pnpm exec turbo run build --filter=@objectstack/formula --filter=@objectstack/lint --concurrency=2 behind scripts/pm/os-verify-lock.sh (VERDICT command-exit 0; held 92 s, waited 0 s) it exits 0.
• Also run, outside the derivation: pnpm --filter @objectstack/spec run check:skill-refs exit 0 ("9 generated files in sync"); pnpm check:skill-top-level-keys exit 0.
• NOT MEASURED locally, by design: the type-check lanes, the Test Core shards, the 11 wide-population families and the 51 roster families the derivation names are CI's; the 15 pending-changeset families do not apply (no changeset — this diff publishes nothing from any released package; label skip-changeset).

Reverse verification of the ratchet payment (one-off; committed first; scripts/ablation-replace.mjs)

• Attempt 1 was a no-op by the tool's own count check (the anchor was a substring of its replacement, anchor count 1 → 1): refused and restored, nothing measured.
• Attempt 2, re-anchored on "prove, the rest by hand." with the deleted clause re-added: mutation landed on disk (blob 7220a34363d3 → efe8f6825326); node scripts/check-skills-token-ratchet.mjs exit 1 — "skills/objectstack-data/SKILL.md is 6144 tokens; the ratchet ceiling is 6128 (over by 16)". Restore proven: blob == HEAD 7220a34363d3, git diff HEAD empty, git status --porcelain empty.

Acceptance notes

• The class pin packages/spec/src/shared/retired-key-migrate-sentence.test.ts (WITHDRAWN_CLAIM) matches only "to rewrite … automatically" and the "rewrites (it for you / existing sources / authored sources / your sources / your source files)" spellings — no "strip" — so it never saw these two lines, and nothing in this PR is implied to be covered by it. Widening it is spec-lane work and the file is held by PR fix(spec): the retirement sentence names --write: it applies the edits it can prove, you apply the rest #22142; it is not touched here. Carrier: the domain:spec seat, via the skills seat's relay.
• skills/objectstack-data/SKILL.md now sits 1 token under its unchanged 6128 ceiling. Lowering the ceiling to 6127 is legitimate per the gate's own header and outside this card's file surface. Carrier: the next PR that touches scripts/check-skills-token-ratchet.mjs, or the skills seat.
• Tier H (skills/**): this PR stays draft and lands on an authorized APPROVED review or the maintainer's hand; no seat flips it ready.

维护者速读(草稿)

改了什么:objectstack-data 技能里两句话(rules/indexing.md:31、SKILL.md:377)原本说 os migrate meta --from 16 会"自动剥掉"/"剥掉"已退役的索引键 type 和 partial。改成工具的真实行为:默认只列出机械修改;--write 只落它能证明的那些站点;其余由作者手工完成。顺带把 skills/** 里所有 os migrate meta 句子逐条核对了一遍(上表),其余均属实,一字未动。

为什么改:这是对外发布的技能包(npx skills add 原样装进客户项目),读到这句的 AI 作者会以为源码已被清理,把退役键留在原地,直到 tsc 或解析报错才发现。docs/NORTH-STAR.md 优先级第 4 条:发布面上的错句就是产品缺陷;retired-key.ts 的内部裁决是"这句话必须对工具为真"。

风险与代价(含回滚):纯文本改动,不碰代码、不碰 spec、不发包、无 changeset。SKILL.md 已顶在 token 上限,新句子靠删掉同一段里被下文重述的一句付账(内容仍在 SKILL.md:387-388 与 rules/indexing.md)。回滚 = revert 这一个提交。

席位意见:

你要做的:确认两句新措辞与 PR #22142 正在采用的 house sentence 一致;同意则 APPROVE,由席位落地。

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0aa5205228f83141189fcf67cb538976dcface60
Local-runs: none

Reviewed in-seat by the skills seat 1 (dispatching seat; this session is served at the contract-review tier, read off get_session), 2026-10-08T06:10Z. Face hit: governed rule text (skills/**, Tier H). Read-only shape held: the diff (get_files = 2 files, +5/−4), the card #22144 and its thread (triage's grade 6052701386, the claim 6053103099, the os-dev-report 6053505522), the head's check-runs; nothing built or run locally. Premises re-read on origin/main 13aea18959 (the branch cut at 1e5d322c1e; skills/objectstack-data/** untouched between them; merge-tree clean).

① Derived judgments

1. rules/indexing.md:31-33: "run os migrate meta --from 16 to strip them automatically" → "run os migrate meta --from 16 to list the mechanical edits; --write applies the ones it can prove, and you apply the rest by hand": correct. packages/cli/src/commands/migrate/meta.ts:762-769 declares write with default: false and the description "Rewrite the authored source files in place for each mechanical change traced to one literal in one project file; every other change is listed with the reason it was not written"; the sentence is the house wording PR fix(spec): the retirement sentence names --write: it applies the edits it can prove, you apply the rest #22142 (feat(cli): os migrate meta --write — the AST codemod that rewrites authored sources for the mechanical applied set (v18) #9591) moves the retirement sentence to, and the 16 → 17 step carries the object-index-type-partial-removed conversion (packages/spec/src/conversions/registry.ts), so "lists the mechanical edits" is true of exactly these keys. The surrounding sentence ("What to do instead is the subject of …") re-wrapped by the longer line — a wrap inside a changed paragraph, not a ratchet payment; indexing.md has 1039 tokens of headroom.
2. SKILL.md:377-378: "os migrate meta --from 16 strips them. Access methods and partial predicates are database-layer migrations." → "os migrate meta --from 16 lists the edits; --write applies the ones it can prove, the rest by hand.": correct, the shortest true form of the same claim; same three readings as item 1.
3. Ratchet payment in SKILL.md (ceiling 6128, headroom 0 before): the deleted clause "Access methods and partial predicates are database-layer migrations." survives in the same file — :44 (Index Strategy: "… composite indexes, partial indexes") and :388 ("how to build partial / gin / gist indexes at the database layer") — and in rules/indexing.md § "Access methods and partial indexes", which the sentence right beside the edit points the reader to. 6128 → 6127 tokens (headroom 1); content, not wrapping; no rule, failure row or command lost.
4. Closing enumeration (the card's "third member" direction): the dev's git grep -n "os migrate meta" -- skills/ on the head gives 30 hits in 5 files plus one bare migrate meta hit, each judged against the three tests (default lists and writes no source; --write only the provable sites; --from at or above the floor 16); the table in the PR body reads every hit outside the two as true and changes none. Seat control: the same grep on origin/main 13aea18959 gives the same 30 sites (the seat's own listing at the claim, 06:00Z, agrees line by line); the upgrade skill's :132, :153, :466 already state the default-lists / --write behaviour, so a wording churn there would have been wrong. Correct and complete.
5. No eval under skills/objectstack-data/evals/ quotes either sentence (dev grep for "strip": 0; seat's reading at the claim agrees). Frontmatter untouched; check:skill-docs "in sync" and check:skill-refs "9 generated files in sync" quoted from the head.
6. Nothing else in skills/** moves: get_files = the two files, +5/−4 (the 9-line count under the human-merge threshold).

② Semver level

None. Prose-only edits to published skill text; no package files[] content, no API, no schema. skip-changeset on the PR is the correct declaration for this repository (docs-only), applied by this seat after its own reading (the dev's write was refused by its session classifier, recorded in its report).

③ Boundary flags

• Dev flag (acceptance note): the class pin retired-key-migrate-sentence.test.ts (WITHDRAWN_CLAIM) has no "strip" spelling and never saw these lines; widening it is spec-lane work and the file is held by PR fix(spec): the retirement sentence names --write: it applies the edits it can prove, you apply the rest #22142 — answered: not this PR's; relayed by this seat to the domain:spec seat as a cross-lane memo on the seat posts (no card: the spec lane's open PR holds the file and its dev already read these lines).
• Dev flag: SKILL.md's ceiling could be lowered to 6127 — stays a note; outside the surface, legitimate but not owed.
• open_questions: none. premise_still_valid: true, with the flag declaration and the conversion id quoted as evidence.

Implemented-by: claude/issue-22144-data-skill-migrate-meta-sentences
Reviewed-by: session_01CXydFDyiQwNbGFkmwrcRQq

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

维护者速读(终稿)

席位:skills 席 1,session_01CXydFDyiQwNbGFkmwrcRQq,2026-10-08T06:20Z。对照席位自己读的 diff(head 0aa5205228,两个文件 +5/−4)校正 dev 草稿;契约复核记录(PASS)在本 PR 上一条评论,ACCEPT 在卡片 #22144。

改了什么:只改对外发布的 objectstack-data 技能里两句话。rules/indexing.md:31 原说"运行 os migrate meta --from 16 自动剥掉"已退役的索引键 type/partial,SKILL.md:377 原说"os migrate meta --from 16 会剥掉它们";现在都改成工具的真实行为:默认只列出机械修改,--write 只落它能证明的站点,其余由作者手工完成——与 spec 车道 PR #22142 正在采用的 house sentence、以及 upgrade 技能里已落地的 :153 同一措辞。SKILL.md 顶在 token 上限(6128/6128),新句靠删掉同段里一句下文已重述的话支付(内容仍在 :44、:388 与 rules/indexing.md 对应小节),6128 → 6127。顺带把 skills/** 里全部 30 处 os migrate meta 句子逐条按三条判据核了一遍(默认不写源码 / --write 只写可证明站点 / --from 不低于下限 16),其余均属实、一字未动,表在 PR 正文。

为什么改:技能包随 npx skills add 原样进客户项目;AI 作者读到"自动剥掉"会以为源码已清理、把退役键留在原地,直到 tsc 或解析报错。北极星优先级 4:发布面上的错句是产品缺陷;retired-key.ts 的内部裁决是"这句话必须对工具为真"。这是本家族(#22120、#22123、本卡)的收口卡。

风险与代价(含回滚):纯文本,不碰代码、不碰 spec、无 changeset(skip-changeset,docs-only)。棘轮:SKILL.md 6128 → 6127(上限 6128),rules/indexing.md 2183 → 2202(上限 3241);未折行凑数(indexing.md 的一处重排是同段落加长后的自然换行,余量 1039)。阳性对照:dev 把删掉的那句加回去,棘轮门禁即红(超 16 token),恢复后与 HEAD 字节一致。回滚 = revert 本 PR 的一个提交。

席位意见:同意合入,席内契约复核 PASS。两点备注、均未立卡:① 类 pin retired-key-migrate-sentence.test.ts 的 WITHDRAWN_CLAIM 正则没有 "strip" 拼法,所以它一直看不见这两句;加宽是 spec 车道的活,且该文件正被 PR #22142 持有,本 PR 不碰——本席以跨车道备忘转给 spec 席。② SKILL.md 的上限可顺手降到 6127,由下一个碰棘轮脚本的 PR 带走。

你要做的:用授权账号(os-zhuang 或 hotlong)在本 PR 上 APPROVE 一次,或亲手合入。PR 保持 draft;收到授权 APPROVED 后由本席落地并收口 #22144(若批准者已自行翻 ready 入队,本席只做收口)。

---

Generated by Claude Code