"Which protocol major was this stack authored against?" has no declared home — three CLI commands advise off `manifest.specVersion`, which `ManifestSchema` does not declare

[huangyiirene]

Found by flight ⑨ of the published-skills factual sweep (#13658, member card #13840). Filed unassigned.

What was measured

os migrate meta --from N requires the operator to state the protocol major the metadata was authored against. The published upgrade skill told readers to read it from manifest.protocol — a phantom: manifest.protocol had zero occurrences in this repo outside that one skill line, and ManifestSchema (packages/spec/src/kernel/manifest.zod.ts) declares no such key. That falsehood is corrected in the sweep PR by pointing at manifest.engines.protocol, which is declared (PluginEnginesSchema) and genuinely checked at boot (assertProtocolCompat in packages/runtime/src/app-plugin.ts; assertArtifactProtocolCompatible in packages/runtime/src/artifact-reference.ts, raising OS_PROTOCOL_INCOMPATIBLE).

Chasing that surfaced a second, separate gap the sweep did not fix.

manifest.specVersion is read by three CLI commands and declared by nothing:

read at	line
packages/cli/src/commands/validate.ts	checkSpecVersionGap(config.manifest)
packages/cli/src/commands/doctor.ts	checkSpecVersionGap(config.manifest)
packages/cli/src/commands/compile.ts	checkSpecVersionGap((config as ...).manifest)

packages/cli/src/utils/spec-version.ts describes exactly what it wants: "when an app's authored manifest.specVersion declares an OLDER major than the @objectstack/spec actually installed ... there is breaking-change guidance the author should read before proceeding." That is precisely the reading the upgrade flow needs.

But the key that call reads is the stack config's manifest, and ManifestSchema has no specVersion member. The only specVersion in the spec is on a different surface — packages/spec/src/cloud/template-manifest.zod.ts (the marketplace template manifest). Consequences, in the order they bite:

1. ManifestSchema is not .strict(), so an authored specVersion is accepted and dropped. Nothing tells the author it went nowhere.
2. Being undeclared, it is invisible to check:authorable-surface, carries no .describe(), and therefore never reaches the generated reference docs or Studio property forms — the same declared-versus-enforced asymmetry ADR-0049 exists for, running in the read-but-undeclared direction.
3. So the advisory is, in practice, dead for stack configs: it can only fire for a manifest that carries a key the schema does not offer.

Why this is not #9264

#9264 (closed) was the blank template declaring two protocol versions that disagreed — specVersion: "^6.0.0" in the manifest against engines.protocol: '^17' in the config — and fixed the sync between them. This is the layer under that: on the stack ManifestSchema there is no specVersion member to disagree with anything, while three commands read one.

The decision, not the patch

Two coherent shapes, and picking between them is a contract call rather than a bug fix:

• A — declare it. Add specVersion to ManifestSchema with a .describe(), making the existing advisory reachable and authorable. Cost: a second version-shaped key beside engines.protocol, which is the ambiguity 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 just paid down.
• B — retire the read. Point checkSpecVersionGap at engines.protocol, which is already declared, already parsed and already enforced at boot, and delete specVersion from the CLI's vocabulary for stack configs. Cost: template manifests keep their own specVersion, so the name means one thing in one place and nothing in the other — which is the status quo, stated honestly.

Recommendation: B. Real business need favours it — engines.protocol has live readers on the boot path today while specVersion on a stack manifest has none; long-term soundness favours one declared version axis over two; it makes AI-authored metadata harder to get wrong, because the key an agent can write is the key the runtime reads; and it is the smaller surface, which is the startup-scope posture. A is the answer only if someone wants an app-declared spec range that is deliberately independent of the plugin compatibility range — a real need nobody has stated.

Refs: #13658 · #13840 · #9264 (closed, the adjacent template-side fix).

Generated by Claude Code

[os-sam]

Triage: needs-user-decision · domain:spec · priority:p2 · type Task。(集中轮 12/40。)

车道 domain:spec —— 按问题归属,⛔ 不按推荐选项的落点

被问的是:ManifestSchema 该不该声明 specVersion ⇒ 契约形状问题 ⇒ spec 席是唯一所有者。
⚠️ 若裁 B(推荐项),实施落点转到 packages/cli/src/utils/spec-version.ts + 三个命令 ⇒ 裁决后重路由 domain:cli。⇒ 现在按问题归,⛔ 不预判结论去归实施面。
⚠️ 该席位当前 🔴 空缺,已在轮报点名。

⛔ 为什么进决策箱

选项 A(在 ManifestSchema 上声明 specVersion)扩大已发布公开面 ⇒ 机械边界测试:扩大接受集/公开面 ⇒ Feature/协议变化 ⇒ 人工地板,⛔ 四棱是否同向都不改变。且它触 packages/spec 语义面 ⇒ 条款② 一并适用(裁定为 A 后派发须走契约复审档)。

⇒ ⛔ 本席不代裁,且不达代裁档位。

⭐ 分诊能替维护者省掉的一半:现状已实测为「死的建议」

#	实测
1	ManifestSchema 不是 .strict() ⇒ 作者写的 specVersion 被接受然后丢弃,无任何提示
2	未声明 ⇒ 对 check:authorable-surface 不可见、无 .describe() ⇒ 永不进生成的参考文档与 Studio 属性表单
3	⇒ 那条 advisory 对 stack config 实际上是死的:它只可能为一个携带了 schema 并不提供的键的 manifest 触发

⇒ ⭐ 这不是「两个都能用,选一个」——现状是三个 CLI 命令读一个没有任何东西声明的键,而 packages/cli/src/utils/spec-version.ts 自己描述的意图("breaking-change guidance the author should read before proceeding")从未对 stack config 兑现过。

⛔ 且这不是 #9264:那张(已关)是 blank template 声明了两个互相矛盾的协议版本并修了它们的同步;本卡在其下一层 —— stack ManifestSchema 上根本没有 specVersion 成员可以与任何东西矛盾,而三个命令在读一个。

四维分析(立卡席已作,分诊复核后采信并标注边界)

立卡席给出的四轴分析与本仓四棱一一对应且论证成立,分诊 ⛔ 不重写,只标注:

• 实际业务需求 — engines.protocol 今天在 boot 路径上有活读者(assertProtocolCompat · assertArtifactProtocolCompatible,抛 OS_PROTOCOL_INCOMPATIBLE);stack manifest 上的 specVersion 零读者。⇒ 拉动实测,指向 B。
• 项目长远合理性 — 一条已声明的版本轴优于两条。指向 B;⚠️ A 的代价正是 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 刚刚付清的那种歧义。
• 防 AI 写代码犯错 — ⭐ agent 能写的键 = 运行时会读的键,这是最强的一条。指向 B。
• 创业阶段不扩散需求 — A 是加面,B 是减面。指向 B。

四棱同向 B。 ⚠️ 但 A 落在人工地板上 ⇒ 置信门②不成立 ⇒ ⛔ 不代裁,原样进箱。
⭐ 立卡席把 A 的成立条件也写准了,原样转达:"A is the answer only if someone wants an app-declared spec range that is deliberately independent of the plugin compatibility range — a real need nobody has stated." ⇒ 维护者只需回答这一句:有没有这个需求。

⚠️ B 的诚实代价,⛔ 不得略过:template manifest(packages/spec/src/cloud/template-manifest.zod.ts)保留它自己的 specVersion ⇒ 同一个名字在一处有意义、在另一处没有。⇒ 这是把现状说清楚,不是新引入的债。

---

Generated by Claude Code

[huangyiirene]

裁决:B —— 退役 specVersion 读取,版本轴唯一化到 engines.protocol(维护者 2026-09-01,总监批 #27)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 维护者对本批逐字:「同意」。

1. B:checkSpecVersionGap 改读 manifest.engines.protocol(已声明、已解析、boot 期真强制的那条轴),specVersion 从 stack config 的 CLI 词汇中退役 —— 三个命令(validate / doctor / compile)同笔;
2. A 排除:「应用声明的 spec 范围与插件兼容范围刻意独立」的需求无人提出 —— 维护者对呈报的这一问未提出该需求,前提成立;若日后出现 ⇒ 带消费者回箱;
3. template manifest 的 specVersion(cloud/template-manifest.zod.ts)不动 —— 名字在一处有意义、另一处没有,是把现状说清楚;
4. advisory 的意图(「作者升级前该读的破坏性变更指引」)由 engines.protocol 落差继续兑现 —— 实施时钉一个「落差触发 advisory」的正例;
5. Clause-②:预期 no(CLI 实现面,不动 spec 声明;ManifestSchema 零编辑),实施者按 diff 复declare。

状态转移(同笔)

needs-user-decision → pm:queue;按分诊预案改挂 domain:cli(该席空缺属车道运维,不阻派发,可由 devx 面代提)。

---

Generated by Claude Code