Worktree Isolation

Isolate a unit of work in a sibling Git worktree. Ordinary Git is sufficient; basicly worktree is an optional provisioning and landing convenience. It covers placement, provisioning, merge and cleanup. For tracker records see work-tracker. For commits see the git reference of cli-tools and conventional-commits.

Rules

• Isolate every non-trivial change. This includes multi-file work, work that runs the gates, and work parallel to another track.
• Skip isolation for a trivial edit, such as a typo. A worktree has a real setup cost.
• Put the worktree at the sibling path <repo>.worktrees/<name>. The sibling checkout stays outside repository scans. Git hooks share the common Git directory regardless of checkout placement.
• Avoid accidental hook bypasses. A relative core.hooksPath can silently skip hooks. For explicit user-requested observer repair, use a command-scoped bypass, run affected checks directly and disclose what did not run. Never disable hooks permanently.
• Resolve conflicts against the whole task intent. Inspect both changes, preserve unrelated work and rerun affected checks; do not restart the plan merely because branches coupled.
• Run merge commands from the base checkout. Git refuses to update a branch that another worktree has checked out.

Protected destinations

An agent sandbox can allow source edits while protecting .codex, .agents or the Git hook directory. Install and landing preflight planned changes before updating the catalog, committing tracker state or rebasing. An access refusal names the destination and the ordinary command to retry; unchanged protected outputs need no write.

For an already-authorized upgrade or landing, request task-scoped execution review for that exact command in the named checkout. In Codex, use the execution tool's require_escalated permission with the protected destination as the reason. The CLI cannot escalate itself. Preserve dotenv denials, normal hooks, signing and loop checkpoints; do not broaden a machine profile. Read the retry result and verify the repository state before continuing the loop.

Create and finish a worktree

basicly worktree create <name> [--base <branch>]           # add and provision
basicly worktree list                                       # active sessions; stale ones are marked
basicly worktree merge <name> --bead <id> [--mode M]        # rebase, verify, --no-ff merge
basicly worktree merge-queue <name>:<id> ... [--mode M]     # merge several, in the given topological order
basicly worktree cleanup <name> [--force]                   # remove the worktree and its merged branch

Use create when the work commits: it provisions .venv, node_modules and the hooks, and a plain git worktree add leaves them missing, so the first commit fails. A plain git worktree add ../<repo>.worktrees/<name> -b <branch> suits read-only work.

Inspect existing branches and worktrees first; do not replace or discard another session's work. Integrate from the base checkout and preserve shared tracker history.

For each lifecycle step, cleanup refusals, how hooks resolve in a linked worktree and the Claude Code background isolation setting, read lifecycle.