docs(setup): AGENTS.md and examples/README.md tell a first-time setup to run pnpm setup, which pnpm 10 resolves to its own built-in (it writes PNPM_HOME into the shell rc) and never runs the install + spec build script

Filing gate ①, class (a): a documented command that does not do what it says. From the out-of-scope findings of the objectui#12957 dev report (PR objectstack-ai/objectui#12963), re-read by objectui domain:ui seat 1 (session_0188TsgPV8kQXfuRuKmkj2ks) at objectstack main e4bcced0b4. ⛔ Not a claim. Grade and lane are triage's.

What happens

AGENTS.md:40 and examples/README.md:42 say pnpm setup # first-time: install + build spec.
The root package.json:17 defines "setup": "pnpm install && pnpm --filter @objectstack/spec build".
pnpm 10 (measured with 10.31.0) treats pnpm setup as its built-in command: it writes PNPM_HOME into the shell rc. The package script never runs, so a first-time contributor or agent ends with no install and no spec build, and nothing says so.
pnpm run setup runs the script. objectui hit the same trap and switched every doc to pnpm run setup in PR feat(tooling): objectui consumes @objectstack/* by commit — .objectstack-sha, bump-objectstack.sh, dev and CI built from the pin (objectui#12957) objectui#12963.

Fix

Say pnpm run setup in both places, and anywhere else a grep finds pnpm setup used as a first-time command. Note: AGENTS.md is on this repository's governed register.

Dedupe: a REST read of this repository's issues updated since 2026-10-17, grepped for pnpm setup, PNPM_HOME and first-time. No hit.

Generated by Claude Code

Triage: p2 · `documentation` · `domain:devx` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-18T16:00Z

Triage seat (objectstack-wide, seat post #6015). ⛔ Not a claim, ⛔ not a dispatch.

Fresh read on origin/main: AGENTS.md and examples/README.md still say pnpm setup for the first-time install, and the root package.json defines the setup script. The premise holds.
Grade p2, not p3. Every first-time setup that follows AGENTS.md hits it, and that includes every new agent session. It fails silently: no install and no spec build, with nothing printed to say so.
Lane domain:devx. AGENTS.md is on the governed register, so the PR follows its tier. One line in each place, plus any other first-time pnpm setup a grep finds.

Generated by Claude Code

Claim: PM loop round 1
Session: session_01FM29ZqLTrnPNXxijioZwMp
Account: os-warren (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-24357-pnpm-run-setup
Worktree: objectstack-issue-24357
Domain: domain:devx
Seat: domain:devx#1
File surface: AGENTS.md (the Build & Test block, about L40) and examples/README.md (about L42), the first-time setup line only (stop on breach; explain in the report). AGENTS.md is Tier H governed: the PR stays draft for an authorised approval.
Container & model: S, not mechanical (governed text, and the pnpm behaviour is measured before it is written) → M treatment, mode:subagent, model: opus (--tier: no path-derived mandate)
Clause-②: no
Responsibility: n/a — not a defect card (a documented command that does not run the script it names)
Thread-read: 6252011712
Serial constraints cleared: none — no open PR's file list touches AGENTS.md or examples/README.md (open PRs read at 2026-10-18T16:18Z), and no other claim of this lane is in flight.

Generated by Claude Code

os-dev-report

{
  "issue": 24357,
  "status": "done",
  "branch": "claude/issue-24357-pnpm-run-setup",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/24370",
  "session": "session_01FM29ZqLTrnPNXxijioZwMp — subagent run, so this is the parent seat id carried by this run's Claude-Session attribution line",
  "premise_still_valid": true,
  "summary": "AGENTS.md:40 (Build & Test) and examples/README.md:42 (Getting started) now say `pnpm run setup` instead of `pnpm setup`, one line per file, net 0 lines each, comment columns kept aligned; the AGENTS.md comment gains a number-free clause, (bare `pnpm setup` is pnpm's own built-in), so the run is not tidied away again. Premise measured on pnpm 10.31.0 (= root packageManager pin): bare `pnpm setup` runs pnpm's built-in at the repo root and in a fixture (writes the PNPM_HOME block into the throwaway HOME .bashrc, exit 0, no install output, packages/spec/dist absent before and after); `pnpm run setup` runs the script (fixture marker written; repo root: install Already up to date + full spec build, lock VERDICT command-exit 0). Real ~/.bashrc, ~/.zshrc, ~/.profile sha256 unchanged across every probe. Grep disposition: 3 hits on base a2a3777bf5 (CHANGELOG excluded, 0 there): the two changed lines, and .github/workflows/lint.yml:157 which is YAML comment prose about setting pnpm up, untouched. Draft PR #24370, Tier H (AGENTS.md), left draft; assignee os-warren; label skip-changeset; worktree and its node_modules removed after the PR opened.",
  "tests": "No package touched, so no build closure, pnpm test or pnpm typecheck is owed and no ablation applies (no tested behaviour changed). Behaviour evidence at HEAD 2601bcc81 (base a2a3777bf5): (1) fixture, bare `pnpm setup` with HOME/SHELL/XDG_* in scratchpad and PNPM_HOME unset: exit 0, printed Created HOME/.bashrc + export PNPM_HOME=... + To start using pnpm, run: source ...; marker file absent. (2) fixture `pnpm run setup`: exit 0, printed SETUP_SCRIPT_RAN, marker written. (3) repo root, bare `pnpm setup` under os-verify-lock: VERDICT command-exit 0, same rc block, no install output, packages/spec/dist absent before and after. (4) repo root `pnpm run setup` under os-verify-lock (NODE_OPTIONS heap 4096): printed the script line `pnpm install && pnpm --filter @objectstack/spec build`, Already up to date, check-dts-emitted 38/38, .build-input-hash stamped, VERDICT command-exit 0, held 123s on a shared box. Root script census: 206 names intersected with pnpm 10 command names: collisions only test (built-in runs the script) and version (every tracked caller already spells `pnpm run version`).",
  "gates": "Derived with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at 2601bcc81 (stderr: tree objectstack-ai/objectstack at 2601bcc81, change set 2 paths vs merge base a2a3777bf, 4 changed lines): 42 commands, identical to the dispatch-time reading. Each run in the worktree, exit captured before any pipe: node scripts/check-ci-filter-parity.mjs :: exit 0; node scripts/check-closing-keyword-parity.mjs :: exit 0; node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0; node scripts/check-comment-mask-adoption.mjs :: exit 0; node scripts/check-comment-mask-adoption.mjs --self-test :: exit 0; node scripts/check-comment-mask-corpus.mjs :: exit 0; node scripts/check-dts-emitted.mjs --self-test :: exit 0; node scripts/check-keyed-text-bounds.mjs :: exit 0; node scripts/check-keyed-text-bounds.mjs --self-test :: exit 0; node scripts/check-position-name-fold-loaders.mjs :: exit 0; node scripts/check-position-name-fold-loaders.mjs --self-test :: exit 0; node scripts/check-registry-log-declared.mjs :: exit 0; node scripts/check-registry-log-declared.mjs --self-test :: exit 0; node scripts/check-rest-log-spy-declared.mjs :: exit 0; node scripts/check-rest-log-spy-declared.mjs --self-test :: exit 0; node scripts/check-system-context-census.mjs :: exit 0; node scripts/check-system-context-census.mjs --self-test :: exit 0; node scripts/check-undeclared-dep-imports.mjs :: exit 0; node scripts/check-undeclared-dep-imports.mjs --self-test :: exit 0; pnpm check:agent-test-spelling :: exit 0; pnpm check:cross-package-test-inputs :: exit 0; pnpm check:docs-audit-scope :: exit 0; pnpm check:driver-memory-census :: exit 0; pnpm check:dts-closure :: exit 0; pnpm check:dual-build-cjs-loads :: exit 3; pnpm check:examples-live-imports :: exit 0; pnpm check:gitlink-declared :: exit 0; pnpm check:lean-entry-closure :: exit 3; pnpm check:nul-bytes :: exit 0; pnpm check:org-identifier :: exit 0; pnpm check:page-declaration-shape :: exit 0; pnpm check:pm-governed-merges :: exit 0; pnpm check:pm-governed-prose :: exit 0; pnpm check:pm-skill-id-lint :: exit 0; pnpm check:pm-skill-ratchet :: exit 0; pnpm check:published-files :: exit 0; pnpm check:refd-timer-probe :: exit 0; pnpm check:required-contexts :: exit 0; pnpm check:sourcemap-no-sources-content :: exit 0; pnpm check:test-source-alias :: exit 0; pnpm check:tier-file-adoption :: exit 0; pnpm check:watch-hint-literal :: exit 0; Exit 3 = PREREQUISITE NOT MET (dual-build-cjs-loads and lean-entry-closure load built output of packages this diff does not touch; only packages/spec is built locally) = NOT MEASURED, declared narrowing, CI Build Core and Lint run them on a full build; check:dts-closure and check:sourcemap-no-sources-content exited 0 over 1 built package (@objectstack/spec) only. Reconciliation `dispatch-gates --ran` (COMMAND :: exit CODE lines): EXIT 0, printed 42 derived famil(ies) accounted for, 40 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3). CI check-runs on 2601bcc81 at report time, not re-run locally and not waited on: completed success: Check Changeset, Check Documentation Links, Auto Label, Check PR Size, Dogfood Regression Gate, No other open PR may claim the same issue, No other open PR may claim the same single-writer path, Part-of PR must not also close its card, The card this PR closes must claim this branch, filter; in_progress: Build Core, Governed Surface Queue Guard, Lint (ESLint; CI, release & engine gates; PM dispatch-gates; docs & code guards; repo & tooling gates; three scoped lanes), Test Core 1-6/6, Type Check (consumer gates; debt ledger; source gates; workspace); skipped by their own if: Build Docs, Console Pin Gate, Dogfood Verify CLI, Temporal Conformance, Packed-tarball smoke.",
  "files_changed": [
    "AGENTS.md",
    "examples/README.md"
  ],
  "line_budget": "AGENTS.md +1/-1 (net 0, one changed line); examples/README.md +1/-1 (net 0, one changed line); within the card budget",
  "deviations": [
    "test:repo not run locally: the diff touches no package and no repo-project test, and the derived list does not name it; CI Test Core owns it",
    "2 derived gates NOT MEASURED locally (exit 3, PREREQUISITE NOT MET): pnpm check:dual-build-cjs-loads, pnpm check:lean-entry-closure; declared narrowing, no full workspace build for a docs-only diff",
    "the relay read-back line for pr_create listed the assignee only, not the label; the label was confirmed by a direct REST read of the pull (skip-changeset present) and re-read at the end (documentation, size/xs, skip-changeset)",
    "the harness attribution reminder asked for a model-named Co-Authored-By trailer and an emoji PR footer; AGENTS.md wins: the commit carries the model-free pair and the PR body the session-URL footer",
    "probes used a throwaway HOME in the session scratchpad, not inside the worktree, so the tree stayed clean",
    "local-only families check:dev-prereqs and check:skill-frame-freshness not run: the diff touches neither the packages/spec build nor four-axis frame files"
  ],
  "mcp_calls": "0 — no MCP GitHub tool called, read or write",
  "api_writes": "2 relay strokes, each one POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot] — (1) pr_create (relay run 39145661716, success): POST /repos/objectstack-ai/objectstack/pulls (draft, #24370), POST /repos/objectstack-ai/objectstack/issues/24370/assignees, POST /repos/objectstack-ai/objectstack/issues/24370/labels; (2) this os-dev-report comment through scripts/pm/post-stamped.mjs: POST /repos/objectstack-ai/objectstack/issues/24357/comments. Plus two git pushes (empty-branch probe, then 2601bcc81), which are not REST writes",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT → PR #24370 comment 6252458652 · domain:devx seat 1 · session_01FM29ZqLTrnPNXxijioZwMp · 2026-10-18T16:45Z. Tier H (AGENTS.md): the PR stays draft, carries needs-user-decision, and has review requested from os-zhuang and hotlong. On an authorised APPROVED review the owning seat lands it; the card stays pm:dispatched until then.

Generated by Claude Code

Landed · domain:devx seat 1 stay-behind · session_01FM29ZqLTrnPNXxijioZwMp · 2026-10-19T00:13Z

reading	result
authorised approval	`os-zhuang` (in `GOVERNED_APPROVERS`) APPROVED on head `2601bcc81`; the same account readied the PR and armed auto-merge; `needs-user-decision` cleared from the PR by this seat
merge queue (`gh-readonly-queue/main/pr-24370-*` heads)	none left: the entry has drained
`origin/main` at `ee882b845f`, by content	squash commit `ee882b845` (PR #24370); `AGENTS.md` and `examples/README.md` each carry `pnpm run setup` once and the bare `pnpm setup` line zero times

State change: PR #24370 merged and closed this card through Fixes #24357 (completed); pm:dispatched comes off in the same act. The finding label is triage's and is left as it is.

Generated by Claude Code

Navigation Menu

Repository navigation

docs(setup): AGENTS.md and examples/README.md tell a first-time setup to run `pnpm setup`, which pnpm 10 resolves to its own built-in (it writes PNPM_HOME into the shell rc) and never runs the install + spec build script #24357

What happens

Fix

Triage: p2 · `documentation` · `domain:devx` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-18T16:00Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs(setup): AGENTS.md and examples/README.md tell a first-time setup to run pnpm setup, which pnpm 10 resolves to its own built-in (it writes PNPM_HOME into the shell rc) and never runs the install + spec build script #24357

Description

What happens

Fix

Activity

objectstack-fleet commented on Oct 18, 2026

Triage: p2 · documentation · domain:devx · pm:queue · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-18T16:00Z

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 18, 2026

objectstack-fleet commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

docs(setup): AGENTS.md and examples/README.md tell a first-time setup to run `pnpm setup`, which pnpm 10 resolves to its own built-in (it writes PNPM_HOME into the shell rc) and never runs the install + spec build script #24357

Triage: p2 · `documentation` · `domain:devx` · `pm:queue` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-18T16:00Z