@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/gemini-cli/harness-autopilot/SKILL.md

@@ -1,926 +1,275 @@
 # Harness Autopilot
 
-> Autonomous phase execution loop — chains planning, execution, verification, and review across multi-phase projects, pausing only at human decision points.
+> Lightweight orchestrator — dispatches isolated phase-agents, tracks state, chains artifacts between phases. Delegates all planning/execution/verification/review to dedicated persona agents.
 
 ## When to Use
 
-- After a multi-phase spec is approved and you want automated execution across all phases
-- When a project has 2+ implementation phases that would require repeated manual skill invocations
-- When you want the Ralph Loop pattern (fresh context per iteration, append-only learnings) applied at the phase level
+- After a multi-phase spec is approved and you want automated phase execution
+- When a project has 2+ implementation phases requiring repeated skill invocations
 - NOT for single-phase work (use harness-execution directly)
 - NOT when the spec is not yet approved (use harness-brainstorming first)
-- NOT for CI/headless execution (this is a conversational skill)
+- NOT for CI/headless execution (conversational skill)
 
-## Relationship to Other Skills
+## Persona Agents
 
-| Skill                | Persona Agent (`subagent_type`) | Role in Autopilot                            |
-| -------------------- | ------------------------------- | -------------------------------------------- |
-| harness-planning     | `harness-planner`               | Delegated to for phase plan creation         |
-| harness-execution    | `harness-task-executor`         | Delegated to for task-by-task implementation |
-| harness-verification | `harness-verifier`              | Delegated to for post-execution validation   |
-| harness-code-review  | `harness-code-reviewer`         | Delegated to for post-verification review    |
+| Skill                | `subagent_type`         | State(s)             |
+| -------------------- | ----------------------- | -------------------- |
+| harness-planning     | `harness-planner`       | PLAN                 |
+| harness-execution    | `harness-task-executor` | EXECUTE              |
+| harness-verification | `harness-verifier`      | VERIFY               |
+| harness-code-review  | `harness-code-reviewer` | REVIEW, FINAL_REVIEW |
 
-Autopilot orchestrates these persona agents — it never reimplements their logic. Each agent is dispatched via the Agent tool with the corresponding `subagent_type`, which isolates it to the harness methodology and prevents it from using unrelated skills.
-
-## Iron Law
-
-**Autopilot delegates, never reimplements.** If you find yourself writing planning logic, execution logic, or review logic inside the autopilot loop, STOP. Delegate to the dedicated persona agent.
-
-**Always use dedicated persona agents, never general-purpose agents.** Every dispatch MUST target the specific harness persona (`harness-planner`, `harness-task-executor`, `harness-verifier`, `harness-code-reviewer`). General-purpose agents see all globally registered skills and may use unrelated workflows instead of the harness methodology.
-
-- **Claude Code:** Use the Agent tool with `subagent_type` set to the persona name.
-- **Gemini CLI:** Use the `run_agent` tool targeting the persona by name, or dispatch via `harness persona run <name>`.
-
-**Plans are gated by concern signals.** When no concern signals fire (low complexity, no planner concerns, task count within threshold), plans are auto-approved with a structured report and execution proceeds immediately. When any signal fires, the plan pauses for human review with the standard yes/revise/skip/stop flow. The `--review-plans` session flag forces all plans to pause regardless of signals.
+**Iron Law:** Autopilot delegates, never reimplements. If writing plan/execute/verify/review logic, STOP — delegate via `subagent_type`. Always use dedicated persona agents, never general-purpose agents.
 
 ## Rigor Levels
 
-The `rigorLevel` is set during INIT via `--fast` or `--thorough` flags and persists for the entire session. Default is `standard`.
-
-| State          | `fast`                                                                                 | `standard` (default)                                                    | `thorough`                                                                                                                 |
-| -------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| PLAN           | Pass `rigorLevel: fast` to planner. Planner skips skeleton pass.                       | Default planner behavior.                                               | Pass `rigorLevel: thorough` to planner. Planner always produces skeleton for approval.                                     |
-| APPROVE_PLAN   | Auto-approve all plans regardless of concern signals. Skip human review.               | Default signal-based approval logic.                                    | Force human review of all plans (equivalent to `--review-plans`).                                                          |
-| EXECUTE        | Skip scratchpad — agents keep research in conversation. Checkpoint commits still fire. | Agents use scratchpad for research >500 words. Checkpoint commits fire. | Verbose scratchpad — agents write all research, reasoning, and intermediate output to scratchpad. Checkpoint commits fire. |
-| VERIFY         | Minimal verification — run `harness validate` only. Skip detailed verification agent.  | Default verification pipeline.                                          | Full verification — run verification agent with expanded checks.                                                           |
-| PHASE_COMPLETE | Scratchpad clear is a no-op (nothing written).                                         | Clear scratchpad for completed phase.                                   | Clear scratchpad for completed phase.                                                                                      |
+Set at INIT (`--fast` / `--thorough`); persists for session. Default: `standard`.
 
-When `rigorLevel` is `fast`, the APPROVE_PLAN concern signal evaluation is bypassed entirely — plans always auto-approve. When `rigorLevel` is `thorough`, it implicitly sets `reviewPlans: true` for the APPROVE_PLAN gate.
+| State        | `fast`                     | `standard`            | `thorough`                    |
+| ------------ | -------------------------- | --------------------- | ----------------------------- |
+| PLAN         | Skip skeleton pass         | Default               | Always skeleton with approval |
+| APPROVE_PLAN | Auto-approve, skip signals | Signal-based          | Force human review            |
+| EXECUTE      | Skip scratchpad            | Scratchpad >500 words | Verbose scratchpad            |
+| VERIFY       | `harness validate` only    | Full pipeline         | Expanded checks               |
 
-## Process
-
-### State Machine
+## State Machine
 
 ```
 INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE
-                                                                         ↓
-                                                                   [next phase?]
-                                                                    ↓         ↓
-                                                                 ASSESS   FINAL_REVIEW → DONE
+                                                                    │
+                                                             [next phase?]
+                                                              │           │
+                                                           ASSESS   FINAL_REVIEW → DONE
 ```
 
 ---
 
