@massu/core 0.5.0 → 0.6.0

package/commands/massu-dead-code.md

@@ -1,17 +1,17 @@
 ---
 name: massu-dead-code
-description: Detect and remove dead code — orphaned modules, unused exports, unused dependencies
+description: "When user asks about unused code, says 'find dead code', 'clean up unused', or wants to reduce codebase size by removing unreferenced exports"
 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.
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
 
 # 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.
+Identify and safely remove dead code (orphaned components, unused exports, unused dependencies, unreferenced files) using a combination of knip, audit-dead-code.sh, and manual verification.
 
 ---
 
@@ -27,36 +27,31 @@ Identify and safely remove dead code (orphaned modules, unused exports, unused d
 
 ## PROTOCOL
 
-### Step 1: Inventory Source Files
+### Step 1: Run knip
 
 ```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"
+npm run knip 2>&1 | tee /tmp/knip-output.txt
 ```
 
-### Step 2: Find Unused Exports
+Capture counts: unused files, unused dependencies, unused exports, unused types.
 
-For each exported function/class/constant, check if it's imported elsewhere:
+### Step 2: Run audit-dead-code.sh
 
 ```bash
-# For each export, verify it has importers
-grep -rn "import.*[name]" packages/core/src/ --include="*.ts"
+./scripts/audit-dead-code.sh 2>&1 | tee /tmp/dead-code-audit.txt
 ```
 
-Cross-reference with `tools.ts` registrations - tool definitions and handlers are always "used" even if not directly imported elsewhere.
+Cross-reference with knip findings.
 
 ### 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 |
+| ORPHANED_COMPONENT | knip + audit | Verify no dynamic imports, remove if truly orphaned |
+| UNUSED_EXPORT | knip | Check if used via barrel re-export, remove if dead |
+| UNUSED_DEPENDENCY | knip | `npm uninstall` after verifying not dynamically required |
+| UNUSED_FILE | knip | Verify no require() or dynamic import(), remove if dead |
+| DEAD_PROCEDURE | audit | Verify not called from any UI, remove if dead |
 
 ### Step 4: Verify Each Finding
 
@@ -64,10 +59,10 @@ 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
+grep -rn "import.*[name]" src/ --include="*.ts" --include="*.tsx"
+grep -rn "require.*[name]" src/ --include="*.ts" --include="*.tsx"
+grep -rn "dynamic.*import.*[name]" src/ --include="*.ts" --include="*.tsx"
+grep -rn "<[ComponentName]" src/ --include="*.tsx"
 ```
 
 If ANY reference found: KEEP (mark as false positive).
@@ -80,7 +75,7 @@ If NO references found: candidate for removal.
 
 | # | File/Export | Category | References Found | Action | Risk |
 |---|------------|----------|-----------------|--------|------|
-| 1 | packages/core/src/X.ts | ORPHAN | 0 | REMOVE | Low |
+| 1 | src/components/X.tsx | ORPHAN | 0 | REMOVE | Low |
 | 2 | lodash (dep) | UNUSED_DEP | 0 direct | UNINSTALL | Medium |
 ```
 
@@ -91,9 +86,9 @@ If NO references found: candidate for removal.
 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)
+3. Run `npx tsc --noEmit` (VR-TYPE)
 4. Run `npm test` (VR-TEST)
-5. Run `bash scripts/massu-pattern-scanner.sh`
+5. Run `./scripts/pattern-scanner.sh`
 
 ### Step 7: Report
 
@@ -113,17 +108,17 @@ After user approval:
 ## QUICK COMMANDS
 
 ```bash
-# Check for unused dependencies
-npx depcheck packages/core
+# Full knip report
+npm run knip
 
-# Pattern scanner (verify no violations introduced)
-bash scripts/massu-pattern-scanner.sh
+# Strict mode (fails on any issue)
+npm run knip:strict
 
-# Full build verification
-npm run build
+# Existing dead code audit
+./scripts/audit-dead-code.sh
 
-# Full test suite
-npm test
+# Pattern scanner (verify no violations introduced)
+./scripts/pattern-scanner.sh
 ```
 
 ---

package/commands/massu-debug/references/auto-learning.md

