@sugar-crash-studios/vibe-forge 0.4.0

package/docs/cleanup-workflow.md

@@ -0,0 +1,329 @@
+# Vibe-Code Lifecycle: Build → Test → Cleanup → Ship
+
+**Version:** 1.0.0  
+**Last Updated:** 2026-02-04  
+**Author:** SpasticPalate
+
+---
+
+## Overview
+
+Vibe coding with AI produces working code fast, but accumulates three categories of technical debt:
+
+| Debt Type | Symptom | Tool |
+|-----------|---------|------|
+| **Duplication** | Same logic copy-pasted across files | [jscpd](https://jscpd.dev) |
+| **Dead Code** | Unused files, exports, dependencies | [Knip](https://knip.dev) |
+| **Pattern Inconsistency** | Mixed syntax for equivalent operations | [ast-grep](https://ast-grep.github.io) |
+
+This workflow inserts a structured cleanup gate between "it works" and "it ships."
+
+---
+
+## The Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    VIBE-CODE LIFECYCLE                   │
+│                                                         │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐            │
+│  │  1. VIBE  │──▶│ 2. TEST  │──▶│3. CLEANUP│            │
+│  │  (build)  │   │ (verify) │   │ (refine) │            │
+│  └──────────┘   └──────────┘   └────┬─────┘            │
+│                                     │                   │
+│                                     ▼                   │
+│                 ┌──────────┐   ┌──────────┐             │
+│                 │ 5. DEPLOY│◀──│ 4. TEST  │             │
+│                 │  (ship)  │   │(confirm) │             │
+│                 └──────────┘   └──────────┘             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Phase 1: VIBE (Build)
+
+**Goal:** Get working features fast. Don't overthink structure.
+
+This is the creative phase. Use Claude, Cursor, Copilot — whatever gets features working. Accept that the output will have rough edges. That's what the cleanup phase is for.
+
+**Rules during vibe phase:**
+- Commit often to a feature branch
+- Don't refactor while building — that's a different phase
+- Capture TODO comments for things you know are messy
+- Focus on behavior, not beauty
+
+**Exit criteria:** Feature works as intended.
+
+### Phase 2: TEST (Verify)
+
+**Goal:** Confirm the vibe-coded feature actually works.
+
+Run your test suite. If tests don't exist yet, this is Crucible's domain — write them now before touching the code further. You need a passing baseline before cleanup or you won't know if cleanup broke something.
+
+```bash
+npm test                    # Unit/integration tests
+npm run test:e2e            # E2E if applicable
+```
+
+**Exit criteria:** All tests pass. You have a green baseline.
+
+### Phase 3: CLEANUP (Refine)
+
+**Goal:** Eliminate the three categories of vibe-coding debt.
+
+This is the core of the workflow. Run the three tools in order — each one's output informs the next.
+
+#### Step 3a: Detect Duplicates (jscpd)
+
+**Why first:** Duplication is the most common vibe-coding sin. Fixing it first reduces the surface area for the other tools.
+
+```bash
+npm run cleanup:duplicates
+# or directly:
+npx jscpd ./src --min-tokens 50 --reporters console --format "typescript,javascript,tsx,jsx"
+```
+
+**What to do with results:**
+- **Exact clones (>30 lines):** Extract to a shared utility/hook/component
+- **Near-clones (similar structure, different details):** Generalize with parameters
+- **Small clones (<10 lines):** Probably fine — not everything needs DRYing
+
+**Judgment call:** Don't extract something into a shared utility if it's only used in 2 places and the abstraction would be harder to understand than the duplication. The goal is maintainability, not minimum line count.
+
+#### Step 3b: Remove Dead Code (Knip)
+
+**Why second:** After extracting duplicates into shared code, some of the original files/exports become unused. Knip catches that, plus all the other dead code from iterative prompting.
+
+```bash
+npm run cleanup:deadcode
+# or directly:
+npx knip
+```
+
+**What Knip finds:**
+- Unused files (whole files nothing imports)
+- Unused exports (exported but never imported)
+- Unused dependencies (in package.json but never imported)
+- Unused dev dependencies
+
+**What to do with results:**
+- **Unused files:** Delete them. If you need them later, they're in git.
+- **Unused exports:** Remove the `export` keyword, or delete if the function itself is unused
+- **Unused deps:** `npm uninstall <package>`
+- **False positives:** Add to `knip.json` ignore list (dynamic imports, entry points Knip doesn't know about)
+
+#### Step 3c: Normalize Patterns (ast-grep)
+
+**Why last:** With duplicates extracted and dead code removed, you're working with a leaner codebase. Now standardize the patterns.
+
+```bash
+npm run cleanup:patterns
+# or directly:
+npx @ast-grep/cli scan --config .ast-grep/sgconfig.yml
+```
+
+**Common patterns to normalize (React/TS projects):**
+
+```yaml
+# .ast-grep/rules/optional-chaining.yml
+id: use-optional-chaining
+language: typescript
+rule:
+  pattern: $A && $A.$B
+fix: $A?.$B
+message: "Use optional chaining instead of && guard"
+severity: warning
+
+# .ast-grep/rules/no-console-log.yml  
+id: no-console-log
+language: typescript
+rule:
+  pattern: console.log($$$ARGS)
+message: "Remove console.log before shipping"
+severity: warning
+
+# .ast-grep/rules/prefer-const.yml
+id: prefer-const
+language: typescript
+rule:
+  pattern: let $VAR = $INIT
+constraints:
+  # Only when variable is never reassigned
+message: "Use const for variables that are never reassigned"
+severity: hint
+```
+
+**Interactive rewrite mode** (review each change):
+```bash
+npx @ast-grep/cli scan --config .ast-grep/sgconfig.yml --interactive
+```
+
+### Phase 4: TEST (Confirm)
+
+**Goal:** Verify cleanup didn't break anything.
+
+```bash
+npm test                    # Same tests as Phase 2
+npm run test:e2e            # Same E2E
+npm run build               # Verify the build still works
+```
+
+If anything fails, the cleanup introduced a regression. Fix it before proceeding.
+
+**Exit criteria:** All tests pass again. Build succeeds.
+
+### Phase 5: DEPLOY (Ship)
+
+**Goal:** Push clean, tested code.
+
+```bash
+git add -A
+git commit -m "cleanup: deduplicate, remove dead code, normalize patterns"
+git push
+```
+
+Then follow your normal deploy process (PR, CI, Dockhand webhook, etc.).
+
+---
+
+## Running the Full Cleanup
+
+One command to run all three tools in sequence:
+
+```bash
+npm run cleanup
+```
+
+This runs the cleanup script which executes all three tools, collects results, and produces a summary. See the `scripts/cleanup.sh` section below for implementation.
+
+---
+
+## Project Setup
+
+### Install Tools
+
+```bash
+# Global (available across all projects)
+npm install -g jscpd @ast-grep/cli
+
+# Per-project (recommended for CI)
+npm install -D jscpd @ast-grep/cli knip
+```
+
+### package.json Scripts
+
+Add to any project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "cleanup": "node scripts/cleanup.mjs",
+    "cleanup:duplicates": "jscpd ./src --min-tokens 50 --reporters console",
+    "cleanup:deadcode": "knip",
+    "cleanup:patterns": "sg scan",
+    "cleanup:fix": "sg scan --interactive"
+  }
+}
+```
+
+### Configuration Files
+
+Drop these into any project root. See the `_cleanup-kit/` directory for ready-to-copy templates.
+
+---
+
+## Integration with Vibe Forge Agents
+
+### Crucible (Testing)
+
+Crucible owns Phases 2 and 4. The cleanup phase sits between Crucible's two test runs. Crucible should be aware that cleanup may change file structure (extracted utilities, deleted files) and should re-run the full suite, not just affected tests.
+
+### Sentinel (Code Review)
+
+Sentinel can use cleanup tool output as review signals:
+- **jscpd clones remaining after cleanup** = reviewer should question why
+- **Knip unused exports after cleanup** = missed cleanup items  
+- **ast-grep warnings after cleanup** = pattern violations to flag
+
+### Aegis (Security)
+
+ast-grep rules can include security patterns. Aegis-authored rules live alongside pattern normalization rules:
+
+```yaml
+# .ast-grep/rules/aegis-no-eval.yml
+id: no-eval
+language: typescript
+rule:
+  pattern: eval($$$ARGS)
+message: "eval() is a security risk. Use safer alternatives."
+severity: error
+```
+
+### New: Refinery Agent (Optional)
+
+If you want to formalize the cleanup phase as a Vibe Forge agent, a "Refinery" agent would own Phase 3 exclusively. Its personality: methodical, numbers-driven, focused on codebase hygiene rather than features. It receives code after Crucible's first pass and hands back cleaned code for Crucible's second pass.
+
+---
+
+## Metrics and Thresholds
+
+Track these over time to measure vibe-coding debt accumulation:
+
+| Metric | Source | Healthy | Warning | Action Required |
+|--------|--------|---------|---------|-----------------|
+| Clone percentage | jscpd | <3% | 3-5% | >5% |
+| Unused files | Knip | 0 | 1-3 | >3 |
+| Unused dependencies | Knip | 0 | 1-2 | >2 |
+| Unused exports | Knip | <5 | 5-15 | >15 |
+| Pattern violations | ast-grep | 0 | 1-5 | >5 |
+
+### CI Gate (Optional)
+
+Add to your GitHub Actions / CI pipeline:
+
+```yaml
+cleanup-check:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+    - run: npm ci
+    - run: npx jscpd ./src --threshold 5 --reporters console
+    - run: npx knip --no-exit-code  # Report only, don't fail yet
+    - run: npx @ast-grep/cli scan   # Fail on error-severity rules
+```
+
+---
+
+## When to Skip Cleanup
+
+Not every commit needs the full cycle:
+
+- **Hotfix:** Skip cleanup, go straight from vibe → test → deploy. Come back for cleanup later.
+- **Prototype/spike:** Don't cleanup throwaway code. Mark the branch as experimental.
+- **Config-only changes:** Compose files, env vars, nginx configs — static analysis tools won't help.
+- **Documentation:** No code to clean up.
+
+Apply cleanup when you're shipping a feature or before merging to main.
+
+---
+
+## FAQ
+
+**Q: How long does cleanup take?**  
+A: 5-15 minutes for a typical feature. The tools run in seconds; the human decisions (what to extract, what to delete) take the time.
+
+**Q: Should I cleanup every commit?**  
+A: No. Cleanup per feature, not per commit. Batch your vibe-coding commits, then cleanup once before the PR.
+
+**Q: What if jscpd finds clones I want to keep?**  
+A: Add them to `.jscpd.json` ignore patterns. Some duplication is intentional (test fixtures, similar-but-different components).
+
+**Q: What if Knip says something is unused but it's actually used dynamically?**  
+A: Add it to `knip.json` entry or ignore patterns. Common with dynamic imports, plugin systems, and barrel files.
+
+**Q: Can I use ast-grep to auto-fix everything?**  
+A: You can, but use `--interactive` mode to review each change. Automated rewrites without review are just a different flavor of vibe coding.
+
+---
+
+*This workflow is designed for React/TypeScript projects but the tools and process apply to any JavaScript/TypeScript codebase.*