-### Phase 1: INIT — Load Spec and Restore State
-
-1. **Resolve spec path.** The spec file is provided as an argument, or ask the user for the spec path.
-
-2. **Derive session slug and directory:**
-   - Derive the session slug from the spec path:
-     1. If the path starts with `docs/`, strip the `docs/` prefix. Otherwise, use the full relative path.
-     2. Drop the trailing `.md` extension
-     3. Replace all `/` and `.` characters with `--`
-     4. Lowercase the result
-   - Set `sessionDir = .harness/sessions/<slug>/`
-   - Create the session directory if it does not exist
-
-3. **Check for existing state.** Read `{sessionDir}/autopilot-state.json`. If it exists and `currentState` is not `DONE`:
-   - **Schema migration:** If `schemaVersion < 3`, backfill missing fields: set `startingCommit` to the earliest commit in `history` (or current HEAD if no history), set `decisions` to `[]`, set `finalReview` to `{ "status": "pending", "findings": [], "retryCount": 0 }`. If `schemaVersion < 4`, set `reviewPlans` to `false`. Update `schemaVersion` to `4` and save. If `schemaVersion < 5`, set `rigorLevel` to `"standard"`. Update `schemaVersion` to `5` and save.
-   - Report: "Resuming autopilot from state `{currentState}`, phase {currentPhase}: {phaseName}."
-   - Skip steps 4 and 5 (initial state creation and flag parsing) — these only apply to fresh starts.
-   - Skip to the recorded `currentState` and continue from there.
-
-4. **If no existing state (fresh start):**
-   - Read the spec file.
-   - Parse the `## Implementation Order` section to extract phases.
-   - For each phase heading (`### Phase N: Name`), extract:
-     - Phase name
-     - Complexity annotation (`<!-- complexity: low|medium|high -->`, default: `medium`)
-   - Capture the starting commit: run `git rev-parse HEAD` and store the result as `startingCommit`.
-   - Create `{sessionDir}/autopilot-state.json`:
-     ```json
-     {
-       "schemaVersion": 5,
-       "sessionDir": ".harness/sessions/<slug>",
-       "specPath": "<path to spec>",
-       "startingCommit": "<git rev-parse HEAD output>",
-       "reviewPlans": false,
-       "rigorLevel": "standard",
-       "currentState": "ASSESS",
-       "currentPhase": 0,
-       "phases": [
-         {
-           "name": "<phase name>",
-           "complexity": "<low|medium|high>",
-           "complexityOverride": null,
-           "planPath": null,
-           "status": "pending"
-         }
-       ],
-       "retryBudget": {
-         "maxAttempts": 3,
-         "currentTask": null
-       },
-       "history": [],
-       "decisions": [],
-       "finalReview": {
-         "status": "pending",
-         "findings": [],
-         "retryCount": 0
-       }
-     }
-     ```
-
-5. **Parse session flags.** Check CLI arguments for session-level flags. These persist for the entire session -- resuming a session preserves the settings from when it was started (flags are only read on fresh start, not on resume).
-   - `--review-plans`: Set `state.reviewPlans: true`.
-   - `--fast`: Set `state.rigorLevel: "fast"`. Reduces rigor across all phases: skip skeleton approval, skip scratchpad, minimal verification.
-   - `--thorough`: Set `state.rigorLevel: "thorough"`. Increases rigor across all phases: require skeleton approval, verbose scratchpad, full verification.
-   - If neither `--fast` nor `--thorough` is passed, `rigorLevel` defaults to `"standard"`.
-   - If both `--fast` and `--thorough` are passed, reject with error: "Cannot use --fast and --thorough together. Choose one."
-
-6. **Load context via gather_context.** Use the `gather_context` MCP tool to load all working context efficiently:
-
-   ```json
-   gather_context({
-     path: "<project-root>",
-     intent: "Autopilot phase execution for <spec name>",
-     skill: "harness-autopilot",
-     session: "<session-slug>",
-     include: ["state", "learnings", "handoff", "validation"]
-   })
-   ```
-
-   This loads session-scoped learnings, handoff, state, and validation results in a single call. The `session` parameter ensures all reads come from the session directory (`.harness/sessions/<slug>/`), isolating this workstream from others. Note any relevant learnings or known dead ends for the current phase from the returned `learnings` array.
-
-7. **Load session summary for cold start.** If resuming (existing `autopilot-state.json` found):
-   - Call `loadSessionSummary()` for the session slug to get quick orientation context (~200 tokens).
-   - The summary provides the last skill, phase, status, and next step — enough to understand where the autopilot left off without re-reading the full state machine.
-   - If no summary exists (first run), skip — the full INIT handles context loading.
-
-8. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
-   - Current project priorities (which features are `in-progress`)
-   - Blockers that may affect the upcoming phases
-   - Overall project status and milestone progress
+### INIT
 
-   This provides the autopilot with project-level context beyond the individual spec being executed. If the roadmap does not exist, skip this step — the autopilot operates normally without it.
-
-9. **Transition to ASSESS.**
+1. Resolve spec path (argument or prompt).
+2. Derive session slug: strip `docs/`, drop `.md`, replace `/` and `.` with `--`, lowercase. Set `sessionDir = .harness/sessions/<slug>/`.
+3. Check for existing state: read `{sessionDir}/autopilot-state.json`. If present and not DONE: report "Resuming from `{currentState}`, phase {N}: {name}." Apply schema migration if `schemaVersion < 5` (backfill missing fields). Jump to recorded state.
+4. Fresh start: read spec, parse `## Implementation Order` for phases (`### Phase N: Name` + `<!-- complexity: low|medium|high -->`, default: `medium`). Capture `startingCommit` via `git rev-parse HEAD`. Write `autopilot-state.json` (schemaVersion: 5, currentState: "ASSESS", currentPhase: 0).
+5. Flags: `--fast` → `rigorLevel: "fast"`. `--thorough` → `rigorLevel: "thorough"`. `--review-plans` → `reviewPlans: true`. Both flags together → reject with error.
+6. Call `gather_context({ path, skill: "harness-autopilot", session: slug, include: ["state", "learnings", "handoff", "validation"] })`.
+7. → ASSESS.
 
 ---
 
-### ASSESS — Determine Phase Approach
-
-1. **Read the current phase** from `{sessionDir}/autopilot-state.json` at index `currentPhase`.
-
-2. **Check if plan already exists.** If `planPath` is set and the file exists, skip to `APPROVE_PLAN`.
+### ASSESS
 
-3. **Evaluate complexity:**
-   - Read the phase's `complexity` field from state.
-   - If `complexityOverride` is set, use it instead.
-   - Decision matrix:
-
-     | Effective Complexity | Action                                                                                                                                                                                                                               |
-     | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-     | `low`                | Auto-plan via `harness-planner` agent. Proceed to PLAN.                                                                                                                                                                              |
-     | `medium`             | Auto-plan via `harness-planner` agent. Proceed to PLAN. Present with extra scrutiny note.                                                                                                                                            |
-     | `high`               | Pause. Tell the user: "Phase {N}: {name} is marked high-complexity. Run `/harness:planning` interactively for this phase, then re-invoke `/harness:autopilot` to continue." Transition to PLAN with `awaitingInteractivePlan: true`. |
-
-4. **Update state** with `currentState: "PLAN"` and save.
+1. Read current phase at `currentPhase`.
+2. If `planPath` set and file exists: → APPROVE_PLAN.
+3. Complexity routing:
+   - `low`/`medium`: auto-plan via harness-planner → PLAN.
+   - `high`: pause. Instruct: "Run `/harness:planning` interactively, then re-invoke `/harness:autopilot`." Wait for re-invocation.
+4. Update `currentState: "PLAN"`.
 
 ---
 
-### PLAN — Generate or Await Plan
-
-**If auto-planning (low/medium complexity):**
-
-1. Dispatch a planning agent using the Agent tool:
-
-   ```
-   Agent tool parameters:
-     subagent_type: "harness-planner"
-     description: "Plan phase {N}: {name}"
-     prompt: |
-       You are running harness-planning for phase {N}: {name}.
-
-       Spec: {specPath}
-       Session directory: {sessionDir}
-       Session slug: {sessionSlug}
-       Phase description: {phase description from spec}
-       Rigor level: {rigorLevel}
-
-       On startup, call gather_context({ session: "{sessionSlug}" }) to load
-       session-scoped learnings, state, and validation context.
+### PLAN
 
-       ## Scratchpad (if rigorLevel is not "fast")
+**Auto-plan (low/medium):** Dispatch harness-planner:
 
-       For bulky research output (spec analysis, codebase exploration notes,
-       dependency analysis — anything >500 words), write to scratchpad instead
-       of keeping in conversation:
-
-         writeScratchpad({ session: "{sessionSlug}", phase: "{phaseName}", projectPath: "{projectPath}" }, "research-{topic}.md", content)
-
-       Reference the scratchpad file path in your conversation instead of
-       inlining the content. This keeps the planning context focused on
-       decisions and task structure.
+```
+subagent_type: "harness-planner"
+prompt: "Phase {N}: {name}. Spec: {specPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Follow harness-planning. Write plan to docs/plans/. Write {sessionDir}/handoff.json when done."
+```
 
-       Follow the harness-planning skill process exactly. Write the plan to
-       docs/plans/{date}-{phase-name}-plan.md. Write {sessionDir}/handoff.json when done.
-   ```
+On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override check: `low` + tasks>10 or checkpoints>3 → `"medium"`; tasks>20 or checkpoints>6 → `"high"`. Update state `planPath`. → APPROVE_PLAN.
 
