@massu/core 0.1.2 → 0.4.0

package/commands/massu-cleanup.md

@@ -0,0 +1,315 @@
+---
+name: massu-cleanup
+description: Dead code removal — unused imports, orphaned files, dead exports, and stale references
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-cleanup
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
+
+# CS Cleanup: Dead Code Removal
+
+## Objective
+
+Identify and remove dead code across the codebase: unused imports, orphaned files, dead exports, and stale references. Changes are applied by category with verification after each batch. If any removal causes test regressions, the batch is reverted and investigated.
+
+**Usage**: `/massu-cleanup` (full scan) or `/massu-cleanup [area]` (focused: imports, exports, files, deps)
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never delete without verifying zero references** — grep before every removal
+- **Run tests after each category** — a passing baseline MUST be maintained
+- **Revert on regression** — if a batch breaks tests, revert before continuing
+- **FIX ALL ISSUES ENCOUNTERED (CR-9)** — pre-existing issues found during cleanup MUST be fixed
+- **No config or public API removals** — scope only to internal dead code
+- **Proof > reasoning. Commands > assumptions.**
+
+---
+
+## SCOPE GUARD (MANDATORY)
+
+**This command is for INTERNAL dead code only. If ANY of these are true, ABORT:**
+
+| Condition | Why It's Too Big | Alternative |
+|-----------|-----------------|-------------|
+| Removal touches exported public API | Needs blast radius plan | `/massu-create-plan` |
+| Removes MCP tool name | Affects all consumers | `/massu-create-plan` |
+| Removes config interface fields | Affects all config users | `/massu-create-plan` |
+| Touches > 20 files | Needs structured plan | `/massu-create-plan` |
+
+---
+
+## STEP 1: BASELINE SNAPSHOT
+
+Capture the behavioral baseline BEFORE making any changes:
+
+### 1a. Test Baseline
+
+```bash
+npm test 2>&1
+```
+
+Record:
+```markdown
+### Test Baseline
+| Metric | Value |
+|--------|-------|
+| Total tests | [N] |
+| Passing | [N] |
+| Failing | [N] |
+```
+
+### 1b. Type Check Baseline
+
+```bash
+cd packages/core && npx tsc --noEmit 2>&1
+```
+
+Record:
+```markdown
+### Type Check Baseline
+| Metric | Value |
+|--------|-------|
+| Type errors | [N] |
+```
+
+**This baseline is the behavioral contract. After cleanup:**
+- Test count MUST be >= baseline
+- Passing count MUST be >= baseline
+- Type error count MUST be <= baseline
+
+---
+
+## STEP 2: DISCOVERY
+
+Scan all categories in parallel. Do NOT remove anything yet.
+
+### 2a. Unused Imports
+
+```bash
+# TypeScript unused imports (ts error 6133)
+cd packages/core && npx tsc --noEmit 2>&1 | grep "is declared but"
+
+# ESLint-style: imports never referenced in file body
+grep -rn "^import" packages/core/src/ --include="*.ts" | head -50
+```
+
+### 2b. Dead Exports
+
+```bash
+# Exported symbols with zero external references
+grep -rn "^export " packages/core/src/ --include="*.ts" | grep -v "__tests__" | while IFS=: read file line content; do
+  name=$(echo "$content" | grep -oP '(?<=export (function|const|class|type|interface|enum) )\w+' | head -1)
+  if [ -n "$name" ]; then
+    count=$(grep -rn "$name" packages/core/src/ --include="*.ts" | grep -v "^$file:" | grep -v "__tests__" | wc -l)
+    if [ "$count" -eq 0 ]; then
+      echo "DEAD EXPORT: $name in $file"
+    fi
+  fi
+done
+```
+
+### 2c. Orphaned Files
+
+```bash
+# Source files not imported anywhere
+for f in packages/core/src/*.ts; do
+  base=$(basename "$f" .ts)
+  # Skip entry points and test files
+  if [[ "$base" == "server" || "$base" == "index" || "$f" == *"__tests__"* ]]; then
+    continue
+  fi
+  count=$(grep -rn "from.*['\"]\./${base}" packages/core/src/ --include="*.ts" | grep -v "__tests__" | wc -l)
+  if [ "$count" -eq 0 ]; then
+    echo "POSSIBLY ORPHANED: $f"
+  fi
+done
+```
+
+### 2d. Unused Dependencies
+
+```bash
+# List all dependencies
+cat packages/core/package.json | grep -A 50 '"dependencies"'
+
+# Check each dependency usage
+grep -rn "from.*'better-sqlite3'\|require.*better-sqlite3" packages/core/src/ --include="*.ts" | wc -l
+grep -rn "from.*'yaml'\|require.*yaml" packages/core/src/ --include="*.ts" | wc -l
+```
+
+### 2e. TODO/FIXME/HACK Comments
+
+```bash
+# Enumerate all stale markers — informational only (no auto-removal)
+grep -rn "TODO\|FIXME\|HACK\|XXX\|DEPRECATED" packages/core/src/ --include="*.ts" | grep -v "__tests__"
+```
+
+---
+
+## STEP 3: CLASSIFICATION
+
+For every candidate found in Step 2, classify each as:
+
+```markdown
+### Cleanup Inventory
+
+| Category | Item | File | References | Action | Reason |
+|----------|------|------|-----------|--------|--------|
+| Unused import | [name] | [file] | 0 | REMOVE | Never used after import |
+| Dead export | [name] | [file] | 0 | INVESTIGATE → REMOVE/KEEP | [context] |
+| Orphaned file | [file] | - | 0 | INVESTIGATE → REMOVE/KEEP | [context] |
+| Stale dep | [pkg] | package.json | [N] | REMOVE/KEEP | [reason] |
+```
+
+**Rules:**
+- Zero INVESTIGATE items allowed before implementation starts
+- Every REMOVE item must be verified with negative grep
+- Every KEEP item must have a documented reason
+
+---
+
+## STEP 4: CLEANUP
+
+Apply removals by category. Maximum 1 category per batch.
+
+```
+CLEANUP LOOP:
+  FOR EACH category in [imports, exports, files, deps]:
+    1. Select all REMOVE items in this category
+    2. Apply removals
+    3. Run type check:
+         cd packages/core && npx tsc --noEmit 2>&1
+    4. Run tests:
+         npm test 2>&1
+    5. Compare against baseline:
+         - Type errors must be <= baseline
+         - Passing tests must be >= baseline
+    6. IF regression detected:
+         - REVERT the entire category batch
+         - Document failure reason
+         - Skip this category
+    7. IF clean:
+         - Record category as successful
+         - Proceed to next category
+```
+
+### Category Record Template
+
+```markdown
+### Category: [imports/exports/files/deps]
+
+| Item | File | Action | Verification |
+|------|------|--------|-------------|
+| [item] | [file] | REMOVED | grep returned 0 |
+
+| Check | Before | After | Status |
+|-------|--------|-------|--------|
+| Type errors | [N] | [N] | EQUIVALENT/IMPROVED |
+| Tests passing | [N] | [N] | EQUIVALENT/IMPROVED |
+```
+
+---
+
+## STEP 5: NEGATIVE VERIFICATION (VR-NEGATIVE)
+
+For every removed item, confirm it is gone:
+
+```bash
+# Unused import removed
+grep -rn "[import_name]" packages/core/src/ --include="*.ts"
+# MUST return 0 matches (or only in unrelated contexts)
+
+# Dead export removed
+grep -rn "export.*[export_name]" packages/core/src/ --include="*.ts"
+# MUST return 0 matches
+
+# Orphaned file removed
+ls [removed_file_path]
+# MUST fail (file should not exist)
+```
+
+```markdown
+### Negative Verification
+
+| Item | Grep Result | Status |
+|------|-------------|--------|
+| [name] | 0 matches | CLEAN |
+| [file] | File not found | CLEAN |
+```
+
+**If ANY stale reference remains:** Fix it before proceeding.
+
+---
+
+## STEP 6: FINAL VERIFICATION
+
+### Gate 1: Pattern Scanner (VR-PATTERN)
+```bash
+bash scripts/massu-pattern-scanner.sh
+# MUST exit 0
+```
+
+### Gate 2: Type Check (VR-TYPE)
+```bash
+cd packages/core && npx tsc --noEmit
+# MUST show 0 errors (or <= baseline)
+```
+
+### Gate 3: All Tests (VR-TEST)
+```bash
+npm test
+# MUST exit 0, all tests pass
+```
+
+### Gate 4: Hook Build (VR-HOOK-BUILD)
+```bash
+cd packages/core && npm run build:hooks
+# MUST exit 0
+```
+
+---
+
+## COMPLETION REPORT
+
+```markdown
+## CS CLEANUP COMPLETE
+
+### Scope
+- **Files modified**: [N]
+- **Files deleted**: [N]
+- **Categories processed**: [N]
+
+### Items Removed
+| Category | Count | Examples |
+|----------|-------|---------|
+| Unused imports | [N] | [examples] |
+| Dead exports | [N] | [examples] |
+| Orphaned files | [N] | [names] |
+| Unused dependencies | [N] | [names] |
+
+### Items Kept (with reason)
+| Item | Reason |
+|------|--------|
+| [item] | [reason — e.g., used in tests, reserved for upcoming feature] |
+
+### Behavioral Equivalence
+| Metric | Before | After | Delta | Status |
+|--------|--------|-------|-------|--------|
+| Tests passing | [N] | [N] | [0] | EQUIVALENT |
+| Type errors | [N] | [N] | [0] | EQUIVALENT/IMPROVED |
+
+### Verification Gates
+| Gate | Status |
+|------|--------|
+| Pattern Scanner | PASS |
+| Type Safety | PASS |
+| Tests | PASS ([N] passed) |
+| Hook Build | PASS |
+| Negative Verification | PASS (0 stale references) |
+
+### Next Steps
+- Review changes: `git diff`
+- Commit: `/massu-commit`
+```