@massu/core 0.4.2 → 0.6.0

package/commands/massu-loop/references/loop-controller.md

@@ -0,0 +1,188 @@
+# Loop Controller
+
+> Reference doc for `/massu-loop`. Return to main file for overview.
+
+## MANDATORY LOOP CONTROLLER (EXECUTE THIS - DO NOT SKIP)
+
+**This section is the EXECUTION ENTRY POINT. You MUST follow these steps exactly.**
+
+### How This Command Works
+
+This command is a **loop controller** for implementation + verification. Your job is to:
+1. Extract plan items and implement them
+2. After implementation, spawn a `massu-plan-auditor` subagent for verification
+3. Parse the structured result (`GAPS_DISCOVERED: N`)
+4. If gaps discovered > 0: fix gaps, then spawn ANOTHER FRESH auditor pass
+5. Only when a COMPLETE FRESH PASS discovers ZERO gaps can you declare complete
+
+**The verification audit runs inside Task subagents. This prevents early termination.**
+
+### CRITICAL: GAPS_DISCOVERED Semantics (Incident #19, Feb 7, 2026)
+
+**`GAPS_DISCOVERED` = total gaps FOUND during the pass, REGARDLESS of whether they were also fixed.**
+
+| Scenario | GAPS_DISCOVERED | Loop Action |
+|----------|----------------|-------------|
+| Pass finds 0 gaps | 0 | **EXIT** - verification complete |
+| Pass finds 5 gaps, fixes all 5 | **5** (NOT 0) | **CONTINUE** - must re-verify |
+| Pass finds 3 gaps, fixes 1, 2 need controller | **3** | **CONTINUE** - fix remaining, re-verify |
+
+**THE RULE**: A clean pass means zero gaps DISCOVERED from the start. Fixing gaps during a pass does NOT make it a clean pass. The fixes themselves could introduce new issues. Only a fresh pass starting clean and finding nothing proves correctness.
+
+### Execution Protocol
+
+```
+PLAN_PATH = $ARGUMENTS (the plan file path or task description)
+iteration = 0
+
+# Phase 1: IMPLEMENT (do the work)
+# Read plan, extract items, implement each one with VR-* proof
+
+# Phase 1.5: MULTI-PERSPECTIVE REVIEW (after implementation, before verification)
+# Spawn 3 focused review subagents IN PARALLEL for independent analysis
+# Each reviewer has an adversarial mindset and a SINGLE focused concern (Principle #20)
+# Elegance/simplicity assessment happens in Phase 2.1 POST-BUILD REFLECTION (Q4)
+
+security_result = Task(subagent_type="massu-security-reviewer", model="opus", prompt="
+  Review implementation for plan: {PLAN_PATH}
+  Focus: Security vulnerabilities, auth gaps, input validation, data exposure
+  Check all new/modified files. Return structured result with SECURITY_GATE.
+")
+
+architecture_result = Task(subagent_type="massu-architecture-reviewer", model="opus", prompt="
+  Review implementation for plan: {PLAN_PATH}
+  Focus: Design issues, coupling problems, pattern compliance, scalability
+  Check all new/modified files. Return structured result with ARCHITECTURE_GATE.
+")
+
+ux_result = Task(subagent_type="massu-ux-reviewer", model="sonnet", prompt="
+  Review implementation for plan: {PLAN_PATH}
+  Focus: User experience, accessibility, loading/error/empty states, consistency
+  Check all new/modified UI files. Return structured result with UX_GATE.
+")
+
+# Parse results and fix any CRITICAL/HIGH findings before proceeding to verification
+# FAIL gate = must fix before proceeding
+# WARN findings = document and proceed
+
+# Phase 1.6: TEST-FIRST FOR CRITICAL FINDINGS
+# If ANY Phase 1.5 reviewer flagged a CRITICAL-severity BUG (not pattern violation):
+#   1. Read _shared-references/test-first-protocol.md
+#   2. For EACH critical bug finding:
+#      - Write a failing test that demonstrates the bug (Step 1)
+#      - Verify the test fails for the expected reason (Step 2)
+#      - Apply the fix (Step 3)
+#      - Verify the test passes (Step 4)
+#   3. Report TEST_FIRST_GATE: PASS or SKIPPED (with reason)
+# If NO critical bug findings: skip this phase entirely
+
+# Phase 2: VERIFY (audit loop - STRUCTURAL)
+WHILE true:
+  iteration += 1
+
+  # Run circuit breaker check (CR-37: detect stagnation)
+  bash scripts/hooks/loop-circuit-breaker.sh --pass {iteration} --plan-trajectory .claude/loop-state/plan-trajectory.json
+  # Parse circuit breaker output - BAIL_AND_REPLAN is a structural halt
+  IF CIRCUIT_BREAKER_STATUS == "DEPTH_EXCEEDED":
+    Output: "CIRCUIT BREAKER: Loop depth exceeded (nested spawn detected)."
+    Output: "Current LOOP_DEPTH exceeds MAX_LOOP_DEPTH. Refusing to continue."
+    STOP loop immediately — cascade prevention.
+
+  IF CIRCUIT_BREAKER_STATUS == "BAIL_AND_REPLAN":
+    Output: "CIRCUIT BREAKER: The current approach is not converging after {iteration} passes."
+    Output: "No progress: {no_progress_count} passes | Same errors: {same_error_count} passes"
+    Output: "Options: (a) Re-plan with different approach (b) Continue current approach (c) Stop"
+    AskUserQuestion: "The loop has stalled. How should we proceed?"
+    IF user chooses re-plan: STOP loop, output current state, recommend /massu-create-plan
+    IF user chooses continue: CONTINUE loop (reset circuit breaker: bash scripts/hooks/loop-circuit-breaker.sh --reset)
+    IF user chooses stop: STOP loop, output current state as incomplete
+
+  IF CIRCUIT_BREAKER_STATUS == "PLAN_FUNDAMENTALLY_WRONG":
+    Output: "CIRCUIT BREAKER: Plan is fundamentally wrong — {distinct_failures} different items have failed."
+    Output: "This indicates a systemic plan issue, not isolated implementation problems."
+    Output: "Options:"
+    Output: "  (a) DISPOSE plan and regenerate from scratch (preserves learnings)"
+    Output: "  (b) Continue with current plan (override)"
+    Output: "  (c) Stop and review manually"
+    AskUserQuestion: "The plan appears fundamentally flawed. How should we proceed?"
+    IF user chooses dispose:
+      - Save failed items + error context to plan trajectory file
+      - STOP loop, output current state
+      - Recommend: /massu-create-plan with failed items as constraints
+      - The NEW plan goes through the same zero-gaps audit loop before implementation
+    IF user chooses continue: CONTINUE loop (reset: bash scripts/hooks/loop-circuit-breaker.sh --reset)
+    IF user chooses stop: STOP loop, output current state as incomplete
+
+  # Spawn auditor subagent for ONE complete verification pass
+  result = Task(subagent_type="massu-plan-auditor", model="opus", prompt="
+    Audit iteration {iteration} for plan: {PLAN_PATH}
+    Execute ONE complete audit pass. Verify ALL deliverables.
+    Check code quality (patterns, build, types, tests).
+    Check plan coverage (every item verified with proof).
+    Fix any gaps you find (code or plan document).
+
+    CRITICAL INSTRUCTION FOR GAPS_DISCOVERED:
+    Report GAPS_DISCOVERED as the total number of gaps you FOUND during this pass,
+    EVEN IF you also fixed them. Finding 5 gaps and fixing all 5 = GAPS_DISCOVERED: 5.
+    A clean pass that finds nothing wrong from the start = GAPS_DISCOVERED: 0.
+    Do NOT report 0 just because you fixed everything. The loop controller needs to know
+    whether this was a clean pass (found nothing) or a dirty pass (found and fixed things).
+
+    Return the structured result block with GAPS_DISCOVERED (not GAPS_FOUND).
+  ")
+
+  # Parse structured result
+  gaps = parse GAPS_DISCOVERED from result
+
+  # Report iteration to user
+  Output: "Verification iteration {iteration}: {gaps} gaps discovered"
+
+  IF gaps == 0:
+    Output: "ALL GATES PASSED - Clean pass with zero gaps discovered in iteration {iteration}"
+    BREAK
+  ELSE:
+    Output: "{gaps} gaps discovered in iteration {iteration}, starting fresh re-verification..."
+    # Fix code-level gaps the auditor identified but couldn't fix
+    # Then continue the loop for re-verification
+    CONTINUE
+END WHILE
+
+# Phase 2.1: POST-BUILD REFLECTION + MANDATORY MEMORY PERSIST (CR-38)
+# See references/auto-learning.md for full protocol
+```
+
+### Rules for the Loop Controller
+
+| Rule | Meaning |
+|------|---------|
+| **NEVER output a final verdict while gaps discovered > 0** | Only a CLEAN zero-gap-from-start iteration produces the final report |
+| **NEVER treat "found and fixed" as zero gaps** | Fixing during a pass still means gaps were discovered |
+| **NEVER ask user "should I continue?"** | The loop is mandatory - just execute it |
+| **NEVER stop after fixing gaps** | Fixing gaps requires a FRESH re-audit to verify the fixes |
+| **ALWAYS use Task tool for verification passes** | Subagents keep context clean |
+| **ALWAYS parse GAPS_DISCOVERED from result** | This is the loop control variable (DISCOVERED, not REMAINING) |
+| **Maximum 10 iterations** | If still failing after 10, report to user with remaining gaps |
+| **ALWAYS run multi-perspective review after implementation** | 3 reviewers catch different issues than 1 auditor |
+| **Run review subagents IN PARALLEL** | Security, architecture, UX reviews are independent |
+| **Fix CRITICAL/HIGH findings before verification** | Don't waste auditor passes on known issues |
+| **VR-PIPELINE for data features (CR-43)** | After implementing any data pipeline (AI, cron, generation, ETL), trigger it manually and verify non-empty output before marking complete |
+
+### Why This Architecture Exists
+
+**Incident #14 (Jan 30, 2026)**: Audit loop terminated after 1 pass with 6 open gaps. User had to manually intervene. Root cause: instructional "MUST loop" text competed with default "report and stop" behavior. By making the loop STRUCTURAL (spawn subagent, check result, loop), early termination becomes structurally impossible.
+
+**Incident #19 (Feb 7, 2026)**: Auditor found 16 gaps and fixed all 16 in the same pass, reported GAPS_FOUND: 0. Loop exited after 1 iteration without verifying the fixes. GAPS_DISCOVERED (not GAPS_REMAINING) is the correct metric.
+
+---
+
+### Subagent Budget Discipline
+
+The loop controller (main agent) coordinates; subagents execute scoped work. Follow these principles to prevent subagent sprawl:
+
+| Principle | Meaning |
+|-----------|---------|
+| **One task per subagent** | Each Task call has a single, scoped objective (Principle #20) |
+| **Main agent fixes, subagent verifies** | Controller fixes code-level gaps; auditor subagent re-verifies |
+| **No nested spawns** | Subagents NEVER spawn their own subagents (circuit breaker enforces via LOOP_DEPTH) |
+| **Parallel only when independent** | Review agents (security, architecture, UX) run in parallel; sequential passes run sequentially |
+| **Budget awareness** | Each subagent pass costs ~20-40K tokens. 10 iterations = significant cost. Fix root causes, not symptoms |

package/commands/massu-loop/references/plan-extraction.md

@@ -0,0 +1,78 @@
+# Plan Item Extraction
+
+> Reference doc for `/massu-loop`. Return to main file for overview.
+
+## PLAN ITEM EXTRACTION PROTOCOL (MANDATORY - STEP 0)
+
+**Before ANY implementation, extract ALL plan items into a trackable checklist.**
+
+### Step 0.1: Read Plan Document (Not Memory)
+
+```bash
+cat [PLAN_FILE_PATH]
+```
+
+**You MUST read the plan file. Do NOT rely on memory or summaries.**
+
+### Step 0.2: Extract ALL Deliverables
+
+For EACH section of the plan, extract concrete items into a table:
+
+```markdown
+## PLAN ITEM EXTRACTION
+
+### Source Document
+- **Plan File**: [path]
+- **Total Sections**: [N]
+
+### Extracted Items
+| Item # | Type | Description | Location | Verification Command | Status |
+|--------|------|-------------|----------|---------------------|--------|
+| P1-001 | FILE_CREATE | Component.tsx | src/components/ | ls -la [path] | PENDING |
+| P1-002 | PROCEDURE | router.method | src/server/api/ | grep "method" [router] | PENDING |
+
+### Item Types
+FILE_CREATE, FILE_MODIFY, COMPONENT, PROCEDURE, MIGRATION, FEATURE, REMOVAL (VR-NEGATIVE), REFACTOR
+
+### Coverage Summary
+- **Total Items**: [N] | **Verified Complete**: 0 | **Coverage**: 0%
+```
+
+### Step 0.3: Create Verification Commands
+
+| Item Type | Verification Method | Expected Result |
+|-----------|---------------------|-----------------|
+| FILE_CREATE | `ls -la [path]` | File exists, size > 0 |
+| FILE_MODIFY | `grep "[change]" [file]` | Pattern found |
+| COMPONENT | `grep "export.*ComponentName" [index]` | Export exists |
+| PROCEDURE | `grep "[procedure]:" [router]` | Procedure defined |
+| MIGRATION | `SELECT column_name FROM information_schema` | Column exists |
+| FEATURE | Feature-specific grep | Functionality present |
+| REMOVAL | `grep -rn "[old]" src/ \| wc -l` | 0 matches |
+
+### Step 0.4: Track Coverage Throughout
+
+After EVERY implementation action, update coverage count and verify with proof.
+
+---
+
+## PLAN DOCUMENT COMPLETION TRACKING (MANDATORY)
+
+Add completion table to TOP of plan document with status for each task:
+
+```markdown
+# IMPLEMENTATION STATUS
+
+**Plan**: [Name] | **Status**: COMPLETE/IN_PROGRESS | **Last Updated**: [date]
+
+| # | Task/Phase | Status | Verification | Date |
+|---|------------|--------|--------------|------|
+| 1 | [description] | 100% COMPLETE | VR-GREP: 0 refs | 2026-01-20 |
+```
+
+### VR-PLAN-STATUS Verification
+
+```bash
+grep "IMPLEMENTATION STATUS" [plan_file]
+grep -c "100% COMPLETE\|DONE\|\*\*DONE\*\*" [plan_file]
+```

package/commands/massu-loop/references/vr-plan-spec.md

@@ -0,0 +1,140 @@
+# VR-PLAN Verification Details
+
+> Reference doc for `/massu-loop`. Return to main file for overview.
+
+## VR-PLAN: VERIFICATION PLANNING STEP
+
+**Before executing ANY verification checks, ENUMERATE all applicable VR-* checks first.**
+
+```markdown
+### VR-PLAN: Verification Strategy
+
+**Work being verified**: [description]
+**Domains touched**: [database / UI / API / auth / build / config]
+
+| # | VR-* Check | Target File/Component | Why Applicable | Status |
+|---|------------|----------------------|----------------|--------|
+| 1 | VR-BUILD | Full project | Always required | PENDING |
+| 2 | VR-TYPE | Full project | Always required | PENDING |
+| 3 | VR-TEST | Full project | Always required (CR-21) | PENDING |
+| ... | ... | ... | ... | ... |
+
+**Execution order**: VR-SCHEMA first -> VR-BUILD/VR-TYPE -> VR-TEST -> VR-RENDER/VR-COUPLING -> VR-RUNTIME
+```
+
+### Mandatory Checks (ALWAYS include)
+
+| Check | When to Include |
+|-------|----------------|
+| VR-BUILD | ALWAYS |
+| VR-TYPE | ALWAYS |
+| VR-TEST | ALWAYS (CR-21) |
+| VR-FILE | When files created |
+| VR-GREP | When code added |
+| VR-NEGATIVE | When code removed |
+| VR-SCHEMA | When DB changed |
+| VR-DATA | When config-driven features touched |
+| VR-RENDER | When UI components created |
+| VR-COUPLING | When backend features added |
+| VR-HANDLER | When buttons/actions added |
+| VR-API-CONTRACT | When frontend calls backend |
+| VR-PLAN-COVERAGE | When implementing a plan |
+| VR-SPEC-MATCH | When UI items specify CSS classes/structure (CR-42) |
+| VR-PIPELINE | When data pipeline features implemented (CR-43) |
+| VR-RUNTIME | After all other checks pass |
+
+Do NOT start verification until VR-PLAN is complete with all domains, checks, targets, and execution order.
+
+---
+
+## COMPLETION CRITERIA
+
+Massu Loop is COMPLETE **only when BOTH gates pass: Code Quality AND Plan Coverage**.
+
+### GATE 1: Code Quality Verification (All Must Pass in SAME Audit Run)
+- [ ] All phases executed, all checkpoints passed with zero gaps
+- [ ] Pattern scanner: Exit 0
+- [ ] Type check: 0 errors
+- [ ] Build: Exit 0
+- [ ] Lint: Exit 0
+- [ ] Prisma validate: Exit 0
+- [ ] Tests: ALL PASS (MANDATORY)
+- [ ] Security: No secrets staged
+- [ ] VR-RENDER: All UI components rendered in pages
+
+### GATE 2: Plan Coverage Verification
+- [ ] Plan file read (actual file, not memory)
+- [ ] ALL items extracted into tracking table
+- [ ] EACH item verified with VR-* proof
+- [ ] Coverage = 100% (99% = FAIL)
+- [ ] Plan document updated with completion status
+
+### DUAL VERIFICATION REQUIREMENT
+
+**BOTH gates must pass:**
+
+```markdown
+## DUAL VERIFICATION RESULT
+| Gate | Status | Details |
+|------|--------|---------|
+| Code Quality | PASS/FAIL | Pattern scanner, build, types |
+| Plan Coverage | PASS/FAIL | X/Y items (Z%) |
+
+**RESULT: COMPLETE** (only if both PASS)
+```
+
+**Code Quality: PASS + Plan Coverage: FAIL = NOT COMPLETE**
+
+### Additional Verification
+- [ ] User Flow: ALL buttons, navigation, props, callbacks, state, e2e flows verified
+- [ ] Component Reuse: Checked existing before creating new
+- [ ] DB verified: all environments
+- [ ] Session state shows COMPLETED
+- [ ] Phase archives created
+- [ ] Help site updated for user-facing changes (or N/A)
+- [ ] Plan document completion table added at TOP
+
+---
+
+## COMPLETION OUTPUT
+
+```markdown
+## [MASSU LOOP - COMPLETE]
+
+### Dual Verification Certification
+- **Audit loops required**: N (loop #N achieved 0 gaps + 100% coverage)
+- **Code Quality Gate**: PASS
+- **Plan Coverage Gate**: PASS (X/X items = 100%)
+- **CERTIFIED**: Both gates passed in single complete audit
+
+### Summary
+- Total iterations: N
+- Total checkpoints: N (all PASSED)
+- Final audit loop: #N - ZERO GAPS + 100% COVERAGE
+
+### GATE 1: Code Quality Evidence
+| Gate | Command | Result |
+|------|---------|--------|
+| Pattern scanner | `./scripts/pattern-scanner.sh` | Exit 0 |
+| Type check | `npx tsc --noEmit` | 0 errors |
+| Build | `npm run build` | Exit 0 |
+| DB (DEV) | VR-SCHEMA | VERIFIED |
+| DB (PROD) | VR-SCHEMA | VERIFIED |
+
+### GATE 2: Plan Coverage Evidence
+| Item # | Description | Verification | Status |
+|--------|-------------|--------------|--------|
+| P1-001 | [description] | [VR-* output] | COMPLETE |
+| ... | ... | ... | COMPLETE |
+
+**Plan Coverage: X/X items (100%)**
+
+### Plan Document Updated
+- File: [path]
+- Completion table: ADDED at TOP
+- Plan Status: COMPLETE
+
+### Session State
+Updated: session-state/CURRENT.md
+Status: COMPLETED
+```

package/commands/massu-loop-playwright.md

@@ -1,13 +1,15 @@
 ---
 name: massu-loop-playwright
-description: Browser-based audit and fix loop — functional, visual, and performance testing with Playwright
+description: "When user wants browser-based testing, says 'test in browser', 'playwright audit', or needs visual/functional verification with Playwright"
 allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*), mcp__plugin_playwright_playwright__*, mcp__playwright__*
 ---
 name: massu-loop-playwright
 
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-5, CR-12 enforced.
+
 # Massu Loop Playwright: Browser-Based Audit & Fix Protocol
 