-2. When the agent returns:
-   - Read the generated plan path from `{sessionDir}/handoff.json`.
-   - **Apply complexity override check:**
-     - Count tasks in the plan.
-     - Count `[checkpoint:*]` markers.
-     - If `spec_complexity == "low"` AND (`task_count > 10` OR `checkpoint_count > 3`):
-       Set `complexityOverride: "medium"` in state. Note to user: "Planning produced {N} tasks — more than expected for low complexity. Reviewing with extra scrutiny."
-     - If `spec_complexity == "low"` AND (`task_count > 20` OR `checkpoint_count > 6`):
-       Set `complexityOverride: "high"` in state. Note to user: "This phase is significantly larger than expected. Consider breaking it down."
-   - Update state: set `planPath` for the current phase.
-   - Transition to `APPROVE_PLAN`.
-
-**If awaiting interactive plan (high complexity):**
-
-1. Check if a plan file now exists for this phase (user ran planning separately).
-   - Look for files matching `docs/plans/*{phase-name}*` or check `{sessionDir}/handoff.json` for a planning handoff.
-2. If found: update `planPath` in state, transition to `APPROVE_PLAN`.
-3. If not found: remind the user and wait.
+**Interactive plan (high):** Check for plan file at `docs/plans/*{phase-name}*` or `planPath` in handoff. If found: update `planPath` → APPROVE_PLAN. If not: remind and wait.
 
 ---
 
-### APPROVE_PLAN — Conditional Review Gate
-
-1. **Gather plan metadata:**
-   - Phase name and number
-   - Task count (from the plan file)
-   - Checkpoint count
-   - Estimated time (task count x 3 minutes)
-   - Effective complexity (original + any override)
-   - Concerns array from the planning handoff (`{sessionDir}/handoff.json` field `concerns`, default: `[]` if field is absent)
-
-2. **Rigor-level override:**
-   - If `rigorLevel` is `"fast"`: Skip the signal evaluation entirely. Auto-approve the plan. Record decision as `"auto_approved_plan_fast"`. Transition directly to EXECUTE.
-   - If `rigorLevel` is `"thorough"`: Force `shouldPauseForReview = true` regardless of other signals (equivalent to `--review-plans`).
-   - If `rigorLevel` is `"standard"`: Proceed with normal signal evaluation below.
-
-3. **Evaluate `shouldPauseForReview`.** Check the following signals in order. If **any** signal is true, pause for human review. If **all** are false, auto-approve.
-
-   | #   | Signal               | Condition                             | Description                                                                                                                                                                                  |
-   | --- | -------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | 1   | `reviewPlans`        | `state.reviewPlans === true`          | Session-level flag set by `--review-plans` CLI arg                                                                                                                                           |
-   | 2   | `highComplexity`     | `phase.complexity === "high"`         | Phase is marked as high complexity in the spec (reachable when resuming after interactive planning; confirms the plan is ready for automated execution even though the human drove planning) |
-   | 3   | `complexityOverride` | `phase.complexityOverride !== null`   | Planner produced more tasks than expected for the spec complexity                                                                                                                            |
-   | 4   | `plannerConcerns`    | Handoff `concerns` array is non-empty | Planner flagged specific risks or uncertainties                                                                                                                                              |
-   | 5   | `taskCount`          | Plan contains > 15 tasks (i.e., 16+)  | Plan is large enough to warrant human review                                                                                                                                                 |
-
-4. **Build the signal evaluation result** for reporting and recording:
-
-   ```json
-   {
-     "reviewPlans": false,
-     "highComplexity": "low",
-     "complexityOverride": null,
-     "plannerConcerns": [],
-     "taskCount": 8,
-     "taskThreshold": 15
-   }
-   ```
-
-5. **If auto-approving (no signals fired):**
-
-   a. **Emit structured auto-approve report:**
-
-   ```
-   Auto-approved Phase 1: Setup Infrastructure
-     Review mode: auto
-     Complexity: low (no override)
-     Planner concerns: none
-     Tasks: 8 (threshold: 15)
-   ```
-
-   b. **Record the decision** in state `decisions` array:
-
-   ```json
-   {
-     "phase": 0,
-     "decision": "auto_approved_plan",
-     "timestamp": "ISO-8601",
-     "signals": {
-       "reviewPlans": false,
-       "highComplexity": "low",
-       "complexityOverride": null,
-       "plannerConcerns": [],
-       "taskCount": 8,
-       "taskThreshold": 15
-     }
-   }
-   ```
-
-   c. **Transition to EXECUTE** — no human interaction needed.
-
-6. **If pausing for review (one or more signals fired):**
-
-   a. **Emit structured pause report** showing which signal(s) triggered:
-
-   ```
-   Pausing for review -- Phase 2: Auth Middleware
-     Review mode: manual (--review-plans flag set)
-     Complexity override: low -> medium (triggered)
-     Planner concerns: 2 concern(s)
-     Tasks: 12 (threshold: 15)
-   ```
-
-   Mark triggered signals explicitly. Non-triggered signals display their normal value without "(triggered)".
-
-   b. **Present the plan summary:** task count, checkpoint count, estimated time, effective complexity, and any concerns from the planning handoff.
-
-   c. **Ask:** "Approve this plan and begin execution? (yes / revise / skip phase / stop)"
-   - **yes** — Transition to EXECUTE.
-   - **revise** — Tell user to edit the plan file directly, then re-present from step 1.
-   - **skip phase** — Mark phase as `skipped` in state, transition to PHASE_COMPLETE.
-   - **stop** — Save state and exit. User can resume later.
-
-   d. **Record the decision** in state `decisions` array:
-
-   ```json
-   {
-     "phase": 0,
-     "decision": "approved_plan",
-     "timestamp": "ISO-8601",
-     "signals": {
-       "reviewPlans": true,
-       "highComplexity": "low",
-       "complexityOverride": "medium",
-       "plannerConcerns": ["concern text"],
-       "taskCount": 12,
-       "taskThreshold": 15
-     }
-   }
-   ```
-
-   Use the actual decision value: `approved_plan`, `revised_plan`, `skipped_phase`, or `stopped`.
+### APPROVE_PLAN
 
-7. **Update state** with `currentState: "EXECUTE"` (or appropriate state for skip/stop) and save.
+1. Gather: task count, checkpoint count, concerns from `{sessionDir}/handoff.json` (default `[]`).
+2. `"fast"` → auto-approve, record `"auto_approved_plan_fast"`, → EXECUTE.
+3. `"thorough"` → force `shouldPauseForReview = true`.
+4. Signals (any true → pause; all false → auto-approve):
+   - `reviewPlans: true`
+   - `phase.complexity === "high"`
+   - `phase.complexityOverride !== null`
+   - Handoff `concerns` non-empty
+   - Task count > 15
+5. **Auto-approve:** emit report (mode, complexity, concerns, task count). Record decision with signal snapshot in `decisions[]`. → EXECUTE.
+6. **Pause:** show triggered signals. Ask "Approve? (yes / revise / skip phase / stop)." Record decision. Route accordingly.
 
 ---
 
