Offer optional worktree isolation when another task uses the repo

[geldmacher]

Why

Two Workflow tasks that plan or implement in the same checkout step on each other. One agent’s edits land in the other’s dirty tree, branches get mixed, and the merge is harder than the product change. A hard lock would also block intentional parallel work, and forcing a git worktree for every plan would add ceremony to the common case: one clean checkout, one task.

The check is a soft warning at the start of planning (and before the first edit of a sequence that does not already have a choice). The human can continue carefully, wait, or isolate. A clean sole checkout, including a clean idle worktree, stays put: no question, no worktree. Commits that only exist on another branch do not count as overlap.

A worktree avoids the checkout clash now. It does not merge itself. Folding the branch back, or throwing the attempt away, stays an explicit request so unrelated dirt and other people’s worktrees are not swept up at the end.

How

The procedure lives in one shared reference, references/concurrent-work.md, loaded only when detection finds overlap or the plan already records a checkout choice. That keeps it out of the default plan, review, correction, and Auto-Work context. A separate worktree-isolation or reconcile-worktree skill would repeat the same steps at discovery time; the phases already have entrypoints, so they cross-link instead.

Detection uses git (common directory, git worktree list, this checkout’s uncommitted changes) plus plans and reports already in the task, and host-visible sessions when the host already exposes them. Another worktree counts only when that checkout has uncommitted changes, or a handoff or host-visible task names both this repository and that checkout. Commits that only exist on its branch do not. A clean idle worktree does not. Stale local branches with no worktree and no unfinished handoff do not either. Nothing is written to a new lock file or plan registry. The native plan is the cold-start record Implement already uses: choice, base, branch, path, what must be preserved, and whether the other owner and the overlapping files are clear.

One recommendation, first match wins:

1. The other workstream is mid-edit on files this task must change: wait.
2. An active workstream or a dirty checkout this task must leave untouched, and this host can start a child agent with a workspace outside the current checkout: isolate.
3. That same overlap, but the host cannot do that or it is unclear: continue carefully, and say that independent review would miss the isolated checkout. A sibling directory is not assumed to be visible.
4. The human wants one checkout, or a worktree cannot be created: continue carefully.

git worktree add runs only as the first implementation step, for the branch and path named in the plan, and only when the plan says the other owner and the overlapping files are clear. A missing clarity field pauses and does not create the worktree. Light approval covers that step. Dark may take it only with that clear field. The step still does not authorize commit, push, or merge.

Agent-facing behavior:

• plan-work inspects before questions. A clean idle worktree is not another workstream. Overlap produces the three options and the one recommendation above. The vague-scope decision round is unchanged and stays a separate product question.
• Implement follows the recorded choice and the clarity field. Missing choice plus other in-flight work in this checkout sends the executor back to the reference before editing.
• Auto-Work applies that same check before the first edit. The reviewer is started with the worktree as its workspace when the host can give it a workspace outside the current checkout. When that path cannot be read, the review reports missing proof and does not treat the primary checkout as the result.
• Review reads the recorded branch and worktree and stays read-only.
• Correct patches that same worktree and leaves the other checkout alone. Copying the result back is reconcile, not correction.
• Reconcile merges or rebases only into the destination the human named, refuses a dirty destination, rechecks the merged tree, then removes only this assignment’s worktree. Abandon shows uncommitted work and deletes nothing until discard is confirmed.
• learn-from-work and verification-work edit and drive the checkout that holds the product change. A git worktree does not replace test-data or process isolation. A repeated collision stays on the existing correction ladder: prefer a check, or this shared procedure, over a new project rule that copies the steps.
• work-status, pause-safely, session-pickup, and parallel hillclimb experiments carry the path, branch, and choice.

Context: default phase scenarios omit the reference. The sharper rules stayed in references/concurrent-work.md. plan-work, reviewer.md, and implementation-work.md were not lengthened.

Checks

• npm run context-budget and npm run link-check passed. node --test tests/concurrent-work.test.mjs passed.
• Earlier full npm test on the first revision: 78 passed. The 24 GitHub release tests fail in this environment because origin is rewritten to an authenticated URL (repository must identify one GitHub repository). That check is unchanged by this diff.