worktree-fanout-verification-gate

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

1. 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.
2. 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.
3. 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.
4. 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).