@harness-engineering/cli 1.7.0 → 1.8.0

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

@@ -1,6 +1,6 @@
 name: harness-code-review
-version: "1.0.0"
-description: Structured code review with automated harness checks
+version: "2.0.0"
+description: Multi-phase code review pipeline with mechanical checks, graph-scoped context, and parallel review agents
 cognitive_mode: adversarial-reviewer
 triggers:
   - manual
@@ -14,12 +14,25 @@ tools:
   - Read
   - Glob
   - Grep
+  - emit_interaction
 cli:
   command: harness skill run harness-code-review
   args:
     - name: path
       description: Project root path
       required: false
+    - name: --comment
+      description: Post inline comments to GitHub PR
+      required: false
+    - name: --deep
+      description: Add threat modeling pass (invokes security-review --deep)
+      required: false
+    - name: --no-mechanical
+      description: Skip mechanical checks (useful if already run)
+      required: false
+    - name: --ci
+      description: Enable eligibility gate, non-interactive output
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/claude-code/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/claude-code/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

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

@@ -12,8 +12,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 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
+
+**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
 
@@ -50,6 +65,20 @@ Query the graph for five key structural indicators:
 
 5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
 
+#### Fallback (without graph)
+
+When no graph is available, use static analysis to approximate structural metrics:
+
+1. **Build adjacency list**: Grep all source files for `import`/`require` statements. Parse each to extract the imported path. Build an adjacency list mapping each file to its imports.
+2. **Hub detection**: From the adjacency list, count inbound edges per file. Files with >10 importers are hubs.
+3. **Orphan detection**: Files with zero inbound edges that are not entry points (not `index.*`, not in `package.json` main/exports). Use glob to find all source files, then subtract those that appear as import targets.
+4. **Cycle detection**: Run DFS on the adjacency list. When a back-edge is found, report the cycle path.
+5. **Deep chain detection**: From entry points, DFS to find the longest import chain. Report chains exceeding 7 hops.
+6. **Module cohesion (approximate)**: For each directory, count imports that stay within the directory (internal) vs imports that leave it (external). Cohesion = internal / (internal + external).
+7. **Run `check_dependencies` CLI** — this works without a graph and can detect layer violations.
+
+> Fallback completeness: ~60% — cannot compute transitive depth beyond what import parsing reveals; coupling metrics are approximate.
+
 ### Phase 2: SCORE — Calculate Health Score
 
 Compute a weighted health score (0-100):
@@ -104,7 +133,7 @@ For each problem found, generate a specific, actionable recommendation:
 
 ## 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 static analysis fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_relationships`, and `check_dependencies` MCP tools.
 
@@ -114,7 +143,7 @@ For each problem found, generate a specific, actionable recommendation:
 - All five structural metrics gathered (hubs, orphans, cycles, deep chains, cohesion)
 - Recommendations are specific and actionable (name files, suggest concrete fixes)
 - 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
 
@@ -141,8 +170,8 @@ Output:
 
 ## Gates
 
-- **No analysis without graph.** If no graph exists, stop and instruct to run `harness scan`.
-- **No guessing.** All metrics must come from graph queries, not heuristics.
+- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, DFS cycle detection, hub/orphan identification). Do not stop — produce the best analysis possible.
+- **Systematic analysis required.** All metrics must come from graph queries (with graph) or systematic import parsing (without graph). Do not guess — parse actual import statements.
 
 ## Escalation