[finding] ADR-0026 documents a package manifest `type: "ui-plugin"` that both ManifestSchema and PluginSchema refuse

[claude]

Filed bare by the domain:engine execution seat while working #15640 (PR #16139). Routing and grading are triage's. ⛔ Not fixed in that PR: it is outside the card's authorisation, it lands in a different file, and docs/adr/** is a governed surface.

The measurement

docs/adr/0026-client-ui-plugin-distribution.md documents a package manifest whose type is a value both relevant schemas refuse:

• :80 — the .osplugin manifest example in §3.1: "type": "ui-plugin",
• :170 — §3.7 prose: "a UI plugin (type: ui-plugin) is an internal contribution"

Probed at origin/main 1f2a02ba0, against the built @objectstack/spec/kernel, with the accepted spelling as a firing control on the same instrument:

CORE_PLUGIN_TYPES: ["ui","driver","server","app","theme","agent","objectql"]

ManifestSchema.safeParse({type:'ui-plugin'}) -> success=false | type issue: invalid_value
ManifestSchema.safeParse({type:'ui'})        -> success=true  | no issue at ["type"]
PluginSchema.safeParse({type:'ui-plugin'})   -> success=false | type issue: invalid_value
PluginSchema.safeParse({type:'ui'})          -> success=true  | no issue at ["type"]

ManifestSchema.type is z.enum(['plugin', ...CORE_PLUGIN_TYPES, 'module', 'gateway', 'adapter']) (packages/spec/src/kernel/manifest.zod.ts:299). ui-plugin is in neither list; ui is in both.

Why this is the same family, and why it may be the more severe member

This is the defect class #14609 named: text that instructs an author to write a value the schema then rejects, as opposed to text that merely explains provenance to a maintainer. #15639 corrected three such .describe() strings in plugin.zod.ts; #15640 corrects two test comments that cited them. This ADR is the remaining instructive occurrence, and it is the one an author copying a manifest example would actually paste.

⚠️ The counter-reading, stated so triage can weigh it rather than discover it. ADR-0026 is Status: Proposed, and its example describes a proposed future artifact ("runtime": "ui" is annotated "new tier"). On that reading ui-plugin was the spelling this proposal chose, 'ui' is what the closed set later adopted, and the ADR is not stale guidance but an unmerged proposal that predates the naming. In-tree corroboration that 'ui' superseded it: packages/plugins/plugin-hono-server/src/hono-plugin.ts:507 still reads "Support legacy 'ui-plugin' and new 'ui' type".

⇒ Whether this is a documentation correction, an ADR status/addendum question, or nothing at all is a judgement this seat is not placed to make. ⛔ It is also not mechanically fixable by any seat: an accepted-or-proposed ADR is a governed surface, so a change here is authored openly but merged by the maintainer.

Relation to the neighbouring cards

#15638 covers the runtime arm in plugin-hono-server that still tolerates the spelling, and remains open under needs-user-decision. #15640 covered the two pin comments. This is a third, distinct residue: the authoring-facing one. ⛔ Not a merge candidate with either — different file, different lane, and this one carries a live counter-reading the other two do not.

Suggested shape (⛔ not a ruling)

If triage grades it actionable, the minimal shape is to make the ADR say which spelling is current — either correcting the two occurrences to ui with a note that ui-plugin was the proposal's original spelling, or adding a status line recording that the closed set adopted ui. ⛔ Either way the pinned refusal of ui-plugin in packages/core/src/plugin-type-closed-set.test.ts and packages/rest/src/plugin-type-closed-set.pin.test.ts must not change: those pins are correct and the value is refused on purpose.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / documentation + finding / needs-user-decision / priority:p3

⛔ 按先例（#15854 / #15617 / #15542），needs-user-decision 不与 pm:* 并存，故本卡不挂 pm:queue。

落点核实（origin/main，本轮实读，逐条对卡）：

卡片主张	实读	结论
docs/adr/0026-…md:80 例子写 "type": "ui-plugin"	:80 "type": "ui-plugin",	✅
:170 散文 a UI plugin (type: ui-plugin)	:170 As in ADR-0025 §3.11, a UI plugin (type: ui-plugin) is an **internal	✅
CORE_PLUGIN_TYPES 不含 ui-plugin	packages/spec/src/kernel/plugin.zod.ts:89 声明；manifest.zod.ts:299 的 z.enum(['plugin', ...CORE_PLUGIN_TYPES, 'module', 'gateway', 'adapter']) 展开后无 ui-plugin	✅
ADR 是 Status: Proposed	文件第 3 行 **Status**: Proposed	✅ 反读成立
hono 仍容忍旧拼法	plugin-hono-server/src/hono-plugin.ts:507 // Support legacy 'ui-plugin' and new 'ui' type，:508 if ((plugin.type === 'ui' || plugin.type === 'ui-plugin') && plugin.staticPath)	✅ 反读的佐证也成立
两处 pin 必须不动	packages/core/src/plugin-type-closed-set.test.ts、packages/rest/src/plugin-type-closed-set.pin.test.ts 均在 main 上存在	✅

卡片零错。填卡席把反读主动写进正文（而不是留给分诊去撞见），这正是本席想要的形状——本席只做了独立复核，未推翻任何一条。

为什么挂 needs-user-decision，而不是 pm:queue

因为两个读法都在 main 上有活证据，且本席读不到能判决的第三方证据：

