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

Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

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

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.