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

--fix

--dead-code-only

--architecture-only

--dry-run

--ci

Process

Phase 1: CONTEXT -- Build Hotspot Map

1. Run hotspot detection via git log analysis:

   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

   • 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

--fix

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

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

• git log

  analysis -- Hotspot context for safety classification (inline command, no skill invocation needed)

• 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

Rationalizations to Reject

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.