@harness-engineering/cli 1.7.0 → 1.8.0

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

@@ -0,0 +1,48 @@
+name: harness-soundness-review
+version: "1.0.0"
+description: Deep soundness analysis of specs and plans with auto-fix and convergence loop
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-soundness-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: Review mode — "spec" for spec soundness or "plan" for plan soundness
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-soundness-review
+    path: string
+type: rigid
+phases:
+  - name: check
+    description: Run all checks for the current mode and classify findings
+    required: true
+  - name: fix
+    description: Auto-fix inferrable issues and log changes
+    required: true
+  - name: converge
+    description: Re-run checks, compare issue counts, loop or stop
+    required: true
+  - name: surface
+    description: Present remaining issues to user for resolution
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -13,8 +13,23 @@
 
 ## Prerequisites
 
-A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
-If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
 
 ## Process
 
@@ -43,6 +58,20 @@ For each changed file, use graph traversal to find test files:
 
 3. **Co-change tests**: Check `co_changes_with` edges for test files that historically change alongside the modified files.
 
+#### Fallback (without graph)
+
+When no graph is available, use naming conventions, import parsing, and git history:
+
+1. **Tier 1 — Filename convention matching**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory)
+   - `__tests__/foo.ts`, `__tests__/foo.test.ts`
+   - Test files in a parallel `tests/` directory mirroring the source path
+2. **Tier 2 — Import-linked tests**: Parse test files' import statements (grep for `import.*from` in `*.test.*` and `*.spec.*` files). If a test file imports the changed file, it belongs in Tier 2 (if not already in Tier 1).
+3. **Tier 3 — Co-change correlated tests**: Use `git log --format="%H" --name-only` to find test files that frequently change in the same commit as the target file. Files that co-change in >2 commits are co-change correlated.
+4. **Rank**: Tier 1 = direct filename match, Tier 2 = import-linked tests, Tier 3 = co-change correlated tests. Output the same tiered format as the graph version.
+
+> Fallback completeness: ~80% — naming conventions and imports catch most mappings; misses dynamic imports and indirect coverage.
+
 ### Phase 3: PRIORITIZE — Rank and Generate Commands
 
 Organize tests into three tiers:
@@ -85,7 +114,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
 
@@ -95,7 +124,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 - Executable run commands generated for quick and full test runs
 - Coverage gaps flagged for changed files with no test coverage
 - Report follows the structured output format
-- All findings are backed by graph query evidence, not heuristics
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
 ## Examples
 
@@ -122,8 +151,8 @@ Output:
 
 ## Gates
 
-- **No advice without graph.** If no graph exists, fall back to: "Run all tests in the same directory as changed files."
-- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these.
+- **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these (whether found via graph or naming conventions).
 
 ## Escalation
 

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

