Worktree Isolation

Worktree Isolation

Every issue gets its own sandbox — and enforcement is non-optional

---

The Principle

Each GitHub issue gets its own git worktree. Agents never modify main directly. This prevents conflicts when multiple agents work concurrently and ensures every PR has a clean diff.

main (protected)
├── worktree: AssemblyZero-838/ (branch: 838-refactor)
├── worktree: AssemblyZero-840/ (branch: 840-fix)
└── worktree: AssemblyZero-850/ (branch: 850-refactor)

---

How It Works

Workflow	Creates Worktree?	Command
run_requirements_workflow.py	Yes (LLD work)	Auto-creates ../AssemblyZero-{ID}/
run_implement_from_lld.py	Yes (implementation)	Auto-creates ../AssemblyZero-{ID}/
Both	Cleanup after merge	git worktree remove ../AssemblyZero-{ID}

Each worktree has a full repo copy on an independent branch. File changes in one worktree cannot affect another.

---

Why Not Just Branches?

Branches share the working directory. With 3–4 agents running concurrently:

Approach	Concurrent Agents	Risk
Branches only	Agent A checks out 840-fix, Agent B checks out 838-refactor	File conflicts, corrupted state, lost work
Worktrees	Agent A works in AssemblyZero-840/, Agent B in AssemblyZero-838/	Physically separate directories — zero conflict

---

The Enforcement Story

The Default Was Wrong (#822)

Originally, --no-worktree was documented as the default. This trained agents to lock main by running implementations directly on the main branch.

Fix: Worktree is now the DEFAULT. --no-worktree requires explicit opt-in and produces a warning. Agents that were trained on the old documentation now get worktrees automatically.

Requirements Workflow Too (#825)

run_requirements_workflow.py was missing worktree enforcement — agents wrote LLDs directly on main. Fixed to create worktrees for LLD work, not just implementation.

Agent Bypass Incident (#733)

A sub-agent blocked on permissions fell back to running on main instead of in its assigned worktree. The permissions dialog interrupted the worktree setup, and the agent proceeded without isolation.

Fix: Explicit worktree validation at workflow entry points — if the worktree doesn't exist, the workflow fails rather than silently falling back to main.

---

Lineage Archival

Before creating a PR, workflow artifacts are archived inside the worktree:

# Inside the worktree:
poetry run python tools/archive_worktree_lineage.py \
    --worktree . --issue {ID} --main-repo .

git commit -m "chore: archive workflow lineage (Closes #{ID})"
# Then push and create PR

This ensures the PR includes the full decision trail: LLD, implementation spec, test reports, Gemini verdicts.

---

Cleanup Protocol

After merge:

git worktree remove ../AssemblyZero-{ID}
git branch -d {ID}-fix && git checkout main && git pull

Worktree and branch are removed. main is updated. No dangling state.

---

Related

• Implementation Workflow — The pipeline that uses worktrees
• Safety & Guardrails — Worktree as rollback mechanism
• Cerberus PR Governance — What happens after the PR is created