Prove the touched surface first. Do not reflexively run the whole suite.

1. Inspect the diff and classify the touched surface:

- source: `pnpm changed:lanes --json`, then `pnpm check:changed`

- tests only: `pnpm test:changed`

- one failing file: `pnpm test <path-or-filter> -- --reporter=verbose`

- normal source checkout, source change: `pnpm changed:lanes --json`, then `pnpm check:changed`

- normal source checkout, tests only: `pnpm test:changed`

- normal source checkout, one failing file: `pnpm test <path-or-filter> -- --reporter=verbose`

- Codex worktree or linked/sparse checkout, one/few explicit files: `node scripts/run-vitest.mjs <path-or-filter>`

- Codex worktree or linked/sparse checkout, changed gates or anything broad: `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... --shell -- "pnpm check:changed"`

- workflow-only: `git diff --check`, workflow syntax/lint (`actionlint` when available)

- docs-only: `pnpm docs:list`, docs formatter/lint only if docs tooling changed or requested

2. Reproduce narrowly before fixing.

- Prefer GitHub Actions for release/Docker proof when the workflow already has the prepared image and secrets.

- Use `scripts/committer "<msg>" <paths...>` when committing; stage only your files.

- If deps are missing, run `pnpm install`, retry once, then report the first actionable error.

- In a Codex worktree or linked/sparse checkout, do not run direct local

`pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, or `scripts/committer` until

you have verified pnpm will not reconcile or reinstall dependencies. Use

`node scripts/run-vitest.mjs` for tiny local proof, `node

scripts/crabbox-wrapper.mjs` for Testbox, and `git commit --no-verify` only

after the relevant remote or node-wrapper proof is already clean.

- For Blacksmith Testbox proof, use Crabbox first. `pnpm crabbox:run -- --provider

blacksmith-testbox --timing-json -- <command...>` warms, claims, syncs, runs,

reports, and cleans up one-shot boxes. Reuse only an id/slug created in this

Use targeted file paths whenever possible. Avoid raw `vitest`; use the repo

`pnpm test` wrapper so project routing, workers, and setup stay correct.

When the checkout is a Codex worktree, prefer the direct node harness instead:

```bash

node scripts/run-vitest.mjs <path-or-filter>

```

That keeps the test scoped without giving pnpm a chance to run dependency

status checks or install reconciliation in a linked worktree.

## Command Semantics