@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/gemini-cli/harness-accessibility/skill.yaml

@@ -0,0 +1,51 @@
+name: harness-accessibility
+version: "1.0.0"
+description: WCAG accessibility scanning, contrast checking, ARIA validation, and remediation
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_new_feature
+  - on_project_init
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-accessibility
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: scope
+      description: Scope of scan (full, component, page)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-accessibility
+    path: string
+type: rigid
+phases:
+  - name: scan
+    description: Scan codebase for accessibility issues (WCAG AA baseline)
+    required: true
+  - name: evaluate
+    description: Evaluate severity and categorize findings
+    required: true
+  - name: report
+    description: Generate structured accessibility report
+    required: true
+  - name: fix
+    description: Apply automated fixes for mechanical issues
+    required: false
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-design-system

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

@@ -13,18 +13,23 @@
 
 ## Relationship to Other Skills
 
-| Skill                | Role in Autopilot                            |
-| -------------------- | -------------------------------------------- |
-| harness-planning     | Delegated to for phase plan creation         |
-| harness-execution    | Delegated to for task-by-task implementation |
-| harness-verification | Delegated to for post-execution validation   |
-| harness-code-review  | Delegated to for post-verification review    |
+| Skill                | Persona Agent (`subagent_type`) | Role in Autopilot                            |
+| -------------------- | ------------------------------- | -------------------------------------------- |
+| harness-planning     | `harness-planner`               | Delegated to for phase plan creation         |
+| harness-execution    | `harness-task-executor`         | Delegated to for task-by-task implementation |
+| harness-verification | `harness-verifier`              | Delegated to for post-execution validation   |
+| harness-code-review  | `harness-code-reviewer`         | Delegated to for post-verification review    |
 
-Autopilot orchestrates these skills — it never reimplements their logic.
+Autopilot orchestrates these persona agents — it never reimplements their logic. Each agent is dispatched via the Agent tool with the corresponding `subagent_type`, which isolates it to the harness methodology and prevents it from using unrelated skills.
 
 ## Iron Law
 
-**Autopilot delegates, never reimplements.** If you find yourself writing planning logic, execution logic, or review logic inside the autopilot loop, STOP. Delegate to the appropriate skill via subagent.
+**Autopilot delegates, never reimplements.** If you find yourself writing planning logic, execution logic, or review logic inside the autopilot loop, STOP. Delegate to the dedicated persona agent.
+
+**Always use dedicated persona agents, never general-purpose agents.** Every dispatch MUST target the specific harness persona (`harness-planner`, `harness-task-executor`, `harness-verifier`, `harness-code-reviewer`). General-purpose agents see all globally registered skills and may use unrelated workflows instead of the harness methodology.
+
+- **Claude Code:** Use the Agent tool with `subagent_type` set to the persona name.
+- **Gemini CLI:** Use the `run_agent` tool targeting the persona by name, or dispatch via `harness persona run <name>`.
 
 **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.
 
@@ -44,20 +49,32 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### Phase 1: INIT — Load Spec and Restore State
 
-1. **Check for existing state.** Read `.harness/autopilot-state.json`. If it exists and `currentState` is not `DONE`:
+1. **Resolve spec path.** The spec file is provided as an argument, or ask the user for the spec path.
+
+2. **Derive session slug and directory:**
+   - Derive the session slug from the spec path:
+     1. If the path starts with `docs/`, strip the `docs/` prefix. Otherwise, use the full relative path.
+     2. Drop the trailing `.md` extension
+     3. Replace all `/` and `.` characters with `--`
+     4. Lowercase the result
+   - Set `sessionDir = .harness/sessions/<slug>/`
+   - Create the session directory if it does not exist
+
+3. **Check for existing state.** Read `{sessionDir}/autopilot-state.json`. If it exists and `currentState` is not `DONE`:
    - Report: "Resuming autopilot from state `{currentState}`, phase {currentPhase}: {phaseName}."
    - Skip to the recorded `currentState` and continue from there.
 
