@massu/core 0.1.2 → 0.4.0

package/commands/massu-dead-code.md

@@ -0,0 +1,131 @@
+---
+name: massu-dead-code
+description: Detect and remove dead code — orphaned modules, unused exports, unused dependencies
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-dead-code
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9 enforced.
+
+# Massu Dead Code: Automated Dead Code Detection & Removal
+
+## Objective
+
+Identify and safely remove dead code (orphaned modules, unused exports, unused dependencies, unreferenced files) using manual verification and codebase analysis.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Verify before removing** - grep for alternative import paths, barrel exports, dynamic imports
+- **Blast radius analysis** - every removal gets a grep check for references
+- **Build must pass after** - VR-BUILD + VR-TYPE mandatory after removals
+- **No false positives** - if unsure, KEEP the code
+- **FIX ALL ISSUES ENCOUNTERED (CR-9)** - if dead code reveals other issues, fix them too
+
+---
+
+## PROTOCOL
+
+### Step 1: Inventory Source Files
+
+```bash
+# List all source files
+find packages/core/src -name "*.ts" -not -path "*/__tests__/*" -not -path "*/node_modules/*" | sort
+
+# List all exports
+grep -rn "export " packages/core/src/ --include="*.ts" | grep -v "__tests__" | grep -v "node_modules"
+```
+
+### Step 2: Find Unused Exports
+
+For each exported function/class/constant, check if it's imported elsewhere:
+
+```bash
+# For each export, verify it has importers
+grep -rn "import.*[name]" packages/core/src/ --include="*.ts"
+```
+
+Cross-reference with `tools.ts` registrations - tool definitions and handlers are always "used" even if not directly imported elsewhere.
+
+### Step 3: Categorize Findings
+
+| Category | Source | Action |
+|----------|--------|--------|
+| ORPHANED_MODULE | No imports found | Verify not dynamically loaded, remove if truly orphaned |
+| UNUSED_EXPORT | No importers | Check if used via re-export, remove if dead |
+| UNUSED_DEPENDENCY | package.json | `npm uninstall` after verifying not dynamically required |
+| UNUSED_FILE | No references | Verify no require() or dynamic import(), remove if dead |
+| DEAD_FUNCTION | Never called | Verify not exported for external use, remove if dead |
+
+### Step 4: Verify Each Finding
+
+For EACH candidate removal:
+
+```bash
+# Check for all possible import patterns
+grep -rn "import.*[name]" packages/core/src/ --include="*.ts"
+grep -rn "require.*[name]" packages/core/src/ --include="*.ts"
+grep -rn "[name]" packages/core/src/tools.ts
+grep -rn "[name]" massu.config.yaml
+```
+
+If ANY reference found: KEEP (mark as false positive).
+If NO references found: candidate for removal.
+
+### Step 5: Present Removal Plan
+
+```markdown
+## Dead Code Removal Plan
+
+| # | File/Export | Category | References Found | Action | Risk |
+|---|------------|----------|-----------------|--------|------|
+| 1 | packages/core/src/X.ts | ORPHAN | 0 | REMOVE | Low |
+| 2 | lodash (dep) | UNUSED_DEP | 0 direct | UNINSTALL | Medium |
+```
+
+**WAIT FOR USER APPROVAL before executing removals.**
+
+### Step 6: Execute Removals
+
+After user approval:
+1. Remove files/exports/dependencies
+2. Run `npm run build` (VR-BUILD)
+3. Run `cd packages/core && npx tsc --noEmit` (VR-TYPE)
+4. Run `npm test` (VR-TEST)
+5. Run `bash scripts/massu-pattern-scanner.sh`
+
+### Step 7: Report
+
+```markdown
+## Dead Code Removal Report
+
+- **Files removed**: N
+- **Exports removed**: N
+- **Dependencies uninstalled**: N
+- **Build**: PASS
+- **Types**: PASS
+- **Tests**: PASS
+```
+
+---
+
+## QUICK COMMANDS
+
+```bash
+# Check for unused dependencies
+npx depcheck packages/core
+
+# Pattern scanner (verify no violations introduced)
+bash scripts/massu-pattern-scanner.sh
+
+# Full build verification
+npm run build
+
+# Full test suite
+npm test
+```
+
+---
+
+**Remember: Dead code removal is a cleanup operation. When in doubt, keep the code.**

package/commands/massu-debug.md

