@harness-engineering/cli 1.8.2 → 1.10.0

package/dist/agents/skills/claude-code/cleanup-dead-code/SKILL.md

@@ -74,9 +74,9 @@ For each item categorized as safe:
 
 **New fix types:**
 
-- **Dead exports (non-public):** Use `apply_fixes` with `fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
-- **Commented-out code:** Use `apply_fixes` with `fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
-- **Orphaned dependencies:** Use `apply_fixes` with `fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
+- **Dead exports (non-public):** Use `detect_entropy` with `autoFix: true, fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
+- **Commented-out code:** Use `detect_entropy` with `autoFix: true, fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
+- **Orphaned dependencies:** Use `detect_entropy` with `autoFix: true, fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
 
 ### Phase 3.5: Convergence Loop (Standalone)
 

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

@@ -95,7 +95,18 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      }
      ```
 
-5. **Load context.** Read `.harness/learnings.md` and `.harness/failures.md` (global, at `.harness/` root) if they exist. Note any relevant learnings or known dead ends for the current phase.
+5. **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",
+     include: ["state", "learnings", "handoff", "validation"]
+   })
+   ```
+
+   This loads learnings (including failure entries tagged `[outcome:failure]`), handoff context, state, and validation results in a single call. Note any relevant learnings or known dead ends for the current phase from the returned `learnings` array.
 
 6. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
    - Current project priorities (which features are `in-progress`)
@@ -328,7 +339,9 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 3. **Mark phase as `complete`** in state.
 
-4. **Check for next phase:**
+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.
+
+5. **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.
@@ -372,16 +385,20 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - [skill:harness-autopilot] [outcome:observation] {any notable patterns from the run}
    ```
 
-5. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
+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`.
+
+6. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
 
 ## Harness Integration
 
 - **`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.
 - **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`.
 
 ## Success Criteria
 

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

@@ -45,8 +45,35 @@ If you find yourself writing production code, tests, or scaffolding before the h
      path: "<project-root>",
      type: "question",
      question: {
-       text: "For auth, should we use:",
-       options: ["A) existing JWT middleware", "B) OAuth2 via provider X", "C) external service"]
+       text: "For auth, which approach should we use?",
+       options: [
+         {
+           label: "A) Existing JWT middleware",
+           pros: ["Already in codebase", "Team has experience"],
+           cons: ["No refresh token support", "Session-only"],
+           risk: "low",
+           effort: "low"
+         },
+         {
+           label: "B) OAuth2 via provider X",
+           pros: ["Industry standard", "Refresh tokens built-in"],
+           cons: ["New dependency", "Learning curve"],
+           risk: "medium",
+           effort: "medium"
+         },
+         {
+           label: "C) External auth service",
+           pros: ["Zero maintenance", "Enterprise features included"],
+           cons: ["Vendor lock-in", "Monthly cost", "Latency"],
+           risk: "medium",
+           effort: "low"
+         }
+       ],
+       recommendation: {
+         optionIndex: 0,
+         reason: "Sufficient for current requirements. OAuth2 adds complexity we don't need yet.",
+         confidence: "high"
+       }
      }
    })
    ```
@@ -120,14 +147,24 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
      type: "confirmation",
      confirmation: {
        text: "Approve spec at <file-path>?",
-       context: "<one-paragraph summary of the design>"
+       context: "<one-paragraph summary of the design>",
+       impact: "Spec approval unlocks implementation planning. No code changes yet.",
+       risk: "low"
      }
    })
    ```
 
    The human must explicitly approve before this skill is complete.
 
-6. **Write handoff and suggest transition.** After the human approves the spec:
+6. **Add feature to roadmap.** If `docs/roadmap.md` exists:
+   - Derive the feature name from the spec title (the H1 heading of the proposal).
+   - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
+   - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
+   - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
+   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `addFeature()` from core.
+   - If no roadmap exists, skip this step silently.
+
+7. **Write handoff and suggest transition.** After the human approves the spec:
 
    Write `.harness/handoff.json`:
 