-**Shared rules**: Read `.claude/commands/_shared-preamble.md` for POST-COMPACTION (CR-35), QUALITY STANDARDS, and CR-9 (fix all issues) rules.
+**Shared rules**: Read `.claude/commands/_shared-preamble.md` for POST-COMPACTION (CR-12), QUALITY STANDARDS, and CR-9 (fix all issues) rules.
 
 ---
 
@@ -30,8 +32,8 @@ name: massu-loop-playwright
 # Test a specific URL
 /massu-loop-playwright https://example.com/docs
 
-# Test a specific page path (requires a full URL)
-/massu-loop-playwright https://localhost:3000/docs/getting-started
+# Test a local dev server page
+/massu-loop-playwright http://localhost:3000/docs/getting-started
 
 # Test multiple pages
 /massu-loop-playwright https://example.com/docs https://example.com/pricing
@@ -66,8 +68,6 @@ ELSE:
 - Output artifacts generated by Massu (static sites, reports, etc.)
 - A local dev server (`http://localhost:...`)
 
-Alternatively, use `--url` to test specific pages when the target app routes are known.
-
 ---
 
 ## SAFETY RULE (ABSOLUTE)
@@ -496,7 +496,7 @@ FOR EACH issue in issues WHERE priority <= P2:
      - Follow ALL CLAUDE.md patterns (no shortcuts)
 
   3. VERIFY the fix
-     - The live site requires a deployment/rebuild to verify browser-side
+     - The live site requires a rebuild/deployment to verify browser-side
      - For code-level verification: run applicable VR-* checks
      - VR-GREP: Confirm correct pattern is present
      - VR-NEGATIVE: Confirm incorrect pattern is removed
@@ -786,7 +786,7 @@ Ask the user how to proceed.
 After EVERY browser-discovered bug fix:
 
 ### Step 1: Ingest into Memory
-Use `mcp__massu__massu_memory_ingest` with:
+Use `mcp__massu-codegraph__massu_memory_ingest` with:
 - type: "bugfix"
 - description: "[Browser symptom] -> [Code fix]"
 - files: [list of files changed]
@@ -815,7 +815,7 @@ Fix ALL instances, not just the one found on this page.
 
 ## START NOW
 
-**Step 0: Write AUTHORIZED_COMMAND to session state (CR-35)**
+**Step 0: Write AUTHORIZED_COMMAND to session state (CR-12)**
 
 Before any other work, update `session-state/CURRENT.md` to include:
 ```