Test

Progress Contract

Register these steps as a native task list at Step 1, before running. Report progress as "N steps remaining, size class S/M/L" — never wall-clock ETAs.

Steps: (1) read-config, (2) compute-diff, (3) select-tests, (4) run-tests.

Arguments

• scope — optional path. Test files/dirs → run exactly those (skip diff mapping). Source paths → restrict diff selection to changes under that subtree. Mutually exclusive with --all; if both are given, error and ask the user to choose.
• --all — full suite. Mutually exclusive with scope.

Workflow

Step 1 — Read project config

Read the host project's CLAUDE.md for:

• test_command — command used to run tests.
• subset_syntax — how to pass a file or module subset (e.g. pytest {files}).
• weight — heavy (suite takes ~5+ minutes) or light.

If CLAUDE.md is absent or missing a test_command:

• State explicitly that no test command was found.
• Detect from repo artifacts: pyproject.toml or pytest.ini → pytest; manage.py → python manage.py test; package.json → npm test; go.mod → go test ./...; Cargo.toml → cargo test.
• Announce what was detected before running.

Step 2 — Compute diff

Resolve the base branch: git symbolic-ref refs/remotes/origin/HEAD (strip to branch name); if unset, use main if it exists, else master. State the chosen base in the selection printout.

Combine git diff HEAD (working tree + index) with commits on the current branch not yet on the base branch.

If the combined diff is empty:

• Report: "no changes detected."
• Suggest re-running with --all.
• Exit without running tests.

If --all was passed, skip directly to Step 4.

Step 3 — Select tests

Map changed source files to test files using, in order:

1. Explicit rules in host CLAUDE.md (e.g. test_mapping: {src/foo.py: tests/test_foo.py}).
2. Mirrored paths — src/foo/bar.py → tests/foo/test_bar.py (or bar_test.py).
3. Same-name — any file named test_<module> or <module>_test anywhere in the repo.
4. Import heuristics — test files that import the changed module.

ALWAYS print the selection and rationale before running:

selected 4 of 812 test files: tests/foo/test_bar.py (mirrored path), tests/test_baz.py (import match)

Silent gaps are forbidden. If a changed file maps to no test file, state that explicitly.

If the selection is empty and weight: heavy:

• Report: "no targeted tests found; run with --all to execute the full suite."
• Exit.

If the selection is empty and weight: light:

• Report the gap and run the full suite.

Step 4 — Run tests ← STOP when heavy + --all

If weight: heavy and --all was passed, confirm with the user before running the full suite.

Run using the resolved command and subset_syntax for the selected files. For --all (once confirmed on heavy, or immediately on light), omit the file filter.

---

Shared Conventions

• Commits: conventional format type(scope): brief description — no AI attribution, no Co-Authored-By lines of any kind.
• Never push directly to protected branches (protected branches — see the octo guard's list).
• Never use --no-verify or force-push.
• Parallel-first: dispatches that do not consume each other's output MUST go in a single message. Dispatching sequentially what could run concurrently is a defect, not a style choice. Cap ≈10 concurrent lanes; more work than lanes → batch waves.
• Reader-first output: lead with the outcome in one sentence; keep the visible reply short and dev-readable — only what changes the reader's next action. Full detail (complete reports, evidence, logs) goes to a file under .claude/octo/reports/YYYY-MM-DD-<skill>-<slug>.md with the path given in chat — never dumped into the conversation.