@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -31,7 +31,21 @@ Autopilot orchestrates these persona agents — it never reimplements their logi
 - **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>`.
 
-**Human always approves plans.** No plan executes without explicit human sign-off, regardless of complexity level. The difference is whether autopilot generates the plan automatically or asks the human to drive planning interactively.
+**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.
+
+## 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.                                                                                      |
+
+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.
 
 ## Process
 
@@ -42,7 +56,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
                                                                          ↓
                                                                    [next phase?]
                                                                     ↓         ↓
-                                                                 ASSESS      DONE
+                                                                 ASSESS   FINAL_REVIEW → DONE
 ```
 
 ---
@@ -61,7 +75,9 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - 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):**
@@ -70,12 +86,16 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - 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": 2,
+       "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": [
@@ -91,11 +111,24 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
          "maxAttempts": 3,
          "currentTask": null
        },
-       "history": []
+       "history": [],
+       "decisions": [],
+       "finalReview": {
+         "status": "pending",
+         "findings": [],
+         "retryCount": 0
+       }
      }
      ```
 
-5. **Load context via gather_context.** Use the `gather_context` MCP tool to load all working context efficiently:
+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({
@@ -109,19 +142,19 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
    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.
 
-6. **Load session summary for cold start.** If resuming (existing `autopilot-state.json` found):
+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.
 
-7. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
+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
 
    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.
 
-8. **Transition to ASSESS.**
+9. **Transition to ASSESS.**
 
 ---
 
@@ -163,10 +196,23 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
        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.
 
+       ## Scratchpad (if rigorLevel is not "fast")
+
+       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.
+
        Follow the harness-planning skill process exactly. Write the plan to
        docs/plans/{date}-{phase-name}-plan.md. Write {sessionDir}/handoff.json when done.
    ```
@@ -192,27 +238,119 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ---
 
-### APPROVE_PLAN — Human Review Gate
-
-**This state always pauses for human input.**
+### APPROVE_PLAN — Conditional Review Gate
 
-1. **Present the plan summary:**
+1. **Gather plan metadata:**
    - Phase name and number
-   - Task count
+   - Task count (from the plan file)
    - Checkpoint count
-   - Estimated time (task count × 3 minutes)
+   - Estimated time (task count x 3 minutes)
    - Effective complexity (original + any override)
-   - Any concerns from the planning handoff
+   - 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)".
 
-2. **Ask:** "Approve this plan and begin execution? (yes / revise / skip phase / stop)"
+   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.
+   - **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.
 
-3. **Record the decision** in state: `decisions` array.
+   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
+     }
+   }
+   ```
 
-4. **Update state** with `currentState: "EXECUTE"` and save.
+   Use the actual decision value: `approved_plan`, `revised_plan`, `skipped_phase`, or `stopped`.
+
+7. **Update state** with `currentState: "EXECUTE"` (or appropriate state for skip/stop) and save.
 
 ---
 
@@ -231,16 +369,35 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
        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)
+
+       Reference the scratchpad file path instead of inlining the content.
+
        Follow the harness-execution skill process exactly.
        Update {sessionDir}/state.json after each task.
        Write {sessionDir}/handoff.json when done or when blocked.
    ```
 
 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.
@@ -257,6 +414,16 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      - **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)"
@@ -268,7 +435,11 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### VERIFY — Post-Execution Validation
 
-1. **Dispatch verification agent using the Agent tool:**
+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:
@@ -287,14 +458,14 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
        Report pass/fail with findings.
    ```
 
-2. **When the agent returns:**
+3. **When the agent returns:**
    - **All checks pass:** Transition to REVIEW.
-   - **Failures found:** Surface findings to the user. Ask: "Fix these issues before review? (yes / skip verification / stop)"
-     - **yes** — Re-enter EXECUTE with targeted fixes (retry budget resets for verification fixes).
-     - **skip** — Proceed to REVIEW with verification warnings noted.
+   - **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.
 
-3. **Update state** with `currentState: "REVIEW"` and save.
+4. **Update state** with `currentState: "REVIEW"` and save.
 
 ---
 
@@ -320,9 +491,10 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    ```
 
 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? (yes / override / stop)"
