@harness-engineering/cli 1.13.1 → 1.15.0

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

@@ -31,7 +31,7 @@ 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.
 
 ## Process
 
@@ -42,7 +42,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
                                                                          ↓
                                                                    [next phase?]
                                                                     ↓         ↓
-                                                                 ASSESS      DONE
+                                                                 ASSESS   FINAL_REVIEW → DONE
 ```
 
 ---
@@ -61,7 +61,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.
    - 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 +72,15 @@ 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": 4,
        "sessionDir": ".harness/sessions/<slug>",
        "specPath": "<path to spec>",
+       "startingCommit": "<git rev-parse HEAD output>",
+       "reviewPlans": false,
        "currentState": "ASSESS",
        "currentPhase": 0,
        "phases": [
@@ -91,11 +96,19 @@ 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 `--review-plans`. If present, set `state.reviewPlans: true` in the state file. This flag persists for the entire session — resuming a session preserves the setting from when it was started (the flag is only read on fresh start, not on resume).
+
+6. **Load context via gather_context.** Use the `gather_context` MCP tool to load all working context efficiently:
 
    ```json
    gather_context({
@@ -109,19 +122,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.**
 
 ---
 
@@ -192,27 +205,114 @@ 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. **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                                                                                                                                                 |
+
+3. **Build the signal evaluation result** for reporting and recording:
+
+   ```json
+   {
+     "reviewPlans": false,
+     "highComplexity": "low",
+     "complexityOverride": null,
+     "plannerConcerns": [],
+     "taskCount": 8,
+     "taskThreshold": 15
+   }
+   ```
+
+4. **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.
+
+5. **If pausing for review (one or more signals fired):**
 
-2. **Ask:** "Approve this plan and begin execution? (yes / revise / skip phase / stop)"
+   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.
+   - **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
+     }
+   }
+   ```
+
+   Use the actual decision value: `approved_plan`, `revised_plan`, `skipped_phase`, or `stopped`.
 
-4. **Update state** with `currentState: "EXECUTE"` and save.
+6. **Update state** with `currentState: "EXECUTE"` (or appropriate state for skip/stop) and save.
 
 ---
 
@@ -289,9 +389,9 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 2. **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.
@@ -320,9 +420,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.
 
@@ -379,7 +480,76 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - 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 +560,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 +578,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 +594,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 +614,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,7 +623,7 @@ 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`.
 
@@ -456,7 +635,8 @@ 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
 
 ## Examples
@@ -491,10 +671,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 +714,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 +738,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 +793,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.

package/dist/agents/skills/claude-code/harness-autopilot/skill.yaml

@@ -23,6 +23,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: review-plans
+      description: Force human review of all plans (overrides auto-approve)
+      required: false
 mcp:
   tool: run_skill
   input:
@@ -37,6 +40,9 @@ phases:
   - name: loop
     description: Execute state machine — assess, plan, execute, verify, review per phase
     required: true
+  - name: final_review
+    description: Project-wide code review of cumulative changes before PR offer
+    required: true
   - name: complete
     description: Final summary and PR offering
     required: true

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

@@ -259,6 +259,45 @@ For each proposed approach, evaluate from each perspective:
 
 Converge on a recommendation that addresses all concerns before presenting the design.
 
