/worktree

name: worktree
description: 'Use when work needs an isolated git worktree: new work, an existing ref, a gated feature workspace, a manifest-tracked loop run, or a candidate patch captured without touching the current checkout (`capture-isolated-patch`). Not for plain branches: use create-branch. Not for remote, credential, publish, deploy, or irreversible changes.'

Worktree isolation

Contract

| Field | Bound contract | |---|---| | Trigger | A new isolated worktree or branch is requested, an existing ref or PR needs isolation, feature work needs a gated workspace with setup and baseline tests (feature-gate mode), a run needs a manifest-tracked worktree (loop-run mode), or a candidate patch must be captured from an ephemeral worktree without touching the current checkout (`capture-isolated-patch` mode). | | Authority | Reversible local: writes only the worktree directory, `.worktrees/` or `.loop-worktrees/` entries, a gitignore entry, symlinked hooks, manifest bookkeeping, or (`capture-isolated-patch` mode) a fresh temporary worktree and binary-safe patch under its parent temporary directory; rollback is removing the worktree and reverting those entries. Capture-isolated-patch mode never writes the original checkout. Loop-run mode never passes `--force` to `git worktree remove`. No remote mutation. | | Side effect | Local write: creates or attaches an isolated git worktree and reports its exact path and status. Feature-gate mode also runs setup and the baseline test suite. Loop-run mode also maintains a status manifest under `.loop-worktrees/`. Capture-isolated-patch mode runs the command in an ephemeral worktree, captures stdout/stderr/exit code, and writes and returns a binary-safe patch file path or preserves the worktree on extraction failure. | | Done | `new-work` and `isolate-existing-ref` modes have an isolated workspace the harness can see and manage, with no phantom state. `feature-gate` adds a green baseline suite or surfaces a failure. `loop-run` adds a manifest where every worktree has a legal status and no removal used `--force`. `capture-isolated-patch` writes and returns a binary-safe patch file path and command results, removes its temporary worktree after successful extraction, or preserves it and reports extraction failure; the original checkout is unchanged either way. |

Inputs

1. Mode (required): one of `new-work`, `isolate-existing-ref`, `feature-gate`, `loop-run`, `capture-isolated-patch`. Default `new-work` when no ref is named and no gate, lifecycle, or patch capture is requested. 2. Ref to isolate (`isolate-existing-ref` only): a PR head, branch, or commit. 3. New branch name (optional): derived from the work description when omitted. 4. Base branch (optional): defaults to origin's default branch, else `main`. 5. Setup command (`feature-gate`, optional): project setup to run inside the worktree, for example `pnpm install --frozen-lockfile`. When omitted, no setup step runs. 6. `runId` (`loop-run`, required): unique run identifier used verbatim as a path segment and branch suffix; a single path segment (no `/`, not `.` or `..`). 7. `pattern` (`loop-run`, required at create): short work-pattern label kept on the manifest entry for audit. 8. Status for mark (`loop-run`, required): exactly one of `active`, `rejected`, `escalated`, `merged`, `stale`. 9. Cleanup set (`loop-run`, optional): status CSV, default `rejected,escalated`, plus an optional age cutoff `<n>` + `s|m|h|d` (for example `24h`). 10. Command (`capture-isolated-patch`, required): shell command that produces the candidate change; run it inside the ephemeral worktree with that worktree as its working directory. 11. Base ref (`capture-isolated-patch`, optional): git ref used to create the detached worktree; defaults to the current `HEAD`. 12. Repo path (`capture-isolated-patch`, optional): repository path for validation and worktree creation; defaults to the current working directory.

Procedure

1. Determine the mode from the inputs. For `capture-isolated-patch`, require `command` and resolve optional `base-ref` and `repo-path`; for other modes, do not create a worktree for single-task work that can happen on a branch in the current checkout. Done when: the mode is decided, capture inputs are resolved when applicable, and single-task work is ruled out for other modes. 2. Mode `capture-isolated-patch`: verify `repo-path` is a git work tree and `base-ref` resolves, both scoped to `repo-path`: `git -C <repo-path> rev-parse --is-inside-work-tree` and `git -C <repo-path> rev-parse --verify <base-ref>`. Stop and report the exact failing check before creating any worktree if either fails. For other modes, detect existing isolation before creating anything by comparing the resolved absolute git dir against the resolved absolute common git dir: run `git rev-parse --absolute-git-dir` and `(cd "$(git rev-parse --git-common-dir)" && pwd -P)`. Equal paths are a normal checkout and continue to step 5; different paths continue to step 3 for the existing-isolation check. Done when: capture validation passes or its failing check is named, or the non-capture comparison establishes equal or different paths and routes accordingly. 3. Mode `capture-isolated-patch`: create an ephemeral worktree at a fresh temporary path with `git -C <repo-path> worktree add --detach <tmp-path> <base-ref>` and record `<tmp-path>`. Report the git error if creation fails. For other modes after a different-path result from step 2, run `git rev-parse --show-superproject-working-tree`. Non-empty output means a submodule: in feature-gate mode stop and report that isolation must run from the superproject; in other modes treat it as a normal checkout and continue to step 5. Empty output means the run is already in an isolated worktree: report the worktree path (`git rev-parse --show-toplevel`) and current branch. In new-work and feature-gate modes proceed in place and skip to the mode steps. In isolate-existing-ref mode check the