@@ -153,7 +190,19 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
        "reason": "Spec approved and written to docs/",
        "artifacts": ["<spec file path>"],
        "requiresConfirmation": true,
-       "summary": "<Spec title> -- <key design choices>. <N> success criteria, <N> implementation phases."
+       "summary": "<Spec title> -- <key design choices>. <N> success criteria, <N> implementation phases.",
+       "qualityGate": {
+         "checks": [
+           {
+             "name": "spec-written",
+             "passed": true,
+             "detail": "Written to docs/changes/<feature>/proposal.md"
+           },
+           { "name": "harness-validate", "passed": true },
+           { "name": "human-approved", "passed": true }
+         ],
+         "allPassed": true
+       }
      }
    }
    ```
@@ -216,6 +265,7 @@ Converge on a recommendation that addresses all concerns before presenting the d
 - **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
 - **Spec location** — Specs go to `docs/changes/<feature>/proposal.md`. Follow existing naming patterns.
 - **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
+- **Roadmap sync** — After spec approval, call `manage_roadmap` with action `add` to register the new feature as `planned` in `docs/roadmap.md`. Skip silently if no roadmap exists. Duplicates are silently ignored.
 - **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-planning. Uses confirmed transition (waits for user approval).
 
 #### Requirement Phrasing

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

@@ -122,12 +122,15 @@ Run mechanical checks to establish an exclusion boundary. Any issue caught mecha
 
 **Checks:**
 
-1. **Harness validation:**
-   ```bash
-   harness validate
-   harness check-deps
-   harness check-docs
+1. **Harness validation:** Use `assess_project` to run all harness health checks in parallel:
+   ```json
+   assess_project({
+     path: "<project-root>",
+     checks: ["validate", "deps", "docs"],
+     mode: "detailed"
+   })
    ```
+   This runs `harness validate`, `harness check-deps`, and `harness check-docs` in parallel and returns a unified report. Any check failure is reported in the `checks` array with `passed: false`.
 2. **Security scan:** Run `run_security_scan` MCP tool on changed files. Record findings with rule ID, file, line, and remediation.
 3. **Type checking:** Run the project's type checker (e.g., `tsc --noEmit`). Record any type errors.
 4. **Linting:** Run the project's linter (e.g., `eslint`). Record any lint violations.
@@ -202,13 +205,21 @@ Gather context in this order until the ratio is met:
 
 #### Graph-Enhanced Context (when available)
 
-When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+When a knowledge graph exists at `.harness/graph/`, use `gather_context` for efficient context assembly:
 
-- `query_graph` — traverse dependency chain from changed files to find all imports and transitive dependencies
-- `get_impact` — find all affected tests, docs, and downstream code
-- `find_context_for` — assemble review context within token budget, ranked by relevance
+```json
+gather_context({
+  path: "<project-root>",
+  intent: "Code review of <change description>",
+  skill: "harness-code-review",
+  tokenBudget: 8000,
+  include: ["graph", "learnings", "validation"]
+})
+```
+
+This replaces manual `query_graph` + `get_impact` + `find_context_for` calls with a single composite call that assembles review context in parallel, ranked by relevance. Falls back gracefully when no graph is available (`meta.graphAvailable: false`).
 
-Graph queries replace manual grep/find commands and discover transitive dependencies that file search misses. Fall back to file-based commands if no graph is available.
+For domain-specific scoping (compliance, bug detection, security, architecture), supplement `gather_context` output with targeted `query_graph` calls as needed.
 
 #### Context Assembly Commands
 