@@ -0,0 +1,61 @@
+# Auto-Learning Protocol
+
+**MANDATORY after every bug fix.** The system MUST automatically learn from every fix. This is NOT optional.
+
+---
+
+## Step 1: Ingest Failure + Fix into Memory
+
+```
+Use mcp__massu-codegraph__massu_memory_ingest with:
+- type: "bugfix"
+- description: "[What was wrong] -> [What fixed it]"
+- files: [list of files changed]
+- importance: 5 (if caused data exposure or production error), 3 (if caused build/type error), 2 (if cosmetic)
+```
+
+---
+
+## Step 2: Record Correct vs Incorrect Pattern
+
+Update `memory/MEMORY.md` with:
+
+```markdown
+## [Category] Pattern (discovered [date])
+- WRONG: [the incorrect pattern that caused the bug]
+- CORRECT: [the pattern that fixed it]
+- File(s): [where it was found]
+```
+
+---
+
+## Step 3: Add to Pattern Scanner (if grep-able)
+
+If the incorrect pattern can be detected by grep, add it to `scripts/pattern-scanner.sh`:
+
+```bash
+# Check for [description of bad pattern]
+BAD_PATTERN=$(grep -rn "[bad_pattern]" src/ --include="*.ts" --include="*.tsx" | grep -v node_modules | wc -l)
+if [ "$BAD_PATTERN" -gt 0 ]; then
+  echo "[FAIL] [description]"
+  CRITICAL=$((CRITICAL + 1))
+fi
+```
+
+---
+
+## Step 4: Search for Same Pattern Codebase-Wide (CR-9)
+
+```bash
+grep -rn "[bad_pattern]" src/ --include="*.ts" --include="*.tsx"
+```
+
+Fix ALL instances found, not just the one that was reported.
+
+---
+
+## When to Skip
+
+- **NEVER** skip Steps 1-2 (memory recording)
+- Skip Step 3 only if the pattern cannot be expressed as a grep pattern
+- **NEVER** skip Step 4 (codebase-wide search)

package/commands/massu-debug/references/codegraph-tracing.md

@@ -0,0 +1,80 @@
+# Codegraph-Enhanced Tracing
+
+How to use codegraph MCP tools for dependency tracing and understanding the full context before debugging.
+
+---
+
+## Tools and When to Use Them
+
+| Tool | Purpose | Use When |
+|------|---------|----------|
+| `mcp__codegraph__codegraph_callers` | Who calls the buggy function? | Find all entry points that could trigger the bug |
+| `mcp__codegraph__codegraph_callees` | What does the buggy function call? | Find all dependencies that might be the real source |
+| `mcp__codegraph__codegraph_context` | Full context (CRs, patterns, schema) for a file | Get CLAUDE.md-aware context for the file being debugged |
+| `mcp__massu-codegraph__massu_context` | Massu-specific context for the affected file | Schema alerts, pattern warnings specific to this file |
+| `mcp__codegraph__codegraph_impact` | What would be affected by changes to this file? | Before making a fix, understand blast radius |
+| `mcp__codegraph__codegraph_search` | Search for symbols/patterns across the codebase | When you need to find all instances of a pattern |
+
+---
+
+## Recommended Workflow
+
+### Step 1: Identify the Buggy File/Function
+
+From the error trace or user report, identify the file and function where the error originates.
+
+### Step 2: Get Full Context
+
+```
+mcp__codegraph__codegraph_context(file: "src/server/api/routers/[router].ts")
+```
+
+This returns:
+- Applicable CRs (Canonical Rules) for this file
+- Known patterns that apply
+- Schema information if database-related
+- Import dependencies
+
+### Step 3: Trace Callers (Upstream)
+
+```
+mcp__codegraph__codegraph_callers(symbol: "procedureName", file: "src/server/api/routers/[router].ts")
+```
+
+This reveals:
+- Which UI components call this procedure
+- Which other routers depend on it
+- Entry points from API routes or cron jobs
+
+### Step 4: Trace Callees (Downstream)
+
+```
+mcp__codegraph__codegraph_callees(symbol: "procedureName", file: "src/server/api/routers/[router].ts")
+```
+
+This reveals:
+- What database operations the function performs
+- What utility functions it depends on
+- External service calls
+
+### Step 5: Check Impact Before Fixing
+
+```
+mcp__codegraph__codegraph_impact(file: "src/server/api/routers/[router].ts")
+```
+
+Before applying a fix, understand what else could break.
+
+---
+
+## Key Principle
+
+**Use these tools BEFORE forming hypotheses.** Understanding the full call graph prevents fixing symptoms instead of root causes.
+
+A bug in the UI might actually originate in:
+- The tRPC router (wrong query)
+- The database layer (missing RLS)
+- A utility function (incorrect transformation)
+- The middleware (wrong routing)
+
+Tracing callers and callees reveals the true source.

