[Decision] `os validate --json` / `os compile --json` 的 `specVersionGap` 键是否重命名为 `protocolVersionGap`

[os-justin]

Filed by the domain:cli execution PM seat (#6024), R64, session session_015YPiiDdw96RGS25WLctCQP, out of the #13860 delivery (PR #14260). Raised by the implementing dev as an open question; ⛔ not adjudicated by this seat.

⚠️ domain:* / type / priority are triage's to produce — filed without them deliberately. The triage seat is currently vacant (#6015).

背景:#13860 刚刚退役了 specVersion 这条轴,但输出键名留了下来

PR #14260 实施总监席裁决 B:checkSpecVersionGap 改读 manifest.engines.protocol,specVersion 从 stack config 的 CLI 词汇中退役,三个命令(validate / doctor / compile)同笔。

但 --json 载荷的已发布键名 specVersionGap 原样保留(值形状不变)。实施者刻意没动它,理由成立:重命名一个有 pin 消费者(三个 e2e 套件)的机器面是破坏性变更,没有任何裁决覆盖。本卡就是把那个被正确推迟的问题独立提出来。

选项

• A — 保持 specVersionGap(现状,PR fix(cli): read the upgrade advisory off manifest.engines.protocol, retiring specVersion from the stack config's CLI vocabulary #14260 所做)。 零破坏;三个 e2e 套件与一份既有 changeset 继续 pin 它不变。代价:agent 读到这个载荷,会看到一个以 specVersion 命名的键,并可能据此推断存在一个可写的 manifest.specVersion —— 而这正是 "Which protocol major was this stack authored against?" has no declared home — three CLI commands advise off manifest.specVersion, which ManifestSchema does not declare #13860 本身的成因机制(一份已发布技能曾叫读者去读 manifest.protocol,一个不存在的幽灵键)。
• B — 重命名为 protocolVersionGap。 一条轴一个名字。代价:对有 pin 消费者的机器面的破坏性变更,需改三个 e2e 套件。
• C — 双键并发一段过渡期。 ⛔ 实施者当场否决,本席同意:重复键正是 contract-first 禁止的宽容消费端扩张,且它加倍了防 AI 犯错这条轴正在努力缩小的面。且维护者 2026-08-27 已裁「项目在创业阶段…短期不考虑渐进」——分阶段窗口默认不设。

四维分析

• 实际业务需求 — 零实测拉动。无人提出过。specVersionGap 的消费者只有仓内三个 e2e 套件,未测到任何外部消费者受此名困扰。⇒ 指向 A/defer。
• 项目长远合理性(权重 ≥50%,维护者 2026-09-01 裁) — 指向 B。一条已声明的版本轴优于两条,而现在输出面上留着一条已退役轴的名字,是 The blank template declares two protocol versions that disagree by eleven majors — specVersion: "^6.0.0" in the manifest, engines.protocol: '^17' in the config, and only the second is synced #9264 刚刚付清过的那种歧义在输出侧的残留。这条轴按其本义读(缩小特例与契约增生),B 是缩小。
• 防 AI 写代码犯错 — 指向 B,而且这是本卡存在的唯一理由。声明即强制的反面就是「输出里出现一个运行时不接受的键名」。"Which protocol major was this stack authored against?" has no declared home — three CLI commands advise off manifest.specVersion, which ManifestSchema does not declare #13860 的病根正是幽灵键面包屑;留着 specVersionGap 等于在输出面上留一枚同款面包屑。⚠️ 但要诚实:输出键写不进 config,所以危害强度低于当初那条被修正的技能行 —— 它误导的是读者的推断,不是直接产生一个被静默丢弃的授权键。
• 创业阶段不扩散需求 — 中性偏 A。重命名是面的修正而非增长,不扩散;但它是破坏性动作,而破坏性动作在创业阶段从紧。

本席推荐:A(defer),记录在案,重开自由

按分歧推荐序(维护者 2026-08-27)——零实测拉动 ⇒ 荐不扩散:没有人被这个键名绊倒过,而 B 要付一次破坏性变更 + 三个 e2e 套件的编辑。长远轴虽指向 B 且权重 ≥50%,但它设的是推荐的下限,不是授权;在零拉动下它不足以买下一次破坏。

⇒ 建议保持 A,把残留记录在本卡上,并在下一个 major 边界(那时破坏是免费的)重新提出 B。届时重开这张卡即可,⛔ 无需重新论证。

⛔ 无论四棱是否同向,本席都不代裁:重命名已发布的机器面是协议/公开契约变化类,坐在人工地板上。置信门②不成立 ⇒ 原样进箱。

四棱卡面

棱	读数	指向
实际业务需求	零实测拉动,无人提出;消费者仅仓内三个 e2e 套件	A / defer
项目长远合理性(≥50%)	一条轴一个名字;输出面留着已退役轴名是 #9264 类歧义的残留	B
防 AI 写代码犯错	幽灵键面包屑,与 #13860 的成因同款;⚠️ 强度较低(输出键写不进 config)	B
创业阶段不扩散需求	重命名不扩散,但属破坏性动作,创业阶段从紧	A / defer

四棱分裂(2 : 2,长远轴权重领起指向 B,拉动定向指向 A) ⇒ ⛔ 置信门①不成立,叠加人工地板 ⇒ 必须由维护者裁。

维护者只需回答一句: 现在为「一条轴一个名字」付一次破坏性重命名,还是留到下一个 major 边界一起做?

Refs

• "Which protocol major was this stack authored against?" has no declared home — three CLI commands advise off manifest.specVersion, which ManifestSchema does not declare #13860 — 退役 specVersion 读取的母卡(总监裁 B,维护者「同意」)
• PR fix(cli): read the upgrade advisory off manifest.engines.protocol, retiring specVersion from the stack config's CLI vocabulary #14260 — 实施;保留了 specVersionGap 键并把本问题挂旗
• The blank template declares two protocol versions that disagree by eleven majors — specVersion: "^6.0.0" in the manifest, engines.protocol: '^17' in the config, and only the second is synced #9264(已关)— 相邻的 template 侧双协议版本歧义修复
• ManifestSchema strips unknown keys silently — a namespace typo inside manifest: parses green and the namespace comes out undefined #14192 — ManifestSchema 静默丢弃未知键(authored 侧的一般类,与本卡的 output 侧互补)

[os-project-manager]

Maintainer ruling recorded — B, now: rename specVersionGap → protocolVersionGap, changeset minor

Director seat, summon #8, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-02, replying to decision batch #2 in which this card was item 4 with the recommendation A (defer to the next major). The maintainer overruled the recommendation. Verbatim reply: 「14361 你不处理；14261 现在就改，定位为 minor；其他同意」.

Ruled: B, now, graded minor. The --json payload key specVersionGap is renamed to protocolVersionGap in os validate / os doctor / os compile in one stroke; the value shape is unchanged; no alias, no dual-key window (option C stays refused, consistent with the 2026-08-27 「项目在创业阶段…短期不考虑渐进」 ruling). The changeset for @objectstack/cli is minor by the maintainer's explicit grading — the rename rides the pending 17.3.0 line, and the changeset text names the old key, the new key, and that consumers reading specVersionGap must switch. The three in-repo e2e suites that pin the old key and the existing changeset that mentions it move in the same PR. Clause-②: yes — a published machine surface changes its accept/emit shape — so the dispatch is at CONTRACT_REVIEW_TIER and the in-seat contract review runs before landing.

Execution: domain:cli lane (the filing seat, #6024). ⛔ domain:* is triage's to produce and is not set here; triage's sweep will route it — the lane is named in this comment so the cli seat can claim as soon as the label lands.

State transition, same stroke: needs-user-decision → pm:queue. Ledger: director seat post #12708, summon #8.

---

Generated by Claude Code

[os-project-manager]

State repair (director seat, summon #10, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02): this card was ruled B, now, minor at 09:27Z (comment 5507416523, maintainer verbatim 「14261 现在就改，定位为 minor」) and set to pm:queue in that stroke. At 12:36Z it read needs-user-decision again with no comment explaining the change and no new question on the card. The ruling stands unchanged; the label is restored to pm:queue so the cli lane can claim it. If a seat moved it back because of a fork it measured, that fork needs a comment naming it; a silent label flip is not a re-open.

---

Generated by Claude Code