@@ -493,7 +504,9 @@ emit_interaction({
   type: "confirmation",
   confirmation: {
     text: "Review complete: <Assessment>. Accept review?",
-    context: "<N critical, N important, N suggestion findings>"
+    context: "<N critical, N important, N suggestion findings>",
+    impact: "Accepting the review finalizes findings. If 'approve', ready for merge. If 'request-changes', fixes are needed.",
+    risk: "<low if approve, high if critical findings>"
   }
 })
 ```
@@ -528,7 +541,16 @@ Call `emit_interaction`:
     "reason": "Review approved with no blocking issues",
     "artifacts": ["<reviewed files>"],
     "requiresConfirmation": true,
-    "summary": "Review approved. <N> suggestions noted. Ready to create PR or merge."
+    "summary": "Review approved. <N> suggestions noted. Ready to create PR or merge.",
+    "qualityGate": {
+      "checks": [
+        { "name": "mechanical-checks", "passed": true },
+        { "name": "no-critical-findings", "passed": true },
+        { "name": "no-important-findings", "passed": true },
+        { "name": "harness-validate", "passed": true }
+      ],
+      "allPassed": true
+    }
   }
 }
 ```
@@ -591,9 +613,8 @@ _This section is not part of the pipeline. It documents the process for respondi
 
 ## Harness Integration
 
-- **`harness validate`** — Run in Phase 2 (MECHANICAL). Must pass for the pipeline to continue to AI review.
-- **`harness check-deps`** — Run in Phase 2 (MECHANICAL). Failures are Critical issues that stop the pipeline.
-- **`harness check-docs`** — Run in Phase 2 (MECHANICAL). Documentation drift findings are recorded for the exclusion set.
+- **`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.
+- **`gather_context`** — Used in Phase 3 (CONTEXT) for efficient parallel context assembly. Replaces separate graph query calls.
 - **`harness cleanup`** — Optional check during Phase 2 for entropy accumulation in changed files.
 - **Graph queries** — Used in Phase 3 (CONTEXT) for dependency-scoped context and in Phase 5 (VALIDATE) for reachability verification. Graceful fallback when no graph exists.
 - **`emit_interaction`** -- Call after review approval to suggest transitioning to merge/PR creation. Only emitted on APPROVE assessment. Uses confirmed transition (waits for user approval).

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

@@ -205,7 +205,7 @@ After removing the `legacy-auth` module:
 - **`harness cleanup --type dead-code --json`** -- Dead code detection input
 - **`harness check-deps --json`** -- Architecture violation detection input
 - **`harness skill run harness-hotspot-detector`** -- Hotspot context for safety classification
-- **`apply_fixes` MCP tool** -- Applies safe fixes via the MCP server
+- **`detect_entropy` MCP tool with `autoFix: true`** -- Detects entropy and applies safe fixes via the MCP server
 - **`harness validate`** -- Final validation after all fixes
 - **`harness check-deps`** -- Final architecture check after all fixes
 

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

@@ -26,20 +26,27 @@ Deviating from the plan mid-execution introduces untested assumptions, breaks ta
 
 1. **Load the plan.** Read the plan document from `docs/plans/`. Identify the total task count and any checkpoints.
 
-2. **Load state.** Read `.harness/state.json` to determine current position. If the file does not exist, this is a fresh start — position is Task 1.
+2. **Gather context in one call.** Use the `gather_context` MCP tool to load all working context at once:
 
-3. **Load learnings.** Read `.harness/learnings.md` for context from previous sessions. These are hard-won insights — do not ignore them.
+   ```json
+   gather_context({
+     path: "<project-root>",
+     intent: "Execute plan tasks starting from current position",
+     skill: "harness-execution",
+     include: ["state", "learnings", "handoff", "validation"]
+   })
+   ```
 
-4. **Load failures.** Read `.harness/failures.md` for known dead ends. If any entries match approaches in the current plan, surface warnings before proceeding.
+   This returns `state` (current position — if null, this is a fresh start at Task 1), `learnings` (hard-won insights from previous sessions — do not ignore them), `handoff` (structured context from the previous skill), and `validation` (current project health). If any constituent fails, its field is null and the error is reported in `meta.errors`.
 
-5. **Load handoff.** Read `.harness/handoff.json` if it exists. Contains structured context from the previous skill (e.g., harness-planning passing context to harness-execution). Use this to prime session state.
+3. **Check for known dead ends.** Review `learnings` entries tagged `[outcome:failure]`. If any match approaches in the current plan, surface warnings before proceeding.
 
-6. **Verify prerequisites.** For the current task:
+4. **Verify prerequisites.** For the current task:
    - Are dependency tasks marked complete in state?
    - Do the files referenced in the task exist as expected?
    - Does the test suite pass? Run `harness validate` to confirm a clean baseline.
 
-7. **If prerequisites fail,** do not proceed. Report what is missing and which task is blocked.
+5. **If prerequisites fail,** do not proceed. Report what is missing and which task is blocked.
 
 ### Graph-Enhanced Context (when available)
 
@@ -75,7 +82,17 @@ For each task, starting from the current position:
 
 4. **Commit atomically.** Each task produces exactly one commit. Use the commit message specified in the plan. If no message is specified, write a descriptive message in the project's convention.
 
-5. **Run mechanical gate.** After each task commit, run the full gate check: test suite, linter, type checker, build, and `harness validate`. This is binary pass/fail.
+5. **Run mechanical gate.** After each task commit, run the full gate check. Use `assess_project` to run harness checks (including lint) in parallel, then run the test suite:
+
+   ```json
+   assess_project({
+     path: "<project-root>",
+     checks: ["validate", "deps", "lint"],
+     mode: "summary"
+   })
+   ```
+
+   Then run the project's test suite (`npx turbo run test` or equivalent). This is binary pass/fail.
    - **All pass →** proceed to the next task.
    - **Any fail →** retry with error context (max 2 attempts).
    - **Still failing after retries →** record the failure in `.harness/failures.md`, escalate, and stop.
@@ -109,7 +126,9 @@ Plans contain three types of checkpoints. Each requires pausing execution.
      type: "confirmation",
      confirmation: {
        text: "Task N complete. Output: <summary>. Continue to Task N+1?",
-       context: "<test output or file diff summary>"
+       context: "<test output or file diff summary>",
+       impact: "Continuing proceeds to the next task. Declining pauses execution for review.",
+       risk: "low"
      }
    })
    ```