package/commands/massu-debug/references/common-shortcuts.md

@@ -0,0 +1,98 @@
+# Common Debugging Shortcuts
+
+Quick diagnosis patterns for common error types.
+
+---
+
+## Quick Error Checks
+
+```bash
+# All console errors in components
+grep -rn "console.error" src/components/
+
+# All try/catch blocks
+grep -rn "catch\s*(" src/server/
+
+# All error boundaries
+grep -rn "ErrorBoundary\|error.tsx" src/
+
+# Recent server logs (Supabase)
+# Use mcp__supabase__[ENV]__get_logs for each environment
+```
+
+---
+
+## Quick Pattern Violations
+
+```bash
+# Run full pattern check
+./scripts/pattern-scanner.sh
+
+# Quick manual checks
+grep -rn "ctx.prisma" src/server/ | wc -l      # Should be 0
+grep -rn "ctx.db.users" src/ | wc -l           # Should be 0
+grep -rn "include:" src/server/ | wc -l        # Should be 0
+grep -rn "publicProcedure.mutation" src/ | wc -l  # Should be 0
+```
+
+---
+
+## 500 Internal Server Error
+
+1. Check server logs: `mcp__supabase__[ENV]__get_logs`
+2. VR-SCHEMA-PRE: Verify table/column existence
+3. Check for `ctx.prisma` (should be `ctx.db`)
+4. Check for `include:` (should use 3-step queries)
+5. Check for `ctx.db.users` (should be `ctx.db.user_profiles`)
+6. Check BigInt serialization (use `Number()` on return)
+7. Check Decimal serialization (use `serializeUnifiedProduct()`)
+
+---
+
+## 403 Forbidden / 401 Unauthorized
+
+1. Check RLS policies: `scripts/check-rls-policies.sh [table]`
+2. Verify service_role grants exist
+3. Check `protectedProcedure` vs `publicProcedure`
+4. Check middleware routing in `middleware.ts`
+5. Check portal_access.portal_type alignment
+6. Verify session token validity
+
+---
+
+## React Crash / TypeError
+
+1. Check for `value=""` in any `<Select>` or `<SelectItem>` (use `__none__`)
+2. Check null guards on nullable string methods: `(status || "pending").replace()`
+3. Check Suspense boundaries for `use(params)` pages
+4. Check for `onSuccess` in `useQuery` options (removed in React Query v5)
+5. Check useCallback dependency stability (use specific function refs, not parent objects)
+
+---
+
+## Build Failures
+
+1. Check for static jsdom/cheerio imports (must use `await import()`)
+2. Check client/server boundary violations (`@/lib/db` in client components)
+3. Check `next-intl` setup (plugin + request.ts + Provider)
+4. Run `NODE_OPTIONS="--max-old-space-size=8192" npx tsc --noEmit`
+5. Check for circular dependencies in import chains
+
+---
+
+## "No Data" / Empty Results
+
+1. VR-DATA: Query actual config values and compare keys to code expectations
+2. Check RLS policies allow the operation for the current user role
+3. Check grants exist for service_role
+4. Verify table exists in the target environment (schema drift)
+5. Check if `findManyGeneric` has any hidden default limit
+
+---
+
+## Realtime / Subscription Failures
+
+1. Check query key format: `queryKey: [['router', 'procedure']]` (double brackets)
+2. Verify RLS policies exist for the table
+3. Check realtime is enabled for the table in Supabase dashboard
+4. Verify the subscription channel name matches

