[objectstack-fleet]

Fixes #24357
Clause-②: no

What changed

One line in each of two files, net ±0 lines per file:

• AGENTS.md, Build & Test block: pnpm setup becomes pnpm run setup, and the comment now ends (bare `pnpm setup` is pnpm's own built-in), so the next edit does not tidy the run away. The comment column stays aligned with the lines around it.
• examples/README.md, Getting started block: pnpm setup becomes pnpm run setup. The comment column stays aligned.

Nothing else is touched. The root package.json setup script is unchanged.

Why: measured on pnpm 10.31.0

10.31.0 is both the root packageManager pin and the container's pnpm --version. Every probe of the bare form ran with HOME, SHELL=/bin/bash and XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_CACHE_HOME / XDG_STATE_HOME pointed at a throwaway directory in the session scratchpad, with PNPM_HOME unset. I read the sha256 of the container's real ~/.bashrc, ~/.zshrc and ~/.profile before and after every probe, and none of them changed.

probe	where	what ran	exit
bare pnpm setup	a fixture project whose only script is setup, which writes a marker file	pnpm's built-in. It created the throwaway .bashrc with the # pnpm ... export PNPM_HOME=... ... # pnpm end block and printed "To start using pnpm, run: source ...". No marker file.	0
pnpm run setup	the same fixture	the script. It printed SETUP_SCRIPT_RAN and wrote the marker file.	0
bare pnpm setup	this repo's root at a2a3777bf5	the built-in again, with the same rc block. No install output. packages/spec/dist was absent before and after.	0
pnpm run setup	this repo's root, with the real HOME so it uses the real store	pnpm install && pnpm --filter @objectstack/spec build. It printed Already up to date, ran the spec build to check-dts-emitted: 38/38 and stamped packages/spec/dist/.build-input-hash.	0 (os-verify-lock VERDICT command-exit 0)

So the failure is silent. Bare pnpm setup exits 0, prints text that looks like success, and edits the contributor's shell rc. It leaves no install and no spec build behind. pnpm help setup agrees: "Usage: pnpm setup. Sets up pnpm".

Every pnpm setup hit and its disposition

On the base, git grep -nE 'pnpm setup\b' a2a3777bf5 -- . ':!**/CHANGELOG.md' found 3 hits. The excluded CHANGELOG.md files have 0 hits, and they are release-owned anyway.

hit	disposition
AGENTS.md:40	a first-time setup command: changed
examples/README.md:42	a first-time setup command: changed
.github/workflows/lint.yml:157	YAML comment prose ("checkout, Node and pnpm setup, the caches, the install, ...") about setting pnpm up, not the command: untouched, and outside this card's file surface

After the change, the same grep finds 2 hits: lint.yml:157, and the new AGENTS.md comment, which names the bare form on purpose. On the base, git grep -nE 'pnpm run setup' found 0 hits.

I also intersected the 206 root package.json script names with pnpm 10's command names. The only other collisions are test, where pnpm's built-in runs the script so nothing breaks, and version, which every tracked caller already spells pnpm run version.

The open choice I settled: the comment clause

Should the AGENTS.md line say why it is run? I judged it on the four axes. Business need: the readers are first-time contributors and every new agent session, and bare pnpm setup is exactly what they ran. Long-term soundness: the clause states the trap once, where the command lives, with no gate and no new file. Making AI mistakes structurally harder: an agent that knows pnpm SCRIPT normally runs a script will shorten pnpm run setup back to pnpm setup. The clause names why this one must keep run, and that shortening is how the defect got in. No scope spread: one line, no number, no incident narrative (check:pm-skill-id-lint is green). examples/README.md gets only the run, because its readers follow it rather than edit it.

Changeset

None. The PR carries the skip-changeset label: both files are repo-root docs, and no package's files[] ships either of them. The devx lane rule says root scripts/, docs and test-only changes get skip-changeset.

Gates (local subset, at 2601bcc81)

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 42 commands for the two paths, the same list as the dispatch-time reading. I ran each one in the worktree and captured its exit code before any pipe:

• 40 exited 0. That includes check:pm-governed-prose, check:pm-governed-merges, check:pm-skill-id-lint (87 files clean), check:pm-skill-ratchet, check:nul-bytes, check:cross-package-test-inputs, check:published-files, check:test-source-alias and check:examples-live-imports, plus every node scripts/check-*.mjs row and its --self-test.
• 2 exited 3 with PREREQUISITE NOT MET, which reads as NOT MEASURED, not as a failure: pnpm check:dual-build-cjs-loads and pnpm check:lean-entry-closure. Both load built output of packages this diff does not touch, and only packages/spec is built in this worktree. CI's Build Core and Lint jobs run them over a full build.
• check:dts-closure and check:sourcemap-no-sources-content exited 0 but swept 1 built package (@objectstack/spec) for the same reason.
• dispatch-gates --ran with COMMAND :: exit CODE lines printed: "42 derived famil(ies) accounted for — 40 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)".

No package is touched, so no package build closure, pnpm test or pnpm typecheck is owed. No tested behaviour changed, so there is no ablation. Every family CI runs on the PR is read from the PR's check-runs, not re-run here.

Acceptance notes

• examples/README.md runs pnpm install on the line above pnpm run setup, and the script runs pnpm install again. That is redundant but harmless, since the second install is a no-op. It is polish, not a defect, so I left it as written. Carrier: none.
• Renaming the root script to a name pnpm does not own would remove the trap at its source instead of documenting it. I did not take that route. It changes package.json outside this card's file surface, objectui kept the setup name and moved its docs to pnpm run setup, and nothing in this repo calls the script by any other spelling. Carrier: none.

维护者速读(草稿)

改了什么:AGENTS.md「Build & Test」段和 examples/README.md「Getting started」段里首次安装的那一行,pnpm setup 改成 pnpm run setup。AGENTS.md 那一行的注释补了半句,说明裸 pnpm setup 是 pnpm 自带的命令。每个文件只改一行,行数不变。

为什么改:pnpm 10 下,裸 pnpm setup 跑的是 pnpm 自带的 setup 命令,它往 shell 配置文件里写 PNPM_HOME。仓库根 package.json 里的 setup 脚本(装依赖 + 构建 spec)根本不会跑。这个命令以 0 退出,打印的提示看起来像成功了,所以照 AGENTS.md 做首次安装的新同事或新 agent 会以为已经装好,实际上依赖没装、spec 没构建,shell 配置还被改了。两种写法都在本仓根目录和一个隔离夹具里实测过,全程没碰真实的 rc 文件。

风险与代价(含回滚):只改两行文档,不碰代码,没有发布面,不加门禁。代价是首次安装命令多了 4 个字符。回滚就是 revert 这个 PR。AGENTS.md 是 Tier H 治理面,所以整个 PR 要等你批准才能落地。

席位意见:

你要做的:看一下这两行 diff,同意就给一次批准(APPROVED review),之后由席位落地。如果不想要注释里那半句,告诉席位只保留 pnpm run setup 即可。

---

Generated by Claude Code

[objectstack-fleet]

维护者速读

改了什么:AGENTS.md「Build & Test」段和 examples/README.md 的首次安装那一行,把 pnpm setup 改成 pnpm run setup。AGENTS.md 那行注释补了半句:裸 pnpm setup 是 pnpm 自带的命令。两个文件各改一行,行数不变。

为什么改:在 pnpm 10 下,裸 pnpm setup 执行的是 pnpm 自带的 setup 命令,它只往 shell 配置文件里写 PNPM_HOME。仓库根 package.json 里的 setup 脚本(装依赖 + 构建 spec)根本不会执行,而命令仍以 0 退出、打印看似成功的提示。结果是照 AGENTS.md 做首次安装的新同事或新 agent 会以为已经装好,实际上依赖没装、spec 没构建。dev 在仓库根目录和隔离夹具里把两种写法都实测过;席位另跑了 pnpm help setup,确认是 pnpm 内置命令("Sets up pnpm")。

风险与代价(含回滚):只改两行文档,不碰代码,没有对外发布面,也不加门禁。回滚就是 revert 这个 PR。

席位意见:建议批准。改动与 main 上的 package.json 脚本一致,注释那半句是为了防止下一个 agent 把 run 又"简化"掉,不带卡号、不带事故叙事,符合 AGENTS.md 自身的写法规则。

你要做的:同意就给这个 PR 一次批准(APPROVED review),之后由 devx 席位落地。

席位核对

ACCEPT · domain:devx seat 1 · os-warren · session_01FM29ZqLTrnPNXxijioZwMp · 2026-10-18T16:43Z · head 2601bcc81 · card #24357 (claim 6252197090)

• Form. Draft, base main, author objectstack-fleet[bot]. The body's first line is Fixes #24357, the only closing keyword in the body. Assignee os-warren. skip-changeset: applied by the dev at pr_create; the seat's own check agrees, since both paths are repo-root docs that no package's files[] ships.
• Premise, measured. Seat reading in its own worktree: pnpm help setup (pnpm 10.31.0, the root packageManager pin) → "Usage: pnpm setup — Sets up pnpm", the built-in. The dev's fixture and repo-root probes (throwaway HOME, real rc files' sha256 unchanged) are in the PR body.
• Grep disposition. git grep -nE 'pnpm setup\b' origin/main -- . ':!**/CHANGELOG.md' at a2a3777bf5 → 3 hits: the two changed lines, and .github/workflows/lint.yml:157, YAML comment prose about setting pnpm up, correctly left.
• Scope. 2 files, +2 / −2, one line each, comment columns kept. The new AGENTS.md clause carries no issue number (check:pm-skill-id-lint green locally).
• Path fork. node scripts/pm/check-governed-merges.mjs --pr 24370 → GOVERNED, landing tier H, on AGENTS.md (×1); examples/README.md is not on the register; 4 changed lines ≤ 3000. Per Prime Directive feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14 this PR stays draft until an authorised APPROVED review from GOVERNED_APPROVERS; then this seat lands it.
• Gates, pinned to head 2601bcc81. 43 check-runs, all completed: 33 success, 10 skipped. node scripts/pm/check-expected-skips.mjs --pr 24370 → VERDICT … OK — 10 skipped check-run(s), every one in the roster (exit 0). Required contexts: Lint & Repo Gates, TypeScript Type Check, Test Core, Build Core and Governed Surface Queue Guard all success.
• Accepted deviations. check:dual-build-cjs-loads and check:lean-entry-closure NOT MEASURED locally (exit 3, unbuilt packages the diff does not touch); CI runs them.
• Acceptance notes. The redundant pnpm install above pnpm run setup in examples/README.md, and renaming the root script instead: both noted, not filed.

---

Generated by Claude Code