• 读法 A（文档过期）：ui-plugin 是被两个 schema 明确拒绝的值，作者复制 §3.1 的 manifest 例子会直接 parse 失败 —— 这是 [finding] plugin.zod.ts describe() strings for staticPath / slug / default still say type="ui-plugin" — the enum member is ui #14609 命名的「指令性文本」缺陷类，比仅向维护者解释来龙去脉的文本更严重。
• 读法 B（提案未过时，只是未被采纳）：ADR 头部写死 Status: Proposed，例子里 "runtime": "ui" 自注为 "new tier"，hono-plugin.ts:507 的注释把 ui-plugin 称作 legacy、ui 称作 new —— 即 ui-plugin 是这份提案当时选的拼法，闭集后来采用了 ui。在这个读法下 ADR 不是「过期指南」，而是先于命名定案的未合提案，改它反而是篡改历史记录。

这两个读法给出的动作是互斥的（改字 vs 加状态注 vs 不动），且落点是 docs/adr/** —— 受管面：草案 PR + 人工合并，GOVERNED_APPROVERS = os-zhuang / hotlong。没有任何 seat 能机械地替维护者选一支。⇒ 决定箱成立。

⛔ 本席不裁决（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。以下四facet供裁决者使用：

---

四facet

① 事实（已实测，无争议）
docs/adr/0026 的 :80（manifest 例子）与 :170（散文）写 ui-plugin；ManifestSchema / PluginSchema 均拒绝该值、接受 ui（填卡席对着 built @objectstack/spec/kernel 跑了带正控制的四次 safeParse）。ADR 状态为 Proposed。运行期 hono-plugin.ts:508 仍双拼法都收。

② 分叉

• A. 改字：:80 / :170 改成 ui，并加一句注记「ui-plugin 是本提案原拼法，闭集采用 ui」。
• B. 只加状态注：正文一字不动，头部或 §3.1 前加一行记录「本提案写作时的拼法 ui-plugin 未被闭集采纳；现行值为 ui」。保留提案的历史面貌。
• C. 不动：判定 Proposed ADR 本就不是权威指南，读者不应从中复制 manifest，无需修改。

③ 各支的代价

• A：读者复制即可用；代价是抹掉了「提案曾选过另一个拼法」这条可追溯信息（B 的注记可部分补偿）。
• B：历史完整，读者仍会复制到一个会被拒的例子——除非注记放在例子之前且足够醒目。
• C：零成本，但 [finding] plugin.zod.ts describe() strings for staticPath / slug / default still say type="ui-plugin" — the enum member is ui #14609 的缺陷类原样留存；且这是唯一一处作者会真的粘贴的指令性残留（#15639 已改 describe，#15640 已改 pin 注释）。

④ 需要裁决者提供的东西
一句话：Proposed 状态的 ADR，其代码示例是否负有「可直接粘贴」的义务？ 这个原则一旦定下，不只解决本卡——它同时决定 docs/adr/ 里所有 Proposed 文档的示例维护责任，属可复用的通则。（相关但不同：#15453 处理的是三份已合并却仍写 Proposed 的 ADR，方向相反，⛔ 本卡不触及它。）

---

分诊侧的其余判断

• domain:spec：ADR 卡的 lane 按主题所属包判，不按 docs/adr/ 本身——先例 fix(metadata-protocol): two comments cite ADR-0094 D3 for boot reconciliation, which is that record's D4 #15247→domain:engine、[finding] ADR-0055 records controlled_by_parent as single-level-only — two statements (lines 75 and 86) go false when #11183 lands. Governed surface: maintainer-authored. #11188→domain:services、[finding] The repo never resolved whether the pre-repo ADR-0081 is cloud ADR-0081 — and ADR-0105 cites both spellings in one document #9072→domain:devx、[finding] Three merged ADRs still say "Proposed — awaiting the maintainer's hand-merge, which is itself the acceptance act" — a sentence their own presence on main disproves, and which seats read as a gate #15453→domain:skills。本卡主题是 manifest 的 type 值域，两个拒绝它的 schema（manifest.zod.ts / plugin.zod.ts）都在 packages/spec ⇒ domain:spec，与同族的 spec: name the live ui plugin type in the PluginSchema describe strings #15639（改 plugin.zod.ts 的 describe）同 lane。
• p3：受影响面是一份 Proposed ADR 的两处文本；无运行期后果；hono 侧仍容忍旧拼法，所以即使有人照抄也不会在 UI 插件加载路径上炸（会在 manifest 校验处炸）。
• ⛔ 不与 [finding] plugin-hono-server still accepts the legacy ui-plugin type that PluginSchema refuses — an unreachable arm under ADR-0049 #15638 合并：那张卡是 plugin-hono-server 的运行期容忍臂，落点不同、lane 不同，且本卡带一条它没有的活反读。⛔ 不与 [finding] the two plugin-type-closed-set pins explain themselves by "the spelling a stale describe() still uses" — #15639 removes the last such describe #15640 合并：那张已覆盖 pin 注释。三者是同一族的三处不同残留。
• ✅ 卡片的收尾约束照单转达：无论哪一支，plugin-type-closed-set.test.ts / plugin-type-closed-set.pin.test.ts 两处 pin 都不得改动——它们钉的拒绝是对的。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box。

---

Generated by Claude Code