@@ -0,0 +1,484 @@
+---
+name: massu-debug
+description: Systematic debugging with hypothesis testing, root cause tracing, and verified fixes
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-debug
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
+
+# CS Debug: Systematic Debugging Protocol
+
+## Objective
+
+Trace errors to root cause systematically using hypothesis-driven investigation. Never guess — read the code, form hypotheses, test them, and verify fixes don't break anything else.
+
+**Usage**: `/massu-debug [error description, test name, or stack trace]`
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never guess the root cause** — read the code
+- **Never apply a fix without understanding WHY it works**
+- **Always verify the fix doesn't break other tests**
+- **Record each hypothesis and its outcome**
+- **FIX ALL ISSUES ENCOUNTERED (CR-9)** — if you find additional bugs while debugging, fix those too
+- **Proof > reasoning. Commands > assumptions.**
+- **No blind changes** — Understand before modifying
+
+---
+
+## ZERO-GAP AUDIT LOOP
+
+**Debugging does NOT complete until a SINGLE COMPLETE VERIFICATION finds ZERO remaining issues.**
+
+```
+DEBUG VERIFICATION LOOP:
+  1. Apply fix(es)
+  2. Run ALL verification checks for the fix
+  3. Count remaining issues found
+  4. IF issues > 0:
+       - Root cause not fully addressed
+       - Re-investigate and fix
+       - Return to Step 2
+  5. IF issues == 0:
+       - BUG FIXED AND VERIFIED
+```
+
+| Scenario | Action |
+|----------|--------|
+| Fix reveals new issue | Address it, re-verify ENTIRE fix |
+| Re-verify finds 1 issue | Fix it, re-verify ENTIRELY |
+| Re-verify finds 0 issues | **NOW** debug complete |
+
+**Partial verification is NOT valid. The fix must be fully verified in a SINGLE run.**
+
+---
+
+## DOMAIN-SPECIFIC PATTERN LOADING
+
+Based on the bug's domain, load relevant pattern sections from CLAUDE.md:
+
+| Domain | Section | Load When |
+|--------|---------|-----------|
+| Tool modules | Tool Registration Pattern | Tool registration/handler bugs |
+| Config | Config Access Pattern | Config parsing/access bugs |
+| Hooks | Hook stdin/stdout Pattern | Hook compilation/runtime bugs |
+| Build | Build & Test Commands | Build/compilation errors |
+| Database | SQLite Database Pattern | DB access bugs |
+
+---
+
+## STEP 0: REPRODUCE THE FAILURE (MANDATORY)
+
+Before investigating root cause, CONFIRM you can trigger the exact error.
+
+1. Identify the exact reproduction steps from user report
+2. Execute those steps (or equivalent verification commands)
+3. Capture the actual error output
+4. If you CANNOT reproduce: document that and investigate why
+
+WHY: Debugging without reproduction is guessing. Fixes without reproduction cannot be verified.
+
+### 0.2 Memory Check
+
+Before investigating, search for past failures related to this issue:
+
+- Check session state (`.claude/session-state/CURRENT.md`) for recent failures
+- Search codebase for similar error patterns
+- Check if this is a known issue with an established fix pattern
+
+If matches found: read the previous failures and avoid repeating failed approaches.
+
+---
+
+## STEP 1: SYMPTOM CAPTURE
+
+### 1.0 Error Category Matrix
+
+| Error Type | Likely Cause | First Check |
+|------------|--------------|-------------|
+| TypeError | Null/undefined value | Null guards in source |
+| Import error | Missing/wrong module path | ESM import path |
+| Config error | Missing config key | massu.config.yaml |
+| Build fail | TypeScript/esbuild error | tsc output |
+| Test fail | Assertion mismatch | Test expectations |
+| Tool not found | Missing registration | tools.ts wiring |
+| Hook timeout | Heavy dependency or infinite loop | Hook source |
+
+Record the exact error from `$ARGUMENTS`:
+
+```markdown
+### Symptom
+- **Error**: [exact error message or test name]
+- **Stack trace**: [if provided]
+- **Unexpected behavior**: [what happened vs what was expected]
+- **Reproducible**: [how to reproduce — test command, user action, etc.]
+```
+
+**If `$ARGUMENTS` is a test name:**
+```bash
+# Run the specific test to capture the full error
+npx vitest run [test-file-or-pattern] 2>&1
+```
+
+**If `$ARGUMENTS` is an error message:**
+```bash
+# Search for the error message in the codebase
+grep -rn "[error message]" packages/core/src/ --include="*.ts" --include="*.tsx"
+```
+
+**If `$ARGUMENTS` is vague or missing:**
+```
+OUTPUT: "Please provide one of: (1) exact error message, (2) failing test name, (3) stack trace, (4) steps to reproduce"
+ABORT
+```
+
+---
+
+## STEP 2: LOCATE ERROR SOURCE
+
+### From Stack Trace
+
+Parse the stack trace for the originating file and line number:
+
+```bash
+# Read the file at the error location with 50 lines of surrounding context
+# (25 lines before, 25 lines after the error line)
+```
+
+### From Error Message
+
+```bash
+# Grep for the error message string in source code
+grep -rn "[error message text]" packages/core/src/ --include="*.ts"
+# Also search in other package directories if applicable
+grep -rn "[error message text]" packages/ --include="*.ts" --include="*.tsx"
+```
+
+### From Test Failure
+
+```bash
+# Read the failing test to understand what it expects
+# Read the source module the test imports
+```
+
+```markdown
+### Error Location
+- **File**: [file path]
+- **Line**: [line number]
+- **Function**: [function name]
+- **Context**: [what this code is supposed to do]
+```
+
+---
+
+## STEP 3: TRACE CALL CHAIN
+
+Follow function calls upstream to understand the full execution path:
+
+```bash
+# Find who calls this function
+grep -rn "[function_name](" packages/core/src/ --include="*.ts"
+
+# Find what arguments are passed
+# Read each caller to understand the data flow
+```
+
+Build the call chain:
+
+```markdown
+### Call Chain
+```
+caller_1() [file_1.ts:NN]
+  → caller_2() [file_2.ts:NN]
+    → error_site() [file_3.ts:NN]  ← ERROR HERE
+```
+
+### Data Flow
+| Step | Variable | Value/Type | Source |
+|------|----------|------------|--------|
+| 1 | [var] | [value/type] | [where it comes from] |
+| 2 | [var] | [value/type] | [transformation] |
+| 3 | [var] | [unexpected value] | ← MISMATCH |
+```
+
+---
+
+## STEP 4: HYPOTHESIS FORMATION
+
+Based on code reading (NOT guessing), form up to 3 ranked hypotheses:
+
+```markdown
+### Hypotheses
+
+| # | Hypothesis | Confidence | Verification Method |
+|---|-----------|------------|---------------------|
+| H1 | [most likely cause based on code reading] | HIGH/MED/LOW | [specific command or check to verify] |
+| H2 | [alternative cause] | HIGH/MED/LOW | [specific command or check to verify] |
+| H3 | [least likely cause] | HIGH/MED/LOW | [specific command or check to verify] |
+```
+
+**Hypothesis quality requirements:**
+- Each hypothesis must be based on SPECIFIC code you read (cite file:line)
+- Each verification method must be a CONCRETE action (bash command, grep, read specific file)
+- "Something might be wrong" is NOT a valid hypothesis
+
+---
+
+## STEP 5: HYPOTHESIS TESTING
+
+Test hypotheses in order of confidence (highest first):
+
+```
+FOR EACH hypothesis (highest confidence first):
+  1. Execute the verification method
+  2. Record the result
+  3. IF confirmed → proceed to STEP 6
+  4. IF rejected → record why and test next hypothesis
+
+IF all hypotheses rejected:
+  - Expand search scope
+  - Read more files in the call chain
+  - Check for environmental factors (config, DB state, imports)
+  - Form new hypotheses and repeat from STEP 4
+```
+
+```markdown
+### Hypothesis Testing Results
+
+| # | Hypothesis | Verification | Result | Outcome |
+|---|-----------|-------------|--------|---------|
+| H1 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
+| H2 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
+| H3 | [hypothesis] | [what you did] | [what you found] | CONFIRMED / REJECTED |
+```
+
+---
+
+## STEP 6: ROOT CAUSE DOCUMENTATION
+
+Document the confirmed root cause before applying any fix:
+
+```markdown
+### Root Cause
+
+- **What**: [precise description of the bug]
+- **Why**: [why this bug exists — missing check, wrong assumption, stale code, etc.]
+- **Where**: [file(s) and line(s) affected]
+- **When introduced**: [if determinable — recent commit, original code, etc.]
+- **Blast radius**: [what else could be affected by this bug and by the fix]
+```
+
+---
+
+## STEP 7: APPLY FIX
+
+### Scope Check
+
+```
+IF fix touches > 5 files:
+  OUTPUT: "Fix scope is large ([N] files). Consider using /massu-create-plan for a structured approach."
+  ASK user whether to proceed or create a plan
+```
+
+### Apply the Fix
+
+1. **Apply the minimal correct fix** following CLAUDE.md patterns
+2. **Document what was changed and why**
+3. **Do NOT make unrelated improvements** — fix the bug only
+
+```markdown
+### Fix Applied
+
+| File | Change | Reason |
+|------|--------|--------|
+| [file:line] | [what was changed] | [why this fixes the root cause] |
+```
+
+---
+
+## STEP 8: VERIFY FIX
+
+### 8a. Targeted Test (if exists)
+
+```bash
+# Run the originally-failing test
+npx vitest run [test file] 2>&1
+```
+
+**Must pass.** If it still fails, go back to STEP 4 with new information.
+
+### 8b. Full Test Suite (VR-TEST)
+
+```bash
+npm test 2>&1
+# MUST exit 0, ALL tests pass
+```
+
+### 8c. Type Check (VR-TYPE)
+
+```bash
+cd packages/core && npx tsc --noEmit
+# MUST show 0 errors
+```
+
+### 8d. Pattern Scanner (VR-PATTERN)
+
+```bash
+bash scripts/massu-pattern-scanner.sh
+# MUST exit 0
+```
+
+### 8e. Hook Build (VR-HOOK-BUILD, if hooks modified)
+
+```bash
+cd packages/core && npm run build:hooks
+# MUST exit 0
+```
+
+**If ANY verification fails:**
+1. Investigate the new failure
+2. Determine if it was caused by the fix or is pre-existing
+3. Fix it (CR-9: fix ALL issues encountered)
+4. Re-run ALL verification from 8a
+
+---
+
+## STEP 9: RECORD FOR LEARNING
+
+Update session state with the debugging outcome:
+
+```bash
+# Update .claude/session-state/CURRENT.md with:
+# - Bug description
+# - Root cause
+# - Fix applied
+# - Lesson learned
+```
+
+```markdown
+### Learning Record
+- **Bug**: [one-line description]
+- **Root Cause**: [one-line explanation]
+- **Fix**: [one-line description of fix]
+- **Lesson**: [what to watch for in the future to prevent similar bugs]
+- **Pattern**: [if this reveals a recurring pattern, note it for potential pattern scanner rule]
+```
+
+---
+
+## ABORT CONDITIONS
+
+| Condition | Action |
+|-----------|--------|
+| Cannot reproduce the error | Report reproduction failure, ask for more details |
+| Root cause is in external dependency | Report finding, suggest dependency update or workaround |
+| Fix requires architectural changes | Abort, suggest `/massu-create-plan` |
+| All hypotheses rejected after 2 rounds | Report findings, escalate to user with all evidence gathered |
+
+---
+
+## MANDATORY PLAN DOCUMENT UPDATE (If Debug From Plan)
+
+**If debug session was part of a plan, update the plan document.**
+
+```markdown
+# IMPLEMENTATION STATUS
+
+**Plan**: [Plan Name]
+**Status**: DEBUG COMPLETE / PARTIAL
+**Last Updated**: [YYYY-MM-DD HH:MM]
+
+## Bug Fixes Applied
+
+| # | Bug Description | Status | Verification | Date |
+|---|-----------------|--------|--------------|------|
+| 1 | [Bug from plan] | FIXED | VR-BUILD: Pass | [date] |
+
+## Root Causes Identified
+
+| Bug | Root Cause | Prevention |
+|-----|-----------|------------|
+| [bug] | [cause] | [how to prevent] |
+```
+
+---
+
+## AUTO-LEARNING PROTOCOL (MANDATORY after every fix)
+
+After EVERY bug fix:
+
+### Step 1: Record the Pattern
+Update `.claude/session-state/CURRENT.md` with:
+- What was wrong (the incorrect pattern)
+- What fixed it (the correct pattern)
+- File(s) affected
+
+### Step 2: Add to Pattern Scanner (if grep-able)
+If the incorrect pattern can be detected by grep, consider adding it to `scripts/massu-pattern-scanner.sh`.
+
+### Step 3: Search Codebase-Wide (CR-9)
+```bash
+grep -rn "[bad_pattern]" packages/core/src/ --include="*.ts"
+```
+Fix ALL instances found, not just the one that was reported.
+
+---
+
+## COMPLETION REPORT
+
+```markdown
+## CS DEBUG COMPLETE
+
+### Symptom
+- **Error**: [original error]
+
+### Investigation
+- **Hypotheses tested**: [N]
+- **Confirmed hypothesis**: H[N] — [description]
+
+### Root Cause
+- **What**: [bug description]
+- **Why**: [why it happened]
+- **Where**: [file:line]
+
+### Fix Applied
+| File | Change |
+|------|--------|
+| [file] | [change description] |
+
+### Verification
+| Check | Status |
+|-------|--------|
+| Target test | PASS |
+| Full test suite | PASS ([N] tests) |
+| Type check | PASS (0 errors) |
+| Pattern scanner | PASS |
+
+### Learning
+- **Lesson**: [what was learned]
+- **Prevention**: [how to prevent in future]
+```
+
+---
+
+## START NOW
+
+1. Capture the symptom with exact error messages
+2. **Reproduce the failure** (Step 0 - MANDATORY)
+3. Categorize the error type using the matrix
+4. Load relevant pattern section from CLAUDE.md
+5. Check session-state for past related failures
+6. Trace the call chain
+7. Form hypotheses and test each
+8. Identify root cause with evidence
+9. Apply minimal fix following CLAUDE.md
+10. Verify fix with VR-* protocols
+11. Check for regressions (full test suite)
+12. **Execute AUTO-LEARNING PROTOCOL** (record, scan, search)
+13. Update session state
+14. Produce debug report
+
+**Remember: Evidence over assumptions. Prove, don't guess. Learn from every fix.**