@@ -125,7 +144,27 @@ Plans contain three types of checkpoints. Each requires pausing execution.
      type: "question",
      question: {
        text: "Task N requires a decision: <description>",
-       options: ["<option A>", "<option B>"]
+       options: [
+         {
+           label: "<option A>",
+           pros: ["<pro 1>", "<pro 2>"],
+           cons: ["<con 1>"],
+           risk: "low",
+           effort: "low"
+         },
+         {
+           label: "<option B>",
+           pros: ["<pro 1>"],
+           cons: ["<con 1>", "<con 2>"],
+           risk: "medium",
+           effort: "medium"
+         }
+       ],
+       recommendation: {
+         optionIndex: 0,
+         reason: "<why this option is recommended>",
+         confidence: "medium"
+       }
      }
    })
    ```
@@ -162,7 +201,15 @@ emit_interaction({
     completedPhase: "execution",
     suggestedNext: "verification",
     reason: "All plan tasks executed and verified",
-    artifacts: ["<list of created/modified files>"]
+    artifacts: ["<list of created/modified files>"],
+    qualityGate: {
+      checks: [
+        { name: "all-tasks-complete", passed: true, detail: "<N>/<N> tasks" },
+        { name: "harness-validate", passed: true },
+        { name: "tests-pass", passed: true }
+      ],
+      allPassed: true
+    }
   }
 })
 ```