-### EXECUTE — Run the Plan
+### EXECUTE
 
-1. **Dispatch execution agent using the Agent tool:**
+Dispatch harness-task-executor:
 
-   ```
-   Agent tool parameters:
-     subagent_type: "harness-task-executor"
-     description: "Execute phase {N}: {name}"
-     prompt: |
-       You are running harness-execution for phase {N}: {name}.
-
-       Plan: {planPath}
-       Session directory: {sessionDir}
-       Session slug: {sessionSlug}
-       State: {sessionDir}/state.json
-       Rigor level: {rigorLevel}
-
-       On startup, call gather_context({ session: "{sessionSlug}" }) to load
-       session-scoped learnings, state, and validation context.
-
-       ## Scratchpad (if rigorLevel is not "fast")
-
-       For bulky intermediate output (test output analysis, error investigation
-       notes, dependency trees — anything >500 words), write to scratchpad:
-
-         writeScratchpad({ session: "{sessionSlug}", phase: "{phaseName}", projectPath: "{projectPath}" }, "task-{N}-{topic}.md", content)
+```
+subagent_type: "harness-task-executor"
+prompt: "Phase {N}: {name}. Plan: {planPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Update {sessionDir}/state.json per task. Write {sessionDir}/handoff.json when done or blocked."
+```
 
-       Reference the scratchpad file path instead of inlining the content.
+**Checkpoints:** `[checkpoint:human-verify]` → show output, confirm, resume. `[checkpoint:decision]` → present options, record choice, resume. `[checkpoint:human-action]` → instruct user, wait for confirmation, resume. After each passing checkpoint: `commitAtCheckpoint()`.
 
-       Follow the harness-execution skill process exactly.
-       Update {sessionDir}/state.json after each task.
-       Write {sessionDir}/handoff.json when done or when blocked.
-   ```
+**Outcome:** All tasks complete → VERIFY. Task fails → retry logic:
 
-2. **When the agent returns, check the outcome:**
-   - **After each checkpoint verification passes**, commit the work:
-     ```
-     commitAtCheckpoint({
-       projectPath: "{projectPath}",
-       session: "{sessionSlug}",
-       checkpointLabel: "Checkpoint {N}: {checkpoint description}"
-     })
-     ```
-     If the commit result shows `committed: false`, no changes existed — continue silently.
-   - **All tasks complete:** Transition to VERIFY.
-   - **Checkpoint reached:** Surface the checkpoint to the user in the main conversation. Handle the checkpoint type:
-     - `[checkpoint:human-verify]` — Show output, ask for confirmation, then resume execution agent.
-     - `[checkpoint:decision]` — Present options, record choice, resume execution agent.
-     - `[checkpoint:human-action]` — Instruct user, wait for confirmation, resume execution agent.
-   - **Task failed:** Enter retry logic (see below).
-
-3. **Retry logic on failure:**
-   - Read `retryBudget` from state.
-   - If `attemptsUsed < maxAttempts`:
-     - Increment `attemptsUsed`.
-     - Record the attempt (timestamp, error, fix attempted, result).
-     - **Attempt 1:** Read error output, apply obvious fix, re-dispatch execution agent for the failed task only.
-     - **Attempt 2:** Expand context — read related files, check `learnings.md` for similar failures, re-dispatch with additional context.
-     - **Attempt 3:** Full context gather — read test output, imports, plan instructions for ambiguity. Re-dispatch with maximum context.
-   - If budget exhausted:
-     - **Recovery commit:** Before stopping, commit any passing work:
-       ```
-       commitAtCheckpoint({
-         projectPath: "{projectPath}",
-         session: "{sessionSlug}",
-         checkpointLabel: "Phase {N}: {name} — recovery at task {taskNumber}",
-         isRecovery: true
-       })
-       ```
-       This preserves all work completed before the failure. The `[autopilot][recovery]` prefix in the commit message distinguishes recovery commits from normal checkpoint commits.
-     - **Stop.** Present all 3 attempts with full context to the user.
-     - Record failure in `.harness/failures.md`.
-     - Ask: "How should we proceed? (fix manually and continue / revise plan / stop)"
-     - Save state. User's choice determines next transition.
-
-4. **Update state** after each execution cycle and save.
+- Attempt 1: read error, apply obvious fix, re-dispatch for failed task.
+- Attempt 2: expand context — read related files, check `learnings.md`, re-dispatch.
+- Attempt 3: full context — test output, imports, plan instructions, re-dispatch.
+- Budget exhausted: recovery commit (`[autopilot][recovery]` prefix in message), record in `.harness/failures.md`. Ask: "fix manually and continue / revise plan / stop."
 
 ---
 
-### VERIFY — Post-Execution Validation
+### VERIFY
 
-1. **Rigor-level branching:**
-   - If `rigorLevel` is `"fast"`: Skip the verification agent entirely. Run only `harness validate`. If it passes, transition to REVIEW. If it fails, surface to user.
-   - If `rigorLevel` is `"thorough"` or `"standard"`: Dispatch the verification agent as below.
-
-2. **Dispatch verification agent using the Agent tool:**
-
-   ```
-   Agent tool parameters:
-     subagent_type: "harness-verifier"
-     description: "Verify phase {N}: {name}"
-     prompt: |
-       You are running harness-verification for phase {N}: {name}.
-
-       Session directory: {sessionDir}
-       Session slug: {sessionSlug}
-
-       On startup, call gather_context({ session: "{sessionSlug}" }) to load
-       session-scoped learnings, state, and validation context.
-
-       Follow the harness-verification skill process exactly.
-       Report pass/fail with findings.
-   ```
-
-3. **When the agent returns:**
-   - **All checks pass:** Transition to REVIEW.
-   - **Failures found:** Surface findings to the user. Ask: "Fix these issues before review? (fix / skip verification / stop)"
-     - **fix** — Re-enter EXECUTE with targeted fixes (retry budget resets for verification fixes).
-     - **skip** — Record skip decision in `decisions` array. Proceed to REVIEW with verification warnings noted.
-     - **stop** — Save state and exit.
-
-4. **Update state** with `currentState: "REVIEW"` and save.
+- `"fast"`: run `harness validate`. Pass → REVIEW. Fail → surface to user.
+- `"standard"`/`"thorough"`: dispatch harness-verifier:
+  ```
+  subagent_type: "harness-verifier"
+  prompt: "Phase {N}: {name}. Session: {sessionSlug}. Rigor: {rigorLevel}. Verify and report pass/fail with findings."
+  ```
+  Pass → REVIEW. Fail → ask "fix / skip verification / stop." `fix`: re-enter EXECUTE (retry budget resets).
 
 ---
 
-### REVIEW — Code Review
+### REVIEW
 
-1. **Dispatch review agent using the Agent tool:**
+Dispatch harness-code-reviewer:
 
-   ```
-   Agent tool parameters:
-     subagent_type: "harness-code-reviewer"
-     description: "Review phase {N}: {name}"
-     prompt: |
-       You are running harness-code-review for phase {N}: {name}.
-
-       Session directory: {sessionDir}
-       Session slug: {sessionSlug}
-
-       On startup, call gather_context({ session: "{sessionSlug}" }) to load
-       session-scoped learnings, state, and validation context.
-
-       Follow the harness-code-review skill process exactly.
-       Report findings with severity (blocking / warning / note).
-   ```
-
-2. **When the agent returns:**
-   - **Persist review findings:** Write the review findings to `{sessionDir}/phase-{N}-review.json` (array of findings with severity, file, line, title). This file is consumed by FINAL_REVIEW step 3.
-   - **No blocking findings:** Report summary, transition to PHASE_COMPLETE.
-   - **Blocking findings:** Surface to user. Ask: "Address blocking findings before completing this phase? (fix / override / stop)"
-     - **fix** — Re-enter EXECUTE with review fixes.
-     - **override** — Record override decision, transition to PHASE_COMPLETE.
-     - **stop** — Save state and exit.
+```
+subagent_type: "harness-code-reviewer"
+prompt: "Phase {N}: {name}. Session: {sessionSlug}. Follow harness-code-review. Report findings (critical / important / suggestion)."
+```
 
