How do I install the Worktree Fanout Verification Gate skill?

Run npx skillmds@latest add oimiragieo/worktree-fanout-verification-gate in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Worktree Fanout Verification Gate safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Worktree Fanout Verification Gate?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Worktree Fanout Verification Gate free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Worktree Fanout Verification Gate?

oimiragieo (@oimiragieo) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Worktree Fanout Verification Gate by oimiragieo

Name: Worktree Fanout Verification Gate
Author: oimiragieo

Worktree Fanout Verification Gate

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.

oimiragieo Updated Sep 17, 2026 0 repo stars

File contents

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.

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).

---name: worktree-fanout-verification-gatedescription: 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## OverviewA 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 agentliterally 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 agentreports 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 order1. **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, aninstaller test mismatch, a contract-test break, a repo-wide formatting failure, and a corpus-IDFranking 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 (themap-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 realbinary).

Frequently asked questions