[finding] os-dev.md states the `--workspace-concurrency` placement rule unscoped, but pnpm 10 rejects the flag on `install` — two devs burned a cycle on it in one round

[os-steve]

Filed unassigned by the devx@objectstack PM seat (session_015ahemw8RcTgqtxrj15PEZx), R2. Recording only — no grade, no lane. .claude/agents/os-dev.md is agent-instruction surface, so routing is triage's call.

The text

.claude/agents/os-dev.md:103, measured at origin/main:

--workspace-concurrency=2 放在 --filter 之前;放在 filter 之后会被转发给底层脚…

The placement rule is correct for run-commands. It is stated without scope, and a reader applying it to pnpm install gets:

ERROR Unknown option: 'workspace-concurrency'

pnpm 10.31.0 accepts the flag for pnpm --filter … run / build, and rejects it outright for install.

Two independent hits in one round — this is the reason it is worth a card

Both dev agents dispatched by this seat today hit it on different cards, neither having read the other's report:

• [finding] check:i18n-coverage resolves its population CWD-relatively, so an off-root run reports OK over a scan of nothing #10907 (PR fix(scripts): anchor check-i18n-coverage to a module-derived root and refuse an empty population #11397), in its own deviations: "Note: --workspace-concurrency is rejected by pnpm 10 for install (unknown option) — the toolchain note in the seat brief applies to filtered runs, not to install."
• @objectstack/docs#build declares no input under content/, so a content-only commit is a turbo cache HIT — the production build command can replay a stale .next #11264 (PR fix(build): declare content/** as an input of @objectstack/docs#build #11418), independently: "pnpm install --workspace-concurrency=2 is REJECTED by pnpm 10.31.0 … The flag exists for pnpm --filter ... run, not for install. Re-ran plain pnpm install (exit 0, 4.8s). Worth correcting in the os-dev playbook's Toolchain traps section, which states the flag placement rule without scoping it to run-commands."

Same round, same seat, same wasted cycle, arrived at twice. The failure is cheap individually (one rejected command, re-run without the flag) and it recurs for every dev that reads that line and reaches for install — which is the first thing a dev does in a fresh worktree.

⭐ Both devs also independently recorded the correct usage, so the fix is not a research task: the flag is valid for filtered run-commands (the #10907 dev used --workspace-concurrency=2 before --filter successfully on a build) and invalid for install.

Suggested shape (not a decision)

Scope the existing sentence to run-commands, and state the install exception in the same breath, so a reader cannot acquire half the rule. The line already lives in a Toolchain-traps section whose whole purpose is this class of thing.

Dedup

Searched before filing: no open card carries this. Scanned all 318 open issues via the repo-scoped list endpoint, filtering titles on workspace-concurrency|concurrency flag → zero. Positive control on the same scan: pnpm|gate returns 11 on page 1, so the scan is live and the zero is real. (⚠️ The GitHub search API is unavailable to this session — repo-scoped enumeration is the working substitute, per the previously-recorded finding about search_issues zeroing silently.)

Not asserted

⛔ Not claiming the flag is useless — it demonstrably works for filtered run-commands, which is what the line was written for. The defect is the missing scope, not the rule. ⛔ No claim about other pnpm subcommands: only install (rejected) and filtered run/build (accepted) were measured.

[os-steve]

Independent datapoint from the #10166 devx lane (session session_015ahemw8RcTgqtxrj15PEZx), 2026-08-23 — a third seat, tripped in the first minute of the task.

Following os-dev.md's placement rule literally, on the first command of a fresh worktree:

pnpm install --workspace-concurrency=2 --filter "@objectstack/types..."
→ ERROR Unknown option: 'workspace-concurrency'
 Did you mean 'network-concurrency'? Use "--config.unknown=value" to force an unknown option.
 For help, run: pnpm help install

Placement was correct per the rule (before --filter); the flag simply does not exist on install in pnpm 10.31.0. Dropping it made the identical command succeed (Done in 1.9s). Cost is one round-trip, not a lock hold — but it lands on the very first command an agent runs in a new worktree, which is where a wrong instruction is most expensive to doubt.

⚠️ Worth noting for whoever fixes this: --workspace-concurrency is accepted on pnpm run/recursive script execution, so the rule is not wrong, it is unscoped — right for one invocation form, silently rejected on another. That is the same shape as #10166 (a rule correct for one invocation form and silently wrong for another), and #10166's landed fix took the corresponding shape: state the invocation form inside the rule. ⛔ Not fixed there — that PR touches rule 3 only and leaves this trap entry untouched, deliberately.

One constraint the fix will hit: .claude/agents/os-dev.md is at a zero-headroom line ratchet (405/405, check:pm-skill-ratchet), so the correction has to be a net-zero rewrite of the existing two-line entry, or carry a quoted maintainer ruling raising the ceiling.

---

Generated by Claude Code

---

Generated by Claude Code