-3. **Update state** with `currentState: "PHASE_COMPLETE"` and save.
+Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_COMPLETE. Blocking → ask "fix / override / stop." `fix`: re-enter EXECUTE. `override`: record decision in `decisions[]` → PHASE_COMPLETE.
 
 ---
 
-### PHASE_COMPLETE — Summary and Transition
-
-1. **Present phase summary:**
-   - Phase name and number
-   - Tasks completed
-   - Retries used
-   - Verification result (pass/fail/skipped)
-   - Review findings count (blocking/warning/note)
-   - Time from phase start to completion (from history timestamps)
-
-2. **Record phase in history:**
-
-   ```json
-   {
-     "phase": 0,
-     "name": "<phase name>",
-     "startedAt": "<timestamp>",
-     "completedAt": "<now>",
-     "tasksCompleted": 8,
-     "retriesUsed": 1,
-     "verificationPassed": true,
-     "reviewFindings": { "blocking": 0, "warning": 1, "note": 3 }
-   }
-   ```
-
-3. **Mark phase as `complete`** in state.
-
-4. **Clear scratchpad for this phase.** Call `clearScratchpad({ session: sessionSlug, phase: phaseName, projectPath: projectPath })` to delete ephemeral research files for the completed phase. This frees disk space and prevents stale scratchpad data from leaking into future phases.
+### PHASE_COMPLETE
 
-5. **Sync roadmap.** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true`. This reflects the just-completed phase in the roadmap (e.g., updating the feature from `planned` to `in-progress`). If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
-
-6. **Write session summary.** Update the session summary to reflect the completed phase:
-
-   ```json
-   writeSessionSummary(projectPath, sessionSlug, {
-     session: "<session-slug>",
-     lastActive: "<ISO timestamp>",
-     skill: "harness-autopilot",
-     phase: "<completed phase number> of <total phases>",
-     status: "Phase <N> complete. <tasks completed>/<total> tasks.",
-     spec: "<spec path>",
-     plan: "<current plan path>",
-     keyContext: "<1-2 sentences: what this phase accomplished, key decisions>",
-     nextStep: "<e.g., Continue to Phase N+1: <name>, or DONE>"
-   })
-   ```
-
-7. **Check for next phase:**
-   - If more phases remain: "Phase {N} complete. Next: Phase {N+1}: {name} (complexity: {level}). Continue? (yes / stop)"
-     - **yes** — Increment `currentPhase`, reset `retryBudget`, transition to ASSESS.
-     - **stop** — Save state and exit.
-   - If no more phases: Transition to FINAL_REVIEW.
+1. Present summary: name, tasks completed, retries used, verification result, review findings count, elapsed time.
+2. Record in `history[]`: phase index, name, startedAt, completedAt, tasksCompleted, retriesUsed, verificationPassed, reviewFindings.
+3. Mark phase `complete` in state. Clear scratchpad: `clearScratchpad({ session, phase, projectPath })`.
+4. Sync roadmap: `manage_roadmap sync apply:true` (skip if no roadmap; never `force_sync: true`).
+5. Write session summary: `writeSessionSummary(projectPath, sessionSlug, { session, lastActive, skill: "harness-autopilot", phase, status, spec, plan, keyContext, nextStep })`.
+6. More phases: "Phase {N} complete. Next: {N+1}: {name} ({complexity}). Continue? (yes / stop)." `yes` → increment `currentPhase`, reset `retryBudget`, → ASSESS. `stop` → save and exit.
+7. No more phases: → FINAL_REVIEW.
 
 ---
 
-### FINAL_REVIEW — Project-Wide Code Review
-
-> Runs automatically after the last phase completes. Reviews the cumulative diff (`startingCommit..HEAD`) across all phases to catch cross-phase issues before the PR offer.
-
-1. **Update state** with `currentState: "FINAL_REVIEW"` and save.
-
-2. **Update `finalReview` tracking** in `autopilot-state.json`: set `finalReview.status` to `"in_progress"`.
-
-3. **Gather per-phase review findings.** Read from `{sessionDir}/` — each phase's review output is stored alongside the phase handoff. Collect all review findings across phases into a single context block.
-
-4. **Dispatch review agent using the Agent tool:**
+### FINAL_REVIEW
 
+1. Set `currentState: "FINAL_REVIEW"`, `finalReview.status: "in_progress"`.
+2. Gather per-phase findings from `{sessionDir}/phase-{N}-review.json` files.
+3. Dispatch harness-code-reviewer:
    ```
-   Agent tool parameters:
-     subagent_type: "harness-code-reviewer"
-     description: "Final review: cross-phase coherence check"
-     prompt: |
-       You are running harness-code-review as a final project-wide review.
-
-       Diff scope: startingCommit..HEAD (use `git diff {startingCommit}..HEAD`)
-       Starting commit: {startingCommit}
-       Session directory: {sessionDir}
-       Session slug: {sessionSlug}
-
-       On startup, call gather_context({ session: "{sessionSlug}" }) to load
-       session-scoped learnings, state, and validation context.
-
-       ## Per-Phase Review Findings
-
-       {collected per-phase findings}
-
-       These were found and addressed during per-phase reviews. Don't assume
-       they're resolved — verify. Focus extra attention on cross-phase coherence:
-       naming consistency, duplicated utilities, architectural drift across phases.
-
-       Review the FULL diff (startingCommit..HEAD), not just the last phase.
-       Report findings with severity (blocking / warning / note).
+   subagent_type: "harness-code-reviewer"
+   prompt: "Final cross-phase review. Diff: git diff {startingCommit}..HEAD. Session: {sessionSlug}. Prior findings: {collected}. Focus on cross-phase coherence: naming, duplicated utilities, architectural drift. Report findings (critical / important / suggestion)."
    ```
+4. No blocking: store in `finalReview.findings`, set `"passed"` → DONE.
+5. Blocking: ask "fix / override / stop."
+   - `fix`: increment `finalReview.retryCount` (max 3). Dispatch harness-task-executor: "Fix these blocking findings: {findings with file, line, title}. Session: {sessionSlug}. Commit each fix atomically." Run `harness validate`. Re-run FINAL_REVIEW from step 1. If retryCount > 3: stop, record in `.harness/failures.md`.
+   - `override`: record rationale in `decisions[]`. Set `"overridden"` → DONE.
+   - `stop`: save state and exit (resumable).
 
-5. **When the agent returns:**
-   - **No blocking findings:** Store all findings (blocking, warning, note) in `finalReview.findings`. Update `finalReview.status` to `"passed"`, report summary, transition to DONE.
-   - **Blocking findings:** Store all findings (blocking, warning, note) in `finalReview.findings`. Surface blocking findings to user. Ask: "Address blocking findings before completing? (fix / override / stop)"
-     - **fix** — Increment `finalReview.retryCount`. If `retryCount <= 3`: dispatch fixes using the Agent tool, then run `harness validate` to verify the fix, then re-run FINAL_REVIEW from step 2 (re-sets status to `in_progress`, re-gathers per-phase findings for fresh context). If `retryCount > 3`: stop — present all attempts to user, record in `.harness/failures.md`, ask: "How should we proceed? (fix manually and continue / stop)"
-
-       Fix dispatch:
-
-       ```
-       Agent tool parameters:
-         subagent_type: "harness-task-executor"
-         description: "Fix final review findings"
-         prompt: |
-           Fix the following blocking review findings. One task per finding.
+---
 
