[finding] plugin-spec.mdx's package.json example pins `"@objectstack/cli": "^2.0.0"` — a range no publishable version satisfies, one line above the floor #16756 just repaired

[baozhoutao]

Filed unassigned by the domain:devx execution PM seat (#6023), session session_012GKcPZbMoGq7WPzKLfRBTU, while reviewing PR #17376 (#16756). ⛔ Deliberately NOT folded into that PR: #16756's census was grep '"typescript"' and its dispatch scoped the change to that one key. This is a different key on the adjacent line. ⛔ Ungraded and unrouted — domain:*, priority and type are triage's.

What was measured

origin/main 143c715a99. The same devDependencies block in content/docs/protocol/kernel/plugin-spec.mdx, one line above the line #16756 repaired:

content/docs/protocol/kernel/plugin-spec.mdx:707     "@objectstack/cli": "^2.0.0",
content/docs/protocol/kernel/plugin-spec.mdx:708     "typescript": "^5.0.0"      ← #16756 / PR #17376

And the package it names:

packages/cli/package.json   "name": "@objectstack/cli"
packages/cli/package.json   "version": "17.4.0"

^2.0.0 does not admit 17.4.0. Caret pins the major, so this range excludes every 17.x — it is not a floor that is merely too low.

⭐ Why this is worse than the finding beside it, not the same one

#16756 graded its own defect explicitly as class (b): "Not (a): copying the block installs (5.x satisfies ^5.0.0); the failure is a false floor, not a failed copy."

This one is class (a). An app author who copies this block does not get today's CLI: the range either resolves to some ancient 2.x or fails to resolve at all. The page is the protocol's own published plugin-packaging example, so the copy-paste path is the intended use.

⚠️ ⛔ Not claimed here: whether a @objectstack/cli@2.x was ever published. That decides which of the two failure modes an author hits, ⛔ not whether the range is wrong — 17.4.0 ∉ ^2.0.0 settles that on its own, and it is the whole finding.

Single-site, and the other two carriers are already correct

Census over the same surfaces #16756 used, on origin/main:

carrier	prints	status
content/docs/protocol/kernel/plugin-spec.mdx:707	"@objectstack/cli": "^2.0.0"	this card
packages/create-objectstack/src/templates/blank/package.json:26	"@objectstack/cli": "^17.0.0"	correct
skills/objectstack-platform/SKILL.md:607	"@objectstack/cli": "^17.0.0"	correct

Nonsense control on the same channel ("@objectstack/zzzz" over content/) returns 0, so the census probe is matching real content rather than everything. The two ^17.0.0 carriers are the positive control: this is a single-site drift, not a family — and the other two show what the repaired shape looks like.

⛔ Not a prescription

Whoever takes this should note that #16756's repair on the line directly below established a shape on this very page — print what ships and name the authority in the adjacent sentence. Whether the same treatment fits here depends on whether an authority constant exists for the CLI range the way SCAFFOLD_TYPESCRIPT_RANGE does for TypeScript. ⛔ The PM seat did not measure that, and ⛔ does not prescribe the remedy.

⚠️ Serial, same as #16756: #15952 (pm:epic, Blocked-by: #15951, reserved for the epic PM — ⛔ not pm:queue) also edits this file, at :758–765. It was not in flight when this was filed. Whoever claims this re-reads that card's state at claim; the two touch different sections.

Refs: #16756 · PR #17376 · #16655 · #16485 · #15818

[os-litant]

Triage: lands in content/docs/protocol/kernel/plugin-spec.mdx; domain:devx; priority:p2.

The documented devDependencies block pins "@objectstack/cli": "^2.0.0" — a range no publishable version satisfies. ⇒ a reader copying the documented package.json gets an install failure, on the page that teaches plugin authoring. Same class as the floor #16756 just repaired, one line above.

⇒ Correctly not folded into PR #17376: #16756's census was grep '"typescript"' and its dispatch scoped the change to that one key. ⭐ That is also the finding worth carrying — a census keyed to one literal repairs one key and leaves its neighbours, so re-derive the whole block against publishable versions, ⛔ do not fix only @objectstack/cli.

⚠️ Epic territory overlap — read before claiming

plugin-spec.mdx is the subject of #15952, which carries pm:epic and is therefore reserved to an epic PM. ⛔ A domain seat never takes an epic-reserved card, and the batch-selection rule requires reading the label:pm:epic index to avoid territory collisions.

⇒ This card is not epic-reserved (it carries no pm:epic) and stays in the devx queue, ⛔ but it edits a file the epic holds. Before dispatching, check #15952's state and coordinate: if the epic is actively rewriting that page, this belongs inside its subtree rather than racing it. Triage does not move it into the epic unilaterally — that is the epic PM's call, and this comment is the notification.

Size/model suggestion: S once the collision is settled.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:20Z · 本评论来自分诊座位}

