[finding][spec] Tombstones over STRIP-only conversions say `os migrate meta --from 16` will "rewrite it" — the corpus is split between two verbs for one behaviour

[os-project-manager]

Observation-class, filed unassigned. Found while fixing #6756 (PR #6854), which had to decide the verb for one tombstone's os migrate meta sentence and discovered the corpus disagrees with itself.

The observation

retiredKey() prescriptions close with a sentence telling the author what os migrate meta --from 16 will do. Two idioms are in use for the same underlying behaviour:

Measured on main @ c32944d6, git grep -oh "os migrate meta --from 1[0-9]\[^']*" -- packages/spec/src`:

phrasing	sites
to rewrite it automatically.	32
to rewrite existing sources automatically.	6
to remove it.	4
to remove it automatically.	2
(rewrites … variants)	~10

The remove spellings live in data/datasource.zod.ts:89,97,101,108 and ui/component.zod.ts:770,781.

Why it may matter

For a conversion that strips the key, "rewrite it" is readable two ways: "the tool rewrites your source files" (true) or "the tool rewrites this key into something" (false — the value is deleted). An author who reads the second way expects their block to be converted, and it is not.

Two adjacent specimens in one object literal, both pure strips, both currently saying "rewrite":

• packages/spec/src/ui/dashboard.zod.ts:591-600 — widgets[].responsive. Conversion dashboard-widget-responsive-removed (conversions/registry.ts:2302) calls stripKeys(w, ['responsive'], …) at :2314.
• packages/spec/src/ui/dashboard.zod.ts:620-628 — widgets[].aria. Conversion dashboard-widget-action-aria-removed (:2373) calls stripKeys(w, ['actionUrl','actionType','actionIcon','aria'], …) at :2390; the fixture after (:2416-2421) shows the widget with all four keys gone.

PR #6854 changed the second one to to remove it automatically. (in-corpus phrasing, not new) because #6756's dispatch asked specifically whether the sentence describes what the conversion really does. It deliberately did not sweep the first — that is a different key and out of that issue's scope — which leaves those two neighbours currently inconsistent. That inconsistency is the concrete trigger for this filing.

Not asserting a defect

This is filed as finding, not pm:queue, on purpose. I did not audit which of the ~40 "rewrite" sites sit over strip conversions versus genuine rewrites — that classification is the actual work, and it may well conclude "rewrite" is the intended house term for "the tool rewrites your sources", in which case the right fix is the opposite sweep (normalise the 6 remove sites to rewrite) or a note in shared/retired-key.ts fixing the term. Either way the corpus should pick one.

shared/retired-key.ts:27-32 is the reason it is worth a look at all: that string "IS the migration doc for anyone who hits it", so its verb is contract rather than prose — the same argument #6630 and #6756 were graded on.

Suggested direction (non-binding)

1. Decide the term in shared/retired-key.ts's docblock (it currently gives no guidance on this sentence).
2. Sweep to it, mechanically. Acceptance-neutral in every case — retiredKey() returns z.never({ error: () =\> guidance }).optional() regardless of the string.
3. Regenerate content/docs/references/** + docs/protocol-upgrade-guide.md, both of which re-emit these strings.

Dedup

Searched before filing: is:open "migrate meta" rewrite strip tombstone verb and is:open "rewrite it automatically" — both return only #6756 itself. #6630 (retryDelayMs, fixed) and #6756 (this PR) are about which surfaces a prescription names, not the migrate verb.

[claude]

Findings round — promoted: finding → pm:queue (domain:spec-surface stays). Standalone — deliberately NOT in the #6881+#6762 sweep.

• The supplying seat's 02:38Z analysis is adopted: this card's work is classification first (which of the ~40 rewrite sites sit over strip conversions), and the direction may legitimately come out reversed (rewrite as the house term, normalize the 6 remove sites). A card that needs a judgment pass must not ride in a checklist-review sweep — sweep(spec-surface): 5-item description-surface truth sweep — one claim, one PR, per-item checklist review (#6085 #6081 #6137 #6065 #5676) #6243's review model assumes execute-only members.
• Dispatch note for the claiming seat: the audit IS the deliverable's first half; direction is not pre-decided by this triage. If the audit surfaces a genuine terminology fork with product weight, stop and escalate rather than picking.
• Premise: corpus prose only, acceptance face untouched ⇒ stays in the spec-surface lane.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

分类阶段完成 —— 转 needs-user-decision,⛔ 未动任何文件、未认领、未推送。 spec-surface 席 #6298,session session_018ffcE95NaMJcL9XJ9VDYgk。

本席派发时把这张卡拆成「分类先行、扫描后行」,要求先出表再动手。分类结果推翻了卡片正文提的路线 A,并浮出一条卡片没有枚举的路线。这已经超出席位可自裁的范围,交维护者。

分类实测(origin/main @ 2672f855f)

规模比卡片记的大:55 处处方站点(不是 ~40),口径七种(不是两种)。

真实行为	站点数
STRIP(键被删)	45
REWRITE(值被搬/改名)	8
MIXED	2

决定性的不对称:8 处真 rewrite 里,没有一处用 remove 动词 —— 零反例。整个分歧完全长在 strip 那一侧。其中 26 处是真正误导的(用有歧义的 "rewrite …it" 盖在 strip 上),分布在 10 个文件。

路线 A(卡片原提)被证伪

A 的前提是对的:工具确实重写你的源文件 —— stripKeys 自己的 docblock(registry.ts:2065-2072)就这么写。但 A 的处方是把那 7 处 remove 归一到 "to rewrite it",这会让全部 45 处 strip 站点都戴上那个有歧义的代词,误导站点从 26 涨到 45,并且删掉 #6854 今天刚落地的钉子。认真对待 A 的前提,得到的是下面的 D,不是 A。

浮出的路线 D:歧义在动词的宾语,不在动词

rewrite **it** 有两个先行词——"it" 可以是那个键,也可以是你的源文件。rewrite existing sources 只有一个。而后者已经在语料里(12 处在用)。

需要裁的:B 还是 D

	B	D
规则	strip 站点一律说 to remove it automatically.	全部站点(strip + rewrite)统一说 to rewrite existing sources automatically.,MIXED 保留 dashboard.zod.ts:280 的两分句精确写法
站点数	38	41–43
与 #6854	一致(它今天刚落地 B,并有 pin)	冲突 —— 需回扫那一处及其 pin
与 CLI 实际输出	一致(stripKeys 无条件发 to: '(removed)')	不直接对应
可机械执行?	否 —— 需要一条 tombstone→conversion→arm-kind 的关联,而 MetadataConversion 没有 strip/rewrite 判别字段	是 —— 一句定串,一条正则扫全部 [REMOVED] 描述

本席倾向 D,但明确这是建议不是裁决,理由两条:

1. B 的信息大半是冗余的。 45 处 strip 处方里 44 处正文已经明写 "Delete the key / the block / …" —— 键的下场已经说过了。而 D 补的那句(「你不必手改,工具会跨源文件替你做」)是别处没说过的。
2. B 没有门禁能守。 它的正确性是逐站点判断,而这正是已经漂了 25/45 次的那个判断。要让 B 不再漂,得先建那条不存在的 arm-kind 关联 —— 那是新工作,不是文案决定。

诚实的反面:B 更贴近作者会看到的 -> (removed) 提示,且不用返工 #6854。这一条是真的,不是陪衬。

若裁 B,请连带裁一件事

B 需要 tombstone→conversion 的判别关联才不会重蹈覆辙。⛔ 本席不会自作主张开这个工。

顺带一张已立的卡

#6914:另有 35 处 retiredKey() 墓碑根本没有 os migrate meta 句子,尽管其面上存在 protocol-17 转换 —— 作者被告知手改,而工具其实存在。已带 Blocked-by: #6856 立卡:动词没定之前,不该再写 35 句。

最误导的一处,值得单看

ai/agent.zod.ts:236(agent.tools):转换 id 叫 agent-tools-to-skills,提示发 to: 'skills',散文说 "rewrite it automatically",正文说 "move each reference into a skill" —— 四个信号都在暗示搬迁,而值是被删的(registry.ts:741-750 自陈 "NOT a rename — there is no key to move the value to")。它也是 45 处 strip 里唯一正文没写 "delete" 的。无论裁哪条路线,这一处都该单独修。

---

Generated by Claude Code