@@ -160,6 +160,70 @@ After running all three levels, produce a structured gap report:
 ### Verdict: INCOMPLETE — 2 gaps must be resolved
 ```
 
+The verification report uses conventional markdown patterns for structured output:
+
+```
+**[CRITICAL]** path/to/file.ts:22 — TODO: implement validation (anti-pattern)
+**[IMPORTANT]** path/to/file.ts — exported but not imported by any other file
+```
+
+### Verification Sign-Off
+
+After producing the verification report, request acceptance:
+
+```json
+emit_interaction({
+  path: "<project-root>",
+  type: "confirmation",
+  confirmation: {
+    text: "Verification report: <VERDICT>. Accept and proceed?",
+    context: "<summary: N artifacts checked, N gaps found>"
+  }
+})
+```
+
+### Handoff and Transition
+
+After producing the verification report, write the handoff and conditionally transition:
+
+Write `.harness/handoff.json`:
+
+```json
+{
+  "fromSkill": "harness-verification",
+  "phase": "COMPLETE",
+  "summary": "<verdict summary>",
+  "artifacts": ["<verified file paths>"],
+  "verdict": "pass | fail",
+  "gaps": ["<gap descriptions if any>"]
+}
+```
+
+**If verdict is PASS (all levels passed, no gaps):**
+
+Call `emit_interaction`:
+
+```json
+{
+  "type": "transition",
+  "transition": {
+    "completedPhase": "verification",
+    "suggestedNext": "review",
+    "reason": "Verification passed at all 3 levels",
+    "artifacts": ["<verified file paths>"],
+    "requiresConfirmation": false,
+    "summary": "Verification passed: <N> artifacts checked. EXISTS, SUBSTANTIVE, WIRED all passed."
+  }
+}
+```
+
+The response will include `nextAction: "Invoke harness-code-review skill now"`.
+Immediately invoke harness-code-review without waiting for user input.
+
+**If verdict is FAIL or INCOMPLETE:**
+
+Do NOT emit a transition. Surface gaps to the user for resolution. The handoff is written with the gaps recorded for future reference.
+
 ---
 
 ### Regression Test Verification
@@ -184,6 +248,8 @@ If step 4 passes (test does not fail without the fix), the test is not a valid r
 
 All commands must be run fresh in the current session. Do not rely on results from a previous session or a previous run in the same session if code has changed since.
 
+- **`emit_interaction`** -- Call after verification passes to auto-transition to harness-code-review. Only emitted on PASS verdict. Uses auto-transition (proceeds immediately).
+
 ## Success Criteria
 
 - Every claimed deliverable has been verified at all 3 levels

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

@@ -13,6 +13,7 @@ tools:
   - Bash
   - Read
   - Glob
+  - emit_interaction
 cli:
   command: harness skill run harness-verification
   args:

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

@@ -89,6 +89,16 @@ Rules:
 - If all checks are SKIPPED, overall result is `PASS` (nothing to fail).
 - On FAIL, include a brief summary of what failed (e.g., "3 type errors", "2 lint errors", "5 tests failed") below the structured block.
 
+### Roadmap Sync (conditional)
+
+When all non-skipped checks pass (overall `Verification: PASS`) and `docs/roadmap.md` exists:
+
+1. Trigger a roadmap sync to update feature statuses based on the verified state.
+2. Use the `manage_roadmap` MCP tool with `sync` action if available, or note to the caller that a roadmap sync is recommended.
+3. Features linked to plans whose tasks are all complete and verified may be marked as `done`.
+
+If `docs/roadmap.md` does not exist, skip this step silently. If verification failed, do not sync — the roadmap should only reflect verified completions.
+
 ## Deterministic Checks
 
 This skill is entirely deterministic. There are no LLM judgment calls anywhere in the process.
@@ -106,6 +116,7 @@ This skill is entirely deterministic. There are no LLM judgment calls anywhere i
 - Output format is consumed by harness-integrity for the unified pipeline
 - Invokes `harness-accessibility` for design constraint checking when `design` config exists
 - Design violations respect `design.strictness` from `harness.config.json`
+- **Roadmap sync** — When verification passes and `docs/roadmap.md` exists, triggers `manage_roadmap sync` to mark verified features as `done`. Only fires on overall PASS.
 
 ## Success Criteria
 

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

@@ -59,6 +59,11 @@
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
+5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
+   - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
+   - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
+   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
@@ -82,7 +87,9 @@ harness scan [path]
 
 This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
 
-4. **Commit the initialization.** All generated and configured files in a single commit.
+4. **Mention roadmap.** After validation passes, inform the user: "When you are ready to set up a project roadmap, run `/harness:roadmap --create`. This creates a unified `docs/roadmap.md` that tracks features, milestones, and status across your specs and plans." This is informational only — do not create the roadmap automatically.
+
+5. **Commit the initialization.** All generated and configured files in a single commit.
 
 ## Harness Integration
 
@@ -91,6 +98,8 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
 - **`harness validate`** — Verify the full project configuration is valid and complete.
 - **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
+- **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
+- **Roadmap nudge** — After successful initialization, inform the user about `/harness:roadmap --create` for setting up project-level feature tracking. Informational only; does not create the roadmap.
 
 ## Success Criteria
 
@@ -102,6 +111,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - Personas are configured if the project uses them
 - The adoption level matches what was agreed upon with the human
 - All generated files are committed in a single atomic commit
+- i18n configuration is set if the human chose to enable it during init
 
 ## Examples
 
@@ -131,6 +141,10 @@ Edit AGENTS.md:
   - Add stack: TypeScript, Express, Vitest, PostgreSQL
   - Add conventions: "Use zod for validation, repository pattern for data access"
   - Add constraints: "No direct SQL queries outside repository layer"
+  - Ask: "Will this project support multiple languages?"
+  - Human: "Yes, Spanish and French."
+  - Run harness-i18n-workflow configure (source: en, targets: es, fr)
+  - Run harness-i18n-workflow scaffold (creates locales/ directory structure)
 ```
 
 **VALIDATE:**