@@ -219,7 +266,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
    }
    ```
 
-5. **Sync roadmap (if present).** If `docs/roadmap.md` exists, trigger a roadmap sync to update linked feature statuses based on the just-completed execution state. Use the `manage_roadmap` MCP tool with `sync` action if available, or invoke `/harness:roadmap --sync`. This keeps the roadmap current as plans are executed. If no roadmap exists, skip this step silently.
+5. **Sync roadmap (mandatory when present).** If `docs/roadmap.md` exists, call `manage_roadmap` with action `sync` and `apply: true` to update linked feature statuses from the just-completed execution state. Do not use `force_sync: true` — the human-always-wins rule applies. If `manage_roadmap` is unavailable, fall back to direct file manipulation using `syncRoadmap()` from core. If no roadmap exists, skip silently.
 
 6. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record.
 
@@ -236,7 +283,16 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
        "reason": "All tasks complete",
        "artifacts": ["<list of created/modified files>"],
        "requiresConfirmation": false,
-       "summary": "Completed <N> tasks. <N> files created, <N> modified. All quick gates passed."
+       "summary": "Completed <N> tasks. <N> files created, <N> modified. All quick gates passed.",
+       "qualityGate": {
+         "checks": [
+           { "name": "all-tasks-complete", "passed": true, "detail": "<N>/<N> tasks" },
+           { "name": "harness-validate", "passed": true },
+           { "name": "tests-pass", "passed": true },
+           { "name": "no-blockers", "passed": true }
+         ],
+         "allPassed": true
+       }
      }
    }
    ```
@@ -265,12 +321,13 @@ These are non-negotiable. When any condition is met, stop immediately.
 ## Harness Integration
 
 - **`harness validate`** — Run after every task completion. Mandatory. No task is complete without a passing validation.
+- **`gather_context`** — Used in PREPARE phase to load state, learnings, handoff, and validation in a single call instead of 4+ separate reads.
 - **`harness check-deps`** — Run when tasks add new imports or modules. Catches boundary violations early.
 - **`harness state show`** — View current execution position and progress.
 - **`harness state learn "<message>"`** — Append a learning from the command line.
 - **`.harness/state.json`** — Read at session start to resume position. Updated after every task.
 - **`.harness/learnings.md`** — Append-only knowledge capture. Read at session start for prior context.
-- **Roadmap sync** — After completing plan execution, sync roadmap status via `manage_roadmap sync` if `docs/roadmap.md` exists. Keeps roadmap current with execution progress.
+- **Roadmap sync** — After completing plan execution, call `manage_roadmap` with action `sync` and `apply: true` to update roadmap status. Mandatory when `docs/roadmap.md` exists. Do not use `force_sync: true`. Falls back to `syncRoadmap()` from core if MCP tool is unavailable.
 - **`emit_interaction`** -- Call at plan completion to auto-transition to harness-verification. Uses auto-transition (proceeds immediately without user confirmation).
 
 ## Success Criteria

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

@@ -46,7 +46,34 @@ Work backward from the goal. Do not start with "what should we build?" Start wit
      type: "question",
      question: {
        text: "The spec mentions X but does not define behavior for Y. Should we:",
-       options: ["A) Include Y in this plan", "B) Defer Y to a follow-up plan", "C) Update the spec first"]
+       options: [
+         {
+           label: "A) Include Y in this plan",
+           pros: ["Complete feature in one pass", "No follow-up coordination needed"],
+           cons: ["Increases plan scope and time", "May delay delivery"],
+           risk: "medium",
+           effort: "high"
+         },
+         {
+           label: "B) Defer Y to a follow-up plan",
+           pros: ["Keeps current plan focused", "Ship sooner"],
+           cons: ["Y remains unhandled", "May need rework when Y is added"],
+           risk: "low",
+           effort: "low"
+         },
+         {
+           label: "C) Update the spec first",
+           pros: ["Design is complete before planning", "No surprises during execution"],
+           cons: ["Blocks planning until spec is updated", "Extra round-trip"],
+           risk: "low",
+           effort: "medium"
+         }
+       ],
+       recommendation: {
+         optionIndex: 1,
+         reason: "Keeping the current plan focused reduces risk. Y can be addressed in a dedicated follow-up.",
+         confidence: "medium"
+       }
      }
    })
    ```
@@ -174,7 +201,9 @@ When presenting the task breakdown, use progress markers:
      type: "confirmation",
      confirmation: {
        text: "Approve plan at <plan-file-path>?",
-       context: "<task count> tasks, <estimated time> minutes. <one-sentence summary>"
+       context: "<task count> tasks, <estimated time> minutes. <one-sentence summary>",
+       impact: "Approving unlocks task-by-task execution. Plan defines exact file paths, code, and commands.",
+       risk: "low"
      }
    })
    ```