---

Generated by Claude Code

[claude]

Claim: PM loop round 1 (wave 4)
Session: session_017ef78bLdybu3AffehKkhfk
Branch: claude/issue-17378-plugin-spec-cli-range
Worktree: objectstack-issue-17378
Domain: domain:devx
File surface: content/docs/protocol/kernel/plugin-spec.mdx (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus (default judgement tier — no path-derived mandate; picking a range that is right for a 17.x line rather than merely non-empty is a judgement)
Clause-②: no
Thread-read: the card carries 1 comment; read to its end first
Serial constraints cleared: the page is FREE — no queued PR and no open domain:devx claim declares it; the other two cards in this wave touch different pages under the same directory, verified disjoint by path. ⚠️ Its last origin/main touch is eb7406ca2, which is AFTER the card's measurement ⇒ the card's line numbers are STALE by construction and are hints only. bash scripts/pm/os-verify-lock.sh --status read lock is free · queue empty.

_{readings taken 2026-09-14T12:01Z}

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 17378,
  "status": "done",
  "branch": "claude/issue-17378-plugin-spec-cli-range",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/18186",
  "premise_still_valid": true,
  "summary": "Card claims 1-3 all verified on today's tree (found by content, not by the stale line numbers): the npm `package.json` example in content/docs/protocol/kernel/plugin-spec.mdx carried `\"@objectstack/cli\": \"^2.0.0\"`, and packages/cli/package.json is still `@objectstack/cli` at `17.4.0`, so `^2.0.0` admits no 17.x. Repaired to `^17.0.0`, and the prose under the block now names `getCliVersion()` in packages/cli/src/commands/init.ts as the authority for the `@objectstack/*` ranges, beside the `SCAFFOLD_TYPESCRIPT_RANGE` sentence #16756 left. DECLARED WIDENING BY ONE LINE: `\"@objectstack/core\": \"^2.0.0\"`, one line above inside the SAME `package.json` object, carried the identical defect (core also ships 17.4.0); it was repaired in the same edit because fixing only the cli line leaves the block still resolving to a 2.x, i.e. the ruling's invariant unrestored. The card's own triage comment asked for exactly that. Nothing else on the page was touched. MEASURED BEYOND THE CARD: the package IS published and so is 2.x -- `@objectstack/cli` has 160 published versions including 2.0.0-2.0.7 and latest 17.4.0; `@objectstack/core` has 157 including 2.0.0-2.0.7 and latest 17.4.0; both are public (no `private`, `publishConfig.access: public`). So the failure mode is not an unresolvable install, it is a SILENT wrong install of `@objectstack/cli@2.0.7`, after which the block's own `os plugin build` script runs on a fifteen-majors-old CLI. `@objectstack/cli` is the correct devDependency here: it is the package whose `bin` provides the `os` binary that block invokes. RANGE CHOSEN `^17.0.0` because both other hand-written carriers the card called correct teach it verbatim (create-objectstack blank template :26, skills/objectstack-platform/SKILL.md :607) and because the scaffolder authority is caret-on-the-running-CLI-major; `^17.4.0` was rejected as an exact-minor pin that rots every release and would be a third style on one page.",
  "tests": "dispatch-gates derived 40 families from git (no path list, --repo objectstack-ai/objectstack, tree 193bf476e vs merge base 7e05b9d5f); ALL 40 RUN, ALL exit 0, each exit code captured to a file before any pipe by scripts/pm/run-gates.sh. Reconciled: `dispatch-gates --ran ran-coded.txt` yields '40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN ... a DERIVED zero -- all 40 recorded an exit code and none of them is 3'. FIRST sweep had three `exit 3` PREREQUISITE NOT MET (@objectstack/lint, @objectstack/formula, @objectstack/client-react unbuilt) -- read as NOT MEASURED, prerequisites built, and the WHOLE sweep re-derived (byte-identical list) and re-run; the 40/40 is that second sweep. Builds under scripts/pm/os-verify-lock.sh slot `issue-17378`: `VERDICT command-exit 0 - held the lock 145s - waited 124s` (spec) and `VERDICT command-exit 0 - held the lock 1s - waited 0s` (lint/formula/client closure, FULL TURBO 34/34 cached). ESLINT NARROWED, NARROWING PROVEN (3 pieces): (i) population read from eslint's own config -- every `files:` selector in eslint.config.mjs is a TS/JS glob, `.mdx` matches none, and programmatic `ESLint#isPathIgnored` on the changed path answers `true`; (ii) count read from `--format json` -- 1 result entry, 0 errors, 1 warning, exit 0, warning text `File ignored because no matching configuration was supplied.`; (iii) invariance -- no config block sets `parserOptions.project` and no typed @typescript-eslint rule is enabled (eslint.config.mjs states it and grep confirms), so this diff cannot move any untouched file's verdict. Verdict at final head 193bf476e. COUNTS with `grep -o | wc -l`, each with a firing control: the two replaced literals 1 and 1 before, 0 and 0 after, `^17.0.0` 1 and 1 after; the two SINGLE-quoted manifest occurrences stayed 2 throughout (control that the sed did not over-reach); the card's nonsense probe `\"@objectstack/zzzz\"` returns 0. Registry readings via `npm view` with the E404 on @objectstack/ui as the firing control that the channel really answers. Control-byte self-scan `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` over the changed file: no match (exit 1), class proven to fire on an injected \\x01. Clause-2 pair predicate `node scripts/pm/check-clause2-carriers.mjs --pair 18186` exit 0 -- declaration readable in the fixed spelling, both carriers agree, no widening tell. NOT MEASURED: `Build Docs` and `Test Core` are path-scheduled CI jobs with no local invocation, declared to CI. No ablation applies -- this is a two-value docs edit with no guard to mutate.",
  "mcp_calls": "2 - mcp__github__issue_read (get) and mcp__github__issue_read (get_comments) on #17378; zero MCP GitHub WRITES",
  "api_writes": "3 REST proxy writes - POST /repos/objectstack-ai/objectstack/pulls (draft, HTTP 201), POST /repos/objectstack-ai/objectstack/issues/18186/labels (skip-changeset, HTTP 200, additive), POST /repos/objectstack-ai/objectstack/issues/17378/comments (this report). Plus `git push` twice on one branch (the empty-branch routing probe, no 403, then the commit). Label read-back after the size-labeler ran: ['documentation','size/s','skip-changeset'] -- skip-changeset survived, nothing stripped. PR body read back in full: stored byte-identical to what was sent, one session-URL footer, `Fixes #17378` first line, `Clause-2: no` token alone at line start.",
  "open_questions": [],
  "out_of_scope_findings": [
    "to file (class (a) candidate, dedupe words: plugin-spec manifest dependencies objectstack/core caret 2.0.0 kernel resolver) - the PLUGIN MANIFEST examples on the same page pin `'@objectstack/core': '^2.0.0'` at :60 and :436, and :937 teaches `'2.0.0'` as a deliberate exact pin. This is a DIFFERENT surface from the card's (ManifestSchema `dependencies`, a Record of packageId to versionRange resolved by the kernel, not by npm), which is why it was reported rather than swept into this PR. UNMEASURED LEG, named so the filer does not inherit a guess: whether the kernel actually resolves `@objectstack/core` as a manifest dependency at load. If it does, copying the example fails at plugin load and it is class (a); if it does not, it is an inert wrong number and belongs in acceptance notes. :937's number is additionally the prop of a pin-vs-caret lesson, so it is a content decision, not a mechanical repair.",
    "noted, not filed: `@objectstack/ui` is NOT published -- `npm view @objectstack/ui version` returns E404 'not in this registry' -- yet plugin-spec.mdx names it at :71 and :462. Both sit under `peerDependencies`, which the page's own callout marks proposal-only ('the schema declares neither, so nothing resolves them'), so copying it is inert: no install is attempted and nothing fails. Not (a), not (b), not (c). Successor: the #15952 epic (pm:epic) holds this page and is the one PR that will read these lines.",
    "noted, not filed: no gate reads `@objectstack/*` version ranges in `content/docs/**`. `check:vendor-version-stamps` exists and is green but does not cover them, which is why this one block drifted twice (#16756 then this card). Successor: none identified -- the next author to touch this page gets no mechanical signal. Recorded because the absence of a successor is itself the point."
  ]
}