package/commands/massu-debug/references/investigation-phases.md

@@ -0,0 +1,294 @@
+# Investigation Phases (0-7)
+
+Full detail for each investigation phase in the massu-debug protocol.
+
+---
+
+## PHASE 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.1 Check Memory for Related Failures
+
+Before investigating, check if this error has been seen before:
+
+Use `mcp__massu-codegraph__massu_memory_failures` with keywords from
+the error message.
+Use `mcp__massu-codegraph__massu_memory_search` with the affected
+file/feature name.
+
+If a match is found:
+- The previous root cause and fix are documented
+- Check if the previous fix regressed
+- Do NOT retry previously failed approaches (check recurrence_count)
+
+---
+
+## PHASE 1: SYMPTOM CAPTURE
+
+### 1.1 Document the Issue
+```markdown
+## Bug Report
+
+### Symptom
+- **What happens**: [exact behavior observed]
+- **Expected**: [what should happen]
+- **Environment**: DEV / PROD
+- **Reproducible**: Always / Sometimes / Once
+
+### Error Messages
+- **Console errors**: [exact text]
+- **Network errors**: [status codes, responses]
+- **Server logs**: [relevant log entries]
+
+### Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. [Bug occurs]
+```
+
+### 1.2 Collect Initial Evidence
+```bash
+# Recent changes that might be related
+git log --oneline -10
+
+# Check for recent file changes in affected area
+git diff HEAD~5 --name-only | grep -E "(component|router|page)"
+
+# Check build status
+npm run build 2>&1 | tail -20
+
+# Check for type errors
+npx tsc --noEmit 2>&1 | head -30
+```
+
+---
+
+## PHASE 2: CATEGORIZE & LOAD PATTERNS
+
+### 2.1 Error Category Matrix
+
+| Error Type | Likely Cause | Pattern File | First Check |
+|------------|--------------|--------------|-------------|
+| 500 Internal | DB/API error | database-patterns.md | Server logs |
+| 403 Forbidden | RLS/Auth | auth-patterns.md | RLS policies |
+| 401 Unauthorized | Session | auth-patterns.md | Token validity |
+| TypeError | Null/undefined | ui-patterns.md | Null guards |
+| React crash | Component error | ui-patterns.md | Error boundary |
+| Build fail | Import/config | build-patterns.md | tsc output |
+| Network timeout | API/DB slow | database-patterns.md | Query performance |
+
+### 2.2 Load Relevant Patterns
+Based on error category, read the appropriate pattern file and extract:
+- Common causes for this error type
+- Required verification checks
+- Known gotchas from CLAUDE.md
+
+---
+
+## PHASE 3: TRACE THE PATH
+
+### 3.1 UI Layer Investigation
+```bash
+# Find the component
+grep -rn "[ComponentName]" src/components/ src/app/
+
+# Check for event handlers
+grep -A 10 "onClick\|onSubmit\|onChange" [component_file]
+
+# Check for API calls
+grep -n "api\.\|useMutation\|useQuery" [component_file]
+
+# Check for null guards (CLAUDE.md rule)
+grep -n "?\.\||| \"\"\|?? " [component_file]
+```
+
+### 3.2 API Layer Investigation
+```bash
+# Find the router/procedure
+grep -rn "[procedureName]" src/server/api/routers/
+
+# Check procedure protection
+grep -B 5 "[procedureName]" src/server/api/routers/ | grep "protected\|public"
+
+# Check input validation
+grep -A 15 "[procedureName]:" src/server/api/routers/ | grep -A 10 "input"
+
+# Check for CLAUDE.md violations
+grep -n "ctx.prisma\|include:\|ctx.db.users" [router_file]
+```
+
+### 3.3 Database Layer Investigation
+```sql
+-- Check table exists
+SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename = '[TABLE]';
+
+-- Check column types
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = '[TABLE]';
+
+-- Check RLS policies
+SELECT polname, polcmd, polroles::text
+FROM pg_policies
+WHERE tablename = '[TABLE]';
+
+-- Check grants
+SELECT grantee, privilege_type
+FROM information_schema.table_privileges
+WHERE table_name = '[TABLE]';
+
+-- Test query directly
+SELECT * FROM [TABLE] WHERE [condition] LIMIT 5;
+```
+
+---
+
+## PHASE 4: HYPOTHESIS TESTING
+
+### 4.1 Hypothesis Template
+```markdown
+### Hypothesis [N]
+
+**Theory**: [What you think is wrong]
+**Evidence Supporting**: [Why you think this]
+**Test**: [How to verify]
+**Result**: [What happened]
+**Verdict**: CONFIRMED / REJECTED
+```
+
+### 4.2 Common Hypothesis Checklist
+
+#### Database Issues
+- [ ] Table exists in all environments?
+- [ ] Column types match Prisma schema?
+- [ ] RLS policies allow this operation?
+- [ ] service_role grants exist?
+- [ ] Using `ctx.db` not `ctx.prisma`?
+- [ ] Using `user_profiles` not `users`?
+- [ ] No `include:` statements (3-step pattern)?
+
+#### Auth Issues
+- [ ] Session valid and not expired?
+- [ ] User has required role/permissions?
+- [ ] protectedProcedure used for mutations?
+- [ ] Middleware routing correct?
+
+#### UI Issues
+- [ ] Null guards present (`?.` or `|| ""`)?
+- [ ] Loading state handled?
+- [ ] Error state handled?
+- [ ] Mobile responsive (`sm:page-container`)?
+- [ ] No `value=""` in Select.Item?
+
+#### Build Issues
+- [ ] All imports resolve?
+- [ ] No circular dependencies?
+- [ ] jsdom dynamically imported?
+- [ ] No client/server boundary violations?
+
+---
+
+## PHASE 5: ROOT CAUSE IDENTIFICATION
+
+### 5.1 Document Root Cause
+```markdown
+## Root Cause Analysis
+
+### The Problem
+[Exact technical cause]
+
+### Why It Happened
+[How this bug was introduced]
+
+### CLAUDE.md Violation (If Any)
+- Rule violated: [CR-X or pattern]
+- Correct pattern: [from CLAUDE.md]
+
+### Files Affected
+- [file1:line]
+- [file2:line]
+```
+
+### 5.2 Verify Root Cause
+```bash
+# Prove the root cause with VR-* protocol
+# VR-GREP: Show the problematic code
+grep -n "[problematic pattern]" [file]
+
+# VR-NEGATIVE: Confirm violation exists
+grep -rn "[violation]" src/ | wc -l
+# Should be > 0 if this is the cause
+```
+
+---
+
+## PHASE 6: FIX & VERIFY
+
+### 6.1 Apply Fix
+Follow CLAUDE.md patterns exactly:
+- Read relevant pattern file
+- Apply minimal correct fix
+- Do NOT over-engineer
+
+### 6.2 Verify Fix (MANDATORY)
+
+```bash
+# VR-NEGATIVE: Violation removed
+grep -rn "[old_violation]" src/ | wc -l
+# Expected: 0
+
+# VR-GREP: Correct pattern present
+grep -n "[correct_pattern]" [file]
+# Expected: Match found
+
+# VR-BUILD: Build passes
+npm run build
+
+# VR-TYPE: Types pass
+npx tsc --noEmit
+
+# Pattern scanner
+./scripts/pattern-scanner.sh
+
+# VR-COUPLING: Backend-frontend sync (CRITICAL - Added Jan 2026)
+./scripts/check-coupling.sh
+# Expected: Exit 0 - all backend features exposed in UI
+```
+
+### 6.3 Environment Verification
+If DB-related, verify fix in all environments:
+```sql
+-- Run same query that was failing
+-- Verify it now succeeds
+```
+
+---
+
+## PHASE 7: REGRESSION CHECK
+
+### 7.1 Related Functionality
+```bash
+# Find all uses of modified code
+grep -rn "[modified_function]" src/
+
+# Check for other places with same pattern
+grep -rn "[similar_pattern]" src/
+```
+
+### 7.2 Test User Flow
+Verify the original user flow now works:
+```markdown
+| Step | Action | Expected | Actual | Status |
+|------|--------|----------|--------|--------|
+| 1 | [action] | [expected] | [actual] | PASS |
+| 2 | [action] | [expected] | [actual] | PASS |
+```