Spec Property Retirement

Spec 属性退役(ADR-0049 enforce-or-remove)

被解析却不被强制执行的属性是静默 no-op;对安全或能力类属性,它是假合规 —— tool.permissions 承诺过一道没人强制的调用门,flow.active: false 从未停下过任何 flow。ADR-0049 说这样的属性必须被强制执行、标 experimental,或不存在。 本技能是第三条路:一次删除真正的代价是什么,按什么顺序付。

删掉键本身也许只占 5% 的工作。其余 95% 在于:一个键可以在 ~14 个地方被编写,而守 着每个地方的门禁是分别地、串行地失败的 —— 一个过期面遮住其余全部,于是你得到的 是 每个面一轮红构建,而不是一轮报出全部。

先读验证侧:packages/spec/liveness/README.md(裁定怎么得出、verifiedAt、为什么 preview renderer 不算消费者)与 AGENTS.md §"Touched packages/spec?"(八个生成产 物)。本文不重复它们。

0. 动手删之前:删除是正确的处置吗?

• 它是安全/能力形状的吗? 那么 ADR-0049 约束成立,惰性是缺陷不是债。 rls.enabled 曾是「证据错误的 live」而实际无人读取 —— disabled 的 policy 仍在贡献它的授权。那个键最后是被强制执行,不是被删除。功能存在时,强制 执行赢。
• 它是文档形状的吗? hook.label、hook.description、flow.description 没有运行时消费者,但被有意保留 —— 它们为下一个读者(按 ADR-0033,常是模 型)记录意图。把豁免写进台账 note,下次审计不再重审。良性展示元数据 (description、tags、icon)永远谈不上「误导」;不要标 authorWarn,也 不要退役它。
• 有已承诺的路线图吗? 那就是 experimental + .describe() 里的 [EXPERIMENTAL — not enforced] 标记,不是删除。
• 同 major 记账。 同一个未发布 major 里更早的 conversion 改名了你现在要删 的键,就吸收它:把改名折进删除,删掉改名条目。二者复合后效果不可观测,而 conversion 表的 fixture 不相交契约(§3)会因叠放而失败。先例: agent.knowledge 在发布前吞掉了 topics→sources 改名。
• 台账判它 live-elsewhere 吗? 本仓实测无消费者、姊妹仓真在强制执行的 键 —— 永不是删除候选。单读 dead 会批准一次删除,而它删掉的是姊妹仓某 道门的输入。该核的不是删除面,是它的佐证纪律:外仓指针、 evidenceScope: "cross-repo"、带日期的 verifiedAt、180 天过期 —— 四条由 packages/spec/scripts/liveness/elsewhere.mts 执行,出处见 README 的 live-elsewhere 一节。

1. 裁判是构建,不是台账

台账的 dead 裁定是删除的输入,不能替代构建自己的证明。它是一条带时间戳的声 明,代码在它底下双向移动(flow.status 与 action.undoable 都被低估过)。

所以:先尝试删除,让构建来裁。 #3896 收尾里,view.form.data 挂在工作清单上是 dead(「两个仓都没有 form 路径的读者」),而删除打断了 gen:schema —— defineForm 往每个 *.form.ts 写 data: { provider: 'schema', schemaId },metadata-protocol 把它喂给 metadata-admin 管线。正确的回应不是硬删:把台账条目改回 live、附真实 证据与 verifiedAt,收窄 conversion,钉上 non-warn。十四个键里有一个是这样被证伪的 —— 给它留预算。

两条推论:

• tsc 和门禁是你最好的清扫器。 retiredKey() 墓碑把键的类型定为 never,于 是 monorepo 里每个编写点都编译失败。examples/app-showcase 三处 template: true 里有两处是 grep 漏掉、墓碑找到的。让墓碑替你找调用者,再去人肉搜。
• grep 只能证明存在。 要证明不存在,要么手工闭合调用图(声明 → 注册 → accessor → 调用者),要么编写该属性并启动应用。见 README 的 "How to verify a claim without fooling yourself" —— 包括 macOS 上 git grep -E 不认 \b。

2. 分叉:走哪条删除路线(决定下游一切)

