<!--
  scaffold: worktree-isolation.md
  bucket: engineering-discipline (Bucket 5)
  what belongs here: the DOUBLE-FACED worktree isolation rule.
    - In the PA's OWN estate (agents, operator, projects), parallel workers with worktree isolation are fine — PA is the coordination point.
    - In engineering PROJECT repos (downstream apps, third-party sites, non-PA repos), NEVER concurrent WRITE workers; writes must be sequential.
    - Multiple concurrent READ workers are always fine.
    - Rationale.
-->

# Worktree isolation — double-faced rule

## The rule

Parallel worker dispatch with `isolation: "worktree"` behaves differently in two contexts.

**Face A: the PA's OWN estate (this operator repo — the `agents/`, `operator/`, `projects/`, `work/` tree).** Parallel workers with worktree isolation is FINE. The PA is the coordination point; all writes flow back through the PA's merge, so concurrent worker branches don't step on each other.

**Face B: engineering PROJECT repos (downstream applications, third-party sites, product codebases, anywhere the PA is NOT the sole coordinator).** NEVER run more than one WRITE worker concurrently. Writes MUST be sequential — dispatch, wait for return + merge, then dispatch the next.

**Both faces: multiple concurrent READ workers are always fine.** Read-only workers (Explore-style survey, investigation, planning) can run in parallel in any context.

## Why the two faces exist

**Face A rationale.** In the PA's own estate, every write goes through the PA. Two worker branches with disjoint file targets merge cleanly. Two workers with overlapping file targets are a brief bug (the PA shouldn't have dispatched them in parallel on the same files), not an isolation failure.

**Face B rationale.** In project repos, coordination flows through the project's own merge process (PR review, CI, release). Two concurrent workers cutting worktree branches produce two PRs that may need reconciliation; the reconciliation costs more than sequential execution. Plus the project repo has other humans / CI / release tooling that may not tolerate rapid parallel branch creation.

## What worktree isolation actually gives you

From `dispatch-envelope.md`:

- **Isolated:** working tree, git branch, staged changes, `git status`. Repo-relative operations are per-worktree.
- **NOT isolated:** `/tmp`, `$HOME`, network, credentials, MCP session state, any absolute path outside the repo root, environment variables.

Treat worktree isolation as "git-safe parallel edits", NOT "sandboxed process". Cross-worker collisions on `/tmp` files or MCP sessions still happen.

## Cleanup

Worktrees where the worker made changes do NOT auto-clean. They persist at `.claude/worktrees/agent-{agentId}/`. Prior sessions accumulate stale worktrees; periodic `git worktree prune` + directory sweep is warranted.

If the operator ships a worktree-hygiene tool (a scheduled sweep), reference it here.

<!-- OPERATOR: name any worktree-hygiene tool or convention here. -->

## Related

- CLAUDE.md.template Bucket 5 rule 7.
- `dispatch-envelope.md` § Worktree Isolation — the fuller detail.
- `blast-radius-and-safety.md` — the write-safety context worktrees fit inside.