From cf83c5827dd7785876dc3c92ad7c10cdf2196c9f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 6 May 2026 07:37:38 +0100 Subject: [PATCH] docs: clarify targeted local validation --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6448293e275..c1a02f00248 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,8 +57,8 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work. - Linting: use repo wrappers (`pnpm lint:*`, `scripts/run-oxlint.mjs`); do not invoke generic JS formatters/lints unless a repo script uses them. - Heavy checks: `OPENCLAW_LOCAL_CHECK=1`, mode `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`; CI/shared use `OPENCLAW_LOCAL_CHECK=0`. - Crabbox: preferred live scenario runner when available. It has Linux, Windows, and macOS workers/targets; pick the OS that matches the bug. If unavailable, use the local system, Docker, Parallels, or CI live lane that proves the same behavior. -- Blacksmith/Testbox: on maintainer machines with Blacksmith access, broad/shared validation defaults to Testbox. This includes `pnpm check`, `pnpm check:changed`, `pnpm test`, `pnpm test:changed`, Docker/E2E/live/package/build gates, and any command likely to fan out across many Vitest projects. Do not start those broad gates locally unless the user explicitly asks for local proof or sets `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`. -- Local validation: targeted edit loops only, such as `pnpm test `, targeted formatter checks, and small lint/type probes. If a local command expands beyond targeted proof, stop it and move the broad gate to Testbox. +- Blacksmith/Testbox: use when the validation needs the remote environment, broad/shared suite capacity, cross-OS/package/Docker/E2E/live proof, or another end-to-end setup that is meaningfully better off-host. Broad fan-out commands such as `pnpm check`, full `pnpm test`, Docker/E2E/live/package/build gates, and wide changed gates belong in Testbox by default. Do not start those broad gates locally unless the user explicitly asks for local proof or sets `OPENCLAW_LOCAL_CHECK_MODE=throttled|full`. +- Local validation: targeted edit loops stay local, such as `pnpm test `, narrow `pnpm test:changed` selections, targeted formatter checks, and small lint/type probes. If a local command expands beyond targeted proof, stop it and move the broad gate to Testbox. - Testbox use: run from repo root, pre-warm early with `blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90`, reuse the returned `tbx_...` id for all `run`/`download` commands, and stop boxes you created before handoff. Timeout bins: `90` minutes default, `240` multi-hour, `720` all-day, `1440` overnight; anything above `1440` needs explicit approval and cleanup. - Testbox full-suite profile: `blacksmith testbox run --id "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test"`. For installable package proof, prefer the GitHub `Package Acceptance` workflow over ad hoc Testbox commands. @@ -98,8 +98,8 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work. - extension tests: extension test typecheck/tests - public SDK/plugin contract: extension prod/test too - unknown root/config: all lanes -- Before handoff/push for code/test/runtime/config changes: run `pnpm check:changed` in Testbox by default on maintainer machines. Tests-only: run `pnpm test:changed` in Testbox by default. Full prod sweep: run `pnpm check` in Testbox. Use local only for narrow targeted proof or when explicitly requested. -- If `pnpm test:changed` or `pnpm check:changed` selects broad/shared lanes, it belongs in Testbox; do not let it continue locally after it fans out. +- Before handoff/push for code/test/runtime/config changes: prove the touched surface. Use local targeted tests/checks for narrow changes; use Testbox when `pnpm check:changed`, `pnpm test:changed`, or other validation selects broad/shared lanes or needs a remote/end-to-end environment. Full prod sweeps (`pnpm check`, full `pnpm test`) belong in Testbox by default on maintainer machines. +- If `pnpm test:changed` or `pnpm check:changed` stays narrowly scoped, it can run locally. If it fans out into broad/shared lanes, stop it and move the broad gate to Testbox. - Docs/changelog-only and CI/workflow metadata-only changes are not changed-gate work by default. Use `git diff --check` plus the relevant formatter/docs/workflow sanity check; escalate to `pnpm check:changed` only when scripts, test config, generated docs/API, package metadata, or runtime/build behavior changed. - Rebase sanity: after a green `pnpm check:changed`, a clean rebase onto current `origin/main` does not require rerunning the full changed gate when the rebase