-           {blocking findings with file, line, title, and rationale}
+### DONE
 
-           Session directory: {sessionDir}
-           Session slug: {sessionSlug}
+1. Present: total phases, tasks, retries, time, `finalReview.status` + findings count, any overridden findings.
+2. Ask "Create a PR? (yes / no)."
+3. Write final handoff to `{sessionDir}/handoff.json`. Append learnings to `.harness/learnings.md`. Call `promoteSessionLearnings(projectPath, sessionSlug)`. If learnings count > 30, suggest `harness learnings prune`.
+4. If `docs/roadmap.md` exists: call `manage_roadmap update` to set feature done. Skip if not found.
+5. Write final `writeSessionSummary()`. Set `currentState: "DONE"` in autopilot-state.json.
 
-           Follow the harness-execution skill process. Commit each fix atomically.
-           Write {sessionDir}/handoff.json when done.
-       ```
+---
 
-     - **override** — Record override decision (rationale from user) in state `decisions` array. Update `finalReview.status` to `"overridden"`. Transition to DONE.
-     - **stop** — Save state and exit. Resumable from FINAL_REVIEW.
+## Process
 
-6. **Update state** and save after each step.
+1. **INIT** — Resolve spec, derive session slug, check for existing state, parse phases.
+2. **ASSESS** — Route by complexity: low/medium auto-plans, high pauses for interactive planning.
+3. **PLAN → APPROVE** — Dispatch harness-planner, check approval signals, auto-approve or pause.
+4. **EXECUTE** — Dispatch harness-task-executor with plan path, handle checkpoints and retries (max 3).
+5. **VERIFY → REVIEW** — Dispatch harness-verifier and harness-code-reviewer, fix blocking findings.
+6. **PHASE_COMPLETE** — Summarize, sync roadmap, loop to ASSESS for next phase or proceed to FINAL_REVIEW.
+7. **FINAL_REVIEW → DONE** — Cross-phase review, offer PR creation, write final handoff.
 
 ---
 
-### DONE — Final Summary
-
-1. **Present project summary:**
-   - Total phases completed
-   - Total tasks across all phases
-   - Total retries used
-   - Total time (first phase start to last phase completion)
-   - Final review result: `finalReview.status` (passed / overridden) and total findings count from `finalReview.findings`
-   - Any overridden review findings (per-phase and final)
-
-2. **Offer next steps:**
-   - "Create a PR? (yes / no)"
-   - If yes: assemble commit history, suggest PR title and description.
-
-3. **Write final handoff** to `{sessionDir}/handoff.json`:
-
-   ```json
-   {
-     "fromSkill": "harness-autopilot",
-     "phase": "DONE",
-     "summary": "Completed {N} phases with {M} total tasks",
-     "completed": ["Phase 1: ...", "Phase 2: ..."],
-     "pending": [],
-     "concerns": [],
-     "decisions": ["<all decisions from all phases>"],
-     "contextKeywords": ["<merged from spec>"],
-     "finalReview": {
-       "status": "<passed | overridden>",
-       "findingsCount": "<number of findings from final review>"
-     }
-   }
-   ```
-
-4. **Append learnings** to `.harness/learnings.md`:
-
-   ```
-   ## {date} — Autopilot: {spec name}
-   - [skill:harness-autopilot] [outcome:complete] Executed {N} phases, {M} tasks, {R} retries
-   - [skill:harness-autopilot] [outcome:observation] {any notable patterns from the run}
-   ```
+## Harness Integration
 
-5. **Promote session learnings to global.** Call `promoteSessionLearnings(projectPath, sessionSlug)` to move generalizable session learnings (tagged `[outcome:gotcha]`, `[outcome:decision]`, `[outcome:observation]`) to the global `learnings.md`. Report: "Promoted {N} learnings to global, {M} session-specific entries kept in session."
+- **State:** `{sessionDir}/autopilot-state.json` (orchestration) + `{sessionDir}/state.json` (task-level, written by harness-execution).
+- **Handoff:** `{sessionDir}/handoff.json` — written by each delegated skill, read by next. Autopilot writes final handoff at DONE.
+- **Checkpoint commits:** `commitAtCheckpoint()` after passing checkpoints. Recovery commits use `[autopilot][recovery]` prefix.
+- **Scratchpad:** cleared at PHASE_COMPLETE via `clearScratchpad()`. Skipped at `rigorLevel: "fast"`.
 
-6. **Check if pruning is needed.** Call `countLearningEntries(projectPath)`. If the count exceeds 30, suggest: "Global learnings.md has {count} entries (threshold: 30). Run `harness learnings prune` to analyze patterns and archive old entries."
+---
 
-7. **Update roadmap to done.** If `docs/roadmap.md` exists and the current spec maps to a roadmap feature, call `manage_roadmap` with action `update` to set the feature status to `done`. Derive the feature name from the spec title (H1 heading) or the session's `handoff.json` `summary` field. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `updateFeature()` from core and warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub." Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+## Gates
 
-8. **Write final session summary.** Update the session summary to reflect completion:
+- **No reimplementing delegated skills.** Writing planning/execution/verification/review logic → STOP. Delegate via `subagent_type`.
+- **No executing without plan approval.** Every plan passes APPROVE_PLAN. No exceptions.
+- **No skipping VERIFY or REVIEW.** Human can override findings; steps cannot be skipped.
+- **No infinite retries.** EXECUTE budget: 3 attempts. FINAL_REVIEW: 3 cycles. If exhausted, stop and surface.
+- **No modifying state files manually.** If corrupted, start fresh.
 
-   ```json
-   writeSessionSummary(projectPath, sessionSlug, {
-     session: "<session-slug>",
-     lastActive: "<ISO timestamp>",
-     skill: "harness-autopilot",
-     status: "DONE. <total phases> phases, <total tasks> tasks complete.",
-     spec: "<spec path>",
-     keyContext: "<1-2 sentences: overall summary of what was built>",
-     nextStep: "All phases complete. Create PR or close session."
-   })
-   ```
+## Escalation
 
-9. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
+- **Spec missing Implementation Order:** Cannot identify phases. Ask user to add phase annotations or provide roadmap.
+- **Delegated skill fails to produce output:** Check `{sessionDir}/handoff.json`. Report and ask: retry or stop.
+- **User wants to reorder phases mid-run:** Update `phases[]` (mark skipped, adjust `currentPhase`). Do not re-run completed phases.
+- **Context limits approaching:** Persist state immediately. "State saved. Re-invoke `/harness:autopilot` to continue."
+- **2 consecutive phase failures:** Suggest reviewing spec for systemic issues.
 
-## Harness Integration
+## Rationalizations to Reject
 
-- **`harness validate`** — Run during INIT to verify project health. Included in every execution task via harness-execution delegation.
-- **`gather_context`** — Used in INIT phase to load learnings, state, handoff, and validation in a single call instead of reading files individually.
-- **`harness check-deps`** — Delegated to harness-execution (included in task steps).
-- **State file** — `.harness/sessions/<slug>/autopilot-state.json` tracks the orchestration state machine. `.harness/sessions/<slug>/state.json` tracks task-level execution state (managed by harness-execution). The slug is derived from the spec path during INIT.
-- **Handoff** — `.harness/sessions/<slug>/handoff.json` is written by each delegated skill and read by the next. Autopilot writes a final handoff on DONE.
-- **Learnings** — `.harness/learnings.md` (global) is appended by both delegated skills and autopilot itself. On DONE, session learnings with generalizable outcomes are promoted to global via `promoteSessionLearnings`. If global count exceeds 30, autopilot suggests running `harness learnings prune`.
-- **Roadmap context** — During INIT, reads `docs/roadmap.md` (if present) for project-level priorities, blockers, and milestone status. Provides broader context for phase execution decisions.
-- **Roadmap sync** — During PHASE_COMPLETE, calls `manage_roadmap` with `sync` and `apply: true` to reflect phase progress. During DONE, calls `manage_roadmap` with `update` to set feature status to `done`. Both skip silently when no roadmap exists. Neither uses `force_sync: true`.
-- **Scratchpad** — Agents write bulky research output (>500 words) to `.harness/sessions/<slug>/scratchpad/<phase>/` via `writeScratchpad()` instead of keeping it in conversation context. Cleared automatically at phase transitions via `clearScratchpad()` in PHASE_COMPLETE. Skipped entirely when `rigorLevel` is `"fast"`.
-- **Checkpoint commits** — After each checkpoint verification passes in EXECUTE, `commitAtCheckpoint()` creates a commit with message `[autopilot] <label>`. On failure with retry budget exhausted, a recovery commit is created with `[autopilot][recovery] <label>`. Skipped silently when no changes exist.
-- **Rigor levels** — `--fast` / `--thorough` flags set `rigorLevel` in state during INIT. Persists for the entire session. Affects PLAN (skeleton skip/require), APPROVE_PLAN (auto-approve/force-review), EXECUTE (scratchpad usage), and VERIFY (minimal/full). See the Rigor Behavior Table for details.
+| Rationalization                                                         | Reality                                                                                           |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| "Low complexity means I can skip APPROVE_PLAN"                          | Low complexity means auto-approval only when no signals fire. Signals override complexity.        |
+| "I can inline planning logic instead of dispatching to harness-planner" | Iron Law. Autopilot delegates, never reimplements. No exceptions.                                 |
+| "Retry budget exhausted but one more approach might work"               | 3-attempt budget prevents compounding failure. Exceeding it without human input is unrecoverable. |
+| "Keeping research in conversation is faster than scratchpad"            | Scratchpad gated by rigor level. At standard/thorough, >500 words must go to scratchpad.          |
+| "Plan auto-approved, so I can skip recording the decision"              | Every approval—auto or manual—is recorded in `decisions[]`. That array is the audit trail.        |
 
 ## Success Criteria
 
-- Single `/harness:autopilot` invocation executes all phases through to completion
-- Resume from any state after context reset via session-scoped `autopilot-state.json`
-- Low-complexity phases auto-plan; high-complexity phases pause for interactive planning
-- Planning override bumps complexity upward when task signals disagree
-- Retry budget (3 attempts) with escalating context before surfacing failures
-- Existing skills (planning, execution, verification, review) are unchanged
-- Plans auto-approve when no concern signals fire; plans pause for human review when any signal fires
-- `--review-plans` flag forces human review for all plans in a session
-- Phase completion summary shown between every phase
-- `--fast` skips skeleton approval, skips scratchpad, auto-approves plans, and runs minimal verification
-- `--thorough` requires skeleton approval, uses verbose scratchpad, forces plan review, and runs full verification
-- Scratchpad is cleared automatically at every phase transition (PHASE_COMPLETE)
-- Checkpoint commits fire after every passing checkpoint; recovery commits fire on retry budget exhaustion
-- Rigor level persists across session resume — set once during INIT, never changed mid-session
-
-## Rationalizations to Reject
-
-| Rationalization                                                                                     | Reality                                                                                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "This phase is low complexity, so I can skip the APPROVE_PLAN gate entirely"                        | Low complexity only means auto-approval when no concern signals fire. If the planner flagged concerns, produced a complexity override, or the task count exceeds 15, the gate pauses regardless of the spec annotation. |
-| "I can write the planning logic inline instead of dispatching to the harness-planner persona agent" | The Iron Law is explicit: autopilot delegates, never reimplements. Using a general-purpose agent or inlining planning logic bypasses the harness methodology.                                                           |
-| "The retry budget is exhausted but I can try one more approach before stopping"                     | The 3-attempt retry budget exists because each failed attempt degrades context and compounds risk. Exceeding the budget without human input turns a recoverable failure into an unrecoverable one.                      |
-| "I will skip the scratchpad since keeping research in conversation is faster"                       | Scratchpad is gated by rigor level. At standard or thorough, bulky research (>500 words) must go to scratchpad to keep agent conversation focused on decisions.                                                         |
-| "The plan auto-approved, so I can skip recording the decision in the decisions array"               | Every plan approval -- auto or manual -- must be recorded with its signal evaluation. The decisions array is the audit trail that explains why a plan was approved.                                                     |
+- All phases in the spec are executed in order with plan → execute → verify → review per phase
+- Every plan approval is recorded in `decisions[]` (auto or manual)
+- Retry budget (3 attempts) is enforced — exhausted retries surface to user, never silently continue
+- FINAL_REVIEW runs on `startingCommit..HEAD` diff and catches cross-phase coherence issues
+- State is persisted to `autopilot-state.json` after every state transition — re-invocation resumes correctly
+- `harness validate` passes after every phase
 
 ## Examples
 
-### Example: 3-Phase Security Scanner
-
-**User invokes:** `/harness:autopilot docs/changes/security-scanner/proposal.md`
-
-**Or with rigor flag:** `/harness:autopilot docs/changes/security-scanner/proposal.md --fast`
-
-**INIT (with --fast):**
-
-```
-Read spec — found 3 phases:
-  Phase 1: Core Scanner (complexity: low)
-  Phase 2: Rule Engine (complexity: high)
-  Phase 3: CLI Integration (complexity: low)
-Rigor level: fast
-Created .harness/sessions/changes--security-scanner--proposal/autopilot-state.json. Starting Phase 1.
-```
-
-**Phase 1 — APPROVE_PLAN (fast mode):**
-
-```
-Auto-approved Phase 1: Core Scanner (fast mode — signal evaluation skipped)
-```
-
-**Phase 1 — EXECUTE (checkpoint commit):**
-
-```
-[harness-task-executor executes 8 tasks]
-Checkpoint 1: types and interfaces — committed (abc1234)
-Checkpoint 2: core implementation — committed (def5678)
-Checkpoint 3: tests and validation — nothing to commit (skipped)
-```
-
-**INIT:**
-
-```
-Read spec — found 3 phases:
-  Phase 1: Core Scanner (complexity: low)
-  Phase 2: Rule Engine (complexity: high)
-  Phase 3: CLI Integration (complexity: low)
-Created .harness/sessions/changes--security-scanner--proposal/autopilot-state.json. Starting Phase 1.
-```
-
-**Phase 1 — ASSESS:**
-
-```
-Phase 1: Core Scanner — complexity: low. Auto-planning.
-```
-
-**Phase 1 — PLAN:**
-
-```
-[harness-planner agent runs harness-planning]
-Plan generated: docs/plans/2026-03-19-core-scanner-plan.md (8 tasks, ~24 min)
-```
-
-**Phase 1 — APPROVE_PLAN:**
+**Invocation:** `/harness:autopilot docs/changes/security-scanner/proposal.md`
 
-```
-Auto-approved Phase 1: Core Scanner
-  Review mode: auto
-  Complexity: low (no override)
-  Planner concerns: none
-  Tasks: 8 (threshold: 15)
-```
+**INIT:** 3 phases found: Phase 1: Core Scanner (low), Phase 2: Rule Engine (high), Phase 3: CLI Integration (low).
 
-**Phase 1 — EXECUTE → VERIFY → REVIEW:**
+**Phase 1 — ASSESS → PLAN:** harness-planner dispatched. Returns plan: `docs/plans/2026-03-19-core-scanner-plan.md` (8 tasks).
 
-```
-[harness-task-executor agent executes 8 tasks... all pass]
-[harness-verifier agent runs verification... pass]
-[harness-code-reviewer agent runs code review... 0 blocking, 2 notes]
-```
+**Phase 1 — APPROVE_PLAN (auto):** All signals false. "Auto-approved Phase 1: Core Scanner | auto | low | no concerns | 8 tasks."
 
-**Phase 1 — PHASE_COMPLETE:**
+**Phase 1 — EXECUTE:** harness-task-executor dispatched with plan path + session. 8 tasks complete. 2 checkpoint commits.
 
-```
-Phase 1: Core Scanner — COMPLETE
-Tasks: 8/8 | Retries: 0 | Verification: pass | Review: 0 blocking
-Next: Phase 2: Rule Engine (complexity: high). Continue? (yes / stop)
-→ User: "yes"
-```
+**Phase 1 — VERIFY:** harness-verifier dispatched. Pass. **REVIEW:** harness-code-reviewer. 0 blocking, 2 notes.
 
-**Phase 2 — ASSESS:**
+**Phase 1 — PHASE_COMPLETE:** "Phase 1 complete. Next: Phase 2: Rule Engine (high). Continue? → yes"
 
-```
-Phase 2: Rule Engine — complexity: high.
-This phase requires interactive planning. Run /harness:planning with the
-Rule Engine section of the spec, then re-invoke /harness:autopilot to continue.
-```
+**Phase 2 — ASSESS:** High complexity. "Run `/harness:planning` interactively, then re-invoke." [User plans interactively. Re-invokes.]
 
-**[User runs /harness:planning interactively, produces plan]**
+**INIT (resume):** "Resuming from PLAN, phase 2: Rule Engine. Found plan: docs/plans/2026-03-19-rule-engine-plan.md"
 
-**User re-invokes:** `/harness:autopilot`
+**Phase 2 — APPROVE_PLAN (paused):** Complexity: high triggered. "Approve? → yes" **EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE.** 14 tasks, 1 retry.
 
-**INIT (resume):**
+**Phase 3:** auto-plans and executes. **FINAL_REVIEW:** harness-code-reviewer on `startingCommit..HEAD`. 0 blocking, 1 warning. Passed.
 
-```
-Resuming autopilot from state PLAN, phase 2: Rule Engine.
-Found plan: docs/plans/2026-03-19-rule-engine-plan.md
-```
+**DONE:** 3 phases, 30 tasks, 1 retry. "Create PR? → yes"
 
-**Phase 2 — APPROVE_PLAN:**
+**Retry exhaustion (during any phase):**
 
 ```
