# Feature: Shadow-Git Checkpoints (Phase 3)

**Gated by `prefs.global.shadowGit.enabled`** (default: `false`). The orchestrator snapshots the worktree via `$HOME/.claude/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history.

```bash
# Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.
bash "$HOME/.claude/lib/shadow-git.sh" init "$TASK_ID" "$WORKTREE"

# Per-step (mode: per-todo-step  -  default): snapshot AFTER each plan-todos
# step completes successfully, so restore lands on a known-good state.
bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "$notes"
bash "$HOME/.claude/lib/shadow-git.sh" snapshot "$TASK_ID" "$WORKTREE" "step $id: $task"

# Per-mutation (mode: per-tool-call): the orchestrator hooks into every Edit/
# Write/MultiEdit/Bash-mutation tool call. Higher fidelity, ~50ms × tool-call
# overhead  -  recommended only for security-critical paths or experimental
# refactors where the user values fine-grained rollback over speed.

# Rollback on demand (interactive helper):
bash "$HOME/.claude/lib/shadow-git.sh" list "$TASK_ID"
bash "$HOME/.claude/lib/shadow-git.sh" restore "$TASK_ID" "$WORKTREE" <sha> --files
```

Shadow repo location: `~/.claude/state/shadow-git/<task-id>/.git/`. Storage cap: `prefs.shadowGit.pruneAfterDays` (default 14). `/multi-agent:purge` honors this prune; manual cleanup via `shadow-git.sh prune <task-id>`.