永不从非 strict schema 上裸删一个键:zod 会静默剥掉它,你只是用一个静默 no-op 换了 另一个(#2169 "Mark Done does nothing" 的形状)。

⚠ 台账纪律按路线是相反的 —— 两种失败也不对称

liveness 门禁走的是 schema 的 shape,逐个属性去 packages/spec/liveness/<type>.json 里查。retiredKey() 在那个 shape 里仍是一个属 性。因此:

现在两个方向都会红 CI,搞反了两边都很响:

• 删掉墓碑键的行,报 UNCLASSIFIED(#3896 清扫一次 14 个 —— 本节就是防它);
• 留着 strict 删除键的行,报 ORPHAN 行。

orphan 这条腿是新的(packages/spec/scripts/liveness/orphans.mts)。它落地之前这个方向从不失败 —— 门禁走 schema 再查行,键已离开 shape 的行根本不会被问到,原地腐烂。report 的 aria/performance 行就这样比它们的键多活了一整个 release,靠有人恰好读到那个文件 才手工删掉。你撞上 orphan 报错而属性确实还可编写时,要修的是 walk,不是行: walk 看不见的属性就是 ratchet 管不到的属性。

墓碑条目的 note 模板(house style 原文,如 liveness/action.json):

REMOVED <date> — tombstoned at the schema (retiredKey carries the prescription; authoring it is a tsc error and a parse error) and stripped from sources by the protocol-<N> conversion. The entry stays because retiredKey keeps the key in the walked shape (the rls.priority precedent); <what to do instead>.

⚠ 四张 ratchet 的可见性,按路线是相反的 —— 拿错对照就会判错

验收时最常问的一句是「四张 ratchet 零变化,正常吗?」。答案完全取决于你走的是哪条 路线,2026-08-03 一天内两种形态各实测到一例,正好互为对照:

为什么会这样:这四张 ratchet 记录的是导出面与 def 的存在性,不是 def 内部的取值 集合。枚举少一个 value,导出的名字、schema 的 key、def 的数量都没变,于是四张全都 一模一样。

后果是双向的,两边都很贵:

• 把「枚举值收窄」的零变化判成异常 → 白折腾,以为 agent 漏做了生成物;
• 把「整 def 删除」的零变化判成正常 → 放过一个根本没真正删掉的 def。

所以验收顺序是:先确定路线,再决定该期待什么读数,不要反过来用读数去猜路线。 整 def 删除还有一条自证信号:json-schema.manifest/(#5837 起按 category 分片)的 ratchet(#2978)会先开火,要求你有意删除对应的 manifest key;删完重跑,per-key ratchet 会自行判定 为 #4650 路径 3(def no longer emitted by this build)。这串输出本身就是路线的证据,留在 PR 里。

枚举值收窄既然对四张 ratchet 不可见,它的处方就只能挂在枚举自己的 error map 上、按 issue.input 分派(packages/spec/src/data/hook-body.zod.ts 的 HookBodyCapability,沿用 object.managedBy: 'system' 的先例)—— 三条路线里没有一条 适用于「def 存活、只少一个值」。

guidance 字符串怎么写

五条惯例,树上每个墓碑都遵守 —— 逐点判定归下面那个 pin 测试,不归这段散文:

1. 反引号包着的全限定键打头 —— `flow.errorHandling.fallbackNodeId`,不是裸尾段。
2. was removed in @objectstack/spec <version> (ADR-XXXX[ Dn]);#<n> 归 schema 注释,check:doc-authoring 把门。
3. 一个破折号从句讲它为何惰性或错误 —— "it never had an effect"、"no renderer ever read it"。
4. 祈使句修复:改名写 "use <replacement>" + "Rename the key; the value (…) is unchanged.";删除写 "Delete the key." + 真正生效的机制是什么。
5. Run `os migrate meta --from <N-1>` to list the mechanical edits for existing sources; apply them by hand. —— 命令重放链、打印机械修改清单,从不写 source 文件(#9591 的 in-place codemod 落地前恒 真)。 消息不点名 conversion id;conversion 由 CLI 命令引用。唯一允许的变体(按形状、不按站点): conversion 只覆盖值的一部分时,两从句形点名覆盖的部分 —— Run `os migrate meta --from <N-1>` to list the mechanical edits for the <X> case; <what the tool does with the rest>. (样板:ui/dashboard.zod.ts compareTo.offset)。守这两个形状的 pin 人群含本文件: packages/spec/src/shared/retired-key-migrate-sentence.test.ts。

这个字符串就是撞上它的人的迁移文档 —— 包括一次跳好几个 major、load-path conversion 已不再覆盖的那位。

3. 注册面(ADR-0087 D2/D3)—— 否则门禁拦你

scripts/build-schemas.ts 的门 (b) 会打红任何没按精确 ${defKey}:${name} 注册 进 RETIRED_KEYS_BY_MAJOR 的新墓碑键:墓碑只对撞上它的人可闻,而 spec-changes.json、生成的 upgrade guide 与 spec_changes MCP 工具才是主通道,不 注册它们就一直空着。

⚠ 这是两个独立义务,其中只有一个是字符串匹配。 registry 条目是门禁读的; conversion 是消费者跟的。两个都要写。

• 一条 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, copy-on-write —— 没命中就原样返回输入引用。
• 一条 RETIRED_KEYS_BY_MAJOR 条目,在 packages/spec/src/migrations/registry.ts —— 字面 '<defKey>:<name>',拼法照 authorable-surface/<category>.json(去掉 [RETIRED] 标),挂在本 major 下。 这就是门 (b) 按精确集合成员读的字符串;不做推断,也不从邻键辐射。门禁的失败输 出会打印该粘贴的那一行。⚠ 不要在墓碑落地前先加条目:点名一个还活着的键的 条目,会以「无人消费的注册」打红门 (b2)。 为什么要第二张表: #4659 之前门 (b) 拿键的叶名去比对每条已注册的 surface(endsWith('.' + name),全 major,def 忽略),于是 dashboard.aria 注册中了 ui/FormView:aria,protocol 11 的 flow.node.type 注册中了任意 .type(#4658)。对每个常见叶名,保证早已失效。 条目同时启动老化时钟(#5898): 门 (c) 读同一张表来决定这个墓碑的 authorable-surface/ 行何时可删(~两个 major),所以你把它写在哪个 major 下,时钟就从那个 release 数起。比这张表更老的退役是未申报的、因此不可删的 —— 没有东西能诚实地给它们定日期(叶匹配曾把 data/Index:type 的日期从一个不相干 的 flow.node.type 定到 major 11,而 baseline 文件自己的 git 历史始于 17.0.0-rc.0)。要删那类行,先考证它真实的 major、补条目、在 PR 里写明。 ⚠ 永不加一行你定不了日期的:这里的估计会被之后每个门当成事实读。
• surface 保持散文 —— 它不再被匹配。 按作者写元数据的方式写 (flow.nodes[].outputSchema),那也是 upgrade guide 打印的。多键 conversion 仍用恰好 ' / ' 连接子句(tool 清扫以来的 house style)。下游不再有任何东西 从它解析归属 —— 那个职责移给了上面的条目。#5898 起这对每个消费者都成立:门 (c) 的 aged-out tombstone 证明曾是最后一个叶匹配者,现在也读同一张精确键 表,再没有任何规则从 surface 解析归属。
• retiredFromLoadPath: true —— 退役恒真。两种论证,不可互换:对改名它意 味着「没有 alias 窗口,故意的」(拒绝由墓碑负责;条目存在是为了 spec-changes.json 与 os migrate meta 仍携带它);对默认值翻转它承重正 确性 —— 自动应用 field-required-notnull-explicit 的 loader 会把 NOT NULL 盖 到 17 时代编写的 required: true 上,静默恢复 ADR-0113 删掉的三重绑定。只有 migrate meta --from <old> 可以应用翻转 —— 在那里「这份 source 早于拆分」是 事实而不是猜测。
• 一步 D3 链,在 packages/spec/src/migrations/registry.ts —— 把 id 加进 MIGRATIONS_BY_MAJOR[N].conversionIds,扩写该步的 rationale。 conversion.toMajor 必须等于该步的 major。⚠ 没有东西直接断言「每个 conversion 都接进了某一步」,拼错的 id 在 replay 时被静默跳过; chain-replay 测试抓得到它,只因为没接线的 fixture 永远到不了自己的 after。 所以把那个测试的失败读作「没接线」,不是「transform 坏了」。
• fixture 必须不相交 —— 两重。 每个 fixture 都被整张表 replay,必须恰好等于 自己的 after,每条 notice 都归属自己的 id。before 保持最小、避开其它条目 的键(新的 objects[].fields fixture 不许带裸 required: true,否则 notNull conversion 在它上面开火)。第二重容易漏:retiredFromLoadPath 的 fixture 还必 须不被任何 live-window conversion 碰到,因为另有测试断言它以零 notice 走过 默认加载路径。这条不相交契约正是逼出同 major 吸收(§0)的东西。
• 幂等靠构造,不靠测试。 没有测试把 conversion replay 两遍。stripKeys 删 除天然幂等(if (!(key in next)) continue),renameKey 拒绝覆盖已存在的 canonical 值;默认值翻转不是幂等安全的,靠它自己的守卫加 retiredFromLoadPath。你的 transform 不属于这些形状,就自己证明幂等 —— CLI e2e(packages/cli/test/migrate-meta.e2e.test.ts)会 replay 迁移后的快照并断 言 applied 为空。
• 没有 source 可重写的响应面键,改注册成 SemanticMigration(D3 semantic[]),reason 与 acceptanceCriteria 非空 —— EnhancedApiError.fieldErrors 是成品示例。

4. 面清单

从上往下做;每一行背后都有一个门。

• Schema —— 墓碑或 strict 删除(§2),外加 schema 内注释:删了什么、真正生 效的机制是什么。
• 孤儿值 schema —— 一个键的 XxxConfigSchema 没有别的消费者就随它一起走 (PerformanceConfigSchema、AIKnowledgeSchema、ToolCategorySchema)。没有 消费者的导出 schema 会被发现它的人读成能力(#3950 先例)。这 —— 且只有这 —— 会动 api-surface/:那份快照打印的是类型引用,不是展开的 shape,对键级收 窄全盲(#3883 从 defineAction 的输入删了三个键,快照没动)。它的门还住在另 一个 workflow(TypeScript Type Check,不是 Check Generated Artifacts),读 的是构建出的 dist/*.d.ts。
• Conversion + 链步 + 精确键 RETIRED_KEYS_BY_MAJOR 条目(§3)。
• Liveness 台账 —— 按 §2 的路线表,带 verifiedAt。更新 README 的按类型行 连同计数(那张表狠狠漂过一次;用 README 里的 python 片段重新生成计数,不 要手改)。
• 生成 baseline —— pnpm --filter @objectstack/spec gen:schema 会动 authorable-surface/<category>.json(墓碑 → 一条新的 … [RETIRED] 行; strict 删除 → 该行消失,这是门 (a) 的绊线,所以同一个 PR 里有意删掉它)与 json-schema.manifest/<category>.json。#5837 起两者都按 category 分片 —— 门 禁把整个目录读成一个集合,退役流程不变;变的只是那一行住在哪个文件。然后 gen:spec-changes、gen:upgrade-guide、gen:api-surface、gen:docs。 「改了 X → 重新生成 Y」的表见 AGENTS.md。
• Forms —— 从 packages/spec/src/**/*.form.ts 剪掉 { field: '<key>' } 输 入。未强制能力的表单输入是假合规的 UI 半边。原位留一行注释。
• i18n bundle —— 剪掉表单输入会改变抽取出的标签:pnpm i18n:extract 重新生 成 packages/platform-objects/src/apps/translations/*.metadata-forms.generated.ts (merge 模式;退役是纯删除)。由 pnpm check:i18n 把门。
• CLI advisory lint —— packages/lint/src/lint-liveness-properties.ts 是台账驱动的,退役键会自动停止告警;更新它的测试去断言 non-warn(「strict parse 现在接管它们」)。
• Pin 测试 —— 一条阴性,断言处方本身 (.toThrow(/<key>.*removed.*use `<replacement>`/s) —— s 标志是 house style,因为消息跨行),一条阳性,对非 strict 剥除路径断言 not.toHaveProperty(key)。参考 packages/spec/src/ai/agent.test.ts:69-95。 ⭐ 缺席 pin 一律 tree-scoped,永不 file-scoped:file-scoped 只看得见作者想得 到的那个文件,漏网的恰是他不知道的引用(实测五处、三个包、两张卡,其中两处还 是删除之后新写的)。排除 **/CHANGELOG.md、.changeset/ 与 pin 自身,理由 写在旁边,⛔ 不建允许清单文件;⛔ 缺席断言不是陈旧提及,「修好它」即删掉守卫。 ⭐ 半径按包申报一次:CROSS_PACKAGE_TEST_INPUTS 写进 scripts/cross-package-test-inputs.mjs,并配 齐 turbo.json:声明 test:repo 脚本的包配 <pkg>#test:repo 且 <pkg>#test 不带根输入,否则配 <pkg>#test;分歧以 scripts/check-cross-package-test-inputs.mjs 为准。walk 降在循环变量上、门禁 点不出名字的 glob 另配 heldBy 证人。⛔ 半径未申报的 tree-scoped pin 不是完成的退役。
• Examples —— examples/app-showcase/** 必须停止编写该键。墓碑路线上 tsc 替你找齐。
• 已发布 skills —— 教这个键的 skills/*/SKILL.md(表格、defineX 示例) —— 由 check:skill-examples 与 check:skill-refs 把门。
• Docs —— content/docs/** 的散文、表格与代码块 —— 除了 content/docs/releases/,代码 PR 永不碰它(AGENTS.md Documentation Guardrails)。release notes 在发布时从 changesets + D2/D3 registry 集中编写,你的 changeset(下一项)才是通往它们的输入。content/docs/** 的其余部分:先 grep 键 名,再读周边文件 —— 被删的键会藏在离参考表三节远的一个 defineFlow 示例里。
• Changeset —— @objectstack/spec 用 major。AGENTS.md:breaking changeset 必须带 FROM → TO 映射与一行修复;它作为 npm 包里的 CHANGELOG.md 发出,是升级中的 agent 撞上墓碑报错后 grep 的东西。 样板是任一条活着的 .changeset/*-retired.md —— 抄它的 "The retirement kit:" 段。⚠ 并带上 ADR-0087 处置标记(AGENTS.md 的 changeset 一节; pnpm check:adr-0087-registration 把门)—— 退役正是它点名的那一类。
• check:generated 明确不跑的源码审计 —— 整组跑,永不单点。 它的输出会点名 它们;陷阱是跑了五个漏了第六个。咬退役的是 check:variant-docs:删掉一个 discriminated union 会孤儿化它的 variant/doc-ledger 条目(实测:条目比它的 union 多活了一轮复核),本地跳过则只在 CI 变红。
• packages/qa/dogfood 在退役的默认消费半径之内 —— 不只是 import 该 schema 的那些包。它持有 ADR-0058 D7 表达式面 conformance 台账 (test/expression-conformance.test.ts),删掉任何带表达式面的 schema 成员都 会搁浅一条 covers 条目("STALE covers — surface no longer in source",同一 个 PR,第二次漏)。推送前跑它的定向套件,不管你的 import 图怎么说。

更正(§1)也必须传播到上面每一行。 form.data 翻回 live 时,台账、conversion 与测试都改了 —— 但 release-notes 行与台账 README 行还写着它已删除,教作者去删一个 defineForm 会写的键。更正路径是没有人给它准备清单的那条;用这一份。

5. 把门禁跑到真能失败

pnpm --filter @objectstack/spec build            # REQUIRED first — 见 §6 的 dist 陷阱
pnpm --filter @objectstack/spec check:generated  # 一条命令跑齐,首个失败不挡住其余
pnpm check:i18n && pnpm --filter @objectstack/spec test

⛔ 永不手搓一份 check:* 名单逐个跑:手工配对是 AGENTS.md 明禁的,而一条命令一次 报全部过期产物,正是 CI 做不到的事。check:generated 的输出会点名它不跑的五个 纯源码审计 —— check:liveness、check:empty-state、check:skill-examples、 check:exported-any、check:dual-source-exports —— 它们没有生成器,那里的失败是 真发现、不是过期产物,按 §4 那一行整组另跑。

6. 各费过一轮红构建的陷阱

⚠️ 四个陷阱不写在这里,因为它们对每个 dev 都成立、锚点在别处:过期 dist 的假 红、管道吃掉退出码、串行门禁互相遮蔽、--check 是门而裸模式重写。锚点是 AGENTS.md 的「Touched packages/spec?」一节与 .claude/agents/os-dev.md 的「本地验证范围」; ⛔ 这里不留第二份拷贝。

• 截断的 grep 漏掉编写者。 | head -8 藏掉了 SKILL.md 的 defineSkill 示 例;examples/ 有三处 template: true,不是一处。先按上下文找文件,再进文件里 grep 键 —— 且把 tsc 和门禁当权威清扫器。
• 只改 conversion 的 summary 也会过期。 那个字符串被逐字抄进 spec-changes.json 的 to 字段与 upgrade guide 的表行,所以纯散文改动也要 gen:spec-changes + gen:upgrade-guide,和任何别的改动一样。