| name | worktree-fanout-verification-gate |
| description | Use when an orchestrator fans work out to worktree-isolated subagents (isolation:'worktree') and is about to integrate or PR the returned branches — especially when an agent reports "tests pass" / "N green" / "ruff clean". Worktree checkouts CANNOT self-test (no project venv), so their results are unverified hypotheses. Symptoms: parallel fan-out of code edits, "branch already used by worktree", Formatting/Linting CI failure after a green local run, scoped tests green but full CI red. |
Worktree Fan-out Verification Gate
Overview
A worktree-isolated subagent's output is a HYPOTHESIS, not a verified result. A worktree
(isolation:'worktree') is a bare git checkout with no project virtualenv, so the agent
literally cannot run the test/lint/type tools — uv run pytest|ruff|mypy (or npm test, etc.)
do not work there. The orchestrator is the only verification gate. Trust nothing the agent
reports about test/lint/type state until you re-run it yourself in the real environment.
When to use
- Orchestrating any
isolation:'worktree' fan-out that edits code.
- About to integrate returned branches or open a PR from them.
- Any agent reports "tests pass" / "N green" / "ruff clean" / "mypy clean".
The gate — per returned branch, in order
- Remove the worktree FIRST —
git worktree remove --force <path> before you checkout the
branch in the main repo. Otherwise "branch already used by worktree" blocks the checkout, AND if
you run tests in the main repo without switching, you silently exercise the BASE branch's code,
not the agent's — a false green.
- Verify in the REAL env — checkout the branch in the main repo (which has the venv) and re-run
the suite: e.g.
uv run --no-sync python -m pytest <changed files> -p no:cacheprovider -o addopts="" -q
ruff check + mypy. The agent's "N tests pass" is a hypothesis until this re-run confirms it.
- Format ALL agent-touched files — run the formatter (
ruff format --preview, prettier, etc.)
on EVERY file in git diff <base> --name-only, NOT just the ones you hand-fixed. Agents could not
run the formatter in the worktree, so their files arrive unformatted and the repo-wide format-check
CI job fails on files you never opened.
- Scoped-green is NOT CI-green — a changed-area test run can pass while full CI fails because:
(a) lint/format jobs run repo-wide; (b) ONE unrelated failing test reddens the whole test job across
every OS/version combo; (c) edits can have CROSS-CORPUS side effects (e.g. a BM25/IDF ranking shift
that flips a search/capsule result) that scoped tests never exercise. Run the full CI-equivalent, or
at minimum treat scoped-green as "not yet a merge signal."
Common mistakes
- Trusting "163 tests pass" from a worktree agent → re-run in the venv revealed 11 failures.
- Formatting only your hand-fixed files → CI "Formatting & Linting" red on the agent's other files.
- Checking out a branch while its worktree still exists → tests run the base branch's code, false green.
- Treating scoped-local-green as merge-ready → full CI surfaced 8 failures (one a cross-corpus IDF
ranking regression invisible to the changed-area tests).
Real-world impact (2026-06-29, tensor-grep PR #302)
A 6-agent worktree fan-out. This gate caught, in sequence: cuDF 11 test failures, lint/mypy gaps, an
installer test mismatch, a contract-test break, a repo-wide formatting failure, and a corpus-IDF
ranking regression — none of which the agents could self-detect, all of which would have shipped red.
Related
REQUIRED BACKGROUND for the orchestration side: the dynamic-workflow authoring discipline (the
map-ledger, tiering, and agent-output-is-a-hypothesis rules). See also verify-plan-against-code
(pre-build, citation-enforced seam check) and dogfood-the-shipped-artifact (post-release, the real
binary).