-2. **If no existing state (fresh start):**
-   - Read the spec file (provided as argument or found via `.harness/handoff.json`). If neither is available, ask the user for the spec path.
+4. **If no existing state (fresh start):**
+   - Read the spec file.
    - Parse the `## Implementation Order` section to extract phases.
    - For each phase heading (`### Phase N: Name`), extract:
      - Phase name
      - Complexity annotation (`<!-- complexity: low|medium|high -->`, default: `medium`)
-   - Create `.harness/autopilot-state.json`:
+   - Create `{sessionDir}/autopilot-state.json`:
      ```json
      {
-       "schemaVersion": 1,
+       "schemaVersion": 2,
+       "sessionDir": ".harness/sessions/<slug>",
        "specPath": "<path to spec>",
        "currentState": "ASSESS",
        "currentPhase": 0,
@@ -78,15 +95,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      }
      ```
 
-3. **Load context.** Read `.harness/learnings.md` and `.harness/failures.md` if they exist. Note any relevant learnings or known dead ends for the current phase.
+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.
+
+6. **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.
 
-4. **Transition to ASSESS.**
+7. **Transition to ASSESS.**
 
 ---
 
 ### ASSESS — Determine Phase Approach
 
-1. **Read the current phase** from `autopilot-state.json` at index `currentPhase`.
+1. **Read the current phase** from `{sessionDir}/autopilot-state.json` at index `currentPhase`.
 
 2. **Check if plan already exists.** If `planPath` is set and the file exists, skip to `APPROVE_PLAN`.
 
@@ -97,8 +121,8 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
      | Effective Complexity | Action                                                                                                                                                                                                                               |
      | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-     | `low`                | Auto-plan via subagent. Proceed to PLAN.                                                                                                                                                                                             |
-     | `medium`             | Auto-plan via subagent. Proceed to PLAN. Present with extra scrutiny note.                                                                                                                                                           |
+     | `low`                | Auto-plan via `harness-planner` agent. Proceed to PLAN.                                                                                                                                                                              |
+     | `medium`             | Auto-plan via `harness-planner` agent. Proceed to PLAN. Present with extra scrutiny note.                                                                                                                                            |
      | `high`               | Pause. Tell the user: "Phase {N}: {name} is marked high-complexity. Run `/harness:planning` interactively for this phase, then re-invoke `/harness:autopilot` to continue." Transition to PLAN with `awaitingInteractivePlan: true`. |
 
 4. **Update state** with `currentState: "PLAN"` and save.
@@ -109,22 +133,27 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 **If auto-planning (low/medium complexity):**
 
-1. Dispatch a subagent with the following prompt:
+1. Dispatch a planning agent using the Agent tool:
 
    ```
-   You are running harness-planning for phase {N}: {name}.
-
-   Spec: {specPath}
-   Phase description: {phase description from spec}
-   Previous phase learnings: {relevant learnings from .harness/learnings.md}
-   Known failures to avoid: {relevant entries from .harness/failures.md}
-
-   Follow the harness-planning skill process exactly. Write the plan to
-   docs/plans/{date}-{phase-name}-plan.md. Write .harness/handoff.json when done.
+   Agent tool parameters:
+     subagent_type: "harness-planner"
+     description: "Plan phase {N}: {name}"
+     prompt: |
+       You are running harness-planning for phase {N}: {name}.
+
+       Spec: {specPath}
+       Session directory: {sessionDir}
+       Phase description: {phase description from spec}
+       Previous phase learnings (global): {relevant learnings from .harness/learnings.md}
+       Known failures to avoid (global): {relevant entries from .harness/failures.md}
+
+       Follow the harness-planning skill process exactly. Write the plan to
+       docs/plans/{date}-{phase-name}-plan.md. Write {sessionDir}/handoff.json when done.
    ```
 
-2. When the subagent returns:
-   - Read the generated plan path from `.harness/handoff.json`.
+2. When the agent returns:
+   - Read the generated plan path from `{sessionDir}/handoff.json`.
    - **Apply complexity override check:**
      - Count tasks in the plan.
      - Count `[checkpoint:*]` markers.
