Skip to content

Worktree isolation policy (STANDING, council-approved 2026-07-11)

Fleet-wide. Every machine, every model, every harness. Refines the P2.5 concurrent-worktree-ownership standard (concurrent-worktree-ownership.md) with the exception/friction rules the council settled.

Councilled 2026-07-11 (fable tier, chaired manually — auto-chairman timed out). Seats: Claude / Codex / Gemini / Grok (local Ollama failed; both house councils timed out). Peer ranking A > B > D > C, Claude's answer won 3/4 votes.

The load-bearing distinction

Worktrees fix exactly one hazard: concurrent sessions clobbering each other's uncommitted working state (the documented sweep incidents). They do NOT fix contention on a single hot file every session edits (delivery board, status ledger). Putting a board flip in a worktree just relocates the collision from checkout-time to merge-time — every merge conflicts on the same file, adding rebase tax while removing zero risk.

So policy splits by hazard class, never by change size. "Tiny fix" and "docs-only" are NOT valid exceptions — a one-liner that grows to three files mid-build is exactly when a shared checkout gets polluted, and agents misjudge scope. Rejected unanimously.

Rule 1 — Universal isolation (default for all real work)

Any change to code, tests, config, CI, or reviewable docs (architecture, specs, learning content, runbooks that change ops/security/agent behavior):

  • git worktree add + branch wt/WT-xxxx/<ticket>, build/edit/test only there.
  • Standing per-commit review gate (/council-code-review) applies.
  • Land via the vetted-branch FF-push pattern when main is contended.
  • No size exemption. One-liners included.

Exceptions — main checkout allowed ONLY for these classes

E1 — Board / status metadata only

Delivery-board status flips, ticket-state ledger updates. Guards (all required): - Path allowlist, not agent judgment — e.g. docs/BOARD.md, board ticket files. Content = status-field flips + appends only; any rewording of a doc disqualifies → worktree. - git status --porcelain empty before edit (clean precondition). - Atomic sequence, sub-60s exposure: git pull --rebase → edit → git add <exact path> → commit → push. Never leave the edit uncommitted. - Broad staging stays banned (git add -A / git add . / commit -a) — the PreToolUse guard enforces this fleet-wide. - Non-FF push → rebase, retry once; second rejection = real contention → escalate to a worktree or hand to the lane owner. - Prefer a single board writer when multiple sessions are active. - Exempt from /council-code-review by the same path allowlist (metadata, not code).

E2 — Landing / integration ops

FF-merge, restack, pull, push of already-vetted branches. Not "building in main." Guard: no feature edits in the operation; abort if unexpected dirty files appear.

E3 — Emergency repo hygiene

Fixing broken repo metadata that blocks worktree creation or branch landing. Guard: smallest possible change, exact-path staging, immediate commit, retrospective review.

Explicitly rejected

  • "Trivial docs/text fixes" in main + blanket review-skip for non-executable files (Gemini) — unbounded agent judgment; CI YAML, configs, and agent-policy docs are non-executable but behavioral. Last place, unanimous.
  • Docs-in-main under an "exclusive claim" (Grok E2) — an informal lock has no enforcement across a multi-session fleet; it is the brittle mechanism that caused the past sweep incidents. Flagged by 3/4 reviewers. Docs go through a worktree.

YELLOW / friction

The pressure to carve out "tiny fix" exceptions is really review-gate cost, not worktree cost — git worktree add is seconds and zero tokens. Fix by amortizing the gate, not by weakening isolation:

  • Batch micro-fixes per lane — several one-liners under one ticket lane share one worktree, one review pass, one merge. Fits the YELLOW lane-consolidation model (worktree-consolidation.md).
  • Reuse long-lived per-lane worktrees; prune weekly. Don't add/remove per micro-edit.
  • ww-start / ww-land helper scripts attack ceremony cost (complementary).

One line

Agents never develop in the main checkout. Isolate by default, one worktree per ticket-lane, batch micro-fixes to amortize review. Only pure board-status flips (path-allowlisted, atomic, serialized), branch-landing ops, and emergency repo hygiene may touch main.

Council report: llm-council/reports/2026-07-11_142118_should-all-current-workwingman-ww-work.md