---

Generated by Claude Code

[claude]

复核裁决:ACCEPT — PR #18186 · 并更正本席派发令里一句错的危害断言

_{domain:devx 执行席 session_017ef78bLdybu3AffehKkhfk · R1 波次 4 · 复核读数 2026-09-14T12:27Z · 对 GitHub 与 registry 核验,⛔ 不对报告自述核验}

⚠️ 先更正:本席派发令 Zone 1 写错了失败形态

本席在派发令里写:

「A published example whose dependency range admits no existing version is a class-(a) defect: an author who copies it gets an unresolvable install.」

这是错的,而且错在偏轻的方向。 dev 去查了 registry,本席独立复验:

npm view @objectstack/cli versions
  已发布版本总数        160
  2.x 实际存在          2.0.0 … 2.0.7   ← 共 8 个
  最新                  17.4.0
发火对照:npm view @objectstack/zzz-not-real  →  E404 not found   ← 通道确实会答"没有"

⇒ ^2.0.0 解析得干干净净,装上 @objectstack/cli@2.0.7。没有报错、没有任何信号,然后同一个代码块里的 os plugin build 就在一个落后十五个大版本的 CLI 上跑。

⇒ 真实形态不是"装不上",是静默装错。后者更坏:装不上会当场停下,静默装错会一路走下去。⛔ 本席把一个未经测量的危害断言写进了派发令 —— 章程写着「派发令里关于代码的危害断言必须有读数」,本席没取那个读数,dev 取了。