-Pausing for review -- Phase 2: Rule Engine
-  Review mode: auto
-  Complexity: high (triggered)
-  Planner concerns: none
-  Tasks: 14 (threshold: 15)
-Approve this plan and begin execution? (yes / revise / skip / stop)
-→ User: "yes"
-```
-
-**Phase 2 — EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE**
-
-```
-[Execution with checkpoint pauses as needed]
-Phase 2: Rule Engine — COMPLETE
-Tasks: 14/14 | Retries: 1 | Verification: pass | Review: 0 blocking
-Next: Phase 3: CLI Integration (complexity: low). Continue? (yes / stop)
-→ User: "yes"
-```
-
-**Phase 3 — [auto-plans, executes, completes]**
-
-**FINAL_REVIEW:**
-
-```
-[harness-code-reviewer runs cross-phase review on startingCommit..HEAD]
-Final review: 0 blocking, 1 warning. Passed.
-```
-
-**DONE:**
-
+Task 4 fails → Retry 1/3: obvious fix applied, still fails
+             → Retry 2/3: expanded context (related files + learnings), still fails
+             → Retry 3/3: full context gather (test output + imports + plan), still fails
+Budget exhausted. Recorded in .harness/failures.md.
+Fix manually and continue / revise plan / stop?
 ```