@@ -192,7 +221,16 @@ When presenting the task breakdown, use progress markers:
         "reason": "Plan approved with all tasks defined",
         "artifacts": ["<plan file path>"],
         "requiresConfirmation": true,
-        "summary": "<Plan title> -- <N> tasks, <N> checkpoints. Estimated <time>."
+        "summary": "<Plan title> -- <N> tasks, <N> checkpoints. Estimated <time>.",
+        "qualityGate": {
+          "checks": [
+            { "name": "plan-written", "passed": true, "detail": "Written to docs/plans/" },
+            { "name": "harness-validate", "passed": true },
+            { "name": "observable-truths-traced", "passed": true },
+            { "name": "human-approved", "passed": true }
+          ],
+          "allPassed": true
+        }
       }
     }
     ```

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

@@ -43,6 +43,20 @@ pnpm typecheck 2>&1 || npx tsc --noEmit 2>&1 || make typecheck 2>&1
 pnpm test 2>&1 || npm test 2>&1 || make test 2>&1
 ```
 
+#### 2b. Harness Health Check
+
+If the project uses harness, run `assess_project` for harness-specific validation:
+
+```json
+assess_project({
+  path: "<project-root>",
+  checks: ["validate", "deps"],
+  mode: "summary"
+})
+```
+
+If `healthy: false`, include harness check failures in the mechanical check report. This replaces manually running `harness validate` and `harness check-deps` as separate commands.
+
 #### 3. Gate Decision
 
 - **Any check fails:** STOP. Report the failure. Do not proceed to AI review. The author must fix mechanical issues first.
@@ -133,12 +147,21 @@ If no source files are staged, skip the security scan.
 
 Perform a focused, lightweight review of staged changes. This is NOT a full code review — it catches obvious issues only.
 
-#### 1. Get the Staged Diff
+#### 1. Quick Review via review_changes
 
