@massu/core 0.4.2 → 0.6.0

package/commands/massu-golden-path/references/approval-points.md

@@ -0,0 +1,216 @@
+# Approval Points
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+There are exactly 4 approval points (5 when using `--competitive` mode) where the golden path pauses for user input. Everything else runs automatically.
+
+## Approval Point Format
+
+```
+===============================================================================
+APPROVAL REQUIRED: [TYPE]
+===============================================================================
+
+[Details]
+
+OPTIONS:
+  "approve" / "yes" to continue
+  "modify" to request changes
+  "abort" to stop the golden path
+
+===============================================================================
+```
+
+After receiving approval, immediately continue. Do NOT ask "shall I continue?" -- just proceed.
+
+---
+
+## Approval Point #1: PLAN
+
+Triggered at: End of Phase 1 (after plan creation + audit loop).
+
+```
+===============================================================================
+APPROVAL REQUIRED: PLAN
+===============================================================================
+
+Plan created and audited ({iteration} audit passes, 0 gaps).
+
+PLAN SUMMARY:
+--------------------------------------------------------------------------
+Feature: [name]
+File: [plan path]
+Total Items: [N]
+Phases: [list]
+
+Requirements Coverage: [X]/10 dimensions resolved
+Feasibility: VERIFIED (DB, files, patterns, security)
+Audit Passes: {iteration} (final pass: 0 gaps)
+--------------------------------------------------------------------------
+
+OPTIONS:
+  "approve" to begin implementation
+  "modify: [changes]" to adjust plan
+  "abort" to stop
+
+===============================================================================
+```
+
+---
+
+## Approval Point #2: NEW PATTERN
+
+Triggered at: Any phase, when a new pattern is needed that does not exist in CLAUDE.md or patterns/*.md.
+
+```
+===============================================================================
+APPROVAL REQUIRED: NEW PATTERN
+===============================================================================
+
+A new pattern is needed for: [functionality]
+
+Existing patterns checked:
+- [pattern 1]: Not suitable because [reason]
+
+PROPOSED NEW PATTERN:
+--------------------------------------------------------------------------
+Name: [Pattern Name]
+Domain: [UI/Database/Auth/etc.]
+
+WRONG: [code]
+CORRECT: [code]
+Error if violated: [What breaks]
+--------------------------------------------------------------------------
+
+OPTIONS:
+  "approve" to save and continue
+  "modify: [changes]" to adjust
+  "abort" to stop
+
+===============================================================================
+```
+
+---
+
+## Approval Point #3: COMMIT
+
+Triggered at: End of Phase 4 (after all verification gates pass).
+
+```
+===============================================================================
+APPROVAL REQUIRED: COMMIT
+===============================================================================
+
+All verification checks passed. Ready to commit.
+
+VERIFICATION RESULTS:
+--------------------------------------------------------------------------
+  Pattern scanner: Exit 0
+  Type check: 0 errors
+  Build: Exit 0
+  Lint: Exit 0
+  Prisma: Valid
+  Security: No secrets staged, no credentials in code
+  VR-RENDER: All UI components rendered
+  VR-COUPLING: All backend features exposed in UI
+  VR-COLOR: No hardcoded Tailwind colors
+  Plan Coverage: [X]/[X] = 100%
+  Database: All environments verified
+  Help site: UP TO DATE / N/A
+  Quality Score: [X.X]/5.0
+--------------------------------------------------------------------------
+
+FILES TO BE COMMITTED:
+[list]
+
+PROPOSED COMMIT MESSAGE:
+--------------------------------------------------------------------------
+[type]: [description]
+
+[body]
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+--------------------------------------------------------------------------
+
+OPTIONS:
+  "approve" to commit and continue to push
+  "message: [new message]" to change commit message
+  "abort" to stop (changes remain staged)
+
+===============================================================================
+```
+
+---
+
+## Approval Point #4: PUSH
+
+Triggered at: End of Phase 5 (after all push verification tiers pass).
+
+```
+===============================================================================
+APPROVAL REQUIRED: PUSH TO REMOTE
+===============================================================================
+
+All verification tiers passed. Ready to push.
+
+PUSH GATE SUMMARY:
+--------------------------------------------------------------------------
+Commit: [hash]
+Message: [message]
+Files changed: [N] | +[N] / -[N]
+Branch: [branch] -> origin
+
+Tier 1 (Quick): PASS
+Tier 2 (Tests): PASS -- Unit: X/X, E2E: X/X, Regression: 0
+Tier 3 (Security): PASS -- Audit: 0 high/crit, RLS: verified, Secrets: clean
+--------------------------------------------------------------------------
+
+OPTIONS:
+  "approve" / "push" to push to remote
+  "abort" to stop (commit remains local)
+
+===============================================================================
+```
+
+---
+
+## Approval Point #5: WINNER SELECTION (--competitive only)
+
+Triggered at: End of Phase 2-COMP-D (after competitive scoring completes). Only present when `--competitive` flag is used.
+
+```
+===============================================================================
+APPROVAL REQUIRED: WINNER SELECTION
+===============================================================================
+
+Competitive implementation complete. {N} agents scored.
+
+COMPETITIVE SCORECARD:
+--------------------------------------------------------------------------
+| Dimension          | Agent A ({bias_a}) | Agent B ({bias_b}) | Agent C ({bias_c}) |
+|--------------------|--------------------|--------------------|---------------------|
+| Code Clarity       | X/5                | X/5                | X/5                 |
+| Pattern Compliance | X/5                | X/5                | X/5                 |
+| Error Handling     | X/5                | X/5                | X/5                 |
+| UX Quality         | X/5                | X/5                | X/5                 |
+| Test Coverage      | X/5                | X/5                | X/5                 |
+| **Raw Total**      | **XX/25**          | **XX/25**          | **XX/25**           |
+| **Weighted Total** | **XX.X**           | **XX.X**           | **XX.X**            |
+
+NOTABLE DIFFERENCES:
+  [Aspect]: Agent A did [X], Agent B did [Y]
+
+RECOMMENDATION: Agent {X} ({bias}) — [reason]
+--------------------------------------------------------------------------
+
+PER-AGENT NOTES:
+  Agent A ({bias_a}): [approach summary, strengths, weaknesses]
+  Agent B ({bias_b}): [approach summary, strengths, weaknesses]
+
+OPTIONS:
+  "approve" to accept recommended winner (Agent {X})
+  "override [agent_id]" to select a different winner
+  "abort" to stop (worktrees remain for manual inspection)
+
+===============================================================================
+```

package/commands/massu-golden-path/references/competitive-mode.md

@@ -0,0 +1,273 @@
+# Competitive Mode Protocol
+
+> Reference doc for `/massu-golden-path --competitive`. Return to main file for overview.
+
+**Purpose**: Spawn 2-3 competing implementations of the same plan with different optimization biases, score all implementations, and select the winner before proceeding with Massu's verification rigor.
+
+**Triggering**: Only when `/massu-golden-path --competitive` is explicitly used. Never automatic.
+
+---
+
+## Pre-Flight Guard (MANDATORY)
+
+Before spawning agents, scan the plan for database migration items:
+
+```
+SCAN plan for:
+  - Items with type = MIGRATION
+  - Items containing ALTER TABLE, CREATE TABLE, DROP TABLE
+  - Items containing RLS policies or grants
+  - Items referencing database migrations
+
+IF any found:
+  ABORT competitive mode with message:
+  "Competitive mode cannot run plans with database migrations.
+   Apply migrations first, then re-run with --competitive."
+```
+
+This mirrors the `/massu-batch` DB guard pattern (`scripts/batch-db-guard.sh`).
+
+---
+
+## Phase 2-COMP-A: Agent Spawning
+
+### Determine Agent Count & Bias Assignments
+
+| Flag | Agents | Bias Assignments |
+|------|--------|-----------------|
+| `--competitive` (default) | 2 | `quality` + `robust` |
+| `--competitive --agents 3` | 3 | `quality` + `ux` + `robust` |
+| `--competitive --biases quality,ux` | 2 | Custom assignment |
+
+### Spawn Agents
+
+For each agent, spawn using worktree isolation:
+
+```
+FOR each agent (A, B, [C]):
+  Agent(
+    isolation: "worktree",
+    prompt: [See Phase 2-COMP-B template],
+    model: "opus"
+  )
+```
+
+All agents spawn in PARALLEL. Each gets an isolated git worktree branch.
+
+---
+
+## Phase 2-COMP-B: Agent Prompt Template
+
+Each competing agent receives this prompt, customized with their bias preset:
+
+```
+You are implementing a plan in competitive mode. Your implementation will be
+scored against other agents implementing the same plan with different priorities.
+
+PLAN FILE: {plan_path}
+YOUR BIAS: {bias_preset}
+YOUR BRANCH: {worktree_branch}
+
+BIAS INSTRUCTIONS:
+{bias_prompt_fragment}
+
+IMPLEMENTATION RULES:
+1. Read the plan from disk and implement ALL items
+2. Follow ALL CLAUDE.md patterns (ctx.db, protectedProcedure, etc.)
+3. Do NOT run database migrations (handled separately)
+4. Run pattern-scanner after each file: ./scripts/pattern-scanner.sh
+5. Run tsc after implementation: npx tsc --noEmit
+6. Fix any issues before declaring done
+
+OUTPUT FORMAT (at completion):
+```
+COMPETITIVE_AGENT_RESULT:
+  BIAS: {bias}
+  BRANCH: {branch}
+  STATUS: COMPLETE | FAILED
+  FILES_CHANGED: [list]
+  SELF_SCORE:
+    code_clarity: X/5
+    pattern_compliance: X/5
+    error_handling: X/5
+    ux_quality: X/5
+    test_coverage: X/5
+  NOTES: [key decisions, trade-offs made]
+  ERROR: [if failed, what went wrong]
+```
+```
+
+---
+
+## Phase 2-COMP-B.1: Bias Preset Definitions
+
+### Quality Bias
+```
+YOUR OPTIMIZATION PRIORITY: CODE QUALITY
+
+Focus on:
+- Crystal-clear naming for all variables, functions, and components
+- Consistent code structure following established patterns exactly
+- Minimal complexity — prefer simple, readable solutions over clever ones
+- Strong typing with meaningful type names
+- Functions under 50 lines, files under 500 lines
+- Comments only where logic is non-obvious
+
+When in doubt between two approaches, choose the one that is easier to read
+and maintain, even if the alternative has slightly better performance or
+handles one more edge case.
+```
+
+### UX Bias
+```
+YOUR OPTIMIZATION PRIORITY: USER EXPERIENCE
+
+Focus on:
+- Loading states with skeletons for every async operation
+- Error states with clear messages and recovery actions
+- Empty states with helpful guidance
+- Responsive design across mobile, tablet, and desktop
+- Accessibility: aria labels, keyboard navigation, focus management
+- Dark mode support with proper contrast
+- Smooth transitions and micro-interactions
+- Toast notifications for all user actions (success, error, info)
+
+When in doubt between two approaches, choose the one that provides the
+better user experience, even if it requires slightly more code.
+```
+
+### Robust Bias
+```
+YOUR OPTIMIZATION PRIORITY: ROBUSTNESS & ERROR HANDLING
+
+Focus on:
+- Comprehensive input validation at every boundary
+- Try/catch around all async operations with specific error messages
+- Null/undefined guards for all optional data
+- Edge cases: empty arrays, single items, maximum values, concurrent access
+- Defensive coding: never trust external input, always validate
+- Graceful degradation when services are unavailable
+- Proper error propagation with context
+
+When in doubt between two approaches, choose the one that handles more
+failure modes, even if it requires slightly more code or complexity.
+```
+
+---
+
+## Phase 2-COMP-C: Monitoring & Collection
+
+```
+WAIT for all agents to complete
+
+FOR each agent result:
+  PARSE COMPETITIVE_AGENT_RESULT from output
+  IF STATUS == FAILED:
+    INCREMENT failure_count
+    LOG failure details
+
+IF failure_count == total_agents:
+  ABORT with total failure error (see error-handling.md)
+ELSE IF failure_count > 0:
+  LOG: "{failure_count} agent(s) failed, continuing with {remaining} successful"
+  CONTINUE with successful agents only
+ELSE:
+  ALL agents completed successfully
+```
+
+---
+
+## Phase 2-COMP-D: Scoring & Comparison
+
+Spawn the `massu-competitive-scorer` agent:
+
+```
+Task(
+  subagent_type: "massu-competitive-scorer",
+  model: "opus",
+  prompt: "
+    Score and compare competing implementations.
+    Plan: {plan_path}
+    Branches: {list of successful worktree branches}
+    Bias assignments: {map of branch -> bias}
+
+    Execute your full scoring workflow and return the structured comparison.
+  "
+)
+```
+
+Parse the scorer output for:
+- `WINNER`: branch name
+- `WINNER_BIAS`: bias preset
+- `WINNER_SCORE`: weighted total
+- `RUNNER_UP`: branch name
+- `RUNNER_UP_SCORE`: weighted total
+- `SCORE_MARGIN`: difference
+
+---
+
+## Phase 2-COMP-E: Winner Selection
+
+**APPROVAL POINT #5: WINNER SELECTION**
+
+Present the scorer's comparative scorecard to the user. See `approval-points.md` for exact format.
+
+### After Approval
+
+| User Response | Action |
+|---------------|--------|
+| `approve` | Accept recommended winner, proceed to Phase 2-COMP-F |
+| `override [agent_id]` | Select the specified agent as winner instead |
+| `abort` | Stop golden path, leave worktrees for inspection |
+
+---
+
+## Phase 2-COMP-F: Winner Merge
+
+### Merge Winning Branch
+
+```
+1. Identify winning worktree branch
+2. git merge {winning_branch} --no-ff -m "competitive-mode: merge winner ({bias})"
+3. IF merge conflict:
+     Present to user for resolution (see error-handling.md)
+4. ELSE:
+     Merge successful
+```
+
+### Cleanup Losing Worktrees
+
+```
+FOR each non-winning worktree:
+  git worktree remove {path} --force
+  git branch -D {branch_name}
+
+IF cleanup fails:
+  Log warning (non-blocking, see error-handling.md)
+```
+
+### Post-Merge Verification
+
+```
+1. Run ./scripts/pattern-scanner.sh (exit 0 required)
+2. Run npx tsc --noEmit (0 errors required)
+3. IF either fails:
+     Fix issues from merge
+     Re-run verification
+```
+
+### Continue to Phase 2.5
+
+After successful merge and verification, proceed directly to Phase 2.5 (Gap & Enhancement Analysis). The winner's implementation is now on the current branch and all subsequent phases (2.5, 3, 4, 5, 6) run normally.
+
+---
+
+## Cost Implications
+
+| Mode | Phase 2 Token Multiplier | When to Use |
+|------|-------------------------|-------------|
+| Standard (no flag) | 1x | Most features, incremental changes |
+| `--competitive` (2 agents) | ~2.2x | New modules, critical features, UI-heavy work |
+| `--competitive --agents 3` | ~3.3x | High-stakes features, new domain areas |
+
+The multiplier applies ONLY to Phase 2 (implementation). All other phases run once regardless.

package/commands/massu-golden-path/references/error-handling.md

@@ -0,0 +1,121 @@
+# Error Handling
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+## Recoverable Errors
+
+Fix automatically -> re-run failed step -> if fixed, continue without pausing -> if not fixable after 3 attempts, pause and report.
+
+## Non-Recoverable Errors
+
+```
+===============================================================================
+GOLDEN PATH BLOCKED
+===============================================================================
+
+BLOCKER: [Description]
+Required: [Steps to resolve]
+After resolving, run /massu-golden-path again.
+
+===============================================================================
+```
+
+---
+
+## Abort Handling
+
+When user says "abort" at any approval point:
+
+```
+===============================================================================
+GOLDEN PATH ABORTED
+===============================================================================
+
+Stopped at: [Phase N -- Approval Point]
+
+CURRENT STATE:
+  Completed phases: [list]
+  Pending phases: [list]
+  Plan file: [path]
+  Files changed: [list]
+  Commit created: YES/NO
+  Pushed: NO
+
+TO RESUME:
+  Run /massu-golden-path again with the same plan
+  Or run individual commands:
+    /massu-loop      -- Continue implementation
+    /massu-simplify  -- Run quality analysis
+    /massu-commit    -- Run commit verification
+    /massu-push      -- Run push verification
+
+===============================================================================
+```
+
+---
+
+## Post-Compaction Re-Verification (CR-42)
+
+**After ANY context compaction during a golden path run**, BEFORE continuing implementation:
+
+1. **Re-read the FULL plan document** from disk (CR-5 -- never from memory)
+2. **Diff every completed item against actual code**: For each item marked complete in the tracking table, re-run its VR-* verification command
+3. **VR-SPEC-MATCH audit**: For every completed UI item with specific CSS classes/structure in the plan, grep for those EXACT strings in the implementation
+4. **Flag mismatches**: Any item where implementation doesn't match the plan's exact spec -> mark as gap, fix before continuing
+
+This prevents the common failure mode where compaction loses spec details and the agent continues implementing without matching the plan's precise requirements.
+
+---
+
+## Competitive Mode Errors (--competitive only)
+
+### Agent Failure During Implementation
+
+**Partial failure** (1 agent fails, 2+ remain): Continue with remaining agents. Log the failure. Score only the successful implementations.
+
+**Total failure** (all agents fail):
+```
+===============================================================================
+GOLDEN PATH BLOCKED
+===============================================================================
+
+BLOCKER: All competing agents failed during Phase 2-COMP
+  Agent A ({bias_a}): [error summary]
+  Agent B ({bias_b}): [error summary]
+
+Required: Fix the underlying issue, then re-run /massu-golden-path --competitive
+  Or run without --competitive to use standard single-agent implementation.
+
+===============================================================================
+```
+
+### Merge Conflict When Applying Winner
+
+If the winning worktree branch cannot be cleanly merged:
+```
+===============================================================================
+GOLDEN PATH BLOCKED
+===============================================================================
+
+BLOCKER: Merge conflict when applying winner (Agent {X})
+Conflicting files: [list]
+
+Required: Resolve conflicts manually, then continue with Phase 2.5
+  Or select a different winner: "override [agent_id]"
+
+===============================================================================
+```
+
+### Scoring Tie
+
+If two or more agents have weighted scores within 0.5 of each other, flag as TIE and present to user for decision via the Winner Selection approval point. The scorer will note `SCORE_MARGIN: < 0.5 (TIE)` and the user must use `override [agent_id]` to select.
+
+### Worktree Cleanup Failure
+
+If worktree cleanup fails after winner selection:
+```
+Warning: Failed to clean up worktree branches. Manual cleanup:
+  git worktree remove [path] --force
+  git branch -D [branch_name]
+```
+This is non-blocking — continue with the golden path.

package/commands/massu-golden-path/references/phase-0-requirements.md

@@ -0,0 +1,53 @@
+# Phase 0: Requirements & Context Loading
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+## 0.1 Session Context Loading
+
+```
+[GOLDEN PATH -- PHASE 0: REQUIREMENTS & CONTEXT]
+```
+
+- Call `massu_memory_sessions` for recent session context
+- Call `massu_memory_search` + `massu_memory_failures` with feature keywords
+- Read `session-state/CURRENT.md` for any prior state
+
+## 0.2 Requirements Coverage Map
+
+Initialize ALL dimensions as `pending`:
+
+| # | Dimension | Status | Resolved By |
+|---|-----------|--------|-------------|
+| D1 | Problem & Scope | pending | User request + interview |
+| D2 | Users & Personas | pending | Interview |
+| D3 | Data Model | pending | Phase 1A (DB Reality Check) |
+| D4 | Backend / API | pending | Phase 1A (Codebase Reality Check) |
+| D5 | Frontend / UX | pending | Interview + Phase 1A |
+| D6 | Auth & Permissions | pending | Phase 1A (Security Pre-Screen) |
+| D7 | Error Handling | pending | Phase 1A (Pattern Compliance) |
+| D8 | Security | pending | Phase 1A (Security Pre-Screen) |
+| D9 | Edge Cases | pending | Phase 1A (Question Filtering) |
+| D10 | Performance | pending | Phase 1A (Pattern Compliance) |
+
+## 0.3 Ambiguity Detection (7 Signals)
+
+| Signal | Description |
+|--------|-------------|
+| A1 | Vague scope -- no clear boundary |
+| A2 | No success criteria -- no measurable outcome |
+| A3 | Implicit requirements -- unstated but necessary |
+| A4 | Multi-domain -- spans 3+ domains |
+| A5 | Contradictions -- conflicting constraints |
+| A6 | No persona -- unclear who benefits |
+| A7 | New integration -- external service not yet in codebase |
+
+**Score >= 2**: Enter interview loop (0.4). **Score 0-1**: Fast-track to Phase 1A.
+
+## 0.4 Interview Loop (When Triggered)
+
+Ask via AskUserQuestion, one question at a time:
+1. Show compact coverage status: `Coverage: D1:done D2:pending ...`
+2. Provide 2-4 curated options (never open-ended)
+3. Push back on contradictions and over-engineering
+4. Self-terminate when D1, D2, D5 covered
+5. Escape hatch: user says "skip" / "enough" / "just do it" -> mark remaining as `n/a`