docs(agents): show the targeted-vitest spelling and refuse the bare separator

[os-steve]

Part of #10166 — this lands triage's parts (1) and (2). It deliberately does not land the PreToolUse hook (A) or the os-verify-lock.sh refusal line (B) that the 2026-08-21 PM ruling adopted; triage's 2026-08-22 re-scope excluded tooling from this card, so those remain unimplemented and the card stays open for them.

⚠️ Governed surface — do not queue

Both files are governed (.claude/**, AGENTS.md). This PR stays draft and waits for a human merge: no ready flip, no auto-merge, no merge queue.

The defect

os-dev.md rule 3 named pnpm --filter <pkg>, vitest --maxWorkers=2 and turbo --concurrency=2without ever showing how they join. A gap that forces an invention is worse than a wrong statement, because every reader invents the same wrong thing — and npm semantics supply --.

Measured, on @objectstack/types (13 test files, test script is exactly vitest run)

spelling	result
pnpm --filter <pkg> test -- --maxWorkers=2 src/keyset-walk.test.ts	banner echoes vitest run -- --maxWorkers=2 … · 13 files / 362 tests · exit 0
whole suite, no pattern at all	13 files / 362 tests — byte-identical to the "targeted" run above
pnpm --filter <pkg> test --maxWorkers=2 src/keyset-walk.test.ts	1 file / 12 tests / 285ms
pnpm --filter <pkg> exec vitest run --maxWorkers=2 src/keyset-walk.test.ts	1 file / 12 tests / 399ms
pnpm exec vitest run src/keyset-walk.test.ts from the package cwd	1 file / 12 tests / 269ms
pnpm exec vitest run -- src/keyset-walk.test.ts (stray --, no package script)	13 files / 362 tests

The last row matters: the exec route our own docs recommend is swallowed identically. Nothing about avoiding the package script protects you — the separator does.

The card's unverified half: --maxWorkers=2 was swallowed too

Probed against the exact parser (vitest 4.1.10 → cac 7.0.0, resolved from vitest's own tree; the earlier note on the card said 6.7.14):

["run","--maxWorkers=2","src/keyset-walk.test.ts"] options.maxWorkers = 2 args = ["src/keyset-walk.test.ts"] options['--'] = []
["run","--","--maxWorkers=2","src/keyset-walk.test.ts"] options.maxWorkers = undefined args = [] options['--'] = ["--maxWorkers=2","src/keyset-walk.test.ts"]

Both directions confirmed in vitest itself: an unknown flag before the separator throws CACError: Unknown option `--thisFlagDoesNotExist` (exit 1); the same flag after it exits 0 with no error, and a --filesOnly sitting after it is ignored as well (362 test lines listed instead of a file list).

⇒ Every run that used the -- spelling had no worker cap. The concurrency discipline was inert in the same breath as the file filter.

Net-zero, because both homes are at zero-headroom ratchets

check:pm-skill-ratchet sets each ceiling at the landed line count: os-dev.md 405/405, AGENTS.md 961/961. Raising a ceiling requires a maintainer ruling quoted in the PR, and this PR has none — so the fix is a rewrite, not an addition (os-dev.md stays at exactly 405, AGENTS.md at 961). That also follows the ratchet header's own instruction: "provenance is one line, stories live on cards, not in operational text." The measurements above therefore live here and on the card, not in the agent definition.

A first draft added a full Toolchain traps entry with the mechanism (+13 lines) and was rejected by the ratchet. The landed rule carries the spelling and the refusal; the mechanism stays on the card.

Why this spelling and not the one triage named

Triage named pnpm exec vitest run <file> "from the right cwd". Verified — it works (row 5). The rule documents pnpm --filter <pkg> exec vitest run --maxWorkers=2 <file> instead, because it is the strict superset: it needs no cd, and agent bash calls in this container reset cwd between invocations, so a cwd-dependent spelling would reintroduce exactly the form-scoping defect this card is about. Both were measured; the more robust one is documented.

Scope

• ⛔ No wrapper script and no lint rule (triage ruling 3).
• ⛔ [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 #11419 (the unscoped --workspace-concurrency placement rule) is not addressed here and remains open — it is its own unassigned card. I did trip over it first-hand while setting up: pnpm install --workspace-concurrency=2 --filter … → ERROR Unknown option: 'workspace-concurrency'. One more datapoint for that card, fixed in neither file here.
• No changeset: nothing publishable changes (skip-changeset).

Gates

All 12 families derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no path arguments) green at 685883f. Repo-wide pnpm lint is CI's: both changed files report isPathIgnored: true from eslint's own flat config (2 files submitted, 0 linted, 0 rule results), so no untouched file's verdict can move.

Generated by Claude Code

---

Generated by Claude Code