package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md

@@ -32,6 +32,18 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 When a graph is available, it IS the source of truth for documentation coverage. Drift = stale or missing edges between code and doc nodes. Fall back to file-based commands if no graph is available.
 
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - Use `pipeline.exclusions` to skip findings that were already addressed in the FIX phase
+  - Write `GapFinding[]` results back to `pipeline.gapFindings` in handoff.json
+  - This enables dedup across FIX and AUDIT phases
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
 ### Phase 2: Detect Gaps
 
 Categorize findings into four types:

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

@@ -25,6 +25,12 @@
    - `standard` -- warnings are visible, errors block (default behavior)
    - `permissive` -- all findings are informational (nothing blocks, but everything is reported)
 
+2.5. **Check for i18n skill overlap.** Read `harness.config.json` for `i18n.enabled`:
+
+- If `i18n.enabled: true`, **defer** `lang` and `dir` attribute checks to `harness-i18n`. Do not scan for missing `lang` on `<html>` or missing `dir` on user-content containers -- those checks are covered by the i18n skill's scan phase with more context (locale-aware, RTL-aware).
+- If `i18n.enabled` is false or absent, scan for `lang`/`dir` as normal (these remain part of the accessibility audit).
+- This deduplication prevents the same finding from appearing in both the accessibility report and the i18n report.
+
 3. **Scan component files.** Search all files matching `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html` for the following violations:
 
    **Images and media:**
@@ -176,6 +182,7 @@ This phase is optional. It applies fixes only for **mechanical issues** -- viola
 - **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Provides token data used for contrast checking. The ingestor parses `tokens.json` so the accessibility scanner can compare code colors against declared tokens.
 - **`harness-impact-analysis`** -- When tokens change (palette update, new colors), impact analysis traces affected components. The accessibility skill uses this to determine which components need re-scanning.
 - **`harness-design-system`** -- Dependency. When contrast failures originate from token definitions (not component code), escalate to harness-design-system to fix at the source.
+- **`harness-i18n` deduplication** -- When `i18n.enabled: true` in config, `lang` and `dir` attribute checks are deferred to the i18n skill. This prevents duplicate findings across the accessibility and i18n reports. When i18n is not enabled, these checks remain part of the accessibility scan.
 
 ## Success Criteria
 

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

@@ -97,7 +97,14 @@ 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.
 
-6. **Transition to ASSESS.**
+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.
+
+7. **Transition to ASSESS.**
 
 ---
 
@@ -374,6 +381,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 - **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
 

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.

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

@@ -0,0 +1,64 @@
+name: harness-codebase-cleanup
+version: "1.0.0"
+description: Orchestrate dead code removal and architecture violation fixes with shared convergence loop
+cognitive_mode: systematic-orchestrator
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-codebase-cleanup
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: fix
+      description: Enable convergence-based auto-fix (default detect+report only)
+      required: false
+    - name: dead-code-only
+      description: Skip architecture checks
+      required: false
+    - name: architecture-only
+      description: Skip dead code checks
+      required: false
+    - name: dry-run
+      description: Show what would be fixed without applying
+      required: false
+    - name: ci
+      description: Non-interactive mode (safe fixes only, report everything else)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-codebase-cleanup
+    path: string
+type: flexible
+phases:
+  - name: context
+    description: Run hotspot detection, build churn map
+    required: true
+  - name: detect
+    description: Run dead code and architecture detection in parallel
+    required: true
+  - name: classify
+    description: Classify findings, apply hotspot downgrade, cross-concern dedup
+    required: true
+  - name: fix
+    description: Convergence loop - apply safe fixes, verify, re-detect
+    required: false
+  - name: report
+    description: Generate actionable report of fixes applied and remaining findings
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - cleanup-dead-code
+  - enforce-architecture
+  - harness-hotspot-detector