package/commands/massu-deploy.md

@@ -0,0 +1,91 @@
+---
+name: massu-deploy
+description: Deploy the current project to Vercel
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+name: massu-deploy
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+# Massu Deploy: Autonomous Deployment Pipeline
+
+## Workflow Position
+
+```
+/massu-create-plan -> /massu-plan -> /massu-loop -> /massu-commit -> /massu-push -> /massu-deploy
+(CREATE)           (AUDIT)        (IMPLEMENT)   (COMMIT)        (PUSH)         (DEPLOY)
+```
+
+**This command deploys the website to Vercel production with pre-flight checks.**
+
+---
+
+## CRITICAL: THIS COMMAND DEPLOYS TO PRODUCTION
+
+**This command runs `scripts/massu-deploy.sh` which deploys to the Vercel project `massu`.**
+
+### Pre-Flight Checks (automatic)
+1. Branch check — must be on `main` with clean working tree
+2. Project target verification — must match projectId `prj_Io7AaGCM27cwRQerAj3BdihUur1Y`
+3. Local build verification — `npm run build` must succeed
+4. Deploy to production — `vercel --prod --yes`
+5. Smoke tests — GET `/` and `/docs` must return 200
+6. Rollback guidance — if smoke tests fail, prints rollback command
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- Never create a new Vercel project — always deploy to the existing `massu` project
+- Never deploy with uncommitted changes
+- Always verify build locally before deploying
+- Always run smoke tests after deployment
+- Use `printf` (not `echo`) for any env var operations
+
+---
+
+## START NOW
+
+### Step 1: Dry Run First
+
+Run the deploy script in dry-run mode to verify pre-flight checks:
+
+```bash
+bash scripts/massu-deploy.sh --dry-run
+```
+
+If dry-run passes, ask user for approval:
+
+```
+===============================================================================
+APPROVAL REQUIRED: DEPLOY TO PRODUCTION
+===============================================================================
+
+Pre-flight checks passed. Ready to deploy.
+
+Target: Vercel project "massu" (prj_Io7AaGCM27cwRQerAj3BdihUur1Y)
+Branch: [current branch]
+
+OPTIONS:
+  - Type "approve" or "deploy" to deploy to production
+  - Type "abort" to cancel
+
+===============================================================================
+```
+
+### Step 2: Deploy
+
+After approval, run the full deploy:
+
+```bash
+bash scripts/massu-deploy.sh
+```
+
+### Step 3: Report Results
+
+Report the deployment URL and smoke test results.
+
+If smoke tests fail, provide the rollback command:
+```bash
+cd website && npx vercel rollback --yes
+```