worktree-lifecycle

worktree-lifecycle

Governance layer for worktrees that already exist (or are about to). Creation mechanics — directory convention, ignore-safety, clean baseline — live in using-git-worktrees and are referenced, never restated here. This skill owns everything after the spawn: what the worktree is allowed to touch, when it is merge-ready, and when it may be removed.

When to use

• Deciding whether a task should be isolated in a worktree at all
• Declaring which paths a worktree owns so parallel agents stay disjoint
• Answering "is this worktree merge-ready?" — status, dirty state, ahead/behind, verification evidence
• Running the scoped verification for a worktree's declared change
• Removing a finished worktree without losing commits

Do NOT use when:

• Creating the worktree — that is using-git-worktrees (Iron Law: no worktree without verified ignore + clean baseline)
• Plain branch work (switch, rebase, PR) without worktree isolation — git-workflow
• Picking a subagent-orchestration mode — subagent-orchestration selects the mode; this skill governs the worktrees a chosen mode uses

The Iron Law

EVERY GOVERNED WORKTREE DECLARES ITS SCOPE. NO REMOVAL WHILE
UNIQUE UNMERGED COMMITS EXIST. INHERITED COMMITS ARE NEVER DROPPED.

Procedure

1. Decide isolation

Isolate when any holds; otherwise stay on the current branch (per the Do-NOT list in using-git-worktrees):

• Parallel agents/sessions must not share a working directory
• The current branch is mid-work and a stash/switch would risk state
• The change is exploratory and may be thrown away whole
• A long-running build/test occupies the current worktree

Then create via using-git-worktrees (or the host primitive — § Host-native mapping below), declare the scope lock (§ 2), keep status honest (§ 3), and gate removal (§ 4).

2. Scope lock

At worktree start, write a .worktree-scope.md note at the worktree root and keep it untracked via .git/info/exclude (shared exclude — one line .worktree-scope.md, no commit needed):

## Scope lock
- branch: <branch-name>
- owns: <path or glob list — the ONLY paths this worktree edits>
- task: <one-line task statement>
- created: <ISO date>

The lock is the disjointness contract between parallel worktrees. A diff that leaves the owned paths is scope creep — stop and surface, per scope-control. Check mechanically:

git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
# every path must match an `owns:` entry

3. Status / merge-ready checklist

A worktree is merge-ready only when ALL hold:

1. Clean tree — git status --porcelain is empty.
2. Scope lock respected — changed files ⊆ owns: paths (command above).
3. Verification evidence attached — the scoped probe for the declared change ran fresh and passed (per verify-before-complete); record command + result tail in the status report. No fresh evidence → not merge-ready, regardless of how the diff looks.
4. Ahead/behind known — git fetch origin --quiet then git rev-list --left-right --count HEAD...origin/<base>. Behind → flag; divergent (both sides non-zero on a pushed branch) → route to git-workflow § Divergent-State Recovery.
5. No inherited-commit drops — commits on the branch that this session did not author stay on the branch; never rebase-out, reset-away, or exclude them (rule git-history-discipline, shared-branch Iron Law).

4. Cleanup discipline

Removal is gated by the deterministic helper (edge-case-tested: detached HEAD, branch without remote, tag-only reachability, deleted remote branch, untracked files, paths with spaces):

npx tsx node_modules/@event4u/agent-config/src/scripts/worktree_cleanup_check.ts check <worktree-path>

Exit 0 → removal allowed; exit 1 → refuse, gates in order:

1. Detached HEAD — no branch to judge reachability for; resolve manually first.
2. Unsaved work — git status --porcelain non-empty, untracked files included (never answer with --force).
3. Unique-commit check — commits reachable from the worktree branch but from no other ref (branches, remotes, AND tags — a tag counts as reachability). Non-empty → refuse removal; the branch holds work that exists nowhere else. Surface the commit list and hand back — merging or preserving them is the user's call (git-history-discipline).

Then: remove, never delete — git worktree remove <path>, then git worktree prune. Branch deletion is a separate, permission-gated step (scope-control); never force-delete (-D) as part of cleanup. Cross-worktree scope-lock overlaps are scanned via worktree_cleanup_check scope-overlap (surfaced by /worktree status).

Whole-checkout sweeps. Worktrees accumulate one per branch and are never removed on merge; git worktree prune only clears registrations whose directory is already gone, so it does nothing for the live ones. Classify the whole set in one pass rather than gate-checking by hand:

npx tsx node_modules/@event4u/agent-config/src/scripts/worktree_cleanup_check.ts inventory [repo] [--json|--plan]

safe requires all of: on a branch, merged into the trunk, clean, inside a conventional worktree root (.claude/worktrees/ or .worktrees/), and no git activity for 48 h. review keeps its disqualifying reason so the next sweep starts from a shorter list; live means another session may hold it. A worktree outside the conventional roots is never safe — sitting beside the repo it can be mistaken for a sibling package, so its removal stays a judgement call.

The mode reports only. --plan prints git worktree remove plus git branch -d (never -D) for the safe set; running it is a bulk deletion needing the user's explicit this-turn approval (non-destructive-by-default), which a single earlier approval never covers.

Host-native mapping

The mapping changes only who creates the directory. Scope lock, merge-ready checklist, and cleanup gates are host-independent.

Gotcha

• git log <branch> --not --all is always empty — --all includes the branch itself, so the naive check never fires. The --exclude="refs/heads/<branch>" --all variant is also unreliable when combined with --not (observed on git 2.39). Use the for-each-ref expansion above — it enumerates every ref except the branch explicitly.
• Scope note committed by accident — .worktree-scope.md must be in .git/info/exclude; .gitignore would be a tracked change outside the scope lock.
• "Unchanged worktree" ≠ "no unique commits" — a host auto-clean only covers worktrees with no changes; a worktree with committed but unmerged work still needs the unique-commit gate.
• Stale ahead/behind — always git fetch before the rev-list --left-right count; a cached view reports merge-ready on a diverged branch.

Output format

1. Worktree — path + branch, and the scope-lock owns: list
2. State — clean/dirty, ahead/behind vs base, merge-ready verdict with the failing checklist item named when not ready
3. Evidence — verification command(s) run + result tail, or "none attached" stated explicitly
4. Next step — merge path, missing verification, or cleanup verdict (allowed / refused with the unique-commit list)

Do NOT

• NEVER remove a worktree whose branch has commits on no other ref
• NEVER git worktree remove --force past a dirty tree
• NEVER drop, rebase-out, or reset-away inherited commits (rule git-history-discipline)
• NEVER report merge-ready without fresh verification evidence
• NEVER edit outside the scope-lock owns: paths without surfacing it

Handover