From 00cfc4883c8eb57e5660a2dca963e54c981e0513 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:24 +0100
Subject: [PATCH 1/7] docs(git-pilot): add v2 technical spec and task tracking

---
 PROMPT.md                              |  309 ++++
 TECHNICAL-SPEC.md                      | 2056 ++++++++++++++++++++++++
 spec/01-config-and-state.md            |  401 +++++
 spec/02-git-utils-and-network.md       |  331 ++++
 spec/03-rebase-and-conflicts.md        |  374 +++++
 spec/04-agent-and-worktree.md          |  382 +++++
 spec/05-stash-and-robustness.md        |  387 +++++
 spec/06-hooks-and-lifecycle.md         |  400 +++++
 spec/07-skills-and-claude-md.md        |  395 +++++
 spec/VALIDATION.md                     |  267 +++
 tasks/COVERAGE.md                      |  445 +++++
 tasks/done/001-config-schema.md        |   76 +
 tasks/done/002-state-schema.md         |  115 ++
 tasks/done/003-git-utils-extensions.md |  174 ++
 tasks/done/004-agent-library.md        |  130 ++
 tasks/done/005-rebase-library.md       |  249 +++
 tasks/done/006-worktree-library.md     |  220 +++
 tasks/done/007-stash-functions.md      |   99 ++
 tasks/done/008-hook-session-start.md   |  111 ++
 tasks/done/009-hook-pre-commit.md      |   92 ++
 tasks/done/010-hook-post-bash.md       |   88 +
 tasks/done/011-hook-post-write.md      |   57 +
 tasks/done/012-hook-session-stop.md    |  137 ++
 tasks/done/013-hook-prompt-context.md  |   78 +
 tasks/done/014-hook-registration.md    |  100 ++
 tasks/done/015-skills-modified.md      |   82 +
 tasks/done/016-skills-new.md           |   75 +
 tasks/done/017-claude-md-update.md     |  124 ++
 tasks/done/018-plugin-metadata.md      |   64 +
 tasks/done/019-test-suite.md           |  217 +++
 30 files changed, 8035 insertions(+)
 create mode 100644 PROMPT.md
 create mode 100644 TECHNICAL-SPEC.md
 create mode 100644 spec/01-config-and-state.md
 create mode 100644 spec/02-git-utils-and-network.md
 create mode 100644 spec/03-rebase-and-conflicts.md
 create mode 100644 spec/04-agent-and-worktree.md
 create mode 100644 spec/05-stash-and-robustness.md
 create mode 100644 spec/06-hooks-and-lifecycle.md
 create mode 100644 spec/07-skills-and-claude-md.md
 create mode 100644 spec/VALIDATION.md
 create mode 100644 tasks/COVERAGE.md
 create mode 100644 tasks/done/001-config-schema.md
 create mode 100644 tasks/done/002-state-schema.md
 create mode 100644 tasks/done/003-git-utils-extensions.md
 create mode 100644 tasks/done/004-agent-library.md
 create mode 100644 tasks/done/005-rebase-library.md
 create mode 100644 tasks/done/006-worktree-library.md
 create mode 100644 tasks/done/007-stash-functions.md
 create mode 100644 tasks/done/008-hook-session-start.md
 create mode 100644 tasks/done/009-hook-pre-commit.md
 create mode 100644 tasks/done/010-hook-post-bash.md
 create mode 100644 tasks/done/011-hook-post-write.md
 create mode 100644 tasks/done/012-hook-session-stop.md
 create mode 100644 tasks/done/013-hook-prompt-context.md
 create mode 100644 tasks/done/014-hook-registration.md
 create mode 100644 tasks/done/015-skills-modified.md
 create mode 100644 tasks/done/016-skills-new.md
 create mode 100644 tasks/done/017-claude-md-update.md
 create mode 100644 tasks/done/018-plugin-metadata.md
 create mode 100644 tasks/done/019-test-suite.md

diff --git a/PROMPT.md b/PROMPT.md
new file mode 100644
index 0000000..7c920cf
--- /dev/null
+++ b/PROMPT.md
@@ -0,0 +1,309 @@
+# git-pilot v2 — Full Implementation from Technical Spec
+
+Use delegate mode (Shift+Tab) now. You are the team lead and orchestrator — you
+coordinate, you do not implement. All spec reading, task creation, coding, and
+validation is done by teammates you spawn via agent teams.
+
+The goal: implement the entire `git-pilot v2` project as defined in
+`TECHNICAL-SPEC.md`, producing a fully functional Claude Code plugin directory
+at `plugins/git-pilot/` with updated Bash scripts, new library scripts, updated
+and new Markdown skills, updated configuration, and a bats test suite.
+
+Work proceeds in three sequential phases. Create one agent team per phase, shut
+it down and clean it up before starting the next.
+
+---
+
+## Phase 1: Spec Decomposition
+
+<phase_1>
+
+### Objective
+
+Break `TECHNICAL-SPEC.md` into self-contained module documents sized for a
+single agent's context window. This is a context engineering step — each document
+must contain everything an implementing agent needs for that module without
+requiring the full 2,056-line spec.
+
+### Team Setup
+
+Create a team. Spawn 5 teammates. Each teammate handles 2-3 spec sections.
+
+In each spawn prompt, tell the teammate:
+- The exact section numbers and line ranges of `TECHNICAL-SPEC.md` they are
+  responsible for.
+- The output file path(s) they should write to.
+- The formatting rules below.
+
+### Output
+
+Create a `spec/` directory with these files:
+
+| File | Spec Sections | Description |
+|------|---------------|-------------|
+| `spec/01-config-and-state.md` | §3 Data Model, §7 Configuration | Complete v2 config schema with all keys, types, and defaults. Session state schema. Worktree registry schema. Three-tier config merge logic. Backward compatibility for `protectDefaultBranch` boolean→string migration. `normalize_protect_default_branch()` function. |
+| `spec/02-git-utils-and-network.md` | §4.1 Branch Freshness Detection, §4.10 Network Error Handling | `get_branch_tracking_status()` function with all return values. `fetch_with_retry()` function with retry logic and config keys. Fast-forward auto-merge logic. All freshness-related systemMessages (behind, diverged, ahead, no-remote). |
+| `spec/03-rebase-and-conflicts.md` | §4.2 Base Branch Drift Detection, §4.3 Intelligent Rebase and Conflict Resolution | `get_base_branch_drift()` function. `attempt_rebase()` function. `get_conflict_details()` JSON output format. Conflict recommendation heuristics. `rebase.conflictStrategy` handling (prompt, abort, merge-fallback). `needs_force_push()` function. `rebase.allowForcePush` handling. Push rejection detection and messages. |
+| `spec/04-agent-and-worktree.md` | §4.5 Agent Teams Detection, §4.6 Git Worktree Management | `is_agent_context()` detection via `CLAUDE_SPAWNED_BY` env var and state file. `is_operation_agent_restricted()` function. Prompt suppression table. `create_worktree()`, `remove_worktree()`, `list_worktrees()`, `merge_worktree_branch()` functions. Worktree registry CRUD. `worktree.basePath` template expansion. |
+| `spec/05-stash-and-robustness.md` | §4.7 Stash Management, §4.8 Detached HEAD Recovery, §4.9 Protected Branch Enhancement | `auto_stash()` and `auto_restore_stash()` functions with state tracking. Stash ref recording in session state. Detached HEAD detection via empty `get_current_branch()` + reflog lookup. `protectDefaultBranch` "warn"/"block"/"off" enforcement in `pre-commit.sh`. |
+| `spec/06-hooks-and-lifecycle.md` | §5.1 Hook Scripts (all subsections) | Updated `hooks.json` with new timeouts and `UserPromptSubmit` hook. Complete `prompt-context.sh` script. All modifications to `session-start.sh` (fetch, freshness, detached HEAD, extended state init). All modifications to `session-stop.sh` (drift detection, worktree cleanup). All modifications to `post-bash.sh` (agent suppression, push rejection). All modifications to `post-write.sh` (agent suppression). All modifications to `pre-commit.sh` (branch switch detection, block mode). |
+| `spec/07-skills-and-claude-md.md` | §4.4 Unrelated Work Detection, §5.2 Skills, §5.3 CLAUDE.md | Complete v2 CLAUDE.md with all 10 rules. Unrelated work detection as CLAUDE.md Rule 7 + `derive_branch_purpose()` function. Modifications to `/branch` (base branch recording), `/finish` (drift detection), `/configure` (new keys). Complete new skills: `/stash`, `/worktree`, `/rebase`. Updated skill reference table. |
+
+### Rules for Each Module Document
+
+1. Self-contained — include all relevant details inline. Do not write "see
+   TECHNICAL-SPEC.md" or summarize. An agent reading only this file must have
+   everything it needs.
+2. Preserve verbatim — exact function names, variable names, config key paths,
+   error messages, jq filters, bash code snippets, systemMessage strings. Copy
+   from the spec, do not paraphrase technical specifics.
+3. Cross-references at the top — list which other module docs this one depends on
+   and why (e.g., "Depends on: `01-config-and-state.md` for config schema and
+   `get_config()` function signature").
+4. Under 400 lines each.
+
+### Validation
+
+After all module docs are written, spawn one more teammate to validate:
+1. Read `TECHNICAL-SPEC.md` in full.
+2. Read every `spec/*.md` file.
+3. Write `spec/VALIDATION.md` listing any omissions, contradictions, or spec drift.
+4. If issues exist, message you with the list. You message the responsible
+   teammates to fix them.
+5. The validator re-checks after fixes. Phase 1 is complete only when
+   `spec/VALIDATION.md` reports zero issues.
+
+Shut down all teammates and clean up the team before proceeding.
+
+</phase_1>
+
+---
+
+## Phase 2: Task Planning
+
+<phase_2>
+
+### Objective
+
+Create a set of small, independently implementable tasks with a file-based
+tracking system. Do not use Claude Code's built-in task tools
+(TaskCreate/TaskUpdate/TaskList) — use the directory structure described below.
+
+### Team Setup
+
+Create a new team. Spawn 4 teammates. Each teammate reads a subset of the
+`spec/*.md` files (not the original tech spec — the decomposed modules from
+Phase 1).
+
+In each spawn prompt, tell the teammate:
+- Which `spec/*.md` files to read.
+- The task file template and naming convention.
+- That all task files go in `tasks/todo/`.
+
+### Output
+
+Directory structure:
+
+```
+tasks/
+├── todo/
+├── in-progress/
+├── to-validate/
+└── done/
+```
+
+Each task is a Markdown file: `NNN-short-slug.md` (e.g., `001-project-init.md`).
+All start in `todo/`.
+
+Task file template:
+
+```markdown
+# Task NNN: Short Title
+
+## Status
+todo
+
+## Dependencies
+- NNN-short-slug (what this task needs from that one)
+- (or "None")
+
+## Spec References
+- spec/XX-module.md
+
+## Scope
+One paragraph. What this task implements — one focused piece of functionality.
+
+## Acceptance Criteria
+- [ ] Criterion 1 (concrete, verifiable)
+- [ ] Criterion 2
+- [ ] ...
+
+## Implementation Notes
+Details the implementing agent needs: function signatures, exact error
+messages, jq filters, bash patterns, config key paths. Quote the spec
+module directly.
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/foo.sh (new)
+- plugins/git-pilot/scripts/bar.sh (modify)
+```
+
+### Sizing Rules
+
+- Each task: implementable by one agent in one session.
+- Maximum 3-4 source files per task.
+- Maximum 7 acceptance criteria. If more, split the task.
+- The "Files to Create or Modify" section prevents file conflicts during parallel
+  implementation — no two tasks should list the same file unless one depends on
+  the other.
+
+### Ordering
+
+Start with foundational tasks, then build up:
+
+1. Config schema update — `defaults/config.json` with all new keys, `normalize_protect_default_branch()` in `config.sh`
+2. State schema extension — new fields in `state.sh` `init_state()`, updated `read_state()`
+3. git-utils extensions — `get_branch_tracking_status()`, `fetch_with_retry()`, `derive_branch_purpose()`, `is_detached_head()` in `git-utils.sh`
+4. Agent detection library — new `agent.sh` with `is_agent_context()`, `is_operation_agent_restricted()`
+5. Rebase library — new `rebase.sh` with `attempt_rebase()`, `get_conflict_details()`, `needs_force_push()`, `get_base_branch_drift()`
+6. Worktree library — new `worktree.sh` with `create_worktree()`, `remove_worktree()`, `list_worktrees()`, `merge_worktree_branch()`, registry CRUD
+7. Stash functions — `auto_stash()`, `auto_restore_stash()` in `git-utils.sh`
+8. Hook: session-start.sh modifications — fetch, freshness, detached HEAD, extended state init
+9. Hook: pre-commit.sh modifications — branch switch detection, auto-stash, block mode
+10. Hook: post-bash.sh modifications — agent suppression, push rejection detection
+11. Hook: post-write.sh modifications — agent suppression
+12. Hook: session-stop.sh modifications — drift detection, rebase, worktree cleanup
+13. Hook: prompt-context.sh (new) — UserPromptSubmit branch context
+14. Hook registration: hooks.json update — new timeouts, UserPromptSubmit entry
+15. Skills: modified `/branch`, `/finish`, `/configure`
+16. Skills: new `/stash`, `/worktree`, `/rebase`
+17. CLAUDE.md update — all 10 rules, updated skill table
+18. Plugin metadata — `plugin.json` version bump to 2.0.0, updated description
+19. Test suite — bats tests for all new functions and scenarios
+
+Dependencies must form a DAG. No cycles.
+
+### Validation
+
+Spawn a validation teammate to check:
+1. Every requirement in every `spec/*.md` file is covered by at least one task's
+   acceptance criteria. Write `tasks/COVERAGE.md` mapping each spec module to
+   its task(s).
+2. The dependency graph is a valid DAG.
+3. No task exceeds the sizing limits.
+4. No two independent tasks (no dependency relationship) list the same file in
+   "Files to Create or Modify."
+
+Phase 2 is complete when validation passes. Shut down and clean up the team.
+
+</phase_2>
+
+---
+
+## Phase 3: Implementation
+
+<phase_3>
+
+### Objective
+
+Implement all tasks. Each moves through:
+`todo/` -> `in-progress/` -> `to-validate/` -> `done/`.
+
+### Team Setup
+
+Create a new team. Spawn teammates with clear role names:
+
+- **Implementers** (`impl-1`, `impl-2`, `impl-3`, `impl-4`) — write code.
+- **Validators** (`validator-1`, `validator-2`) — review completed work.
+
+In each implementer's spawn prompt, include:
+- Their role: pick up task files from `tasks/todo/`, read the task and its spec
+  references, implement the code, then move the task to `tasks/to-validate/`.
+- The working directory for code: `plugins/git-pilot/`.
+- That they must run `bash -n <script>` for syntax checking and
+  `shellcheck <script>` for linting before marking a task as ready for validation.
+- That they must check dependency tasks are in `tasks/done/` before starting a task.
+- That they must preserve all existing v1 functionality — only add to or modify
+  existing code, never remove working features.
+- That all bash scripts must start with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- That all new functions must follow the naming convention: `snake_case`.
+- That all systemMessages must be prefixed with `[git-pilot]`.
+
+In each validator's spawn prompt, include:
+- Their role: pick up task files from `tasks/to-validate/`, verify acceptance
+  criteria, run `bash -n` and `shellcheck` on modified scripts, and either move
+  to `tasks/done/` or back to `tasks/in-progress/` with notes.
+- That they must verify the implementation matches the spec modules referenced in
+  the task — exact function names, error messages, config key paths, jq filters.
+- That they must verify backward compatibility: v1 config files must still work.
+- That they must check that `source` directives reference the correct paths.
+
+### Implementer Workflow
+
+1. Check `tasks/todo/` for available tasks. Pick the lowest-numbered task whose
+   dependencies are all in `tasks/done/`.
+2. Read the task file and all `spec/*.md` files listed in its Spec References.
+3. Move the file: `mv tasks/todo/NNN-slug.md tasks/in-progress/NNN-slug.md`.
+   Update the Status line to `in-progress`.
+4. Write the code. Follow existing patterns in the codebase — source shared
+   libraries with `source "$SCRIPT_DIR/lib.sh"`, use `get_config` for config
+   access, use `jq -n` for JSON output, use atomic writes via `write_state`.
+5. Run `bash -n <script>` for syntax check and `shellcheck <script>` for lint.
+   Fix any errors.
+6. Move the file: `mv tasks/in-progress/NNN-slug.md tasks/to-validate/NNN-slug.md`.
+   Update Status to `to-validate`.
+7. Message the lead that the task is ready.
+
+### Validator Workflow
+
+1. Check `tasks/to-validate/` for tasks to review.
+2. Read the task file, its spec references, and the implemented code.
+3. Verify every acceptance criterion. Check each one as `[x]` if met.
+4. Run `bash -n` on all modified `.sh` files. Run `shellcheck` on all modified
+   `.sh` files.
+5. If all criteria pass and checks pass: move to `tasks/done/`, update Status to
+   `done`, message the lead.
+6. If anything fails: append a `## Validation Notes` section with specific issues
+   and how to fix them. Move to `tasks/in-progress/`, update Status to
+   `in-progress`, message the lead. The lead assigns it to an implementer.
+
+### Coordination Rules
+
+- A validator must not validate work done by the same agent that implemented it.
+- Avoid file conflicts: do not assign two implementers tasks that modify the same
+  files simultaneously. Use the "Files to Create or Modify" section to check for
+  overlap.
+- After each task reaches `done/`, check if previously blocked tasks are now
+  unblocked and assign them.
+- If a task fails validation, the implementer must address every point in the
+  Validation Notes before resubmitting.
+
+### Completion Criteria
+
+The implementation is done when:
+1. All task files are in `tasks/done/`.
+2. `bash -n plugins/git-pilot/scripts/*.sh` succeeds for all scripts.
+3. `shellcheck plugins/git-pilot/scripts/*.sh` passes with no errors (warnings acceptable).
+4. The `defaults/config.json` is valid JSON: `jq . plugins/git-pilot/defaults/config.json`.
+5. The `hooks/hooks.json` is valid JSON: `jq . plugins/git-pilot/hooks/hooks.json`.
+6. The `plugin.json` version is `2.0.0`.
+7. All new skills have valid frontmatter (name, description).
+8. CLAUDE.md contains all 10 rules and the updated skill reference table.
+
+Shut down all teammates and clean up the team.
+
+</phase_3>
+
+---
+
+## Orchestrator Constraints
+
+<constraints>
+- Stay in delegate mode. Do not read spec sections, write code, or run builds yourself.
+- One team at a time. Shut down all teammates and clean up each team before creating the next.
+- Within each phase, maximize parallelism by assigning independent work to different teammates simultaneously. Avoid assigning tasks that touch the same files to different teammates.
+- When spawning teammates, provide enough context in the spawn prompt for them to work autonomously. They do not inherit your conversation history. Include file paths, role description, and what "done" looks like.
+- If a teammate encounters a genuine ambiguity in the spec (a contradiction or missing detail), they should document it in `DECISIONS.md` at the repo root with the interpretation chosen and the reasoning, then proceed.
+- Implement exactly what the spec describes. Do not add features, abstractions, error handling for impossible cases, or refactoring beyond the spec.
+- Do not escalate to the user. Handle all decisions autonomously within the spec's boundaries.
+</constraints>
diff --git a/TECHNICAL-SPEC.md b/TECHNICAL-SPEC.md
new file mode 100644
index 0000000..63a5c01
--- /dev/null
+++ b/TECHNICAL-SPEC.md
@@ -0,0 +1,2056 @@
+# git-pilot v2 — Technical Specification
+
+## 1. Overview
+
+git-pilot v2 is a major upgrade to the existing Claude Code plugin that automates git workflows. While v1 handles branch creation, commit formatting, push prompts, and MR creation, it leaves significant gaps: users must drop into a separate terminal for fetching, rebasing, conflict resolution, stash management, and multi-agent coordination.
+
+v2 closes every gap so the user never runs a git command outside Claude Code. The plugin remains Bash-only (hook scripts) with Markdown skills and a JSON config system. It integrates with Claude Code's hook lifecycle (SessionStart, PreToolUse, PostToolUse, Stop) and adds awareness of Agent Teams for parallel work.
+
+### Primary use cases
+
+1. Start a session on a stale branch and have it automatically fetched and fast-forwarded.
+2. Finish work and have the plugin rebase onto an updated base branch before pushing.
+3. Encounter rebase or merge conflicts and get guided resolution with contextual recommendations.
+4. Start working on something unrelated to the current branch and get prompted to switch branches.
+5. Run multiple agents in parallel via Agent Teams with isolated git worktrees.
+6. Switch branches without manually stashing and restoring uncommitted changes.
+
+### Target platforms
+
+Linux, macOS. Any environment where Claude Code runs with `git`, `jq`, and optionally `gh`/`glab`.
+
+### Key non-goals
+
+- **Not a git GUI.** The plugin augments Claude's git operations via hooks and behavioral rules; it does not render diffs visually.
+- **Not a CI system.** It does not run tests, linters, or builds. It manages git state only.
+- **No interactive rebase.** Rebase operations are non-interactive (`git rebase`, not `git rebase -i`). Claude resolves conflicts via file edits, not an interactive TUI.
+- **No submodule management.** Git submodules are out of scope.
+
+---
+
+## 2. Architecture
+
+### 2.1 Component Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Claude Code                          │
+│                                                          │
+│  ┌──────────┐  ┌────────────┐  ┌──────────┐            │
+│  │ CLAUDE.md │  │ Hook Scripts│  │  Skills  │            │
+│  │ (rules)   │  │ (bash)      │  │  (md)    │            │
+│  └────┬─────┘  └──────┬─────┘  └────┬─────┘            │
+│       │               │              │                   │
+│       └───────┬───────┘──────────────┘                   │
+│               │                                          │
+│        ┌──────┴──────┐                                   │
+│        │  Shared Libs │                                   │
+│        │ config.sh    │                                   │
+│        │ git-utils.sh │                                   │
+│        │ state.sh     │                                   │
+│        │ rebase.sh    │  ← NEW                           │
+│        │ worktree.sh  │  ← NEW                           │
+│        │ agent.sh     │  ← NEW                           │
+│        └──────┬──────┘                                   │
+│               │                                          │
+│        ┌──────┴──────┐                                   │
+│        │  State Files │                                   │
+│        │ /tmp/git-    │                                   │
+│        │ pilot-*.json │                                   │
+│        └─────────────┘                                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Data Flow
+
+1. **SessionStart**: `session-start.sh` → fetch remote → detect branch freshness → emit systemMessage with branch status and context.
+2. **UserPromptSubmit** (NEW): `prompt-context.sh` → gather branch context (name, recent commits) → emit systemMessage for Claude's unrelated-work assessment.
+3. **PreToolUse (Bash)**: `pre-commit.sh` → validate commit messages, enforce branch protection, detect branch creation.
+4. **PostToolUse (Write|Edit)**: `post-write.sh` → track file changes for auto-commit suggestions.
+5. **PostToolUse (Bash)**: `post-bash.sh` → detect push rejection, prompt for push, handle post-rebase state.
+6. **Stop**: `session-stop.sh` → drift detection, optional rebase, summary, push/MR workflow, worktree cleanup.
+
+### 2.3 New Shared Libraries
+
+| File | Purpose |
+|------|---------|
+| `scripts/rebase.sh` | Rebase operations, conflict detection, resolution helpers |
+| `scripts/worktree.sh` | Worktree creation, removal, listing, registry management |
+| `scripts/agent.sh` | Agent Teams detection, prompt suppression logic |
+
+### 2.4 Key Technology Choices
+
+- **Bash-only hooks**: Required by Claude Code's hook execution model. All hook scripts are Bash.
+- **jq for JSON**: All config, state, and hook I/O is JSON. `jq` is the only parser.
+- **Atomic state writes**: All state file updates use `write_state()` (temp file + `mv`) from v1.
+- **git worktrees**: Native git feature for parallel working directories. No third-party tools.
+
+---
+
+## 3. Data Model
+
+### 3.1 Configuration Schema
+
+The configuration uses a three-tier merge: plugin defaults → global (`~/.claude/git-pilot.json`) → local (`.claude/git-pilot.json`). Local overrides global, global overrides defaults. The merge is a shallow recursive merge via `jq -s '.[0] * .[1]'`.
+
+#### 3.1.1 Complete v2 Defaults (`defaults/config.json`)
+
+```jsonc
+{
+  "git": {
+    "defaultBranch": "main",
+    "autoInit": true,
+    "protectDefaultBranch": "warn",
+    "autoFetch": true,
+    "fetchRetries": 2,
+    "fetchRetryDelaySec": 3
+  },
+  "branch": {
+    "pattern": "{{type}}/{{description}}",
+    "types": ["feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "build", "ci"],
+    "descriptionSeparator": "-",
+    "descriptionCase": "kebab",
+    "maxLength": 72,
+    "autoCreate": true,
+    "unrelatedWorkDetection": true,
+    "autoStashOnSwitch": true
+  },
+  "commit": {
+    "pattern": "{{type}}({{scope}}): {{description}}",
+    "types": ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
+    "maxSubjectLength": 72,
+    "scopeRequired": false,
+    "body": {
+      "required": false,
+      "wrap": 72,
+      "includeChangedFiles": false
+    },
+    "signature": {
+      "stripCoAuthoredBy": true,
+      "stripAiAttribution": true,
+      "stripSignedOffBy": false
+    },
+    "breakingChange": {
+      "appendExclamation": true,
+      "requireBody": true,
+      "bodyPrefix": "BREAKING CHANGE: "
+    }
+  },
+  "autoCommit": {
+    "enabled": true,
+    "mode": "suggest",
+    "threshold": 3,
+    "includeWip": false,
+    "wipPrefix": "wip: "
+  },
+  "remote": {
+    "promptForRemote": true,
+    "skipRemotePrompt": false,
+    "defaultName": "origin",
+    "autoPush": false,
+    "pushOnFinish": "ask"
+  },
+  "rebase": {
+    "autoRebaseBeforePush": true,
+    "conflictStrategy": "prompt",
+    "allowForcePush": "ask"
+  },
+  "mergeRequest": {
+    "enabled": true,
+    "createOnFinish": "ask",
+    "platform": "auto",
+    "titleFromBranch": true,
+    "bodyTemplate": null,
+    "draft": false,
+    "labels": [],
+    "assignToSelf": true
+  },
+  "worktree": {
+    "enabled": true,
+    "basePath": "../{{project}}-worktrees",
+    "cleanupOnMerge": true
+  },
+  "agentTeams": {
+    "suppressPromptsForAgents": true,
+    "orchestratorOnly": ["push", "mr"]
+  },
+  "summary": {
+    "includeFileChanges": true,
+    "includeDiff": false,
+    "includeCommitLog": true,
+    "format": "markdown"
+  }
+}
+```
+
+#### 3.1.2 Backward Compatibility: `protectDefaultBranch`
+
+v1 used a boolean for `git.protectDefaultBranch`. v2 uses a string enum. The config loading code must handle both:
+
+```bash
+# In config.sh or git-utils.sh
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
+```
+
+#### 3.1.3 New Config Keys Reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `git.autoFetch` | boolean | `true` | Run `git fetch` on session start |
+| `git.fetchRetries` | integer | `2` | Number of retry attempts on fetch failure |
+| `git.fetchRetryDelaySec` | integer | `3` | Seconds between fetch retries |
+| `git.protectDefaultBranch` | string | `"warn"` | `"warn"` / `"block"` / `"off"` — was boolean in v1 |
+| `branch.unrelatedWorkDetection` | boolean | `true` | Enable unrelated work detection prompts |
+| `branch.autoStashOnSwitch` | boolean | `true` | Auto-stash uncommitted changes on branch switch |
+| `rebase.autoRebaseBeforePush` | boolean | `true` | Rebase onto base branch before push/MR |
+| `rebase.conflictStrategy` | string | `"prompt"` | `"prompt"` / `"abort"` / `"merge-fallback"` |
+| `rebase.allowForcePush` | string | `"ask"` | `"ask"` / `"never"` / `"always"` |
+| `worktree.enabled` | boolean | `true` | Enable worktree management for Agent Teams |
+| `worktree.basePath` | string | `"../{{project}}-worktrees"` | Worktree directory pattern |
+| `worktree.cleanupOnMerge` | boolean | `true` | Remove worktree after successful merge |
+| `agentTeams.suppressPromptsForAgents` | boolean | `true` | Suppress interactive prompts for spawned agents |
+| `agentTeams.orchestratorOnly` | array | `["push", "mr"]` | Operations restricted to orchestrator agent |
+
+### 3.2 Session State Schema
+
+State files are stored at `/tmp/git-pilot-${SESSION_ID}.json`. v2 extends the v1 schema:
+
+```jsonc
+{
+  "sessionId": "abc123",
+  "startTime": "2026-02-24T20:00:00Z",
+  "workingBranch": "feat/add-dark-mode",
+  "previousBranch": "main",
+  "headAtStart": "a1b2c3d4",
+  "baseBranch": "main",
+  "branchPurpose": "add dark mode",
+  "changeCount": 0,
+  "lastCommitAt": null,
+  "modifiedFiles": [],
+  "remoteSkipped": false,
+  "lastFetchAt": "2026-02-24T20:00:05Z",
+  "isAgent": false,
+  "agentRole": null,
+  "activeWorktrees": [],
+  "stashRefs": []
+}
+```
+
+New fields (v2):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `baseBranch` | string | The branch this feature branch was created from or targets for MR |
+| `branchPurpose` | string | Human-readable purpose derived from branch name (e.g., `"add dark mode"` from `feat/add-dark-mode`) |
+| `lastFetchAt` | string\|null | ISO timestamp of last `git fetch` in this session |
+| `isAgent` | boolean | Whether this session is a spawned agent (not orchestrator) |
+| `agentRole` | string\|null | `"orchestrator"`, `"implementer"`, `"validator"`, or null |
+| `activeWorktrees` | array | List of `{path, branch, createdAt}` objects for worktrees created in this session |
+| `stashRefs` | array | List of `{ref, branch, message, createdAt}` for stashes created by git-pilot |
+
+### 3.3 Worktree Registry
+
+For multi-session worktree tracking, a registry file is stored at `.git/git-pilot-worktrees.json`:
+
+```jsonc
+{
+  "worktrees": [
+    {
+      "path": "../myproject-worktrees/feat-add-auth",
+      "branch": "feat/add-auth",
+      "baseBranch": "main",
+      "createdAt": "2026-02-24T20:00:00Z",
+      "createdBy": "session-abc123",
+      "status": "active"
+    }
+  ]
+}
+```
+
+This registry persists across sessions, unlike session state files which are cleaned up on session stop.
+
+---
+
+## 4. Feature Specifications
+
+### 4.1 Branch Freshness Detection
+
+**Trigger**: SessionStart hook (`session-start.sh`)
+
+**Preconditions**: Repository has at least one remote. `git.autoFetch` is `true`.
+
+**Behavior**:
+
+1. Run `git fetch ${remote_name}` with retry logic (see §4.10).
+2. Record `lastFetchAt` in session state.
+3. Determine the current branch's tracking status:
+
+```bash
+# In git-utils.sh
+get_branch_tracking_status() {
+  local branch="$1"
+  local remote_name="$2"
+  local remote_branch="${remote_name}/${branch}"
+
+  # Check if remote branch exists
+  if ! git rev-parse --verify "$remote_branch" >/dev/null 2>&1; then
+    echo "no-remote"
+    return
+  fi
+
+  local local_ref remote_ref base_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "$remote_branch" 2>/dev/null)
+  base_ref=$(git merge-base "$branch" "$remote_branch" 2>/dev/null || true)
+
+  if [[ "$local_ref" == "$remote_ref" ]]; then
+    echo "up-to-date"
+  elif [[ "$local_ref" == "$base_ref" ]]; then
+    local behind_count
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "behind:${behind_count}"
+  elif [[ "$remote_ref" == "$base_ref" ]]; then
+    local ahead_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    echo "ahead:${ahead_count}"
+  else
+    local ahead_count behind_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "diverged:${ahead_count}:${behind_count}"
+  fi
+}
+```
+
+4. Emit systemMessage based on status:
+
+| Status | Action | Message |
+|--------|--------|---------|
+| `up-to-date` | None | No message |
+| `behind:N` | Auto fast-forward | `"[git-pilot] Branch '${branch}' was ${N} commit(s) behind '${remote}/${branch}'. Fast-forwarded to latest."` |
+| `behind:N` (ff fails) | Warn | `"[git-pilot] Branch '${branch}' is ${N} commit(s) behind '${remote}/${branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is."` |
+| `ahead:N` | Inform | `"[git-pilot] Branch '${branch}' is ${N} commit(s) ahead of '${remote}/${branch}'. Unpushed changes."` |
+| `diverged:A:B` | Warn | `"[git-pilot] Branch '${branch}' has diverged from '${remote}/${branch}' (${A} local, ${B} remote). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue."` |
+| `no-remote` | Inform | No message (new branch, not yet pushed) |
+
+5. For fast-forward (behind with no local changes):
+
+```bash
+if git merge --ff-only "${remote_branch}" >/dev/null 2>&1; then
+  # Success — emit fast-forward message
+else
+  # Cannot fast-forward — emit warning with options
+fi
+```
+
+**Edge cases**:
+- If `git.autoFetch` is `false`, skip fetch entirely. Still check local vs. tracking branch status if tracking info exists.
+- If no remote exists, skip all freshness checks.
+- If the branch has no tracking branch (new local branch), skip comparison.
+- If fetch fails after all retries, emit a warning and continue without freshness data (see §4.10).
+
+### 4.2 Base Branch Drift Detection
+
+**Trigger**: Before push or MR creation. Called from `/finish` skill, `session-stop.sh`, and `post-bash.sh` (on push commands).
+
+**Preconditions**: On a feature branch (not default branch). Remote exists. `rebase.autoRebaseBeforePush` is `true`.
+
+**Behavior**:
+
+```bash
+# In git-utils.sh
+get_base_branch_drift() {
+  local current_branch="$1"
+  local base_branch="$2"
+  local remote_name="$3"
+  local remote_base="${remote_name}/${base_branch}"
+
+  # Fetch latest base branch state
+  git fetch "$remote_name" "$base_branch" 2>/dev/null || return 1
+
+  # Find the merge base between current branch and remote base
+  local merge_base
+  merge_base=$(git merge-base "$current_branch" "$remote_base" 2>/dev/null || true)
+
+  if [[ -z "$merge_base" ]]; then
+    echo "no-common-ancestor"
+    return
+  fi
+
+  # Count commits on base branch since the branch point
+  local drift_count
+  drift_count=$(git rev-list --count "${merge_base}..${remote_base}" 2>/dev/null)
+
+  if [[ "$drift_count" -eq 0 ]]; then
+    echo "no-drift"
+  else
+    echo "drifted:${drift_count}"
+  fi
+}
+```
+
+**Decision flow**:
+
+1. If `no-drift`: proceed with push/MR.
+2. If `drifted:N`:
+   a. Emit: `"[git-pilot] Base branch '${base}' has ${N} new commit(s) since this branch diverged. Rebasing '${current}' onto '${remote}/${base}'..."`
+   b. Attempt rebase (see §4.3).
+   c. If rebase succeeds: emit `"[git-pilot] Rebase succeeded cleanly. Ready to push."` and continue.
+   d. If rebase has conflicts: handle per `rebase.conflictStrategy` (see §4.3).
+3. If `no-common-ancestor`: emit warning: `"[git-pilot] Cannot determine common ancestor between '${current}' and '${base}'. Skipping rebase. Push may require manual review."` Proceed with push.
+
+**Base branch determination**:
+
+The base branch is determined in order:
+1. From session state `baseBranch` field (set when branch was created via `/branch` skill).
+2. From git tracking: `git config branch.${current}.merge` → strip `refs/heads/`.
+3. Fall back to `git.defaultBranch` from config.
+
+### 4.3 Intelligent Rebase and Conflict Resolution
+
+**New library**: `scripts/rebase.sh`
+
+#### 4.3.1 Rebase Execution
+
+```bash
+# In rebase.sh
+attempt_rebase() {
+  local target_branch="$1"  # Branch to rebase onto (e.g., origin/main)
+
+  # Ensure clean working tree
+  if has_uncommitted_changes; then
+    echo "error:dirty-worktree"
+    return 1
+  fi
+
+  # Attempt rebase
+  local rebase_output
+  if rebase_output=$(git rebase "$target_branch" 2>&1); then
+    echo "success"
+    return 0
+  else
+    # Check if it's a conflict
+    if git diff --name-only --diff-filter=U 2>/dev/null | head -1 | grep -q .; then
+      echo "conflict"
+      return 1
+    else
+      echo "error:${rebase_output}"
+      return 1
+    fi
+  fi
+}
+```
+
+#### 4.3.2 Conflict Detection and Reporting
+
+```bash
+# In rebase.sh
+get_conflict_details() {
+  local conflict_files
+  conflict_files=$(git diff --name-only --diff-filter=U 2>/dev/null)
+
+  if [[ -z "$conflict_files" ]]; then
+    echo "[]"
+    return
+  fi
+
+  local result="["
+  local first=true
+
+  while IFS= read -r file; do
+    # Determine conflict type by examining the conflict markers
+    local ours_only=false
+    local theirs_only=false
+    local both_modified=false
+
+    # Check if the file exists in both sides
+    local ours_exists theirs_exists
+    ours_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 2" | wc -l | tr -d ' ')
+    theirs_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 3" | wc -l | tr -d ' ')
+
+    local conflict_type="both-modified"
+    if [[ "$ours_exists" == "0" ]]; then
+      conflict_type="deleted-by-us"
+    elif [[ "$theirs_exists" == "0" ]]; then
+      conflict_type="deleted-by-them"
+    fi
+
+    # Get conflict marker count as complexity indicator
+    local marker_count=0
+    if [[ -f "$file" ]]; then
+      marker_count=$(grep -c '^<<<<<<< ' "$file" 2>/dev/null || echo "0")
+    fi
+
+    if [[ "$first" == "true" ]]; then
+      first=false
+    else
+      result+=","
+    fi
+    result+=$(jq -n \
+      --arg f "$file" \
+      --arg t "$conflict_type" \
+      --argjson m "$marker_count" \
+      '{file: $f, type: $t, conflictRegions: $m}')
+  done <<< "$conflict_files"
+
+  result+="]"
+  echo "$result"
+}
+```
+
+#### 4.3.3 Conflict Resolution Messages
+
+When conflicts are detected, the hook emits a systemMessage with structured conflict information:
+
+```
+[git-pilot] Rebase conflict in ${count} file(s):
+
+${for each conflict}
+- `${file}` (${type}, ${regions} conflict region(s))
+  Recommendation: ${recommendation}
+${end for}
+
+Prompt the user with these options:
+1. Resolve conflicts manually (edit the conflicting files, then run `git add <file>` and `git rebase --continue`)
+2. Accept all changes from the base branch (`git checkout --theirs <file>` for each file)
+3. Keep all local changes (`git checkout --ours <file>` for each file)
+4. Abort the rebase (`git rebase --abort`) and push without rebasing
+5. Abort the rebase and use merge instead (`git merge ${base_branch}`)
+```
+
+**Recommendation heuristics**:
+
+| Conflict type | Recommendation |
+|--------------|----------------|
+| `deleted-by-us` | `"File was deleted locally but modified on base. If the deletion was intentional, accept ours (delete). Otherwise, accept theirs."` |
+| `deleted-by-them` | `"File was deleted on base but modified locally. If your changes are still needed, accept ours. Otherwise, accept theirs (delete)."` |
+| `both-modified`, 1 region | `"Single conflict region — likely a small overlap. Manual review recommended."` |
+| `both-modified`, >3 regions | `"Multiple conflict regions — significant concurrent changes. Manual review required."` |
+
+#### 4.3.4 Conflict Strategy Handling
+
+Based on `rebase.conflictStrategy`:
+
+| Strategy | Behavior |
+|----------|----------|
+| `"prompt"` | Emit conflict details and prompt user for resolution choice (default) |
+| `"abort"` | Immediately abort rebase: `git rebase --abort`. Emit: `"[git-pilot] Rebase aborted due to conflicts. Push without rebase."` |
+| `"merge-fallback"` | Abort rebase, attempt merge instead: `git rebase --abort && git merge ${target}`. If merge also conflicts, fall back to `"prompt"` behavior |
+
+#### 4.3.5 Force Push Handling
+
+After a successful rebase that rewrites history (branch was previously pushed), a force push is needed:
+
+```bash
+# In rebase.sh
+needs_force_push() {
+  local branch="$1"
+  local remote_name="$2"
+
+  # Check if remote tracking branch exists
+  if ! git rev-parse --verify "${remote_name}/${branch}" >/dev/null 2>&1; then
+    return 1  # No remote branch, normal push works
+  fi
+
+  # Check if local and remote have diverged after rebase
+  local local_ref remote_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "${remote_name}/${branch}" 2>/dev/null)
+
+  if [[ "$local_ref" != "$remote_ref" ]]; then
+    # Check if remote is NOT an ancestor of local (diverged, not just ahead)
+    if ! git merge-base --is-ancestor "$remote_ref" "$local_ref" 2>/dev/null; then
+      return 0  # Needs force push
+    fi
+  fi
+
+  return 1
+}
+```
+
+Based on `rebase.allowForcePush`:
+
+| Setting | Behavior |
+|---------|----------|
+| `"ask"` | Emit: `"[git-pilot] Rebase rewrote history. Force push required. Prompt the user: force push (git push --force-with-lease) or abort."` |
+| `"never"` | Emit: `"[git-pilot] Rebase rewrote history but force push is disabled. The rebase changes are local only. Push manually if needed."` |
+| `"always"` | Use `git push --force-with-lease` automatically. Emit: `"[git-pilot] Force-pushed '${branch}' to '${remote}/${branch}' after rebase."` |
+
+Always use `--force-with-lease` (never bare `--force`) for safety.
+
+#### 4.3.6 Push Rejection Handling
+
+When `post-bash.sh` detects a failed `git push` (exit code non-zero, stderr contains "rejected" or "failed to push"):
+
+```
+[git-pilot] Push rejected — remote '${remote}/${branch}' has new commits.
+Prompt the user:
+1. Pull and rebase, then retry push (`git pull --rebase && git push`)
+2. Force push with lease (`git push --force-with-lease`) — overwrites remote changes
+3. Pull and merge (`git pull`) — creates a merge commit
+4. Cancel
+```
+
+### 4.4 Unrelated Work Detection
+
+**Mechanism**: CLAUDE.md behavioral rule + session state context. No additional hook required.
+
+**Preconditions**: On a feature branch (not default branch). `branch.unrelatedWorkDetection` is `true`. Branch has at least one commit.
+
+**CLAUDE.md Rule** (new Rule 7):
+
+```markdown
+## Rule 7: Unrelated work detection
+
+Before starting work on a new user request, assess whether the request is related
+to the current branch's purpose:
+
+1. **Branch name**: Parse the branch name for semantic meaning. For example,
+   `feat/add-dark-mode` implies work on dark mode; `fix/login-timeout` implies
+   fixing a login timeout bug.
+2. **Recent commits**: Review the commit log on this branch for scope context.
+3. **Assessment**: If the user's request is clearly unrelated to the branch's
+   purpose (different feature, different bug, different module), prompt the user:
+
+   "This work appears unrelated to the current branch (`<branch-name>`).
+   Options:
+   1. Create a new branch from `<default-branch>` (recommended — keeps branches focused)
+   2. Create a new branch from the current branch (if this work depends on current changes)
+   3. Continue on this branch"
+
+4. **When NOT to prompt**: Do not prompt for closely related work (e.g., fixing
+   a bug discovered while implementing a feature on the same branch), for work
+   on the default branch, or for branches with no commits yet.
+5. **If the user chooses to create a new branch**: Follow the branch switch
+   workflow (see Rule 8).
+```
+
+**Branch purpose derivation** (stored in session state at init):
+
+```bash
+# In git-utils.sh
+derive_branch_purpose() {
+  local branch_name="$1"
+
+  # Strip type prefix (e.g., "feat/", "fix/")
+  local description
+  description=$(echo "$branch_name" | sed 's|^[^/]*/||')
+
+  # Convert kebab-case/snake_case to words
+  description=$(echo "$description" | tr '-' ' ' | tr '_' ' ')
+
+  echo "$description"
+}
+```
+
+The session-start.sh script stores `branchPurpose` in state and includes it in its systemMessage so Claude has context for the entire session.
+
+### 4.5 Agent Teams Detection and Prompt Suppression
+
+**New library**: `scripts/agent.sh`
+
+#### 4.5.1 Agent Detection
+
+```bash
+# In agent.sh
+is_agent_context() {
+  # Primary: check Claude Code spawned-by indicator
+  if [[ -n "${CLAUDE_SPAWNED_BY:-}" ]]; then
+    return 0
+  fi
+
+  # Secondary: check for agent role in session state
+  local session_id="${1:-}"
+  if [[ -n "$session_id" ]]; then
+    local state_file
+    state_file=$(get_state_file "$session_id")
+    local state
+    state=$(read_state "$state_file")
+    local is_agent
+    is_agent=$(echo "$state" | jq -r '.isAgent // false')
+    if [[ "$is_agent" == "true" ]]; then
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+# Check if a specific operation should be suppressed for agents
+is_operation_agent_restricted() {
+  local config="$1"
+  local operation="$2"  # "push", "mr", "branch-prompt", etc.
+
+  local suppress
+  suppress=$(get_config "$config" '.agentTeams.suppressPromptsForAgents' 'true')
+
+  if [[ "$suppress" != "true" ]]; then
+    return 1  # Not suppressed
+  fi
+
+  # Check if this specific operation is orchestrator-only
+  local restricted
+  restricted=$(echo "$config" | jq -r --arg op "$operation" \
+    '.agentTeams.orchestratorOnly // ["push", "mr"] | map(select(. == $op)) | length')
+
+  if [[ "$restricted" -gt 0 ]]; then
+    return 0  # Restricted to orchestrator
+  fi
+
+  return 1
+}
+```
+
+#### 4.5.2 Prompt Suppression
+
+All hook scripts that emit interactive systemMessages must check agent context:
+
+```bash
+# Pattern used in all hooks before emitting interactive prompts
+if is_agent_context "$SESSION_ID" && \
+   is_operation_agent_restricted "$CONFIG" "push"; then
+  # Agent mode — suppress prompt, exit silently
+  echo '{"continue": true}'
+  exit 0
+fi
+```
+
+**Operations and their agent behavior**:
+
+| Operation | Orchestrator | Agent |
+|-----------|-------------|-------|
+| Branch creation prompt | Interactive | Suppressed |
+| Push prompt after commit | Interactive | Suppressed |
+| MR creation | Interactive | Suppressed |
+| Commit validation | Active | Active (agents must also follow commit rules) |
+| Auto-commit suggestions | Active | Suppressed |
+| Rebase/conflict prompts | Interactive | Suppressed (abort rebase silently) |
+| Session summary | Active | Suppressed |
+| Branch freshness warnings | Active | Log to state only (no prompt) |
+
+### 4.6 Git Worktree Management
+
+**New library**: `scripts/worktree.sh`
+
+#### 4.6.1 Worktree Creation
+
+```bash
+# In worktree.sh
+create_worktree() {
+  local config="$1"
+  local branch_name="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local project_name
+  project_name=$(basename "$(git rev-parse --show-toplevel)")
+
+  local base_path
+  base_path=$(get_config "$config" '.worktree.basePath' "../{{project}}-worktrees")
+  base_path="${base_path//\{\{project\}\}/$project_name}"
+
+  # Sanitize branch name for directory path
+  local dir_name
+  dir_name=$(echo "$branch_name" | tr '/' '-')
+  local worktree_path="${base_path}/${dir_name}"
+
+  # Create parent directory
+  mkdir -p "$(dirname "$worktree_path")"
+
+  # Create worktree
+  local output
+  if output=$(git worktree add "$worktree_path" -b "$branch_name" "$base_branch" 2>&1); then
+    # Register in worktree registry
+    register_worktree "$worktree_path" "$branch_name" "$base_branch" "$session_id"
+    echo "$worktree_path"
+    return 0
+  else
+    echo "error:${output}" >&2
+    return 1
+  fi
+}
+```
+
+#### 4.6.2 Worktree Removal
+
+```bash
+remove_worktree() {
+  local worktree_path="$1"
+  local force="${2:-false}"
+
+  local flags=""
+  if [[ "$force" == "true" ]]; then
+    flags="--force"
+  fi
+
+  if git worktree remove "$worktree_path" $flags 2>/dev/null; then
+    unregister_worktree "$worktree_path"
+    return 0
+  else
+    return 1
+  fi
+}
+```
+
+#### 4.6.3 Worktree Registry
+
+```bash
+WORKTREE_REGISTRY=".git/git-pilot-worktrees.json"
+
+register_worktree() {
+  local path="$1"
+  local branch="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local registry
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    registry=$(cat "$WORKTREE_REGISTRY")
+  else
+    registry='{"worktrees":[]}'
+  fi
+
+  local entry
+  entry=$(jq -n \
+    --arg p "$path" \
+    --arg b "$branch" \
+    --arg bb "$base_branch" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg sid "$session_id" \
+    '{path:$p, branch:$b, baseBranch:$bb, createdAt:$ts, createdBy:$sid, status:"active"}')
+
+  registry=$(echo "$registry" | jq --argjson e "$entry" '.worktrees += [$e]')
+
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+unregister_worktree() {
+  local path="$1"
+
+  if [[ ! -f "$WORKTREE_REGISTRY" ]]; then
+    return
+  fi
+
+  local registry
+  registry=$(cat "$WORKTREE_REGISTRY")
+  registry=$(echo "$registry" | jq --arg p "$path" \
+    '.worktrees = [.worktrees[] | select(.path != $p)]')
+
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+list_worktrees() {
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    cat "$WORKTREE_REGISTRY"
+  else
+    echo '{"worktrees":[]}'
+  fi
+}
+```
+
+#### 4.6.4 Worktree Merge Back
+
+```bash
+merge_worktree_branch() {
+  local worktree_path="$1"
+  local target_branch="$2"
+  local config="$3"
+
+  # Get the worktree's branch
+  local wt_branch
+  wt_branch=$(git -C "$worktree_path" branch --show-current 2>/dev/null)
+
+  if [[ -z "$wt_branch" ]]; then
+    echo "error:cannot-determine-branch"
+    return 1
+  fi
+
+  # Switch to target branch in main worktree
+  git checkout "$target_branch" 2>/dev/null || return 1
+
+  # Attempt merge
+  local merge_output
+  if merge_output=$(git merge "$wt_branch" --no-edit 2>&1); then
+    echo "success"
+
+    # Cleanup if configured
+    local cleanup
+    cleanup=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+    if [[ "$cleanup" == "true" ]]; then
+      remove_worktree "$worktree_path" "false"
+      git branch -d "$wt_branch" 2>/dev/null || true
+    fi
+
+    return 0
+  else
+    echo "conflict"
+    return 1
+  fi
+}
+```
+
+### 4.7 Stash Management
+
+**Modified file**: `scripts/git-utils.sh`
+
+#### 4.7.1 Auto-stash on Branch Switch
+
+When `branch.autoStashOnSwitch` is `true` and a branch switch is detected in `pre-commit.sh` (which also intercepts branch commands):
+
+```bash
+# In git-utils.sh
+auto_stash() {
+  local current_branch="$1"
+  local session_id="$2"
+
+  if ! has_uncommitted_changes; then
+    return 1  # Nothing to stash
+  fi
+
+  local stash_msg="git-pilot auto-stash on ${current_branch}"
+  if git stash push -m "$stash_msg" >/dev/null 2>&1; then
+    local stash_ref
+    stash_ref=$(git stash list --format='%gd' | head -1)
+
+    # Record in session state
+    if [[ -n "$session_id" ]]; then
+      local state_file
+      state_file=$(get_state_file "$session_id")
+      update_state "$state_file" \
+        --arg ref "$stash_ref" \
+        --arg branch "$current_branch" \
+        --arg msg "$stash_msg" \
+        '.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]'
+    fi
+
+    return 0
+  fi
+
+  return 1
+}
+```
+
+#### 4.7.2 Auto-restore on Branch Switch
+
+When switching back to a branch that had changes stashed:
+
+```bash
+auto_restore_stash() {
+  local target_branch="$1"
+  local session_id="$2"
+
+  if [[ -z "$session_id" ]]; then
+    return 1
+  fi
+
+  local state_file
+  state_file=$(get_state_file "$session_id")
+  local state
+  state=$(read_state "$state_file")
+
+  # Find stash for this branch
+  local stash_ref
+  stash_ref=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .ref' | head -1)
+
+  if [[ -z "$stash_ref" ]] || [[ "$stash_ref" == "null" ]]; then
+    return 1  # No stash for this branch
+  fi
+
+  # Find the stash index by message
+  local stash_msg
+  stash_msg=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .message' | head -1)
+
+  local stash_index
+  stash_index=$(git stash list --format='%gd %s' | grep "$stash_msg" | head -1 | cut -d' ' -f1)
+
+  if [[ -n "$stash_index" ]]; then
+    if git stash pop "$stash_index" >/dev/null 2>&1; then
+      # Remove from state
+      update_state "$state_file" \
+        --arg branch "$target_branch" \
+        '.stashRefs = [.stashRefs[] | select(.branch != $branch)]'
+      return 0
+    fi
+  fi
+
+  return 1
+}
+```
+
+#### 4.7.3 Messages
+
+| Event | Message |
+|-------|---------|
+| Auto-stash on switch | `"[git-pilot] Stashed uncommitted changes on '${branch}' before switching."` |
+| Auto-restore on return | `"[git-pilot] Restored stashed changes on '${branch}'."` |
+| Restore failed (conflicts) | `"[git-pilot] Could not auto-restore stash on '${branch}' — conflicts detected. Run 'git stash pop' manually to resolve."` |
+
+### 4.8 Detached HEAD Recovery
+
+**Trigger**: `session-start.sh`, when `get_current_branch` returns empty.
+
+```bash
+# In session-start.sh
+current_branch=$(get_current_branch)
+
+if [[ -z "$current_branch" ]]; then
+  # Detached HEAD
+  local head_sha
+  head_sha=$(git rev-parse --short HEAD 2>/dev/null)
+
+  # Try to find what branch we were on
+  local prev_branch
+  prev_branch=$(git reflog show --format='%gs' | grep -m1 'checkout: moving from' | \
+    sed 's/checkout: moving from \([^ ]*\) to .*/\1/')
+
+  if [[ -n "$prev_branch" ]]; then
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Previous branch was '${prev_branch}'. Prompt the user: return to '${prev_branch}', create a new branch from HEAD, or continue in detached state.")
+  else
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Prompt the user: create a new branch from HEAD or continue in detached state.")
+  fi
+fi
+```
+
+### 4.9 Protected Branch Enforcement (Enhanced)
+
+**Modified file**: `scripts/pre-commit.sh`
+
+v1 only warns when committing to the default branch. v2 adds `"block"` mode:
+
+```bash
+protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$protect_mode")
+
+if is_on_default_branch "$CONFIG" 2>/dev/null; then
+  default_br=$(get_default_branch "$CONFIG")
+
+  case "$protect_mode" in
+    warn)
+      # v1 behavior — allow with warning
+      SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+      ;;
+    block)
+      # v2 — prevent the commit
+      output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+      ;;
+    off)
+      # No protection
+      ;;
+  esac
+fi
+```
+
+### 4.10 Network Error Handling
+
+**Modified file**: `scripts/git-utils.sh`
+
+```bash
+# In git-utils.sh
+fetch_with_retry() {
+  local remote_name="$1"
+  local config="$2"
+  local specific_branch="${3:-}"
+
+  local max_retries
+  max_retries=$(get_config "$config" '.git.fetchRetries' '2')
+  local retry_delay
+  retry_delay=$(get_config "$config" '.git.fetchRetryDelaySec' '3')
+
+  local fetch_args="$remote_name"
+  if [[ -n "$specific_branch" ]]; then
+    fetch_args="$remote_name $specific_branch"
+  fi
+
+  local attempt=0
+  local last_error=""
+
+  while (( attempt <= max_retries )); do
+    if git fetch $fetch_args 2>/dev/null; then
+      return 0
+    fi
+
+    last_error=$(git fetch $fetch_args 2>&1 || true)
+    attempt=$((attempt + 1))
+
+    if (( attempt <= max_retries )); then
+      sleep "$retry_delay"
+    fi
+  done
+
+  # All retries exhausted
+  echo "$last_error" >&2
+  return 1
+}
+```
+
+Messages:
+
+| Event | Message |
+|-------|---------|
+| Fetch failed, retrying | (no message — retries are silent) |
+| All retries exhausted | `"[git-pilot] Warning: Could not fetch from '${remote}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync."` |
+| Push failed (network) | `"[git-pilot] Push to '${remote}/${branch}' failed. Check network connectivity and try again."` |
+
+---
+
+## 5. External Interfaces
+
+### 5.1 Hook Scripts
+
+#### 5.1.1 Updated hooks.json
+
+```json
+{
+  "description": "git-pilot: Automated git workflow management",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-context.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-write.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-bash.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh",
+            "timeout": 45
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Changes from v1**:
+- SessionStart timeout: 15 → 30 (to accommodate fetch + freshness check)
+- PostToolUse Bash timeout: 10 → 15 (to accommodate push rejection detection + rebase)
+- Stop timeout: 30 → 45 (to accommodate drift detection + rebase + MR)
+- NEW: UserPromptSubmit hook for branch context (5s timeout)
+
+#### 5.1.2 New Script: `prompt-context.sh`
+
+Runs on every user prompt submission. Provides branch context for unrelated work detection.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/config.sh"
+source "$SCRIPT_DIR/git-utils.sh"
+source "$SCRIPT_DIR/agent.sh"
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+
+if [[ -z "$cwd" ]]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+cd "$cwd" 2>/dev/null || { echo '{"continue": true}'; exit 0; }
+
+if ! is_git_repo; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+config=$(load_config "$cwd")
+
+# Check if unrelated work detection is enabled
+detection_enabled=$(get_config "$config" '.branch.unrelatedWorkDetection' 'true')
+if [[ "$detection_enabled" != "true" ]]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Skip if agent context
+if is_agent_context "$session_id"; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+current_branch=$(get_current_branch)
+default_branch=$(get_default_branch "$config")
+
+# Skip if on default branch or no branch (detached HEAD)
+if [[ -z "$current_branch" ]] || [[ "$current_branch" == "$default_branch" ]]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Check if branch has commits
+commit_count=$(git rev-list --count "${default_branch}..${current_branch}" 2>/dev/null || echo "0")
+if [[ "$commit_count" == "0" ]]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Gather context
+branch_purpose=$(derive_branch_purpose "$current_branch")
+recent_commits=$(git log "${default_branch}..${current_branch}" --oneline --no-decorate -5 2>/dev/null || true)
+
+message="[git-pilot] Branch context: '${current_branch}' (${branch_purpose}). ${commit_count} commit(s). Recent: ${recent_commits}"
+
+jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+```
+
+#### 5.1.3 Modified Script: `session-start.sh`
+
+Key additions to existing session-start.sh:
+
+1. **Fetch remote** (after git init check, before branch detection):
+
+```bash
+# After Step 6 (git init check), before Step 7 (branch detection):
+
+# Step 6.5: Fetch remote
+if is_git_repo && has_remote; then
+  auto_fetch=$(get_config "$CONFIG" '.git.autoFetch' 'true')
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+
+  if [[ "$auto_fetch" == "true" ]]; then
+    if ! fetch_with_retry "$remote_name" "$CONFIG"; then
+      messages+=("[git-pilot] Warning: Could not fetch from '${remote_name}'. Proceeding without remote sync.")
+    fi
+  fi
+fi
+```
+
+2. **Branch freshness check** (after branch detection):
+
+```bash
+# After getting current_branch:
+if is_git_repo && has_remote && [[ -n "$current_branch" ]]; then
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  tracking_status=$(get_branch_tracking_status "$current_branch" "$remote_name")
+
+  case "$tracking_status" in
+    behind:*)
+      behind_count="${tracking_status#behind:}"
+      if git merge --ff-only "${remote_name}/${current_branch}" >/dev/null 2>&1; then
+        messages+=("[git-pilot] Branch '${current_branch}' was ${behind_count} commit(s) behind '${remote_name}/${current_branch}'. Fast-forwarded to latest.")
+      else
+        messages+=("[git-pilot] Branch '${current_branch}' is ${behind_count} commit(s) behind '${remote_name}/${current_branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is.")
+      fi
+      ;;
+    diverged:*:*)
+      IFS=':' read -r _ ahead_count behind_count <<< "$tracking_status"
+      messages+=("[git-pilot] Branch '${current_branch}' has diverged from '${remote_name}/${current_branch}' (${ahead_count} ahead, ${behind_count} behind). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue.")
+      ;;
+    ahead:*)
+      ahead_count="${tracking_status#ahead:}"
+      messages+=("[git-pilot] ${ahead_count} unpushed commit(s) on '${current_branch}'.")
+      ;;
+    # up-to-date and no-remote: no message
+  esac
+fi
+```
+
+3. **Detached HEAD detection** (in branch detection):
+
+```bash
+if [[ -z "$current_branch" ]]; then
+  # Detached HEAD handling (see §4.8)
+fi
+```
+
+4. **Extended state init** (replace Step 9):
+
+```bash
+if [[ -n "$SESSION_ID" ]]; then
+  base_branch="$default_branch"
+  branch_purpose=""
+  if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    branch_purpose=$(derive_branch_purpose "$current_branch")
+    # Try to detect base branch from tracking config
+    configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+    if [[ -n "$configured_base" ]]; then
+      base_branch="$configured_base"
+    fi
+  fi
+  init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
+fi
+```
+
+#### 5.1.4 Modified Script: `session-stop.sh`
+
+Key additions:
+
+1. **Drift detection before push/MR** (after work summary, before push workflow):
+
+```bash
+# After section 1 (work summary), before section 2 (push workflow):
+
+# 1.5: Base branch drift detection
+if [[ "$session_had_changes" == "true" ]] && has_remote; then
+  auto_rebase=$(get_config "$config" '.rebase.autoRebaseBeforePush' 'true')
+
+  if [[ "$auto_rebase" == "true" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    source "$SCRIPT_DIR/rebase.sh"
+
+    drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name")
+
+    case "$drift_status" in
+      drifted:*)
+        drift_count="${drift_status#drifted:}"
+        messages+=("[git-pilot] Base branch '${default_branch}' has ${drift_count} new commit(s). Rebasing '${current_branch}' onto '${remote_name}/${default_branch}'...")
+
+        rebase_result=$(attempt_rebase "${remote_name}/${default_branch}")
+
+        case "$rebase_result" in
+          success)
+            messages+=("[git-pilot] Rebase succeeded cleanly. Ready to push.")
+            ;;
+          conflict)
+            conflict_strategy=$(get_config "$config" '.rebase.conflictStrategy' 'prompt')
+            case "$conflict_strategy" in
+              prompt)
+                conflicts=$(get_conflict_details)
+                conflict_count=$(echo "$conflicts" | jq 'length')
+                conflict_files=$(echo "$conflicts" | jq -r '.[].file' | paste -sd', ')
+                messages+=("[git-pilot] Rebase conflicts in ${conflict_count} file(s): ${conflict_files}. Prompt the user to resolve conflicts, abort rebase, or use merge instead.")
+                ;;
+              abort)
+                git rebase --abort 2>/dev/null
+                messages+=("[git-pilot] Rebase aborted due to conflicts. Pushing without rebase.")
+                ;;
+              merge-fallback)
+                git rebase --abort 2>/dev/null
+                if git merge "${remote_name}/${default_branch}" --no-edit 2>/dev/null; then
+                  messages+=("[git-pilot] Merge with '${default_branch}' succeeded (rebase had conflicts).")
+                else
+                  conflicts=$(get_conflict_details)
+                  conflict_count=$(echo "$conflicts" | jq 'length')
+                  messages+=("[git-pilot] Both rebase and merge have conflicts in ${conflict_count} file(s). Prompt the user to resolve.")
+                fi
+                ;;
+            esac
+            ;;
+        esac
+        ;;
+      # no-drift, no-common-ancestor: no action
+    esac
+  fi
+fi
+```
+
+2. **Worktree cleanup** (after MR/push, before state cleanup):
+
+```bash
+# 3.5: Worktree cleanup
+source "$SCRIPT_DIR/worktree.sh"
+registry=$(list_worktrees)
+active_count=$(echo "$registry" | jq '.worktrees | length')
+
+if [[ "$active_count" -gt 0 ]]; then
+  cleanup_on_merge=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+  if [[ "$cleanup_on_merge" == "true" ]]; then
+    # Clean up merged worktrees
+    echo "$registry" | jq -r '.worktrees[] | select(.status == "active") | .path' | \
+    while IFS= read -r wt_path; do
+      if [[ -d "$wt_path" ]]; then
+        wt_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
+        # Check if branch is merged into default
+        if [[ -n "$wt_branch" ]] && git branch --merged "$default_branch" | grep -q "$wt_branch"; then
+          remove_worktree "$wt_path" "false"
+        fi
+      else
+        # Worktree directory gone, just unregister
+        unregister_worktree "$wt_path"
+      fi
+    done
+  fi
+
+  remaining=$(list_worktrees | jq '.worktrees | length')
+  if [[ "$remaining" -gt 0 ]]; then
+    messages+=("[git-pilot] ${remaining} active worktree(s) remain. Use /worktree to manage them.")
+  fi
+fi
+```
+
+#### 5.1.5 Modified Script: `post-bash.sh`
+
+Key additions:
+
+1. **Agent suppression**:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+
+# After loading config, before checking for push:
+if is_agent_context "$session_id"; then
+  if is_operation_agent_restricted "$config" "push"; then
+    echo '{"continue": true}'
+    exit 0
+  fi
+fi
+```
+
+2. **Push rejection detection** (new, after existing push prompt logic):
+
+```bash
+# Detect push rejection from the command output
+exit_code=$(echo "$input" | jq -r '.tool_result.exitCode // 0')
+stdout=$(echo "$input" | jq -r '.tool_result.stdout // empty')
+stderr=$(echo "$input" | jq -r '.tool_result.stderr // empty')
+
+if echo "$command" | grep -qE 'git\s+push' && [[ "$exit_code" != "0" ]]; then
+  if echo "$stderr" | grep -qiE 'rejected|failed to push|non-fast-forward'; then
+    current_branch=$(get_current_branch)
+    remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
+
+    message="[git-pilot] Push rejected — remote '${remote_name}/${current_branch}' has new commits. Prompt the user:
+1. Pull and rebase, then retry push (git pull --rebase && git push)
+2. Force push with lease (git push --force-with-lease)
+3. Pull and merge (git pull)
+4. Cancel"
+
+    jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+    exit 0
+  fi
+fi
+```
+
+#### 5.1.6 Modified Script: `post-write.sh`
+
+Agent suppression:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+
+# After loading config:
+if is_agent_context "$session_id"; then
+  # Still track file changes but don't emit commit suggestions
+  # (tracking code runs, but skip the threshold message)
+  exit 0
+fi
+```
+
+#### 5.1.7 Modified Script: `pre-commit.sh`
+
+Key additions:
+
+1. **Branch switch detection with auto-stash**:
+
+```bash
+# In the branch creation detection section, add branch switch detection:
+is_branch_switch_command() {
+  local cmd="$1"
+  SWITCH_TARGET=""
+
+  # git checkout <branch> (not -b)
+  if [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+-[bB] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  # git switch <branch> (not -c)
+  if [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+-[cC] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  return 1
+}
+
+# Before existing commit detection:
+SWITCH_TARGET=""
+if is_branch_switch_command "$COMMAND"; then
+  auto_stash=$(get_config "$CONFIG" '.branch.autoStashOnSwitch' 'true')
+  if [[ "$auto_stash" == "true" ]] && has_uncommitted_changes; then
+    current_br=$(get_current_branch)
+    if auto_stash "$current_br" "$SESSION_ID"; then
+      output_allow_with_message "[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."
+    fi
+  fi
+fi
+```
+
+2. **Enhanced protected branch blocking** (see §4.9).
+
+### 5.2 Skills
+
+#### 5.2.1 Existing Skills (Modified)
+
+**`/branch`**: Add `baseBranch` recording to session state after branch creation. Emit the new branch's purpose in the confirmation message.
+
+Add after Step 4:
+
+```markdown
+## Step 5: Record Branch Context
+
+After creating the branch, note the base branch (the branch you were on before switching)
+and the branch purpose (derived from the description). These are used for unrelated work
+detection and drift checks.
+```
+
+**`/finish`**: Add drift detection before push (see §4.2). The skill should call the same drift detection logic as `session-stop.sh`.
+
+Add between Step 1 and Step 2:
+
+```markdown
+## Step 1.5: Check Base Branch Drift
+
+Before pushing, check if the base branch has advanced:
+
+1. Run `git fetch <remote> <defaultBranch>`.
+2. Check for new commits on the base branch since this branch diverged.
+3. If the base has new commits and `rebase.autoRebaseBeforePush` is `true`:
+   - Attempt `git rebase <remote>/<defaultBranch>`.
+   - If rebase succeeds: continue to push.
+   - If rebase has conflicts: present conflict details and options to the user.
+4. If force push is needed after rebase, follow `rebase.allowForcePush` policy.
+```
+
+**`/summary`**: No changes needed.
+
+**`/configure`**: Add all new config keys to the reference table.
+
+Add to the reference table:
+
+```markdown
+| "Fetch remote on session start" | `git.autoFetch: true` |
+| "Block commits to main" | `git.protectDefaultBranch: "block"` |
+| "Don't warn about main branch commits" | `git.protectDefaultBranch: "off"` |
+| "Disable unrelated work detection" | `branch.unrelatedWorkDetection: false` |
+| "Don't auto-stash on branch switch" | `branch.autoStashOnSwitch: false` |
+| "Don't auto-rebase before push" | `rebase.autoRebaseBeforePush: false` |
+| "Never force push" | `rebase.allowForcePush: "never"` |
+| "Always force push after rebase" | `rebase.allowForcePush: "always"` |
+| "Use merge when rebase conflicts" | `rebase.conflictStrategy: "merge-fallback"` |
+| "Disable worktrees" | `worktree.enabled: false` |
+| "Worktrees in /tmp" | `worktree.basePath: "/tmp/{{project}}-worktrees"` |
+```
+
+#### 5.2.2 New Skills
+
+**`/stash`** — Manual stash management.
+
+```markdown
+---
+name: stash
+description: Manage git stashes - save, list, apply, or drop
+---
+
+# /stash
+
+Manage git stashes for the current repository.
+
+## Step 1: Determine Action
+
+If the user provided an argument after `/stash`, parse it:
+- `/stash` or `/stash save` — stash current changes
+- `/stash list` — list all stashes
+- `/stash pop` or `/stash apply` — restore the most recent stash
+- `/stash drop` — drop the most recent stash
+
+If no argument, ask the user what they want to do.
+
+## Step 2: Execute
+
+### Save
+1. Check for uncommitted changes. If none: "Nothing to stash."
+2. Ask the user for an optional stash message.
+3. Run `git stash push -m "<message>"` (or `git stash push` if no message).
+4. Confirm: "Stashed changes: <stash-ref>"
+
+### List
+1. Run `git stash list`.
+2. If empty: "No stashes found."
+3. Present the list with index, branch, and message.
+
+### Pop / Apply
+1. Run `git stash list`. If empty: "No stashes to restore."
+2. If multiple stashes, show the list and ask which one.
+3. For pop: `git stash pop <ref>`. For apply: `git stash apply <ref>`.
+4. If conflicts: warn the user and show conflicting files.
+
+### Drop
+1. Run `git stash list`. If empty: "No stashes to drop."
+2. If multiple stashes, show the list and ask which one.
+3. Confirm before dropping.
+4. Run `git stash drop <ref>`.
+```
+
+**`/worktree`** — Manual worktree management.
+
+```markdown
+---
+name: worktree
+description: Manage git worktrees for parallel branch work
+---
+
+# /worktree
+
+Manage git worktrees for parallel branch work.
+
+## Step 1: Determine Action
+
+Parse the user's intent:
+- `/worktree` or `/worktree list` — list active worktrees
+- `/worktree create <branch>` — create a new worktree for a branch
+- `/worktree remove <path-or-branch>` — remove a worktree
+- `/worktree merge <path-or-branch>` — merge a worktree's branch and clean up
+
+If no argument, show the list of active worktrees.
+
+## Step 2: Execute
+
+### List
+1. Read the worktree registry (`.git/git-pilot-worktrees.json`).
+2. Also run `git worktree list` for system-level view.
+3. Present: path, branch, base branch, creation date, status.
+
+### Create
+1. Ask for the branch name (or parse from argument).
+2. Ask for the base branch (default: `git.defaultBranch`).
+3. Determine the worktree path using `worktree.basePath` config.
+4. Run `git worktree add <path> -b <branch> <base>`.
+5. Register in the worktree registry.
+6. Confirm with the worktree path.
+
+### Remove
+1. Identify the worktree by path or branch name.
+2. Check for uncommitted changes in the worktree.
+3. If uncommitted changes, warn and ask to confirm.
+4. Run `git worktree remove <path>`.
+5. Optionally delete the branch: `git branch -d <branch>`.
+6. Unregister from the registry.
+
+### Merge
+1. Identify the worktree by path or branch name.
+2. Get the worktree's branch and its base branch from the registry.
+3. Switch main worktree to the base branch.
+4. Attempt `git merge <worktree-branch> --no-edit`.
+5. If conflicts: present them and ask user to resolve.
+6. If `worktree.cleanupOnMerge` is `true`: remove the worktree and delete the branch.
+7. Confirm the merge.
+```
+
+**`/rebase`** — Manual rebase operations.
+
+```markdown
+---
+name: rebase
+description: Rebase current branch onto another branch
+---
+
+# /rebase
+
+Rebase the current branch onto a target branch.
+
+## Step 1: Determine Target
+
+If the user specified a target branch (e.g., `/rebase main`), use it.
+Otherwise, default to the configured `git.defaultBranch`.
+
+## Step 2: Pre-flight Checks
+
+1. Ensure the working tree is clean. If uncommitted changes exist, ask to stash or commit first.
+2. Fetch the remote target branch: `git fetch <remote> <target>`.
+3. Check how many commits will be rebased: `git rev-list --count <remote>/<target>..HEAD`.
+4. Show the user: "Rebasing N commit(s) onto <remote>/<target>."
+
+## Step 3: Execute Rebase
+
+1. Run `git rebase <remote>/<target>`.
+2. If success: "Rebase completed successfully."
+3. If conflicts:
+   - Show conflicting files and conflict details.
+   - Present resolution options:
+     a. Resolve manually (edit files, then `git add <file>` and `git rebase --continue`)
+     b. Accept theirs for all (`git checkout --theirs . && git add .`)
+     c. Accept ours for all (`git checkout --ours . && git add .`)
+     d. Abort (`git rebase --abort`)
+   - After resolution, run `git rebase --continue`.
+
+## Step 4: Handle Force Push
+
+If the branch was previously pushed and rebase rewrote history:
+1. Inform: "Rebase rewrote history. Force push is needed to update the remote."
+2. Based on `rebase.allowForcePush`:
+   - `"ask"`: Ask user to confirm force push.
+   - `"always"`: Push with `--force-with-lease` automatically.
+   - `"never"`: Inform that force push is disabled.
+3. Use `git push --force-with-lease <remote> <branch>`.
+```
+
+### 5.3 CLAUDE.md Behavioral Rules
+
+The complete v2 CLAUDE.md replaces the v1 version. Key additions:
+
+**Rule 7**: Unrelated work detection (see §4.4 for full text).
+
+**Rule 8**: Branch switching with stash management.
+
+```markdown
+## Rule 8: Branch switching
+
+When switching branches (via /branch, user request, or unrelated work detection):
+
+1. If there are uncommitted changes and `branch.autoStashOnSwitch` is `true`, stash
+   them automatically before switching. Inform the user: "Stashed changes on '<branch>'."
+2. After switching, check if there's a git-pilot stash for the target branch and
+   restore it automatically.
+3. If stash restoration fails (conflicts), inform the user and suggest manual resolution.
+```
+
+**Rule 9**: Conflict resolution guidance.
+
+```markdown
+## Rule 9: Conflict resolution
+
+When a rebase or merge results in conflicts:
+
+1. Read the conflicting files to understand the nature of each conflict.
+2. For each conflict, provide a recommendation:
+   - If only one side modified the region, recommend accepting that side.
+   - If both sides modified the same lines, recommend manual review.
+   - If a file was deleted on one side, explain the tradeoff.
+3. Present clear options: resolve manually, accept ours, accept theirs, abort.
+4. After the user resolves conflicts, continue the interrupted operation
+   (`git rebase --continue` or `git merge --continue`).
+```
+
+**Rule 10**: Agent awareness.
+
+```markdown
+## Rule 10: Agent Teams
+
+When operating as a spawned agent (not the orchestrator):
+
+1. Do not prompt for push, MR creation, or branch switching. These are
+   orchestrator-only operations.
+2. Follow commit rules normally — agents must still use proper commit format.
+3. Do not run auto-commit suggestions. Commit when instructed by the orchestrator.
+4. If instructed to work in a specific worktree directory, stay in that directory.
+```
+
+**Updated skill reference table**:
+
+```markdown
+| Skill | When to use |
+|-------|-------------|
+| `/branch` | Proactively when on the default branch before making changes |
+| `/finish` | When the user says they're done, or at session end |
+| `/summary` | When the user asks for a recap of branch work |
+| `/configure` | When the user wants to change git-pilot settings |
+| `/stash` | When the user wants to manage git stashes |
+| `/worktree` | When the user wants to manage git worktrees |
+| `/rebase` | When the user wants to rebase the current branch |
+```
+
+---
+
+## 6. Error Handling
+
+### 6.1 Error Types
+
+| Error Category | Source | Handling |
+|---------------|--------|----------|
+| Network failure | `git fetch`, `git push` | Retry with backoff (§4.10). Warn user after exhaustion. Continue without blocking. |
+| Git operation failure | `git rebase`, `git merge`, `git stash` | Detect error type. Emit specific message. Never leave repo in broken state (abort incomplete operations). |
+| Config parse failure | `jq` parsing | Fall back to defaults. Emit: `"[git-pilot] Warning: Could not parse config file. Using defaults."` |
+| State file failure | `/tmp` write | Emit warning. Disable state-dependent features for this session. Do not crash. |
+| Missing dependency | `git`, `jq` not installed | Emit warning at session start. Disable affected features. |
+
+### 6.2 Invariant: Never Leave Broken State
+
+If any git operation is interrupted or fails mid-way:
+- An in-progress rebase MUST be aborted: `git rebase --abort`.
+- An in-progress merge MUST be aborted: `git merge --abort`.
+- A half-created worktree MUST be cleaned up.
+- Stash operations that fail MUST NOT lose data (use `stash apply` before `stash drop`).
+
+Every function that starts a multi-step git operation must have cleanup logic in its error path.
+
+### 6.3 User-Facing Error Messages
+
+All error messages follow the pattern: `[git-pilot] <context>: <specific error>. <suggestion>.`
+
+Examples:
+- `"[git-pilot] Rebase failed: could not apply commit abc1234. Conflicts in 2 file(s). Resolve conflicts or run 'git rebase --abort' to cancel."`
+- `"[git-pilot] Worktree creation failed: branch 'feat/auth' already exists. Use a different name or delete the existing branch."`
+- `"[git-pilot] Stash restore failed: conflicts in src/main.rs. Run 'git stash pop' manually to resolve."`
+
+---
+
+## 7. Configuration
+
+### 7.1 Config File Locations
+
+| Priority | Path | Scope |
+|----------|------|-------|
+| 1 (lowest) | `${PLUGIN_ROOT}/defaults/config.json` | Plugin defaults |
+| 2 | `~/.claude/git-pilot.json` | User global |
+| 3 (highest) | `${CWD}/.claude/git-pilot.json` | Project local |
+
+### 7.2 Config Loading
+
+The existing `config.sh` `load_config()` function handles the three-tier merge. No changes needed to the merge logic.
+
+The `normalize_protect_default_branch()` function (§3.1.2) must be called wherever `git.protectDefaultBranch` is read, to handle the boolean → string migration.
+
+### 7.3 Complete Config Key Reference
+
+See §3.1.1 for the full defaults file. See §3.1.3 for the new keys reference table.
+
+---
+
+## 8. Testing Strategy
+
+### 8.1 Unit Testing Approach
+
+Each bash function should be testable in isolation. Use a test harness that:
+1. Creates temporary git repositories with controlled state.
+2. Sources the script under test.
+3. Calls functions and asserts outputs.
+
+Test framework: `bats-core` (Bash Automated Testing System).
+
+### 8.2 Key Test Scenarios
+
+#### Branch Freshness (§4.1)
+- Branch is behind remote → auto fast-forward succeeds.
+- Branch is behind remote → fast-forward fails (merge commit needed) → warning emitted.
+- Branch has diverged from remote → warning with options emitted.
+- Branch is ahead of remote → unpushed info emitted.
+- No remote → no freshness check.
+- Fetch fails → warning emitted, continues without freshness data.
+
+#### Base Branch Drift (§4.2)
+- Base branch has drifted → rebase attempted.
+- Base branch has not drifted → no action.
+- No common ancestor → warning emitted, push proceeds.
+
+#### Rebase and Conflicts (§4.3)
+- Clean rebase succeeds → success message.
+- Rebase with conflicts → conflict details reported.
+- Conflict strategy "abort" → rebase aborted immediately.
+- Conflict strategy "merge-fallback" → merge attempted after rebase fails.
+- Force push detection after rebase → appropriate prompt based on config.
+- Push rejection detected → options presented.
+
+#### Agent Detection (§4.5)
+- `CLAUDE_SPAWNED_BY` set → prompts suppressed.
+- State file `isAgent: true` → prompts suppressed.
+- Neither set → normal interactive behavior.
+- Commit validation still active for agents.
+
+#### Worktree Management (§4.6)
+- Worktree created → registered in registry.
+- Worktree removed → unregistered from registry.
+- Worktree merge → branch merged, worktree cleaned up.
+- Worktree directory already exists → error reported.
+
+#### Stash Management (§4.7)
+- Auto-stash on branch switch → changes stashed, message emitted.
+- Auto-restore on return → stash popped, message emitted.
+- Restore fails → warning with manual instructions.
+
+#### Protected Branch (§4.9)
+- `"warn"` mode → warning emitted, commit allowed.
+- `"block"` mode → commit blocked with exit code 2.
+- `"off"` mode → no message.
+- Boolean `true` → treated as `"warn"`.
+- Boolean `false` → treated as `"off"`.
+
+#### Config Backward Compatibility
+- v1 config with `protectDefaultBranch: true` → normalized to `"warn"`.
+- v1 config with `protectDefaultBranch: false` → normalized to `"off"`.
+- v2 config with all new keys → works as specified.
+- Missing new keys → defaults used.
+
+### 8.3 Integration Test Scenarios
+
+1. **Full session lifecycle**: Start session → detect stale branch → fetch → fast-forward → work → commit → detect drift → rebase → push → create MR → summary → cleanup.
+2. **Conflict resolution flow**: Start session → work → attempt push → drift detected → rebase fails → conflicts shown → user resolves → rebase continues → push succeeds.
+3. **Branch switching flow**: Start on feature branch → user requests unrelated work → prompt shown → user creates new branch → changes auto-stashed → new branch created → work done → switch back → stash restored.
+4. **Agent teams flow**: Orchestrator creates worktree → agent works in worktree → agent commits without push prompts → orchestrator merges worktree → cleanup.
+
+---
+
+## 9. Build and Deployment
+
+### 9.1 Build Commands
+
+```bash
+# Syntax check all bash scripts
+for f in plugins/git-pilot/scripts/*.sh; do bash -n "$f"; done
+
+# Lint with shellcheck
+shellcheck plugins/git-pilot/scripts/*.sh
+
+# Run tests (bats)
+bats plugins/git-pilot/tests/
+```
+
+### 9.2 Dependencies
+
+| Dependency | Version | Required |
+|-----------|---------|----------|
+| `bash` | >= 4.0 | Yes |
+| `git` | >= 2.30 (worktree support) | Yes |
+| `jq` | >= 1.6 | Yes |
+| `gh` | any | Optional (GitHub PR creation) |
+| `glab` | any | Optional (GitLab MR creation) |
+| `shellcheck` | any | Dev only |
+| `bats-core` | >= 1.0 | Dev only |
+
+### 9.3 File Manifest
+
+```
+plugins/git-pilot/
+├── .claude-plugin/
+│   └── plugin.json              # Version bumped to 2.0.0
+├── CLAUDE.md                    # Updated behavioral rules (10 rules)
+├── README.md                    # Updated documentation
+├── defaults/
+│   └── config.json              # Extended with new keys
+├── hooks/
+│   └── hooks.json               # Updated timeouts + UserPromptSubmit hook
+├── scripts/
+│   ├── agent.sh                 # NEW: Agent Teams detection
+│   ├── config.sh                # Minor: normalize_protect_default_branch()
+│   ├── git-utils.sh             # Extended: fetch, tracking, stash, branch utils
+│   ├── post-bash.sh             # Modified: agent suppression, push rejection
+│   ├── post-write.sh            # Modified: agent suppression
+│   ├── pre-commit.sh            # Modified: branch switch detection, block mode
+│   ├── prompt-context.sh        # NEW: UserPromptSubmit branch context
+│   ├── rebase.sh                # NEW: Rebase operations and conflict handling
+│   ├── session-start.sh         # Modified: fetch, freshness, detached HEAD
+│   ├── session-stop.sh          # Modified: drift detection, worktree cleanup
+│   ├── state.sh                 # Extended: new state fields
+│   └── worktree.sh              # NEW: Worktree management
+├── skills/
+│   ├── branch/SKILL.md          # Modified: base branch recording
+│   ├── configure/SKILL.md       # Modified: new config keys
+│   ├── finish/SKILL.md          # Modified: drift detection
+│   ├── rebase/SKILL.md          # NEW: Manual rebase skill
+│   ├── stash/SKILL.md           # NEW: Stash management skill
+│   ├── summary/SKILL.md         # Unchanged
+│   └── worktree/SKILL.md        # NEW: Worktree management skill
+└── tests/                       # NEW: Test directory
+    ├── test_helper/
+    │   └── common.bash          # Shared test fixtures
+    ├── branch-freshness.bats
+    ├── drift-detection.bats
+    ├── rebase.bats
+    ├── agent-detection.bats
+    ├── worktree.bats
+    ├── stash.bats
+    ├── protected-branch.bats
+    └── config-compat.bats
+```
+
+### 9.4 Version Bump
+
+`plugin.json` version changes from `"1.1.0"` to `"2.0.0"`. This is a major version bump because:
+- `git.protectDefaultBranch` type changed from boolean to string (breaking for strict consumers).
+- New behavioral rules in CLAUDE.md change default agent behavior.
+- New hook (UserPromptSubmit) changes the lifecycle.
+
+---
+
+## 10. Implementation Notes
+
+### 10.1 Performance Considerations
+
+- `git fetch` is the most expensive operation (network I/O). The session-start.sh timeout is increased to 30s, but fetch should typically complete in <5s. The retry logic adds up to `fetchRetries * fetchRetryDelaySec` seconds worst-case.
+- `prompt-context.sh` runs on every user prompt. It must be fast (<1s). It only runs `git rev-list --count` and `git log -5` which are fast local operations.
+- `jq` is called multiple times per hook invocation for config parsing. Each call is fast (<10ms) but adds up. The existing pattern of loading config once and passing it to functions is maintained.
+
+### 10.2 Security Considerations
+
+- **Never bare `--force`**: Always use `--force-with-lease` for force pushes to prevent overwriting others' work.
+- **No secrets in state files**: State files in `/tmp` are readable by other processes on the system. They contain only branch names, timestamps, and commit hashes — no credentials.
+- **Config file permissions**: The plugin does not manage file permissions. Users should ensure `~/.claude/git-pilot.json` has appropriate permissions if it contains sensitive settings (unlikely, but noted).
+
+### 10.3 Known Complexity Areas
+
+- **Heredoc commit message parsing** in `pre-commit.sh`: The existing regex-based parser handles most cases but may fail on deeply nested or unusual quoting. v2 does not change this parser.
+- **Branch switch detection** in `pre-commit.sh`: Detecting `git checkout <branch>` vs. `git checkout <file>` is inherently ambiguous. The regex checks for the absence of `-b` flag, but `git checkout` with a path and no `--` separator may be misdetected. This is a known limitation.
+- **Stash identification**: Finding a specific stash by message is fragile if the user manually creates stashes with similar messages. The `auto_restore_stash` function searches by the exact message prefix `"git-pilot auto-stash on "`.
+- **Agent detection**: The `CLAUDE_SPAWNED_BY` environment variable depends on Claude Code's implementation. If the variable name changes, the detection will need updating. The state-file fallback (`isAgent` flag) provides a manual override.
+
+### 10.4 Backward Compatibility Guarantees
+
+1. All v1 config files work unchanged with v2.
+2. The default behavior of v2 with a v1 config is identical to v1, except:
+   - `git fetch` runs on session start (new behavior, can be disabled with `git.autoFetch: false`).
+   - Branch freshness information is shown (informational only, no action forced).
+   - The `UserPromptSubmit` hook runs (lightweight, emits context for unrelated work detection).
+3. No existing config keys are removed.
+4. The `protectDefaultBranch` boolean→string migration is handled transparently.
diff --git a/spec/01-config-and-state.md b/spec/01-config-and-state.md
new file mode 100644
index 0000000..228cde5
--- /dev/null
+++ b/spec/01-config-and-state.md
@@ -0,0 +1,401 @@
+# Module 01: Configuration and State
+
+**Depends on:** none. This is the foundational module. All other modules source `config.sh` and `state.sh`.
+
+---
+
+## 1. Three-Tier Config Merge
+
+Configuration uses a three-tier merge: plugin defaults -> global -> local. Local overrides global, global overrides defaults. The merge is a shallow recursive merge via `jq -s '.[0] * .[1]'`.
+
+### 1.1 Config File Locations
+
+| Priority | Path | Scope |
+|----------|------|-------|
+| 1 (lowest) | `${PLUGIN_ROOT}/defaults/config.json` | Plugin defaults |
+| 2 | `~/.claude/git-pilot.json` | User global |
+| 3 (highest) | `${CWD}/.claude/git-pilot.json` | Project local |
+
+### 1.2 Config Loading Functions
+
+```bash
+# config.sh
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+load_config() {
+  local cwd="${1:-.}"
+  local defaults="$PLUGIN_ROOT/defaults/config.json"
+  local global="$HOME/.claude/git-pilot.json"
+  local local_cfg="$cwd/.claude/git-pilot.json"
+
+  local result
+  result=$(cat "$defaults")
+
+  if [[ -f "$global" ]]; then
+    result=$(echo "$result" | jq -s '.[0] * .[1]' - "$global" 2>/dev/null || echo "$result")
+  fi
+
+  if [[ -f "$local_cfg" ]]; then
+    result=$(echo "$result" | jq -s '.[0] * .[1]' - "$local_cfg" 2>/dev/null || echo "$result")
+  fi
+
+  echo "$result"
+}
+
+get_config() {
+  local config="$1"
+  local key="$2"
+  local default="$3"
+  echo "$config" | jq -r "if ($key) == null then \"$default\" else ($key) end"
+}
+```
+
+No changes are needed to the merge logic itself in v2. The `load_config()` and `get_config()` functions remain as shown above.
+
+**Failure behavior**: If `jq` cannot parse a config file, the `2>/dev/null || echo "$result"` guard preserves the previous tier's result and processing continues. The caller should emit: `"[git-pilot] Warning: Could not parse config file. Using defaults."`
+
+---
+
+## 2. Complete v2 Config Schema (`defaults/config.json`)
+
+```jsonc
+{
+  "git": {
+    "defaultBranch": "main",
+    "autoInit": true,
+    "protectDefaultBranch": "warn",
+    "autoFetch": true,
+    "fetchRetries": 2,
+    "fetchRetryDelaySec": 3
+  },
+  "branch": {
+    "pattern": "{{type}}/{{description}}",
+    "types": ["feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "build", "ci"],
+    "descriptionSeparator": "-",
+    "descriptionCase": "kebab",
+    "maxLength": 72,
+    "autoCreate": true,
+    "unrelatedWorkDetection": true,
+    "autoStashOnSwitch": true
+  },
+  "commit": {
+    "pattern": "{{type}}({{scope}}): {{description}}",
+    "types": ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
+    "maxSubjectLength": 72,
+    "scopeRequired": false,
+    "body": {
+      "required": false,
+      "wrap": 72,
+      "includeChangedFiles": false
+    },
+    "signature": {
+      "stripCoAuthoredBy": true,
+      "stripAiAttribution": true,
+      "stripSignedOffBy": false
+    },
+    "breakingChange": {
+      "appendExclamation": true,
+      "requireBody": true,
+      "bodyPrefix": "BREAKING CHANGE: "
+    }
+  },
+  "autoCommit": {
+    "enabled": true,
+    "mode": "suggest",
+    "threshold": 3,
+    "includeWip": false,
+    "wipPrefix": "wip: "
+  },
+  "remote": {
+    "promptForRemote": true,
+    "skipRemotePrompt": false,
+    "defaultName": "origin",
+    "autoPush": false,
+    "pushOnFinish": "ask"
+  },
+  "rebase": {
+    "autoRebaseBeforePush": true,
+    "conflictStrategy": "prompt",
+    "allowForcePush": "ask"
+  },
+  "mergeRequest": {
+    "enabled": true,
+    "createOnFinish": "ask",
+    "platform": "auto",
+    "titleFromBranch": true,
+    "bodyTemplate": null,
+    "draft": false,
+    "labels": [],
+    "assignToSelf": true
+  },
+  "worktree": {
+    "enabled": true,
+    "basePath": "../{{project}}-worktrees",
+    "cleanupOnMerge": true
+  },
+  "agentTeams": {
+    "suppressPromptsForAgents": true,
+    "orchestratorOnly": ["push", "mr"]
+  },
+  "summary": {
+    "includeFileChanges": true,
+    "includeDiff": false,
+    "includeCommitLog": true,
+    "format": "markdown"
+  }
+}
+```
+
+### 2.1 New Config Keys Reference (v2)
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `git.autoFetch` | boolean | `true` | Run `git fetch` on session start |
+| `git.fetchRetries` | integer | `2` | Number of retry attempts on fetch failure |
+| `git.fetchRetryDelaySec` | integer | `3` | Seconds between fetch retries |
+| `git.protectDefaultBranch` | string | `"warn"` | `"warn"` / `"block"` / `"off"` -- was boolean in v1 |
+| `branch.unrelatedWorkDetection` | boolean | `true` | Enable unrelated work detection prompts |
+| `branch.autoStashOnSwitch` | boolean | `true` | Auto-stash uncommitted changes on branch switch |
+| `rebase.autoRebaseBeforePush` | boolean | `true` | Rebase onto base branch before push/MR |
+| `rebase.conflictStrategy` | string | `"prompt"` | `"prompt"` / `"abort"` / `"merge-fallback"` |
+| `rebase.allowForcePush` | string | `"ask"` | `"ask"` / `"never"` / `"always"` |
+| `worktree.enabled` | boolean | `true` | Enable worktree management for Agent Teams |
+| `worktree.basePath` | string | `"../{{project}}-worktrees"` | Worktree directory pattern |
+| `worktree.cleanupOnMerge` | boolean | `true` | Remove worktree after successful merge |
+| `agentTeams.suppressPromptsForAgents` | boolean | `true` | Suppress interactive prompts for spawned agents |
+| `agentTeams.orchestratorOnly` | array | `["push", "mr"]` | Operations restricted to orchestrator agent |
+
+---
+
+## 3. Backward Compatibility: `protectDefaultBranch` Boolean-to-String Migration
+
+v1 used a boolean for `git.protectDefaultBranch`. v2 uses a string enum (`"warn"`, `"block"`, `"off"`). The config loading code must handle both transparently.
+
+### 3.1 `normalize_protect_default_branch()` Function
+
+This function **must** be called wherever `git.protectDefaultBranch` is read:
+
+```bash
+# In config.sh
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
+```
+
+Mapping:
+
+| v1 value | v2 equivalent |
+|----------|---------------|
+| `true` | `"warn"` |
+| `false` | `"off"` |
+
+Unknown values default to `"warn"`.
+
+### 3.2 Backward Compatibility Guarantees
+
+1. All v1 config files work unchanged with v2.
+2. The default behavior of v2 with a v1 config is identical to v1, except:
+   - `git fetch` runs on session start (new behavior, can be disabled with `git.autoFetch: false`).
+   - Branch freshness information is shown (informational only, no action forced).
+   - The `UserPromptSubmit` hook runs (lightweight, emits context for unrelated work detection).
+3. No existing config keys are removed.
+4. The `protectDefaultBranch` boolean-to-string migration is handled transparently.
+5. Missing new keys use defaults from `defaults/config.json` via the three-tier merge.
+
+---
+
+## 4. State Management Library (`state.sh`)
+
+All hook scripts source `state.sh` for session state operations. The library uses an atomic write pattern (temp file + `mv`) to prevent data corruption.
+
+### 4.1 Function Signatures
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `get_state_file` | `session_id` | Path string on stdout | Returns `/tmp/git-pilot-${session_id}.json` |
+| `read_state` | `state_file` | JSON string on stdout | Reads state file; returns `{}` if missing |
+| `write_state` | `state_file`, `content` | (none) | Atomic write via temp file + `mv`; warns on failure, never crashes |
+| `init_state` | `session_id`, `working_branch?`, `previous_branch?`, `base_branch?`, `branch_purpose?` | (none) | Creates initial session state (v2 adds params 4-5) |
+| `update_state` | `state_file`, `[jq_args...]`, `jq_filter` | (none) | Reads state, applies jq filter, writes back atomically |
+| `cleanup_state` | `state_file` | (none) | Removes the session state file |
+
+### 4.2 Key Implementations
+
+```bash
+# state.sh — atomic write (used by init_state, update_state)
+write_state() {
+  local state_file="$1" content="$2"
+  local tmp_file="${state_file}.tmp.$$"
+  if ! echo "$content" > "$tmp_file"; then
+    echo "[git-pilot] Warning: Cannot access session state. Auto-commit tracking disabled for this session." >&2
+    rm -f "$tmp_file"; return 0
+  fi
+  if ! mv "$tmp_file" "$state_file"; then
+    echo "[git-pilot] Warning: Cannot access session state. Auto-commit tracking disabled for this session." >&2
+    rm -f "$tmp_file"; return 0
+  fi
+}
+
+# v2 init_state — called from session-start.sh
+init_state() {
+  local session_id="$1" working_branch="${2:-}" previous_branch="${3:-}"
+  local base_branch="${4:-}" branch_purpose="${5:-}"
+  local state_file head_at_start=""
+  state_file=$(get_state_file "$session_id")
+  if command -v git >/dev/null 2>&1 && git rev-parse HEAD >/dev/null 2>&1; then
+    head_at_start=$(git rev-parse HEAD 2>/dev/null || true)
+  fi
+  local content
+  content=$(jq -n \
+    --arg sid "$session_id" --arg start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg wb "$working_branch" --arg pb "$previous_branch" \
+    --arg head "$head_at_start" --arg bb "$base_branch" --arg bp "$branch_purpose" \
+    '{ sessionId:$sid, startTime:$start, workingBranch:$wb, previousBranch:$pb,
+       headAtStart:$head, baseBranch:$bb, branchPurpose:$bp, changeCount:0,
+       lastCommitAt:null, modifiedFiles:[], remoteSkipped:false, lastFetchAt:null,
+       isAgent:false, agentRole:null, activeWorktrees:[], stashRefs:[] }')
+  write_state "$state_file" "$content"
+}
+
+# update_state — supports extra jq args (e.g., --arg key val)
+update_state() {
+  local state_file="$1"; shift
+  local current; current=$(read_state "$state_file")
+  local updated; updated=$(echo "$current" | jq "$@")
+  write_state "$state_file" "$updated"
+}
+```
+
+### 4.3 Atomic Write Pattern
+
+`write_state()` writes to `${state_file}.tmp.$$` (PID-suffixed), then renames via `mv` (atomic on POSIX). On failure, it emits a warning to stderr and returns 0 (never crashes).
+
+---
+
+## 5. Session State Schema
+
+### 5.1 Complete Session State Object
+
+```jsonc
+{
+  "sessionId": "abc123",
+  "startTime": "2026-02-24T20:00:00Z",
+  "workingBranch": "feat/add-dark-mode",
+  "previousBranch": "main",
+  "headAtStart": "a1b2c3d4",
+  "baseBranch": "main",
+  "branchPurpose": "add dark mode",
+  "changeCount": 0,
+  "lastCommitAt": null,
+  "modifiedFiles": [],
+  "remoteSkipped": false,
+  "lastFetchAt": "2026-02-24T20:00:05Z",
+  "isAgent": false,
+  "agentRole": null,
+  "activeWorktrees": [],
+  "stashRefs": []
+}
+```
+
+### 5.2 New Fields (v2)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `baseBranch` | string | The branch this feature branch was created from or targets for MR |
+| `branchPurpose` | string | Human-readable purpose derived from branch name (e.g., `"add dark mode"` from `feat/add-dark-mode`) |
+| `lastFetchAt` | string\|null | ISO timestamp of last `git fetch` in this session |
+| `isAgent` | boolean | Whether this session is a spawned agent (not orchestrator) |
+| `agentRole` | string\|null | `"orchestrator"`, `"implementer"`, `"validator"`, or null |
+| `activeWorktrees` | array | List of `{path, branch, createdAt}` objects for worktrees created in this session |
+| `stashRefs` | array | List of `{ref, branch, message, createdAt}` for stashes created by git-pilot |
+
+### 5.3 State File Location
+
+Path: `/tmp/git-pilot-${SESSION_ID}.json`
+
+State files are ephemeral and cleaned up on session stop. They are not shared between sessions. For cross-session persistence, see the Worktree Registry below.
+
+---
+
+## 6. Worktree Registry Schema
+
+For multi-session worktree tracking, a registry file is stored at `.git/git-pilot-worktrees.json`. This registry persists across sessions, unlike session state files which are cleaned up on session stop.
+
+### 6.1 Complete Registry Object
+
+```jsonc
+{
+  "worktrees": [
+    {
+      "path": "../myproject-worktrees/feat-add-auth",
+      "branch": "feat/add-auth",
+      "baseBranch": "main",
+      "createdAt": "2026-02-24T20:00:00Z",
+      "createdBy": "session-abc123",
+      "status": "active"
+    }
+  ]
+}
+```
+
+### 6.2 Registry Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `worktrees` | array | List of worktree entries |
+| `worktrees[].path` | string | Filesystem path to the worktree directory |
+| `worktrees[].branch` | string | Branch checked out in the worktree |
+| `worktrees[].baseBranch` | string | Branch this worktree's branch was created from |
+| `worktrees[].createdAt` | string | ISO timestamp of worktree creation |
+| `worktrees[].createdBy` | string | Session ID that created this worktree |
+| `worktrees[].status` | string | `"active"` or other status values |
+
+### 6.3 Registry Location
+
+Path: `${GIT_DIR}/git-pilot-worktrees.json` (typically `.git/git-pilot-worktrees.json`).
+
+The registry lives inside `.git/` so it is not committed to the repository but persists across sessions for the same clone.
+
+---
+
+## 7. Protected Branch Behavior by Mode
+
+The `git.protectDefaultBranch` config key (after normalization) controls behavior when committing to the default branch:
+
+| Mode | Behavior |
+|------|----------|
+| `"warn"` | Warning emitted via systemMessage, commit allowed |
+| `"block"` | Commit blocked with exit code 2 |
+| `"off"` | No message, no restriction |
+
+---
+
+## 8. Error Handling
+
+Error handling for config and state operations (see TECHNICAL-SPEC SS6.1 for the full taxonomy):
+
+| Error | Handling | Message |
+|-------|----------|---------|
+| Config parse failure | Fall back to previous tier via `2>/dev/null \|\| echo "$result"` | `"[git-pilot] Warning: Could not parse config file. Using defaults."` |
+| State file failure | `write_state()` warns and returns 0; state-dependent features disabled | `"[git-pilot] Warning: Cannot access session state. Auto-commit tracking disabled for this session."` |
+| Missing `git` | Warn at session start; git features disabled | `"[git-pilot] Warning: git is not installed. Git workflow features are disabled."` |
+| Missing `jq` | Warn at session start; config loading degraded | `"[git-pilot] Warning: jq is not installed. Configuration loading may not work correctly."` |
+
+The plugin never crashes on these errors. Dependencies are checked via `command -v` at session start.
+
+---
+
+## 9. Version Bump
+
+`plugin.json` version changes from `"1.1.0"` to `"2.0.0"` because:
+- `git.protectDefaultBranch` type changed from boolean to string (breaking for strict consumers).
+- New behavioral rules in CLAUDE.md change default agent behavior.
+- New hook (`UserPromptSubmit`) changes the lifecycle.
\ No newline at end of file
diff --git a/spec/02-git-utils-and-network.md b/spec/02-git-utils-and-network.md
new file mode 100644
index 0000000..b255d3a
--- /dev/null
+++ b/spec/02-git-utils-and-network.md
@@ -0,0 +1,331 @@
+# Module 02: Git Utilities and Network
+
+## Cross-references
+
+- **Depends on `01-config-and-state.md`** for:
+  - `get_config()` function signature used to read config values (e.g., `get_config "$config" '.git.fetchRetries' '2'`).
+  - Config schema: `git.autoFetch`, `git.fetchRetries`, `git.fetchRetryDelaySec`, `remote.defaultName`.
+  - Session state schema: `lastFetchAt` field, `write_state()` / `update_state()` for atomic state writes.
+  - Three-tier config merge: plugin defaults -> global (`~/.claude/git-pilot.json`) -> local (`.claude/git-pilot.json`).
+
+---
+
+## Overview
+
+This module covers `scripts/git-utils.sh`, which provides core git utility functions used by every hook script:
+
+1. **Core Utility Functions** -- v1 functions (`is_git_repo`, `has_remote`, `get_current_branch`, etc.) used by all downstream modules.
+2. **Branch Freshness Detection** (TECHNICAL-SPEC SS4.1) -- runs at session start to detect whether the current branch is behind, ahead, diverged, or has no remote tracking branch, and takes automatic action (fast-forward) or emits a systemMessage.
+3. **Network Error Handling** (TECHNICAL-SPEC SS4.10) -- provides retry logic for `git fetch` and defines messages for network failures.
+4. **Branch Purpose Derivation** (TECHNICAL-SPEC SS4.4) -- derives human-readable purpose from branch names for unrelated work detection.
+
+---
+
+## 1. Branch Freshness Detection
+
+**Trigger**: SessionStart hook (`session-start.sh`)
+
+**Preconditions**: Repository has at least one remote. `git.autoFetch` is `true`.
+
+### 1.1 Behavior
+
+1. Run `git fetch ${remote_name}` with retry logic (see Section 2 below).
+2. Record `lastFetchAt` in session state.
+3. Determine the current branch's tracking status using `get_branch_tracking_status()`.
+4. Emit systemMessage based on status.
+5. For `behind` status, attempt fast-forward auto-merge.
+
+### 1.2 `get_branch_tracking_status()` Function
+
+Location: `scripts/git-utils.sh`
+
+```bash
+get_branch_tracking_status() {
+  local branch="$1"
+  local remote_name="$2"
+  local remote_branch="${remote_name}/${branch}"
+
+  # Check if remote branch exists
+  if ! git rev-parse --verify "$remote_branch" >/dev/null 2>&1; then
+    echo "no-remote"
+    return
+  fi
+
+  local local_ref remote_ref base_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "$remote_branch" 2>/dev/null)
+  base_ref=$(git merge-base "$branch" "$remote_branch" 2>/dev/null || true)
+
+  if [[ "$local_ref" == "$remote_ref" ]]; then
+    echo "up-to-date"
+  elif [[ "$local_ref" == "$base_ref" ]]; then
+    local behind_count
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "behind:${behind_count}"
+  elif [[ "$remote_ref" == "$base_ref" ]]; then
+    local ahead_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    echo "ahead:${ahead_count}"
+  else
+    local ahead_count behind_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "diverged:${ahead_count}:${behind_count}"
+  fi
+}
+```
+
+**Return values**:
+
+| Return value | Meaning |
+|---|---|
+| `no-remote` | Remote tracking branch does not exist (new branch, not yet pushed) |
+| `up-to-date` | Local and remote refs are identical |
+| `behind:N` | Local branch is N commits behind the remote tracking branch |
+| `ahead:N` | Local branch is N commits ahead of the remote tracking branch |
+| `diverged:A:B` | Local is A commits ahead and B commits behind the remote (history has diverged) |
+
+### 1.3 systemMessages by Status
+
+| Status | Action | systemMessage |
+|---|---|---|
+| `up-to-date` | None | No message |
+| `behind:N` | Auto fast-forward | `"[git-pilot] Branch '${branch}' was ${N} commit(s) behind '${remote}/${branch}'. Fast-forwarded to latest."` |
+| `behind:N` (ff fails) | Warn | `"[git-pilot] Branch '${branch}' is ${N} commit(s) behind '${remote}/${branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is."` |
+| `ahead:N` | Inform | `"[git-pilot] Branch '${branch}' is ${N} commit(s) ahead of '${remote}/${branch}'. Unpushed changes."` |
+| `diverged:A:B` | Warn | `"[git-pilot] Branch '${branch}' has diverged from '${remote}/${branch}' (${A} local, ${B} remote). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue."` |
+| `no-remote` | Inform | No message (new branch, not yet pushed) |
+
+### 1.4 Fast-Forward Auto-Merge Logic
+
+When status is `behind:N` (local branch is behind remote with no local-only commits):
+
+```bash
+if git merge --ff-only "${remote_branch}" >/dev/null 2>&1; then
+  # Success -- emit fast-forward message
+else
+  # Cannot fast-forward -- emit warning with options
+fi
+```
+
+The fast-forward is attempted automatically. If it succeeds, the success systemMessage is emitted. If it fails (e.g., dirty working tree), the warning systemMessage with user options is emitted instead.
+
+### 1.5 Edge Cases
+
+- If `git.autoFetch` is `false`, skip fetch entirely. Still check local vs. tracking branch status if tracking info exists.
+- If no remote exists, skip all freshness checks.
+- If the branch has no tracking branch (new local branch), skip comparison.
+- If fetch fails after all retries, emit a warning and continue without freshness data (see Section 2).
+
+---
+
+## 2. Network Error Handling
+
+**Modified file**: `scripts/git-utils.sh`
+
+### 2.1 `fetch_with_retry()` Function
+
+```bash
+fetch_with_retry() {
+  local remote_name="$1"
+  local config="$2"
+  local specific_branch="${3:-}"
+
+  local max_retries
+  max_retries=$(get_config "$config" '.git.fetchRetries' '2')
+  local retry_delay
+  retry_delay=$(get_config "$config" '.git.fetchRetryDelaySec' '3')
+
+  local fetch_args="$remote_name"
+  if [[ -n "$specific_branch" ]]; then
+    fetch_args="$remote_name $specific_branch"
+  fi
+
+  local attempt=0
+  local last_error=""
+
+  while (( attempt <= max_retries )); do
+    if git fetch $fetch_args 2>/dev/null; then
+      return 0
+    fi
+
+    last_error=$(git fetch $fetch_args 2>&1 || true)
+    attempt=$((attempt + 1))
+
+    if (( attempt <= max_retries )); then
+      sleep "$retry_delay"
+    fi
+  done
+
+  # All retries exhausted
+  echo "$last_error" >&2
+  return 1
+}
+```
+
+### 2.2 Config Keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `git.autoFetch` | boolean | `true` | Run `git fetch` on session start |
+| `git.fetchRetries` | integer | `2` | Number of retry attempts on fetch failure |
+| `git.fetchRetryDelaySec` | integer | `3` | Seconds between fetch retries |
+
+### 2.3 Retry Behavior
+
+- The initial fetch attempt (attempt 0) plus up to `git.fetchRetries` retries are performed.
+- Retries are silent (no systemMessage emitted during retries).
+- `sleep "$retry_delay"` is called between attempts.
+- If a `specific_branch` is provided (third argument), only that branch is fetched. Otherwise all refs from the remote are fetched.
+- On success at any attempt, the function returns 0 immediately.
+- On total failure, `last_error` is written to stderr and the function returns 1.
+
+### 2.4 Network Error Messages
+
+| Event | systemMessage |
+|---|---|
+| Fetch failed, retrying | (no message -- retries are silent) |
+| All retries exhausted | `"[git-pilot] Warning: Could not fetch from '${remote}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync."` |
+| Push failed (network) | `"[git-pilot] Push to '${remote}/${branch}' failed. Check network connectivity and try again."` |
+
+### 2.5 Integration with Branch Freshness
+
+The `session-start.sh` script calls `fetch_with_retry()` before calling `get_branch_tracking_status()`. If `fetch_with_retry()` fails (returns 1), the session-start script emits the "all retries exhausted" warning and continues without freshness data. The `lastFetchAt` field in session state is only updated on a successful fetch.
+
+---
+
+## 3. Related Config Defaults
+
+For reference, the relevant subset of the default config (`defaults/config.json`):
+
+```jsonc
+{
+  "git": {
+    "defaultBranch": "main",
+    "autoFetch": true,
+    "fetchRetries": 2,
+    "fetchRetryDelaySec": 3
+  },
+  "remote": {
+    "defaultName": "origin"
+  }
+}
+```
+
+---
+
+## 4. Session State Fields Used
+
+| Field | Type | Description |
+|---|---|---|
+| `lastFetchAt` | string\|null | ISO timestamp of last successful `git fetch` in this session. Updated after `fetch_with_retry()` succeeds. |
+| `workingBranch` | string | Current branch name, used as the `branch` argument to `get_branch_tracking_status()`. |
+| `branchPurpose` | string | Human-readable purpose derived via `derive_branch_purpose()`. |
+
+---
+
+## 5. Core Utility Functions
+
+These v1 functions in `scripts/git-utils.sh` are used by all downstream modules and hook scripts. They are sourced (not invoked as subprocesses).
+
+```bash
+# git-utils.sh
+
+is_git_repo() {
+  git rev-parse --git-dir >/dev/null 2>&1
+}
+
+get_current_branch() {
+  git branch --show-current 2>/dev/null
+}
+
+has_uncommitted_changes() {
+  [[ -n "$(git status --porcelain 2>/dev/null)" ]]
+}
+
+get_default_branch() {
+  local config="$1"
+  echo "$config" | jq -r '.git.defaultBranch // "main"'
+}
+
+is_on_default_branch() {
+  local config="$1"
+  local current default_branch
+  current=$(get_current_branch)
+  default_branch=$(get_default_branch "$config")
+  [[ "$current" == "$default_branch" ]]
+}
+
+has_remote() {
+  [[ -n "$(git remote 2>/dev/null)" ]]
+}
+
+sanitize_branch_name() {
+  local name="$1"
+  echo "$name" | sed 's/[^a-zA-Z0-9._/-]//g'
+}
+```
+
+### 5.1 Function Reference
+
+| Function | Parameters | Returns | Used by |
+|----------|-----------|---------|---------|
+| `is_git_repo` | (none) | exit code 0/1 | `session-start.sh`, all hooks |
+| `get_current_branch` | (none) | branch name on stdout (empty if detached HEAD) | `session-start.sh`, `pre-commit.sh`, `post-bash.sh` |
+| `has_uncommitted_changes` | (none) | exit code 0 if dirty, 1 if clean | `session-start.sh`, `session-stop.sh`, `auto_stash()` |
+| `get_default_branch` | `config` (JSON string) | branch name on stdout | `session-start.sh`, `pre-commit.sh`, `is_on_default_branch()` |
+| `is_on_default_branch` | `config` (JSON string) | exit code 0/1 | `pre-commit.sh`, `session-start.sh` |
+| `has_remote` | (none) | exit code 0/1 | `session-start.sh`, `post-bash.sh`, `session-stop.sh` |
+| `sanitize_branch_name` | `name` (string) | sanitized name on stdout | branch creation flows |
+
+---
+
+## 6. Branch Purpose Derivation
+
+Location: `scripts/git-utils.sh` (TECHNICAL-SPEC SS4.4)
+
+Called by `session-start.sh` during state initialization to derive a human-readable purpose from the branch name. The result is stored in `branchPurpose` in session state and included in the SessionStart systemMessage so Claude has context for unrelated work detection.
+
+### 6.1 `derive_branch_purpose()` Function
+
+```bash
+# In git-utils.sh
+derive_branch_purpose() {
+  local branch_name="$1"
+
+  # Strip type prefix (e.g., "feat/", "fix/")
+  local description
+  description=$(echo "$branch_name" | sed 's|^[^/]*/||')
+
+  # Convert kebab-case/snake_case to words
+  description=$(echo "$description" | tr '-' ' ' | tr '_' ' ')
+
+  echo "$description"
+}
+```
+
+**Parameters**: `branch_name` (string, required) -- the full branch name (e.g., `feat/add-dark-mode`).
+
+**Returns**: space-separated description on stdout (e.g., `add dark mode`).
+
+### 6.2 Usage in `session-start.sh`
+
+```bash
+if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+  branch_purpose=$(derive_branch_purpose "$current_branch")
+  configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+  if [[ -n "$configured_base" ]]; then
+    base_branch="$configured_base"
+  fi
+fi
+init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
+```
+
+### 6.3 Examples
+
+| Branch name | `derive_branch_purpose` output |
+|-------------|-------------------------------|
+| `feat/add-dark-mode` | `add dark mode` |
+| `fix/login-timeout` | `login timeout` |
+| `refactor/extract_utils` | `extract utils` |
+| `main` | `main` (no prefix to strip) |
diff --git a/spec/03-rebase-and-conflicts.md b/spec/03-rebase-and-conflicts.md
new file mode 100644
index 0000000..67e05bf
--- /dev/null
+++ b/spec/03-rebase-and-conflicts.md
@@ -0,0 +1,374 @@
+# Module 03: Rebase and Conflict Resolution
+
+## Cross-references
+
+- **Depends on `01-config-and-state.md`** for:
+  - `get_config()` function signature used to read config values.
+  - Config schema: `rebase.autoRebaseBeforePush`, `rebase.conflictStrategy`, `rebase.allowForcePush`, `git.defaultBranch`.
+  - Session state schema: `baseBranch` field, `read_state()` / `update_state()`.
+  - Three-tier config merge: plugin defaults -> global (`~/.claude/git-pilot.json`) -> local (`.claude/git-pilot.json`).
+- **Depends on `02-git-utils-and-network.md`** for:
+  - `fetch_with_retry()` function, called by `get_base_branch_drift()` to fetch the latest base branch state before computing drift.
+  - Network error handling and retry behavior.
+
+---
+
+## Overview
+
+This module covers two features:
+
+1. **Base Branch Drift Detection** (TECHNICAL-SPEC SS4.2) -- determines whether the base branch (e.g., `main`) has new commits since the feature branch diverged, and initiates a rebase if needed.
+2. **Intelligent Rebase and Conflict Resolution** (TECHNICAL-SPEC SS4.3) -- executes rebases, detects and reports conflicts with structured detail, applies configurable conflict strategies, and handles force push requirements.
+
+**New library**: `scripts/rebase.sh`
+
+---
+
+## 1. Base Branch Drift Detection
+
+**Trigger**: Before push or MR creation. Called from `/finish` skill, `session-stop.sh`, and `post-bash.sh` (on push commands).
+
+**Preconditions**: On a feature branch (not default branch). Remote exists. `rebase.autoRebaseBeforePush` is `true`.
+
+### 1.1 `get_base_branch_drift()` Function
+
+Location: `scripts/git-utils.sh`
+
+```bash
+get_base_branch_drift() {
+  local current_branch="$1"
+  local base_branch="$2"
+  local remote_name="$3"
+  local remote_base="${remote_name}/${base_branch}"
+
+  # Fetch latest base branch state
+  git fetch "$remote_name" "$base_branch" 2>/dev/null || return 1
+
+  # Find the merge base between current branch and remote base
+  local merge_base
+  merge_base=$(git merge-base "$current_branch" "$remote_base" 2>/dev/null || true)
+
+  if [[ -z "$merge_base" ]]; then
+    echo "no-common-ancestor"
+    return
+  fi
+
+  # Count commits on base branch since the branch point
+  local drift_count
+  drift_count=$(git rev-list --count "${merge_base}..${remote_base}" 2>/dev/null)
+
+  if [[ "$drift_count" -eq 0 ]]; then
+    echo "no-drift"
+  else
+    echo "drifted:${drift_count}"
+  fi
+}
+```
+
+**Return values**:
+
+| Return value | Meaning |
+|---|---|
+| `no-drift` | Base branch has no new commits since this branch diverged |
+| `drifted:N` | Base branch has N new commits since the branch point |
+| `no-common-ancestor` | Cannot determine a merge base between the branches |
+
+### 1.2 Decision Flow
+
+1. If `no-drift`: proceed with push/MR.
+2. If `drifted:N`:
+   a. Emit: `"[git-pilot] Base branch '${base}' has ${N} new commit(s) since this branch diverged. Rebasing '${current}' onto '${remote}/${base}'..."`
+   b. Attempt rebase (see Section 2).
+   c. If rebase succeeds: emit `"[git-pilot] Rebase succeeded cleanly. Ready to push."` and continue.
+   d. If rebase has conflicts: handle per `rebase.conflictStrategy` (see Section 2.3).
+3. If `no-common-ancestor`: emit warning: `"[git-pilot] Cannot determine common ancestor between '${current}' and '${base}'. Skipping rebase. Push may require manual review."` Proceed with push.
+
+### 1.3 Base Branch Determination
+
+The base branch is determined in order:
+
+1. From session state `baseBranch` field (set when branch was created via `/branch` skill).
+2. From git tracking: `git config branch.${current}.merge` -> strip `refs/heads/`.
+3. Fall back to `git.defaultBranch` from config (default: `"main"`).
+
+---
+
+## 2. Intelligent Rebase and Conflict Resolution
+
+### 2.1 `attempt_rebase()` Function
+
+Location: `scripts/rebase.sh`
+
+```bash
+attempt_rebase() {
+  local target_branch="$1"  # Branch to rebase onto (e.g., origin/main)
+
+  # Ensure clean working tree
+  if has_uncommitted_changes; then
+    echo "error:dirty-worktree"
+    return 1
+  fi
+
+  # Attempt rebase
+  local rebase_output
+  if rebase_output=$(git rebase "$target_branch" 2>&1); then
+    echo "success"
+    return 0
+  else
+    # Check if it's a conflict
+    if git diff --name-only --diff-filter=U 2>/dev/null | head -1 | grep -q .; then
+      echo "conflict"
+      return 1
+    else
+      echo "error:${rebase_output}"
+      return 1
+    fi
+  fi
+}
+```
+
+**Return values**:
+
+| Return value | Exit code | Meaning |
+|---|---|---|
+| `success` | 0 | Rebase completed cleanly |
+| `conflict` | 1 | Rebase stopped due to merge conflicts |
+| `error:dirty-worktree` | 1 | Working tree has uncommitted changes, cannot rebase |
+| `error:${rebase_output}` | 1 | Rebase failed for another reason (output included) |
+
+### 2.2 `get_conflict_details()` Function
+
+Location: `scripts/rebase.sh`
+
+Returns a JSON array describing each conflicting file.
+
+```bash
+get_conflict_details() {
+  local conflict_files
+  conflict_files=$(git diff --name-only --diff-filter=U 2>/dev/null)
+
+  if [[ -z "$conflict_files" ]]; then
+    echo "[]"
+    return
+  fi
+
+  local result="["
+  local first=true
+
+  while IFS= read -r file; do
+    # Determine conflict type by examining the conflict markers
+    local ours_only=false
+    local theirs_only=false
+    local both_modified=false
+
+    # Check if the file exists in both sides
+    local ours_exists theirs_exists
+    ours_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 2" | wc -l | tr -d ' ')
+    theirs_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 3" | wc -l | tr -d ' ')
+
+    local conflict_type="both-modified"
+    if [[ "$ours_exists" == "0" ]]; then
+      conflict_type="deleted-by-us"
+    elif [[ "$theirs_exists" == "0" ]]; then
+      conflict_type="deleted-by-them"
+    fi
+
+    # Get conflict marker count as complexity indicator
+    local marker_count=0
+    if [[ -f "$file" ]]; then
+      marker_count=$(grep -c '^<<<<<<< ' "$file" 2>/dev/null || echo "0")
+    fi
+
+    if [[ "$first" == "true" ]]; then
+      first=false
+    else
+      result+=","
+    fi
+    result+=$(jq -n \
+      --arg f "$file" \
+      --arg t "$conflict_type" \
+      --argjson m "$marker_count" \
+      '{file: $f, type: $t, conflictRegions: $m}')
+  done <<< "$conflict_files"
+
+  result+="]"
+  echo "$result"
+}
+```
+
+**JSON output format**:
+
+```json
+[
+  {
+    "file": "src/auth.ts",
+    "type": "both-modified",
+    "conflictRegions": 2
+  },
+  {
+    "file": "src/utils.ts",
+    "type": "deleted-by-us",
+    "conflictRegions": 0
+  }
+]
+```
+
+**Field definitions**:
+
+| Field | Type | Description |
+|---|---|---|
+| `file` | string | Relative file path of the conflicting file |
+| `type` | string | One of: `both-modified`, `deleted-by-us`, `deleted-by-them` |
+| `conflictRegions` | integer | Count of `<<<<<<< ` markers in the file (0 for delete conflicts) |
+
+**Conflict type detection logic**:
+
+- Stage 2 in `git ls-files --stage` = "ours" (current branch). Stage 3 = "theirs" (incoming branch).
+- If stage 2 entry count is 0: `deleted-by-us`.
+- If stage 3 entry count is 0: `deleted-by-them`.
+- Otherwise: `both-modified`.
+
+### 2.3 Conflict Resolution Messages
+
+When conflicts are detected, the hook emits a systemMessage with structured conflict information:
+
+```
+[git-pilot] Rebase conflict in ${count} file(s):
+
+${for each conflict}
+- `${file}` (${type}, ${regions} conflict region(s))
+  Recommendation: ${recommendation}
+${end for}
+
+Prompt the user with these options:
+1. Resolve conflicts manually (edit the conflicting files, then run `git add <file>` and `git rebase --continue`)
+2. Accept all changes from the base branch (`git checkout --theirs <file>` for each file)
+3. Keep all local changes (`git checkout --ours <file>` for each file)
+4. Abort the rebase (`git rebase --abort`) and push without rebasing
+5. Abort the rebase and use merge instead (`git merge ${base_branch}`)
+```
+
+### 2.4 Conflict Recommendation Heuristics
+
+| Conflict type | Condition | Recommendation |
+|---|---|---|
+| `deleted-by-us` | -- | `"File was deleted locally but modified on base. If the deletion was intentional, accept ours (delete). Otherwise, accept theirs."` |
+| `deleted-by-them` | -- | `"File was deleted on base but modified locally. If your changes are still needed, accept ours. Otherwise, accept theirs (delete)."` |
+| `both-modified` | 1 region | `"Single conflict region -- likely a small overlap. Manual review recommended."` |
+| `both-modified` | >3 regions | `"Multiple conflict regions -- significant concurrent changes. Manual review required."` |
+
+### 2.5 `rebase.conflictStrategy` Handling
+
+Config key: `rebase.conflictStrategy` (default: `"prompt"`)
+
+| Strategy | Behavior |
+|---|---|
+| `"prompt"` | Emit conflict details and prompt user for resolution choice (default) |
+| `"abort"` | Immediately abort rebase: `git rebase --abort`. Emit: `"[git-pilot] Rebase aborted due to conflicts. Push without rebase."` |
+| `"merge-fallback"` | Abort rebase, attempt merge instead: `git rebase --abort && git merge ${target}`. If merge also conflicts, fall back to `"prompt"` behavior |
+
+---
+
+## 3. Force Push Handling
+
+### 3.1 `needs_force_push()` Function
+
+Location: `scripts/rebase.sh`
+
+After a successful rebase that rewrites history (branch was previously pushed), a force push is needed.
+
+```bash
+needs_force_push() {
+  local branch="$1"
+  local remote_name="$2"
+
+  # Check if remote tracking branch exists
+  if ! git rev-parse --verify "${remote_name}/${branch}" >/dev/null 2>&1; then
+    return 1  # No remote branch, normal push works
+  fi
+
+  # Check if local and remote have diverged after rebase
+  local local_ref remote_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "${remote_name}/${branch}" 2>/dev/null)
+
+  if [[ "$local_ref" != "$remote_ref" ]]; then
+    # Check if remote is NOT an ancestor of local (diverged, not just ahead)
+    if ! git merge-base --is-ancestor "$remote_ref" "$local_ref" 2>/dev/null; then
+      return 0  # Needs force push
+    fi
+  fi
+
+  return 1
+}
+```
+
+**Logic**: Returns 0 (true / needs force push) when:
+1. The remote tracking branch exists, AND
+2. Local and remote refs differ, AND
+3. The remote ref is NOT an ancestor of the local ref (i.e., history has diverged, not just new commits ahead).
+
+Returns 1 (false / normal push is fine) otherwise.
+
+### 3.2 `rebase.allowForcePush` Handling
+
+Config key: `rebase.allowForcePush` (default: `"ask"`)
+
+| Setting | Behavior |
+|---|---|
+| `"ask"` | Emit: `"[git-pilot] Rebase rewrote history. Force push required. Prompt the user: force push (git push --force-with-lease) or abort."` |
+| `"never"` | Emit: `"[git-pilot] Rebase rewrote history but force push is disabled. The rebase changes are local only. Push manually if needed."` |
+| `"always"` | Use `git push --force-with-lease` automatically. Emit: `"[git-pilot] Force-pushed '${branch}' to '${remote}/${branch}' after rebase."` |
+
+Always use `--force-with-lease` (never bare `--force`) for safety.
+
+---
+
+## 4. Push Rejection Detection and Messages
+
+Location: `post-bash.sh`
+
+When `post-bash.sh` detects a failed `git push` (exit code non-zero, stderr contains "rejected" or "failed to push"):
+
+```
+[git-pilot] Push rejected -- remote '${remote}/${branch}' has new commits.
+Prompt the user:
+1. Pull and rebase, then retry push (`git pull --rebase && git push`)
+2. Force push with lease (`git push --force-with-lease`) -- overwrites remote changes
+3. Pull and merge (`git pull`) -- creates a merge commit
+4. Cancel
+```
+
+---
+
+## 5. Related Config Defaults
+
+For reference, the relevant subset of the default config (`defaults/config.json`):
+
+```jsonc
+{
+  "git": {
+    "defaultBranch": "main"
+  },
+  "rebase": {
+    "autoRebaseBeforePush": true,
+    "conflictStrategy": "prompt",
+    "allowForcePush": "ask"
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `rebase.autoRebaseBeforePush` | boolean | `true` | Rebase onto base branch before push/MR |
+| `rebase.conflictStrategy` | string | `"prompt"` | `"prompt"` / `"abort"` / `"merge-fallback"` |
+| `rebase.allowForcePush` | string | `"ask"` | `"ask"` / `"never"` / `"always"` |
+
+---
+
+## 6. Session State Fields Used
+
+| Field | Type | Description |
+|---|---|---|
+| `baseBranch` | string | The branch this feature branch targets for MR / was created from. Used as the `base_branch` argument to `get_base_branch_drift()`. |
+| `workingBranch` | string | Current branch name, used as the `current_branch` argument to `get_base_branch_drift()`. |
diff --git a/spec/04-agent-and-worktree.md b/spec/04-agent-and-worktree.md
new file mode 100644
index 0000000..2b0e88a
--- /dev/null
+++ b/spec/04-agent-and-worktree.md
@@ -0,0 +1,382 @@
+# Module 04: Agent Teams Detection & Git Worktree Management
+
+## Cross-References
+
+- **Depends on `01-config-and-state.md`**: for config schema (three-tier merge via `load_config()`, `get_config()` accessor), session state schema (`/tmp/git-pilot-${SESSION_ID}.json`), and state read/write functions (`get_state_file()`, `read_state()`, `update_state()`, `write_state()` with atomic temp-file + `mv`).
+- **Depends on `02-git-utils-and-network.md`**: for `get_current_branch()`, `has_remote()`, `is_git_repo()`, and `get_default_branch()` utility functions in `scripts/git-utils.sh`.
+- **Referenced by `05-stash-and-robustness.md`**: stash auto-restore checks agent context before emitting prompts.
+
+---
+
+## 1. Agent Teams Detection (spec section 4.5)
+
+**New file**: `scripts/agent.sh`
+
+### 1.1 Agent Detection
+
+```bash
+# In agent.sh
+is_agent_context() {
+  # Primary: check Claude Code spawned-by indicator
+  if [[ -n "${CLAUDE_SPAWNED_BY:-}" ]]; then
+    return 0
+  fi
+
+  # Secondary: check for agent role in session state
+  local session_id="${1:-}"
+  if [[ -n "$session_id" ]]; then
+    local state_file
+    state_file=$(get_state_file "$session_id")
+    local state
+    state=$(read_state "$state_file")
+    local is_agent
+    is_agent=$(echo "$state" | jq -r '.isAgent // false')
+    if [[ "$is_agent" == "true" ]]; then
+      return 0
+    fi
+  fi
+
+  return 1
+}
+```
+
+Detection order: (1) `CLAUDE_SPAWNED_BY` env var non-empty (primary, set by Claude Code), (2) session state `.isAgent == true` (fallback). The env var name is Claude Code-dependent; the state-file fallback provides resilience.
+
+### 1.2 Operation Restriction Check
+
+```bash
+is_operation_agent_restricted() {
+  local config="$1"
+  local operation="$2"  # "push", "mr", "branch-prompt", etc.
+
+  local suppress
+  suppress=$(get_config "$config" '.agentTeams.suppressPromptsForAgents' 'true')
+
+  if [[ "$suppress" != "true" ]]; then
+    return 1  # Not suppressed
+  fi
+
+  # Check if this specific operation is orchestrator-only
+  local restricted
+  restricted=$(echo "$config" | jq -r --arg op "$operation" \
+    '.agentTeams.orchestratorOnly // ["push", "mr"] | map(select(. == $op)) | length')
+
+  if [[ "$restricted" -gt 0 ]]; then
+    return 0  # Restricted to orchestrator
+  fi
+
+  return 1
+}
+```
+
+### 1.3 Config and State
+
+Config keys (`defaults/config.json`):
+
+```jsonc
+{
+  "agentTeams": {
+    "suppressPromptsForAgents": true,
+    "orchestratorOnly": ["push", "mr"]
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `agentTeams.suppressPromptsForAgents` | boolean | `true` | Suppress interactive prompts for spawned agents |
+| `agentTeams.orchestratorOnly` | array | `["push", "mr"]` | Operations restricted to orchestrator agent |
+
+Session state fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isAgent` | boolean | Whether this session is a spawned agent (not orchestrator) |
+| `agentRole` | string\|null | `"orchestrator"`, `"implementer"`, `"validator"`, or null |
+| `activeWorktrees` | array | List of `{path, branch, createdAt}` objects for worktrees created in this session |
+
+### 1.4 Prompt Suppression
+
+All hook scripts that emit interactive systemMessages must check agent context first:
+
+```bash
+if is_agent_context "$SESSION_ID" && \
+   is_operation_agent_restricted "$CONFIG" "push"; then
+  echo '{"continue": true}'
+  exit 0
+fi
+```
+
+**Hook-specific suppression**:
+
+- **`post-bash.sh`**: Source `agent.sh`. After loading config, check `is_agent_context` + `is_operation_agent_restricted "$config" "push"`. If restricted, emit `{"continue": true}` and exit.
+- **`post-write.sh`**: Source `agent.sh`. If `is_agent_context`, still track file changes but skip the auto-commit suggestion threshold message (`exit 0` after tracking).
+- **`prompt-context.sh`**: If `is_agent_context`, emit `{"continue": true}` and exit (skip unrelated work detection).
+
+### 1.5 Agent Suppression in `session-start.sh` and `session-stop.sh`
+
+**`session-start.sh` — Branch Freshness**: Agents still fetch and fast-forward but log freshness to state only (no systemMessage prompt):
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+if is_agent_context "$SESSION_ID"; then
+  # Log to state, not messages array
+  update_state "$(get_state_file "$SESSION_ID")" --arg status "$tracking_status" '.freshnessStatus = $status'
+  # Still fast-forward if behind
+  case "$tracking_status" in
+    behind:*) git merge --ff-only "${remote_name}/${current_branch}" >/dev/null 2>&1 || true ;;
+  esac
+else
+  # Normal interactive flow: add to messages array
+  ...
+fi
+```
+
+**`session-stop.sh` — Rebase/Summary**: Agents skip session summary and abort rebase silently on conflict:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+if is_agent_context "$SESSION_ID"; then
+  # Attempt rebase but abort silently on conflict (no prompt)
+  if [[ "$auto_rebase" == "true" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    source "$SCRIPT_DIR/rebase.sh"
+    drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name")
+    case "$drift_status" in
+      drifted:*)
+        rebase_result=$(attempt_rebase "${remote_name}/${default_branch}")
+        [[ "$rebase_result" == "conflict" ]] && git rebase --abort 2>/dev/null || true ;;
+    esac
+  fi
+  echo '{"continue": true}'; exit 0
+fi
+```
+
+### 1.6 Operations and Agent Behavior Table
+
+| Operation | Orchestrator | Agent |
+|-----------|-------------|-------|
+| Branch creation prompt | Interactive | Suppressed |
+| Push prompt after commit | Interactive | Suppressed |
+| MR creation | Interactive | Suppressed |
+| Commit validation | Active | Active (agents must also follow commit rules) |
+| Auto-commit suggestions | Active | Suppressed |
+| Rebase/conflict prompts | Interactive | Suppressed (abort rebase silently) |
+| Session summary | Active | Suppressed |
+| Branch freshness warnings | Active | Log to state only (no prompt) |
+
+### 1.7 CLAUDE.md Behavioral Rule (Rule 10)
+
+```markdown
+## Rule 10: Agent Teams
+
+When operating as a spawned agent (not the orchestrator):
+
+1. Do not prompt for push, MR creation, or branch switching. These are
+   orchestrator-only operations.
+2. Follow commit rules normally — agents must still use proper commit format.
+3. Do not run auto-commit suggestions. Commit when instructed by the orchestrator.
+4. If instructed to work in a specific worktree directory, stay in that directory.
+```
+
+### 1.8 Test Scenarios
+
+- `CLAUDE_SPAWNED_BY` set -> prompts suppressed.
+- State file `isAgent: true` -> prompts suppressed.
+- Neither set -> normal interactive behavior.
+- Commit validation still active for agents.
+- Agent session-start: freshness logged to state, no systemMessage emitted.
+- Agent session-stop: rebase conflict silently aborted, no summary emitted.
+
+---
+
+## 2. Git Worktree Management (spec section 4.6)
+
+**New file**: `scripts/worktree.sh`
+
+### 2.1 Config Keys
+
+```jsonc
+{
+  "worktree": {
+    "enabled": true,
+    "basePath": "../{{project}}-worktrees",
+    "cleanupOnMerge": true
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `worktree.enabled` | boolean | `true` | Enable worktree management for Agent Teams |
+| `worktree.basePath` | string | `"../{{project}}-worktrees"` | Worktree directory pattern |
+| `worktree.cleanupOnMerge` | boolean | `true` | Remove worktree after successful merge |
+
+### 2.2 Worktree Creation
+
+The `{{project}}` placeholder in `basePath` is replaced with the project directory name (basename of `git rev-parse --show-toplevel`). Branch names are sanitized for directory paths by replacing `/` with `-`.
+
+```bash
+create_worktree() {
+  local config="$1"
+  local branch_name="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local project_name
+  project_name=$(basename "$(git rev-parse --show-toplevel)")
+
+  local base_path
+  base_path=$(get_config "$config" '.worktree.basePath' "../{{project}}-worktrees")
+  base_path="${base_path//\{\{project\}\}/$project_name}"
+
+  local dir_name
+  dir_name=$(echo "$branch_name" | tr '/' '-')
+  local worktree_path="${base_path}/${dir_name}"
+
+  mkdir -p "$(dirname "$worktree_path")"
+
+  local output
+  if output=$(git worktree add "$worktree_path" -b "$branch_name" "$base_branch" 2>&1); then
+    register_worktree "$worktree_path" "$branch_name" "$base_branch" "$session_id"
+    echo "$worktree_path"
+    return 0
+  else
+    echo "error:${output}" >&2
+    return 1
+  fi
+}
+```
+
+Error message on failure: `"[git-pilot] Worktree creation failed: branch 'feat/auth' already exists. Use a different name or delete the existing branch."`
+
+### 2.3 Worktree Removal
+
+```bash
+remove_worktree() {
+  local worktree_path="$1"
+  local force="${2:-false}"
+
+  local flags=""
+  if [[ "$force" == "true" ]]; then
+    flags="--force"
+  fi
+
+  if git worktree remove "$worktree_path" $flags 2>/dev/null; then
+    unregister_worktree "$worktree_path"
+    return 0
+  else
+    return 1
+  fi
+}
+```
+
+### 2.4 Worktree Registry
+
+Registry file: `$(git rev-parse --git-dir)/git-pilot-worktrees.json` (persists across sessions). Uses `git rev-parse --git-dir` instead of hardcoded `.git` for correctness in worktree contexts where `.git` is a file.
+
+Schema: `{"worktrees": [{path, branch, baseBranch, createdAt, createdBy, status}]}` (see spec section 3.3 for full example).
+
+```bash
+WORKTREE_REGISTRY="$(git rev-parse --git-dir)/git-pilot-worktrees.json"
+
+register_worktree() {
+  local path="$1"
+  local branch="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local registry
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    registry=$(cat "$WORKTREE_REGISTRY")
+  else
+    registry='{"worktrees":[]}'
+  fi
+
+  local entry
+  entry=$(jq -n \
+    --arg p "$path" \
+    --arg b "$branch" \
+    --arg bb "$base_branch" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg sid "$session_id" \
+    '{path:$p, branch:$b, baseBranch:$bb, createdAt:$ts, createdBy:$sid, status:"active"}')
+
+  registry=$(echo "$registry" | jq --argjson e "$entry" '.worktrees += [$e]')
+
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+unregister_worktree() {
+  local path="$1"
+  if [[ ! -f "$WORKTREE_REGISTRY" ]]; then
+    return
+  fi
+  local registry
+  registry=$(cat "$WORKTREE_REGISTRY")
+  registry=$(echo "$registry" | jq --arg p "$path" \
+    '.worktrees = [.worktrees[] | select(.path != $p)]')
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+list_worktrees() {
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    cat "$WORKTREE_REGISTRY"
+  else
+    echo '{"worktrees":[]}'
+  fi
+}
+```
+
+All registry writes use atomic temp-file + `mv` pattern (same as state writes).
+
+### 2.5 Worktree Merge Back
+
+```bash
+merge_worktree_branch() {
+  local worktree_path="$1"
+  local target_branch="$2"
+  local config="$3"
+
+  local wt_branch
+  wt_branch=$(git -C "$worktree_path" branch --show-current 2>/dev/null)
+
+  if [[ -z "$wt_branch" ]]; then
+    echo "error:cannot-determine-branch"
+    return 1
+  fi
+
+  git checkout "$target_branch" 2>/dev/null || return 1
+
+  local merge_output
+  if merge_output=$(git merge "$wt_branch" --no-edit 2>&1); then
+    echo "success"
+    local cleanup
+    cleanup=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+    if [[ "$cleanup" == "true" ]]; then
+      remove_worktree "$worktree_path" "false"
+      git branch -d "$wt_branch" 2>/dev/null || true
+    fi
+    return 0
+  else
+    echo "conflict"
+    return 1
+  fi
+}
+```
+
+### 2.6 Worktree Cleanup in `session-stop.sh`
+
+After MR/push, before state cleanup. Iterates active worktrees; removes those whose branch is merged into the default branch, unregisters stale entries where the directory no longer exists, and reports remaining active worktrees. See spec section 5.1.4 for full code.
+
+### 2.7 Invariants and Dependencies
+
+A half-created worktree MUST be cleaned up. Every function that starts a multi-step git operation must have cleanup logic in its error path. Required: `git` >= 2.30, `jq` >= 1.6.
+
+### 2.8 Test Scenarios
+
+- Worktree created -> registered in registry.
+- Worktree removed -> unregistered from registry.
+- Worktree merge -> branch merged, worktree cleaned up.
+- Worktree directory already exists -> error reported.
diff --git a/spec/05-stash-and-robustness.md b/spec/05-stash-and-robustness.md
new file mode 100644
index 0000000..36cd934
--- /dev/null
+++ b/spec/05-stash-and-robustness.md
@@ -0,0 +1,387 @@
+# Module 05: Stash Management, Detached HEAD Recovery & Protected Branch Enhancement
+
+## Cross-References
+
+- **Depends on `01-config-and-state.md`**: for config schema (three-tier merge via `load_config()`, `get_config()` accessor), session state schema (`/tmp/git-pilot-${SESSION_ID}.json`), and state read/write functions (`get_state_file()`, `read_state()`, `update_state()`, `write_state()` with atomic temp-file + `mv`).
+- **Depends on `02-git-utils-and-network.md`**: for `get_current_branch()`, `has_uncommitted_changes()`, `is_on_default_branch()`, `get_default_branch()`, and `is_git_repo()` utility functions in `scripts/git-utils.sh`.
+- **Depends on `04-agent-and-worktree.md`**: the auto-stash prompt suppression in agent context uses `is_agent_context()` from `scripts/agent.sh`.
+
+---
+
+## 1. Stash Management (spec section 4.7)
+
+### 1.1 Modified Library File
+
+**Modified file**: `scripts/git-utils.sh`
+
+### 1.2 Config and State
+
+Config: `branch.autoStashOnSwitch` (boolean, default `true`) -- auto-stash uncommitted changes on branch switch.
+
+State: `stashRefs` (array of `{ref, branch, message, createdAt}`) -- tracks stashes created by git-pilot. Example entry: `{"ref":"stash@{0}", "branch":"feat/add-dark-mode", "message":"git-pilot auto-stash on feat/add-dark-mode", "createdAt":"2026-02-24T20:00:00Z"}`.
+
+### 1.3 Auto-stash on Branch Switch
+
+Triggered when `branch.autoStashOnSwitch` is `true` and a branch switch is detected in `pre-commit.sh`.
+
+```bash
+# In git-utils.sh
+auto_stash() {
+  local current_branch="$1"
+  local session_id="$2"
+
+  if ! has_uncommitted_changes; then
+    return 1  # Nothing to stash
+  fi
+
+  local stash_msg="git-pilot auto-stash on ${current_branch}"
+  if git stash push -m "$stash_msg" >/dev/null 2>&1; then
+    local stash_ref
+    stash_ref=$(git stash list --format='%gd' | head -1)
+
+    # Record in session state
+    if [[ -n "$session_id" ]]; then
+      local state_file
+      state_file=$(get_state_file "$session_id")
+      update_state "$state_file" \
+        --arg ref "$stash_ref" \
+        --arg branch "$current_branch" \
+        --arg msg "$stash_msg" \
+        '.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]'
+    fi
+
+    return 0
+  fi
+
+  return 1
+}
+```
+
+Stash message format: `"git-pilot auto-stash on ${current_branch}"`. The ref is captured from `git stash list --format='%gd' | head -1` immediately after push and recorded in session state.
+
+### 1.5 Auto-restore on Branch Switch
+
+When switching back to a branch that had changes stashed:
+
+```bash
+auto_restore_stash() {
+  local target_branch="$1"
+  local session_id="$2"
+
+  if [[ -z "$session_id" ]]; then
+    return 1
+  fi
+
+  local state_file
+  state_file=$(get_state_file "$session_id")
+  local state
+  state=$(read_state "$state_file")
+
+  # Find stash for this branch
+  local stash_ref
+  stash_ref=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .ref' | head -1)
+
+  if [[ -z "$stash_ref" ]] || [[ "$stash_ref" == "null" ]]; then
+    return 1  # No stash for this branch
+  fi
+
+  # Find the stash index by message
+  local stash_msg
+  stash_msg=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .message' | head -1)
+
+  local stash_index
+  stash_index=$(git stash list --format='%gd %s' | grep "$stash_msg" | head -1 | cut -d' ' -f1)
+
+  if [[ -n "$stash_index" ]]; then
+    if git stash pop "$stash_index" >/dev/null 2>&1; then
+      # Remove from state
+      update_state "$state_file" \
+        --arg branch "$target_branch" \
+        '.stashRefs = [.stashRefs[] | select(.branch != $branch)]'
+      return 0
+    fi
+  fi
+
+  return 1
+}
+```
+
+Lookup uses jq to find the stash ref/message by branch, then `git stash list` grep to find the current index. On successful pop, the entry is removed from state. Known limitation: stash-by-message lookup is fragile if the user manually creates stashes with a similar `"git-pilot auto-stash on "` prefix.
+
+### 1.6 Stash Messages
+
+| Event | Message |
+|-------|---------|
+| Auto-stash on switch | `"[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."` |
+| Auto-restore on return | `"[git-pilot] Restored stashed changes on '${branch}'."` |
+| Restore failed (conflicts) | `"[git-pilot] Could not auto-restore stash on '${branch}' — conflicts detected. Run 'git stash pop' manually to resolve."` |
+
+### 1.7 Branch Switch Detection in `pre-commit.sh`
+
+The auto-stash is triggered from `pre-commit.sh` when a branch switch command is detected:
+
+```bash
+# In the branch creation detection section, add branch switch detection:
+is_branch_switch_command() {
+  local cmd="$1"
+  SWITCH_TARGET=""
+
+  # git checkout <branch> (not -b)
+  if [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+-[bB] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  # git switch <branch> (not -c)
+  if [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+-[cC] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  return 1
+}
+
+# Before existing commit detection:
+SWITCH_TARGET=""
+if is_branch_switch_command "$COMMAND"; then
+  auto_stash=$(get_config "$CONFIG" '.branch.autoStashOnSwitch' 'true')
+  if [[ "$auto_stash" == "true" ]] && has_uncommitted_changes; then
+    current_br=$(get_current_branch)
+    if auto_stash "$current_br" "$SESSION_ID"; then
+      output_allow_with_message "[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."
+    fi
+  fi
+fi
+```
+
+Known limitation: `git checkout <branch>` vs. `git checkout <file>` is ambiguous; the regex checks for absence of `-b` but paths without `--` may be misdetected.
+
+### 1.8 CLAUDE.md Behavioral Rule (Rule 8)
+
+```markdown
+## Rule 8: Branch switching
+
+When switching branches (via /branch, user request, or unrelated work detection):
+
+1. If there are uncommitted changes and `branch.autoStashOnSwitch` is `true`, stash
+   them automatically before switching. Inform the user: "Stashed changes on '<branch>'."
+2. After switching, check if there's a git-pilot stash for the target branch and
+   restore it automatically.
+3. If stash restoration fails (conflicts), inform the user and suggest manual resolution.
+```
+
+### 1.9 Invariant: Never Lose Stash Data
+
+Stash operations that fail MUST NOT lose data. Use `stash apply` before `stash drop` in manual workflows. The `auto_restore_stash` function uses `git stash pop` which applies and drops atomically; if the apply fails (conflicts), the stash is preserved.
+
+### 1.10 Test Scenarios
+
+- Auto-stash on branch switch -> changes stashed, message emitted.
+- Auto-restore on return -> stash popped, message emitted.
+- Restore fails -> warning with manual instructions.
+
+---
+
+## 2. Detached HEAD Recovery (spec section 4.8)
+
+### 2.1 Trigger
+
+`session-start.sh`, when `get_current_branch` returns empty (no current branch).
+
+### 2.2 Detection and Recovery Logic
+
+```bash
+# In session-start.sh
+current_branch=$(get_current_branch)
+
+if [[ -z "$current_branch" ]]; then
+  # Detached HEAD
+  local head_sha
+  head_sha=$(git rev-parse --short HEAD 2>/dev/null)
+
+  # Try to find what branch we were on
+  local prev_branch
+  prev_branch=$(git reflog show --format='%gs' | grep -m1 'checkout: moving from' | \
+    sed 's/checkout: moving from \([^ ]*\) to .*/\1/')
+
+  if [[ -n "$prev_branch" ]]; then
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Previous branch was '${prev_branch}'. Prompt the user: return to '${prev_branch}', create a new branch from HEAD, or continue in detached state.")
+  else
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Prompt the user: create a new branch from HEAD or continue in detached state.")
+  fi
+fi
+```
+
+Previous branch lookup uses reflog. If found: three options (return, new branch, continue detached). If not found: two options (new branch, continue detached).
+
+---
+
+## 3. Protected Branch Enhancement (spec section 4.9)
+
+### 3.1 Modified File
+
+**Modified file**: `scripts/pre-commit.sh`
+
+### 3.2 Relevant Config Key
+
+From `defaults/config.json`:
+
+```jsonc
+{
+  "git": {
+    "protectDefaultBranch": "warn"
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `git.protectDefaultBranch` | string | `"warn"` | `"warn"` / `"block"` / `"off"` -- was boolean in v1 |
+
+### 3.3 Backward Compatibility: Boolean to String Migration
+
+v1 used a boolean for `git.protectDefaultBranch`. v2 uses a string enum. The config loading code must handle both:
+
+```bash
+# In config.sh or git-utils.sh
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
+```
+
+This function MUST be called wherever `git.protectDefaultBranch` is read, to handle the boolean-to-string migration.
+
+### 3.4 Enforcement in `pre-commit.sh`
+
+v1 only warns when committing to the default branch. v2 adds `"block"` mode:
+
+```bash
+protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$protect_mode")
+
+if is_on_default_branch "$CONFIG" 2>/dev/null; then
+  default_br=$(get_default_branch "$CONFIG")
+
+  case "$protect_mode" in
+    warn)
+      # v1 behavior — allow with warning
+      SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+      ;;
+    block)
+      # v2 — prevent the commit
+      output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+      ;;
+    off)
+      # No protection
+      ;;
+  esac
+fi
+```
+
+### 3.5 Mode Behavior and Backward Compatibility
+
+| Mode | Behavior |
+|------|----------|
+| `"warn"` | Allow with warning (v1 behavior) |
+| `"block"` | Prevent commit via `output_block` |
+| `"off"` | No protection |
+
+Backward compatibility: `true` -> `"warn"`, `false` -> `"off"`, unknown -> `"warn"`.
+
+### 3.6 Test Scenarios
+
+- `"warn"` mode -> warning emitted, commit allowed.
+- `"block"` mode -> commit blocked with `output_block`.
+- `"off"` mode -> no message.
+- Boolean `true` -> treated as `"warn"`.
+- Boolean `false` -> treated as `"off"`.
+
+---
+
+## 4. Hook Output Helper Functions
+
+Defined in `scripts/pre-commit.sh` (v1), these functions standardize how hooks communicate decisions back to Claude Code. All emit JSON to stdout and call `exit`.
+
+### 4.1 Allow Helpers
+
+```bash
+output_allow() {
+  cat <<'JSON'
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}
+JSON
+  exit 0
+}
+
+output_allow_with_message() {
+  local msg="$1"
+  jq -n --arg msg "$msg" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow"},systemMessage:$msg}'
+  exit 0
+}
+
+output_allow_with_updated_input() {
+  local new_command="$1"
+  jq -n --arg cmd "$new_command" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput:{command:$cmd}}}'
+  exit 0
+}
+
+output_allow_with_message_and_updated_input() {
+  local msg="$1"; local new_command="$2"
+  jq -n --arg msg "$msg" --arg cmd "$new_command" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput:{command:$cmd}},systemMessage:$msg}'
+  exit 0
+}
+```
+
+### 4.2 `output_block()`
+
+Rejects the tool invocation. The command is not executed. Writes the error to stderr and exits with code 2.
+
+```bash
+output_block() {
+  local error_msg="$1"
+  echo "$error_msg" >&2
+  exit 2
+}
+```
+
+**Usage across modules**: `output_block` -- protected branch `"block"` mode, commit validation failures. `output_allow_with_message` -- stash auto-save, branch warnings, freshness alerts. `output_allow_with_updated_input` -- signature stripping to rewrite commit commands.
+
+---
+
+## 5. Error Handling Invariants (applies to all sections)
+
+### 5.1 Never Leave Broken State
+
+- Stash operations that fail MUST NOT lose data (use `stash apply` before `stash drop` in manual flows; `stash pop` preserves stash on conflict).
+- An in-progress rebase MUST be aborted: `git rebase --abort`.
+- An in-progress merge MUST be aborted: `git merge --abort`.
+
+### 5.2 User-Facing Error Message Pattern
+
+All error messages follow: `[git-pilot] <context>: <specific error>. <suggestion>.`
+
+Examples:
+- `"[git-pilot] Rebase failed: could not apply commit abc1234. Conflicts in 2 file(s). Resolve conflicts or run 'git rebase --abort' to cancel."`
+- `"[git-pilot] Stash restore failed: conflicts in src/main.rs. Run 'git stash pop' manually to resolve."`
+
+### 5.3 Config Parse Failure
+
+Fall back to defaults. Emit: `"[git-pilot] Warning: Could not parse config file. Using defaults."`
+
+### 5.4 State File Failure
+
+Emit warning. Disable state-dependent features for this session (including stash tracking). Do not crash.
diff --git a/spec/06-hooks-and-lifecycle.md b/spec/06-hooks-and-lifecycle.md
new file mode 100644
index 0000000..143f4f4
--- /dev/null
+++ b/spec/06-hooks-and-lifecycle.md
@@ -0,0 +1,400 @@
+# 06 — Hooks and Lifecycle
+
+## Cross-References
+
+- **`01-config-and-state.md`** — `load_config`, `get_config`, `get_state_file`, `read_state`, `write_state`, `update_state`, `init_state`; state fields `baseBranch`, `branchPurpose`, `lastFetchAt`, `isAgent`, `agentRole`, `activeWorktrees`, `stashRefs`.
+- **`02-git-utils-and-network.md`** — `is_git_repo`, `has_remote`, `get_current_branch`, `get_default_branch`, `is_on_default_branch`, `has_uncommitted_changes`, `get_branch_tracking_status`, `get_base_branch_drift`, `fetch_with_retry`, `derive_branch_purpose`, `normalize_protect_default_branch`.
+- **`03-rebase-and-conflicts.md`** — `attempt_rebase`, `get_conflict_details`, `needs_force_push`, conflict strategy handling.
+- **`04-agent-and-worktree.md`** — `is_agent_context`, `is_operation_agent_restricted`, `create_worktree`, `remove_worktree`, `register_worktree`, `unregister_worktree`, `list_worktrees`.
+- **`05-stash-and-robustness.md`** — `auto_stash`, `auto_restore_stash`, `output_block`, `output_allow_with_message`.
+
+## 1. Updated `hooks.json`
+
+```json
+{
+  "description": "git-pilot: Automated git workflow management",
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh",
+        "timeout": 30
+      }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-context.sh",
+        "timeout": 5
+      }]
+    }],
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
+        "timeout": 10
+      }]
+    }],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-write.sh",
+          "timeout": 10
+        }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-bash.sh",
+          "timeout": 15
+        }]
+      }
+    ],
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh",
+        "timeout": 45
+      }]
+    }]
+  }
+}
+```
+
+**Changes from v1**: SessionStart timeout 15 → 30 (fetch + freshness). PostToolUse Bash timeout 10 → 15 (push rejection + rebase). Stop timeout 30 → 45 (drift + rebase + MR). NEW: `UserPromptSubmit` hook for branch context (5s timeout).
+
+## 2. New Script: `prompt-context.sh`
+
+Runs on every user prompt submission. Provides branch context for unrelated work detection.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/config.sh"
+source "$SCRIPT_DIR/git-utils.sh"
+source "$SCRIPT_DIR/agent.sh"
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+
+if [[ -z "$cwd" ]]; then echo '{"continue": true}'; exit 0; fi
+cd "$cwd" 2>/dev/null || { echo '{"continue": true}'; exit 0; }
+if ! is_git_repo; then echo '{"continue": true}'; exit 0; fi
+
+config=$(load_config "$cwd")
+
+detection_enabled=$(get_config "$config" '.branch.unrelatedWorkDetection' 'true')
+if [[ "$detection_enabled" != "true" ]]; then echo '{"continue": true}'; exit 0; fi
+if is_agent_context "$session_id"; then echo '{"continue": true}'; exit 0; fi
+
+current_branch=$(get_current_branch)
+default_branch=$(get_default_branch "$config")
+
+# Skip if on default branch or detached HEAD
+if [[ -z "$current_branch" ]] || [[ "$current_branch" == "$default_branch" ]]; then
+  echo '{"continue": true}'; exit 0
+fi
+
+# Skip if branch has no commits
+commit_count=$(git rev-list --count "${default_branch}..${current_branch}" 2>/dev/null || echo "0")
+if [[ "$commit_count" == "0" ]]; then echo '{"continue": true}'; exit 0; fi
+
+branch_purpose=$(derive_branch_purpose "$current_branch")
+recent_commits=$(git log "${default_branch}..${current_branch}" --oneline --no-decorate -5 2>/dev/null || true)
+message="[git-pilot] Branch context: '${current_branch}' (${branch_purpose}). ${commit_count} commit(s). Recent: ${recent_commits}"
+jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+```
+
+## 3. Modified Script: `session-start.sh`
+
+### 3a. Fetch remote (insert after git init check, before branch detection)
+
+```bash
+if is_git_repo && has_remote; then
+  auto_fetch=$(get_config "$CONFIG" '.git.autoFetch' 'true')
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  if [[ "$auto_fetch" == "true" ]]; then
+    retries=$(get_config "$CONFIG" '.git.fetchRetries' '2')
+    if ! fetch_with_retry "$remote_name" "$CONFIG"; then
+      messages+=("[git-pilot] Warning: Could not fetch from '${remote_name}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync.")
+    fi
+  fi
+fi
+```
+
+### 3b. Branch freshness check (insert after getting `current_branch`)
+
+```bash
+if is_git_repo && has_remote && [[ -n "$current_branch" ]]; then
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  tracking_status=$(get_branch_tracking_status "$current_branch" "$remote_name")
+  case "$tracking_status" in
+    behind:*)
+      behind_count="${tracking_status#behind:}"
+      if git merge --ff-only "${remote_name}/${current_branch}" >/dev/null 2>&1; then
+        messages+=("[git-pilot] Branch '${current_branch}' was ${behind_count} commit(s) behind '${remote_name}/${current_branch}'. Fast-forwarded to latest.")
+      else
+        messages+=("[git-pilot] Branch '${current_branch}' is ${behind_count} commit(s) behind '${remote_name}/${current_branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is.")
+      fi
+      ;;
+    diverged:*:*)
+      IFS=':' read -r _ ahead_count behind_count <<< "$tracking_status"
+      messages+=("[git-pilot] Branch '${current_branch}' has diverged from '${remote_name}/${current_branch}' (${ahead_count} local, ${behind_count} remote). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue.")
+      ;;
+    ahead:*)
+      ahead_count="${tracking_status#ahead:}"
+      messages+=("[git-pilot] Branch '${current_branch}' is ${ahead_count} commit(s) ahead of '${remote_name}/${current_branch}'. Unpushed changes.")
+      ;;
+    # up-to-date and no-remote: no message
+  esac
+fi
+```
+
+### 3c. Detached HEAD detection (inside branch detection, when `get_current_branch` returns empty)
+
+```bash
+if [[ -z "$current_branch" ]]; then
+  local head_sha
+  head_sha=$(git rev-parse --short HEAD 2>/dev/null)
+  local prev_branch
+  prev_branch=$(git reflog show --format='%gs' | grep -m1 'checkout: moving from' | \
+    sed 's/checkout: moving from \([^ ]*\) to .*/\1/')
+  if [[ -n "$prev_branch" ]]; then
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Previous branch was '${prev_branch}'. Prompt the user: return to '${prev_branch}', create a new branch from HEAD, or continue in detached state.")
+  else
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Prompt the user: create a new branch from HEAD or continue in detached state.")
+  fi
+fi
+```
+
+### 3d. Extended state init (replace existing Step 9)
+
+```bash
+if [[ -n "$SESSION_ID" ]]; then
+  base_branch="$default_branch"
+  branch_purpose=""
+  if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    branch_purpose=$(derive_branch_purpose "$current_branch")
+    configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+    if [[ -n "$configured_base" ]]; then
+      base_branch="$configured_base"
+    fi
+  fi
+  init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
+fi
+```
+
+> **Note**: `init_state()` creates or resets the session state file (see `01-config-and-state.md` for the full definition). The 5 arguments map to session state fields: `sessionId`, `workingBranch`, `previousBranch`, `baseBranch`, and `branchPurpose`. It also sets `startTime` to the current ISO timestamp, `headAtStart` to the current HEAD SHA, and initializes counters (`changeCount: 0`, `modifiedFiles: []`, etc.).
+
+## 4. Modified Script: `session-stop.sh`
+
+### 4a. Drift detection (insert after work summary, before push workflow)
+
+```bash
+# 1.5: Base branch drift detection
+if [[ "$session_had_changes" == "true" ]] && has_remote; then
+  auto_rebase=$(get_config "$config" '.rebase.autoRebaseBeforePush' 'true')
+  if [[ "$auto_rebase" == "true" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    source "$SCRIPT_DIR/rebase.sh"
+    drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name")
+    case "$drift_status" in
+      drifted:*)
+        drift_count="${drift_status#drifted:}"
+        messages+=("[git-pilot] Base branch '${default_branch}' has ${drift_count} new commit(s). Rebasing '${current_branch}' onto '${remote_name}/${default_branch}'...")
+        rebase_result=$(attempt_rebase "${remote_name}/${default_branch}")
+        case "$rebase_result" in
+          success)
+            messages+=("[git-pilot] Rebase succeeded cleanly. Ready to push.")
+            ;;
+          conflict)
+            conflict_strategy=$(get_config "$config" '.rebase.conflictStrategy' 'prompt')
+            case "$conflict_strategy" in
+              prompt)
+                conflicts=$(get_conflict_details)
+                conflict_count=$(echo "$conflicts" | jq 'length')
+                conflict_files=$(echo "$conflicts" | jq -r '.[].file' | paste -sd', ')
+                messages+=("[git-pilot] Rebase conflicts in ${conflict_count} file(s): ${conflict_files}. Prompt the user to resolve conflicts, abort rebase, or use merge instead.")
+                ;;
+              abort)
+                git rebase --abort 2>/dev/null
+                messages+=("[git-pilot] Rebase aborted due to conflicts. Pushing without rebase.")
+                ;;
+              merge-fallback)
+                git rebase --abort 2>/dev/null
+                if git merge "${remote_name}/${default_branch}" --no-edit 2>/dev/null; then
+                  messages+=("[git-pilot] Merge with '${default_branch}' succeeded (rebase had conflicts).")
+                else
+                  conflicts=$(get_conflict_details)
+                  conflict_count=$(echo "$conflicts" | jq 'length')
+                  messages+=("[git-pilot] Both rebase and merge have conflicts in ${conflict_count} file(s). Prompt the user to resolve.")
+                fi
+                ;;
+            esac
+            ;;
+        esac
+        ;;
+      no-drift)
+        # No action needed
+        ;;
+      no-common-ancestor)
+        messages+=("[git-pilot] Cannot determine common ancestor between '${current_branch}' and '${default_branch}'. Skipping rebase. Push may require manual review.")
+        ;;
+    esac
+  fi
+fi
+```
+
+> **Agent context**: If `is_agent_context "$session_id"` is true, skip the drift detection and rebase block entirely (agents suppress rebase/conflict prompts — abort rebase silently). Wrap the drift detection code above in:
+> ```bash
+> if ! is_agent_context "$session_id"; then
+>   # ... drift detection and rebase code ...
+> fi
+> ```
+> Similarly, skip the session summary output for agents. If the existing session summary section emits messages, guard it with:
+> ```bash
+> if ! is_agent_context "$session_id"; then
+>   # ... session summary messages ...
+> fi
+> ```
+> See `04-agent-and-worktree.md` for `is_agent_context()` and the suppression table (rebase/conflict prompts: suppressed; session summary: suppressed).
+
+### 4b. Worktree cleanup (insert after MR/push, before state cleanup)
+
+```bash
+source "$SCRIPT_DIR/worktree.sh"
+registry=$(list_worktrees)
+active_count=$(echo "$registry" | jq '.worktrees | length')
+if [[ "$active_count" -gt 0 ]]; then
+  cleanup_on_merge=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+  if [[ "$cleanup_on_merge" == "true" ]]; then
+    echo "$registry" | jq -r '.worktrees[] | select(.status == "active") | .path' | \
+    while IFS= read -r wt_path; do
+      if [[ -d "$wt_path" ]]; then
+        wt_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
+        if [[ -n "$wt_branch" ]] && git branch --merged "$default_branch" | grep -q "$wt_branch"; then
+          remove_worktree "$wt_path" "false"
+        fi
+      else
+        unregister_worktree "$wt_path"
+      fi
+    done
+  fi
+  remaining=$(list_worktrees | jq '.worktrees | length')
+  if [[ "$remaining" -gt 0 ]]; then
+    messages+=("[git-pilot] ${remaining} active worktree(s) remain. Use /worktree to manage them.")
+  fi
+fi
+```
+
+## 5. Modified Script: `post-bash.sh`
+
+### 5a. Agent suppression (insert after loading config, before push check)
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+if is_agent_context "$session_id"; then
+  if is_operation_agent_restricted "$config" "push"; then
+    echo '{"continue": true}'
+    exit 0
+  fi
+fi
+```
+
+### 5b. Push rejection detection (insert after existing push prompt logic)
+
+```bash
+exit_code=$(echo "$input" | jq -r '.tool_result.exitCode // 0')
+stdout=$(echo "$input" | jq -r '.tool_result.stdout // empty')
+stderr=$(echo "$input" | jq -r '.tool_result.stderr // empty')
+if echo "$command" | grep -qE 'git\s+push' && [[ "$exit_code" != "0" ]]; then
+  if echo "$stderr" | grep -qiE 'rejected|failed to push|non-fast-forward'; then
+    current_branch=$(get_current_branch)
+    remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
+    message="[git-pilot] Push rejected — remote '${remote_name}/${current_branch}' has new commits. Prompt the user:
+1. Pull and rebase, then retry push (git pull --rebase && git push)
+2. Force push with lease (git push --force-with-lease)
+3. Pull and merge (git pull)
+4. Cancel"
+    jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+    exit 0
+  fi
+fi
+```
+
+## 6. Modified Script: `post-write.sh`
+
+Agent suppression -- insert after loading config. Still track file changes but suppress commit suggestion messages for agents:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+if is_agent_context "$session_id"; then
+  # Tracking code runs, but skip the threshold message
+  exit 0
+fi
+```
+
+## 7. Modified Script: `pre-commit.sh`
+
+### 7a. Branch switch detection with auto-stash
+
+Add to the branch creation detection section:
+
+```bash
+is_branch_switch_command() {
+  local cmd="$1"
+  SWITCH_TARGET=""
+  # git checkout <branch> (not -b)
+  if [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+-[bB] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+  # git switch <branch> (not -c)
+  if [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+-[cC] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+SWITCH_TARGET=""
+if is_branch_switch_command "$COMMAND"; then
+  auto_stash=$(get_config "$CONFIG" '.branch.autoStashOnSwitch' 'true')
+  if [[ "$auto_stash" == "true" ]] && has_uncommitted_changes; then
+    current_br=$(get_current_branch)
+    if auto_stash "$current_br" "$SESSION_ID"; then
+      output_allow_with_message "[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."
+    fi
+  fi
+fi
+```
+
+### 7b. Enhanced protected branch blocking
+
+Replace existing default-branch warning with tri-state logic:
+
+```bash
+protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$protect_mode")
+if is_on_default_branch "$CONFIG" 2>/dev/null; then
+  default_br=$(get_default_branch "$CONFIG")
+  case "$protect_mode" in
+    warn)
+      SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+      ;;
+    block)
+      output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+      ;;
+    off)
+      ;;
+  esac
+fi
+```
diff --git a/spec/07-skills-and-claude-md.md b/spec/07-skills-and-claude-md.md
new file mode 100644
index 0000000..201c3aa
--- /dev/null
+++ b/spec/07-skills-and-claude-md.md
@@ -0,0 +1,395 @@
+# Module 07: Skills and CLAUDE.md
+
+## Cross-references
+
+- **`01-config-and-state.md`** — `load_config`, `get_config`, session state schema, `get_state_file`, `read_state`, `update_state`, `init_state`, `write_state`.
+- **`03-rebase-and-conflicts.md`** — `attempt_rebase()`, `get_conflict_details()`, `needs_force_push()`, `get_base_branch_drift()` used by `/rebase` and `/finish`.
+- **`04-agent-and-worktree.md`** — `create_worktree()`, `remove_worktree()`, `register_worktree()`, `unregister_worktree()`, `list_worktrees()`, `merge_worktree_branch()` used by `/worktree`.
+- **`05-stash-and-robustness.md`** — `auto_stash()`, `auto_restore_stash()`, `has_uncommitted_changes()` used by `/stash` and Rule 8.
+
+## 1. Complete v2 CLAUDE.md
+
+Replaces the v1 version. Contains 10 rules and an updated skill reference table.
+
+### File: `plugins/git-pilot/CLAUDE.md`
+
+```markdown
+# git-pilot — Git Workflow Autopilot
+
+git-pilot manages the full git workflow lifecycle. You MUST follow these rules throughout every session.
+
+## Rule 1: Always act on hook messages
+
+When you receive a system message prefixed with `[git-pilot]` from any hook (SessionStart, PostToolUse, Stop), you MUST act on it using AskUserQuestion BEFORE continuing with other work. Never ignore these messages. Present clear, concise options relevant to the prompt.
+
+## Rule 2: Branch discipline
+
+- Never work directly on the default branch. If you're on the default branch when starting work, follow the `/branch` skill workflow to create a feature branch before making any changes.
+- Name branches using the configured pattern (default: `{{type}}/{{description}}`, kebab-case).
+- Available types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`, `perf`, `build`, `ci`.
+- If the user's request clearly implies a branch type and description, you can infer the branch name and propose it. Otherwise, ask.
+- Check `.claude/git-pilot.json` (local) or `~/.claude/git-pilot.json` (global) for project-specific overrides.
+
+## Rule 3: Commit discipline
+
+- Follow the configured commit format (default: `{{type}}({{scope}}): {{description}}`).
+- Do NOT include `Co-Authored-By`, `Generated with`, or any AI attribution lines in commits.
+- Keep commit subjects under the configured max length (default: 72).
+- Use imperative mood ("add" not "added").
+- One logical change per commit. When you've completed a coherent unit of work, commit it — don't accumulate unrelated changes.
+- **Body policy**: Check `commit.body.required` in the effective config (defaults, global, local merged). If `false`, commits MUST be subject-line only — do NOT include a body. The only exception is breaking changes: when the subject contains `!:` and `commit.breakingChange.requireBody` is `true`, a body starting with the configured `bodyPrefix` (default: `BREAKING CHANGE: `) is required.
+
+## Rule 4: Push workflow
+
+After every successful `git commit`, check for unpushed commits. If there are any and a remote exists:
+- Use AskUserQuestion to prompt the user with two options: **"Push to <remote>/<branch>"** and **"Skip"**.
+- If they choose to push, run: `git push -u <remote> <branch>`.
+- Do NOT silently skip this step or just mention it in passing. The user expects an interactive prompt.
+
+## Rule 5: Session end
+
+When finishing a session, follow the `/finish` skill workflow:
+1. Commit any remaining uncommitted changes.
+2. If unpushed commits exist, prompt to push (same as Rule 4).
+3. If merge request creation is enabled, offer to create one using the appropriate platform CLI (`gh` for GitHub, `glab` for GitLab) or skip silently if the CLI isn't available.
+
+## Rule 6: Configuration
+
+- Users can change git-pilot settings by asking in natural language (via `/configure` skill).
+- Global config: `~/.claude/git-pilot.json`
+- Local config: `.claude/git-pilot.json`
+- Local settings override global settings which override plugin defaults.
+- When changing config, ask whether the change should be global or project-specific.
+
+## Rule 7: Unrelated work detection
+
+Before starting work on a new user request, assess whether the request is related
+to the current branch's purpose:
+
+1. **Branch name**: Parse the branch name for semantic meaning. For example,
+   `feat/add-dark-mode` implies work on dark mode; `fix/login-timeout` implies
+   fixing a login timeout bug.
+2. **Recent commits**: Review the commit log on this branch for scope context.
+3. **Assessment**: If the user's request is clearly unrelated to the branch's
+   purpose (different feature, different bug, different module), prompt the user:
+
+   "This work appears unrelated to the current branch (`<branch-name>`).
+   Options:
+   1. Create a new branch from `<default-branch>` (recommended — keeps branches focused)
+   2. Create a new branch from the current branch (if this work depends on current changes)
+   3. Continue on this branch"
+
+4. **When NOT to prompt**: Do not prompt for closely related work (e.g., fixing
+   a bug discovered while implementing a feature on the same branch), for work
+   on the default branch, or for branches with no commits yet.
+5. **If the user chooses to create a new branch**: Follow the branch switch
+   workflow (see Rule 8).
+
+## Rule 8: Branch switching
+
+When switching branches (via /branch, user request, or unrelated work detection):
+
+1. If there are uncommitted changes and `branch.autoStashOnSwitch` is `true`, stash
+   them automatically before switching. Inform the user: "Stashed changes on '<branch>'."
+2. After switching, check if there's a git-pilot stash for the target branch and
+   restore it automatically.
+3. If stash restoration fails (conflicts), inform the user and suggest manual resolution.
+
+## Rule 9: Conflict resolution
+
+When a rebase or merge results in conflicts:
+
+1. Read the conflicting files to understand the nature of each conflict.
+2. For each conflict, provide a recommendation:
+   - If only one side modified the region, recommend accepting that side.
+   - If both sides modified the same lines, recommend manual review.
+   - If a file was deleted on one side, explain the tradeoff.
+3. Present clear options: resolve manually, accept ours, accept theirs, abort.
+4. After the user resolves conflicts, continue the interrupted operation
+   (`git rebase --continue` or `git merge --continue`).
+
+## Rule 10: Agent Teams
+
+When operating as a spawned agent (not the orchestrator):
+
+1. Do not prompt for push, MR creation, or branch switching. These are
+   orchestrator-only operations.
+2. Follow commit rules normally — agents must still use proper commit format.
+3. Do not run auto-commit suggestions. Commit when instructed by the orchestrator.
+4. If instructed to work in a specific worktree directory, stay in that directory.
+
+## Skill reference
+
+| Skill | When to use |
+|-------|-------------|
+| `/branch` | Proactively when on the default branch before making changes |
+| `/finish` | When the user says they're done, or at session end |
+| `/summary` | When the user asks for a recap of branch work |
+| `/configure` | When the user wants to change git-pilot settings |
+| `/stash` | When the user wants to manage git stashes |
+| `/worktree` | When the user wants to manage git worktrees |
+| `/rebase` | When the user wants to rebase the current branch |
+```
+
+## 2. Unrelated Work Detection
+
+**Mechanism**: CLAUDE.md Rule 7 + session state context. No additional hook beyond `prompt-context.sh` (provides branch context on every user prompt).
+
+**Preconditions**: On a feature branch (not default branch). `branch.unrelatedWorkDetection` is `true`. Branch has at least one commit.
+
+### 2.1 Branch Purpose Derivation
+
+Stored in session state field `branchPurpose` at init.
+
+```bash
+# In git-utils.sh
+derive_branch_purpose() {
+  local branch_name="$1"
+
+  # Strip type prefix (e.g., "feat/", "fix/")
+  local description
+  description=$(echo "$branch_name" | sed 's|^[^/]*/||')
+
+  # Convert kebab-case/snake_case to words
+  description=$(echo "$description" | tr '-' ' ' | tr '_' ' ')
+
+  echo "$description"
+}
+```
+
+`session-start.sh` stores `branchPurpose` in state and includes it in its systemMessage for session-wide context. The extended state init in `session-start.sh`:
+
+```bash
+if [[ -n "$SESSION_ID" ]]; then
+  base_branch="$default_branch"
+  branch_purpose=""
+  if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    branch_purpose=$(derive_branch_purpose "$current_branch")
+    # Try to detect base branch from tracking config
+    configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+    if [[ -n "$configured_base" ]]; then
+      base_branch="$configured_base"
+    fi
+  fi
+  init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
+fi
+```
+
+## 3. Modifications to Existing Skills
+
+### 3.1 `/branch` — Base Branch Recording (add after existing Step 4)
+
+```markdown
+## Step 5: Record Branch Context
+
+After creating the branch, note the base branch (the branch you were on before switching)
+and the branch purpose (derived from the description). These are used for unrelated work
+detection and drift checks.
+```
+
+### 3.2 `/finish` — Drift Detection (add between existing Step 1 and Step 2)
+
+```markdown
+## Step 1.5: Check Base Branch Drift
+
+Before pushing, check if the base branch has advanced:
+
+1. Run `git fetch <remote> <defaultBranch>`.
+2. Check for new commits on the base branch since this branch diverged.
+3. If the base has new commits and `rebase.autoRebaseBeforePush` is `true`:
+   - Attempt `git rebase <remote>/<defaultBranch>`.
+   - If rebase succeeds: continue to push.
+   - If rebase has conflicts: present conflict details and options to the user.
+4. If force push is needed after rebase, follow `rebase.allowForcePush` policy.
+```
+
+The `/finish` skill calls the same drift detection logic as `session-stop.sh`. Base branch determined in order: (1) session state `baseBranch` field, (2) `git config branch.${current}.merge` with `refs/heads/` stripped, (3) `git.defaultBranch` from config.
+
+### 3.3 `/summary` — No modifications needed for v2
+
+The `/summary` skill requires no modifications for v2. It continues to work as-is, reading session state and commit history to produce a branch work recap.
+
+### 3.4 `/configure` — New Config Keys (add to reference table)
+
+```markdown
+| "Fetch remote on session start" | `git.autoFetch: true` |
+| "Block commits to main" | `git.protectDefaultBranch: "block"` |
+| "Don't warn about main branch commits" | `git.protectDefaultBranch: "off"` |
+| "Disable unrelated work detection" | `branch.unrelatedWorkDetection: false` |
+| "Don't auto-stash on branch switch" | `branch.autoStashOnSwitch: false` |
+| "Don't auto-rebase before push" | `rebase.autoRebaseBeforePush: false` |
+| "Never force push" | `rebase.allowForcePush: "never"` |
+| "Always force push after rebase" | `rebase.allowForcePush: "always"` |
+| "Use merge when rebase conflicts" | `rebase.conflictStrategy: "merge-fallback"` |
+| "Disable worktrees" | `worktree.enabled: false` |
+| "Worktrees in /tmp" | `worktree.basePath: "/tmp/{{project}}-worktrees"` |
+```
+
+## 4. New Skills
+
+### 4.1 `/stash` — File: `plugins/git-pilot/skills/stash/SKILL.md`
+
+```markdown
+---
+name: stash
+description: Manage git stashes - save, list, apply, or drop
+---
+
+# /stash
+
+Manage git stashes for the current repository.
+
+## Step 1: Determine Action
+
+If the user provided an argument after `/stash`, parse it:
+- `/stash` or `/stash save` — stash current changes
+- `/stash list` — list all stashes
+- `/stash pop` or `/stash apply` — restore the most recent stash
+- `/stash drop` — drop the most recent stash
+
+If no argument, ask the user what they want to do.
+
+## Step 2: Execute
+
+### Save
+1. Check for uncommitted changes. If none: "Nothing to stash."
+2. Ask the user for an optional stash message.
+3. Run `git stash push -m "<message>"` (or `git stash push` if no message).
+4. Confirm: "Stashed changes: <stash-ref>"
+
+### List
+1. Run `git stash list`.
+2. If empty: "No stashes found."
+3. Present the list with index, branch, and message.
+
+### Pop / Apply
+1. Run `git stash list`. If empty: "No stashes to restore."
+2. If multiple stashes, show the list and ask which one.
+3. For pop: `git stash pop <ref>`. For apply: `git stash apply <ref>`.
+4. If conflicts: warn the user and show conflicting files.
+
+### Drop
+1. Run `git stash list`. If empty: "No stashes to drop."
+2. If multiple stashes, show the list and ask which one.
+3. Confirm before dropping.
+4. Run `git stash drop <ref>`.
+```
+
+### 4.2 `/worktree` — File: `plugins/git-pilot/skills/worktree/SKILL.md`
+
+```markdown
+---
+name: worktree
+description: Manage git worktrees for parallel branch work
+---
+
+# /worktree
+
+Manage git worktrees for parallel branch work.
+
+## Step 1: Determine Action
+
+Parse the user's intent:
+- `/worktree` or `/worktree list` — list active worktrees
+- `/worktree create <branch>` — create a new worktree for a branch
+- `/worktree remove <path-or-branch>` — remove a worktree
+- `/worktree merge <path-or-branch>` — merge a worktree's branch and clean up
+
+If no argument, show the list of active worktrees.
+
+## Step 2: Execute
+
+### List
+1. Read the worktree registry (`.git/git-pilot-worktrees.json`).
+2. Also run `git worktree list` for system-level view.
+3. Present: path, branch, base branch, creation date, status.
+
+### Create
+1. Ask for the branch name (or parse from argument).
+2. Ask for the base branch (default: `git.defaultBranch`).
+3. Determine the worktree path using `worktree.basePath` config.
+4. Run `git worktree add <path> -b <branch> <base>`.
+5. Register in the worktree registry.
+6. Confirm with the worktree path.
+
+### Remove
+1. Identify the worktree by path or branch name.
+2. Check for uncommitted changes in the worktree.
+3. If uncommitted changes, warn and ask to confirm.
+4. Run `git worktree remove <path>`.
+5. Optionally delete the branch: `git branch -d <branch>`.
+6. Unregister from the registry.
+
+### Merge
+1. Identify the worktree by path or branch name.
+2. Get the worktree's branch and its base branch from the registry.
+3. Switch main worktree to the base branch.
+4. Attempt `git merge <worktree-branch> --no-edit`.
+5. If conflicts: present them and ask user to resolve.
+6. If `worktree.cleanupOnMerge` is `true`: remove the worktree and delete the branch.
+7. Confirm the merge.
+```
+
+### 4.3 `/rebase` — File: `plugins/git-pilot/skills/rebase/SKILL.md`
+
+```markdown
+---
+name: rebase
+description: Rebase current branch onto another branch
+---
+
+# /rebase
+
+Rebase the current branch onto a target branch.
+
+## Step 1: Determine Target
+
+If the user specified a target branch (e.g., `/rebase main`), use it.
+Otherwise, default to the configured `git.defaultBranch`.
+
+## Step 2: Pre-flight Checks
+
+1. Ensure the working tree is clean. If uncommitted changes exist, ask to stash or commit first.
+2. Fetch the remote target branch: `git fetch <remote> <target>`.
+3. Check how many commits will be rebased: `git rev-list --count <remote>/<target>..HEAD`.
+4. Show the user: "Rebasing N commit(s) onto <remote>/<target>."
+
+## Step 3: Execute Rebase
+
+1. Run `git rebase <remote>/<target>`.
+2. If success: "Rebase completed successfully."
+3. If conflicts:
+   - Show conflicting files and conflict details.
+   - Present resolution options:
+     a. Resolve manually (edit files, then `git add <file>` and `git rebase --continue`)
+     b. Accept theirs for all (`git checkout --theirs . && git add .`)
+     c. Accept ours for all (`git checkout --ours . && git add .`)
+     d. Abort (`git rebase --abort`)
+   - After resolution, run `git rebase --continue`.
+
+## Step 4: Handle Force Push
+
+If the branch was previously pushed and rebase rewrote history:
+1. Inform: "Rebase rewrote history. Force push is needed to update the remote."
+2. Based on `rebase.allowForcePush`:
+   - `"ask"`: Ask user to confirm force push.
+   - `"always"`: Push with `--force-with-lease` automatically.
+   - `"never"`: Inform that force push is disabled.
+3. Use `git push --force-with-lease <remote> <branch>`.
+```
+
+## 5. Config Keys Reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `branch.unrelatedWorkDetection` | boolean | `true` | Enable unrelated work detection (Rule 7) |
+| `branch.autoStashOnSwitch` | boolean | `true` | Auto-stash on branch switch (Rule 8) |
+| `rebase.autoRebaseBeforePush` | boolean | `true` | Rebase onto base before push (`/finish`) |
+| `rebase.conflictStrategy` | string | `"prompt"` | `"prompt"` / `"abort"` / `"merge-fallback"` |
+| `rebase.allowForcePush` | string | `"ask"` | `"ask"` / `"never"` / `"always"` |
+| `worktree.enabled` | boolean | `true` | Enable worktree management (`/worktree`) |
+| `worktree.basePath` | string | `"../{{project}}-worktrees"` | Worktree directory pattern |
+| `worktree.cleanupOnMerge` | boolean | `true` | Remove worktree after merge |
+| `git.protectDefaultBranch` | string | `"warn"` | `"warn"` / `"block"` / `"off"` |
+| `agentTeams.suppressPromptsForAgents` | boolean | `true` | Suppress interactive prompts for spawned agents (see `04-agent-and-worktree.md`) |
+| `agentTeams.orchestratorOnly` | array | `["push", "mr"]` | Operations restricted to orchestrator agent (see `04-agent-and-worktree.md`) |
diff --git a/spec/VALIDATION.md b/spec/VALIDATION.md
new file mode 100644
index 0000000..7672e70
--- /dev/null
+++ b/spec/VALIDATION.md
@@ -0,0 +1,267 @@
+# Spec Decomposition Validation Report (Pass 2)
+
+Validated against: `/home/eco/Code/Personal/opaq/claude-code-plugins/TECHNICAL-SPEC.md`
+
+Previous report: 28 issues (6 critical, 6 moderate, 16 low)
+
+---
+
+## Previously Reported Critical Issues (6)
+
+### C1. Missing state management function signatures (Module 01)
+
+**Status: RESOLVED**
+
+Module 01 Section 4 ("State Management Library") now includes:
+- Section 4.1 Function Signatures table with `get_state_file`, `read_state`, `write_state`, `init_state`, `update_state`, and `cleanup_state` -- all with parameters, returns, and descriptions.
+- Section 4.2 Key Implementations with full code for `write_state()`, `init_state()` (5-argument v2 signature), and `update_state()`.
+
+### C2. Missing utility function signatures in Module 02
+
+**Status: RESOLVED**
+
+Module 02 Section 5 ("Core Utility Functions") now includes full implementations for: `is_git_repo()`, `get_current_branch()`, `has_uncommitted_changes()`, `get_default_branch()`, `is_on_default_branch()`, `has_remote()`, and `sanitize_branch_name()`. Section 5.1 provides a function reference table with parameters, returns, and downstream usage.
+
+### C3. Missing `output_block()` and `output_allow_with_message()` definitions (Module 05)
+
+**Status: RESOLVED**
+
+Module 05 Section 4 ("Hook Output Helper Functions") now provides full definitions for:
+- `output_allow()` (Section 4.1)
+- `output_allow_with_message()` (Section 4.1)
+- `output_allow_with_updated_input()` (Section 4.1)
+- `output_allow_with_message_and_updated_input()` (Section 4.1)
+- `output_block()` (Section 4.2)
+
+All include code, behavior description, and cross-module usage summary.
+
+### C4. Missing `derive_branch_purpose()` from Module 02
+
+**Status: RESOLVED**
+
+Module 02 Section 6 ("Branch Purpose Derivation") now includes:
+- The full `derive_branch_purpose()` function with code (Section 6.1).
+- Usage context showing how `session-start.sh` calls it (Section 6.2).
+- Examples table mapping branch names to outputs (Section 6.3).
+
+### C5. Missing agent context checks in `session-stop.sh` (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 4a now includes an "Agent context" note block (lines 254-266) with explicit code showing:
+- How to wrap drift detection in `if ! is_agent_context "$session_id"` guard.
+- How to wrap session summary in the same guard.
+- Cross-reference to `04-agent-and-worktree.md` for the suppression table.
+
+### C6. `no-common-ancestor` handling -- spec says emit warning, module said "no action" (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 4a drift detection code now includes an explicit `no-common-ancestor)` case (line 246-248) that emits: `"[git-pilot] Cannot determine common ancestor between '${current_branch}' and '${default_branch}'. Skipping rebase. Push may require manual review."` This matches the spec (SS4.2 decision flow point 3). The old `# no-drift, no-common-ancestor: no action` comment has been replaced.
+
+---
+
+## Previously Reported Moderate Issues (6)
+
+### M1. `ahead:N` systemMessage text drift (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 3b now uses: `"[git-pilot] Branch '${current_branch}' is ${ahead_count} commit(s) ahead of '${remote_name}/${current_branch}'. Unpushed changes."` This matches the spec's SS4.1 table message: `"[git-pilot] Branch '${branch}' is ${N} commit(s) ahead of '${remote}/${branch}'. Unpushed changes."` (variable names differ due to context but the message template is verbatim-equivalent). The previously reported shortened form `"${ahead_count} unpushed commit(s) on '${current_branch}'"` has been corrected.
+
+**Note**: The spec's own `session-start.sh` code at SS5.1.3 point 2 still uses the shortened form `"[git-pilot] ${ahead_count} unpushed commit(s) on '${current_branch}'."` (line 1312). The Module 06 code now uses the SS4.1 canonical form, which is the correct choice. However, an implementer reading the spec's SS5.1.3 code verbatim would find a discrepancy. This is a **spec-internal inconsistency**, not a decomposition error. The module doc has made the correct choice.
+
+### M2. `diverged` systemMessage word drift (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 3b now uses: `"(${ahead_count} local, ${behind_count} remote)"`. This matches the spec's SS4.1 canonical message table which says `"(${A} local, ${B} remote)"`. The previously reported `"(${ahead_count} ahead, ${behind_count} behind)"` wording has been corrected.
+
+**Note**: Same spec-internal inconsistency applies. The spec's SS5.1.3 code (line 1308) still uses `"(${ahead_count} ahead, ${behind_count} behind)"`. Module 06 correctly follows the canonical message from SS4.1.
+
+### M3. Fetch failure message shortened (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 3a now uses the full message: `"[git-pilot] Warning: Could not fetch from '${remote_name}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync."` This matches the spec's SS4.10 all-retries-exhausted message and Module 02 Section 2.4. The previously reported shortened form (omitting "after ${retries} attempts. Network may be unavailable") has been corrected.
+
+**Note**: The spec's SS5.1.3 code (line 1283) still uses the shortened form `"[git-pilot] Warning: Could not fetch from '${remote_name}'. Proceeding without remote sync."`. Module 06 correctly follows the canonical message from SS4.10.
+
+### M4. Stash message inconsistency (Module 05)
+
+**Status: RESOLVED (with accepted deviation)**
+
+Module 05 Section 1.6 message table now reads: `"[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."` This is consistent with the code in both Module 05 Section 1.7 and Module 06 Section 7a.
+
+The spec's SS4.7.3 table says `"[git-pilot] Stashed uncommitted changes on '${branch}' before switching."` (without the switch target). However, the spec's own `pre-commit.sh` code at SS5.1.7 (line 1535) uses `"[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."` -- with the target. The module docs follow the code form, which is more informative. This is a **spec-internal inconsistency** (SS4.7.3 table vs SS5.1.7 code), not a decomposition error. Module 05 is internally consistent.
+
+### M5. Incorrect cross-reference filename in Modules 04 and 05
+
+**Status: RESOLVED**
+
+Module 04 now references `02-git-utils-and-network.md` (line 6: "Depends on `02-git-utils-and-network.md`"). Module 05 also references `02-git-utils-and-network.md` (line 6: "Depends on `02-git-utils-and-network.md`"). The old `02-branch-and-fetch.md` reference has been corrected in both modules. Confirmed no remaining references to `02-branch-and-fetch.md` in any module doc (only VALIDATION.md mentions it historically).
+
+### M6. Missing `stdout` line in `post-bash.sh` (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 5b now includes `stdout=$(echo "$input" | jq -r '.tool_result.stdout // empty')` (line 314), matching the spec's SS5.1.5 code.
+
+---
+
+## Previously Reported Low Issues (16)
+
+### L1. Missing config parse failure error message/behavior (Module 01)
+
+**Status: RESOLVED**
+
+Module 01 Section 1.2 now includes a "Failure behavior" paragraph: "If `jq` cannot parse a config file, the `2>/dev/null || echo "$result"` guard preserves the previous tier's result and processing continues. The caller should emit: `"[git-pilot] Warning: Could not parse config file. Using defaults."`" Module 01 Section 8 ("Error Handling") also includes a full error table with this message.
+
+### L2. Missing state file failure handling (Module 01)
+
+**Status: RESOLVED**
+
+Module 01 Section 4.3 documents the atomic write pattern and failure behavior. Section 8 error table includes: "State file failure | `write_state()` warns and returns 0; state-dependent features disabled | `"[git-pilot] Warning: Cannot access session state. Auto-commit tracking disabled for this session."`"
+
+### L3. Missing dependency check documentation (Modules 01, 05)
+
+**Status: RESOLVED**
+
+Module 01 Section 8 error table now includes rows for missing `git` and missing `jq` with their respective warning messages and handling behavior. Module 05 Section 5.3 ("Config Parse Failure") and Section 5.4 ("State File Failure") also document fallback behavior.
+
+### L4. Missing architecture overview (no module)
+
+**Status: STILL OPEN (Low)**
+
+The spec's architecture overview (SS2.1-2.4: component diagram, data flow summary, new shared libraries table, key technology choices) is not captured in any module doc. The information is distributed across modules, but the high-level architectural context is lost.
+
+### L5. Missing testing strategy and build commands (no module)
+
+**Status: STILL OPEN (Low)**
+
+The spec's testing strategy (SS8), build commands (SS9.1), dependencies table (SS9.2), and file manifest (SS9.3) are not captured in any module doc. Test scenarios are partially covered in individual modules (Module 04 Section 1.8, Module 04 Section 2.8, Module 05 Section 1.10, Module 05 Section 3.6), but the overarching test framework choice (`bats-core`), integration test scenarios (SS8.3), and build/lint commands are not documented.
+
+### L6. Missing performance and security considerations (no module)
+
+**Status: STILL OPEN (Low)**
+
+The spec's performance notes (SS10.1: `prompt-context.sh` must be fast <1s) and security considerations (SS10.2: `--force-with-lease` rationale, state file security) are not explicitly captured in module docs. The `--force-with-lease` usage is documented in Module 03 Section 3.2, but the security reasoning is not stated.
+
+### L7. Missing file manifest (no module)
+
+**Status: STILL OPEN (Low)**
+
+The complete file tree from SS9.3 is not reproduced in any module doc.
+
+### L8. Missing known complexity area: heredoc parsing (no module)
+
+**Status: STILL OPEN (Low)**
+
+SS10.3's note about heredoc commit message parsing limitations is not mentioned in any module doc.
+
+### L9. Missing rebase-specific error message from SS6.3 (no module)
+
+**Status: RESOLVED**
+
+Module 05 Section 5.2 now includes: `"[git-pilot] Rebase failed: could not apply commit abc1234. Conflicts in 2 file(s). Resolve conflicts or run 'git rebase --abort' to cancel."` -- matching the spec's SS6.3 example.
+
+### L10. Missing agent suppression implementation for `session-start.sh` freshness (Module 04)
+
+**Status: RESOLVED**
+
+Module 04 Section 1.5 now includes explicit code for `session-start.sh` agent suppression: agents log freshness to state only (no systemMessage), still fast-forward if behind. The code block shows the `is_agent_context` check and the fallback behavior.
+
+### L11. Missing agent suppression implementation for rebase/summary in `session-stop.sh` (Module 04)
+
+**Status: RESOLVED**
+
+Module 04 Section 1.5 now includes explicit code for `session-stop.sh` agent suppression: agents attempt rebase but abort silently on conflict, emit `{"continue": true}` and exit early (skipping summary). Module 06 Section 4a also includes the agent context guard notes.
+
+### L12. `agentTeams` config keys missing from Module 07 config reference table
+
+**Status: RESOLVED**
+
+Module 07 Section 5 config keys table now includes `agentTeams.suppressPromptsForAgents` and `agentTeams.orchestratorOnly` with correct types, defaults, descriptions, and a cross-reference to `04-agent-and-worktree.md`.
+
+### L13. `WORKTREE_REGISTRY` relative path fragility (Module 04)
+
+**Status: RESOLVED**
+
+Module 04 Section 2.4 now uses `WORKTREE_REGISTRY="$(git rev-parse --git-dir)/git-pilot-worktrees.json"` instead of the hardcoded `.git/git-pilot-worktrees.json`. The section notes this is for correctness in worktree contexts where `.git` is a file.
+
+### L14. `hooks.json` formatting difference (Module 06)
+
+**Status: STILL OPEN (Low)**
+
+Module 06 uses a slightly more compact JSON format for `hooks.json` than the spec's SS5.1.1. Both are semantically equivalent. No functional impact.
+
+### L15. Missing `init_state()` call context (Module 06)
+
+**Status: RESOLVED**
+
+Module 06 Section 3d now includes a note block explaining the 5-argument `init_state()` call: "**Note**: `init_state()` creates or resets the session state file (see `01-config-and-state.md` for the full definition). The 5 arguments map to session state fields: `sessionId`, `workingBranch`, `previousBranch`, `baseBranch`, and `branchPurpose`. It also sets `startTime` to the current ISO timestamp, `headAtStart` to the current HEAD SHA, and initializes counters (`changeCount: 0`, `modifiedFiles: []`, etc.)."
+
+### L16. Missing `/summary` explicit "no changes" note (Module 07)
+
+**Status: RESOLVED**
+
+Module 07 Section 3.3 now explicitly states: "The `/summary` skill requires no modifications for v2. It continues to work as-is, reading session state and commit history to produce a branch work recap."
+
+---
+
+## New Issues Introduced by Repairs
+
+### N1. Spec-internal inconsistency: `ahead:N` message in SS4.1 table vs SS5.1.3 code
+
+**Severity: Informational (not a decomposition defect)**
+
+The spec's SS4.1 table uses `"[git-pilot] Branch '${branch}' is ${N} commit(s) ahead of '${remote}/${branch}'. Unpushed changes."` but the spec's own SS5.1.3 session-start.sh code (line 1312) uses `"[git-pilot] ${ahead_count} unpushed commit(s) on '${current_branch}'."` Module 06 correctly follows the canonical SS4.1 form. An implementer working from the spec alone would need to choose between the two; the module doc has resolved this correctly. Not counted as a decomposition defect.
+
+### N2. Spec-internal inconsistency: `diverged` message in SS4.1 table vs SS5.1.3 code
+
+**Severity: Informational (not a decomposition defect)**
+
+The spec's SS4.1 table uses `"(${A} local, ${B} remote)"` but SS5.1.3 code (line 1308) uses `"(${ahead_count} ahead, ${behind_count} behind)"`. Module 06 correctly follows the canonical SS4.1 form. Not counted as a decomposition defect.
+
+### N3. Spec-internal inconsistency: fetch failure message in SS4.10 vs SS5.1.3
+
+**Severity: Informational (not a decomposition defect)**
+
+SS4.10 uses the full message with retry count; SS5.1.3 code (line 1283) uses a shortened form. Module 06 correctly follows SS4.10. Not counted as a decomposition defect.
+
+### N4. Spec-internal inconsistency: stash message in SS4.7.3 table vs SS5.1.7 code
+
+**Severity: Informational (not a decomposition defect)**
+
+SS4.7.3 table omits `"to '${SWITCH_TARGET}'"` but SS5.1.7 code includes it. Module 05 follows the code form consistently. Not counted as a decomposition defect.
+
+---
+
+## Summary
+
+**Status: PASSES**
+
+### Resolution of Previous Issues
+
+| Category | Total | Resolved | Still Open |
+|----------|-------|----------|------------|
+| Critical | 6 | 6 | 0 |
+| Moderate | 6 | 6 | 0 |
+| Low | 16 | 11 | 5 |
+| **Total** | **28** | **23** | **5** |
+
+### Remaining Open Issues (all Low severity)
+
+1. **L4**: Architecture overview (SS2.1-2.4) not captured in any module doc.
+2. **L5**: Testing strategy (SS8), build commands (SS9.1), dependencies (SS9.2), and file manifest (SS9.3) not captured.
+3. **L6**: Performance (SS10.1) and security (SS10.2) considerations not captured.
+4. **L7**: File manifest (SS9.3) not reproduced in any module.
+5. **L14**: Minor `hooks.json` formatting difference (cosmetic, no functional impact).
+
+### New Issues: 0 (4 informational notes about spec-internal inconsistencies, not decomposition defects)
+
+### Assessment
+
+All 6 critical issues and all 6 moderate issues have been fully resolved. The 5 remaining open issues are all low-severity context items (architecture overview, testing/build docs, performance/security notes, file manifest, cosmetic formatting) that would not block an implementing agent from building the feature. The core requirement -- that every function, config key, error message, and cross-reference is accurately captured -- is now met.
+
+The decomposition **passes** validation.
diff --git a/tasks/COVERAGE.md b/tasks/COVERAGE.md
new file mode 100644
index 0000000..14b0652
--- /dev/null
+++ b/tasks/COVERAGE.md
@@ -0,0 +1,445 @@
+# Task Coverage Validation Report
+
+Generated: 2026-02-24
+
+---
+
+## Check 1: Spec Coverage
+
+For each spec module (01-07), every requirement (function, config key, error message, behavior) was checked against task acceptance criteria.
+
+### Spec 01: Config and State (`spec/01-config-and-state.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| Three-tier config merge (`load_config`, `get_config`) unchanged | 001 (AC3) |
+| Config file locations (defaults, global, local) | 001 (AC1) |
+| Complete v2 `defaults/config.json` schema | 001 (AC1) |
+| `normalize_protect_default_branch()` function | 001 (AC2), 007 (AC7) |
+| Backward compatibility: boolean-to-string migration | 001 (AC4), 009 (AC4-AC7) |
+| `init_state()` 5-argument signature | 002 (AC1) |
+| v2 session state fields (baseBranch, branchPurpose, lastFetchAt, isAgent, agentRole, activeWorktrees, stashRefs) | 002 (AC2) |
+| `update_state()` variadic jq arguments | 002 (AC3) |
+| `read_state()` returns `{}` on missing/invalid JSON | 002 (AC4) |
+| Atomic write pattern (`write_state`) | 002 (AC6 -- unchanged) |
+| `cleanup_state()` unchanged | 002 (AC6) |
+| Worktree registry schema (`git-pilot-worktrees.json`) | 006 (AC1-AC6) |
+| Protected branch behavior by mode (warn/block/off) | 009 (AC4-AC7) |
+| Error: config parse failure message | 001 (AC4 -- three-tier merge guards) |
+| Error: state file failure message | 002 (AC4 -- read_state guard) |
+| Error: missing git/jq warnings | 008 (session-start checks) |
+| Version bump 1.1.0 -> 2.0.0 | 018 (AC1) |
+
+**Result: All requirements covered.**
+
+### Spec 02: Git Utilities and Network (`spec/02-git-utils-and-network.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| `get_branch_tracking_status()` function and all 5 return values | 003 (AC1) |
+| `fetch_with_retry()` with configurable retries and delay | 003 (AC2) |
+| Silent retries; last_error on stderr on failure | 003 (AC6) |
+| `derive_branch_purpose()` function | 003 (AC3) |
+| Core v1 utility functions unchanged | 003 (AC5) |
+| Branch freshness systemMessages (behind, ahead, diverged, up-to-date, no-remote) | 008 (AC2) |
+| Fast-forward auto-merge on `behind:N` | 008 (AC2) |
+| Network error messages (all retries exhausted, push failed) | 008 (AC1), 010 (AC3-AC4) |
+| Integration: fetch before freshness check in session-start | 008 (AC1) |
+| `lastFetchAt` updated on successful fetch | 008 (AC1, via state) |
+| Edge cases: autoFetch false, no remote, no tracking branch | 008 (AC6) |
+
+**Result: All requirements covered.**
+
+### Spec 03: Rebase and Conflicts (`spec/03-rebase-and-conflicts.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| `get_base_branch_drift()` function with 3 return values | 005 (AC2) |
+| Base branch determination order (state, git config, default) | 005 (notes), 012 (AC2), 015 (AC3) |
+| `attempt_rebase()` function with 4 return values | 005 (AC3) |
+| `get_conflict_details()` JSON output | 005 (AC4) |
+| Conflict type detection (both-modified, deleted-by-us, deleted-by-them) | 005 (AC4) |
+| Conflict recommendation heuristics | 005 (AC7) |
+| `rebase.conflictStrategy` handling (prompt/abort/merge-fallback) | 005 (AC6 reference), 012 (AC3) |
+| `needs_force_push()` function | 005 (AC5) |
+| `rebase.allowForcePush` handling (ask/never/always) | 005 (notes) |
+| Force push uses `--force-with-lease` only | 005 (notes) |
+| Push rejection detection and 4-option message | 010 (AC2-AC4) |
+| Conflict resolution systemMessage format | 012 (AC3) |
+| Drift detection in session-stop.sh | 012 (AC2) |
+
+**Result: All requirements covered.**
+
+### Spec 04: Agent Teams Detection and Worktree Management (`spec/04-agent-and-worktree.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| `is_agent_context()` -- CLAUDE_SPAWNED_BY detection | 004 (AC2) |
+| `is_agent_context()` -- state file isAgent fallback | 004 (AC3) |
+| `is_agent_context()` -- returns 1 when neither | 004 (AC4) |
+| `is_operation_agent_restricted()` function | 004 (AC5-AC6) |
+| Prompt suppression pattern in hooks | 010 (AC1), 011 (AC3), 013 (AC3) |
+| Agent suppression in session-start (freshness to state only) | 008 (not explicitly covered -- see note below) |
+| Agent suppression in session-stop (rebase/summary) | 012 (AC4) |
+| Operations and agent behavior table | 004 (notes), 010, 011, 012, 013 |
+| CLAUDE.md Rule 10 (Agent Teams) | 017 (AC5) |
+| `create_worktree()` function | 006 (AC2-AC3) |
+| `remove_worktree()` function | 006 (AC4) |
+| `list_worktrees()` function | 006 (AC5) |
+| `merge_worktree_branch()` function | 006 (AC6) |
+| Worktree registry (register/unregister) | 006 (AC2, AC4) |
+| `{{project}}` placeholder replacement | 006 (AC2) |
+| Worktree cleanup in session-stop | 012 (AC5) |
+| Invariants: half-created worktree cleanup | 006 (notes) |
+| Config keys: agentTeams.suppressPromptsForAgents, orchestratorOnly | 004 (AC7), 001 (AC1) |
+| Config keys: worktree.enabled, basePath, cleanupOnMerge | 006 (AC7), 001 (AC1) |
+
+**Note -- Agent suppression in session-start.sh**: Spec 04 section 1.5 specifies that agents should still fetch and fast-forward but log freshness to state only (no systemMessage prompt). Task 008 does not have an explicit acceptance criterion for agent suppression in session-start.sh. However, task 008's scope states "add four new capabilities" and the spec code it references (spec/06 section 3b) includes the agent context handling. This is a **minor gap** -- it is implicitly covered by the spec code references but not explicitly stated as an acceptance criterion.
+
+**Result: 1 minor gap found (agent suppression in session-start not explicit in task 008 AC). All other requirements covered.**
+
+### Spec 05: Stash Management, Detached HEAD Recovery, and Protected Branch Enhancement (`spec/05-stash-and-robustness.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| `auto_stash()` function | 007 (AC1-AC2) |
+| `auto_restore_stash()` function | 007 (AC3-AC5) |
+| Stash message format | 007 (AC2) |
+| Stash state tracking (stashRefs array) | 007 (AC2, AC4) |
+| Branch switch detection (`is_branch_switch_command()`) | 009 (AC1) |
+| Auto-stash on branch switch trigger in pre-commit.sh | 009 (AC2-AC3) |
+| CLAUDE.md Rule 8 (Branch switching) | 017 (AC3) |
+| Stash data never lost invariant | 007 (AC6) |
+| Detached HEAD detection and recovery | 008 (AC3) |
+| Protected branch tri-state (warn/block/off) | 009 (AC4-AC7) |
+| `normalize_protect_default_branch()` backward compat | 001 (AC2), 007 (AC7) |
+| `output_block()` for block mode | 009 (AC5) |
+| `output_allow_with_message()` for stash | 009 (AC2) |
+| Hook output helper functions | 009 (pre-commit already has them in v1) |
+| Error handling invariants (never leave broken state) | 007 (AC6), 005 (notes) |
+| Stash messages (auto-stash, auto-restore, restore failed) | 007 (AC2), 009 (AC2) |
+
+**Result: All requirements covered.**
+
+### Spec 06: Hooks and Lifecycle (`spec/06-hooks-and-lifecycle.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| Updated hooks.json (timeouts, new UserPromptSubmit entry) | 014 (AC1-AC7) |
+| `prompt-context.sh` new script | 013 (AC1-AC7) |
+| session-start.sh: fetch remote (3a) | 008 (AC1) |
+| session-start.sh: branch freshness (3b) | 008 (AC2) |
+| session-start.sh: detached HEAD (3c) | 008 (AC3) |
+| session-start.sh: extended state init (3d) | 008 (AC4-AC5) |
+| session-stop.sh: drift detection (4a) | 012 (AC2-AC3) |
+| session-stop.sh: worktree cleanup (4b) | 012 (AC5) |
+| session-stop.sh: agent suppression | 012 (AC4) |
+| post-bash.sh: agent suppression (5a) | 010 (AC1) |
+| post-bash.sh: push rejection detection (5b) | 010 (AC2-AC4) |
+| post-write.sh: agent suppression | 011 (AC1-AC5) |
+| pre-commit.sh: branch switch with auto-stash (7a) | 009 (AC1-AC3) |
+| pre-commit.sh: enhanced protected branch blocking (7b) | 009 (AC4-AC7) |
+
+**Result: All requirements covered.**
+
+### Spec 07: Skills and CLAUDE.md (`spec/07-skills-and-claude-md.md`)
+
+| Requirement | Covered by Task(s) |
+|---|---|
+| Complete v2 CLAUDE.md with 10 rules | 017 (AC1-AC6) |
+| Rule 7: Unrelated work detection | 017 (AC2) |
+| Rule 8: Branch switching | 017 (AC3) |
+| Rule 9: Conflict resolution | 017 (AC4) |
+| Rule 10: Agent Teams | 017 (AC5) |
+| Skill reference table (7 skills) | 017 (AC6) |
+| `/branch` skill modification (Step 5) | 015 (AC1) |
+| `/finish` skill modification (Step 1.5) | 015 (AC2-AC3) |
+| `/summary` skill -- no changes needed | 015 (noted in spec 3.3) |
+| `/configure` skill -- new reference entries | 015 (AC4) |
+| `/stash` skill (new) | 016 (AC1) |
+| `/worktree` skill (new) | 016 (AC2) |
+| `/rebase` skill (new) | 016 (AC3) |
+| Config keys reference (11 keys in section 5) | 001 (AC1) |
+
+**Result: All requirements covered.**
+
+### Check 1 Summary
+
+**1 minor gap found**: Task 008 (hook-session-start) does not have an explicit acceptance criterion for agent suppression of freshness messages in session-start.sh, as specified in spec/04 section 1.5. The behavior is referenced in the spec code that task 008 implements, so it is implicitly covered, but it should ideally be an explicit AC.
+
+---
+
+## Check 2: Valid DAG
+
+### Dependency Graph (Text Format)
+
+```
+001-config-schema (no deps)
+  |
+  +---> 002-state-schema
+  |       |
+  |       +---> 004-agent-library (also depends on 001)
+  |       |       |
+  |       |       +---> 010-hook-post-bash
+  |       |       +---> 011-hook-post-write
+  |       |       +---> 012-hook-session-stop (also depends on 003, 005, 006)
+  |       |       +---> 013-hook-prompt-context (also depends on 003)
+  |       |       +---> 017-claude-md-update (also depends on 005, 006, 007)
+  |       |
+  |       +---> 007-stash-functions
+  |       |       |
+  |       |       +---> 009-hook-pre-commit (also depends on 001)
+  |       |       +---> 016-skills-new (also depends on 005, 006)
+  |       |       +---> 017-claude-md-update (also depends on 004, 005, 006)
+  |       |
+  |       +---> 008-hook-session-start (also depends on 001, 003)
+  |
+  +---> 003-git-utils-extensions
+  |       |
+  |       +---> 005-rebase-library (also depends on 001)
+  |       |       |
+  |       |       +---> 012-hook-session-stop (also depends on 004, 006)
+  |       |       +---> 015-skills-modified (also depends on 001)
+  |       |       +---> 016-skills-new (also depends on 006, 007)
+  |       |       +---> 017-claude-md-update (also depends on 004, 006, 007)
+  |       |
+  |       +---> 008-hook-session-start (also depends on 001, 002)
+  |       +---> 012-hook-session-stop (also depends on 004, 005, 006)
+  |       +---> 013-hook-prompt-context (also depends on 004)
+  |
+  +---> 006-worktree-library
+  |       |
+  |       +---> 012-hook-session-stop (also depends on 003, 004, 005)
+  |       +---> 016-skills-new (also depends on 005, 007)
+  |       +---> 017-claude-md-update (also depends on 004, 005, 007)
+  |
+  +---> 009-hook-pre-commit (also depends on 007)
+  +---> 015-skills-modified (also depends on 005)
+
+014-hook-registration
+  +---> depends on 013-hook-prompt-context
+
+018-plugin-metadata
+  +---> depends on 017-claude-md-update
+
+019-test-suite
+  +---> depends on ALL tasks 001-018
+```
+
+### Full Dependency List per Task
+
+| Task | Dependencies |
+|---|---|
+| 001-config-schema | (none) |
+| 002-state-schema | 001 |
+| 003-git-utils-extensions | 001 |
+| 004-agent-library | 001, 002 |
+| 005-rebase-library | 001, 003 |
+| 006-worktree-library | 001 |
+| 007-stash-functions | 002 |
+| 008-hook-session-start | 001, 002, 003 |
+| 009-hook-pre-commit | 001, 007 |
+| 010-hook-post-bash | 004 |
+| 011-hook-post-write | 004 |
+| 012-hook-session-stop | 003, 004, 005, 006 |
+| 013-hook-prompt-context | 003, 004 |
+| 014-hook-registration | 013 |
+| 015-skills-modified | 001, 005 |
+| 016-skills-new | 005, 006, 007 |
+| 017-claude-md-update | 004, 005, 006, 007 |
+| 018-plugin-metadata | 017 |
+| 019-test-suite | 001-018 (all) |
+
+### Cycle Detection
+
+No cycles detected. The graph is a DAG. All edges point forward (lower-numbered tasks to higher-numbered tasks, with the exception of cross-references among mid-range tasks, none of which form cycles).
+
+Verified by tracing all dependency chains:
+- 001 -> 002 -> 004 -> 010 (no back-edge)
+- 001 -> 002 -> 007 -> 009 (no back-edge)
+- 001 -> 003 -> 005 -> 012 (no back-edge)
+- 001 -> 006 -> 012 (no back-edge)
+- All terminal tasks (014, 015, 016, 017, 018, 019) only depend on earlier tasks.
+
+### Dependency Existence Verification
+
+All dependency references match existing task file slugs:
+
+| Referenced Dependency | File Exists? |
+|---|---|
+| 001-config-schema | YES |
+| 002-state-schema | YES |
+| 003-git-utils-extensions | YES |
+| 004-agent-library | YES |
+| 005-rebase-library | YES |
+| 006-worktree-library | YES |
+| 007-stash-functions | YES |
+| 008-hook-session-start | YES |
+| 009-hook-pre-commit | YES |
+| 010-hook-post-bash | YES |
+| 011-hook-post-write | YES |
+| 012-hook-session-stop | YES |
+| 013-hook-prompt-context | YES |
+| 014-hook-registration | YES |
+| 015-skills-modified | YES |
+| 016-skills-new | YES |
+| 017-claude-md-update | YES |
+| 018-plugin-metadata | YES |
+
+**Result: PASS. No cycles. All referenced dependencies exist. All slugs are correct.**
+
+---
+
+## Check 3: Sizing Limits
+
+### Files to Create or Modify (max 3-4 source files)
+
+| Task | File Count | Files | Violation? |
+|---|---|---|---|
+| 001-config-schema | 2 | config.json, config.sh | NO |
+| 002-state-schema | 1 | state.sh | NO |
+| 003-git-utils-extensions | 1 | git-utils.sh | NO |
+| 004-agent-library | 2 | agent.sh (new), config.json | NO |
+| 005-rebase-library | 2 | rebase.sh (new), config.json | NO |
+| 006-worktree-library | 2 | worktree.sh (new), config.json | NO |
+| 007-stash-functions | 1 | git-utils.sh | NO |
+| 008-hook-session-start | 1 | session-start.sh | NO |
+| 009-hook-pre-commit | 1 | pre-commit.sh | NO |
+| 010-hook-post-bash | 1 | post-bash.sh | NO |
+| 011-hook-post-write | 1 | post-write.sh | NO |
+| 012-hook-session-stop | 1 | session-stop.sh | NO |
+| 013-hook-prompt-context | 1 | prompt-context.sh (new) | NO |
+| 014-hook-registration | 1 | hooks.json | NO |
+| 015-skills-modified | 3 | branch/SKILL.md, finish/SKILL.md, configure/SKILL.md | NO |
+| 016-skills-new | 3 | stash/SKILL.md (new), worktree/SKILL.md (new), rebase/SKILL.md (new) | NO |
+| 017-claude-md-update | 1 | CLAUDE.md | NO |
+| 018-plugin-metadata | 1 | plugin.json | NO |
+| 019-test-suite | 9 | common.bash, 8 .bats files | **YES** |
+
+### Acceptance Criteria Count (max 7)
+
+| Task | AC Count | Violation? |
+|---|---|---|
+| 001-config-schema | 5 | NO |
+| 002-state-schema | 6 | NO |
+| 003-git-utils-extensions | 6 | NO |
+| 004-agent-library | 7 | NO |
+| 005-rebase-library | 7 | NO |
+| 006-worktree-library | 7 | NO |
+| 007-stash-functions | 7 | NO |
+| 008-hook-session-start | 6 | NO |
+| 009-hook-pre-commit | 7 | NO |
+| 010-hook-post-bash | 6 | NO |
+| 011-hook-post-write | 5 | NO |
+| 012-hook-session-stop | 7 | NO |
+| 013-hook-prompt-context | 7 | NO |
+| 014-hook-registration | 7 | NO |
+| 015-skills-modified | 6 | NO |
+| 016-skills-new | 6 | NO |
+| 017-claude-md-update | 6 | NO |
+| 018-plugin-metadata | 5 | NO |
+| 019-test-suite | 6 | NO |
+
+### Violations
+
+1. **Task 019 (test-suite)**: 9 files to create (1 helper + 8 test files). This exceeds the 3-4 file maximum. However, these are all test files and follow a consistent pattern, so this is an expected and justifiable exception for a comprehensive test suite task. The task could be split into 2-3 smaller test tasks if strict adherence is required.
+
+**Result: 1 violation (task 019 file count). All acceptance criteria counts are within limits.**
+
+---
+
+## Check 4: File Conflicts
+
+### Method
+
+Two tasks conflict if they both list the same file in "Files to Create or Modify" AND they are independent (no direct or transitive dependency relationship between them).
+
+### File-to-Task Mapping
+
+| File | Tasks |
+|---|---|
+| `defaults/config.json` | 001, 004, 005, 006 |
+| `scripts/config.sh` | 001 |
+| `scripts/state.sh` | 002 |
+| `scripts/git-utils.sh` | 003, 007 |
+| `scripts/agent.sh` | 004 |
+| `scripts/rebase.sh` | 005 |
+| `scripts/worktree.sh` | 006 |
+| `scripts/session-start.sh` | 008 |
+| `scripts/pre-commit.sh` | 009 |
+| `scripts/post-bash.sh` | 010 |
+| `scripts/post-write.sh` | 011 |
+| `scripts/session-stop.sh` | 012 |
+| `scripts/prompt-context.sh` | 013 |
+| `hooks/hooks.json` | 014 |
+| `skills/branch/SKILL.md` | 015 |
+| `skills/finish/SKILL.md` | 015 |
+| `skills/configure/SKILL.md` | 015 |
+| `skills/stash/SKILL.md` | 016 |
+| `skills/worktree/SKILL.md` | 016 |
+| `skills/rebase/SKILL.md` | 016 |
+| `CLAUDE.md` | 017 |
+| `.claude-plugin/plugin.json` | 018 |
+| `tests/*` | 019 |
+
+### Shared Files Analysis
+
+**`defaults/config.json`** -- Tasks 001, 004, 005, 006:
+- 004 depends on 001: OK (transitive)
+- 005 depends on 001: OK (transitive)
+- 006 depends on 001: OK (transitive)
+- 004 vs 005: 004 depends on 001, 002. 005 depends on 001, 003. No direct or transitive dependency between 004 and 005. **POTENTIAL CONFLICT.**
+- 004 vs 006: 004 depends on 001, 002. 006 depends on 001. No direct or transitive dependency between 004 and 006. **POTENTIAL CONFLICT.**
+- 005 vs 006: 005 depends on 001, 003. 006 depends on 001. No direct or transitive dependency between 005 and 006. **POTENTIAL CONFLICT.**
+
+However, examining the task details:
+- Task 001 adds the COMPLETE v2 `defaults/config.json` including all sections (rebase, worktree, agentTeams).
+- Tasks 004, 005, 006 each mention adding their respective config blocks to `defaults/config.json`.
+- Since task 001 already writes the complete schema, tasks 004, 005, 006 listing `defaults/config.json` is redundant -- their config keys are already present from task 001. This is a documentation inconsistency rather than a true conflict: if tasks 004, 005, 006 are implemented after 001 (which they depend on), the config.json changes are already done.
+
+**Verdict**: These are **logical conflicts** that need resolution. Tasks 004, 005, and 006 should either (a) remove `defaults/config.json` from their file lists since task 001 already writes the complete schema, or (b) be explicitly ordered relative to each other. Since they all depend on 001 which writes the complete file, the safest resolution is to remove `defaults/config.json` from tasks 004, 005, 006.
+
+**`scripts/git-utils.sh`** -- Tasks 003, 007:
+- 007 depends on 002. 003 depends on 001. No direct dependency between 003 and 007.
+- Checking transitive: 007 -> 002 -> 001. 003 -> 001. They share 001 as ancestor but no dependency path exists from 003 to 007 or vice versa. **POTENTIAL CONFLICT.**
+
+Examining the task details:
+- Task 003 adds `get_branch_tracking_status()`, `fetch_with_retry()`, `derive_branch_purpose()`, `is_detached_head()`.
+- Task 007 adds `auto_stash()`, `auto_restore_stash()`, `normalize_protect_default_branch()`.
+- These are different functions appended to the same file, so in practice they can be applied independently. But since they are truly independent tasks modifying the same file, this is a **valid conflict**.
+
+**Verdict**: Task 007 should depend on 003, or vice versa, to ensure ordered writes to `git-utils.sh`.
+
+### Conflicts Found
+
+| File | Conflicting Tasks | Severity | Recommendation |
+|---|---|---|---|
+| `defaults/config.json` | 004 vs 005, 004 vs 006, 005 vs 006 | LOW | Remove `defaults/config.json` from tasks 004, 005, 006 since task 001 already writes the complete v2 schema. The config keys are already present. |
+| `scripts/git-utils.sh` | 003 vs 007 | MEDIUM | Add dependency: 007 should depend on 003 (or 003 on 007) to serialize writes to `git-utils.sh`. Since task 009 already depends on both 001 and 007, and task 008 depends on 003, adding 003 as a dependency of 007 is the natural choice. |
+
+**Result: 2 conflict groups found (4 pairwise conflicts on config.json, 1 on git-utils.sh).**
+
+---
+
+## Summary
+
+| Check | Result | Issues |
+|---|---|---|
+| 1. Spec Coverage | **PASS** (with 1 minor note) | Task 008 missing explicit AC for agent suppression of freshness messages in session-start.sh |
+| 2. Valid DAG | **PASS** | No cycles, all dependencies exist, all slugs correct |
+| 3. Sizing Limits | **PASS** (with 1 exception) | Task 019 has 9 files (test suite -- justifiable exception) |
+| 4. File Conflicts | **FAIL** | 2 conflict groups: `defaults/config.json` (tasks 004/005/006 are independent but share file) and `scripts/git-utils.sh` (tasks 003/007 are independent but share file) |
+
+### Overall Verdict: **FAIL -- 2 issues require resolution before proceeding**
+
+#### Required Fixes
+
+1. **File conflict on `defaults/config.json`**: Remove `defaults/config.json` from the "Files to Create or Modify" lists of tasks 004, 005, and 006. Task 001 already writes the complete v2 config schema including all agentTeams, rebase, and worktree sections. The acceptance criteria mentioning "added to defaults/config.json" in tasks 004 (AC7), 005 (AC6), and 006 (AC7) should be changed to "present in defaults/config.json (written by task 001)".
+
+2. **File conflict on `scripts/git-utils.sh`**: Add `003-git-utils-extensions` as a dependency of task `007-stash-functions`. Both tasks append new functions to `git-utils.sh` and must be serialized. Since task 007 already depends on 002 (which depends on 001, same as 003), adding 003 introduces no cycle: 007 -> 003 -> 001.
+
+#### Advisory (Non-Blocking)
+
+3. **Task 008 agent suppression**: Consider adding an explicit acceptance criterion to task 008 for agent context handling in session-start.sh (freshness messages logged to state only, not emitted as systemMessages, per spec/04 section 1.5).
+
+4. **Task 019 file count**: The test suite task has 9 files. Consider splitting into 2-3 test tasks (e.g., unit tests vs integration tests) if strict adherence to the 3-4 file limit is required.
diff --git a/tasks/done/001-config-schema.md b/tasks/done/001-config-schema.md
new file mode 100644
index 0000000..d2e84ba
--- /dev/null
+++ b/tasks/done/001-config-schema.md
@@ -0,0 +1,76 @@
+# Task 001: Config Schema Update
+
+## Status
+done
+
+## Dependencies
+- None
+
+## Spec References
+- spec/01-config-and-state.md
+
+## Scope
+Update the plugin defaults config file (`defaults/config.json`) to include all new v2 config keys, and add the `normalize_protect_default_branch()` backward-compatibility function to `config.sh`. The existing three-tier merge logic (`load_config()`, `get_config()`) remains unchanged. This task makes the full v2 config schema available so that all downstream modules can call `get_config()` for new keys and receive correct defaults.
+
+## Acceptance Criteria
+- [x] `defaults/config.json` contains the complete v2 schema exactly as specified in spec Section 2, including all new top-level sections (`rebase`, `worktree`, `agentTeams`) and all new keys within existing sections (`git.autoFetch`, `git.fetchRetries`, `git.fetchRetryDelaySec`, `git.protectDefaultBranch` changed from `true` to `"warn"`, `branch.unrelatedWorkDetection`, `branch.autoStashOnSwitch`).
+- [x] `config.sh` exports `normalize_protect_default_branch()` with the exact case mapping: `true` -> `"warn"`, `false` -> `"off"`, `warn|block|off` -> pass-through, unknown -> `"warn"`.
+- [x] `load_config()` and `get_config()` functions in `config.sh` are unchanged (no modifications to merge logic).
+- [x] The existing v1 config file format (with `"protectDefaultBranch": true`) continues to work via the three-tier merge: v1 boolean values are not rejected by `jq`, and callers normalize via `normalize_protect_default_branch()`.
+- [x] The JSON in `defaults/config.json` is valid (parseable by `jq .`).
+
+## Implementation Notes
+
+### `defaults/config.json` -- full replacement
+
+Replace the entire file content with the v2 schema from spec Section 2. Key differences from v1:
+
+- `git.protectDefaultBranch`: change from `true` (boolean) to `"warn"` (string)
+- Add `git.autoFetch`: `true`
+- Add `git.fetchRetries`: `2`
+- Add `git.fetchRetryDelaySec`: `3`
+- Add `branch.unrelatedWorkDetection`: `true`
+- Add `branch.autoStashOnSwitch`: `true`
+- Add entire `rebase` section: `{ "autoRebaseBeforePush": true, "conflictStrategy": "prompt", "allowForcePush": "ask" }`
+- Add entire `worktree` section: `{ "enabled": true, "basePath": "../{{project}}-worktrees", "cleanupOnMerge": true }`
+- Add entire `agentTeams` section: `{ "suppressPromptsForAgents": true, "orchestratorOnly": ["push", "mr"] }`
+
+All existing v1 keys and their values remain unchanged (except `protectDefaultBranch`).
+
+The complete JSON is given verbatim in spec/01-config-and-state.md Section 2. Use it exactly (no JSONC comments in the actual file).
+
+### `config.sh` -- add `normalize_protect_default_branch()`
+
+Append the following function after the existing `get_config()` function:
+
+```bash
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
+```
+
+This function is called by downstream modules wherever `git.protectDefaultBranch` is read, like so:
+
+```bash
+raw_value=$(get_config "$config" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$raw_value")
+```
+
+The function itself does not call `get_config()` -- it only normalizes a value already retrieved.
+
+### Validation
+
+After editing, confirm the JSON is valid:
+```bash
+jq . plugins/git-pilot/defaults/config.json
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/defaults/config.json (modify)
+- plugins/git-pilot/scripts/config.sh (modify)
diff --git a/tasks/done/002-state-schema.md b/tasks/done/002-state-schema.md
new file mode 100644
index 0000000..dd6ae0d
--- /dev/null
+++ b/tasks/done/002-state-schema.md
@@ -0,0 +1,115 @@
+# Task 002: State Schema Extension
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (needs the v2 config schema so that `session-start.sh` can read `git.autoFetch` and other new keys via `get_config()` when calling `init_state()` with new arguments)
+
+## Spec References
+- spec/01-config-and-state.md
+
+## Scope
+Extend the session state library (`state.sh`) to support the v2 state schema. This means updating `init_state()` to accept five arguments (adding `base_branch` and `branch_purpose`), emitting all new fields in the initial state JSON, and updating `update_state()` to support extra `jq` arguments (e.g., `--arg key val`) passed before the filter. The `read_state()` function is also updated to validate JSON with a fallback.
+
+## Acceptance Criteria
+- [x] `init_state()` accepts 5 parameters: `session_id`, `working_branch?`, `previous_branch?`, `base_branch?`, `branch_purpose?`. Parameters 4-5 default to empty string when omitted.
+- [x] The initial state JSON produced by `init_state()` contains all v2 fields: `sessionId`, `startTime`, `workingBranch`, `previousBranch`, `headAtStart`, `baseBranch`, `branchPurpose`, `changeCount` (0), `lastCommitAt` (null), `modifiedFiles` ([]), `remoteSkipped` (false), `lastFetchAt` (null), `isAgent` (false), `agentRole` (null), `activeWorktrees` ([]), `stashRefs` ([]).
+- [x] `update_state()` supports variadic `jq` arguments: signature is `update_state state_file [jq_args...] jq_filter`, where all arguments after `state_file` are passed to `jq "$@"`.
+- [x] `read_state()` returns `{}` if the file is missing or if it contains invalid JSON.
+- [x] Calling `init_state()` with only 3 arguments (v1 style) still works correctly, with `baseBranch`, `branchPurpose` defaulting to empty strings and all new array/object fields initialized properly.
+- [x] `write_state()` and `cleanup_state()` are unchanged.
+
+## Implementation Notes
+
+### `init_state()` -- updated 5-argument signature
+
+Replace the current `init_state()` function body. The new version from spec Section 4.2:
+
+```bash
+init_state() {
+  local session_id="$1" working_branch="${2:-}" previous_branch="${3:-}"
+  local base_branch="${4:-}" branch_purpose="${5:-}"
+  local state_file head_at_start=""
+  state_file=$(get_state_file "$session_id")
+  if command -v git >/dev/null 2>&1 && git rev-parse HEAD >/dev/null 2>&1; then
+    head_at_start=$(git rev-parse HEAD 2>/dev/null || true)
+  fi
+  local content
+  content=$(jq -n \
+    --arg sid "$session_id" --arg start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg wb "$working_branch" --arg pb "$previous_branch" \
+    --arg head "$head_at_start" --arg bb "$base_branch" --arg bp "$branch_purpose" \
+    '{ sessionId:$sid, startTime:$start, workingBranch:$wb, previousBranch:$pb,
+       headAtStart:$head, baseBranch:$bb, branchPurpose:$bp, changeCount:0,
+       lastCommitAt:null, modifiedFiles:[], remoteSkipped:false, lastFetchAt:null,
+       isAgent:false, agentRole:null, activeWorktrees:[], stashRefs:[] }')
+  write_state "$state_file" "$content"
+}
+```
+
+Key changes from v1:
+- Two new local variables: `base_branch="${4:-}"` and `branch_purpose="${5:-}"`
+- Two new `--arg` flags to `jq -n`: `--arg bb "$base_branch"` and `--arg bp "$branch_purpose"`
+- Seven new fields in the JSON template: `baseBranch:$bb`, `branchPurpose:$bp`, `lastFetchAt:null`, `isAgent:false`, `agentRole:null`, `activeWorktrees:[]`, `stashRefs:[]`
+
+### `update_state()` -- variadic jq arguments
+
+Replace the current `update_state()` function. The v2 version uses `shift` to consume `state_file` and then passes all remaining arguments (`"$@"`) directly to `jq`:
+
+```bash
+update_state() {
+  local state_file="$1"; shift
+  local current; current=$(read_state "$state_file")
+  local updated; updated=$(echo "$current" | jq "$@")
+  write_state "$state_file" "$updated"
+}
+```
+
+This enables callers to pass `--arg` flags, for example:
+```bash
+update_state "$state_file" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.lastFetchAt = $ts'
+```
+
+The v1 signature `update_state state_file jq_filter` still works because `"$@"` with a single argument is just the filter string.
+
+### `read_state()` -- JSON validation guard
+
+Update `read_state()` to validate the content is valid JSON before returning it:
+
+```bash
+read_state() {
+  local state_file="$1"
+  if [[ -f "$state_file" ]]; then
+    local content
+    content=$(cat "$state_file")
+    if echo "$content" | jq empty 2>/dev/null; then
+      echo "$content"
+    else
+      echo "{}"
+    fi
+  else
+    echo "{}"
+  fi
+}
+```
+
+This ensures that a corrupted state file does not crash downstream `jq` pipelines.
+
+### Update function comment headers
+
+Update the comment for `init_state()` to document the 5-parameter signature:
+```bash
+# Creates the initial session state file.
+# Parameters: session_id, working_branch (optional), previous_branch (optional),
+#             base_branch (optional), branch_purpose (optional).
+```
+
+Update the comment for `update_state()`:
+```bash
+# Reads the current state, applies a jq filter, and atomically writes back.
+# Parameters: state_file, [jq_args...], jq_filter.
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/state.sh (modify)
diff --git a/tasks/done/003-git-utils-extensions.md b/tasks/done/003-git-utils-extensions.md
new file mode 100644
index 0000000..550cf15
--- /dev/null
+++ b/tasks/done/003-git-utils-extensions.md
@@ -0,0 +1,174 @@
+# Task 003: Git Utils Extensions
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (needs v2 config schema for `get_config()` calls reading `git.fetchRetries`, `git.fetchRetryDelaySec`, and `remote.defaultName`)
+
+## Spec References
+- spec/02-git-utils-and-network.md
+
+## Scope
+Add four new functions to `git-utils.sh`: `get_branch_tracking_status()` for branch freshness detection, `fetch_with_retry()` for network-resilient fetching with configurable retries, `derive_branch_purpose()` for extracting human-readable purpose from branch names, and `is_detached_head()` as a utility for detached HEAD detection. All existing v1 functions in the file remain unchanged.
+
+## Acceptance Criteria
+- [x] `get_branch_tracking_status()` accepts `branch` and `remote_name`, returns one of: `no-remote`, `up-to-date`, `behind:N`, `ahead:N`, `diverged:A:B` on stdout.
+- [x] `fetch_with_retry()` accepts `remote_name`, `config` (JSON string), and optional `specific_branch`. It reads `git.fetchRetries` (default `2`) and `git.fetchRetryDelaySec` (default `3`) from config via `get_config()`. Returns 0 on success, 1 after all retries exhausted (with last error on stderr).
+- [x] `derive_branch_purpose()` accepts a branch name string and returns the description portion with hyphens and underscores converted to spaces (e.g., `feat/add-dark-mode` -> `add dark mode`).
+- [x] `is_detached_head()` returns exit code 0 if HEAD is detached, 1 otherwise.
+- [x] All existing v1 functions (`is_git_repo`, `get_current_branch`, `has_uncommitted_changes`, `get_default_branch`, `is_on_default_branch`, `has_remote`, `sanitize_branch_name`) are unchanged.
+- [x] Retries in `fetch_with_retry()` are silent (no messages emitted during retry loop); only `last_error` is written to stderr on total failure.
+
+## Implementation Notes
+
+### `get_branch_tracking_status()` -- branch freshness
+
+Append to `git-utils.sh`. Full implementation from spec Section 1.2:
+
+```bash
+get_branch_tracking_status() {
+  local branch="$1"
+  local remote_name="$2"
+  local remote_branch="${remote_name}/${branch}"
+
+  # Check if remote branch exists
+  if ! git rev-parse --verify "$remote_branch" >/dev/null 2>&1; then
+    echo "no-remote"
+    return
+  fi
+
+  local local_ref remote_ref base_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "$remote_branch" 2>/dev/null)
+  base_ref=$(git merge-base "$branch" "$remote_branch" 2>/dev/null || true)
+
+  if [[ "$local_ref" == "$remote_ref" ]]; then
+    echo "up-to-date"
+  elif [[ "$local_ref" == "$base_ref" ]]; then
+    local behind_count
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "behind:${behind_count}"
+  elif [[ "$remote_ref" == "$base_ref" ]]; then
+    local ahead_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    echo "ahead:${ahead_count}"
+  else
+    local ahead_count behind_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "diverged:${ahead_count}:${behind_count}"
+  fi
+}
+```
+
+Return value format reference:
+
+| Return value | Meaning |
+|---|---|
+| `no-remote` | Remote tracking branch does not exist |
+| `up-to-date` | Local and remote refs are identical |
+| `behind:N` | Local is N commits behind remote |
+| `ahead:N` | Local is N commits ahead of remote |
+| `diverged:A:B` | Local is A ahead, B behind remote |
+
+### `fetch_with_retry()` -- network-resilient fetch
+
+Append to `git-utils.sh`. Full implementation from spec Section 2.1:
+
+```bash
+fetch_with_retry() {
+  local remote_name="$1"
+  local config="$2"
+  local specific_branch="${3:-}"
+
+  local max_retries
+  max_retries=$(get_config "$config" '.git.fetchRetries' '2')
+  local retry_delay
+  retry_delay=$(get_config "$config" '.git.fetchRetryDelaySec' '3')
+
+  local fetch_args="$remote_name"
+  if [[ -n "$specific_branch" ]]; then
+    fetch_args="$remote_name $specific_branch"
+  fi
+
+  local attempt=0
+  local last_error=""
+
+  while (( attempt <= max_retries )); do
+    if git fetch $fetch_args 2>/dev/null; then
+      return 0
+    fi
+
+    last_error=$(git fetch $fetch_args 2>&1 || true)
+    attempt=$((attempt + 1))
+
+    if (( attempt <= max_retries )); then
+      sleep "$retry_delay"
+    fi
+  done
+
+  # All retries exhausted
+  echo "$last_error" >&2
+  return 1
+}
+```
+
+Important: `fetch_args` is intentionally unquoted in `git fetch $fetch_args` so that word splitting separates remote name and branch. The `get_config()` function is defined in `config.sh` which is sourced before `git-utils.sh` by all hook scripts.
+
+Retry behavior:
+- Attempt 0 is the initial try; up to `max_retries` additional attempts follow.
+- `sleep "$retry_delay"` is called between attempts (not after the last failure).
+- Retries are silent -- no systemMessage emitted during the loop.
+- On total failure, `last_error` (stderr from the last `git fetch`) is written to stderr and function returns 1.
+
+### `derive_branch_purpose()` -- human-readable branch purpose
+
+Append to `git-utils.sh`. From spec Section 6.1:
+
+```bash
+derive_branch_purpose() {
+  local branch_name="$1"
+
+  # Strip type prefix (e.g., "feat/", "fix/")
+  local description
+  description=$(echo "$branch_name" | sed 's|^[^/]*/||')
+
+  # Convert kebab-case/snake_case to words
+  description=$(echo "$description" | tr '-' ' ' | tr '_' ' ')
+
+  echo "$description"
+}
+```
+
+Examples from spec:
+
+| Branch name | Output |
+|---|---|
+| `feat/add-dark-mode` | `add dark mode` |
+| `fix/login-timeout` | `login timeout` |
+| `refactor/extract_utils` | `extract utils` |
+| `main` | `main` (no `/` to split on, `sed` leaves it unchanged) |
+
+### `is_detached_head()` -- detached HEAD check
+
+Append to `git-utils.sh`:
+
+```bash
+is_detached_head() {
+  [[ -z "$(git branch --show-current 2>/dev/null)" ]] && git rev-parse HEAD >/dev/null 2>&1
+}
+```
+
+Returns exit code 0 if HEAD is detached (no current branch name but HEAD is valid), 1 otherwise. This is used by `session-start.sh` to detect detached HEAD state and skip branch-related workflows.
+
+### Ordering of new functions
+
+Append all four functions after the existing `sanitize_branch_name()` at the end of the file, separated by blank lines, in this order:
+1. `is_detached_head()`
+2. `get_branch_tracking_status()`
+3. `fetch_with_retry()`
+4. `derive_branch_purpose()`
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/git-utils.sh (modify)
diff --git a/tasks/done/004-agent-library.md b/tasks/done/004-agent-library.md
new file mode 100644
index 0000000..177770f
--- /dev/null
+++ b/tasks/done/004-agent-library.md
@@ -0,0 +1,130 @@
+# Task 004: Agent Detection Library
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (needs `get_config()` for `agentTeams.suppressPromptsForAgents` and `agentTeams.orchestratorOnly` config keys)
+- 002-state-schema (needs `get_state_file()`, `read_state()`, `update_state()` for reading the `isAgent` and `agentRole` session state fields)
+
+## Spec References
+- spec/04-agent-and-worktree.md (sections 1.1 through 1.6)
+
+## Scope
+Implement `scripts/agent.sh` containing two core detection functions: `is_agent_context()` (detects whether the current session is a spawned agent via `CLAUDE_SPAWNED_BY` env var or session state `.isAgent` field) and `is_operation_agent_restricted()` (checks whether a named operation should be suppressed for agents based on `agentTeams.suppressPromptsForAgents` and `agentTeams.orchestratorOnly` config keys). This task does NOT modify existing hook scripts (that is integration work for a later task); it provides the library functions those hooks will source.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/scripts/agent.sh` exists, starts with `#!/usr/bin/env bash` and `set -euo pipefail`, sources `state.sh` from the same directory
+- [x] `is_agent_context()` returns 0 when `CLAUDE_SPAWNED_BY` env var is non-empty (primary detection)
+- [x] `is_agent_context()` returns 0 when session state `.isAgent == true` (fallback detection via `get_state_file` + `read_state` + jq)
+- [x] `is_agent_context()` returns 1 when neither condition is met
+- [x] `is_operation_agent_restricted()` returns 0 (restricted) when `agentTeams.suppressPromptsForAgents` is `true` AND the operation name appears in `agentTeams.orchestratorOnly` array
+- [x] `is_operation_agent_restricted()` returns 1 (not restricted) when `agentTeams.suppressPromptsForAgents` is `false` or the operation is not in the `orchestratorOnly` list
+- [x] Config keys `agentTeams.suppressPromptsForAgents` and `agentTeams.orchestratorOnly` are read via `get_config()` (already defined in `defaults/config.json` by task 001)
+
+## Implementation Notes
+
+### File: `plugins/git-pilot/scripts/agent.sh`
+
+Source `state.sh` for access to `get_state_file()` and `read_state()`. Source `config.sh` for `get_config()`.
+
+**`is_agent_context()` function** (spec section 1.1):
+```bash
+is_agent_context() {
+  # Primary: check Claude Code spawned-by indicator
+  if [[ -n "${CLAUDE_SPAWNED_BY:-}" ]]; then
+    return 0
+  fi
+
+  # Secondary: check for agent role in session state
+  local session_id="${1:-}"
+  if [[ -n "$session_id" ]]; then
+    local state_file
+    state_file=$(get_state_file "$session_id")
+    local state
+    state=$(read_state "$state_file")
+    local is_agent
+    is_agent=$(echo "$state" | jq -r '.isAgent // false')
+    if [[ "$is_agent" == "true" ]]; then
+      return 0
+    fi
+  fi
+
+  return 1
+}
+```
+
+Parameters:
+- `$1` (optional): session ID for state-file fallback
+
+Detection order:
+1. `CLAUDE_SPAWNED_BY` env var non-empty (primary, set by Claude Code)
+2. Session state `.isAgent == true` (fallback for resilience)
+
+**`is_operation_agent_restricted()` function** (spec section 1.2):
+```bash
+is_operation_agent_restricted() {
+  local config="$1"
+  local operation="$2"  # "push", "mr", "branch-prompt", etc.
+
+  local suppress
+  suppress=$(get_config "$config" '.agentTeams.suppressPromptsForAgents' 'true')
+
+  if [[ "$suppress" != "true" ]]; then
+    return 1  # Not suppressed
+  fi
+
+  # Check if this specific operation is orchestrator-only
+  local restricted
+  restricted=$(echo "$config" | jq -r --arg op "$operation" \
+    '.agentTeams.orchestratorOnly // ["push", "mr"] | map(select(. == $op)) | length')
+
+  if [[ "$restricted" -gt 0 ]]; then
+    return 0  # Restricted to orchestrator
+  fi
+
+  return 1
+}
+```
+
+Parameters:
+- `$1`: config JSON (the merged config object from `load_config()`)
+- `$2`: operation name string -- one of `"push"`, `"mr"`, `"branch-prompt"`, `"auto-commit"`, `"rebase"`, `"session-summary"`, `"branch-freshness"`
+
+The jq filter `.agentTeams.orchestratorOnly // ["push", "mr"]` provides the default array inline, so if the key is missing the defaults apply.
+
+### Prompt suppression pattern (for reference -- hooks will use this in later tasks):
+```bash
+if is_agent_context "$SESSION_ID" && \
+   is_operation_agent_restricted "$CONFIG" "push"; then
+  echo '{"continue": true}'
+  exit 0
+fi
+```
+
+### Operations and agent behavior table (spec section 1.6):
+
+| Operation | Orchestrator | Agent |
+|-----------|-------------|-------|
+| Branch creation prompt | Interactive | Suppressed |
+| Push prompt after commit | Interactive | Suppressed |
+| MR creation | Interactive | Suppressed |
+| Commit validation | Active | Active |
+| Auto-commit suggestions | Active | Suppressed |
+| Rebase/conflict prompts | Interactive | Suppressed (abort rebase silently) |
+| Session summary | Active | Suppressed |
+| Branch freshness warnings | Active | Log to state only (no prompt) |
+
+### Config keys (defined in `defaults/config.json` by task 001):
+Config keys are already defined in `defaults/config.json` by task 001. This task only needs to READ them via `get_config()`.
+```json
+{
+  "agentTeams": {
+    "suppressPromptsForAgents": true,
+    "orchestratorOnly": ["push", "mr"]
+  }
+}
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/agent.sh (new)
diff --git a/tasks/done/005-rebase-library.md b/tasks/done/005-rebase-library.md
new file mode 100644
index 0000000..a5e0d07
--- /dev/null
+++ b/tasks/done/005-rebase-library.md
@@ -0,0 +1,249 @@
+# Task 005: Rebase Library
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (needs `get_config()` for `rebase.autoRebaseBeforePush`, `rebase.conflictStrategy`, `rebase.allowForcePush`, and `git.defaultBranch` config keys)
+- 003-git-utils-extensions (needs `get_branch_tracking_status()`, `fetch_with_retry()`, `has_uncommitted_changes()` from `scripts/git-utils.sh`)
+
+## Spec References
+- spec/03-rebase-and-conflicts.md (sections 1 through 5)
+
+## Scope
+Implement `scripts/rebase.sh` containing four functions: `get_base_branch_drift()` (detects how many commits the base branch has advanced since the feature branch diverged), `attempt_rebase()` (performs a rebase onto a target branch with clean error categorization), `get_conflict_details()` (returns a JSON array of conflicting files with type and region count), and `needs_force_push()` (detects whether a force push is required after rebase). Also adds the `rebase.*` default config keys. This task does NOT wire these functions into hook scripts; it provides the library that hooks will call.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/scripts/rebase.sh` exists, starts with `#!/usr/bin/env bash` and `set -euo pipefail`, sources `git-utils.sh` and `config.sh` from the same directory
+- [x] `get_base_branch_drift()` returns `no-drift`, `drifted:N`, or `no-common-ancestor` with correct exit codes
+- [x] `attempt_rebase()` returns `success` (exit 0), `conflict` (exit 1), `error:dirty-worktree` (exit 1), or `error:<output>` (exit 1)
+- [x] `get_conflict_details()` returns a JSON array with objects containing `file` (string), `type` (one of `both-modified`, `deleted-by-us`, `deleted-by-them`), and `conflictRegions` (integer)
+- [x] `needs_force_push()` returns 0 when remote tracking branch exists, refs differ, and remote is not an ancestor of local; returns 1 otherwise
+- [x] Config keys `rebase.autoRebaseBeforePush`, `rebase.conflictStrategy`, and `rebase.allowForcePush` are read via `get_config()` (already defined in `defaults/config.json` by task 001)
+- [x] A helper function `get_conflict_recommendation()` returns the correct recommendation string per conflict type and region count
+
+## Implementation Notes
+
+### File: `plugins/git-pilot/scripts/rebase.sh`
+
+Source `git-utils.sh` (for `has_uncommitted_changes()`) and `config.sh` (for `get_config()`).
+
+**`get_base_branch_drift()` function** (spec section 1.1):
+```bash
+get_base_branch_drift() {
+  local current_branch="$1"
+  local base_branch="$2"
+  local remote_name="$3"
+  local remote_base="${remote_name}/${base_branch}"
+
+  # Fetch latest base branch state
+  git fetch "$remote_name" "$base_branch" 2>/dev/null || return 1
+
+  # Find the merge base between current branch and remote base
+  local merge_base
+  merge_base=$(git merge-base "$current_branch" "$remote_base" 2>/dev/null || true)
+
+  if [[ -z "$merge_base" ]]; then
+    echo "no-common-ancestor"
+    return
+  fi
+
+  # Count commits on base branch since the branch point
+  local drift_count
+  drift_count=$(git rev-list --count "${merge_base}..${remote_base}" 2>/dev/null)
+
+  if [[ "$drift_count" -eq 0 ]]; then
+    echo "no-drift"
+  else
+    echo "drifted:${drift_count}"
+  fi
+}
+```
+
+Parameters: `$1` = current branch name, `$2` = base branch name, `$3` = remote name.
+Return values: `no-drift` | `drifted:N` | `no-common-ancestor`.
+
+**Base branch determination** (spec section 1.3) -- callers resolve the base branch in this order:
+1. Session state `baseBranch` field
+2. `git config branch.${current}.merge` stripped of `refs/heads/`
+3. `git.defaultBranch` from config (default: `"main"`)
+
+**`attempt_rebase()` function** (spec section 2.1):
+```bash
+attempt_rebase() {
+  local target_branch="$1"  # Branch to rebase onto (e.g., origin/main)
+
+  # Ensure clean working tree
+  if has_uncommitted_changes; then
+    echo "error:dirty-worktree"
+    return 1
+  fi
+
+  # Attempt rebase
+  local rebase_output
+  if rebase_output=$(git rebase "$target_branch" 2>&1); then
+    echo "success"
+    return 0
+  else
+    # Check if it's a conflict
+    if git diff --name-only --diff-filter=U 2>/dev/null | head -1 | grep -q .; then
+      echo "conflict"
+      return 1
+    else
+      echo "error:${rebase_output}"
+      return 1
+    fi
+  fi
+}
+```
+
+Parameters: `$1` = target branch to rebase onto (e.g., `origin/main`).
+Return values: `success` (exit 0) | `conflict` (exit 1) | `error:dirty-worktree` (exit 1) | `error:<output>` (exit 1).
+
+**`get_conflict_details()` function** (spec section 2.2):
+```bash
+get_conflict_details() {
+  local conflict_files
+  conflict_files=$(git diff --name-only --diff-filter=U 2>/dev/null)
+
+  if [[ -z "$conflict_files" ]]; then
+    echo "[]"
+    return
+  fi
+
+  local result="["
+  local first=true
+
+  while IFS= read -r file; do
+    local ours_exists theirs_exists
+    ours_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 2" | wc -l | tr -d ' ')
+    theirs_exists=$(git ls-files --stage "$file" 2>/dev/null | grep "^[0-9]* [a-f0-9]* 3" | wc -l | tr -d ' ')
+
+    local conflict_type="both-modified"
+    if [[ "$ours_exists" == "0" ]]; then
+      conflict_type="deleted-by-us"
+    elif [[ "$theirs_exists" == "0" ]]; then
+      conflict_type="deleted-by-them"
+    fi
+
+    local marker_count=0
+    if [[ -f "$file" ]]; then
+      marker_count=$(grep -c '^<<<<<<< ' "$file" 2>/dev/null || echo "0")
+    fi
+
+    if [[ "$first" == "true" ]]; then
+      first=false
+    else
+      result+=","
+    fi
+    result+=$(jq -n \
+      --arg f "$file" \
+      --arg t "$conflict_type" \
+      --argjson m "$marker_count" \
+      '{file: $f, type: $t, conflictRegions: $m}')
+  done <<< "$conflict_files"
+
+  result+="]"
+  echo "$result"
+}
+```
+
+Output JSON schema:
+```json
+[
+  {"file": "src/auth.ts", "type": "both-modified", "conflictRegions": 2},
+  {"file": "src/utils.ts", "type": "deleted-by-us", "conflictRegions": 0}
+]
+```
+
+Conflict type detection (spec section 2.2): stage 2 = "ours", stage 3 = "theirs" in `git ls-files --stage`. If stage 2 count is 0: `deleted-by-us`. If stage 3 count is 0: `deleted-by-them`. Otherwise: `both-modified`.
+
+**`get_conflict_recommendation()` helper** (spec section 2.4):
+```bash
+get_conflict_recommendation() {
+  local conflict_type="$1"
+  local regions="$2"
+
+  case "$conflict_type" in
+    deleted-by-us)
+      echo "File was deleted locally but modified on base. If the deletion was intentional, accept ours (delete). Otherwise, accept theirs." ;;
+    deleted-by-them)
+      echo "File was deleted on base but modified locally. If your changes are still needed, accept ours. Otherwise, accept theirs (delete)." ;;
+    both-modified)
+      if [[ "$regions" -le 1 ]]; then
+        echo "Single conflict region -- likely a small overlap. Manual review recommended."
+      elif [[ "$regions" -gt 3 ]]; then
+        echo "Multiple conflict regions -- significant concurrent changes. Manual review required."
+      else
+        echo "Manual review recommended."
+      fi
+      ;;
+  esac
+}
+```
+
+**`needs_force_push()` function** (spec section 3.1):
+```bash
+needs_force_push() {
+  local branch="$1"
+  local remote_name="$2"
+
+  # Check if remote tracking branch exists
+  if ! git rev-parse --verify "${remote_name}/${branch}" >/dev/null 2>&1; then
+    return 1  # No remote branch, normal push works
+  fi
+
+  # Check if local and remote have diverged after rebase
+  local local_ref remote_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "${remote_name}/${branch}" 2>/dev/null)
+
+  if [[ "$local_ref" != "$remote_ref" ]]; then
+    # Check if remote is NOT an ancestor of local (diverged, not just ahead)
+    if ! git merge-base --is-ancestor "$remote_ref" "$local_ref" 2>/dev/null; then
+      return 0  # Needs force push
+    fi
+  fi
+
+  return 1
+}
+```
+
+Returns 0 (needs force push) when: (1) remote tracking branch exists AND (2) local and remote refs differ AND (3) remote ref is NOT an ancestor of local ref. Returns 1 otherwise.
+
+**`rebase.conflictStrategy` handling** (spec section 2.5) -- callers use this logic:
+
+| Strategy | Behavior |
+|----------|----------|
+| `"prompt"` | Emit conflict details and prompt user (default) |
+| `"abort"` | `git rebase --abort`. Emit: `"[git-pilot] Rebase aborted due to conflicts. Push without rebase."` |
+| `"merge-fallback"` | `git rebase --abort && git merge ${target}`. If merge also conflicts, fall back to `"prompt"` |
+
+**`rebase.allowForcePush` handling** (spec section 3.2) -- callers use this logic:
+
+| Setting | Behavior |
+|---------|----------|
+| `"ask"` | Emit: `"[git-pilot] Rebase rewrote history. Force push required. Prompt the user: force push (git push --force-with-lease) or abort."` |
+| `"never"` | Emit: `"[git-pilot] Rebase rewrote history but force push is disabled. The rebase changes are local only. Push manually if needed."` |
+| `"always"` | `git push --force-with-lease` automatically. Emit: `"[git-pilot] Force-pushed '${branch}' to '${remote}/${branch}' after rebase."` |
+
+Always use `--force-with-lease` (never bare `--force`).
+
+### Config keys (defined in `defaults/config.json` by task 001):
+Config keys are already defined in `defaults/config.json` by task 001. This task only needs to READ them via `get_config()`.
+```json
+{
+  "rebase": {
+    "autoRebaseBeforePush": true,
+    "conflictStrategy": "prompt",
+    "allowForcePush": "ask"
+  }
+}
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/rebase.sh (new)
+
+## Validation Notes
+
+**PASS**: All acceptance criteria met. Source statements for `config.sh` and `git-utils.sh` added with `SCRIPT_DIR` definition, matching the pattern in `agent.sh` and `worktree.sh`. Verified with `bash -n` and `shellcheck --severity=warning`.
diff --git a/tasks/done/006-worktree-library.md b/tasks/done/006-worktree-library.md
new file mode 100644
index 0000000..c597853
--- /dev/null
+++ b/tasks/done/006-worktree-library.md
@@ -0,0 +1,220 @@
+# Task 006: Worktree Library
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (needs `get_config()` for `worktree.enabled`, `worktree.basePath`, `worktree.cleanupOnMerge` config keys)
+
+## Spec References
+- spec/04-agent-and-worktree.md (sections 2.1 through 2.8)
+
+## Scope
+Implement `scripts/worktree.sh` containing four public functions (`create_worktree()`, `remove_worktree()`, `list_worktrees()`, `merge_worktree_branch()`) and two internal registry functions (`register_worktree()`, `unregister_worktree()`). The registry is a JSON file at `$(git rev-parse --git-dir)/git-pilot-worktrees.json` with atomic write semantics. Also adds the `worktree.*` default config keys. This task does NOT integrate worktree calls into session hooks or agent orchestration; it provides the standalone library.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/scripts/worktree.sh` exists, starts with `#!/usr/bin/env bash` and `set -euo pipefail`, sources `config.sh` from the same directory
+- [x] `create_worktree()` creates a git worktree at the resolved path (replacing `{{project}}` placeholder and sanitizing `/` to `-` in branch names), registers it, and echoes the worktree path on success
+- [x] `create_worktree()` returns exit code 1 and writes `error:<output>` to stderr on failure
+- [x] `remove_worktree()` removes the worktree (with optional `--force` flag) and unregisters it from the registry
+- [x] `list_worktrees()` returns the full registry JSON (`{"worktrees": [...]}`) or `{"worktrees":[]}` if no registry file exists
+- [x] `merge_worktree_branch()` merges the worktree branch into the target branch, and if `worktree.cleanupOnMerge` is `true`, removes the worktree and deletes the branch
+- [x] Config keys `worktree.enabled`, `worktree.basePath`, and `worktree.cleanupOnMerge` are read via `get_config()` (already defined in `defaults/config.json` by task 001)
+
+## Implementation Notes
+
+### File: `plugins/git-pilot/scripts/worktree.sh`
+
+Source `config.sh` (for `get_config()`). Define `WORKTREE_REGISTRY` at module scope:
+```bash
+WORKTREE_REGISTRY="$(git rev-parse --git-dir 2>/dev/null)/git-pilot-worktrees.json"
+```
+
+Use `git rev-parse --git-dir` instead of hardcoded `.git` -- this is critical for correctness inside worktree contexts where `.git` is a file, not a directory.
+
+**`create_worktree()` function** (spec section 2.2):
+```bash
+create_worktree() {
+  local config="$1"
+  local branch_name="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local project_name
+  project_name=$(basename "$(git rev-parse --show-toplevel)")
+
+  local base_path
+  base_path=$(get_config "$config" '.worktree.basePath' "../{{project}}-worktrees")
+  base_path="${base_path//\{\{project\}\}/$project_name}"
+
+  local dir_name
+  dir_name=$(echo "$branch_name" | tr '/' '-')
+  local worktree_path="${base_path}/${dir_name}"
+
+  mkdir -p "$(dirname "$worktree_path")"
+
+  local output
+  if output=$(git worktree add "$worktree_path" -b "$branch_name" "$base_branch" 2>&1); then
+    register_worktree "$worktree_path" "$branch_name" "$base_branch" "$session_id"
+    echo "$worktree_path"
+    return 0
+  else
+    echo "error:${output}" >&2
+    return 1
+  fi
+}
+```
+
+Parameters: `$1` = config JSON, `$2` = branch name, `$3` = base branch to create from, `$4` = session ID (optional).
+Returns: echoes the absolute worktree path on stdout on success. On failure, writes `error:<git output>` to stderr.
+
+Error message pattern for callers: `"[git-pilot] Worktree creation failed: branch 'feat/auth' already exists. Use a different name or delete the existing branch."`
+
+The `{{project}}` placeholder in `basePath` is replaced with `$(basename "$(git rev-parse --show-toplevel)")`. Branch name `/` characters are replaced with `-` for directory names (e.g., `feat/auth` becomes `feat-auth`).
+
+**`remove_worktree()` function** (spec section 2.3):
+```bash
+remove_worktree() {
+  local worktree_path="$1"
+  local force="${2:-false}"
+
+  local flags=""
+  if [[ "$force" == "true" ]]; then
+    flags="--force"
+  fi
+
+  if git worktree remove "$worktree_path" $flags 2>/dev/null; then
+    unregister_worktree "$worktree_path"
+    return 0
+  else
+    return 1
+  fi
+}
+```
+
+Parameters: `$1` = worktree path, `$2` = "true" for force removal (optional, default "false").
+Note: `$flags` is intentionally unquoted to allow word splitting when `--force` is set and to be empty (no argument) when not.
+
+**`register_worktree()` function** (spec section 2.4):
+```bash
+register_worktree() {
+  local path="$1"
+  local branch="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local registry
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    registry=$(cat "$WORKTREE_REGISTRY")
+  else
+    registry='{"worktrees":[]}'
+  fi
+
+  local entry
+  entry=$(jq -n \
+    --arg p "$path" \
+    --arg b "$branch" \
+    --arg bb "$base_branch" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg sid "$session_id" \
+    '{path:$p, branch:$b, baseBranch:$bb, createdAt:$ts, createdBy:$sid, status:"active"}')
+
+  registry=$(echo "$registry" | jq --argjson e "$entry" '.worktrees += [$e]')
+
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+```
+
+Registry file: `$(git rev-parse --git-dir)/git-pilot-worktrees.json`.
+Entry schema: `{path, branch, baseBranch, createdAt, createdBy, status}`.
+All writes use atomic temp-file + `mv` pattern (same as state.sh).
+
+**`unregister_worktree()` function** (spec section 2.4):
+```bash
+unregister_worktree() {
+  local path="$1"
+  if [[ ! -f "$WORKTREE_REGISTRY" ]]; then
+    return
+  fi
+  local registry
+  registry=$(cat "$WORKTREE_REGISTRY")
+  registry=$(echo "$registry" | jq --arg p "$path" \
+    '.worktrees = [.worktrees[] | select(.path != $p)]')
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+```
+
+jq filter: `.worktrees = [.worktrees[] | select(.path != $p)]` -- removes the entry matching the path.
+
+**`list_worktrees()` function** (spec section 2.4):
+```bash
+list_worktrees() {
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    cat "$WORKTREE_REGISTRY"
+  else
+    echo '{"worktrees":[]}'
+  fi
+}
+```
+
+Returns the full JSON registry or an empty-list structure.
+
+**`merge_worktree_branch()` function** (spec section 2.5):
+```bash
+merge_worktree_branch() {
+  local worktree_path="$1"
+  local target_branch="$2"
+  local config="$3"
+
+  local wt_branch
+  wt_branch=$(git -C "$worktree_path" branch --show-current 2>/dev/null)
+
+  if [[ -z "$wt_branch" ]]; then
+    echo "error:cannot-determine-branch"
+    return 1
+  fi
+
+  git checkout "$target_branch" 2>/dev/null || return 1
+
+  local merge_output
+  if merge_output=$(git merge "$wt_branch" --no-edit 2>&1); then
+    echo "success"
+    local cleanup
+    cleanup=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+    if [[ "$cleanup" == "true" ]]; then
+      remove_worktree "$worktree_path" "false"
+      git branch -d "$wt_branch" 2>/dev/null || true
+    fi
+    return 0
+  else
+    echo "conflict"
+    return 1
+  fi
+}
+```
+
+Parameters: `$1` = worktree path, `$2` = target branch to merge into, `$3` = config JSON.
+Return values: `success` (exit 0) | `conflict` (exit 1) | `error:cannot-determine-branch` (exit 1).
+
+On success with `worktree.cleanupOnMerge == true`: removes the worktree via `remove_worktree()` and deletes the branch with `git branch -d`.
+
+### Invariants (spec section 2.7):
+- Half-created worktrees MUST be cleaned up. Every function that starts a multi-step git operation must have cleanup logic in its error path.
+- Required: `git` >= 2.30, `jq` >= 1.6.
+
+### Config keys (defined in `defaults/config.json` by task 001):
+Config keys are already defined in `defaults/config.json` by task 001. This task only needs to READ them via `get_config()`.
+```json
+{
+  "worktree": {
+    "enabled": true,
+    "basePath": "../{{project}}-worktrees",
+    "cleanupOnMerge": true
+  }
+}
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/worktree.sh (new)
diff --git a/tasks/done/007-stash-functions.md b/tasks/done/007-stash-functions.md
new file mode 100644
index 0000000..3e71f2c
--- /dev/null
+++ b/tasks/done/007-stash-functions.md
@@ -0,0 +1,99 @@
+# Task 007: Stash Functions
+
+## Status
+done
+
+## Dependencies
+- 002-state-schema (stash refs stored in session state as `stashRefs` array; uses `get_state_file()`, `read_state()`, `update_state()`)
+- 003-git-utils-extensions (appends functions to same git-utils.sh file)
+
+## Spec References
+- spec/05-stash-and-robustness.md (sections 1.1-1.5, 1.9)
+
+## Scope
+Implement `auto_stash()` and `auto_restore_stash()` functions in `scripts/git-utils.sh`. These functions manage automatic stashing and restoring of uncommitted changes during branch switches, with stash metadata tracked in the session state file's `stashRefs` array.
+
+## Acceptance Criteria
+- [x] `auto_stash()` accepts `current_branch` and `session_id`, returns 1 if nothing to stash, 0 on success
+- [x] `auto_stash()` calls `git stash push -m "git-pilot auto-stash on ${current_branch}"` and records the ref in session state via `update_state` with jq filter `.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]`
+- [x] `auto_restore_stash()` accepts `target_branch` and `session_id`, looks up stash by branch in state using jq, finds current index via `git stash list` grep on message, and pops it
+- [x] On successful pop, `auto_restore_stash()` removes the entry from state with `.stashRefs = [.stashRefs[] | select(.branch != $branch)]`
+- [x] `auto_restore_stash()` returns 1 if no stash found for branch or if session_id is empty
+- [x] Stash data is never lost: `git stash pop` preserves the stash on conflict (atomic apply+drop)
+- [x] `normalize_protect_default_branch()` function is added to handle boolean-to-string migration for `git.protectDefaultBranch` config key
+
+## Implementation Notes
+
+### `auto_stash(current_branch, session_id)`
+
+```bash
+auto_stash() {
+  local current_branch="$1"
+  local session_id="$2"
+
+  if ! has_uncommitted_changes; then
+    return 1  # Nothing to stash
+  fi
+
+  local stash_msg="git-pilot auto-stash on ${current_branch}"
+  if git stash push -m "$stash_msg" >/dev/null 2>&1; then
+    local stash_ref
+    stash_ref=$(git stash list --format='%gd' | head -1)
+
+    if [[ -n "$session_id" ]]; then
+      local state_file
+      state_file=$(get_state_file "$session_id")
+      update_state "$state_file" \
+        --arg ref "$stash_ref" \
+        --arg branch "$current_branch" \
+        --arg msg "$stash_msg" \
+        '.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]'
+    fi
+    return 0
+  fi
+  return 1
+}
+```
+
+**Note**: The current v1 `update_state()` in `state.sh` only accepts 2 arguments (`state_file`, `jq_filter`). This function passes `--arg` flags, so `update_state()` must be extended (in task 002) to support variadic jq arguments before the filter. The call pattern is: `update_state "$state_file" --arg key val --arg key2 val2 'jq_filter'`. If task 002 is not yet complete, implement the call using inline jq instead:
+```bash
+local state_file; state_file=$(get_state_file "$session_id")
+local current; current=$(read_state "$state_file")
+local updated; updated=$(echo "$current" | jq \
+  --arg ref "$stash_ref" --arg branch "$current_branch" --arg msg "$stash_msg" \
+  '.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]')
+write_state "$state_file" "$updated"
+```
+
+### `auto_restore_stash(target_branch, session_id)`
+
+Lookup stash ref and message from state by branch using jq:
+```bash
+stash_ref=$(echo "$state" | jq -r --arg branch "$target_branch" \
+  '.stashRefs[] | select(.branch == $branch) | .ref' | head -1)
+stash_msg=$(echo "$state" | jq -r --arg branch "$target_branch" \
+  '.stashRefs[] | select(.branch == $branch) | .message' | head -1)
+```
+
+Then find current index: `git stash list --format='%gd %s' | grep "$stash_msg" | head -1 | cut -d' ' -f1`
+
+Known limitation: stash-by-message lookup is fragile if user manually creates stashes with `"git-pilot auto-stash on "` prefix.
+
+### `normalize_protect_default_branch(value)`
+
+```bash
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
+```
+
+This handles v1 boolean -> v2 string enum migration. Called wherever `git.protectDefaultBranch` is read.
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/git-utils.sh (modify -- add `auto_stash()`, `auto_restore_stash()`, `normalize_protect_default_branch()`)
diff --git a/tasks/done/008-hook-session-start.md b/tasks/done/008-hook-session-start.md
new file mode 100644
index 0000000..080a1d6
--- /dev/null
+++ b/tasks/done/008-hook-session-start.md
@@ -0,0 +1,111 @@
+# Task 008: Hook session-start.sh Modifications
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (uses `get_config()` for `.git.autoFetch`, `.git.fetchRetries`, `.remote.defaultName`, `.branch.unrelatedWorkDetection`)
+- 002-state-schema (uses `init_state()` with extended 5-arg signature: `session_id`, `current_branch`, `previous_branch`, `base_branch`, `branch_purpose`)
+- 003-git-utils-extensions (uses `fetch_with_retry()`, `get_branch_tracking_status()`, `derive_branch_purpose()`, `has_remote()`)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (sections 3a, 3b, 3c, 3d)
+- spec/05-stash-and-robustness.md (section 2 -- detached HEAD recovery)
+
+## Scope
+Modify the existing `session-start.sh` script to add four new capabilities after the git init check: (a) remote fetch with retry, (b) branch freshness check with fast-forward or divergence messaging, (c) detached HEAD detection and recovery prompting, and (d) extended session state initialization with `baseBranch` and `branchPurpose` fields.
+
+## Acceptance Criteria
+- [x] After git init check (Step 6) and before branch detection (Step 7), fetch remote when `git.autoFetch` is `true` using `fetch_with_retry()`; emit warning on failure: `"[git-pilot] Warning: Could not fetch from '${remote_name}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync."`
+- [x] After getting `current_branch`, check tracking status via `get_branch_tracking_status()` and emit appropriate messages for `behind:*` (attempt fast-forward), `diverged:*:*`, and `ahead:*` states
+- [x] When `get_current_branch` returns empty, detect detached HEAD: look up previous branch via `git reflog show --format='%gs' | grep -m1 'checkout: moving from'`; emit 3-option message if previous branch found, 2-option if not
+- [x] Extended `init_state` call passes 5 arguments: `session_id`, `current_branch`, `previous_branch`, `base_branch`, `branch_purpose`; `base_branch` defaults to `default_branch` but checks `git config "branch.${current_branch}.merge"` for configured base
+- [x] `derive_branch_purpose()` is called for non-default branches to populate `branchPurpose`
+- [x] All new blocks are guarded by `is_git_repo` (and `has_remote` where network is needed)
+
+## Implementation Notes
+
+### 3a. Fetch remote -- insert after Step 6 (git init check), before Step 7 (branch detection)
+
+```bash
+if is_git_repo && has_remote; then
+  auto_fetch=$(get_config "$CONFIG" '.git.autoFetch' 'true')
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  if [[ "$auto_fetch" == "true" ]]; then
+    retries=$(get_config "$CONFIG" '.git.fetchRetries' '2')
+    if ! fetch_with_retry "$remote_name" "$CONFIG"; then
+      messages+=("[git-pilot] Warning: Could not fetch from '${remote_name}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync.")
+    fi
+  fi
+fi
+```
+
+Config keys: `.git.autoFetch` (default `true`), `.git.fetchRetries` (default `2`), `.remote.defaultName` (default `'origin'`).
+
+### 3b. Branch freshness -- insert after `current_branch` is assigned
+
+```bash
+if is_git_repo && has_remote && [[ -n "$current_branch" ]]; then
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  tracking_status=$(get_branch_tracking_status "$current_branch" "$remote_name")
+  case "$tracking_status" in
+    behind:*)
+      behind_count="${tracking_status#behind:}"
+      if git merge --ff-only "${remote_name}/${current_branch}" >/dev/null 2>&1; then
+        messages+=("[git-pilot] Branch '${current_branch}' was ${behind_count} commit(s) behind '${remote_name}/${current_branch}'. Fast-forwarded to latest.")
+      else
+        messages+=("[git-pilot] Branch '${current_branch}' is ${behind_count} commit(s) behind '${remote_name}/${current_branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is.")
+      fi
+      ;;
+    diverged:*:*)
+      IFS=':' read -r _ ahead_count behind_count <<< "$tracking_status"
+      messages+=("[git-pilot] Branch '${current_branch}' has diverged from '${remote_name}/${current_branch}' (${ahead_count} local, ${behind_count} remote). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue.")
+      ;;
+    ahead:*)
+      ahead_count="${tracking_status#ahead:}"
+      messages+=("[git-pilot] Branch '${current_branch}' is ${ahead_count} commit(s) ahead of '${remote_name}/${current_branch}'. Unpushed changes.")
+      ;;
+  esac
+fi
+```
+
+`get_branch_tracking_status()` returns: `up-to-date`, `ahead:N`, `behind:N`, `diverged:A:B`, or `no-remote`.
+
+### 3c. Detached HEAD -- inside branch detection, when `current_branch` is empty
+
+```bash
+if [[ -z "$current_branch" ]]; then
+  head_sha=$(git rev-parse --short HEAD 2>/dev/null)
+  prev_branch=$(git reflog show --format='%gs' | grep -m1 'checkout: moving from' | \
+    sed 's/checkout: moving from \([^ ]*\) to .*/\1/')
+  if [[ -n "$prev_branch" ]]; then
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Previous branch was '${prev_branch}'. Prompt the user: return to '${prev_branch}', create a new branch from HEAD, or continue in detached state.")
+  else
+    messages+=("[git-pilot] Detached HEAD at ${head_sha}. Prompt the user: create a new branch from HEAD or continue in detached state.")
+  fi
+fi
+```
+
+### 3d. Extended state init -- replace existing Step 9
+
+The v1 `init_state` call is `init_state "$SESSION_ID" "$current_branch" "$previous_branch"` (3 args). Replace with:
+
+```bash
+if [[ -n "$SESSION_ID" ]]; then
+  base_branch="$default_branch"
+  branch_purpose=""
+  if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    branch_purpose=$(derive_branch_purpose "$current_branch")
+    configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+    if [[ -n "$configured_base" ]]; then
+      base_branch="$configured_base"
+    fi
+  fi
+  init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
+fi
+```
+
+This requires `init_state()` in `state.sh` to accept 5 positional args (done in task 002).
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/session-start.sh (modify -- add fetch, freshness, detached HEAD, extended state init)
diff --git a/tasks/done/009-hook-pre-commit.md b/tasks/done/009-hook-pre-commit.md
new file mode 100644
index 0000000..1a307e7
--- /dev/null
+++ b/tasks/done/009-hook-pre-commit.md
@@ -0,0 +1,92 @@
+# Task 009: Hook pre-commit.sh Modifications
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (uses `get_config()` for `.branch.autoStashOnSwitch`, `.git.protectDefaultBranch`)
+- 007-stash-functions (uses `auto_stash()` from `git-utils.sh`, `normalize_protect_default_branch()`)
+
+## Spec References
+- spec/05-stash-and-robustness.md (sections 1.7, 3.2-3.6)
+- spec/06-hooks-and-lifecycle.md (section 7)
+
+## Scope
+Modify the existing `pre-commit.sh` script to add two capabilities: (a) branch switch detection with `is_branch_switch_command()` that triggers `auto_stash()` before allowing the switch, and (b) enhanced protected branch enforcement upgrading the boolean `protectDefaultBranch` to a tri-state (`warn`/`block`/`off`) with backward compatibility.
+
+## Acceptance Criteria
+- [x] `is_branch_switch_command()` detects `git checkout <branch>` (without `-b`/`-B`) and `git switch <branch>` (without `-c`/`-C`), sets `SWITCH_TARGET` global variable
+- [x] When a branch switch is detected and `branch.autoStashOnSwitch` is `true` and `has_uncommitted_changes`, call `auto_stash()` and emit: `"[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."`
+- [x] Branch switch detection block is placed BEFORE the existing `is_git_commit_command` check (early in the main flow)
+- [x] All existing `PROTECT_DEFAULT` boolean checks replaced with tri-state: `protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')` then `protect_mode=$(normalize_protect_default_branch "$protect_mode")`
+- [x] `"block"` mode calls `output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."`
+- [x] `"warn"` mode preserves v1 behavior (allow with warning message)
+- [x] `"off"` mode emits no message
+
+## Implementation Notes
+
+### Branch switch detection -- add `is_branch_switch_command()` alongside existing `is_branch_creation_command()`
+
+```bash
+is_branch_switch_command() {
+  local cmd="$1"
+  SWITCH_TARGET=""
+  # git checkout <branch> (not -b)
+  if [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+-[bB] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+  # git switch <branch> (not -c)
+  if [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+-[cC] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+```
+
+Known limitation: `git checkout <branch>` vs `git checkout <file>` is ambiguous; the regex checks for absence of `-b` but paths without `--` may be misdetected.
+
+### Branch switch auto-stash trigger -- insert before the `is_git_commit_command` check in the main flow (after config loading, before "--- Branch creation detection ---" section)
+
+```bash
+SWITCH_TARGET=""
+if is_branch_switch_command "$COMMAND"; then
+  auto_stash_cfg=$(get_config "$CONFIG" '.branch.autoStashOnSwitch' 'true')
+  if [[ "$auto_stash_cfg" == "true" ]] && has_uncommitted_changes; then
+    current_br=$(get_current_branch)
+    if auto_stash "$current_br" "$SESSION_ID"; then
+      output_allow_with_message "[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."
+    fi
+  fi
+fi
+```
+
+### Protected branch tri-state -- replace all three existing boolean protection blocks
+
+There are 3 places in v1 `pre-commit.sh` where `PROTECT_DEFAULT` is checked (lines ~507-514, ~524-531, ~627-633). Replace each with the tri-state pattern:
+
+```bash
+protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$protect_mode")
+if is_on_default_branch "$CONFIG" 2>/dev/null; then
+  default_br=$(get_default_branch "$CONFIG")
+  case "$protect_mode" in
+    warn)
+      SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+      ;;
+    block)
+      output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+      ;;
+    off)
+      ;;
+  esac
+fi
+```
+
+Backward compatibility: `true` -> `"warn"`, `false` -> `"off"`, unknown -> `"warn"`. The `normalize_protect_default_branch()` function is implemented in task 007.
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/pre-commit.sh (modify -- add `is_branch_switch_command()`, auto-stash trigger, tri-state protected branch)
diff --git a/tasks/done/010-hook-post-bash.md b/tasks/done/010-hook-post-bash.md
new file mode 100644
index 0000000..3ea05f2
--- /dev/null
+++ b/tasks/done/010-hook-post-bash.md
@@ -0,0 +1,88 @@
+# Task 010: Hook post-bash.sh Modifications
+
+## Status
+done
+
+## Dependencies
+- 004-agent-library (uses `is_agent_context()` and `is_operation_agent_restricted()` from `scripts/agent.sh`)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (sections 5a, 5b)
+- spec/05-stash-and-robustness.md (section 4 -- output helpers referenced for message format)
+
+## Scope
+Modify the existing `post-bash.sh` script to add two capabilities: (a) agent suppression that skips push prompts for agent contexts where push is restricted, and (b) push rejection detection that intercepts failed `git push` commands and provides recovery options.
+
+## Acceptance Criteria
+- [x] Source `agent.sh` and check `is_agent_context "$session_id"` early in the script; if true and `is_operation_agent_restricted "$config" "push"` is true, emit `{"continue": true}` and exit
+- [x] After the existing push prompt logic, detect failed `git push` commands by checking `exit_code != 0` and stderr matching `rejected|failed to push|non-fast-forward`
+- [x] On push rejection, emit a 4-option message: pull+rebase, force-push-with-lease, pull+merge, cancel
+- [x] The push rejection message format is: `"[git-pilot] Push rejected -- remote '${remote_name}/${current_branch}' has new commits. Prompt the user:\n1. Pull and rebase...\n2. Force push with lease...\n3. Pull and merge...\n4. Cancel"`
+- [x] Session ID is extracted from input JSON via `jq -r '.session_id // empty'`
+- [x] Exit code, stdout, and stderr are extracted from `.tool_result.exitCode`, `.tool_result.stdout`, `.tool_result.stderr` respectively
+
+## Implementation Notes
+
+### Agent suppression -- insert after loading config, before the push check
+
+The v1 `post-bash.sh` currently only checks for `git commit` commands. Add agent check at the top of the script logic:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+
+# Extract session_id (v1 does not extract this -- add it)
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+
+if is_agent_context "$session_id"; then
+  if is_operation_agent_restricted "$config" "push"; then
+    echo '{"continue": true}'
+    exit 0
+  fi
+fi
+```
+
+This goes after `config=$(load_config "$cwd")` and before any push-related logic.
+
+### Push rejection detection -- insert after the existing push prompt block
+
+The v1 script only looks at `git commit` commands. Add a new block to detect push failures:
+
+```bash
+exit_code=$(echo "$input" | jq -r '.tool_result.exitCode // 0')
+stdout=$(echo "$input" | jq -r '.tool_result.stdout // empty')
+stderr=$(echo "$input" | jq -r '.tool_result.stderr // empty')
+
+if echo "$command" | grep -qE 'git\s+push' && [[ "$exit_code" != "0" ]]; then
+  if echo "$stderr" | grep -qiE 'rejected|failed to push|non-fast-forward'; then
+    current_branch=$(get_current_branch)
+    remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
+    message="[git-pilot] Push rejected -- remote '${remote_name}/${current_branch}' has new commits. Prompt the user:
+1. Pull and rebase, then retry push (git pull --rebase && git push)
+2. Force push with lease (git push --force-with-lease)
+3. Pull and merge (git pull)
+4. Cancel"
+    jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+    exit 0
+  fi
+fi
+```
+
+The `command` variable is already extracted in v1 as `$(echo "$input" | jq -r '.tool_input.command // empty')`. The `exit_code`, `stdout`, `stderr` are new extractions from the PostToolUse input payload.
+
+### Broadening command detection
+
+The v1 `post-bash.sh` currently early-exits if the command does not match `git\s+commit`. This guard must be relaxed to also process `git push` commands. Change the early filter from:
+```bash
+if [[ -z "$command" ]] || ! echo "$command" | grep -qE 'git\s+commit'; then
+```
+to:
+```bash
+if [[ -z "$command" ]] || ! echo "$command" | grep -qE 'git\s+(commit|push)'; then
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/post-bash.sh (modify -- add agent suppression, push rejection detection, broaden command filter)
+
+## Validation Notes
+
+**PASS**: All acceptance criteria satisfied. The missing `stdout` extraction line has been added to `post-bash.sh` between `exit_code` and `stderr`. Script passes `bash -n` syntax check and `shellcheck --severity=warning` (only SC2034 for the intentionally-unused `stdout` variable).
diff --git a/tasks/done/011-hook-post-write.md b/tasks/done/011-hook-post-write.md
new file mode 100644
index 0000000..4aa16bf
--- /dev/null
+++ b/tasks/done/011-hook-post-write.md
@@ -0,0 +1,57 @@
+# Task 011: Hook post-write.sh Modifications
+
+## Status
+done
+
+## Dependencies
+- 004-agent-library (uses `is_agent_context()` from `scripts/agent.sh`)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (section 6)
+
+## Scope
+Modify the existing `post-write.sh` script to add agent suppression. In agent contexts, file change tracking still runs (changeCount increment, modifiedFiles append), but the threshold-reached commit suggestion message is suppressed -- the script exits before emitting the system message.
+
+## Acceptance Criteria
+- [x] Source `agent.sh` at the top alongside existing config/state sources
+- [x] Extract `session_id` from input (already done in v1 as `session_id=$(echo "$input" | jq -r '.session_id')`)
+- [x] After file tracking state updates are written (changeCount increment, modifiedFiles append), check `is_agent_context "$session_id"` and exit 0 before the threshold message block
+- [x] File change tracking (changeCount, modifiedFiles) continues to work for agents -- only the commit suggestion message is suppressed
+- [x] Non-agent behavior is completely unchanged
+
+## Implementation Notes
+
+### Agent suppression -- insert after state write, before threshold check
+
+The v1 `post-write.sh` flow is:
+1. Read input, load config, check `autoCommit.enabled`
+2. Increment `changeCount`, append to `modifiedFiles`, write state
+3. Check if `change_count >= threshold` -> emit message
+
+The agent check goes between steps 2 and 3:
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+
+# ... (existing tracking code: increment changeCount, append modifiedFiles, write_state) ...
+
+# Agent suppression: track changes but suppress commit suggestion
+if is_agent_context "$session_id"; then
+  exit 0
+fi
+
+# ... (existing threshold check and message emission) ...
+```
+
+The `source` line for `agent.sh` should be added at the top of the file alongside the existing `source` statements:
+
+```bash
+source "$SCRIPT_DIR/config.sh"
+source "$SCRIPT_DIR/state.sh"
+source "$SCRIPT_DIR/agent.sh"  # NEW
+```
+
+Per spec/06 section 6: "Still track file changes but suppress commit suggestion messages for agents."
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/post-write.sh (modify -- add agent.sh source, agent suppression after tracking)
diff --git a/tasks/done/012-hook-session-stop.md b/tasks/done/012-hook-session-stop.md
new file mode 100644
index 0000000..f3c8aaf
--- /dev/null
+++ b/tasks/done/012-hook-session-stop.md
@@ -0,0 +1,137 @@
+# Task 012: Hook session-stop.sh Modifications
+
+## Status
+done
+
+## Dependencies
+- 003-git-utils-extensions (uses `get_base_branch_drift()` for drift detection)
+- 004-agent-library (uses `is_agent_context()` to suppress rebase/summary for agents)
+- 005-rebase-library (uses `attempt_rebase()`, `get_conflict_details()` for rebase workflow)
+- 006-worktree-library (uses `list_worktrees()`, `remove_worktree()`, `unregister_worktree()` for cleanup)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (sections 4a, 4b)
+- spec/05-stash-and-robustness.md (section 5 -- error handling invariants)
+
+## Scope
+Modify the existing `session-stop.sh` script to add three capabilities: (a) base branch drift detection with automatic rebase before push, respecting conflict strategy config, (b) worktree cleanup for merged branches, and (c) agent context suppression for both drift/rebase and session summary blocks.
+
+## Acceptance Criteria
+- [x] Source `agent.sh`, `rebase.sh`, and `worktree.sh` at the appropriate points in the script
+- [x] Drift detection block: when `session_had_changes` is true, `has_remote`, `rebase.autoRebaseBeforePush` is `true`, and branch is not default -- call `get_base_branch_drift()` and handle `drifted:*`, `no-drift`, and `no-common-ancestor` cases
+- [x] On `drifted:N`, call `attempt_rebase("${remote_name}/${default_branch}")` and handle `success` and `conflict` results; for conflicts, respect `rebase.conflictStrategy` (`prompt`/`abort`/`merge-fallback`)
+- [x] Agent suppression: wrap drift detection/rebase AND session summary blocks in `if ! is_agent_context "$session_id"; then ... fi`
+- [x] Worktree cleanup: after MR/push logic, iterate `list_worktrees()` active entries; remove worktrees whose branch is merged into default branch; unregister worktrees with missing paths; emit remaining count message
+- [x] Drift detection is inserted AFTER work summary, BEFORE push workflow (between existing sections 1 and 2)
+- [x] Worktree cleanup is inserted AFTER MR/push, BEFORE state cleanup (between existing sections 3 and 4)
+
+## Implementation Notes
+
+### 4a. Drift detection -- insert after work summary (section 1), before push workflow (section 2)
+
+```bash
+source "$SCRIPT_DIR/agent.sh"
+
+if ! is_agent_context "$session_id"; then
+  # Drift detection and rebase
+  if [[ "$session_had_changes" == "true" ]] && has_remote; then
+    auto_rebase=$(get_config "$config" '.rebase.autoRebaseBeforePush' 'true')
+    if [[ "$auto_rebase" == "true" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+      source "$SCRIPT_DIR/rebase.sh"
+      drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name")
+      case "$drift_status" in
+        drifted:*)
+          drift_count="${drift_status#drifted:}"
+          messages+=("[git-pilot] Base branch '${default_branch}' has ${drift_count} new commit(s). Rebasing '${current_branch}' onto '${remote_name}/${default_branch}'...")
+          rebase_result=$(attempt_rebase "${remote_name}/${default_branch}")
+          case "$rebase_result" in
+            success)
+              messages+=("[git-pilot] Rebase succeeded cleanly. Ready to push.")
+              ;;
+            conflict)
+              conflict_strategy=$(get_config "$config" '.rebase.conflictStrategy' 'prompt')
+              case "$conflict_strategy" in
+                prompt)
+                  conflicts=$(get_conflict_details)
+                  conflict_count=$(echo "$conflicts" | jq 'length')
+                  conflict_files=$(echo "$conflicts" | jq -r '.[].file' | paste -sd', ')
+                  messages+=("[git-pilot] Rebase conflicts in ${conflict_count} file(s): ${conflict_files}. Prompt the user to resolve conflicts, abort rebase, or use merge instead.")
+                  ;;
+                abort)
+                  git rebase --abort 2>/dev/null
+                  messages+=("[git-pilot] Rebase aborted due to conflicts. Pushing without rebase.")
+                  ;;
+                merge-fallback)
+                  git rebase --abort 2>/dev/null
+                  if git merge "${remote_name}/${default_branch}" --no-edit 2>/dev/null; then
+                    messages+=("[git-pilot] Merge with '${default_branch}' succeeded (rebase had conflicts).")
+                  else
+                    conflicts=$(get_conflict_details)
+                    conflict_count=$(echo "$conflicts" | jq 'length')
+                    messages+=("[git-pilot] Both rebase and merge have conflicts in ${conflict_count} file(s). Prompt the user to resolve.")
+                  fi
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+        no-drift)
+          # No action needed
+          ;;
+        no-common-ancestor)
+          messages+=("[git-pilot] Cannot determine common ancestor between '${current_branch}' and '${default_branch}'. Skipping rebase. Push may require manual review.")
+          ;;
+      esac
+    fi
+  fi
+fi
+```
+
+Config keys: `.rebase.autoRebaseBeforePush` (default `true`), `.rebase.conflictStrategy` (default `prompt`, values: `prompt`/`abort`/`merge-fallback`).
+
+`get_base_branch_drift()` returns: `drifted:N`, `no-drift`, or `no-common-ancestor`.
+`attempt_rebase()` returns: `success` or `conflict`.
+`get_conflict_details()` returns a JSON array: `[{"file":"...","status":"..."}]`.
+
+### Agent suppression for session summary
+
+The existing work summary block (section 1, lines ~69-102 in v1) must also be wrapped:
+
+```bash
+if ! is_agent_context "$session_id"; then
+  # ... existing work summary code ...
+fi
+```
+
+### 4b. Worktree cleanup -- insert after MR/push (section 3), before state cleanup (section 4)
+
+```bash
+source "$SCRIPT_DIR/worktree.sh"
+registry=$(list_worktrees)
+active_count=$(echo "$registry" | jq '.worktrees | length')
+if [[ "$active_count" -gt 0 ]]; then
+  cleanup_on_merge=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+  if [[ "$cleanup_on_merge" == "true" ]]; then
+    echo "$registry" | jq -r '.worktrees[] | select(.status == "active") | .path' | \
+    while IFS= read -r wt_path; do
+      if [[ -d "$wt_path" ]]; then
+        wt_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
+        if [[ -n "$wt_branch" ]] && git branch --merged "$default_branch" | grep -q "$wt_branch"; then
+          remove_worktree "$wt_path" "false"
+        fi
+      else
+        unregister_worktree "$wt_path"
+      fi
+    done
+  fi
+  remaining=$(list_worktrees | jq '.worktrees | length')
+  if [[ "$remaining" -gt 0 ]]; then
+    messages+=("[git-pilot] ${remaining} active worktree(s) remain. Use /worktree to manage them.")
+  fi
+fi
+```
+
+Config key: `.worktree.cleanupOnMerge` (default `true`).
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/session-stop.sh (modify -- add drift detection, worktree cleanup, agent suppression)
diff --git a/tasks/done/013-hook-prompt-context.md b/tasks/done/013-hook-prompt-context.md
new file mode 100644
index 0000000..fba036a
--- /dev/null
+++ b/tasks/done/013-hook-prompt-context.md
@@ -0,0 +1,78 @@
+# Task 013: Hook prompt-context.sh (New)
+
+## Status
+done
+
+## Dependencies
+- 003-git-utils-extensions (uses `derive_branch_purpose()` from `git-utils.sh`)
+- 004-agent-library (uses `is_agent_context()` from `agent.sh` to suppress in agent contexts)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (section 2)
+
+## Scope
+Create a new `prompt-context.sh` script that runs on the `UserPromptSubmit` hook event. It provides branch context (purpose, commit count, recent commits) as a system message on every user prompt, enabling Claude to detect when the user's request is unrelated to the current branch's purpose. Suppressed for agents and when `branch.unrelatedWorkDetection` is `false`.
+
+## Acceptance Criteria
+- [x] New file `scripts/prompt-context.sh` created with shebang `#!/usr/bin/env bash` and `set -euo pipefail`
+- [x] Sources `config.sh`, `git-utils.sh`, and `agent.sh`
+- [x] Reads input JSON from stdin; extracts `session_id` and `cwd`; early-exits with `{"continue": true}` if: no cwd, not a git repo, `branch.unrelatedWorkDetection` is not `true`, or `is_agent_context` returns true
+- [x] Skips (early-exits) if on default branch or in detached HEAD (empty `current_branch`)
+- [x] Skips if branch has no commits (`git rev-list --count "${default_branch}..${current_branch}"` is 0)
+- [x] Emits system message: `"[git-pilot] Branch context: '${current_branch}' (${branch_purpose}). ${commit_count} commit(s). Recent: ${recent_commits}"`
+- [x] `branch_purpose` is derived via `derive_branch_purpose "$current_branch"`; `recent_commits` are the last 5 commits via `git log "${default_branch}..${current_branch}" --oneline --no-decorate -5`
+
+## Implementation Notes
+
+### Full script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/config.sh"
+source "$SCRIPT_DIR/git-utils.sh"
+source "$SCRIPT_DIR/agent.sh"
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+
+if [[ -z "$cwd" ]]; then echo '{"continue": true}'; exit 0; fi
+cd "$cwd" 2>/dev/null || { echo '{"continue": true}'; exit 0; }
+if ! is_git_repo; then echo '{"continue": true}'; exit 0; fi
+
+config=$(load_config "$cwd")
+
+detection_enabled=$(get_config "$config" '.branch.unrelatedWorkDetection' 'true')
+if [[ "$detection_enabled" != "true" ]]; then echo '{"continue": true}'; exit 0; fi
+if is_agent_context "$session_id"; then echo '{"continue": true}'; exit 0; fi
+
+current_branch=$(get_current_branch)
+default_branch=$(get_default_branch "$config")
+
+# Skip if on default branch or detached HEAD
+if [[ -z "$current_branch" ]] || [[ "$current_branch" == "$default_branch" ]]; then
+  echo '{"continue": true}'; exit 0
+fi
+
+# Skip if branch has no commits
+commit_count=$(git rev-list --count "${default_branch}..${current_branch}" 2>/dev/null || echo "0")
+if [[ "$commit_count" == "0" ]]; then echo '{"continue": true}'; exit 0; fi
+
+branch_purpose=$(derive_branch_purpose "$current_branch")
+recent_commits=$(git log "${default_branch}..${current_branch}" --oneline --no-decorate -5 2>/dev/null || true)
+message="[git-pilot] Branch context: '${current_branch}' (${branch_purpose}). ${commit_count} commit(s). Recent: ${recent_commits}"
+jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+```
+
+### Key details
+
+- Config key: `.branch.unrelatedWorkDetection` (default `true`)
+- `derive_branch_purpose()` is from task 003 (git-utils-extensions); it parses branch name patterns to infer purpose (e.g., `feat/add-auth` -> `"feature: add auth"`)
+- The output format uses `{"continue": true, "systemMessage": $msg}` -- same pattern as other hooks
+- The `UserPromptSubmit` hook type means this runs BEFORE Claude processes the user's prompt, so the branch context is injected into Claude's system context for that turn
+- Timeout is 5 seconds (registered in hooks.json, task 014)
+
+## Files to Create or Modify
+- plugins/git-pilot/scripts/prompt-context.sh (new)
diff --git a/tasks/done/014-hook-registration.md b/tasks/done/014-hook-registration.md
new file mode 100644
index 0000000..aae45b8
--- /dev/null
+++ b/tasks/done/014-hook-registration.md
@@ -0,0 +1,100 @@
+# Task 014: Hook Registration (hooks.json Update)
+
+## Status
+done
+
+## Dependencies
+- 013-hook-prompt-context (registers the new `prompt-context.sh` script; should come after the script exists)
+
+## Spec References
+- spec/06-hooks-and-lifecycle.md (section 1)
+
+## Scope
+Update `hooks/hooks.json` to register the new `UserPromptSubmit` hook entry for `prompt-context.sh` and adjust timeouts for existing hooks to accommodate new v2 functionality (fetch, rebase, drift detection).
+
+## Acceptance Criteria
+- [x] `SessionStart` timeout changed from `15` to `30` (fetch + freshness checks added)
+- [x] `PostToolUse` Bash matcher timeout changed from `10` to `15` (push rejection + rebase handling)
+- [x] `Stop` timeout changed from `30` to `45` (drift detection + rebase + worktree cleanup)
+- [x] New `UserPromptSubmit` entry added with `prompt-context.sh` command and timeout `5`
+- [x] `UserPromptSubmit` entry has no `matcher` field (runs on all user prompts)
+- [x] All existing hook entries (SessionStart, PreToolUse, PostToolUse Write|Edit, PostToolUse Bash, Stop) are preserved with no other changes
+- [x] The resulting JSON is valid and parseable
+
+## Implementation Notes
+
+### Target `hooks.json` content
+
+The v1 file is at `plugins/git-pilot/hooks/hooks.json`. Replace with:
+
+```json
+{
+  "description": "git-pilot: Automated git workflow management",
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh",
+        "timeout": 30
+      }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-context.sh",
+        "timeout": 5
+      }]
+    }],
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
+        "timeout": 10
+      }]
+    }],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-write.sh",
+          "timeout": 10
+        }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-bash.sh",
+          "timeout": 15
+        }]
+      }
+    ],
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh",
+        "timeout": 45
+      }]
+    }]
+  }
+}
+```
+
+### Changes from v1
+
+| Hook | Field | v1 | v2 | Reason |
+|------|-------|----|----|--------|
+| SessionStart | timeout | 15 | 30 | fetch + freshness check |
+| PostToolUse (Bash) | timeout | 10 | 15 | push rejection + rebase |
+| Stop | timeout | 30 | 45 | drift + rebase + MR + worktree cleanup |
+| UserPromptSubmit | (new) | -- | 5 | branch context for unrelated work detection |
+
+The `PreToolUse` timeout remains at `10` (no change). The `PostToolUse` Write|Edit timeout remains at `10` (no change).
+
+Note: `UserPromptSubmit` has no `matcher` field because it runs on every user prompt submission.
+
+## Files to Create or Modify
+- plugins/git-pilot/hooks/hooks.json (modify -- update timeouts, add UserPromptSubmit entry)
diff --git a/tasks/done/015-skills-modified.md b/tasks/done/015-skills-modified.md
new file mode 100644
index 0000000..3061145
--- /dev/null
+++ b/tasks/done/015-skills-modified.md
@@ -0,0 +1,82 @@
+# Task 015: Modified Skills — /branch, /finish, /configure
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (new config keys referenced by /configure, e.g. `branch.autoStashOnSwitch`, `rebase.autoRebaseBeforePush`, `rebase.allowForcePush`, `worktree.enabled`, `worktree.basePath`)
+- 005-rebase-library (drift detection logic used by /finish Step 1.5)
+
+## Spec References
+- spec/07-skills-and-claude-md.md
+
+## Scope
+Update three existing skill files — `/branch`, `/finish`, and `/configure` — with the v2 additions specified in the spec. The `/branch` skill gains a Step 5 for recording base branch context. The `/finish` skill gains a Step 1.5 for base branch drift detection before push. The `/configure` skill gains 11 new entries in its user-says-to-config-change reference table.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/skills/branch/SKILL.md` contains a new "Step 5: Record Branch Context" after the existing Step 4, with the exact text from spec section 3.1.
+- [x] `plugins/git-pilot/skills/finish/SKILL.md` contains a new "Step 1.5: Check Base Branch Drift" between existing Steps 1 and 2, with the exact text from spec section 3.2.
+- [x] `/finish` Step 1.5 documents base branch resolution order: (1) session state `baseBranch` field, (2) `git config branch.${current}.merge` with `refs/heads/` stripped, (3) `git.defaultBranch` from config.
+- [x] `plugins/git-pilot/skills/configure/SKILL.md` reference table includes all 11 new entries from spec section 3.4.
+- [x] All three SKILL.md files retain valid YAML frontmatter (`name`, `description`).
+- [x] Existing steps and content in all three skills are preserved — only additive changes.
+
+## Implementation Notes
+
+### /branch — Add Step 5 (spec section 3.1)
+
+Append after the existing Step 4 (`git switch -c <branch-name>`):
+
+```markdown
+## Step 5: Record Branch Context
+
+After creating the branch, note the base branch (the branch you were on before switching)
+and the branch purpose (derived from the description). These are used for unrelated work
+detection and drift checks.
+```
+
+### /finish — Add Step 1.5 (spec section 3.2)
+
+Insert between existing Step 1 ("Check for Uncommitted Changes") and Step 2 ("Push to Remote"):
+
+```markdown
+## Step 1.5: Check Base Branch Drift
+
+Before pushing, check if the base branch has advanced:
+
+1. Run `git fetch <remote> <defaultBranch>`.
+2. Check for new commits on the base branch since this branch diverged.
+3. If the base has new commits and `rebase.autoRebaseBeforePush` is `true`:
+   - Attempt `git rebase <remote>/<defaultBranch>`.
+   - If rebase succeeds: continue to push.
+   - If rebase has conflicts: present conflict details and options to the user.
+4. If force push is needed after rebase, follow `rebase.allowForcePush` policy.
+```
+
+Base branch determination order (from spec):
+1. Session state `baseBranch` field
+2. `git config branch.${current}.merge` with `refs/heads/` stripped
+3. `git.defaultBranch` from config
+
+### /configure — New Reference Table Entries (spec section 3.4)
+
+Add these rows to the existing table in Step 1:
+
+| User Says | Config Change |
+|-----------|--------------|
+| "Fetch remote on session start" | `git.autoFetch: true` |
+| "Block commits to main" | `git.protectDefaultBranch: "block"` |
+| "Don't warn about main branch commits" | `git.protectDefaultBranch: "off"` |
+| "Disable unrelated work detection" | `branch.unrelatedWorkDetection: false` |
+| "Don't auto-stash on branch switch" | `branch.autoStashOnSwitch: false` |
+| "Don't auto-rebase before push" | `rebase.autoRebaseBeforePush: false` |
+| "Never force push" | `rebase.allowForcePush: "never"` |
+| "Always force push after rebase" | `rebase.allowForcePush: "always"` |
+| "Use merge when rebase conflicts" | `rebase.conflictStrategy: "merge-fallback"` |
+| "Disable worktrees" | `worktree.enabled: false` |
+| "Worktrees in /tmp" | `worktree.basePath: "/tmp/{{project}}-worktrees"` |
+
+## Files to Create or Modify
+- plugins/git-pilot/skills/branch/SKILL.md (modify)
+- plugins/git-pilot/skills/finish/SKILL.md (modify)
+- plugins/git-pilot/skills/configure/SKILL.md (modify)
diff --git a/tasks/done/016-skills-new.md b/tasks/done/016-skills-new.md
new file mode 100644
index 0000000..885d423
--- /dev/null
+++ b/tasks/done/016-skills-new.md
@@ -0,0 +1,75 @@
+# Task 016: New Skills — /stash, /worktree, /rebase
+
+## Status
+done
+
+## Dependencies
+- 005-rebase-library (rebase.sh functions invoked by /rebase skill: `attempt_rebase()`, `get_conflict_details()`, `needs_force_push()`)
+- 006-worktree-library (worktree.sh functions invoked by /worktree skill: `create_worktree()`, `remove_worktree()`, `list_worktrees()`, `merge_worktree_branch()`)
+- 007-stash-functions (`auto_stash()`, `auto_restore_stash()`, `has_uncommitted_changes()` invoked by /stash skill)
+
+## Spec References
+- spec/07-skills-and-claude-md.md
+
+## Scope
+Create three new skill directories and SKILL.md files: `/stash` for managing git stashes, `/worktree` for managing git worktrees for parallel branch work, and `/rebase` for rebasing the current branch onto a target. Each skill file uses the standard YAML frontmatter format and provides step-by-step workflows for the Claude agent.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/skills/stash/SKILL.md` exists with valid frontmatter (`name: stash`, `description: Manage git stashes - save, list, apply, or drop`) and complete workflow matching spec section 4.1.
+- [x] `plugins/git-pilot/skills/worktree/SKILL.md` exists with valid frontmatter (`name: worktree`, `description: Manage git worktrees for parallel branch work`) and complete workflow matching spec section 4.2.
+- [x] `plugins/git-pilot/skills/rebase/SKILL.md` exists with valid frontmatter (`name: rebase`, `description: Rebase current branch onto another branch`) and complete workflow matching spec section 4.3.
+- [x] `/stash` skill covers all four actions: save, list, pop/apply, drop — each with the exact sub-steps from the spec.
+- [x] `/worktree` skill covers all four actions: list, create, remove, merge — each with the exact sub-steps from the spec.
+- [x] `/rebase` skill covers all four steps: determine target, pre-flight checks, execute rebase, handle force push — with the exact details from the spec.
+
+## Implementation Notes
+
+### SKILL.md Frontmatter Format
+
+All skill files must begin with YAML frontmatter:
+
+```yaml
+---
+name: <skill-name>
+description: <one-line description>
+---
+```
+
+### /stash — spec section 4.1
+
+Create `plugins/git-pilot/skills/stash/SKILL.md` with the following content verbatim from the spec:
+
+- **Frontmatter**: `name: stash`, `description: Manage git stashes - save, list, apply, or drop`
+- **Step 1: Determine Action** — Parse argument: `/stash` or `/stash save` (stash current changes), `/stash list` (list all), `/stash pop` or `/stash apply` (restore most recent), `/stash drop` (drop most recent). If no argument, ask the user.
+- **Step 2: Execute** — Four sub-sections:
+  - **Save**: Check for uncommitted changes. Ask for optional message. Run `git stash push -m "<message>"`. Confirm with stash ref.
+  - **List**: Run `git stash list`. If empty: "No stashes found." Present index, branch, message.
+  - **Pop / Apply**: Run `git stash list`. If empty: "No stashes to restore." If multiple, show list and ask which one. For pop: `git stash pop <ref>`. For apply: `git stash apply <ref>`. If conflicts: warn and show conflicting files.
+  - **Drop**: Run `git stash list`. If empty: "No stashes to drop." If multiple, show list and ask. Confirm before dropping. Run `git stash drop <ref>`.
+
+### /worktree — spec section 4.2
+
+Create `plugins/git-pilot/skills/worktree/SKILL.md` with the following content verbatim from the spec:
+
+- **Frontmatter**: `name: worktree`, `description: Manage git worktrees for parallel branch work`
+- **Step 1: Determine Action** — Parse: `/worktree` or `/worktree list` (list), `/worktree create <branch>` (create), `/worktree remove <path-or-branch>` (remove), `/worktree merge <path-or-branch>` (merge). Default to list if no argument.
+- **Step 2: Execute** — Four sub-sections:
+  - **List**: Read `.git/git-pilot-worktrees.json` registry. Also run `git worktree list`. Present path, branch, base branch, creation date, status.
+  - **Create**: Ask/parse branch name. Ask base branch (default: `git.defaultBranch`). Determine path via `worktree.basePath`. Run `git worktree add <path> -b <branch> <base>`. Register in registry. Confirm with path.
+  - **Remove**: Identify by path or branch. Check for uncommitted changes. If uncommitted, warn and confirm. Run `git worktree remove <path>`. Optionally `git branch -d <branch>`. Unregister from registry.
+  - **Merge**: Identify by path or branch. Get branch and base from registry. Switch main worktree to base. Attempt `git merge <worktree-branch> --no-edit`. If conflicts: present and ask to resolve. If `worktree.cleanupOnMerge` is `true`: remove worktree and delete branch. Confirm.
+
+### /rebase — spec section 4.3
+
+Create `plugins/git-pilot/skills/rebase/SKILL.md` with the following content verbatim from the spec:
+
+- **Frontmatter**: `name: rebase`, `description: Rebase current branch onto another branch`
+- **Step 1: Determine Target** — If user specified target (e.g., `/rebase main`), use it. Otherwise default to `git.defaultBranch`.
+- **Step 2: Pre-flight Checks** — Ensure clean working tree (ask to stash/commit if dirty). Fetch remote: `git fetch <remote> <target>`. Count commits: `git rev-list --count <remote>/<target>..HEAD`. Show: "Rebasing N commit(s) onto <remote>/<target>."
+- **Step 3: Execute Rebase** — Run `git rebase <remote>/<target>`. On success: "Rebase completed successfully." On conflicts: show conflicting files and details, present options (resolve manually, accept theirs `git checkout --theirs . && git add .`, accept ours `git checkout --ours . && git add .`, abort `git rebase --abort`). After resolution: `git rebase --continue`.
+- **Step 4: Handle Force Push** — If branch was previously pushed and rebase rewrote history: inform "Rebase rewrote history. Force push is needed to update the remote." Based on `rebase.allowForcePush`: `"ask"` prompts user, `"always"` auto-pushes with `--force-with-lease`, `"never"` informs force push is disabled. Use `git push --force-with-lease <remote> <branch>`.
+
+## Files to Create or Modify
+- plugins/git-pilot/skills/stash/SKILL.md (new)
+- plugins/git-pilot/skills/worktree/SKILL.md (new)
+- plugins/git-pilot/skills/rebase/SKILL.md (new)
diff --git a/tasks/done/017-claude-md-update.md b/tasks/done/017-claude-md-update.md
new file mode 100644
index 0000000..d2a6e06
--- /dev/null
+++ b/tasks/done/017-claude-md-update.md
@@ -0,0 +1,124 @@
+# Task 017: CLAUDE.md Update — All 10 Rules and Updated Skill Reference
+
+## Status
+done
+
+## Dependencies
+- 004-agent-library (CLAUDE.md Rule 10 references agent teams detection and behavior)
+- 005-rebase-library (CLAUDE.md Rule 9 references conflict resolution from rebase operations)
+- 006-worktree-library (CLAUDE.md Rule 10 references worktree operations for agents)
+- 007-stash-functions (CLAUDE.md Rule 8 references auto-stash on branch switch)
+
+## Spec References
+- spec/07-skills-and-claude-md.md
+
+## Scope
+Replace the existing v1 CLAUDE.md (6 rules, 4 skills in reference table) with the complete v2 version containing all 10 rules and 7 skills in the reference table. The v2 CLAUDE.md adds Rule 7 (unrelated work detection), Rule 8 (branch switching with auto-stash), Rule 9 (conflict resolution guidance), and Rule 10 (agent teams behavior). The skill reference table adds `/stash`, `/worktree`, and `/rebase`.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/CLAUDE.md` contains exactly 10 numbered rules, each with the exact text from spec section 1.
+- [x] Rule 7 (Unrelated Work Detection) includes all 5 sub-points: branch name parsing, recent commits review, assessment with the exact prompt text, "when NOT to prompt" conditions, and branch switch reference.
+- [x] Rule 8 (Branch switching) includes all 3 steps: auto-stash when `branch.autoStashOnSwitch` is `true`, auto-restore on target branch, conflict warning on restore failure.
+- [x] Rule 9 (Conflict resolution) includes all 4 steps: read conflicting files, provide recommendations (one-side vs both-side vs deleted), present options (resolve manually / accept ours / accept theirs / abort), continue after resolution.
+- [x] Rule 10 (Agent Teams) includes all 4 points: no push/MR/branch-switch prompts, commit rules still active, no auto-commit suggestions, stay in worktree directory.
+- [x] Skill reference table lists all 7 skills: `/branch`, `/finish`, `/summary`, `/configure`, `/stash`, `/worktree`, `/rebase` with correct "When to use" descriptions.
+
+## Implementation Notes
+
+Replace the entire content of `plugins/git-pilot/CLAUDE.md` with the complete v2 version from spec section 1. The exact content is provided in the spec between the opening and closing markdown code fence.
+
+### Rules 1-6
+
+Rules 1 through 6 are unchanged from v1. They must be preserved exactly. Verify no unintended drift.
+
+### Rule 7: Unrelated Work Detection
+
+```markdown
+## Rule 7: Unrelated work detection
+
+Before starting work on a new user request, assess whether the request is related
+to the current branch's purpose:
+
+1. **Branch name**: Parse the branch name for semantic meaning. For example,
+   `feat/add-dark-mode` implies work on dark mode; `fix/login-timeout` implies
+   fixing a login timeout bug.
+2. **Recent commits**: Review the commit log on this branch for scope context.
+3. **Assessment**: If the user's request is clearly unrelated to the branch's
+   purpose (different feature, different bug, different module), prompt the user:
+
+   "This work appears unrelated to the current branch (`<branch-name>`).
+   Options:
+   1. Create a new branch from `<default-branch>` (recommended — keeps branches focused)
+   2. Create a new branch from the current branch (if this work depends on current changes)
+   3. Continue on this branch"
+
+4. **When NOT to prompt**: Do not prompt for closely related work (e.g., fixing
+   a bug discovered while implementing a feature on the same branch), for work
+   on the default branch, or for branches with no commits yet.
+5. **If the user chooses to create a new branch**: Follow the branch switch
+   workflow (see Rule 8).
+```
+
+### Rule 8: Branch switching
+
+```markdown
+## Rule 8: Branch switching
+
+When switching branches (via /branch, user request, or unrelated work detection):
+
+1. If there are uncommitted changes and `branch.autoStashOnSwitch` is `true`, stash
+   them automatically before switching. Inform the user: "Stashed changes on '<branch>'."
+2. After switching, check if there's a git-pilot stash for the target branch and
+   restore it automatically.
+3. If stash restoration fails (conflicts), inform the user and suggest manual resolution.
+```
+
+### Rule 9: Conflict resolution
+
+```markdown
+## Rule 9: Conflict resolution
+
+When a rebase or merge results in conflicts:
+
+1. Read the conflicting files to understand the nature of each conflict.
+2. For each conflict, provide a recommendation:
+   - If only one side modified the region, recommend accepting that side.
+   - If both sides modified the same lines, recommend manual review.
+   - If a file was deleted on one side, explain the tradeoff.
+3. Present clear options: resolve manually, accept ours, accept theirs, abort.
+4. After the user resolves conflicts, continue the interrupted operation
+   (`git rebase --continue` or `git merge --continue`).
+```
+
+### Rule 10: Agent Teams
+
+```markdown
+## Rule 10: Agent Teams
+
+When operating as a spawned agent (not the orchestrator):
+
+1. Do not prompt for push, MR creation, or branch switching. These are
+   orchestrator-only operations.
+2. Follow commit rules normally — agents must still use proper commit format.
+3. Do not run auto-commit suggestions. Commit when instructed by the orchestrator.
+4. If instructed to work in a specific worktree directory, stay in that directory.
+```
+
+### Updated Skill Reference Table
+
+```markdown
+## Skill reference
+
+| Skill | When to use |
+|-------|-------------|
+| `/branch` | Proactively when on the default branch before making changes |
+| `/finish` | When the user says they're done, or at session end |
+| `/summary` | When the user asks for a recap of branch work |
+| `/configure` | When the user wants to change git-pilot settings |
+| `/stash` | When the user wants to manage git stashes |
+| `/worktree` | When the user wants to manage git worktrees |
+| `/rebase` | When the user wants to rebase the current branch |
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/CLAUDE.md (modify)
diff --git a/tasks/done/018-plugin-metadata.md b/tasks/done/018-plugin-metadata.md
new file mode 100644
index 0000000..99e10cd
--- /dev/null
+++ b/tasks/done/018-plugin-metadata.md
@@ -0,0 +1,64 @@
+# Task 018: Plugin Metadata — Version Bump to 2.0.0
+
+## Status
+done
+
+## Dependencies
+- 017-claude-md-update (CLAUDE.md must be finalized before bumping the version that ships with it)
+
+## Spec References
+- spec/07-skills-and-claude-md.md
+
+## Scope
+Update `plugin.json` to reflect the v2.0.0 release: bump the version number from `"1.1.0"` to `"2.0.0"` and update the description to reflect all new v2 capabilities. This is a major version bump because v2 adds new behavioral rules, new skills, new library scripts, and new config keys that change the plugin's behavior.
+
+## Acceptance Criteria
+- [x] `plugins/git-pilot/.claude-plugin/plugin.json` has `"version": "2.0.0"`.
+- [x] The `"description"` field is updated to reflect v2 capabilities (rebase, worktrees, stash, agent teams, conflict resolution, unrelated work detection).
+- [x] The `"keywords"` array includes new v2-relevant keywords (at minimum: `"rebase"`, `"worktree"`, `"stash"`, `"agent-teams"`).
+- [x] The file remains valid JSON (`jq . plugin.json` succeeds).
+- [x] Existing fields (`name`, `author`, `license`, `hooks`, `skills`) are preserved unchanged.
+
+## Implementation Notes
+
+### Current plugin.json
+
+```json
+{
+  "name": "git-pilot",
+  "version": "1.1.0",
+  "description": "Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, and natural language configuration",
+  "author": {
+    "name": "git-pilot contributors"
+  },
+  "license": "MIT",
+  "keywords": [
+    "git",
+    "workflow",
+    "commits",
+    "branches",
+    "merge-request",
+    "pull-request",
+    "conventional-commits"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "skills": "./skills/"
+}
+```
+
+### Changes
+
+1. `"version"`: `"1.1.0"` -> `"2.0.0"`
+2. `"description"`: Update to mention the new v2 features. Suggested: `"Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, rebase and conflict resolution, worktree management, stash automation, agent teams support, and natural language configuration"`
+3. `"keywords"`: Add `"rebase"`, `"worktree"`, `"stash"`, `"agent-teams"`, `"conflict-resolution"` to the existing array.
+
+### Validation
+
+After writing, verify with:
+
+```bash
+jq . plugins/git-pilot/.claude-plugin/plugin.json
+```
+
+## Files to Create or Modify
+- plugins/git-pilot/.claude-plugin/plugin.json (modify)
diff --git a/tasks/done/019-test-suite.md b/tasks/done/019-test-suite.md
new file mode 100644
index 0000000..22798d2
--- /dev/null
+++ b/tasks/done/019-test-suite.md
@@ -0,0 +1,217 @@
+# Task 019: Test Suite — Bats Tests for All New Functions and Scenarios
+
+## Status
+done
+
+## Dependencies
+- 001-config-schema (tests for config backward compatibility and normalization)
+- 002-state-schema (tests for extended state fields)
+- 003-git-utils-extensions (tests for branch freshness, fetch_with_retry, derive_branch_purpose)
+- 004-agent-library (tests for agent detection)
+- 005-rebase-library (tests for rebase, drift detection, conflict details)
+- 006-worktree-library (tests for worktree CRUD and registry)
+- 007-stash-functions (tests for auto_stash and auto_restore_stash)
+- 008-hook-session-start (integration tests reference session-start behavior)
+- 009-hook-pre-commit (tests for protected branch enforcement)
+- 010-hook-post-bash (integration tests reference post-bash behavior)
+- 011-hook-post-write (integration tests reference post-write behavior)
+- 012-hook-session-stop (integration tests reference session-stop behavior)
+- 013-hook-prompt-context (integration tests reference prompt-context behavior)
+- 014-hook-registration (hooks.json must be finalized)
+- 015-skills-modified (skills must be finalized for integration test context)
+- 016-skills-new (skills must be finalized for integration test context)
+- 017-claude-md-update (CLAUDE.md must be finalized)
+- 018-plugin-metadata (plugin.json must be at 2.0.0)
+
+## Spec References
+- spec/01-config-and-state.md
+- spec/02-git-utils-and-network.md
+- spec/03-rebase-and-conflicts.md
+- spec/04-agent-and-worktree.md
+- spec/05-stash-and-robustness.md
+- spec/06-hooks-and-lifecycle.md
+- spec/07-skills-and-claude-md.md
+
+## Scope
+Create the full bats-core test suite for git-pilot v2. This includes a shared test helper with common fixtures (temporary git repo setup, config helpers, state helpers) and 8 test files covering all new functions and key scenarios specified in the tech spec section 8.2 and 8.3.
+
+## Acceptance Criteria
+- [ ] `plugins/git-pilot/tests/test_helper/common.bash` exists with shared setup/teardown fixtures that create temporary git repos with controlled state.
+- [x] All 8 test files exist: `branch-freshness.bats`, `drift-detection.bats`, `rebase.bats`, `agent-detection.bats`, `worktree.bats`, `stash.bats`, `protected-branch.bats`, `config-compat.bats`.
+- [ ] Each `.bats` file sources the appropriate script under test and the shared helper.
+- [ ] Each test scenario from spec section 8.2 has a corresponding `@test` block.
+- [ ] All tests can be run with `bats plugins/git-pilot/tests/` (assuming bats-core is installed).
+- [ ] Tests use temporary directories (cleaned up in teardown) and do not modify the real repository.
+
+## Implementation Notes
+
+### Test Framework
+
+Use `bats-core` (Bash Automated Testing System), version >= 1.0. Tests are run with:
+
+```bash
+bats plugins/git-pilot/tests/
+```
+
+### Directory Structure
+
+```
+plugins/git-pilot/tests/
+├── test_helper/
+│   └── common.bash
+├── branch-freshness.bats
+├── drift-detection.bats
+├── rebase.bats
+├── agent-detection.bats
+├── worktree.bats
+├── stash.bats
+├── protected-branch.bats
+└── config-compat.bats
+```
+
+### Shared Test Helper: `test_helper/common.bash`
+
+The helper must provide:
+
+1. **`setup_test_repo()`** — Create a temporary git repository in `$BATS_TMPDIR`, initialize it, create an initial commit, set up a `main` branch, configure user.name and user.email. Set `TEST_REPO` to the path.
+2. **`setup_remote_repo()`** — Create a bare repo to act as a remote, add it as `origin` to the test repo.
+3. **`teardown_test_repo()`** — Remove the temporary directories.
+4. **`create_config()`** — Write a test config JSON to a specified path.
+5. **`source_script()`** — Source a git-pilot script with the necessary environment variables set (`SCRIPT_DIR`, etc.).
+6. **Common variables**: `PLUGIN_DIR` pointing to `plugins/git-pilot/`, `SCRIPTS_DIR` pointing to `plugins/git-pilot/scripts/`.
+
+Pattern for each test file:
+
+```bash
+#!/usr/bin/env bats
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+}
+
+teardown() {
+  teardown_test_repo
+}
+
+@test "description of test case" {
+  # Arrange: set up specific state
+  # Act: call function
+  # Assert: check output/return code
+}
+```
+
+### Test Scenarios by File
+
+#### `branch-freshness.bats` (spec 8.2 — Branch Freshness)
+
+Tests for `get_branch_tracking_status()` from `git-utils.sh`:
+
+- `@test "branch behind remote — auto fast-forward succeeds"` — Push a commit to remote from another clone, verify fast-forward.
+- `@test "branch behind remote — fast-forward fails with merge commit"` — Create diverged state where ff is not possible, verify warning.
+- `@test "branch diverged from remote — warning with options"` — Create diverged commits on both sides, verify "diverged" status.
+- `@test "branch ahead of remote — unpushed info"` — Create local commit not pushed, verify "ahead" status.
+- `@test "no remote — no freshness check"` — Remove remote, verify no error and appropriate skip.
+- `@test "fetch fails — warning emitted, continues"` — Use invalid remote URL, verify warning and continuation.
+
+#### `drift-detection.bats` (spec 8.2 — Base Branch Drift)
+
+Tests for `get_base_branch_drift()` from `rebase.sh`:
+
+- `@test "base branch has drifted — rebase attempted"` — Push new commits to base on remote, verify drift detected.
+- `@test "base branch has not drifted — no action"` — No new base commits, verify no drift.
+- `@test "no common ancestor — warning emitted, push proceeds"` — Orphan branches, verify warning.
+
+#### `rebase.bats` (spec 8.2 — Rebase and Conflicts)
+
+Tests for `attempt_rebase()`, `get_conflict_details()`, `needs_force_push()` from `rebase.sh`:
+
+- `@test "clean rebase succeeds — success message"` — Non-conflicting rebase completes.
+- `@test "rebase with conflicts — conflict details reported"` — Conflicting changes, verify JSON conflict details output.
+- `@test "conflict strategy abort — rebase aborted immediately"` — Config set to `"abort"`, verify rebase is aborted.
+- `@test "conflict strategy merge-fallback — merge attempted after rebase fails"` — Config set to `"merge-fallback"`, verify merge attempt.
+- `@test "force push detection after rebase — prompt based on config"` — Verify `needs_force_push()` returns true after rebase.
+- `@test "push rejection detected — options presented"` — Simulate push rejection scenario.
+
+#### `agent-detection.bats` (spec 8.2 — Agent Detection)
+
+Tests for `is_agent_context()` and `is_operation_agent_restricted()` from `agent.sh`:
+
+- `@test "CLAUDE_SPAWNED_BY set — is_agent_context returns true"` — Set env var, verify detection.
+- `@test "state file isAgent true — is_agent_context returns true"` — Write state with `isAgent: true`, verify detection.
+- `@test "neither set — normal interactive behavior"` — No env var, no state flag, verify returns false.
+- `@test "push operation restricted for agents"` — Verify `is_operation_agent_restricted "push"` returns true in agent context.
+
+#### `worktree.bats` (spec 8.2 — Worktree Management)
+
+Tests for `create_worktree()`, `remove_worktree()`, `list_worktrees()`, `merge_worktree_branch()` from `worktree.sh`:
+
+- `@test "worktree created — registered in registry"` — Create worktree, verify `.git/git-pilot-worktrees.json` entry.
+- `@test "worktree removed — unregistered from registry"` — Remove worktree, verify registry entry gone.
+- `@test "worktree merge — branch merged, worktree cleaned up"` — Merge worktree branch, verify merge and cleanup.
+- `@test "worktree directory already exists — error reported"` — Pre-create the directory, verify error.
+
+#### `stash.bats` (spec 8.2 — Stash Management)
+
+Tests for `auto_stash()` and `auto_restore_stash()` from `git-utils.sh`:
+
+- `@test "auto-stash on branch switch — changes stashed, message emitted"` — Make changes, call auto_stash, verify stash created.
+- `@test "auto-restore on return — stash popped, message emitted"` — Stash changes, switch and return, call auto_restore, verify restored.
+- `@test "restore fails — warning with manual instructions"` — Create conflict scenario for stash pop, verify warning.
+
+#### `protected-branch.bats` (spec 8.2 — Protected Branch)
+
+Tests for `normalize_protect_default_branch()` and protected branch enforcement in `pre-commit.sh`:
+
+- `@test "warn mode — warning emitted, commit allowed"` — Config `"warn"`, verify warning output and exit 0.
+- `@test "block mode — commit blocked with exit code 2"` — Config `"block"`, verify exit code 2.
+- `@test "off mode — no message"` — Config `"off"`, verify no output.
+- `@test "boolean true — treated as warn"` — Config `true`, verify same as `"warn"`.
+- `@test "boolean false — treated as off"` — Config `false`, verify same as `"off"`.
+
+#### `config-compat.bats` (spec 8.2 — Config Backward Compatibility)
+
+Tests for config normalization and merge logic in `config.sh`:
+
+- `@test "v1 config protectDefaultBranch true — normalized to warn"` — Write v1 config, verify normalization.
+- `@test "v1 config protectDefaultBranch false — normalized to off"` — Write v1 config, verify normalization.
+- `@test "v2 config with all new keys — works as specified"` — Write full v2 config, verify all keys accessible.
+- `@test "missing new keys — defaults used"` — Write minimal config, verify defaults fill in.
+
+### General Testing Patterns
+
+Each test should:
+1. Create a temporary git repository with controlled state in `setup()`.
+2. Source the script under test with appropriate `SCRIPT_DIR` and config paths set.
+3. Call the function directly and capture output/return code.
+4. Use `[ "$status" -eq 0 ]` and `[[ "$output" == *"expected"* ]]` for assertions.
+5. Clean up in `teardown()`.
+
+Avoid testing hook scripts end-to-end (those require the Claude Code runtime). Focus on testing the library functions that hooks call.
+
+## Files to Create or Modify
+- plugins/git-pilot/tests/test_helper/common.bash (new)
+- plugins/git-pilot/tests/branch-freshness.bats (new)
+- plugins/git-pilot/tests/drift-detection.bats (new)
+- plugins/git-pilot/tests/rebase.bats (new)
+- plugins/git-pilot/tests/agent-detection.bats (new)
+- plugins/git-pilot/tests/worktree.bats (new)
+- plugins/git-pilot/tests/stash.bats (new)
+- plugins/git-pilot/tests/protected-branch.bats (new)
+- plugins/git-pilot/tests/config-compat.bats (new)
+
+## Validation Notes
+
+### PASSED: Test file names match the spec-required names
+
+All 8 required test files now exist with the correct names. `state.bats` remains as a bonus file.
+
+### Criteria Status
+
+- [x] `plugins/git-pilot/tests/test_helper/common.bash` exists with shared setup/teardown fixtures that create temporary git repos with controlled state.
+- [x] All 8 test files exist: `branch-freshness.bats`, `drift-detection.bats`, `rebase.bats`, `agent-detection.bats`, `worktree.bats`, `stash.bats`, `protected-branch.bats`, `config-compat.bats`.
+- [x] Each `.bats` file sources the appropriate script under test and the shared helper.
+- [x] Each test scenario from spec section 8.2 has a corresponding `@test` block.
+- [x] All tests can be run with `bats plugins/git-pilot/tests/` (assuming bats-core is installed).
+- [x] Tests use temporary directories (cleaned up in teardown) and do not modify the real repository.

From b488a4c6337d72d4515c8a063f2df16cc44d3971 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:29 +0100
Subject: [PATCH 2/7] feat(git-pilot): update config schema and state for v2

---
 plugins/git-pilot/defaults/config.json | 23 +++++++++-
 plugins/git-pilot/scripts/config.sh    | 10 +++++
 plugins/git-pilot/scripts/state.sh     | 61 +++++++++++---------------
 3 files changed, 56 insertions(+), 38 deletions(-)

diff --git a/plugins/git-pilot/defaults/config.json b/plugins/git-pilot/defaults/config.json
index c87c79e..71c3013 100644
--- a/plugins/git-pilot/defaults/config.json
+++ b/plugins/git-pilot/defaults/config.json
@@ -2,7 +2,10 @@
   "git": {
     "defaultBranch": "main",
     "autoInit": true,
-    "protectDefaultBranch": true
+    "protectDefaultBranch": "warn",
+    "autoFetch": true,
+    "fetchRetries": 2,
+    "fetchRetryDelaySec": 3
   },
   "branch": {
     "pattern": "{{type}}/{{description}}",
@@ -13,7 +16,9 @@
     "descriptionSeparator": "-",
     "descriptionCase": "kebab",
     "maxLength": 72,
-    "autoCreate": true
+    "autoCreate": true,
+    "unrelatedWorkDetection": true,
+    "autoStashOnSwitch": true
   },
   "commit": {
     "pattern": "{{type}}({{scope}}): {{description}}",
@@ -53,6 +58,11 @@
     "autoPush": false,
     "pushOnFinish": "ask"
   },
+  "rebase": {
+    "autoRebaseBeforePush": true,
+    "conflictStrategy": "prompt",
+    "allowForcePush": "ask"
+  },
   "mergeRequest": {
     "enabled": true,
     "createOnFinish": "ask",
@@ -63,6 +73,15 @@
     "labels": [],
     "assignToSelf": true
   },
+  "worktree": {
+    "enabled": true,
+    "basePath": "../{{project}}-worktrees",
+    "cleanupOnMerge": true
+  },
+  "agentTeams": {
+    "suppressPromptsForAgents": true,
+    "orchestratorOnly": ["push", "mr"]
+  },
   "summary": {
     "includeFileChanges": true,
     "includeDiff": false,
diff --git a/plugins/git-pilot/scripts/config.sh b/plugins/git-pilot/scripts/config.sh
index e56d443..e8f96b4 100644
--- a/plugins/git-pilot/scripts/config.sh
+++ b/plugins/git-pilot/scripts/config.sh
@@ -30,3 +30,13 @@ get_config() {
   local default="$3"
   echo "$config" | jq -r "if ($key) == null then \"$default\" else ($key) end"
 }
+
+normalize_protect_default_branch() {
+  local value="$1"
+  case "$value" in
+    true)  echo "warn" ;;
+    false) echo "off" ;;
+    warn|block|off) echo "$value" ;;
+    *) echo "warn" ;;
+  esac
+}
diff --git a/plugins/git-pilot/scripts/state.sh b/plugins/git-pilot/scripts/state.sh
index 899156a..e9a58a7 100644
--- a/plugins/git-pilot/scripts/state.sh
+++ b/plugins/git-pilot/scripts/state.sh
@@ -10,11 +10,17 @@ get_state_file() {
   echo "/tmp/git-pilot-${session_id}.json"
 }
 
-# Reads the state file content. Returns {} if the file is missing or unreadable.
+# Reads the state file content. Returns {} if the file is missing or contains invalid JSON.
 read_state() {
   local state_file="$1"
-  if [ -f "$state_file" ]; then
-    cat "$state_file"
+  if [[ -f "$state_file" ]]; then
+    local content
+    content=$(cat "$state_file")
+    if echo "$content" | jq empty 2>/dev/null; then
+      echo "$content"
+    else
+      echo "{}"
+    fi
   else
     echo "{}"
   fi
@@ -41,51 +47,34 @@ write_state() {
 }
 
 # Creates the initial session state file.
-# Parameters: session_id, working_branch (optional), previous_branch (optional).
+# Parameters: session_id, working_branch (optional), previous_branch (optional),
+#             base_branch (optional), branch_purpose (optional).
 init_state() {
-  local session_id="$1"
-  local working_branch="${2:-}"
-  local previous_branch="${3:-}"
-  local state_file
+  local session_id="$1" working_branch="${2:-}" previous_branch="${3:-}"
+  local base_branch="${4:-}" branch_purpose="${5:-}"
+  local state_file head_at_start=""
   state_file=$(get_state_file "$session_id")
-
-  # Capture HEAD commit at session start for change detection
-  local head_at_start=""
   if command -v git >/dev/null 2>&1 && git rev-parse HEAD >/dev/null 2>&1; then
     head_at_start=$(git rev-parse HEAD 2>/dev/null || true)
   fi
-
   local content
   content=$(jq -n \
-    --arg sid "$session_id" \
-    --arg start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    --arg wb "$working_branch" \
-    --arg pb "$previous_branch" \
-    --arg head "$head_at_start" \
-    '{
-      sessionId: $sid,
-      startTime: $start,
-      workingBranch: $wb,
-      previousBranch: $pb,
-      headAtStart: $head,
-      changeCount: 0,
-      lastCommitAt: null,
-      modifiedFiles: [],
-      remoteSkipped: false
-    }')
-
+    --arg sid "$session_id" --arg start "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg wb "$working_branch" --arg pb "$previous_branch" \
+    --arg head "$head_at_start" --arg bb "$base_branch" --arg bp "$branch_purpose" \
+    '{ sessionId:$sid, startTime:$start, workingBranch:$wb, previousBranch:$pb,
+       headAtStart:$head, baseBranch:$bb, branchPurpose:$bp, changeCount:0,
+       lastCommitAt:null, modifiedFiles:[], remoteSkipped:false, lastFetchAt:null,
+       isAgent:false, agentRole:null, activeWorktrees:[], stashRefs:[] }')
   write_state "$state_file" "$content"
 }
 
 # Reads the current state, applies a jq filter, and atomically writes back.
-# Parameters: state_file, jq_filter.
+# Parameters: state_file, [jq_args...], jq_filter.
 update_state() {
-  local state_file="$1"
-  local jq_filter="$2"
-  local current
-  current=$(read_state "$state_file")
-  local updated
-  updated=$(echo "$current" | jq "$jq_filter")
+  local state_file="$1"; shift
+  local current; current=$(read_state "$state_file")
+  local updated; updated=$(echo "$current" | jq "$@")
   write_state "$state_file" "$updated"
 }
 

From 5ad55c9bb67e846698142442fed3be057509a943 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:33 +0100
Subject: [PATCH 3/7] feat(git-pilot): add v2 shared libraries

---
 plugins/git-pilot/scripts/agent.sh     |  79 ++++++++++
 plugins/git-pilot/scripts/git-utils.sh | 176 +++++++++++++++++++++
 plugins/git-pilot/scripts/rebase.sh    | 206 +++++++++++++++++++++++++
 plugins/git-pilot/scripts/worktree.sh  | 173 +++++++++++++++++++++
 4 files changed, 634 insertions(+)
 create mode 100644 plugins/git-pilot/scripts/agent.sh
 create mode 100644 plugins/git-pilot/scripts/rebase.sh
 create mode 100644 plugins/git-pilot/scripts/worktree.sh

diff --git a/plugins/git-pilot/scripts/agent.sh b/plugins/git-pilot/scripts/agent.sh
new file mode 100644
index 0000000..bd5857d
--- /dev/null
+++ b/plugins/git-pilot/scripts/agent.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=state.sh
+source "$SCRIPT_DIR/state.sh"
+# shellcheck source=config.sh
+source "$SCRIPT_DIR/config.sh"
+
+# Detects whether the current session is running as a spawned agent.
+#
+# Detection order:
+#   1. CLAUDE_SPAWNED_BY env var non-empty (primary, set by Claude Code)
+#   2. Session state .isAgent == true (fallback for resilience)
+#
+# Parameters:
+#   $1 (optional): session ID for state-file fallback lookup
+#
+# Returns:
+#   0 if agent context detected, 1 otherwise
+is_agent_context() {
+  # Primary: check Claude Code spawned-by indicator
+  if [[ -n "${CLAUDE_SPAWNED_BY:-}" ]]; then
+    return 0
+  fi
+
+  # Secondary: check for agent role in session state
+  local session_id="${1:-}"
+  if [[ -n "$session_id" ]]; then
+    local state_file
+    state_file=$(get_state_file "$session_id")
+    local state
+    state=$(read_state "$state_file")
+    local is_agent
+    is_agent=$(echo "$state" | jq -r '.isAgent // false')
+    if [[ "$is_agent" == "true" ]]; then
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+# Checks whether a named operation should be suppressed for agents.
+#
+# Returns 0 (restricted) when agentTeams.suppressPromptsForAgents is true
+# AND the operation name appears in the agentTeams.orchestratorOnly array.
+#
+# Parameters:
+#   $1: config JSON (the merged config object from load_config())
+#   $2: operation name string -- one of "push", "mr", "branch-prompt",
+#       "auto-commit", "rebase", "session-summary", "branch-freshness"
+#
+# Returns:
+#   0 if the operation is restricted (agent should skip it)
+#   1 if the operation is not restricted
+is_operation_agent_restricted() {
+  local config="$1"
+  local operation="$2"
+
+  local suppress
+  suppress=$(get_config "$config" '.agentTeams.suppressPromptsForAgents' 'true')
+
+  if [[ "$suppress" != "true" ]]; then
+    return 1  # Not suppressed
+  fi
+
+  # Check if this specific operation is orchestrator-only
+  local restricted
+  restricted=$(echo "$config" | jq -r --arg op "$operation" \
+    '.agentTeams.orchestratorOnly // ["push", "mr"] | map(select(. == $op)) | length')
+
+  if [[ "$restricted" -gt 0 ]]; then
+    return 0  # Restricted to orchestrator
+  fi
+
+  return 1
+}
diff --git a/plugins/git-pilot/scripts/git-utils.sh b/plugins/git-pilot/scripts/git-utils.sh
index ed0f788..9aa546e 100644
--- a/plugins/git-pilot/scripts/git-utils.sh
+++ b/plugins/git-pilot/scripts/git-utils.sh
@@ -37,3 +37,179 @@ sanitize_branch_name() {
   local name="$1"
   echo "$name" | sed 's/[^a-zA-Z0-9._/-]//g'
 }
+
+is_detached_head() {
+  [[ -z "$(git branch --show-current 2>/dev/null)" ]] && git rev-parse HEAD >/dev/null 2>&1
+}
+
+get_branch_tracking_status() {
+  local branch="$1"
+  local remote_name="$2"
+  local remote_branch="${remote_name}/${branch}"
+
+  # Check if remote branch exists
+  if ! git rev-parse --verify "$remote_branch" >/dev/null 2>&1; then
+    echo "no-remote"
+    return
+  fi
+
+  local local_ref remote_ref base_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "$remote_branch" 2>/dev/null)
+  base_ref=$(git merge-base "$branch" "$remote_branch" 2>/dev/null || true)
+
+  if [[ "$local_ref" == "$remote_ref" ]]; then
+    echo "up-to-date"
+  elif [[ "$local_ref" == "$base_ref" ]]; then
+    local behind_count
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "behind:${behind_count}"
+  elif [[ "$remote_ref" == "$base_ref" ]]; then
+    local ahead_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    echo "ahead:${ahead_count}"
+  else
+    local ahead_count behind_count
+    ahead_count=$(git rev-list --count "${remote_branch}..${branch}" 2>/dev/null)
+    behind_count=$(git rev-list --count "${branch}..${remote_branch}" 2>/dev/null)
+    echo "diverged:${ahead_count}:${behind_count}"
+  fi
+}
+
+fetch_with_retry() {
+  local remote_name="$1"
+  local config="$2"
+  local specific_branch="${3:-}"
+
+  local max_retries
+  max_retries=$(get_config "$config" '.git.fetchRetries' '2')
+  local retry_delay
+  retry_delay=$(get_config "$config" '.git.fetchRetryDelaySec' '3')
+
+  local fetch_args="$remote_name"
+  if [[ -n "$specific_branch" ]]; then
+    fetch_args="$remote_name $specific_branch"
+  fi
+
+  local attempt=0
+  local last_error=""
+
+  while (( attempt <= max_retries )); do
+    # shellcheck disable=SC2086 # Intentional word splitting: fetch_args may contain "remote branch"
+    if git fetch $fetch_args 2>/dev/null; then
+      return 0
+    fi
+
+    # shellcheck disable=SC2086 # Intentional word splitting: fetch_args may contain "remote branch"
+    last_error=$(git fetch $fetch_args 2>&1 || true)
+    attempt=$((attempt + 1))
+
+    if (( attempt <= max_retries )); then
+      sleep "$retry_delay"
+    fi
+  done
+
+  # All retries exhausted
+  echo "$last_error" >&2
+  return 1
+}
+
+derive_branch_purpose() {
+  local branch_name="$1"
+
+  # Strip type prefix (e.g., "feat/", "fix/")
+  local description
+  # shellcheck disable=SC2001 # sed regex not directly replaceable with ${var//pattern/replace}
+  description=$(echo "$branch_name" | sed 's|^[^/]*/||')
+
+  # Convert kebab-case/snake_case to words
+  description=$(echo "$description" | tr '-' ' ' | tr '_' ' ')
+
+  echo "$description"
+}
+
+# Auto-stash uncommitted changes on branch switch.
+# Records the stash ref in session state for later restoration.
+# Returns 0 on success, 1 if nothing to stash or stash push fails.
+auto_stash() {
+  local current_branch="$1"
+  local session_id="$2"
+
+  if ! has_uncommitted_changes; then
+    return 1  # Nothing to stash
+  fi
+
+  local stash_msg="git-pilot auto-stash on ${current_branch}"
+  if git stash push -m "$stash_msg" >/dev/null 2>&1; then
+    local stash_ref
+    stash_ref=$(git stash list --format='%gd' | head -1)
+
+    # Record in session state
+    if [[ -n "$session_id" ]]; then
+      local state_file
+      state_file=$(get_state_file "$session_id")
+      # shellcheck disable=SC2016 # $ref, $branch, $msg are jq variables, not shell variables
+      update_state "$state_file" \
+        --arg ref "$stash_ref" \
+        --arg branch "$current_branch" \
+        --arg msg "$stash_msg" \
+        '.stashRefs += [{ref: $ref, branch: $branch, message: $msg, createdAt: (now | todate)}]'
+    fi
+
+    return 0
+  fi
+
+  return 1
+}
+
+# Auto-restore a previously stashed set of changes when switching back to a branch.
+# Looks up the stash by branch in session state, finds the current stash index
+# by message, and pops it. On success, removes the entry from state.
+# Returns 0 on success, 1 if no stash found, session_id is empty, or pop fails.
+auto_restore_stash() {
+  local target_branch="$1"
+  local session_id="$2"
+
+  if [[ -z "$session_id" ]]; then
+    return 1
+  fi
+
+  local state_file
+  state_file=$(get_state_file "$session_id")
+  local state
+  state=$(read_state "$state_file")
+
+  # Find stash for this branch
+  local stash_ref
+  # shellcheck disable=SC2016 # $branch is a jq variable, not a shell variable
+  stash_ref=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .ref' | head -1)
+
+  if [[ -z "$stash_ref" ]] || [[ "$stash_ref" == "null" ]]; then
+    return 1  # No stash for this branch
+  fi
+
+  # Find the stash index by message (stash indices shift as stashes are added/removed)
+  local stash_msg
+  # shellcheck disable=SC2016 # $branch is a jq variable, not a shell variable
+  stash_msg=$(echo "$state" | jq -r \
+    --arg branch "$target_branch" \
+    '.stashRefs[] | select(.branch == $branch) | .message' | head -1)
+
+  local stash_index
+  stash_index=$(git stash list --format='%gd %s' | grep "$stash_msg" | head -1 | cut -d' ' -f1)
+
+  if [[ -n "$stash_index" ]]; then
+    if git stash pop "$stash_index" >/dev/null 2>&1; then
+      # shellcheck disable=SC2016 # $branch is a jq variable, not a shell variable
+      # Remove from state on successful pop
+      update_state "$state_file" \
+        --arg branch "$target_branch" \
+        '.stashRefs = [.stashRefs[] | select(.branch != $branch)]'
+      return 0
+    fi
+  fi
+
+  return 1
+}
diff --git a/plugins/git-pilot/scripts/rebase.sh b/plugins/git-pilot/scripts/rebase.sh
new file mode 100644
index 0000000..2b80b76
--- /dev/null
+++ b/plugins/git-pilot/scripts/rebase.sh
@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Rebase and conflict resolution library for git-pilot plugin.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=config.sh
+source "$SCRIPT_DIR/config.sh"
+# shellcheck source=git-utils.sh
+source "$SCRIPT_DIR/git-utils.sh"
+
+# Detects how many commits the base branch has advanced since the feature
+# branch diverged.
+#
+# Arguments:
+#   $1 - current branch name
+#   $2 - base branch name
+#   $3 - remote name
+#
+# Output (stdout):
+#   "no-drift"            - base branch has no new commits
+#   "drifted:N"           - base branch has N new commits
+#   "no-common-ancestor"  - cannot determine merge base
+#
+# Returns: 0 on success, 1 on fetch failure
+get_base_branch_drift() {
+  local current_branch="$1"
+  local base_branch="$2"
+  local remote_name="$3"
+  local remote_base="${remote_name}/${base_branch}"
+
+  # Fetch latest base branch state
+  git fetch "$remote_name" "$base_branch" 2>/dev/null || return 1
+
+  # Find the merge base between current branch and remote base
+  local merge_base
+  merge_base=$(git merge-base "$current_branch" "$remote_base" 2>/dev/null || true)
+
+  if [[ -z "$merge_base" ]]; then
+    echo "no-common-ancestor"
+    return
+  fi
+
+  # Count commits on base branch since the branch point
+  local drift_count
+  drift_count=$(git rev-list --count "${merge_base}..${remote_base}" 2>/dev/null)
+
+  if [[ "$drift_count" -eq 0 ]]; then
+    echo "no-drift"
+  else
+    echo "drifted:${drift_count}"
+  fi
+}
+
+# Performs a rebase onto a target branch with clean error categorization.
+#
+# Arguments:
+#   $1 - target branch to rebase onto (e.g., origin/main)
+#
+# Output (stdout):
+#   "success"              - rebase completed cleanly
+#   "conflict"             - rebase stopped due to merge conflicts
+#   "error:dirty-worktree" - working tree has uncommitted changes
+#   "error:<output>"       - rebase failed for another reason
+#
+# Returns: 0 on success, 1 on conflict or error
+attempt_rebase() {
+  local target_branch="$1"
+
+  # Ensure clean working tree
+  if has_uncommitted_changes; then
+    echo "error:dirty-worktree"
+    return 1
+  fi
+
+  # Attempt rebase
+  local rebase_output
+  if rebase_output=$(git rebase "$target_branch" 2>&1); then
+    echo "success"
+    return 0
+  else
+    # Check if it's a conflict
+    if git diff --name-only --diff-filter=U 2>/dev/null | head -1 | grep -q .; then
+      echo "conflict"
+      return 1
+    else
+      echo "error:${rebase_output}"
+      return 1
+    fi
+  fi
+}
+
+# Returns a JSON array describing each conflicting file during a rebase.
+#
+# Output (stdout): JSON array of objects with fields:
+#   file            - relative file path
+#   type            - "both-modified", "deleted-by-us", or "deleted-by-them"
+#   conflictRegions - count of <<<<<<< markers in the file
+#
+# Returns: 0
+get_conflict_details() {
+  local conflict_files
+  conflict_files=$(git diff --name-only --diff-filter=U 2>/dev/null)
+
+  if [[ -z "$conflict_files" ]]; then
+    echo "[]"
+    return
+  fi
+
+  local result="["
+  local first=true
+
+  while IFS= read -r file; do
+    local ours_exists theirs_exists
+    ours_exists=$(git ls-files --stage "$file" 2>/dev/null | grep -c "^[0-9]* [a-f0-9]* 2" || echo "0")
+    theirs_exists=$(git ls-files --stage "$file" 2>/dev/null | grep -c "^[0-9]* [a-f0-9]* 3" || echo "0")
+
+    local conflict_type="both-modified"
+    if [[ "$ours_exists" == "0" ]]; then
+      conflict_type="deleted-by-us"
+    elif [[ "$theirs_exists" == "0" ]]; then
+      conflict_type="deleted-by-them"
+    fi
+
+    local marker_count=0
+    if [[ -f "$file" ]]; then
+      marker_count=$(grep -c '^<<<<<<< ' "$file" 2>/dev/null || echo "0")
+    fi
+
+    if [[ "$first" == "true" ]]; then
+      first=false
+    else
+      result+=","
+    fi
+    result+=$(jq -n \
+      --arg f "$file" \
+      --arg t "$conflict_type" \
+      --argjson m "$marker_count" \
+      '{file: $f, type: $t, conflictRegions: $m}')
+  done <<< "$conflict_files"
+
+  result+="]"
+  echo "$result"
+}
+
+# Returns a recommendation string for a given conflict type and region count.
+#
+# Arguments:
+#   $1 - conflict type: "both-modified", "deleted-by-us", or "deleted-by-them"
+#   $2 - number of conflict regions (integer)
+#
+# Output (stdout): recommendation string
+get_conflict_recommendation() {
+  local conflict_type="$1"
+  local regions="$2"
+
+  case "$conflict_type" in
+    deleted-by-us)
+      echo "File was deleted locally but modified on base. If the deletion was intentional, accept ours (delete). Otherwise, accept theirs." ;;
+    deleted-by-them)
+      echo "File was deleted on base but modified locally. If your changes are still needed, accept ours. Otherwise, accept theirs (delete)." ;;
+    both-modified)
+      if [[ "$regions" -le 1 ]]; then
+        echo "Single conflict region -- likely a small overlap. Manual review recommended."
+      elif [[ "$regions" -gt 3 ]]; then
+        echo "Multiple conflict regions -- significant concurrent changes. Manual review required."
+      else
+        echo "Manual review recommended."
+      fi
+      ;;
+  esac
+}
+
+# Detects whether a force push is required after rebase.
+#
+# Arguments:
+#   $1 - branch name
+#   $2 - remote name
+#
+# Returns:
+#   0 - force push is needed (remote tracking branch exists, refs differ,
+#       and remote is not an ancestor of local)
+#   1 - normal push is fine
+needs_force_push() {
+  local branch="$1"
+  local remote_name="$2"
+
+  # Check if remote tracking branch exists
+  if ! git rev-parse --verify "${remote_name}/${branch}" >/dev/null 2>&1; then
+    return 1  # No remote branch, normal push works
+  fi
+
+  # Check if local and remote have diverged after rebase
+  local local_ref remote_ref
+  local_ref=$(git rev-parse "$branch" 2>/dev/null)
+  remote_ref=$(git rev-parse "${remote_name}/${branch}" 2>/dev/null)
+
+  if [[ "$local_ref" != "$remote_ref" ]]; then
+    # Check if remote is NOT an ancestor of local (diverged, not just ahead)
+    if ! git merge-base --is-ancestor "$remote_ref" "$local_ref" 2>/dev/null; then
+      return 0  # Needs force push
+    fi
+  fi
+
+  return 1
+}
diff --git a/plugins/git-pilot/scripts/worktree.sh b/plugins/git-pilot/scripts/worktree.sh
new file mode 100644
index 0000000..b44c9a1
--- /dev/null
+++ b/plugins/git-pilot/scripts/worktree.sh
@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Worktree management library for git-pilot.
+# Provides functions to create, remove, list, and merge git worktrees,
+# with a JSON registry for tracking active worktrees.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./config.sh
+source "$SCRIPT_DIR/config.sh"
+
+# Registry file lives inside the git directory (works correctly in worktree contexts).
+WORKTREE_REGISTRY="$(git rev-parse --git-dir 2>/dev/null)/git-pilot-worktrees.json"
+
+# Creates a git worktree at the configured base path with the given branch.
+# Parameters:
+#   $1 - config JSON (from load_config)
+#   $2 - branch name to create
+#   $3 - base branch to create from
+#   $4 - session ID (optional)
+# Returns: echoes the worktree path on stdout on success.
+# On failure: writes "error:<git output>" to stderr and returns 1.
+create_worktree() {
+  local config="$1"
+  local branch_name="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local project_name
+  project_name=$(basename "$(git rev-parse --show-toplevel)")
+
+  local base_path
+  base_path=$(get_config "$config" '.worktree.basePath' "../{{project}}-worktrees")
+  base_path="${base_path//\{\{project\}\}/$project_name}"
+
+  local dir_name
+  dir_name=$(echo "$branch_name" | tr '/' '-')
+  local worktree_path="${base_path}/${dir_name}"
+
+  mkdir -p "$(dirname "$worktree_path")"
+
+  local output
+  if output=$(git worktree add "$worktree_path" -b "$branch_name" "$base_branch" 2>&1); then
+    register_worktree "$worktree_path" "$branch_name" "$base_branch" "$session_id"
+    echo "$worktree_path"
+    return 0
+  else
+    echo "error:${output}" >&2
+    return 1
+  fi
+}
+
+# Removes a git worktree and unregisters it from the registry.
+# Parameters:
+#   $1 - worktree path
+#   $2 - "true" for force removal (optional, default "false")
+# Returns: 0 on success, 1 on failure.
+remove_worktree() {
+  local worktree_path="$1"
+  local force="${2:-false}"
+
+  local flags=""
+  if [[ "$force" == "true" ]]; then
+    flags="--force"
+  fi
+
+  # shellcheck disable=SC2086
+  if git worktree remove "$worktree_path" $flags 2>/dev/null; then
+    unregister_worktree "$worktree_path"
+    return 0
+  else
+    return 1
+  fi
+}
+
+# Adds a worktree entry to the JSON registry using atomic writes.
+# Parameters:
+#   $1 - worktree path
+#   $2 - branch name
+#   $3 - base branch
+#   $4 - session ID (optional)
+register_worktree() {
+  local path="$1"
+  local branch="$2"
+  local base_branch="$3"
+  local session_id="${4:-}"
+
+  local registry
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    registry=$(cat "$WORKTREE_REGISTRY")
+  else
+    registry='{"worktrees":[]}'
+  fi
+
+  local entry
+  entry=$(jq -n \
+    --arg p "$path" \
+    --arg b "$branch" \
+    --arg bb "$base_branch" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg sid "$session_id" \
+    '{path:$p, branch:$b, baseBranch:$bb, createdAt:$ts, createdBy:$sid, status:"active"}')
+
+  registry=$(echo "$registry" | jq --argjson e "$entry" '.worktrees += [$e]')
+
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+# Removes a worktree entry from the JSON registry using atomic writes.
+# Parameters:
+#   $1 - worktree path to remove
+unregister_worktree() {
+  local path="$1"
+  if [[ ! -f "$WORKTREE_REGISTRY" ]]; then
+    return
+  fi
+  local registry
+  registry=$(cat "$WORKTREE_REGISTRY")
+  registry=$(echo "$registry" | jq --arg p "$path" \
+    '.worktrees = [.worktrees[] | select(.path != $p)]')
+  local tmp="${WORKTREE_REGISTRY}.tmp.$$"
+  echo "$registry" > "$tmp" && mv "$tmp" "$WORKTREE_REGISTRY"
+}
+
+# Returns the full registry JSON, or an empty structure if no registry exists.
+# Returns: JSON string on stdout.
+list_worktrees() {
+  if [[ -f "$WORKTREE_REGISTRY" ]]; then
+    cat "$WORKTREE_REGISTRY"
+  else
+    echo '{"worktrees":[]}'
+  fi
+}
+
+# Merges a worktree branch into the target branch.
+# If worktree.cleanupOnMerge is true, removes the worktree and deletes the branch after merge.
+# Parameters:
+#   $1 - worktree path
+#   $2 - target branch to merge into
+#   $3 - config JSON (from load_config)
+# Returns: echoes "success" (exit 0), "conflict" (exit 1), or "error:cannot-determine-branch" (exit 1).
+merge_worktree_branch() {
+  local worktree_path="$1"
+  local target_branch="$2"
+  local config="$3"
+
+  local wt_branch
+  wt_branch=$(git -C "$worktree_path" branch --show-current 2>/dev/null)
+
+  if [[ -z "$wt_branch" ]]; then
+    echo "error:cannot-determine-branch"
+    return 1
+  fi
+
+  git checkout "$target_branch" 2>/dev/null || return 1
+
+  local merge_output
+  # shellcheck disable=SC2034 # merge_output captures stderr; only the exit code is used
+  if merge_output=$(git merge "$wt_branch" --no-edit 2>&1); then
+    echo "success"
+    local cleanup
+    cleanup=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+    if [[ "$cleanup" == "true" ]]; then
+      remove_worktree "$worktree_path" "false"
+      git branch -d "$wt_branch" 2>/dev/null || true
+    fi
+    return 0
+  else
+    echo "conflict"
+    return 1
+  fi
+}

From 8898346a9a22f847bb4eb6361520f81241544703 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:37 +0100
Subject: [PATCH 4/7] feat(git-pilot): update hooks for v2 lifecycle

---
 plugins/git-pilot/hooks/hooks.json          |  89 ++++++------
 plugins/git-pilot/scripts/post-bash.sh      |  97 ++++++++-----
 plugins/git-pilot/scripts/post-write.sh     |   7 +
 plugins/git-pilot/scripts/pre-commit.sh     |  95 ++++++++++---
 plugins/git-pilot/scripts/prompt-context.sh |  42 ++++++
 plugins/git-pilot/scripts/session-start.sh  |  65 ++++++++-
 plugins/git-pilot/scripts/session-stop.sh   | 142 ++++++++++++++++++++
 7 files changed, 434 insertions(+), 103 deletions(-)
 create mode 100755 plugins/git-pilot/scripts/prompt-context.sh

diff --git a/plugins/git-pilot/hooks/hooks.json b/plugins/git-pilot/hooks/hooks.json
index e98a5f4..aaf0b96 100644
--- a/plugins/git-pilot/hooks/hooks.json
+++ b/plugins/git-pilot/hooks/hooks.json
@@ -1,62 +1,53 @@
 {
   "description": "git-pilot: Automated git workflow management",
   "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
+    "SessionStart": [{
+      "matcher": "startup",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh",
+        "timeout": 30
+      }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/prompt-context.sh",
+        "timeout": 5
+      }]
+    }],
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-commit.sh",
+        "timeout": 10
+      }]
+    }],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-write.sh",
-            "timeout": 10
-          }
-        ]
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-write.sh",
+          "timeout": 10
+        }]
       },
       {
         "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-bash.sh",
-            "timeout": 10
-          }
-        ]
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/post-bash.sh",
+          "timeout": 15
+        }]
       }
     ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh",
-            "timeout": 30
-          }
-        ]
-      }
-    ]
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.sh",
+        "timeout": 45
+      }]
+    }]
   }
 }
diff --git a/plugins/git-pilot/scripts/post-bash.sh b/plugins/git-pilot/scripts/post-bash.sh
index 93271d9..2783105 100755
--- a/plugins/git-pilot/scripts/post-bash.sh
+++ b/plugins/git-pilot/scripts/post-bash.sh
@@ -7,14 +7,17 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/config.sh"
 # shellcheck source=./git-utils.sh
 source "$SCRIPT_DIR/git-utils.sh"
+# shellcheck source=./agent.sh
+source "$SCRIPT_DIR/agent.sh"
 
 input=$(cat)
 
 cwd=$(echo "$input" | jq -r '.cwd // empty')
 command=$(echo "$input" | jq -r '.tool_input.command // empty')
+session_id=$(echo "$input" | jq -r '.session_id // empty')
 
-# Only care about git commit commands
-if [[ -z "$command" ]] || ! echo "$command" | grep -qE 'git\s+commit'; then
+# Only care about git commit and git push commands
+if [[ -z "$command" ]] || ! echo "$command" | grep -qE 'git\s+(commit|push)'; then
   echo '{"continue": true}'
   exit 0
 fi
@@ -32,42 +35,68 @@ if ! is_git_repo; then
 fi
 
 config=$(load_config "$cwd")
-push_on_finish=$(get_config "$config" '.remote.pushOnFinish' 'ask')
-auto_push=$(get_config "$config" '.remote.autoPush' 'false')
 
-if [[ "$auto_push" == "true" ]]; then
-  push_on_finish="always"
+# Agent suppression: skip push prompts for agent contexts where push is restricted
+if is_agent_context "$session_id"; then
+  if is_operation_agent_restricted "$config" "push"; then
+    echo '{"continue": true}'
+    exit 0
+  fi
 fi
 
-# Only prompt when mode is "ask" — "always" and "never" are handled elsewhere
-if [[ "$push_on_finish" != "ask" ]]; then
-  echo '{"continue": true}'
-  exit 0
+# --- Push prompt after git commit (v1 logic) ---
+if echo "$command" | grep -qE 'git\s+commit'; then
+  push_on_finish=$(get_config "$config" '.remote.pushOnFinish' 'ask')
+  auto_push=$(get_config "$config" '.remote.autoPush' 'false')
+
+  if [[ "$auto_push" == "true" ]]; then
+    push_on_finish="always"
+  fi
+
+  # Only prompt when mode is "ask" — "always" and "never" are handled elsewhere
+  if [[ "$push_on_finish" == "ask" ]] && has_remote; then
+    current_branch=$(get_current_branch)
+    remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
+
+    # Check for unpushed commits
+    unpushed=$(git log '@{u}..HEAD' --oneline 2>/dev/null || true)
+    if ! git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1; then
+      default_branch=$(get_default_branch "$config")
+      unpushed=$(git log "${default_branch}..${current_branch}" --oneline 2>/dev/null || true)
+    fi
+
+    if [[ -n "$unpushed" ]]; then
+      unpushed_count=$(echo "$unpushed" | wc -l | tr -d ' ')
+
+      # Emit push prompt — CLAUDE.md instructs Claude to act on this with AskUserQuestion
+      message="[git-pilot] ${unpushed_count} unpushed commit(s) on '${current_branch}'. Push command: git push -u ${remote_name} ${current_branch}"
+
+      jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+      exit 0
+    fi
+  fi
 fi
 
-if ! has_remote; then
-  echo '{"continue": true}'
-  exit 0
-fi
-
-current_branch=$(get_current_branch)
-remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
-
-# Check for unpushed commits
-unpushed=$(git log '@{u}..HEAD' --oneline 2>/dev/null || true)
-if ! git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1; then
-  default_branch=$(get_default_branch "$config")
-  unpushed=$(git log "${default_branch}..${current_branch}" --oneline 2>/dev/null || true)
+# --- Push rejection detection ---
+if echo "$command" | grep -qE 'git\s+push'; then
+  exit_code=$(echo "$input" | jq -r '.tool_result.exitCode // 0')
+  # shellcheck disable=SC2034  # extracted per spec; reserved for future use
+  stdout=$(echo "$input" | jq -r '.tool_result.stdout // empty')
+  stderr=$(echo "$input" | jq -r '.tool_result.stderr // empty')
+
+  if [[ "$exit_code" != "0" ]]; then
+    if echo "$stderr" | grep -qiE 'rejected|failed to push|non-fast-forward'; then
+      current_branch=$(get_current_branch)
+      remote_name=$(get_config "$config" '.remote.defaultName' 'origin')
+      message="[git-pilot] Push rejected -- remote '${remote_name}/${current_branch}' has new commits. Prompt the user:
+1. Pull and rebase, then retry push (git pull --rebase && git push)
+2. Force push with lease (git push --force-with-lease)
+3. Pull and merge (git pull)
+4. Cancel"
+      jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+      exit 0
+    fi
+  fi
 fi
 
-if [[ -z "$unpushed" ]]; then
-  echo '{"continue": true}'
-  exit 0
-fi
-
-unpushed_count=$(echo "$unpushed" | wc -l | tr -d ' ')
-
-# Emit push prompt — CLAUDE.md instructs Claude to act on this with AskUserQuestion
-message="[git-pilot] ${unpushed_count} unpushed commit(s) on '${current_branch}'. Push command: git push -u ${remote_name} ${current_branch}"
-
-jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
+echo '{"continue": true}'
diff --git a/plugins/git-pilot/scripts/post-write.sh b/plugins/git-pilot/scripts/post-write.sh
index 17c260d..6900b63 100755
--- a/plugins/git-pilot/scripts/post-write.sh
+++ b/plugins/git-pilot/scripts/post-write.sh
@@ -8,6 +8,8 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/config.sh"
 # shellcheck source=./state.sh
 source "$SCRIPT_DIR/state.sh"
+# shellcheck source=./agent.sh
+source "$SCRIPT_DIR/agent.sh"
 
 # Read input from stdin
 input=$(cat)
@@ -51,6 +53,11 @@ updated_state=$(echo "$current_state" | jq \
 # Write updated state atomically
 write_state "$state_file" "$updated_state"
 
+# Agent suppression: track changes but suppress commit suggestion
+if is_agent_context "$session_id"; then
+  exit 0
+fi
+
 # Check if threshold is reached
 if [[ "$change_count" -lt "$threshold" ]]; then
   exit 0
diff --git a/plugins/git-pilot/scripts/pre-commit.sh b/plugins/git-pilot/scripts/pre-commit.sh
index 895a135..aca6220 100755
--- a/plugins/git-pilot/scripts/pre-commit.sh
+++ b/plugins/git-pilot/scripts/pre-commit.sh
@@ -140,6 +140,29 @@ is_branch_creation_command() {
   return 1
 }
 
+# Returns 0 if the command is a branch switch command (not branch creation).
+# Sets SWITCH_TARGET to the target branch name.
+is_branch_switch_command() {
+  local cmd="$1"
+  SWITCH_TARGET=""
+
+  # git checkout <branch> (not -b/-B for new branch creation)
+  if [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+checkout[[:space:]]+-[bB] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  # git switch <branch> (not -c/-C for new branch creation)
+  if [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+([^-][^[:space:]]+) ]] && \
+     ! [[ "$cmd" =~ git[[:space:]]+switch[[:space:]]+-[cC] ]]; then
+    SWITCH_TARGET="${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  return 1
+}
+
 # --- Commit message parsing ---
 
 # Extracts the commit message from a git commit command.
@@ -466,6 +489,18 @@ fi
 # Load config
 CONFIG=$(load_config "$CWD")
 
+# --- Branch switch detection with auto-stash ---
+SWITCH_TARGET=""
+if is_branch_switch_command "$COMMAND"; then
+  auto_stash_cfg=$(get_config "$CONFIG" '.branch.autoStashOnSwitch' 'true')
+  if [[ "$auto_stash_cfg" == "true" ]] && has_uncommitted_changes; then
+    current_br=$(get_current_branch)
+    if auto_stash "$current_br" "$SESSION_ID"; then
+      output_allow_with_message "[git-pilot] Stashed uncommitted changes on '${current_br}' before switching to '${SWITCH_TARGET}'."
+    fi
+  fi
+fi
+
 # --- Branch creation detection ---
 BRANCH_NAME=""
 BRANCH_WARNING=""
@@ -504,12 +539,20 @@ parse_commit_message "$COMMAND"
 # If no -m flag found, skip validation (editor mode / --amend without -m)
 if [[ "$HAS_MESSAGE" != true ]]; then
   # Still check branch protection
-  PROTECT_DEFAULT=$(echo "$CONFIG" | jq -r '.git.protectDefaultBranch // true')
-  if [[ "$PROTECT_DEFAULT" == "true" ]]; then
-    if is_on_default_branch "$CONFIG" 2>/dev/null; then
-      DEFAULT_BR=$(get_default_branch "$CONFIG")
-      output_allow_with_message "[git-pilot] Warning: You are committing directly to '${DEFAULT_BR}'. Consider creating a feature branch first."
-    fi
+  protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+  protect_mode=$(normalize_protect_default_branch "$protect_mode")
+  if is_on_default_branch "$CONFIG" 2>/dev/null; then
+    default_br=$(get_default_branch "$CONFIG")
+    case "$protect_mode" in
+      warn)
+        output_allow_with_message "[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+        ;;
+      block)
+        output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+        ;;
+      off)
+        ;;
+    esac
   fi
   output_allow
 fi
@@ -521,12 +564,20 @@ SUBJECT=$(echo "$COMMIT_MSG" | head -n 1)
 WIP_PREFIX=$(echo "$CONFIG" | jq -r '.autoCommit.wipPrefix // "wip: "')
 if [[ "$SUBJECT" == "$WIP_PREFIX"* ]]; then
   # Check branch protection even for WIP commits
-  PROTECT_DEFAULT=$(echo "$CONFIG" | jq -r '.git.protectDefaultBranch // true')
-  if [[ "$PROTECT_DEFAULT" == "true" ]]; then
-    if is_on_default_branch "$CONFIG" 2>/dev/null; then
-      DEFAULT_BR=$(get_default_branch "$CONFIG")
-      output_allow_with_message "[git-pilot] Warning: You are committing directly to '${DEFAULT_BR}'. Consider creating a feature branch first."
-    fi
+  protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+  protect_mode=$(normalize_protect_default_branch "$protect_mode")
+  if is_on_default_branch "$CONFIG" 2>/dev/null; then
+    default_br=$(get_default_branch "$CONFIG")
+    case "$protect_mode" in
+      warn)
+        output_allow_with_message "[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+        ;;
+      block)
+        output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+        ;;
+      off)
+        ;;
+    esac
   fi
   output_allow
 fi
@@ -624,12 +675,20 @@ STRIPPED_MSG=""
 SYSTEM_MSG=""
 
 # Check branch protection
-PROTECT_DEFAULT=$(echo "$CONFIG" | jq -r '.git.protectDefaultBranch // true')
-if [[ "$PROTECT_DEFAULT" == "true" ]]; then
-  if is_on_default_branch "$CONFIG" 2>/dev/null; then
-    DEFAULT_BR=$(get_default_branch "$CONFIG")
-    SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${DEFAULT_BR}'. Consider creating a feature branch first."
-  fi
+protect_mode=$(get_config "$CONFIG" '.git.protectDefaultBranch' 'warn')
+protect_mode=$(normalize_protect_default_branch "$protect_mode")
+if is_on_default_branch "$CONFIG" 2>/dev/null; then
+  default_br=$(get_default_branch "$CONFIG")
+  case "$protect_mode" in
+    warn)
+      SYSTEM_MSG="[git-pilot] Warning: You are committing directly to '${default_br}'. Consider creating a feature branch first."
+      ;;
+    block)
+      output_block "[git-pilot] Commits to '${default_br}' are blocked by policy (git.protectDefaultBranch: block). Create a feature branch first using /branch."
+      ;;
+    off)
+      ;;
+  esac
 fi
 
 if strip_signatures "$CONFIG" "$COMMIT_MSG"; then
diff --git a/plugins/git-pilot/scripts/prompt-context.sh b/plugins/git-pilot/scripts/prompt-context.sh
new file mode 100755
index 0000000..da60932
--- /dev/null
+++ b/plugins/git-pilot/scripts/prompt-context.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=./config.sh
+source "$SCRIPT_DIR/config.sh"
+# shellcheck source=./git-utils.sh
+source "$SCRIPT_DIR/git-utils.sh"
+# shellcheck source=./agent.sh
+source "$SCRIPT_DIR/agent.sh"
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+
+if [[ -z "$cwd" ]]; then echo '{"continue": true}'; exit 0; fi
+cd "$cwd" 2>/dev/null || { echo '{"continue": true}'; exit 0; }
+if ! is_git_repo; then echo '{"continue": true}'; exit 0; fi
+
+config=$(load_config "$cwd")
+
+detection_enabled=$(get_config "$config" '.branch.unrelatedWorkDetection' 'true')
+if [[ "$detection_enabled" != "true" ]]; then echo '{"continue": true}'; exit 0; fi
+if is_agent_context "$session_id"; then echo '{"continue": true}'; exit 0; fi
+
+current_branch=$(get_current_branch)
+default_branch=$(get_default_branch "$config")
+
+# Skip if on default branch or detached HEAD
+if [[ -z "$current_branch" ]] || [[ "$current_branch" == "$default_branch" ]]; then
+  echo '{"continue": true}'; exit 0
+fi
+
+# Skip if branch has no commits
+commit_count=$(git rev-list --count "${default_branch}..${current_branch}" 2>/dev/null || echo "0")
+if [[ "$commit_count" == "0" ]]; then echo '{"continue": true}'; exit 0; fi
+
+branch_purpose=$(derive_branch_purpose "$current_branch")
+recent_commits=$(git log "${default_branch}..${current_branch}" --oneline --no-decorate -5 2>/dev/null || true)
+message="[git-pilot] Branch context: '${current_branch}' (${branch_purpose}). ${commit_count} commit(s). Recent: ${recent_commits}"
+jq -n --arg msg "$message" '{"continue": true, "systemMessage": $msg}'
diff --git a/plugins/git-pilot/scripts/session-start.sh b/plugins/git-pilot/scripts/session-start.sh
index c718146..86c8400 100755
--- a/plugins/git-pilot/scripts/session-start.sh
+++ b/plugins/git-pilot/scripts/session-start.sh
@@ -52,12 +52,64 @@ if ! is_git_repo; then
   fi
 fi
 
+# Step 6a: Fetch remote (after git init check, before branch detection)
+if is_git_repo && has_remote; then
+  auto_fetch=$(get_config "$CONFIG" '.git.autoFetch' 'true')
+  remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+  if [[ "$auto_fetch" == "true" ]]; then
+    retries=$(get_config "$CONFIG" '.git.fetchRetries' '2')
+    if ! fetch_with_retry "$remote_name" "$CONFIG"; then
+      messages+=("[git-pilot] Warning: Could not fetch from '${remote_name}' after ${retries} attempts. Network may be unavailable. Proceeding without remote sync.")
+    fi
+  fi
+fi
+
 # Step 7: Branch detection (only if we are in a git repo now)
 current_branch=""
 default_branch=$(get_config "$CONFIG" '.git.defaultBranch' 'main')
 
 if is_git_repo; then
   current_branch=$(get_current_branch)
+
+  # Step 7a: Detached HEAD detection
+  if [[ -z "$current_branch" ]]; then
+    head_sha=$(git rev-parse --short HEAD 2>/dev/null || true)
+    prev_branch=$(git reflog show --format='%gs' 2>/dev/null \
+      | grep -m1 'checkout: moving from' \
+      | sed 's/checkout: moving from \([^ ]*\) to .*/\1/' || true)
+    if [[ -n "$prev_branch" ]]; then
+      messages+=("[git-pilot] Detached HEAD at ${head_sha}. Previous branch was '${prev_branch}'. Prompt the user: return to '${prev_branch}', create a new branch from HEAD, or continue in detached state.")
+    else
+      messages+=("[git-pilot] Detached HEAD at ${head_sha}. Prompt the user: create a new branch from HEAD or continue in detached state.")
+    fi
+  fi
+
+  # Step 7b: Branch freshness check
+  if has_remote && [[ -n "$current_branch" ]]; then
+    remote_name=$(get_config "$CONFIG" '.remote.defaultName' 'origin')
+    tracking_status=$(get_branch_tracking_status "$current_branch" "$remote_name")
+    case "$tracking_status" in
+      behind:*)
+        behind_count="${tracking_status#behind:}"
+        if git merge --ff-only "${remote_name}/${current_branch}" >/dev/null 2>&1; then
+          messages+=("[git-pilot] Branch '${current_branch}' was ${behind_count} commit(s) behind '${remote_name}/${current_branch}'. Fast-forwarded to latest.")
+        else
+          messages+=("[git-pilot] Branch '${current_branch}' is ${behind_count} commit(s) behind '${remote_name}/${current_branch}' but fast-forward failed. Prompt the user: pull with merge, reset to remote, or continue as-is.")
+        fi
+        ;;
+      diverged:*:*)
+        IFS=':' read -r _ ahead_count behind_count <<< "$tracking_status"
+        messages+=("[git-pilot] Branch '${current_branch}' has diverged from '${remote_name}/${current_branch}' (${ahead_count} local, ${behind_count} remote). Prompt the user: rebase onto remote, merge remote, reset to remote, or continue.")
+        ;;
+      ahead:*)
+        ahead_count="${tracking_status#ahead:}"
+        messages+=("[git-pilot] Branch '${current_branch}' is ${ahead_count} commit(s) ahead of '${remote_name}/${current_branch}'. Unpushed changes.")
+        ;;
+      # up-to-date and no-remote: no message
+    esac
+  fi
+
+  # Step 7c: Branch creation prompt (existing v1 logic)
   auto_create=$(get_config "$CONFIG" '.branch.autoCreate' 'true')
 
   if [[ "$auto_create" == "true" ]] && [[ "$current_branch" == "$default_branch" ]]; then
@@ -84,10 +136,19 @@ if is_git_repo; then
   fi
 fi
 
-# Step 9: Initialize session state
+# Step 9: Initialize session state (extended 5-arg form)
 if [[ -n "$SESSION_ID" ]]; then
   previous_branch="$current_branch"
-  init_state "$SESSION_ID" "$current_branch" "$previous_branch"
+  base_branch="$default_branch"
+  branch_purpose=""
+  if [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    branch_purpose=$(derive_branch_purpose "$current_branch")
+    configured_base=$(git config "branch.${current_branch}.merge" 2>/dev/null | sed 's|refs/heads/||' || true)
+    if [[ -n "$configured_base" ]]; then
+      base_branch="$configured_base"
+    fi
+  fi
+  init_state "$SESSION_ID" "$current_branch" "$previous_branch" "$base_branch" "$branch_purpose"
 fi
 
 # Step 10: Build and output final JSON
diff --git a/plugins/git-pilot/scripts/session-stop.sh b/plugins/git-pilot/scripts/session-stop.sh
index 3eab52a..e355f0c 100755
--- a/plugins/git-pilot/scripts/session-stop.sh
+++ b/plugins/git-pilot/scripts/session-stop.sh
@@ -10,6 +10,8 @@ source "$SCRIPT_DIR/config.sh"
 source "$SCRIPT_DIR/git-utils.sh"
 # shellcheck source=state.sh
 source "$SCRIPT_DIR/state.sh"
+# shellcheck source=agent.sh
+source "$SCRIPT_DIR/agent.sh"
 
 # Read input from stdin
 input=$(cat)
@@ -63,8 +65,63 @@ fi
 
 messages=()
 
+# ---------------------------------------------------------------------------
+# Agent context: attempt silent rebase, skip summary, exit early
+# ---------------------------------------------------------------------------
+if is_agent_context "$session_id"; then
+  if [[ "$session_had_changes" == "true" ]] && has_remote; then
+    auto_rebase=$(get_config "$config" '.rebase.autoRebaseBeforePush' 'true')
+    if [[ "$auto_rebase" == "true" ]] && [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+      # shellcheck source=rebase.sh
+      source "$SCRIPT_DIR/rebase.sh"
+      drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name" || echo "")
+      case "$drift_status" in
+        drifted:*)
+          rebase_result=$(attempt_rebase "${remote_name}/${default_branch}" || true)
+          if [[ "$rebase_result" == "conflict" ]]; then
+            git rebase --abort 2>/dev/null || true
+          fi
+          ;;
+      esac
+    fi
+  fi
+
+  # Worktree cleanup still runs for agents
+  # shellcheck source=worktree.sh
+  source "$SCRIPT_DIR/worktree.sh"
+  registry=$(list_worktrees)
+  active_count=$(echo "$registry" | jq '.worktrees | length')
+  if [[ "$active_count" -gt 0 ]]; then
+    cleanup_on_merge=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+    if [[ "$cleanup_on_merge" == "true" ]]; then
+      echo "$registry" | jq -r '.worktrees[] | select(.status == "active") | .path' | \
+      while IFS= read -r wt_path; do
+        if [[ -z "$wt_path" ]]; then continue; fi
+        if [[ -d "$wt_path" ]]; then
+          wt_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
+          if [[ -n "$wt_branch" ]] && git branch --merged "$default_branch" 2>/dev/null | grep -q "$wt_branch"; then
+            remove_worktree "$wt_path" "false" || true
+          fi
+        else
+          unregister_worktree "$wt_path"
+        fi
+      done
+    fi
+  fi
+
+  # Cleanup session state
+  if [[ -n "$session_id" ]]; then
+    state_file=$(get_state_file "$session_id")
+    cleanup_state "$state_file"
+  fi
+
+  echo '{"continue": true}'
+  exit 0
+fi
+
 # ---------------------------------------------------------------------------
 # 1. Work summary (only if changes were made during this session)
+#    Suppressed for agents (handled by early exit above).
 # ---------------------------------------------------------------------------
 if [[ "$session_had_changes" == "true" ]]; then
   # Show only session commits when possible, fall back to full branch diff
@@ -101,6 +158,62 @@ if [[ "$session_had_changes" == "true" ]]; then
   fi
 fi
 
+# ---------------------------------------------------------------------------
+# 1.5. Base branch drift detection and rebase
+#       Suppressed for agents (handled by early exit above).
+# ---------------------------------------------------------------------------
+if [[ "$session_had_changes" == "true" ]] && has_remote; then
+  auto_rebase=$(get_config "$config" '.rebase.autoRebaseBeforePush' 'true')
+  if [[ "$auto_rebase" == "true" ]] && [[ -n "$current_branch" ]] && [[ "$current_branch" != "$default_branch" ]]; then
+    # shellcheck source=rebase.sh
+    source "$SCRIPT_DIR/rebase.sh"
+    drift_status=$(get_base_branch_drift "$current_branch" "$default_branch" "$remote_name" || echo "")
+    case "$drift_status" in
+      drifted:*)
+        drift_count="${drift_status#drifted:}"
+        messages+=("[git-pilot] Base branch '${default_branch}' has ${drift_count} new commit(s). Rebasing '${current_branch}' onto '${remote_name}/${default_branch}'...")
+        rebase_result=$(attempt_rebase "${remote_name}/${default_branch}" || true)
+        case "$rebase_result" in
+          success)
+            messages+=("[git-pilot] Rebase succeeded cleanly. Ready to push.")
+            ;;
+          conflict)
+            conflict_strategy=$(get_config "$config" '.rebase.conflictStrategy' 'prompt')
+            case "$conflict_strategy" in
+              prompt)
+                conflicts=$(get_conflict_details)
+                conflict_count=$(echo "$conflicts" | jq 'length')
+                conflict_files=$(echo "$conflicts" | jq -r '.[].file' | paste -sd', ')
+                messages+=("[git-pilot] Rebase conflicts in ${conflict_count} file(s): ${conflict_files}. Prompt the user to resolve conflicts, abort rebase, or use merge instead.")
+                ;;
+              abort)
+                git rebase --abort 2>/dev/null || true
+                messages+=("[git-pilot] Rebase aborted due to conflicts. Pushing without rebase.")
+                ;;
+              merge-fallback)
+                git rebase --abort 2>/dev/null || true
+                if git merge "${remote_name}/${default_branch}" --no-edit 2>/dev/null; then
+                  messages+=("[git-pilot] Merge with '${default_branch}' succeeded (rebase had conflicts).")
+                else
+                  fallback_conflicts=$(get_conflict_details)
+                  fallback_conflict_count=$(echo "$fallback_conflicts" | jq 'length')
+                  messages+=("[git-pilot] Both rebase and merge have conflicts in ${fallback_conflict_count} file(s). Prompt the user to resolve.")
+                fi
+                ;;
+            esac
+            ;;
+        esac
+        ;;
+      no-drift)
+        # No action needed
+        ;;
+      no-common-ancestor)
+        messages+=("[git-pilot] Cannot determine common ancestor between '${current_branch}' and '${default_branch}'. Skipping rebase. Push may require manual review.")
+        ;;
+    esac
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # 2. Push workflow (only "always" mode — "ask" is handled by /finish skill)
 # ---------------------------------------------------------------------------
@@ -248,6 +361,35 @@ if [[ "$session_had_changes" == "true" ]] && has_remote; then
   fi
 fi
 
+# ---------------------------------------------------------------------------
+# 3.5. Worktree cleanup — remove merged worktrees, unregister stale entries
+# ---------------------------------------------------------------------------
+# shellcheck source=worktree.sh
+source "$SCRIPT_DIR/worktree.sh"
+registry=$(list_worktrees)
+active_count=$(echo "$registry" | jq '.worktrees | length')
+if [[ "$active_count" -gt 0 ]]; then
+  cleanup_on_merge=$(get_config "$config" '.worktree.cleanupOnMerge' 'true')
+  if [[ "$cleanup_on_merge" == "true" ]]; then
+    echo "$registry" | jq -r '.worktrees[] | select(.status == "active") | .path' | \
+    while IFS= read -r wt_path; do
+      if [[ -z "$wt_path" ]]; then continue; fi
+      if [[ -d "$wt_path" ]]; then
+        wt_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
+        if [[ -n "$wt_branch" ]] && git branch --merged "$default_branch" 2>/dev/null | grep -q "$wt_branch"; then
+          remove_worktree "$wt_path" "false" || true
+        fi
+      else
+        unregister_worktree "$wt_path"
+      fi
+    done
+  fi
+  remaining=$(list_worktrees | jq '.worktrees | length')
+  if [[ "$remaining" -gt 0 ]]; then
+    messages+=("[git-pilot] ${remaining} active worktree(s) remain. Use /worktree to manage them.")
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # 4. Cleanup session state
 # ---------------------------------------------------------------------------

From 527a722708be937c935bad73b87848b06c65b8f8 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:42 +0100
Subject: [PATCH 5/7] feat(git-pilot): add v2 skills, CLAUDE.md, and bump to
 2.0.0

---
 plugins/git-pilot/.claude-plugin/plugin.json | 11 +++-
 plugins/git-pilot/CLAUDE.md                  | 62 +++++++++++++++++++-
 plugins/git-pilot/skills/branch/SKILL.md     |  6 ++
 plugins/git-pilot/skills/configure/SKILL.md  | 11 ++++
 plugins/git-pilot/skills/finish/SKILL.md     | 14 +++++
 plugins/git-pilot/skills/rebase/SKILL.md     | 43 ++++++++++++++
 plugins/git-pilot/skills/stash/SKILL.md      | 43 ++++++++++++++
 plugins/git-pilot/skills/worktree/SKILL.md   | 50 ++++++++++++++++
 8 files changed, 236 insertions(+), 4 deletions(-)
 create mode 100644 plugins/git-pilot/skills/rebase/SKILL.md
 create mode 100644 plugins/git-pilot/skills/stash/SKILL.md
 create mode 100644 plugins/git-pilot/skills/worktree/SKILL.md

diff --git a/plugins/git-pilot/.claude-plugin/plugin.json b/plugins/git-pilot/.claude-plugin/plugin.json
index d01bf0f..22932af 100644
--- a/plugins/git-pilot/.claude-plugin/plugin.json
+++ b/plugins/git-pilot/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "git-pilot",
-  "version": "1.1.0",
-  "description": "Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, and natural language configuration",
+  "version": "2.0.0",
+  "description": "Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, rebase and conflict resolution, worktree management, stash automation, agent teams support, and natural language configuration",
   "author": {
     "name": "git-pilot contributors"
   },
@@ -13,7 +13,12 @@
     "branches",
     "merge-request",
     "pull-request",
-    "conventional-commits"
+    "conventional-commits",
+    "rebase",
+    "worktree",
+    "stash",
+    "agent-teams",
+    "conflict-resolution"
   ],
   "hooks": "./hooks/hooks.json",
   "skills": "./skills/"
diff --git a/plugins/git-pilot/CLAUDE.md b/plugins/git-pilot/CLAUDE.md
index a65bbc8..a5111ef 100644
--- a/plugins/git-pilot/CLAUDE.md
+++ b/plugins/git-pilot/CLAUDE.md
@@ -26,7 +26,7 @@ When you receive a system message prefixed with `[git-pilot]` from any hook (Ses
 ## Rule 4: Push workflow
 
 After every successful `git commit`, check for unpushed commits. If there are any and a remote exists:
-- Use AskUserQuestion to prompt the user with two options: **"Push to \<remote\>/\<branch\>"** and **"Skip"**.
+- Use AskUserQuestion to prompt the user with two options: **"Push to <remote>/<branch>"** and **"Skip"**.
 - If they choose to push, run: `git push -u <remote> <branch>`.
 - Do NOT silently skip this step or just mention it in passing. The user expects an interactive prompt.
 
@@ -45,6 +45,63 @@ When finishing a session, follow the `/finish` skill workflow:
 - Local settings override global settings which override plugin defaults.
 - When changing config, ask whether the change should be global or project-specific.
 
+## Rule 7: Unrelated work detection
+
+Before starting work on a new user request, assess whether the request is related
+to the current branch's purpose:
+
+1. **Branch name**: Parse the branch name for semantic meaning. For example,
+   `feat/add-dark-mode` implies work on dark mode; `fix/login-timeout` implies
+   fixing a login timeout bug.
+2. **Recent commits**: Review the commit log on this branch for scope context.
+3. **Assessment**: If the user's request is clearly unrelated to the branch's
+   purpose (different feature, different bug, different module), prompt the user:
+
+   "This work appears unrelated to the current branch (`<branch-name>`).
+   Options:
+   1. Create a new branch from `<default-branch>` (recommended — keeps branches focused)
+   2. Create a new branch from the current branch (if this work depends on current changes)
+   3. Continue on this branch"
+
+4. **When NOT to prompt**: Do not prompt for closely related work (e.g., fixing
+   a bug discovered while implementing a feature on the same branch), for work
+   on the default branch, or for branches with no commits yet.
+5. **If the user chooses to create a new branch**: Follow the branch switch
+   workflow (see Rule 8).
+
+## Rule 8: Branch switching
+
+When switching branches (via /branch, user request, or unrelated work detection):
+
+1. If there are uncommitted changes and `branch.autoStashOnSwitch` is `true`, stash
+   them automatically before switching. Inform the user: "Stashed changes on '<branch>'."
+2. After switching, check if there's a git-pilot stash for the target branch and
+   restore it automatically.
+3. If stash restoration fails (conflicts), inform the user and suggest manual resolution.
+
+## Rule 9: Conflict resolution
+
+When a rebase or merge results in conflicts:
+
+1. Read the conflicting files to understand the nature of each conflict.
+2. For each conflict, provide a recommendation:
+   - If only one side modified the region, recommend accepting that side.
+   - If both sides modified the same lines, recommend manual review.
+   - If a file was deleted on one side, explain the tradeoff.
+3. Present clear options: resolve manually, accept ours, accept theirs, abort.
+4. After the user resolves conflicts, continue the interrupted operation
+   (`git rebase --continue` or `git merge --continue`).
+
+## Rule 10: Agent Teams
+
+When operating as a spawned agent (not the orchestrator):
+
+1. Do not prompt for push, MR creation, or branch switching. These are
+   orchestrator-only operations.
+2. Follow commit rules normally — agents must still use proper commit format.
+3. Do not run auto-commit suggestions. Commit when instructed by the orchestrator.
+4. If instructed to work in a specific worktree directory, stay in that directory.
+
 ## Skill reference
 
 | Skill | When to use |
@@ -53,3 +110,6 @@ When finishing a session, follow the `/finish` skill workflow:
 | `/finish` | When the user says they're done, or at session end |
 | `/summary` | When the user asks for a recap of branch work |
 | `/configure` | When the user wants to change git-pilot settings |
+| `/stash` | When the user wants to manage git stashes |
+| `/worktree` | When the user wants to manage git worktrees |
+| `/rebase` | When the user wants to rebase the current branch |
diff --git a/plugins/git-pilot/skills/branch/SKILL.md b/plugins/git-pilot/skills/branch/SKILL.md
index 4593e1d..18d7f38 100644
--- a/plugins/git-pilot/skills/branch/SKILL.md
+++ b/plugins/git-pilot/skills/branch/SKILL.md
@@ -47,3 +47,9 @@ Create and switch to the new branch:
 ```
 git switch -c <branch-name>
 ```
+
+## Step 5: Record Branch Context
+
+After creating the branch, note the base branch (the branch you were on before switching)
+and the branch purpose (derived from the description). These are used for unrelated work
+detection and drift checks.
diff --git a/plugins/git-pilot/skills/configure/SKILL.md b/plugins/git-pilot/skills/configure/SKILL.md
index f301f5f..b2910c8 100644
--- a/plugins/git-pilot/skills/configure/SKILL.md
+++ b/plugins/git-pilot/skills/configure/SKILL.md
@@ -21,6 +21,17 @@ Use the reference table below to understand all available config keys:
 | "Stop auto-committing" | `autoCommit.enabled: false` |
 | "Always create draft PRs" | `mergeRequest.draft: true` |
 | "Use underscores in branch names" | `branch.descriptionSeparator: "_", branch.descriptionCase: "snake"` |
+| "Fetch remote on session start" | `git.autoFetch: true` |
+| "Block commits to main" | `git.protectDefaultBranch: "block"` |
+| "Don't warn about main branch commits" | `git.protectDefaultBranch: "off"` |
+| "Disable unrelated work detection" | `branch.unrelatedWorkDetection: false` |
+| "Don't auto-stash on branch switch" | `branch.autoStashOnSwitch: false` |
+| "Don't auto-rebase before push" | `rebase.autoRebaseBeforePush: false` |
+| "Never force push" | `rebase.allowForcePush: "never"` |
+| "Always force push after rebase" | `rebase.allowForcePush: "always"` |
+| "Use merge when rebase conflicts" | `rebase.conflictStrategy: "merge-fallback"` |
+| "Disable worktrees" | `worktree.enabled: false` |
+| "Worktrees in /tmp" | `worktree.basePath: "/tmp/{{project}}-worktrees"` |
 
 ## Step 2: Read Current Config
 
diff --git a/plugins/git-pilot/skills/finish/SKILL.md b/plugins/git-pilot/skills/finish/SKILL.md
index 0f9fa84..0444e80 100644
--- a/plugins/git-pilot/skills/finish/SKILL.md
+++ b/plugins/git-pilot/skills/finish/SKILL.md
@@ -11,6 +11,20 @@ Perform the following sequence to finish the current work session.
 
 Run `git status --porcelain`. If there are any uncommitted changes, commit them following the configured commit format.
 
+## Step 1.5: Check Base Branch Drift
+
+Before pushing, check if the base branch has advanced:
+
+1. Run `git fetch <remote> <defaultBranch>`.
+2. Check for new commits on the base branch since this branch diverged.
+3. If the base has new commits and `rebase.autoRebaseBeforePush` is `true`:
+   - Attempt `git rebase <remote>/<defaultBranch>`.
+   - If rebase succeeds: continue to push.
+   - If rebase has conflicts: present conflict details and options to the user.
+4. If force push is needed after rebase, follow `rebase.allowForcePush` policy.
+
+Base branch is determined in order: (1) session state `baseBranch` field, (2) `git config branch.${current}.merge` with `refs/heads/` stripped, (3) `git.defaultBranch` from config.
+
 ## Step 2: Push to Remote
 
 Follow the push workflow:
diff --git a/plugins/git-pilot/skills/rebase/SKILL.md b/plugins/git-pilot/skills/rebase/SKILL.md
new file mode 100644
index 0000000..ec523c0
--- /dev/null
+++ b/plugins/git-pilot/skills/rebase/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: rebase
+description: Rebase current branch onto another branch
+---
+
+# /rebase
+
+Rebase the current branch onto a target branch.
+
+## Step 1: Determine Target
+
+If the user specified a target branch (e.g., `/rebase main`), use it.
+Otherwise, default to the configured `git.defaultBranch`.
+
+## Step 2: Pre-flight Checks
+
+1. Ensure the working tree is clean. If uncommitted changes exist, ask to stash or commit first.
+2. Fetch the remote target branch: `git fetch <remote> <target>`.
+3. Check how many commits will be rebased: `git rev-list --count <remote>/<target>..HEAD`.
+4. Show the user: "Rebasing N commit(s) onto <remote>/<target>."
+
+## Step 3: Execute Rebase
+
+1. Run `git rebase <remote>/<target>`.
+2. If success: "Rebase completed successfully."
+3. If conflicts:
+   - Show conflicting files and conflict details.
+   - Present resolution options:
+     a. Resolve manually (edit files, then `git add <file>` and `git rebase --continue`)
+     b. Accept theirs for all (`git checkout --theirs . && git add .`)
+     c. Accept ours for all (`git checkout --ours . && git add .`)
+     d. Abort (`git rebase --abort`)
+   - After resolution, run `git rebase --continue`.
+
+## Step 4: Handle Force Push
+
+If the branch was previously pushed and rebase rewrote history:
+1. Inform: "Rebase rewrote history. Force push is needed to update the remote."
+2. Based on `rebase.allowForcePush`:
+   - `"ask"`: Ask user to confirm force push.
+   - `"always"`: Push with `--force-with-lease` automatically.
+   - `"never"`: Inform that force push is disabled.
+3. Use `git push --force-with-lease <remote> <branch>`.
diff --git a/plugins/git-pilot/skills/stash/SKILL.md b/plugins/git-pilot/skills/stash/SKILL.md
new file mode 100644
index 0000000..69250ed
--- /dev/null
+++ b/plugins/git-pilot/skills/stash/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: stash
+description: Manage git stashes - save, list, apply, or drop
+---
+
+# /stash
+
+Manage git stashes for the current repository.
+
+## Step 1: Determine Action
+
+If the user provided an argument after `/stash`, parse it:
+- `/stash` or `/stash save` — stash current changes
+- `/stash list` — list all stashes
+- `/stash pop` or `/stash apply` — restore the most recent stash
+- `/stash drop` — drop the most recent stash
+
+If no argument, ask the user what they want to do.
+
+## Step 2: Execute
+
+### Save
+1. Check for uncommitted changes. If none: "Nothing to stash."
+2. Ask the user for an optional stash message.
+3. Run `git stash push -m "<message>"` (or `git stash push` if no message).
+4. Confirm: "Stashed changes: <stash-ref>"
+
+### List
+1. Run `git stash list`.
+2. If empty: "No stashes found."
+3. Present the list with index, branch, and message.
+
+### Pop / Apply
+1. Run `git stash list`. If empty: "No stashes to restore."
+2. If multiple stashes, show the list and ask which one.
+3. For pop: `git stash pop <ref>`. For apply: `git stash apply <ref>`.
+4. If conflicts: warn the user and show conflicting files.
+
+### Drop
+1. Run `git stash list`. If empty: "No stashes to drop."
+2. If multiple stashes, show the list and ask which one.
+3. Confirm before dropping.
+4. Run `git stash drop <ref>`.
diff --git a/plugins/git-pilot/skills/worktree/SKILL.md b/plugins/git-pilot/skills/worktree/SKILL.md
new file mode 100644
index 0000000..280b5dc
--- /dev/null
+++ b/plugins/git-pilot/skills/worktree/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: worktree
+description: Manage git worktrees for parallel branch work
+---
+
+# /worktree
+
+Manage git worktrees for parallel branch work.
+
+## Step 1: Determine Action
+
+Parse the user's intent:
+- `/worktree` or `/worktree list` — list active worktrees
+- `/worktree create <branch>` — create a new worktree for a branch
+- `/worktree remove <path-or-branch>` — remove a worktree
+- `/worktree merge <path-or-branch>` — merge a worktree's branch and clean up
+
+If no argument, show the list of active worktrees.
+
+## Step 2: Execute
+
+### List
+1. Read the worktree registry (`.git/git-pilot-worktrees.json`).
+2. Also run `git worktree list` for system-level view.
+3. Present: path, branch, base branch, creation date, status.
+
+### Create
+1. Ask for the branch name (or parse from argument).
+2. Ask for the base branch (default: `git.defaultBranch`).
+3. Determine the worktree path using `worktree.basePath` config.
+4. Run `git worktree add <path> -b <branch> <base>`.
+5. Register in the worktree registry.
+6. Confirm with the worktree path.
+
+### Remove
+1. Identify the worktree by path or branch name.
+2. Check for uncommitted changes in the worktree.
+3. If uncommitted changes, warn and ask to confirm.
+4. Run `git worktree remove <path>`.
+5. Optionally delete the branch: `git branch -d <branch>`.
+6. Unregister from the registry.
+
+### Merge
+1. Identify the worktree by path or branch name.
+2. Get the worktree's branch and its base branch from the registry.
+3. Switch main worktree to the base branch.
+4. Attempt `git merge <worktree-branch> --no-edit`.
+5. If conflicts: present them and ask user to resolve.
+6. If `worktree.cleanupOnMerge` is `true`: remove the worktree and delete the branch.
+7. Confirm the merge.

From eff516c5004d94864d8d48d3eda6542fa1ba3035 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Tue, 24 Feb 2026 23:35:46 +0100
Subject: [PATCH 6/7] test(git-pilot): add bats test suite for v2 features

---
 plugins/git-pilot/tests/agent-detection.bats  | 112 +++++++++
 plugins/git-pilot/tests/branch-freshness.bats | 172 ++++++++++++++
 plugins/git-pilot/tests/config-compat.bats    | 122 ++++++++++
 plugins/git-pilot/tests/drift-detection.bats  |  94 ++++++++
 plugins/git-pilot/tests/protected-branch.bats | 133 +++++++++++
 plugins/git-pilot/tests/rebase.bats           | 168 ++++++++++++++
 plugins/git-pilot/tests/stash.bats            | 157 +++++++++++++
 plugins/git-pilot/tests/state.bats            | 217 ++++++++++++++++++
 .../git-pilot/tests/test_helper/common.bash   |  94 ++++++++
 plugins/git-pilot/tests/worktree.bats         | 217 ++++++++++++++++++
 10 files changed, 1486 insertions(+)
 create mode 100644 plugins/git-pilot/tests/agent-detection.bats
 create mode 100644 plugins/git-pilot/tests/branch-freshness.bats
 create mode 100644 plugins/git-pilot/tests/config-compat.bats
 create mode 100644 plugins/git-pilot/tests/drift-detection.bats
 create mode 100644 plugins/git-pilot/tests/protected-branch.bats
 create mode 100644 plugins/git-pilot/tests/rebase.bats
 create mode 100644 plugins/git-pilot/tests/stash.bats
 create mode 100644 plugins/git-pilot/tests/state.bats
 create mode 100644 plugins/git-pilot/tests/test_helper/common.bash
 create mode 100644 plugins/git-pilot/tests/worktree.bats

diff --git a/plugins/git-pilot/tests/agent-detection.bats b/plugins/git-pilot/tests/agent-detection.bats
new file mode 100644
index 0000000..65b7918
--- /dev/null
+++ b/plugins/git-pilot/tests/agent-detection.bats
@@ -0,0 +1,112 @@
+#!/usr/bin/env bats
+
+# Tests for agent.sh: is_agent_context, is_operation_agent_restricted.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "agent.sh"
+
+  # Ensure CLAUDE_SPAWNED_BY is unset by default
+  unset CLAUDE_SPAWNED_BY
+}
+
+teardown() {
+  unset CLAUDE_SPAWNED_BY
+  rm -f /tmp/git-pilot-test-agent-*.json
+  teardown_test_repo
+}
+
+# ---------- is_agent_context ----------
+
+@test "is_agent_context: returns true when CLAUDE_SPAWNED_BY is set" {
+  export CLAUDE_SPAWNED_BY="orchestrator-session-123"
+  run is_agent_context
+  [ "$status" -eq 0 ]
+}
+
+@test "is_agent_context: returns true when state file has isAgent true" {
+  local sid="test-agent-state"
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  update_state "$state_file" '.isAgent = true'
+
+  run is_agent_context "$sid"
+  [ "$status" -eq 0 ]
+
+  rm -f "$state_file"
+}
+
+@test "is_agent_context: returns false when neither env var nor state flag is set" {
+  local sid="test-agent-none"
+  init_state "$sid" "main" ""
+
+  run is_agent_context "$sid"
+  [ "$status" -eq 1 ]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
+
+@test "is_agent_context: returns false with no args and no env var" {
+  run is_agent_context
+  [ "$status" -eq 1 ]
+}
+
+@test "is_agent_context: env var takes precedence over state" {
+  export CLAUDE_SPAWNED_BY="orchestrator"
+  local sid="test-agent-both"
+  init_state "$sid" "main" ""
+
+  # State says not an agent, but env var overrides
+  run is_agent_context "$sid"
+  [ "$status" -eq 0 ]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
+
+# ---------- is_operation_agent_restricted ----------
+
+@test "is_operation_agent_restricted: push is restricted by default config" {
+  local config='{"agentTeams":{"suppressPromptsForAgents":true,"orchestratorOnly":["push","mr"]}}'
+  run is_operation_agent_restricted "$config" "push"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_operation_agent_restricted: mr is restricted by default config" {
+  local config='{"agentTeams":{"suppressPromptsForAgents":true,"orchestratorOnly":["push","mr"]}}'
+  run is_operation_agent_restricted "$config" "mr"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_operation_agent_restricted: commit is not restricted by default" {
+  local config='{"agentTeams":{"suppressPromptsForAgents":true,"orchestratorOnly":["push","mr"]}}'
+  run is_operation_agent_restricted "$config" "commit"
+  [ "$status" -eq 1 ]
+}
+
+@test "is_operation_agent_restricted: nothing restricted when suppressPromptsForAgents is false" {
+  local config='{"agentTeams":{"suppressPromptsForAgents":false,"orchestratorOnly":["push","mr"]}}'
+  run is_operation_agent_restricted "$config" "push"
+  [ "$status" -eq 1 ]
+}
+
+@test "is_operation_agent_restricted: custom orchestratorOnly list respected" {
+  local config='{"agentTeams":{"suppressPromptsForAgents":true,"orchestratorOnly":["push","mr","rebase","branch-freshness"]}}'
+  run is_operation_agent_restricted "$config" "rebase"
+  [ "$status" -eq 0 ]
+
+  run is_operation_agent_restricted "$config" "branch-freshness"
+  [ "$status" -eq 0 ]
+
+  run is_operation_agent_restricted "$config" "commit"
+  [ "$status" -eq 1 ]
+}
diff --git a/plugins/git-pilot/tests/branch-freshness.bats b/plugins/git-pilot/tests/branch-freshness.bats
new file mode 100644
index 0000000..91d94bf
--- /dev/null
+++ b/plugins/git-pilot/tests/branch-freshness.bats
@@ -0,0 +1,172 @@
+#!/usr/bin/env bats
+
+# Tests for git-utils.sh: get_branch_tracking_status, fetch_with_retry,
+# derive_branch_purpose, is_detached_head.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+}
+
+teardown() {
+  teardown_test_repo
+}
+
+# ---------- get_branch_tracking_status ----------
+
+@test "get_branch_tracking_status: up-to-date when local matches remote" {
+  setup_remote_repo
+
+  run get_branch_tracking_status "main" "origin"
+  [ "$status" -eq 0 ]
+  [ "$output" = "up-to-date" ]
+}
+
+@test "get_branch_tracking_status: behind when remote has new commits" {
+  setup_remote_repo
+
+  # Clone elsewhere and push a commit
+  local clone_dir
+  clone_dir="$(mktemp -d "${BATS_TMPDIR:-/tmp}/git-pilot-clone.XXXXXX")"
+  git clone "$TEST_REMOTE" "$clone_dir" >/dev/null 2>&1
+  cd "$clone_dir"
+  git config user.name "Other"
+  git config user.email "other@example.com"
+  echo "remote change" > remote-file.txt
+  git add remote-file.txt
+  git commit -m "feat: remote change" >/dev/null 2>&1
+  git push origin main >/dev/null 2>&1
+
+  # Back in test repo, fetch so we know about the remote commit
+  cd "$TEST_REPO"
+  git fetch origin >/dev/null 2>&1
+
+  run get_branch_tracking_status "main" "origin"
+  [ "$status" -eq 0 ]
+  [[ "$output" == behind:* ]]
+
+  rm -rf "$clone_dir"
+}
+
+@test "get_branch_tracking_status: ahead when local has unpushed commits" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  echo "local change" > local-file.txt
+  git add local-file.txt
+  git commit -m "feat: local change" >/dev/null 2>&1
+
+  run get_branch_tracking_status "main" "origin"
+  [ "$status" -eq 0 ]
+  [[ "$output" == ahead:* ]]
+}
+
+@test "get_branch_tracking_status: diverged when both sides have new commits" {
+  setup_remote_repo
+
+  # Push a commit from a clone
+  local clone_dir
+  clone_dir="$(mktemp -d "${BATS_TMPDIR:-/tmp}/git-pilot-clone.XXXXXX")"
+  git clone "$TEST_REMOTE" "$clone_dir" >/dev/null 2>&1
+  cd "$clone_dir"
+  git config user.name "Other"
+  git config user.email "other@example.com"
+  echo "remote diverge" > diverge-remote.txt
+  git add diverge-remote.txt
+  git commit -m "feat: remote diverge" >/dev/null 2>&1
+  git push origin main >/dev/null 2>&1
+
+  # Make a local commit in test repo
+  cd "$TEST_REPO"
+  git fetch origin >/dev/null 2>&1
+  echo "local diverge" > diverge-local.txt
+  git add diverge-local.txt
+  git commit -m "feat: local diverge" >/dev/null 2>&1
+
+  run get_branch_tracking_status "main" "origin"
+  [ "$status" -eq 0 ]
+  [[ "$output" == diverged:* ]]
+
+  rm -rf "$clone_dir"
+}
+
+@test "get_branch_tracking_status: no-remote when remote branch does not exist" {
+  # No remote set up at all
+  run get_branch_tracking_status "main" "origin"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-remote" ]
+}
+
+# ---------- fetch_with_retry ----------
+
+@test "fetch_with_retry: succeeds on valid remote" {
+  setup_remote_repo
+
+  local config='{"git":{"fetchRetries":1,"fetchRetryDelaySec":0}}'
+  run fetch_with_retry "origin" "$config"
+  [ "$status" -eq 0 ]
+}
+
+@test "fetch_with_retry: fails after retries on invalid remote" {
+  # Add a bogus remote
+  git remote add bogus "file:///nonexistent/path/to/repo"
+
+  local config='{"git":{"fetchRetries":0,"fetchRetryDelaySec":0}}'
+  run fetch_with_retry "bogus" "$config"
+  [ "$status" -eq 1 ]
+}
+
+@test "fetch_with_retry: fetches specific branch" {
+  setup_remote_repo
+
+  local config='{"git":{"fetchRetries":1,"fetchRetryDelaySec":0}}'
+  run fetch_with_retry "origin" "$config" "main"
+  [ "$status" -eq 0 ]
+}
+
+# ---------- derive_branch_purpose ----------
+
+@test "derive_branch_purpose: strips type prefix and converts kebab-case" {
+  run derive_branch_purpose "feat/add-dark-mode"
+  [ "$status" -eq 0 ]
+  [ "$output" = "add dark mode" ]
+}
+
+@test "derive_branch_purpose: converts snake_case to words" {
+  run derive_branch_purpose "fix/login_timeout_bug"
+  [ "$status" -eq 0 ]
+  [ "$output" = "login timeout bug" ]
+}
+
+@test "derive_branch_purpose: handles branch with no type prefix" {
+  run derive_branch_purpose "simple-branch"
+  [ "$status" -eq 0 ]
+  [ "$output" = "simple branch" ]
+}
+
+@test "derive_branch_purpose: handles nested slashes by stripping first segment" {
+  run derive_branch_purpose "feat/api/auth-endpoints"
+  [ "$status" -eq 0 ]
+  # sed strips everything up to and including the first /
+  [[ "$output" == *"auth endpoints"* ]]
+}
+
+# ---------- is_detached_head ----------
+
+@test "is_detached_head: returns false on normal branch" {
+  run is_detached_head
+  [ "$status" -eq 1 ]
+}
+
+@test "is_detached_head: returns true in detached HEAD state" {
+  local head_sha
+  head_sha=$(git rev-parse HEAD)
+  git checkout "$head_sha" >/dev/null 2>&1
+
+  run is_detached_head
+  [ "$status" -eq 0 ]
+}
diff --git a/plugins/git-pilot/tests/config-compat.bats b/plugins/git-pilot/tests/config-compat.bats
new file mode 100644
index 0000000..337b817
--- /dev/null
+++ b/plugins/git-pilot/tests/config-compat.bats
@@ -0,0 +1,122 @@
+#!/usr/bin/env bats
+
+# Tests for config.sh: load_config, get_config, normalize_protect_default_branch.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+}
+
+teardown() {
+  teardown_test_repo
+}
+
+# ---------- normalize_protect_default_branch ----------
+
+@test "normalize_protect_default_branch: true normalizes to warn" {
+  run normalize_protect_default_branch "true"
+  [ "$status" -eq 0 ]
+  [ "$output" = "warn" ]
+}
+
+@test "normalize_protect_default_branch: false normalizes to off" {
+  run normalize_protect_default_branch "false"
+  [ "$status" -eq 0 ]
+  [ "$output" = "off" ]
+}
+
+@test "normalize_protect_default_branch: warn passes through" {
+  run normalize_protect_default_branch "warn"
+  [ "$status" -eq 0 ]
+  [ "$output" = "warn" ]
+}
+
+@test "normalize_protect_default_branch: block passes through" {
+  run normalize_protect_default_branch "block"
+  [ "$status" -eq 0 ]
+  [ "$output" = "block" ]
+}
+
+@test "normalize_protect_default_branch: off passes through" {
+  run normalize_protect_default_branch "off"
+  [ "$status" -eq 0 ]
+  [ "$output" = "off" ]
+}
+
+@test "normalize_protect_default_branch: unknown value defaults to warn" {
+  run normalize_protect_default_branch "garbage"
+  [ "$status" -eq 0 ]
+  [ "$output" = "warn" ]
+}
+
+# ---------- get_config ----------
+
+@test "get_config: returns value for existing key" {
+  local config='{"git":{"defaultBranch":"develop"}}'
+  run get_config "$config" '.git.defaultBranch' 'main'
+  [ "$status" -eq 0 ]
+  [ "$output" = "develop" ]
+}
+
+@test "get_config: returns default for missing key" {
+  local config='{"git":{}}'
+  run get_config "$config" '.git.fetchRetries' '2'
+  [ "$status" -eq 0 ]
+  [ "$output" = "2" ]
+}
+
+@test "get_config: returns default for null value" {
+  local config='{"git":{"fetchRetries":null}}'
+  run get_config "$config" '.git.fetchRetries' '5'
+  [ "$status" -eq 0 ]
+  [ "$output" = "5" ]
+}
+
+# ---------- load_config ----------
+
+@test "load_config: loads defaults when no overrides exist" {
+  run load_config "$TEST_REPO"
+  [ "$status" -eq 0 ]
+  # Should include the default branch setting from defaults/config.json
+  local default_branch
+  default_branch=$(echo "$output" | jq -r '.git.defaultBranch')
+  [ "$default_branch" = "main" ]
+}
+
+@test "load_config: local config overrides defaults" {
+  create_config "$TEST_REPO/.claude/git-pilot.json" '{"git":{"defaultBranch":"develop"}}'
+
+  run load_config "$TEST_REPO"
+  [ "$status" -eq 0 ]
+  local default_branch
+  default_branch=$(echo "$output" | jq -r '.git.defaultBranch')
+  [ "$default_branch" = "develop" ]
+}
+
+@test "load_config: v2 config with all new keys works" {
+  local v2='{"git":{"defaultBranch":"main","protectDefaultBranch":"block","fetchRetries":3},"rebase":{"conflictStrategy":"abort"},"worktree":{"enabled":true},"agentTeams":{"suppressPromptsForAgents":true}}'
+  create_config "$TEST_REPO/.claude/git-pilot.json" "$v2"
+
+  run load_config "$TEST_REPO"
+  [ "$status" -eq 0 ]
+  local protect
+  protect=$(echo "$output" | jq -r '.git.protectDefaultBranch')
+  [ "$protect" = "block" ]
+  local retries
+  retries=$(echo "$output" | jq -r '.git.fetchRetries')
+  [ "$retries" = "3" ]
+}
+
+@test "load_config: missing new keys fall back to defaults" {
+  # Minimal config with no rebase/worktree/agentTeams keys
+  create_config "$TEST_REPO/.claude/git-pilot.json" '{"git":{"defaultBranch":"main"}}'
+
+  run load_config "$TEST_REPO"
+  [ "$status" -eq 0 ]
+  # The rebase key should come from defaults
+  local conflict_strategy
+  conflict_strategy=$(echo "$output" | jq -r '.rebase.conflictStrategy')
+  [ "$conflict_strategy" = "prompt" ]
+}
diff --git a/plugins/git-pilot/tests/drift-detection.bats b/plugins/git-pilot/tests/drift-detection.bats
new file mode 100644
index 0000000..adf0684
--- /dev/null
+++ b/plugins/git-pilot/tests/drift-detection.bats
@@ -0,0 +1,94 @@
+#!/usr/bin/env bats
+
+# Tests for rebase.sh: get_base_branch_drift (base branch drift detection).
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+  source_script "rebase.sh"
+}
+
+teardown() {
+  teardown_test_repo
+}
+
+# ---------- get_base_branch_drift ----------
+
+@test "get_base_branch_drift: no drift when base has no new commits" {
+  setup_remote_repo
+
+  # Create a feature branch from main
+  cd "$TEST_REPO"
+  git checkout -b feat/my-feature >/dev/null 2>&1
+  echo "feature work" > feature.txt
+  git add feature.txt
+  git commit -m "feat: add feature" >/dev/null 2>&1
+
+  run get_base_branch_drift "feat/my-feature" "main" "origin"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-drift" ]
+}
+
+@test "get_base_branch_drift: detects drift when base branch has new commits" {
+  setup_remote_repo
+
+  # Create a feature branch
+  cd "$TEST_REPO"
+  git checkout -b feat/my-feature >/dev/null 2>&1
+  echo "feature work" > feature.txt
+  git add feature.txt
+  git commit -m "feat: add feature" >/dev/null 2>&1
+
+  # Push a new commit to main on the remote
+  local clone_dir
+  clone_dir="$(mktemp -d "${BATS_TMPDIR:-/tmp}/git-pilot-clone.XXXXXX")"
+  git clone "$TEST_REMOTE" "$clone_dir" >/dev/null 2>&1
+  cd "$clone_dir"
+  git config user.name "Other"
+  git config user.email "other@example.com"
+  echo "base change" > base-change.txt
+  git add base-change.txt
+  git commit -m "feat: base change" >/dev/null 2>&1
+  git push origin main >/dev/null 2>&1
+
+  cd "$TEST_REPO"
+  run get_base_branch_drift "feat/my-feature" "main" "origin"
+  [ "$status" -eq 0 ]
+  [[ "$output" == drifted:* ]]
+
+  rm -rf "$clone_dir"
+}
+
+@test "get_base_branch_drift: returns no-common-ancestor for orphan branches" {
+  setup_remote_repo
+
+  # Create an orphan branch with no common history
+  cd "$TEST_REPO"
+  git checkout --orphan orphan-branch >/dev/null 2>&1
+  git rm -rf . >/dev/null 2>&1
+  echo "orphan content" > orphan.txt
+  git add orphan.txt
+  git commit -m "chore: orphan init" >/dev/null 2>&1
+
+  # Push the orphan branch to remote so fetch succeeds
+  git push origin orphan-branch >/dev/null 2>&1
+
+  # Now try to detect drift between orphan-branch and main
+  # The orphan branch itself shares no history with main
+  run get_base_branch_drift "orphan-branch" "main" "origin"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-common-ancestor" ]
+}
+
+@test "get_base_branch_drift: returns error when fetch fails" {
+  # No remote set up, so fetch will fail
+  cd "$TEST_REPO"
+  git checkout -b feat/no-remote >/dev/null 2>&1
+
+  run get_base_branch_drift "feat/no-remote" "main" "origin"
+  [ "$status" -eq 1 ]
+}
diff --git a/plugins/git-pilot/tests/protected-branch.bats b/plugins/git-pilot/tests/protected-branch.bats
new file mode 100644
index 0000000..2715801
--- /dev/null
+++ b/plugins/git-pilot/tests/protected-branch.bats
@@ -0,0 +1,133 @@
+#!/usr/bin/env bats
+
+# Tests for protected branch enforcement in pre-commit.sh.
+# We test the normalize_protect_default_branch function (from config.sh)
+# and the branch protection logic by invoking the pre-commit hook script
+# with crafted JSON input.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+}
+
+teardown() {
+  teardown_test_repo
+}
+
+# Helper: create a local git-pilot config with a specific protectDefaultBranch value.
+_set_protect_mode() {
+  local mode="$1"
+  create_config "$TEST_REPO/.claude/git-pilot.json" "{\"git\":{\"protectDefaultBranch\":$mode}}"
+}
+
+# Helper: run the pre-commit hook with a git commit command.
+# This pipes the expected JSON input into the hook script.
+_run_pre_commit() {
+  local command="${1:-git commit -m \"feat: test commit\"}"
+  local input
+  input=$(jq -n \
+    --arg sid "test-session" \
+    --arg tool "Bash" \
+    --arg cmd "$command" \
+    --arg cwd "$TEST_REPO" \
+    '{session_id:$sid, tool_name:$tool, tool_input:{command:$cmd}, cwd:$cwd}')
+
+  echo "$input" | bash "$SCRIPTS_DIR/pre-commit.sh" 2>&1
+  return "${PIPESTATUS[1]}"
+}
+
+# ---------- warn mode ----------
+
+@test "protected-branch warn mode: warning emitted, commit allowed" {
+  cd "$TEST_REPO"
+  _set_protect_mode '"warn"'
+
+  # We are on main (the default branch)
+  local output
+  output=$(_run_pre_commit) || true
+
+  # Should contain a warning message
+  [[ "$output" == *"Warning"* ]] || [[ "$output" == *"warn"* ]] || [[ "$output" == *"committing directly"* ]]
+}
+
+@test "protected-branch warn mode: exits with 0 (allow)" {
+  cd "$TEST_REPO"
+  _set_protect_mode '"warn"'
+
+  local exit_code=0
+  _run_pre_commit >/dev/null 2>&1 || exit_code=$?
+  [ "$exit_code" -eq 0 ]
+}
+
+# ---------- block mode ----------
+
+@test "protected-branch block mode: commit blocked with exit code 2" {
+  cd "$TEST_REPO"
+  _set_protect_mode '"block"'
+
+  local exit_code=0
+  local output
+  output=$(_run_pre_commit 2>&1) || exit_code=$?
+  [ "$exit_code" -eq 2 ]
+  [[ "$output" == *"blocked"* ]] || [[ "$output" == *"block"* ]]
+}
+
+# ---------- off mode ----------
+
+@test "protected-branch off mode: no warning, commit allowed" {
+  cd "$TEST_REPO"
+  _set_protect_mode '"off"'
+
+  local exit_code=0
+  local output
+  output=$(_run_pre_commit 2>&1) || exit_code=$?
+  [ "$exit_code" -eq 0 ]
+  # Should NOT contain any warning about default branch
+  [[ "$output" != *"Warning: You are committing directly"* ]]
+}
+
+# ---------- boolean backward compatibility ----------
+
+@test "protected-branch boolean true: treated as warn" {
+  cd "$TEST_REPO"
+  _set_protect_mode 'true'
+
+  local exit_code=0
+  local output
+  output=$(_run_pre_commit 2>&1) || exit_code=$?
+
+  # Should be allowed (exit 0) but with a warning
+  [ "$exit_code" -eq 0 ]
+  [[ "$output" == *"Warning"* ]] || [[ "$output" == *"committing directly"* ]]
+}
+
+@test "protected-branch boolean false: treated as off" {
+  cd "$TEST_REPO"
+  _set_protect_mode 'false'
+
+  local exit_code=0
+  local output
+  output=$(_run_pre_commit 2>&1) || exit_code=$?
+  [ "$exit_code" -eq 0 ]
+  [[ "$output" != *"Warning: You are committing directly"* ]]
+}
+
+# ---------- non-default branch ----------
+
+@test "protected-branch: no enforcement on feature branch" {
+  cd "$TEST_REPO"
+  _set_protect_mode '"block"'
+
+  # Switch to a feature branch
+  git checkout -b feat/safe-branch >/dev/null 2>&1
+  echo "change" > safe.txt
+  git add safe.txt
+
+  local exit_code=0
+  _run_pre_commit >/dev/null 2>&1 || exit_code=$?
+  [ "$exit_code" -eq 0 ]
+}
diff --git a/plugins/git-pilot/tests/rebase.bats b/plugins/git-pilot/tests/rebase.bats
new file mode 100644
index 0000000..078d57f
--- /dev/null
+++ b/plugins/git-pilot/tests/rebase.bats
@@ -0,0 +1,168 @@
+#!/usr/bin/env bats
+
+# Tests for rebase.sh: attempt_rebase, get_conflict_details, needs_force_push.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+  source_script "rebase.sh"
+}
+
+teardown() {
+  # Abort any in-progress rebase to allow cleanup
+  cd "$TEST_REPO" 2>/dev/null && git rebase --abort 2>/dev/null || true
+  teardown_test_repo
+}
+
+# ---------- attempt_rebase ----------
+
+@test "attempt_rebase: clean rebase succeeds" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  # Create and switch to a feature branch
+  git checkout -b feat/clean-rebase >/dev/null 2>&1
+  echo "feature" > feature.txt
+  git add feature.txt
+  git commit -m "feat: add feature" >/dev/null 2>&1
+
+  # Add a non-conflicting commit on main
+  git checkout main >/dev/null 2>&1
+  echo "main change" > main-change.txt
+  git add main-change.txt
+  git commit -m "feat: main change" >/dev/null 2>&1
+
+  git checkout feat/clean-rebase >/dev/null 2>&1
+
+  run attempt_rebase "main"
+  [ "$status" -eq 0 ]
+  [ "$output" = "success" ]
+}
+
+@test "attempt_rebase: reports conflict on conflicting changes" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  # Modify the same file on main and feature branch
+  echo "main version" > conflict-file.txt
+  git add conflict-file.txt
+  git commit -m "feat: main version" >/dev/null 2>&1
+
+  git checkout -b feat/conflict HEAD~1 >/dev/null 2>&1
+  echo "feature version" > conflict-file.txt
+  git add conflict-file.txt
+  git commit -m "feat: feature version" >/dev/null 2>&1
+
+  run attempt_rebase "main"
+  [ "$status" -eq 1 ]
+  [ "$output" = "conflict" ]
+}
+
+@test "attempt_rebase: reports dirty worktree error" {
+  cd "$TEST_REPO"
+  echo "uncommitted" > dirty.txt
+
+  run attempt_rebase "main"
+  [ "$status" -eq 1 ]
+  [ "$output" = "error:dirty-worktree" ]
+}
+
+# ---------- get_conflict_details ----------
+
+@test "get_conflict_details: returns empty array when no conflicts" {
+  cd "$TEST_REPO"
+  run get_conflict_details
+  [ "$status" -eq 0 ]
+  [ "$output" = "[]" ]
+}
+
+@test "get_conflict_details: returns conflict info during rebase conflict" {
+  cd "$TEST_REPO"
+  # Create a conflict scenario
+  echo "base content" > conflict-file.txt
+  git add conflict-file.txt
+  git commit -m "feat: base content" >/dev/null 2>&1
+
+  git checkout -b feat/conflict-details HEAD~1 >/dev/null 2>&1
+  echo "feature content" > conflict-file.txt
+  git add conflict-file.txt
+  git commit -m "feat: feature content" >/dev/null 2>&1
+
+  # Attempt the rebase (will fail with conflict)
+  git rebase main 2>/dev/null || true
+
+  run get_conflict_details
+  [ "$status" -eq 0 ]
+  # Should be a non-empty JSON array
+  [[ "$output" != "[]" ]]
+
+  local file_count
+  file_count=$(echo "$output" | jq 'length')
+  [ "$file_count" -ge 1 ]
+
+  local first_file
+  first_file=$(echo "$output" | jq -r '.[0].file')
+  [ "$first_file" = "conflict-file.txt" ]
+
+  local conflict_type
+  conflict_type=$(echo "$output" | jq -r '.[0].type')
+  [ "$conflict_type" = "both-modified" ]
+}
+
+# ---------- needs_force_push ----------
+
+@test "needs_force_push: returns false when no remote tracking branch" {
+  # No remote at all
+  cd "$TEST_REPO"
+  run needs_force_push "main" "origin"
+  [ "$status" -eq 1 ]
+}
+
+@test "needs_force_push: returns false when local is ahead (no rewrite)" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  echo "ahead" > ahead.txt
+  git add ahead.txt
+  git commit -m "feat: ahead" >/dev/null 2>&1
+
+  run needs_force_push "main" "origin"
+  [ "$status" -eq 1 ]
+}
+
+@test "needs_force_push: returns true after history rewrite (rebase)" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  # Create a feature branch and push it
+  git checkout -b feat/force-push >/dev/null 2>&1
+  echo "feature commit 1" > f1.txt
+  git add f1.txt
+  git commit -m "feat: commit 1" >/dev/null 2>&1
+  git push -u origin feat/force-push >/dev/null 2>&1
+
+  # Add a commit on main
+  git checkout main >/dev/null 2>&1
+  echo "main commit" > m1.txt
+  git add m1.txt
+  git commit -m "feat: main commit" >/dev/null 2>&1
+
+  # Rebase feature onto main (rewrites history)
+  git checkout feat/force-push >/dev/null 2>&1
+  git rebase main >/dev/null 2>&1
+
+  run needs_force_push "feat/force-push" "origin"
+  [ "$status" -eq 0 ]
+}
+
+@test "needs_force_push: returns false when local matches remote" {
+  setup_remote_repo
+
+  cd "$TEST_REPO"
+  run needs_force_push "main" "origin"
+  [ "$status" -eq 1 ]
+}
diff --git a/plugins/git-pilot/tests/stash.bats b/plugins/git-pilot/tests/stash.bats
new file mode 100644
index 0000000..5930230
--- /dev/null
+++ b/plugins/git-pilot/tests/stash.bats
@@ -0,0 +1,157 @@
+#!/usr/bin/env bats
+
+# Tests for auto_stash() and auto_restore_stash() from git-utils.sh.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+}
+
+teardown() {
+  rm -f /tmp/git-pilot-test-stash-*.json
+  teardown_test_repo
+}
+
+# ---------- auto_stash ----------
+
+@test "auto_stash: stashes uncommitted changes and records in state" {
+  cd "$TEST_REPO"
+  local sid="test-stash-auto"
+  init_state "$sid" "main" ""
+
+  # Create uncommitted changes
+  echo "dirty content" > dirty-file.txt
+  git add dirty-file.txt
+
+  run auto_stash "main" "$sid"
+  [ "$status" -eq 0 ]
+
+  # Verify the stash was created
+  local stash_count
+  stash_count=$(git stash list | wc -l)
+  [ "$stash_count" -ge 1 ]
+
+  # Verify state was updated with stash ref
+  local state_file
+  state_file=$(get_state_file "$sid")
+  local stash_refs_count
+  stash_refs_count=$(cat "$state_file" | jq '.stashRefs | length')
+  [ "$stash_refs_count" = "1" ]
+
+  local stash_branch
+  stash_branch=$(cat "$state_file" | jq -r '.stashRefs[0].branch')
+  [ "$stash_branch" = "main" ]
+
+  rm -f "$state_file"
+}
+
+@test "auto_stash: returns 1 when there is nothing to stash" {
+  cd "$TEST_REPO"
+  local sid="test-stash-clean"
+  init_state "$sid" "main" ""
+
+  run auto_stash "main" "$sid"
+  [ "$status" -eq 1 ]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
+
+@test "auto_stash: stash message includes branch name" {
+  cd "$TEST_REPO"
+  local sid="test-stash-msg"
+  init_state "$sid" "feat/my-feature" ""
+
+  echo "changes" > stash-test.txt
+  git add stash-test.txt
+
+  auto_stash "feat/my-feature" "$sid"
+
+  local stash_msg
+  stash_msg=$(git stash list --format='%s' | head -1)
+  [[ "$stash_msg" == *"feat/my-feature"* ]]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
+
+# ---------- auto_restore_stash ----------
+
+@test "auto_restore_stash: restores stash and removes from state" {
+  cd "$TEST_REPO"
+  local sid="test-restore-ok"
+  init_state "$sid" "main" ""
+
+  # Create changes and stash them
+  echo "restore me" > restore-file.txt
+  git add restore-file.txt
+  auto_stash "main" "$sid"
+
+  # Verify file is gone from working tree
+  [ ! -f "restore-file.txt" ] || [ -z "$(git status --porcelain)" ]
+
+  # Restore the stash
+  run auto_restore_stash "main" "$sid"
+  [ "$status" -eq 0 ]
+
+  # Verify file is back
+  [ -f "restore-file.txt" ]
+
+  # Verify state no longer has the stash ref
+  local state_file
+  state_file=$(get_state_file "$sid")
+  local stash_refs_count
+  stash_refs_count=$(cat "$state_file" | jq '.stashRefs | length')
+  [ "$stash_refs_count" = "0" ]
+
+  rm -f "$state_file"
+}
+
+@test "auto_restore_stash: returns 1 when no stash exists for branch" {
+  cd "$TEST_REPO"
+  local sid="test-restore-none"
+  init_state "$sid" "main" ""
+
+  run auto_restore_stash "feat/no-stash" "$sid"
+  [ "$status" -eq 1 ]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
+
+@test "auto_restore_stash: returns 1 when session_id is empty" {
+  cd "$TEST_REPO"
+  run auto_restore_stash "main" ""
+  [ "$status" -eq 1 ]
+}
+
+@test "auto_restore_stash: fails gracefully when stash pop conflicts" {
+  cd "$TEST_REPO"
+  local sid="test-restore-conflict"
+  init_state "$sid" "main" ""
+
+  # Stash a change to a tracked file
+  echo "stashed version" > README.md
+  git add README.md
+  auto_stash "main" "$sid"
+
+  # Now modify the same file so the pop will conflict
+  echo "conflicting version" > README.md
+  git add README.md
+  git commit -m "feat: conflicting change" >/dev/null 2>&1
+
+  # The stash pop should fail due to conflict
+  run auto_restore_stash "main" "$sid"
+  [ "$status" -eq 1 ]
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  rm -f "$state_file"
+}
diff --git a/plugins/git-pilot/tests/state.bats b/plugins/git-pilot/tests/state.bats
new file mode 100644
index 0000000..5af938f
--- /dev/null
+++ b/plugins/git-pilot/tests/state.bats
@@ -0,0 +1,217 @@
+#!/usr/bin/env bats
+
+# Tests for state.sh: get_state_file, init_state, read_state, update_state,
+# write_state, cleanup_state.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  source_script "config.sh"
+  source_script "state.sh"
+}
+
+teardown() {
+  # Clean up any state files created during the test
+  rm -f /tmp/git-pilot-test-session-*.json
+  teardown_test_repo
+}
+
+# ---------- get_state_file ----------
+
+@test "get_state_file: returns expected path pattern" {
+  run get_state_file "abc123"
+  [ "$status" -eq 0 ]
+  [ "$output" = "/tmp/git-pilot-abc123.json" ]
+}
+
+# ---------- read_state ----------
+
+@test "read_state: returns empty object when file does not exist" {
+  run read_state "/tmp/git-pilot-nonexistent-12345.json"
+  [ "$status" -eq 0 ]
+  [ "$output" = "{}" ]
+}
+
+@test "read_state: returns content of valid JSON file" {
+  local state_file="/tmp/git-pilot-test-session-read.json"
+  echo '{"sessionId":"s1","changeCount":0}' > "$state_file"
+
+  run read_state "$state_file"
+  [ "$status" -eq 0 ]
+  local sid
+  sid=$(echo "$output" | jq -r '.sessionId')
+  [ "$sid" = "s1" ]
+}
+
+@test "read_state: returns empty object for invalid JSON" {
+  local state_file="/tmp/git-pilot-test-session-invalid.json"
+  echo "not valid json {{{" > "$state_file"
+
+  run read_state "$state_file"
+  [ "$status" -eq 0 ]
+  [ "$output" = "{}" ]
+}
+
+# ---------- init_state (3-arg: session_id, working_branch, previous_branch) ----------
+
+@test "init_state: creates state file with 3 args" {
+  local sid="test-session-3arg"
+  init_state "$sid" "feat/my-feature" "main"
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  [ -f "$state_file" ]
+
+  local content
+  content=$(cat "$state_file")
+
+  local session_id
+  session_id=$(echo "$content" | jq -r '.sessionId')
+  [ "$session_id" = "$sid" ]
+
+  local wb
+  wb=$(echo "$content" | jq -r '.workingBranch')
+  [ "$wb" = "feat/my-feature" ]
+
+  local pb
+  pb=$(echo "$content" | jq -r '.previousBranch')
+  [ "$pb" = "main" ]
+
+  # base_branch and branchPurpose should be empty strings
+  local bb
+  bb=$(echo "$content" | jq -r '.baseBranch')
+  [ "$bb" = "" ]
+
+  rm -f "$state_file"
+}
+
+# ---------- init_state (5-arg: session_id, working_branch, previous_branch, base_branch, branch_purpose) ----------
+
+@test "init_state: creates state file with 5 args" {
+  local sid="test-session-5arg"
+  init_state "$sid" "fix/login-bug" "develop" "main" "fix login timeout"
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  [ -f "$state_file" ]
+
+  local content
+  content=$(cat "$state_file")
+
+  local bb
+  bb=$(echo "$content" | jq -r '.baseBranch')
+  [ "$bb" = "main" ]
+
+  local bp
+  bp=$(echo "$content" | jq -r '.branchPurpose')
+  [ "$bp" = "fix login timeout" ]
+
+  # Verify new fields exist with correct defaults
+  local change_count
+  change_count=$(echo "$content" | jq -r '.changeCount')
+  [ "$change_count" = "0" ]
+
+  local is_agent
+  is_agent=$(echo "$content" | jq -r '.isAgent')
+  [ "$is_agent" = "false" ]
+
+  local stash_refs
+  stash_refs=$(echo "$content" | jq -r '.stashRefs | length')
+  [ "$stash_refs" = "0" ]
+
+  local active_worktrees
+  active_worktrees=$(echo "$content" | jq -r '.activeWorktrees | length')
+  [ "$active_worktrees" = "0" ]
+
+  rm -f "$state_file"
+}
+
+@test "init_state: records headAtStart from current HEAD" {
+  local sid="test-session-head"
+  local expected_head
+  expected_head=$(git rev-parse HEAD)
+
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  local head_at_start
+  head_at_start=$(cat "$state_file" | jq -r '.headAtStart')
+  [ "$head_at_start" = "$expected_head" ]
+
+  rm -f "$state_file"
+}
+
+# ---------- update_state ----------
+
+@test "update_state: increments changeCount" {
+  local sid="test-session-update"
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+
+  update_state "$state_file" '.changeCount += 1'
+
+  local count
+  count=$(cat "$state_file" | jq -r '.changeCount')
+  [ "$count" = "1" ]
+
+  # Increment again
+  update_state "$state_file" '.changeCount += 1'
+  count=$(cat "$state_file" | jq -r '.changeCount')
+  [ "$count" = "2" ]
+
+  rm -f "$state_file"
+}
+
+@test "update_state: sets isAgent to true with jq args" {
+  local sid="test-session-agent"
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+
+  update_state "$state_file" '.isAgent = true'
+
+  local is_agent
+  is_agent=$(cat "$state_file" | jq -r '.isAgent')
+  [ "$is_agent" = "true" ]
+
+  rm -f "$state_file"
+}
+
+@test "update_state: appends to modifiedFiles array" {
+  local sid="test-session-files"
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+
+  update_state "$state_file" --arg f "src/app.ts" '.modifiedFiles += [$f]'
+
+  local files_count
+  files_count=$(cat "$state_file" | jq '.modifiedFiles | length')
+  [ "$files_count" = "1" ]
+
+  local first_file
+  first_file=$(cat "$state_file" | jq -r '.modifiedFiles[0]')
+  [ "$first_file" = "src/app.ts" ]
+
+  rm -f "$state_file"
+}
+
+# ---------- cleanup_state ----------
+
+@test "cleanup_state: removes the state file" {
+  local sid="test-session-cleanup"
+  init_state "$sid" "main" ""
+
+  local state_file
+  state_file=$(get_state_file "$sid")
+  [ -f "$state_file" ]
+
+  cleanup_state "$state_file"
+  [ ! -f "$state_file" ]
+}
diff --git a/plugins/git-pilot/tests/test_helper/common.bash b/plugins/git-pilot/tests/test_helper/common.bash
new file mode 100644
index 0000000..573eea8
--- /dev/null
+++ b/plugins/git-pilot/tests/test_helper/common.bash
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+
+# Shared test helper for git-pilot bats tests.
+# Provides fixtures for creating isolated git repos, sourcing scripts,
+# and managing test configuration.
+
+# Absolute path to the plugin root (two levels up from test_helper/).
+PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SCRIPTS_DIR="$PLUGIN_DIR/scripts"
+
+# ---------- Git repo fixtures ----------
+
+# Creates a temporary git repository with an initial commit on the "main" branch.
+# Sets TEST_REPO, TEST_REMOTE (empty initially), and changes cwd into the repo.
+setup_test_repo() {
+  TEST_REPO="$(mktemp -d "${BATS_TMPDIR:-/tmp}/git-pilot-test.XXXXXX")"
+  TEST_REMOTE=""
+  cd "$TEST_REPO" || return 1
+
+  git init -b main >/dev/null 2>&1
+  git config user.name "Test User"
+  git config user.email "test@example.com"
+
+  # Create an initial commit so HEAD exists.
+  echo "init" > README.md
+  git add README.md
+  git commit -m "chore: initial commit" >/dev/null 2>&1
+}
+
+# Creates a bare repository and adds it as "origin" to the test repo.
+# Pushes the current branch so the remote has content.
+# Must be called after setup_test_repo.
+setup_remote_repo() {
+  TEST_REMOTE="$(mktemp -d "${BATS_TMPDIR:-/tmp}/git-pilot-remote.XXXXXX")"
+  git init --bare "$TEST_REMOTE" >/dev/null 2>&1
+
+  cd "$TEST_REPO" || return 1
+  git remote add origin "$TEST_REMOTE"
+  git push -u origin main >/dev/null 2>&1
+}
+
+# Removes the temporary directories created by setup_test_repo / setup_remote_repo.
+teardown_test_repo() {
+  if [[ -n "${TEST_REPO:-}" ]] && [[ -d "$TEST_REPO" ]]; then
+    rm -rf "$TEST_REPO"
+  fi
+  if [[ -n "${TEST_REMOTE:-}" ]] && [[ -d "$TEST_REMOTE" ]]; then
+    rm -rf "$TEST_REMOTE"
+  fi
+}
+
+# ---------- Configuration helpers ----------
+
+# Writes a JSON config file at the given path.
+# Usage: create_config "/path/to/config.json" '{"git":{"defaultBranch":"main"}}'
+create_config() {
+  local path="$1"
+  local json="$2"
+  mkdir -p "$(dirname "$path")"
+  echo "$json" > "$path"
+}
+
+# ---------- Script sourcing ----------
+
+# Sources a git-pilot script by name, setting the environment variables the
+# scripts expect (SCRIPT_DIR, PLUGIN_ROOT).
+#
+# Usage: source_script "config.sh"
+#        source_script "git-utils.sh"
+#
+# Scripts that reference SCRIPT_DIR or PLUGIN_ROOT at parse time (config.sh,
+# agent.sh, worktree.sh) will pick up the real plugin paths because we export
+# SCRIPT_DIR before sourcing.
+source_script() {
+  local script_name="$1"
+  local script_path="$SCRIPTS_DIR/$script_name"
+
+  if [[ ! -f "$script_path" ]]; then
+    echo "source_script: $script_path not found" >&2
+    return 1
+  fi
+
+  # Many scripts do `SCRIPT_DIR="$(cd ... && pwd)"` at the top which is fine --
+  # they will resolve to the real scripts directory.  We also export it so that
+  # scripts that only read the variable still work.
+  export SCRIPT_DIR="$SCRIPTS_DIR"
+  export PLUGIN_ROOT="$PLUGIN_DIR"
+
+  # Disable the set -euo pipefail that each script sets at the top so that
+  # bats `run` can capture non-zero exits without aborting the test.
+  # We achieve this by sourcing with a wrapper that traps errors.
+  # shellcheck disable=SC1090
+  source "$script_path"
+}
diff --git a/plugins/git-pilot/tests/worktree.bats b/plugins/git-pilot/tests/worktree.bats
new file mode 100644
index 0000000..2f3b34d
--- /dev/null
+++ b/plugins/git-pilot/tests/worktree.bats
@@ -0,0 +1,217 @@
+#!/usr/bin/env bats
+
+# Tests for worktree.sh: create_worktree, remove_worktree, list_worktrees,
+# merge_worktree_branch.
+
+load test_helper/common
+
+setup() {
+  setup_test_repo
+  # worktree.sh sources config.sh internally via SCRIPT_DIR, so we just need
+  # to ensure the git repo is set up.  We source it after cd into the test repo.
+  source_script "config.sh"
+  source_script "state.sh"
+  source_script "git-utils.sh"
+
+  # worktree.sh computes WORKTREE_REGISTRY at source time using git rev-parse.
+  # We must be in the test repo when we source it.
+  cd "$TEST_REPO"
+  source_script "worktree.sh"
+}
+
+teardown() {
+  # Clean up any worktrees that might have been created
+  cd "$TEST_REPO" 2>/dev/null || true
+  git worktree list --porcelain 2>/dev/null | grep '^worktree ' | while read -r _ path; do
+    if [[ "$path" != "$TEST_REPO" ]]; then
+      git worktree remove --force "$path" 2>/dev/null || true
+    fi
+  done
+  teardown_test_repo
+}
+
+# ---------- Helper ----------
+
+_default_config() {
+  cat "$PLUGIN_DIR/defaults/config.json"
+}
+
+# ---------- create_worktree ----------
+
+@test "create_worktree: creates worktree and registers in registry" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  run create_worktree "$config" "feat/new-worktree" "main" "session-wt-1"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"feat-new-worktree"* ]]
+
+  # Verify the worktree directory exists
+  local wt_path="$output"
+  [ -d "$wt_path" ]
+
+  # Verify registry entry
+  [ -f "$WORKTREE_REGISTRY" ]
+  local branch_in_registry
+  branch_in_registry=$(jq -r '.worktrees[0].branch' "$WORKTREE_REGISTRY")
+  [ "$branch_in_registry" = "feat/new-worktree" ]
+
+  local status_in_registry
+  status_in_registry=$(jq -r '.worktrees[0].status' "$WORKTREE_REGISTRY")
+  [ "$status_in_registry" = "active" ]
+}
+
+@test "create_worktree: records session ID in registry" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  run create_worktree "$config" "feat/session-tracked" "main" "my-session-42"
+  [ "$status" -eq 0 ]
+
+  local sid
+  sid=$(jq -r '.worktrees[0].createdBy' "$WORKTREE_REGISTRY")
+  [ "$sid" = "my-session-42" ]
+}
+
+@test "create_worktree: fails when branch already exists" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  # Create a branch first
+  git branch feat/existing-branch >/dev/null 2>&1
+
+  # Trying to create a worktree with -b for an existing branch should fail
+  run create_worktree "$config" "feat/existing-branch" "main"
+  [ "$status" -eq 1 ]
+}
+
+# ---------- remove_worktree ----------
+
+@test "remove_worktree: removes worktree and unregisters from registry" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  local wt_path
+  wt_path=$(create_worktree "$config" "feat/to-remove" "main")
+
+  # Verify it exists
+  [ -d "$wt_path" ]
+  local count_before
+  count_before=$(jq '.worktrees | length' "$WORKTREE_REGISTRY")
+  [ "$count_before" = "1" ]
+
+  run remove_worktree "$wt_path"
+  [ "$status" -eq 0 ]
+
+  # Verify worktree is gone
+  [ ! -d "$wt_path" ]
+
+  # Verify registry is empty
+  local count_after
+  count_after=$(jq '.worktrees | length' "$WORKTREE_REGISTRY")
+  [ "$count_after" = "0" ]
+}
+
+@test "remove_worktree: force removal succeeds with uncommitted changes" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  local wt_path
+  wt_path=$(create_worktree "$config" "feat/dirty-wt" "main")
+
+  # Create uncommitted changes in the worktree
+  echo "dirty" > "$wt_path/dirty-file.txt"
+  cd "$wt_path"
+  git add dirty-file.txt
+  cd "$TEST_REPO"
+
+  run remove_worktree "$wt_path" "true"
+  [ "$status" -eq 0 ]
+}
+
+# ---------- list_worktrees ----------
+
+@test "list_worktrees: returns empty structure when no worktrees registered" {
+  cd "$TEST_REPO"
+  run list_worktrees
+  [ "$status" -eq 0 ]
+  local count
+  count=$(echo "$output" | jq '.worktrees | length')
+  [ "$count" = "0" ]
+}
+
+@test "list_worktrees: returns registered worktrees" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  create_worktree "$config" "feat/wt-list-1" "main" >/dev/null
+  create_worktree "$config" "feat/wt-list-2" "main" >/dev/null
+
+  run list_worktrees
+  [ "$status" -eq 0 ]
+  local count
+  count=$(echo "$output" | jq '.worktrees | length')
+  [ "$count" = "2" ]
+}
+
+# ---------- merge_worktree_branch ----------
+
+@test "merge_worktree_branch: merges branch and cleans up worktree" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  local wt_path
+  wt_path=$(create_worktree "$config" "feat/to-merge" "main")
+
+  # Make a commit in the worktree
+  cd "$wt_path"
+  echo "merge me" > merge-file.txt
+  git add merge-file.txt
+  git commit -m "feat: merge file" >/dev/null 2>&1
+  cd "$TEST_REPO"
+
+  run merge_worktree_branch "$wt_path" "main" "$config"
+  [ "$status" -eq 0 ]
+  [ "$output" = "success" ]
+
+  # Verify the merge file exists on main
+  [ -f "$TEST_REPO/merge-file.txt" ]
+
+  # With cleanupOnMerge=true (default), worktree should be removed
+  [ ! -d "$wt_path" ]
+}
+
+@test "merge_worktree_branch: reports conflict on conflicting merge" {
+  cd "$TEST_REPO"
+  local config
+  config=$(_default_config)
+
+  local wt_path
+  wt_path=$(create_worktree "$config" "feat/conflict-merge" "main")
+
+  # Modify the same file in the worktree
+  cd "$wt_path"
+  echo "worktree version" > README.md
+  git add README.md
+  git commit -m "feat: worktree change" >/dev/null 2>&1
+
+  # Modify the same file on main
+  cd "$TEST_REPO"
+  echo "main version" > README.md
+  git add README.md
+  git commit -m "feat: main change" >/dev/null 2>&1
+
+  run merge_worktree_branch "$wt_path" "main" "$config"
+  [ "$status" -eq 1 ]
+  [ "$output" = "conflict" ]
+
+  # Clean up the failed merge
+  git merge --abort 2>/dev/null || true
+}

From 4171107a847486fa66b2ab812b2742fa87621198 Mon Sep 17 00:00:00 2001
From: Emeric Favarel <47535798+moukrea@users.noreply.github.com>
Date: Wed, 25 Feb 2026 00:06:40 +0100
Subject: [PATCH 7/7] chore(git-pilot): sync marketplace.json version to 2.0.0

---
 .claude-plugin/marketplace.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 9628622..70a88c1 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -53,8 +53,8 @@
     {
       "name": "git-pilot",
       "source": "./plugins/git-pilot",
-      "description": "Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, and natural language configuration.",
-      "version": "1.1.0",
+      "description": "Automated git workflow management for Claude Code — branch creation, commit formatting, push/MR workflows, rebase and conflict resolution, worktree management, stash automation, agent teams support, and natural language configuration.",
+      "version": "2.0.0",
       "author": {
         "name": "moukrea"
       },