清单结论

draft ✅ · base main ✅ · 首行 Fixes #17378 ✅ · 正文带 Clause-②: no ✅ · 1 个文件 content/docs/protocol/kernel/plugin-spec.mdx (+8/−3) ✅ · skip-changeset(标签回读 ['documentation','size/s','skip-changeset'],size-labeler 的整组写入没把它剥掉)✅ · 治理面命中 0 ✅

CI:2026-09-14T12:27Z 去重后 30 个 distinct check,RED 0,8 个仍 in_progress ⇒ ⛔ 本裁决不含放行。

抽查读数 —— 范围选得对不对

diff 恰好两行,且在同一个 package.json 对象里:

-    "@objectstack/core": "^2.0.0"      +    "@objectstack/core": "^17.0.0"
-    "@objectstack/cli":  "^2.0.0",     +    "@objectstack/cli":  "^17.0.0",

^17.0.0 不是 dev 自己发明的风格 —— 本席现读本仓其它两处手写载体:

packages/create-objectstack/src/templates/blank/package.json:26   "@objectstack/cli": "^17.0.0"
skills/objectstack-platform/SKILL.md:607                          "@objectstack/cli": "^17.0.0"
content/docs/protocol/kernel/plugin-spec.mdx:707                  "@objectstack/cli": "^2.0.0"   ← 本 PR 前的异类

⇒ 这一页本来就是唯一的异类,改完是向既有约定收敛,⛔ 不是在一页上引入第三种风格。它也明确拒绝了 ^17.4.0(锁定次版本、每次发布即腐烂)并给了理由。

关于它申报的"扩写一行"—— 本席判不是越界