-```bash
-git diff --cached
+Use the `review_changes` MCP tool with `depth: 'quick'` for fast pre-commit analysis:
+
+```json
+review_changes({
+  path: "<project-root>",
+  diff: "<output of git diff --cached>",
+  depth: "quick",
+  mode: "summary"
+})
 ```
 
+This runs forbidden pattern checks and size analysis. For the semantic review items below, supplement with manual diff reading.
+
 #### 2. Quick Review Checklist
 
 Review the staged diff for these high-signal issues only:
@@ -219,6 +242,8 @@ fi
 - Follows Principle 7 (Deterministic-vs-LLM Split) — mechanical checks first, AI review second
 - Reads `.harness/review-learnings.md` for calibration (if present)
 - Complements harness-code-review (full review) — use pre-commit for quick checks, code-review for thorough analysis
+- **`assess_project`** — Used in Phase 1 for harness-specific health checks (validate + deps) in a single call.
+- **`review_changes`** — Used in Phase 4 with `depth: 'quick'` for fast pre-commit diff analysis.
 
 ## Success Criteria
 

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

@@ -111,7 +111,19 @@ Run every check below. Record each as **pass**, **warn**, or **fail**:
 | `test` script exists in root `package.json`                     | fail                |
 | `lint` script exists in root `package.json`                     | fail                |
 | `typecheck` or `tsc` script exists in root `package.json`       | fail                |
-| `harness validate` passes (project-level health check)          | fail                |
+| `assess_project` passes (harness health + lint gate)            | fail                |
+
+For the `assess_project` check, run it with all harness-specific checks including lint:
+
+```json
+assess_project({
+  path: "<project-root>",
+  checks: ["validate", "deps", "docs", "lint"],
+  mode: "detailed"
+})
+```
+
+If `healthy: false`, each failing check in the `checks` array maps to a separate finding with its `topIssue`. This replaces running `harness validate`, `harness check-deps`, and lint as separate commands.
 
 ##### i18n Coverage (conditional)
 
@@ -507,7 +519,7 @@ This framing is informational — it does not block anything. It gives the team
 
 ## Harness Integration
 
-- **`harness validate`** — Run after auto-fixes to verify project health. Also included in AUDIT phase as a meta-check (does the project pass its own validation?).
+- **`assess_project`** — Used in AUDIT Phase 1 (CI/CD section) to run harness validation, dependency checks, doc coverage, and lint in a single parallel call. Also run after auto-fixes in Phase 3 to verify project health. Automatically inherits new checks added to `assess_project`.
 - **Sub-skill invocations** — Phase 2 dispatches `detect-doc-drift`, `cleanup-dead-code`, `enforce-architecture`, and `diagnostics` as parallel agents. Phase 3 delegates fixes to `align-documentation` and `cleanup-dead-code`.
 - **State file** — `.harness/release-readiness.json` enables session resumption and progress tracking. This file is read at the start of each invocation and written at the end.
 - **Report file** — `release-readiness-report.md` is written to the project root. It is a snapshot, not a tracked artifact — regenerate it on each run.

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

@@ -177,7 +177,9 @@ emit_interaction({
   type: "confirmation",
   confirmation: {
     text: "Verification report: <VERDICT>. Accept and proceed?",
-    context: "<summary: N artifacts checked, N gaps found>"
+    context: "<summary: N artifacts checked, N gaps found>",
+    impact: "Accepting proceeds to code review. Declining requires gap resolution first.",
+    risk: "<low if PASS, high if gaps remain>"
   }
 })
 ```
@@ -212,7 +214,21 @@ Call `emit_interaction`:
     "reason": "Verification passed at all 3 levels",
     "artifacts": ["<verified file paths>"],
     "requiresConfirmation": false,
-    "summary": "Verification passed: <N> artifacts checked. EXISTS, SUBSTANTIVE, WIRED all passed."
+    "summary": "Verification passed: <N> artifacts checked. EXISTS, SUBSTANTIVE, WIRED all passed.",
+    "qualityGate": {
+      "checks": [
+        { "name": "level1-exists", "passed": true, "detail": "<N> artifacts present" },
+        { "name": "level2-substantive", "passed": true, "detail": "No stubs or placeholders" },
+        {
+          "name": "level3-wired",
+          "passed": true,
+          "detail": "All artifacts imported, tested, integrated"
+        },
+        { "name": "anti-pattern-scan", "passed": true, "detail": "No matches" },
+        { "name": "harness-validate", "passed": true }
+      ],
+      "allPassed": true
+    }
   }
 }
 ```

package/dist/agents/skills/gemini-cli/cleanup-dead-code/SKILL.md

@@ -74,9 +74,9 @@ For each item categorized as safe:
 
 **New fix types:**
 
-- **Dead exports (non-public):** Use `apply_fixes` with `fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
-- **Commented-out code:** Use `apply_fixes` with `fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
-- **Orphaned dependencies:** Use `apply_fixes` with `fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
+- **Dead exports (non-public):** Use `detect_entropy` with `autoFix: true, fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
+- **Commented-out code:** Use `detect_entropy` with `autoFix: true, fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
+- **Orphaned dependencies:** Use `detect_entropy` with `autoFix: true, fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
 
 ### Phase 3.5: Convergence Loop (Standalone)