gates.json: test_affected has no cheap pnpm-workspace equivalent — add per-stack guidance

[robercano]

Context

gates.json defines a test_affected gate, wired to the Stop hook so an agent can't finish with a red affected-test run. But "test only what changed" isn't free in every stack:

• pnpm workspaces: no built-in affected filter without extra tooling — pnpm --filter "...[origin/main]" test exists but is awkward and flaky inside worktrees; turbo/nx add a dep.
• Foundry: forge test has no native "since base"; usually you just run all.
• Other stacks (cargo, go, gradle) each differ.

Adapting the template to a TS+Solidity monorepo, the pragmatic choice was test_affected = the full suite.

Suggestion

Add a short note (in GETTING_STARTED.md Step 3 and/or a gates.json comment) with per-stack options for test_affected:

• turbo/nx affected commands
• pnpm --filter "...[<base>]"
• "= full test suite" as a perfectly acceptable starting point (and the right default when the suite is fast)

Low-stakes, but it removes a head-scratch for new adopters and prevents a misconfigured test_affected from silently running everything (or nothing).

Found while using the template; tracked in the project's TEMPLATE_FEEDBACK log.

[robercano]

🤖 Proposed implementation plan

Size: XS (docs-only) · No mechanism change, no gate touches runtime.

Goal

Give adopters per-stack guidance for the test_affected gate so a misconfigured value can't silently run everything (or nothing), and make "= full suite" an explicitly-blessed default.

Files to change

1. docs/GETTING_STARTED.md — in the Step 3 gates section (around the test_affected bullet / the "don't point a gate at a command that can't pass" note), add a short callout block with per-stack options.
2. .claude/gates.json — add a sibling _test_affected_note string key next to test_affected (gate.sh only reads gates.<name>, so an extra _-prefixed key is inert — same convention as the existing _note).

Concrete content (the per-stack table)

Stack	Cheap test_affected	Notes
turbo	turbo run test --filter='...[origin/main]'	needs turbo
nx	nx affected -t test --base=origin/main	needs nx
pnpm (no turbo/nx)	pnpm --filter '...[origin/main]' test	flaky in worktrees unless origin/main is fetched first — see #9
cargo	cargo test (or cargo nextest run)	no cheap since-base; full suite is fine
go	go test ./...	already fast; no filter needed
Foundry	forge test	no native since-base — run all
gradle	./gradlew test	full suite

Plus the key message: test_affected = the full test command is a perfectly good default whenever the suite is fast — only reach for affected-filtering when the full run is too slow to gate on Stop.

Also call out the worktree gotcha: an affected-filter that diffs against origin/main needs that ref present in the worktree; recommend the setup hook from #9 (git fetch origin main) or falling back to the full suite.

Acceptance

• markdownlint docs/ clean (matches CI lint gate).
• node -e "require('./.claude/gates.json')" still parses; gate.sh test_affected behaviour unchanged (extra _-key ignored).

Dependencies / cross-refs

• Feeds Add a worked mixed-stack (TS + Solidity / Foundry) adapter example #6 (the mixed-stack example will cite this note).
• The worktree-fetch mitigation ties to Per-worktree setup/teardown lifecycle hooks so isolated workers can run all gates #9.