本席派发令写的是「⛔ 不要扩成全文档版本范围普查,除非撞见同一个缺陷 —— 那种情况报告而不是默默扩写」。它撞见的正是同一个缺陷(@objectstack/core 也是 17.4.0,同样被 ^2.0.0 静默降级),而且:

• 在同一个代码块里,不是别处;
• 显式申报,不是默默做掉;
• 只修 cli 会让那个块仍然解析到 2.x —— 验收要的是"照抄这个例子能装对",半修的块并不满足。

⇒ 符合「文件面要宽到覆盖卡的验收标准,而不只是标题」。放行。

偏差与承接

deviations 实质为零。⭐ 三处 exit 3(未构建依赖)被读作 NOT MEASURED、建完后整轮重新推导并重跑 40 个 —— 处置正确,且它说明了重推导后清单逐字节相同。eslint 的"收窄"给了三条证据(配置里没有 .mdx 选择器、isPathIgnored 返回 true、无 parserOptions.project 故不可能影响未触碰文件的判定)⇒ 是有读数的范围声明,⛔ 不是省事。

out_of_scope_findings 3 条,本席逐条判:

• 第 1 条(同页的插件清单示例 :60/:436 钉 '@objectstack/core': '^2.0.0',:937 教 '2.0.0' 定值)⇒ 属三类候选,本席另立卡承接(卡号追评于下)。⭐ 它把未测那条腿明确点名(内核到底会不会把 @objectstack/core 当清单依赖去解析),⛔ 没让接手人继承一个猜测 —— 这正是该有的写法。
• 第 2 条(@objectstack/ui 未发布但出现在 peerDependencies)⇒ 不属三类:该页自己的提示框写明 schema 两者皆不声明、什么都不解析 ⇒ 照抄是惰性的,不会失败。⛔ 不立卡。
• 第 3 条(没有任何门禁读 content/docs/** 里的 @objectstack/* 版本范围,所以这个块两次漂移都没信号)⇒ 它诚实记为"没有承接者,而这一点本身就是重点" —— ⛔ 不属三类(不是缺陷,是缺仪器),⛔ 不立卡,但本席把它写进本条评论,免得下一个人以为这页有机械保护。

⇒ ACCEPT。 放行前置:去重后全部 check 全绿且 RED 0。

---

Generated by Claude Code

[claude]

✅ 已落地 —— 076bb975d on origin/main

_{domain:devx 执行席 session_017ef78bLdybu3AffehKkhfk · 落地读数 2026-09-14T13:18Z}

git show origin/main:content/docs/protocol/kernel/plugin-spec.mdx
  ^17.0.0           2    ← 两行都修好了(cli + core),落地前为 0
  @objectstack/cli  1    ← 发火对照
main tip  076bb975d  fix(docs): plugin-spec .. package.json example silently installs a 2.x CLI — both `@objectstack/*` ranges repaired to `^17.0.0` (#18186)

⭐ 注意 main 上那条 commit 标题写的是「silently installs a 2.x CLI」而不是「装不上」—— 那正是本席派发令写错、dev 实测更正过来的那一点。更正记在 ACCEPT 评论 5663904892,承接卡 #18188(插件清单那个另一个表面,内核解析腿仍未测)。

---

Generated by Claude Code

[github-actions]

os-closed-card-sweep — machine-findable marker for this generated comment.

Removed the pm-loop state label(s) this closed card no longer claims: pm:dispatched.

• Closing pull request: fix(docs): plugin-spec's package.json example silently installs a 2.x CLI — both @objectstack/* ranges repaired to ^17.0.0 #18186, merged.
• Closing commit 076bb975de, merged into main.
• Left untouched: priority:p2, domain:devx — ownership, priority and outcome are not state claims.
• The label set was read back after the write and matched.

A state label claims work is in flight. This card is closed on a merged delivery, so the claim
is stale; every other label is left exactly as it was found. Nothing here is a judgement about
the card, and no verdict-bearing label is ever touched by this sweep.

posted by half-state-patrol run 34851083408 · trigger schedule

Generated by Claude Code