+## Session State
+
+This skill reads and writes to the following session sections via `manage_state`:
+
+| Section       | Read | Write | Purpose                                                           |
+| ------------- | ---- | ----- | ----------------------------------------------------------------- |
+| terminology   | yes  | yes   | Captures domain terms discovered during brainstorming             |
+| decisions     | no   | yes   | Records design decisions made during exploration                  |
+| constraints   | yes  | no    | Reads constraints to scope brainstorming                          |
+| risks         | no   | yes   | Captures risks identified during brainstorming                    |
+| openQuestions | yes  | yes   | Adds new questions, resolves answered ones                        |
+| evidence      | no   | yes   | Cites sources for design recommendations and prior art references |
+
+**When to write:** After each phase transition (EXPLORE -> EVALUATE -> PRIORITIZE -> VALIDATE), append relevant entries to the appropriate sections. This ensures downstream skills (planning, execution) inherit accumulated context without re-discovery.
+
+**When to read:** At the start of Phase 1 (EXPLORE), read `terminology` and `constraints` from the session to inherit context from prior skills or previous brainstorming sessions on the same feature.
+
+## Evidence Requirements
+
+When this skill makes claims about existing code behavior, architecture patterns, or technical tradeoffs, it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/services/auth.ts:42` -- "existing JWT middleware handles token refresh")
+2. **Prior art reference:** `file` format with description (e.g., `src/utils/email.ts` -- "email utility already exists, can be reused for notifications")
+3. **Documentation reference:** `docs/path` format (e.g., `docs/changes/user-auth/proposal.md` -- "prior spec established OAuth2 as the auth standard")
+4. **Session evidence:** Write to the `evidence` session section:
+   ```json
+   manage_state({
+     action: "append_entry",
+     session: "<current-session>",
+     section: "evidence",
+     authorSkill: "harness-brainstorming",
+     content: "src/services/auth.ts:42 -- existing JWT middleware supports refresh tokens"
+   })
+   ```
+
+**When to cite:** During Phase 1 (EXPLORE) when referencing existing code or patterns. During Phase 3 (PRIORITIZE) when justifying tradeoffs with concrete code references. During Phase 4 (VALIDATE) when spec references existing implementation details.
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with `[UNVERIFIED]`. Example: `[UNVERIFIED] The current auth middleware does not support refresh tokens`. Uncited claims are flagged during review (Wave 2.2).
+
 ## Harness Integration
 
 - **`harness validate`** — Run after writing the spec to `docs/`. Verifies project health and that the new spec file is properly placed.

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

@@ -138,6 +138,24 @@ Run mechanical checks to establish an exclusion boundary. Any issue caught mecha
 
 **Output:** A set of mechanical findings (file, line, tool, message). This set becomes the exclusion list for Phase 5.
 
+#### Evidence Gate (session-aware)
+
+When a `sessionSlug` is available (e.g., via autopilot dispatch or `--session` flag), the pipeline loads evidence entries from the session state and cross-references them with review findings:
+
+1. Load evidence entries: `readSessionSection(projectRoot, sessionSlug, 'evidence')`
+2. For each finding, check if any active evidence entry references the same file:line location
+3. Findings without matching evidence are tagged with `[UNVERIFIED]` prefix in their title
+4. An evidence coverage report is appended to the review output:
+   ```
+   Evidence Coverage:
+     Evidence entries: 12
+     Findings with evidence: 8/10
+     Uncited findings: 2 (flagged as [UNVERIFIED])
+     Coverage: 80%
+   ```
+
+When no session is available, evidence checking is skipped silently. This is not an error -- evidence checking enhances reviews but does not gate them.
+
 **Exit:** If any mechanical check fails (harness validate, typecheck, or tests), report the mechanical failures in Strengths/Issues/Assessment format and stop the pipeline. The code has fundamental issues that must be fixed before AI review adds value. Lint warnings and security scan findings do not stop the pipeline — they are recorded for exclusion only.
 
 ---
@@ -628,6 +646,32 @@ _This section is not part of the pipeline. It documents the process for respondi
 
 ---
 
+## Evidence Requirements
+
+When this skill produces review findings, every finding MUST include evidence citations. The `ReviewFinding.evidence` array field already exists in the finding schema -- this section defines the citation standard for populating it.
+
+Every review finding MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/api/routes/users.ts:12-15` -- "direct import from db/queries.ts bypasses service layer")
+2. **Diff evidence:** Before/after code from the PR diff with file path and line numbers
+3. **Dependency chain:** Import path showing the violation (e.g., `routes/users.ts:3 imports db/queries.ts` -- "violates routes -> services -> db layer direction")
+4. **Test evidence:** Include test command and output when findings relate to missing or failing tests
+5. **Convention reference:** Cite the specific convention file and rule (e.g., `AGENTS.md:45` -- "convention requires services layer between routes and db")
+6. **Session evidence:** Write significant findings to the `evidence` session section:
+   ```json
+   manage_state({
+     action: "append_entry",
+     session: "<current-session>",
+     section: "evidence",
+     authorSkill: "harness-code-review",
+     content: "src/api/routes/users.ts:12-15 -- layer violation: direct import from db/queries.ts"
+   })
+   ```
+
+**When to cite:** In Phase 4 (FAN-OUT), each subagent populates the `evidence` array in every `ReviewFinding`. In Phase 5 (VALIDATE), evidence is used to verify reachability claims. In Phase 7 (OUTPUT), every issue in the review includes its file:line location and rationale backed by evidence.
+
+**Uncited claims:** Review findings without evidence in the `evidence` array are discarded during Phase 5 (VALIDATE). Observations that cannot be tied to specific file:line references MUST be prefixed with `[UNVERIFIED]` and downgraded to `severity: 'suggestion'`.
+
 ## Harness Integration
 
 - **`assess_project`** — Used in Phase 2 (MECHANICAL) to run `validate`, `deps`, and `docs` checks in parallel. Must pass for the pipeline to continue to AI review. Failures are Critical issues that stop the pipeline.

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