-     - **yes** — Re-enter EXECUTE with review fixes.
+   - **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.
 
@@ -357,9 +529,11 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 3. **Mark phase as `complete`** in state.
 
-4. **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. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
+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.
+
+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. Skip silently if no roadmap exists. Do not use `force_sync: true` — the human-always-wins rule applies.
 
-5. **Write session summary.** Update the session summary to reflect the completed phase:
+6. **Write session summary.** Update the session summary to reflect the completed phase:
 
    ```json
    writeSessionSummary(projectPath, sessionSlug, {
@@ -375,11 +549,80 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    })
    ```
 
-6. **Check for next phase:**
+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 DONE.
+   - If no more phases: Transition to 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:**
+
+   ```
+   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).
+   ```
+
+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}
+
+           Session directory: {sessionDir}
+           Session slug: {sessionSlug}
+
+           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.
+
+6. **Update state** and save after each step.
 
 ---
 
@@ -390,7 +633,8 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - Total tasks across all phases
    - Total retries used
    - Total time (first phase start to last phase completion)
-   - Any overridden review findings
+   - 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)"
@@ -407,7 +651,11 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      "pending": [],
      "concerns": [],
      "decisions": ["<all decisions from all phases>"],
-     "contextKeywords": ["<merged from spec>"]
+     "contextKeywords": ["<merged from spec>"],
+     "finalReview": {
+       "status": "<passed | overridden>",
+       "findingsCount": "<number of findings from final review>"
+     }
    }
    ```
 
@@ -419,9 +667,13 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - [skill:harness-autopilot] [outcome:observation] {any notable patterns from the run}
    ```
 
-5. **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. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
+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."
+
+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. Skip silently if no roadmap exists or if the feature is not found. Do not use `force_sync: true`.
 
-6. **Write final session summary.** Update the session summary to reflect completion:
+8. **Write final session summary.** Update the session summary to reflect completion:
 
    ```json
    writeSessionSummary(projectPath, sessionSlug, {
@@ -435,7 +687,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    })
    ```
 
-7. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
+9. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
 
 ## Harness Integration
 
@@ -444,9 +696,12 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 - **`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.
+- **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.
 
 ## Success Criteria
 
@@ -456,8 +711,14 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 - 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
-- Human approves every plan before execution begins
+- 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
 
 ## Examples
 
@@ -465,6 +726,34 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 **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:**
 
 ```
@@ -491,10 +780,11 @@ Plan generated: docs/plans/2026-03-19-core-scanner-plan.md (8 tasks, ~24 min)
 **Phase 1 — APPROVE_PLAN:**
 
 ```
-Phase 1: Core Scanner
-Tasks: 8 | Checkpoints: 1 | Est. time: 24 min | Complexity: low
-Approve this plan and begin execution? (yes / revise / skip / stop)
-→ User: "yes"
+Auto-approved Phase 1: Core Scanner
+  Review mode: auto
+  Complexity: low (no override)
+  Planner concerns: none
+  Tasks: 8 (threshold: 15)
 ```
 
 **Phase 1 — EXECUTE → VERIFY → REVIEW:**
@@ -533,10 +823,22 @@ Resuming autopilot from state PLAN, phase 2: Rule Engine.
 Found plan: docs/plans/2026-03-19-rule-engine-plan.md
 ```
 
-**Phase 2 — APPROVE_PLAN → EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE**
+**Phase 2 — APPROVE_PLAN:**
 
 ```
-[Same flow as Phase 1, with checkpoint pauses as needed]
+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)
@@ -545,11 +847,19 @@ Next: Phase 3: CLI Integration (complexity: low). Continue? (yes / stop)
 
 **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:**
 
 ```
 All phases complete.
 Total: 3 phases, 30 tasks, 1 retry
+Final review: passed (0 blocking, 1 warning)
 Create a PR? (yes / no)
 → User: "yes"
 ```
@@ -592,7 +902,7 @@ 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 must be explicitly approved by the human before execution begins. No exceptions, regardless of complexity level.
+- **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.