@@ -138,7 +167,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 **If awaiting interactive plan (high complexity):**
 
 1. Check if a plan file now exists for this phase (user ran planning separately).
-   - Look for files matching `docs/plans/*{phase-name}*` or check `.harness/handoff.json` for a planning handoff.
+   - Look for files matching `docs/plans/*{phase-name}*` or check `{sessionDir}/handoff.json` for a planning handoff.
 2. If found: update `planPath` in state, transition to `APPROVE_PLAN`.
 3. If not found: remind the user and wait.
 
@@ -170,27 +199,32 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### EXECUTE — Run the Plan
 
-1. **Dispatch execution subagent:**
+1. **Dispatch execution agent using the Agent tool:**
 
    ```
-   You are running harness-execution for phase {N}: {name}.
-
-   Plan: {planPath}
-   State: .harness/state.json
-   Learnings: .harness/learnings.md
-   Failures: .harness/failures.md
-
-   Follow the harness-execution skill process exactly.
-   Update .harness/state.json after each task.
-   Write .harness/handoff.json when done or when blocked.
+   Agent tool parameters:
+     subagent_type: "harness-task-executor"
+     description: "Execute phase {N}: {name}"
+     prompt: |
+       You are running harness-execution for phase {N}: {name}.
+
+       Plan: {planPath}
+       Session directory: {sessionDir}
+       State: {sessionDir}/state.json
+       Learnings (global): .harness/learnings.md
+       Failures (global): .harness/failures.md
+
+       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 subagent returns, check the outcome:**
+2. **When the agent returns, check the outcome:**
    - **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 subagent.
-     - `[checkpoint:decision]` — Present options, record choice, resume execution subagent.
-     - `[checkpoint:human-action]` — Instruct user, wait for confirmation, resume execution subagent.
+     - `[checkpoint:human-verify]` — Show output, ask for confirmation, then resume execution agent.
+     - `[checkpoint:decision]` — Present options, record choice, resume execution agent.
+     - `[checkpoint:human-action]` — Instruct user, wait for confirmation, resume execution agent.
    - **Task failed:** Enter retry logic (see below).
 
 3. **Retry logic on failure:**
@@ -198,7 +232,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - If `attemptsUsed < maxAttempts`:
      - Increment `attemptsUsed`.
      - Record the attempt (timestamp, error, fix attempted, result).
-     - **Attempt 1:** Read error output, apply obvious fix, re-dispatch execution subagent for the failed task only.
+     - **Attempt 1:** Read error output, apply obvious fix, re-dispatch execution agent for the failed task only.
      - **Attempt 2:** Expand context — read related files, check `learnings.md` for similar failures, re-dispatch with additional context.
      - **Attempt 3:** Full context gather — read test output, imports, plan instructions for ambiguity. Re-dispatch with maximum context.
    - If budget exhausted:
@@ -213,16 +247,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### VERIFY — Post-Execution Validation
 
-1. **Dispatch verification subagent:**
+1. **Dispatch verification agent using the Agent tool:**
 
    ```
-   You are running harness-verification for phase {N}: {name}.
+   Agent tool parameters:
+     subagent_type: "harness-verifier"
+     description: "Verify phase {N}: {name}"
+     prompt: |
+       You are running harness-verification for phase {N}: {name}.
+
+       Session directory: {sessionDir}
 
-   Follow the harness-verification skill process exactly.
-   Report pass/fail with findings.
+       Follow the harness-verification skill process exactly.
+       Report pass/fail with findings.
    ```
 
-2. **When the subagent returns:**
+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).
@@ -235,16 +275,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### REVIEW — Code Review
 
-1. **Dispatch review subagent:**
+1. **Dispatch review agent using the Agent tool:**
 
    ```
-   You are running harness-code-review for phase {N}: {name}.
+   Agent tool parameters:
+     subagent_type: "harness-code-reviewer"
+     description: "Review phase {N}: {name}"
+     prompt: |
+       You are running harness-code-review for phase {N}: {name}.
+
+       Session directory: {sessionDir}
 