@@ -345,6 +345,50 @@ These are non-negotiable. When any condition is met, stop immediately.
 
 - **Three consecutive failures on the same task.** After 3 attempts, the task design is likely wrong. Stop. Report: "Task N has failed 3 times. Root cause: [analysis]. The plan may need revision."
 
+## Session State
+
+This skill reads and writes to the following session sections via `manage_state`:
+
+| Section       | Read | Write | Purpose                                                                               |
+| ------------- | ---- | ----- | ------------------------------------------------------------------------------------- |
+| terminology   | yes  | yes   | Reads domain terms for consistent naming; adds terms discovered during implementation |
+| decisions     | yes  | yes   | Reads planning decisions for context; records implementation decisions                |
+| constraints   | yes  | yes   | Reads constraints to respect boundaries; adds constraints discovered during coding    |
+| risks         | yes  | yes   | Reads risks for awareness; updates risk status as mitigated or realized               |
+| openQuestions | yes  | yes   | Reads questions for context; resolves questions answered by implementation            |
+| evidence      | yes  | yes   | Reads prior evidence; writes file:line citations, test outputs, and diff references   |
+
+**When to write:** After each task completion, append relevant entries. Evidence entries should be written for every significant technical assertion (test result, file reference, performance measurement). Mark openQuestions as resolved when implementation answers them.
+
+**When to read:** During Phase 1 (PREPARE), read all sections via `gather_context` with `include: ["sessions"]` to inherit full accumulated context from brainstorming and planning.
+
+## Evidence Requirements
+
+When this skill makes claims about task completion, test results, or code behavior, it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/services/notification-service.ts:42` -- "create method implemented with validation")
+2. **Test output:** Include the actual test command and its output:
+   ```
+   $ npx vitest run src/services/notification-service.test.ts
+   PASS  src/services/notification-service.test.ts (8 tests)
+   ```
+3. **Diff evidence:** Before/after with file path for modifications to existing files
+4. **Harness output:** Include `harness validate` output as evidence of project health
+5. **Session evidence:** Write to the `evidence` session section after each task:
+   ```json
+   manage_state({
+     action: "append_entry",
+     session: "<current-session>",
+     section: "evidence",
+     authorSkill: "harness-execution",
+     content: "src/services/notification-service.ts:42 -- create method returns Notification with all required fields"
+   })
+   ```
+
+**When to cite:** After every task completion in Phase 2 (EXECUTE). Every commit message claim ("added X", "fixed Y") must be backed by test output or file reference. During Phase 4 (PERSIST) when writing learnings that reference specific code behavior.
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with `[UNVERIFIED]`. Example: `[UNVERIFIED] The notification service handles duplicate entries`. Uncited claims are flagged during review (Wave 2.2).
+
 ## Harness Integration
 
 - **`harness validate`** — Run after every task completion. Mandatory. No task is complete without a passing validation.