-All phases complete.
-Total: 3 phases, 30 tasks, 1 retry
-Final review: passed (0 blocking, 1 warning)
-Create a PR? (yes / no)
-→ User: "yes"
-```
-
-### Example: Retry Budget Exhaustion
-
-**During Phase 1 — EXECUTE:**
-
-```
-Task 4: wire parser — FAILED
-Error: Type error in parser.ts:42 — missing generic parameter
-
-Retry 1/3: Added generic parameter to parseRule<T>. Re-running...
-Task 4: wire parser — FAILED
-Error: Test assertion failure — expected 3 rules, got 0
-
-Retry 2/3: Expanded context — read rule-loader.ts, checked learnings. Fixed import path. Re-running...
-Task 4: wire parser — FAILED
-Error: Test timeout after 5000ms
-
-Retry 3/3: Full context — re-read plan instructions, checked for ambiguity. Found test was missing async/await. Re-running...
-Task 4: wire parser — PASSED
-
-Continuing execution...
-```
-
-**If all 3 retries fail:**
-
-```
-Task 4: wire parser — FAILED (budget exhausted)
-
-Attempt 1: Added generic parameter → Type error persists
-Attempt 2: Fixed import path → Tests still timeout
-Attempt 3: Added async/await → New error: connection refused
-
-Recorded in .harness/failures.md.
-How should we proceed? (fix manually and continue / revise plan / stop)
-```
-
-## Gates
-
-- **No reimplementing delegated skills.** Autopilot orchestrates. If you are writing planning logic, execution logic, verification logic, or review logic, STOP. Delegate to the appropriate persona agent via `subagent_type`.
-- **No executing without plan approval.** Every plan passes through the APPROVE_PLAN gate. When no concern signals fire, the plan is auto-approved with a structured report. When any signal fires, the plan pauses for human review. The `--review-plans` flag forces all plans to pause. No plan reaches EXECUTE without passing this gate.
-- **No skipping VERIFY or REVIEW.** Every phase goes through verification and review. The human can override findings, but the steps cannot be skipped.
-- **No infinite retries.** The retry budget is 3 attempts. If exhausted, STOP and surface to the human. Do not extend the budget without explicit human instruction.
-- **No modifying session state files manually.** The session state files are managed by the skill. If the state appears corrupted, start fresh rather than patching it.
-
-## Escalation
-
-- **When the spec has no Implementation Order section:** Cannot identify phases. Ask the user to add phase annotations to the spec or provide a roadmap file.
-- **When a delegated skill fails to produce expected output:** Check that `{sessionDir}/handoff.json` was written correctly. If the agent failed, report the failure and ask the user whether to retry the entire phase step or stop.
-- **When the user wants to reorder phases mid-run:** Update the phases array in the session-scoped `autopilot-state.json` (mark skipped phases, adjust currentPhase). Do not re-run completed phases.
-- **When context limits are approaching:** Persist state immediately and inform the user: "Context limit approaching. State saved. Re-invoke /harness:autopilot to continue from this point."
-- **When multiple phases fail in sequence:** After 2 consecutive phase failures (retry budget exhausted in both), suggest the user review the spec for systemic issues rather than continuing.