-   Follow the harness-code-review skill process exactly.
-   Report findings with severity (blocking / warning / note).
+       Follow the harness-code-review skill process exactly.
+       Report findings with severity (blocking / warning / note).
    ```
 
-2. **When the subagent returns:**
+2. **When the agent returns:**
    - **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.
@@ -303,7 +349,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - "Create a PR? (yes / no)"
    - If yes: assemble commit history, suggest PR title and description.
 
-3. **Write final handoff:**
+3. **Write final handoff** to `{sessionDir}/handoff.json`:
 
    ```json
    {
@@ -326,20 +372,21 @@ 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 `autopilot-state.json`. Do not delete the file — it serves as a record.
+5. **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.
 - **`harness check-deps`** — Delegated to harness-execution (included in task steps).
-- **State file** — `.harness/autopilot-state.json` tracks the orchestration state machine. `.harness/state.json` tracks task-level execution state (managed by harness-execution).
-- **Handoff** — `.harness/handoff.json` is written by each delegated skill and read by the next. Autopilot writes a final handoff on DONE.
-- **Learnings** — `.harness/learnings.md` is appended by both delegated skills and autopilot itself.
+- **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.
 
 ## Success Criteria
 
 - Single `/harness:autopilot` invocation executes all phases through to completion
-- Resume from any state after context reset via `.harness/autopilot-state.json`
+- Resume from any state after context reset via session-scoped `autopilot-state.json`
 - Low-complexity phases auto-plan; high-complexity phases pause for interactive planning
 - Planning override bumps complexity upward when task signals disagree
 - Retry budget (3 attempts) with escalating context before surfacing failures
@@ -360,7 +407,7 @@ Read spec — found 3 phases:
   Phase 1: Core Scanner (complexity: low)
   Phase 2: Rule Engine (complexity: high)
   Phase 3: CLI Integration (complexity: low)
-Created .harness/autopilot-state.json. Starting Phase 1.
+Created .harness/sessions/specs--2026-03-19-security-scanner/autopilot-state.json. Starting Phase 1.
 ```
 
 **Phase 1 — ASSESS:**
@@ -372,7 +419,7 @@ Phase 1: Core Scanner — complexity: low. Auto-planning.
 **Phase 1 — PLAN:**
 
 ```
-[Subagent runs harness-planning]
+[harness-planner agent runs harness-planning]
 Plan generated: docs/plans/2026-03-19-core-scanner-plan.md (8 tasks, ~24 min)
 ```
 
@@ -388,9 +435,9 @@ Approve this plan and begin execution? (yes / revise / skip / stop)
 **Phase 1 — EXECUTE → VERIFY → REVIEW:**
 
 ```
-[Subagent executes 8 tasks... all pass]
-[Subagent runs verification... pass]
-[Subagent runs code review... 0 blocking, 2 notes]
+[harness-task-executor agent executes 8 tasks... all pass]
+[harness-verifier agent runs verification... pass]
+[harness-code-reviewer agent runs code review... 0 blocking, 2 notes]
 ```
 
 **Phase 1 — PHASE_COMPLETE:**
@@ -479,16 +526,16 @@ 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 skill.
+- **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 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 autopilot-state.json manually.** The state file is managed by the skill. If the state appears corrupted, start fresh rather than patching it.
+- **No modifying session state files manually.** The session state files are managed by the skill. If the state appears corrupted, start fresh rather than patching it.
 
 ## Escalation
 
 - **When the spec has no Implementation Order section:** Cannot identify phases. Ask the user to add phase annotations to the spec or provide a roadmap file.
-- **When a delegated skill fails to produce expected output:** Check that handoff.json was written correctly. If the subagent failed, report the failure and ask the user whether to retry the entire phase step or stop.
-- **When the user wants to reorder phases mid-run:** Update the phases array in autopilot-state.json (mark skipped phases, adjust currentPhase). Do not re-run completed phases.
+- **When a delegated skill fails to produce expected output:** Check that `{sessionDir}/handoff.json` was written correctly. If the agent failed, report the failure and ask the user whether to retry the entire phase step or stop.
+- **When the user wants to reorder phases mid-run:** Update the phases array in the session-scoped `autopilot-state.json` (mark skipped phases, adjust currentPhase). Do not re-run completed phases.
 - **When context limits are approaching:** Persist state immediately and inform the user: "Context limit approaching. State saved. Re-invoke /harness:autopilot to continue from this point."
 - **When multiple phases fail in sequence:** After 2 consecutive phase failures (retry budget exhausted in both), suggest the user review the spec for systemic issues rather than continuing.

package/dist/agents/skills/gemini-cli/harness-autopilot/skill.yaml

@@ -42,9 +42,11 @@ phases:
 state:
   persistent: true
   files:
-    - .harness/autopilot-state.json
-    - .harness/state.json
+    - .harness/sessions/*/autopilot-state.json
+    - .harness/sessions/*/state.json
+    - .harness/sessions/*/handoff.json
     - .harness/learnings.md
+    - .harness/failures.md
 depends_on:
   - harness-planning
   - harness-execution

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

@@ -0,0 +1,226 @@
+# Harness Codebase Cleanup
+
+> Orchestrate dead code removal and architecture violation fixes with a shared convergence loop. Catches cross-concern cascades that individual skills miss.
+
+## When to Use
+
+- After a major refactoring or feature removal when both dead code and architecture violations are likely
+- As a periodic comprehensive codebase hygiene task
+- When `cleanup-dead-code` or `enforce-architecture` individually are not catching cascading issues
+- When you want hotspot-aware safety classification
+- NOT for quick single-concern checks -- use `cleanup-dead-code` or `enforce-architecture` directly
+- NOT when tests are failing -- fix tests first
+- NOT during active feature development
+
+## Flags
+
+| Flag                  | Effect                                                            |
+| --------------------- | ----------------------------------------------------------------- |
+| `--fix`               | Enable convergence-based auto-fix (default: detect + report only) |
+| `--dead-code-only`    | Skip architecture checks                                          |
+| `--architecture-only` | Skip dead code checks                                             |
+| `--dry-run`           | Show what would be fixed without applying                         |
+| `--ci`                | Non-interactive: apply safe fixes only, report everything else    |
+
+## Process
+
+### Phase 1: CONTEXT -- Build Hotspot Map
+
+1. **Run hotspot detection** via `harness skill run harness-hotspot-detector` or equivalent git log analysis:
+   ```bash
+   git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -50
+   ```
+2. **Build churn map.** Parse output into a `file -> commit count` mapping.
+3. **Compute top 10% threshold.** Sort all files by commit count. The file at the 90th percentile defines the threshold. Files above this threshold are "high churn."
+4. **Store as HotspotContext** for use in Phase 3 (CLASSIFY).
+
+### Phase 2: DETECT -- Run Both Concerns in Parallel
+
+1. **Dead code detection** (skip if `--architecture-only`):
+   - Run `harness cleanup --type dead-code --json`
+   - Or use the `detect_entropy` MCP tool with `type: 'dead-code'`
+   - Captures: dead files, dead exports, unused imports, dead internals, commented-out code blocks, orphaned dependencies
+
+2. **Architecture detection** (skip if `--dead-code-only`):
+   - Run `harness check-deps --json`
+   - Captures: layer violations, forbidden imports, circular dependencies, import ordering issues
+
+3. **Merge findings.** Convert all raw findings into `CleanupFinding` objects using `classifyFinding()`. This normalizes both concerns into a shared schema.
+
+### Phase 3: CLASSIFY -- Safety Classification and Dedup
+
+1. **Apply safety classification.** Each `CleanupFinding` already has a safety level from `classifyFinding()`. Review the classification rules:
+
+   **Dead code safety:**
+
+   | Finding                   | Safety        | Condition                                   |
+   | ------------------------- | ------------- | ------------------------------------------- |
+   | Dead files                | Safe          | Not entry point, no side effects            |
+   | Unused imports            | Safe          | Zero references                             |
+   | Dead exports (non-public) | Safe          | Zero importers, not in package entry point  |
+   | Dead exports (public API) | Unsafe        | In package entry point or published package |
+   | Commented-out code        | Safe          | Always (code is in git history)             |
+   | Orphaned npm deps         | Probably safe | Needs install + test verification           |
+   | Dead internals            | Unsafe        | Cannot reliably determine all callers       |
+
+   **Architecture safety:**
+
+   | Violation                           | Safety        | Condition                  |
+   | ----------------------------------- | ------------- | -------------------------- |
+   | Import ordering                     | Safe          | Mechanical reorder         |
+   | Forbidden import (with alternative) | Probably safe | 1:1 replacement configured |
+   | Forbidden import (no alternative)   | Unsafe        | Requires restructuring     |
+   | Design token (unambiguous)          | Probably safe | Single token match         |
+   | Design token (ambiguous)            | Unsafe        | Multiple candidates        |
+   | Upward dependency                   | Unsafe        | Always                     |
+   | Skip-layer dependency               | Unsafe        | Always                     |
+   | Circular dependency                 | Unsafe        | Always                     |
+
+2. **Apply hotspot downgrade.** For each finding, check if the file is in the top 10% by churn (from Phase 1 HotspotContext). If so, downgrade `safe` to `probably-safe`. Do not downgrade `unsafe` findings.
+
+3. **Cross-concern dedup.** Call `deduplicateFindings()` to merge overlapping findings:
+   - A dead import from a forbidden layer = one finding (dead-code concern, noting architecture overlap)
+   - A dead file that has architecture violations = one finding (dead-code, noting violations resolved by deletion)
+
+### Phase 4: FIX -- Convergence Loop
+
+**Only runs when `--fix` flag is set.** Without `--fix`, skip to Phase 5 (REPORT).
+
+```
+findings = classified findings from Phase 3
+previousCount = findings.length
+iteration = 0
+
+while iteration < 5:
+  iteration++
+
+  # Batch 1: Apply safe fixes silently
+  safeFixes = findings.filter(f => f.safety === 'safe')
+  apply(safeFixes)
+
+  # Batch 2: Present probably-safe fixes
+  if --ci mode:
+    skip probably-safe fixes (report only)
+  else:
+    probablySafeFixes = findings.filter(f => f.safety === 'probably-safe')
+    presentAsDiffs(probablySafeFixes)
+    apply(approved fixes)
+
+  # Verify: lint + typecheck + test
+  verifyResult = run("pnpm lint && pnpm tsc --noEmit && pnpm test")
+
+  if verifyResult.failed:
+    revertBatch()
+    reclassify failed fixes as unsafe
+    continue
+
+  # Re-detect both concerns
+  newFindings = runDetection()  # Phase 2 again
+  newFindings = classify(newFindings)  # Phase 3 again
+
+  if newFindings.length >= previousCount:
+    break  # No progress, stop
+
+  previousCount = newFindings.length
+  findings = newFindings
+```
+
+**Verification gate:** Every fix batch must pass lint + typecheck + test. If verification fails:
+
+1. Revert the entire batch (use git: `git checkout -- .`)
+2. Reclassify all findings in the batch as `unsafe`
+3. Continue the loop with remaining findings
+
+**Cross-concern cascade examples:**
+
+- Dead import from forbidden layer: removing the dead import also resolves the architecture violation. Single fix, both resolved.
+- Architecture fix creates dead code: replacing a forbidden import makes the old module's export dead. Next detect cycle catches it.
+- Dead file resolves multiple violations: deleting a dead file that imports from wrong layers resolves those violations too.
+
+### Phase 5: REPORT -- Actionable Output
+
+Generate a structured report with two sections:
+
+**1. Fixes Applied:**
+For each fix that was applied:
+
+- File and line
+- What was fixed (finding type and description)
+- What action was taken (delete, replace, reorder)
+- Verification status (pass/fail)
+
+**2. Remaining Findings (requires human action):**
+For each unsafe finding that was not auto-fixed:
+
+- **What is wrong:** The finding type, file, line, and description
+- **Why it cannot be auto-fixed:** The safety reason and classification logic
+- **Suggested approach:** Concrete next steps for manual resolution
+
+Example report output:
+
+```
+=== HARNESS CODEBASE CLEANUP REPORT ===
+
+Fixes applied: 12
+  - 5 unused imports removed (safe)
+  - 3 dead exports de-exported (safe)
+  - 2 commented-out code blocks deleted (safe)
+  - 1 forbidden import replaced (probably-safe, approved)
+  - 1 orphaned dependency removed (probably-safe, approved)
+
+Convergence: 3 iterations, 12 → 8 → 3 → 3 (stopped)
+
+Remaining findings: 3 (require human action)
+
+  1. UNSAFE: Circular dependency
+     File: src/services/order-service.ts <-> src/services/inventory-service.ts
+     Why: Circular dependencies require structural refactoring
+     Suggested: Extract shared logic into src/services/stock-calculator.ts
+
+  2. UNSAFE: Dead internal function
+     File: src/utils/legacy.ts:45 — processLegacyFormat()
+     Why: Cannot reliably determine all callers (possible dynamic usage)
+     Suggested: Search for string references, check config files, then delete if confirmed unused
+
+  3. UNSAFE: Public API dead export
+     File: packages/core/src/index.ts — legacyHelper
+     Why: Export is in package entry point; external consumers may depend on it
+     Suggested: Deprecate with @deprecated JSDoc tag, remove in next major version
+```
+
+## Examples
+
+### Example: Post-Refactoring Cleanup
+
+After removing the `legacy-auth` module:
+
+1. **Phase 1 (CONTEXT):** Hotspot analysis shows `src/services/auth.ts` has 42 commits (top 5%).
+2. **Phase 2 (DETECT):** Dead code detects 3 dead exports in `src/utils/token.ts` (were only used by legacy-auth). Architecture detects 1 forbidden import in `src/services/session.ts` (still importing from removed module's location).
+3. **Phase 3 (CLASSIFY):** Dead exports classified as `safe` but downgraded to `probably-safe` because `token.ts` is in a high-churn file. Forbidden import classified as `unsafe` (no alternative configured).
+4. **Phase 4 (FIX):** First iteration removes 3 dead exports (approved as probably-safe). Re-detect finds `token.ts` now has zero exports and becomes a dead file. Second iteration deletes the dead file. Convergence stops -- the forbidden import requires manual restructuring.
+5. **Phase 5 (REPORT):** 4 fixes applied (3 dead exports + 1 dead file), 1 remaining finding (forbidden import requiring restructuring).
+
+## Harness Integration
+
+- **`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
+- **`harness validate`** -- Final validation after all fixes
+- **`harness check-deps`** -- Final architecture check after all fixes
+
+## Success Criteria
+
+- All safe fixes are applied without test failures
+- Probably-safe fixes are presented as diffs for approval (or skipped in CI mode)
+- Unsafe findings are never auto-fixed
+- Convergence loop catches cross-concern cascades
+- Report includes actionable guidance for every remaining finding
+- `harness validate` passes after cleanup
+
+## Escalation
+
+- **When convergence loop does not converge after 5 iterations:** The codebase has deeply tangled issues. Stop and report all remaining findings. Consider breaking the cleanup into focused sessions.
+- **When a safe fix causes test failures:** The classification was wrong. Revert, reclassify as unsafe, and investigate the hidden dependency. Document the false positive for future improvement.
+- **When the hotspot detector is unavailable:** Skip the hotspot downgrade. All safety classifications use their base level without churn context.
+- **When dead code and architecture fixes conflict:** The convergence loop handles this naturally. If removing dead code creates an architecture issue (rare), the next detection cycle catches it.