@massu/core 0.5.0 → 0.6.1

package/commands/massu-golden-path/references/phase-2.5-gap-analyzer.md

@@ -0,0 +1,170 @@
+# Phase 2.5: Gap & Enhancement Analyzer Loop
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 2.5: GAP & ENHANCEMENT ANALYSIS]
+```
+
+## Purpose
+
+After implementation (Phase 2) completes successfully, run a continuous gap and enhancement analysis loop. This phase catches everything implementation missed: incomplete features, missing edge cases, UX gaps, untested paths, accessibility issues, and enhancement opportunities.
+
+**This phase loops until a FULL PASS discovers ZERO gaps/enhancements.**
+
+---
+
+## LOOP CONTROLLER
+
+```
+iteration = 0
+MAX_ITERATIONS = 10
+
+WHILE iteration < MAX_ITERATIONS:
+  iteration += 1
+
+  result = Task(subagent_type="gap-analyzer", prompt="
+    Gap & Enhancement Analysis — Iteration {iteration}
+
+    CONTEXT:
+    - Plan file: {PLAN_PATH}
+    - Implementation is COMPLETE (Phase 2 passed)
+    - Your job: find gaps and enhancements the implementation missed
+
+    INSTRUCTIONS:
+    1. Read the plan from disk
+    2. Read CLAUDE.md and relevant patterns
+    3. Review ALL files changed in this session: git diff origin/main --name-only
+    4. Run the analysis categories below
+    5. For each gap/enhancement found: FIX IT immediately
+    6. Report GAPS_DISCOVERED as total found (even if fixed)
+
+    ANALYSIS CATEGORIES:
+
+    A. FUNCTIONAL GAPS
+    - Missing error handling (try/catch, error boundaries, toast notifications)
+    - Missing loading states (Skeleton, Spinner, disabled buttons during submit)
+    - Missing empty states ('No items found' messaging)
+    - Missing null guards on nullable fields
+    - Missing form validation (required fields, format validation)
+    - Incomplete CRUD (create exists but no edit/delete, or vice versa)
+
+    B. UX GAPS
+    - Missing success feedback after mutations (toast.success)
+    - Missing confirmation for destructive actions (AlertDialog)
+    - Missing keyboard navigation (tabIndex, onKeyDown for Enter)
+    - Missing responsive behavior (sm:/md:/lg: breakpoints)
+    - Inconsistent spacing (page-container class, gap values)
+    - Missing breadcrumbs or navigation context
+    - VR-VISUAL weighted score < 3.0 on affected routes
+
+    C. DATA INTEGRITY GAPS
+    - Optimistic updates without rollback
+    - Missing query invalidation after mutations
+    - Stale data after navigation (missing refetch)
+    - Missing pagination for large datasets
+    - Unhandled BigInt/Decimal serialization
+
+    D. SECURITY GAPS
+    - Missing protectedProcedure on mutations
+    - Missing input validation on router inputs
+    - Missing RLS policies on new tables
+    - Exposed sensitive data in client responses
+
+    E. PATTERN COMPLIANCE
+    - Run ./scripts/pattern-scanner.sh on changed files
+    - Check for pattern violations
+    - Check for hardcoded colors (should use design tokens)
+
+    F. ENHANCEMENT OPPORTUNITIES
+    - Type safety improvements (replace 'any' with proper types)
+    - Code deduplication (extract shared logic)
+    - Performance (unnecessary re-renders, missing useMemo/useCallback)
+    - Accessibility (aria-labels, alt text, focus management)
+
+    G. E2E WIRING GAPS
+    - For each data flow in changed files, verify VR-ROUNDTRIP:
+      WRITE: mutation/action reachable from UI or cron
+      STORE: data persists in a real table
+      READ: query reads from that same table
+      DISPLAY: component renders the query data (or cron logs output)
+    - Background-only features (crons, webhooks): WRITE->STORE->READ sufficient
+    - Query-only features (read views): READ->DISPLAY sufficient
+
+    I. RUNTIME & BOOT VERIFICATION (CR-44, Incident 2026-03-29)
+    - For EACH service that was created, modified, or registered in this session:
+      1. VR-DEPS: Verify .venv/bin/python3 exists (if plist references it)
+      2. VR-DEPS: Parse imports from main.py, verify each is installed in the venv
+      3. VR-COMPAT: Check for Python 3.10+ syntax (x | None, match/case) on Python 3.9 systems
+      4. VR-BOOT: Actually start the service (launchctl bootstrap or direct python), wait 5s, verify:
+         - Process is still alive (pgrep)
+         - Exit code is 0 (launchctl list | grep service)
+         - stderr log has no import errors or crashes
+      5. If boot fails: read stderr log, diagnose (missing package? wrong path? syntax error?), fix, retry
+    - Skip condition: plan has NO service/daemon/LaunchAgent items
+    - This category exists because static verification (VR-SYNTAX, VR-GREP) cannot catch:
+      missing venvs, missing pip packages, Python version incompatibilities, or runtime import errors
+
+    H. SPRINT CONTRACT COMPLIANCE (if contracts exist from Phase 2A.5)
+    - Read the sprint contracts from the Phase 2A tracking table
+    - For EACH plan item with a sprint contract:
+      1. List all acceptance criteria from the contract
+      2. Verify EACH criterion with specific evidence (grep, screenshot, DOM state, network response)
+      3. Any unmet criterion = GAP (P1 severity minimum)
+    - Contract criteria are IN ADDITION TO categories A-G — both must pass
+    - Skip condition: items marked `Contract: N/A` in the tracking table
+    - If no sprint contracts were negotiated (Phase 2A.5 skipped), skip this category
+
+    FOR EACH FINDING:
+    1. Classify: GAP (must fix) or ENHANCEMENT (should fix)
+    2. Severity: P0 (broken) / P1 (incorrect) / P2 (polish)
+    3. Fix it immediately
+    4. Verify the fix
+
+    RETURN STRUCTURED RESULT:
+    ```
+    GAPS_DISCOVERED: [N]
+    ENHANCEMENTS_APPLIED: [N]
+    ITEMS_FIXED: [N]
+
+    | # | Type | Severity | Description | File | Fixed |
+    |---|------|----------|-------------|------|-------|
+    | 1 | GAP | P0 | Missing error boundary | src/app/.../page.tsx | YES |
+    ```
+  ")
+
+  gaps = parse GAPS_DISCOVERED from result
+
+  IF gaps == 0:
+    Output: "Gap analysis clean in iteration {iteration} — zero gaps found"
+    BREAK
+  ELSE:
+    Output: "Iteration {iteration}: {gaps} gaps found and fixed, re-analyzing..."
+    CONTINUE
+
+IF iteration == MAX_ITERATIONS AND gaps > 0:
+  Output: "WARNING: Gap analyzer did not converge after {MAX_ITERATIONS} iterations. {gaps} gaps remain."
+```
+
+---
+
+## RULES
+
+| Rule | Meaning |
+|------|---------|
+| **Fix during analysis** | The analyzer fixes gaps as it finds them, not just reports |
+| **Full re-pass required** | After fixes, a fresh pass must find ZERO to exit |
+| **P0 gaps block** | Any P0 gap that can't be fixed stops the golden path |
+| **Enhancements are mandatory** | Enhancements found MUST be applied (this is golden path, not quick fix) |
+| **Pattern scanner gates** | `./scripts/pattern-scanner.sh` must exit 0 after each iteration |
+| **No new files without reason** | Don't create helper files that aren't needed |
+
+---
+
+## WHEN TO SKIP
+
+This phase can be skipped ONLY if:
+- The implementation was documentation-only (no source files changed)
+- User explicitly says "skip gap analysis"
+
+Otherwise, it runs automatically as part of the golden path.

package/commands/massu-golden-path/references/phase-3-simplify.md

@@ -0,0 +1,40 @@
+# Phase 3: Simplification
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 3: SIMPLIFICATION]
+```
+
+## 3.1 Fast Gate
+
+```bash
+./scripts/pattern-scanner.sh  # Fix ALL violations before semantic analysis
+```
+
+## 3.1.5 Dead Code Detection
+
+```bash
+npx knip --no-exit-code --reporter compact 2>/dev/null | head -50
+# OR use /massu-dead-code for full analysis
+```
+
+Review output for unused exports, files, and dependencies. Remove dead code before semantic review. Skip if knip is not installed (advisory gate, not blocking).
+
+## 3.2 Parallel Semantic Review (3 Agents)
+
+Spawn IN PARALLEL (Principle #20 -- one task per agent):
+
+**Efficiency Reviewer** (haiku): Query inefficiency (findMany.length -> SQL COUNT, N+1, unbounded queries), React inefficiency (useState for derived, useEffect->setState, missing useMemo/useCallback), algorithmic inefficiency (O(n^2), repeated sort/filter).
+
+**Reuse Reviewer** (haiku): Known utilities (formatFileSize, serializeUnifiedProduct, mergeWhereWithTenant, emptyToNull, PhoneInputField, sanitizeContentHtml), component duplication against src/components/shared/ and ui/, pattern duplication across new files.
+
+**Pattern Compliance Reviewer** (haiku): React Query v5 (no onSuccess in useQuery), DB patterns (Object.assign->mergeWhereWithTenant, include:->3-step, BigInt Number()), UI patterns (Select value="", missing states, Suspense), security (z.string()->z.enum() for orderBy, CR-5 precedence, CRON_SECRET guard), architecture (link table scoping, SQL aggregates, client/server boundary).
+
+## 3.3 Apply ALL Findings
+
+Sort by SEVERITY (CRITICAL -> LOW). Fix ALL (CR-9). Re-run pattern scanner.
+
+```
+SIMPLIFY_GATE: PASS (N findings, N fixed, 0 remaining)
+```

package/commands/massu-golden-path/references/phase-3.5-security-audit.md

@@ -0,0 +1,108 @@
+# Phase 3.5: Deep Security Audit
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 3.5: DEEP SECURITY AUDIT]
+```
+
+## Purpose
+
+Run a full adversarial security audit loop against ALL files changed in this golden path run. This is a deep, iterative audit with parallel red-team agents that converges to zero findings. It runs AFTER simplification (Phase 3) so the audit targets the final, cleaned-up code -- and BEFORE pre-commit verification (Phase 4) so all security fixes are included in the verification gates.
+
+**This phase is NEVER skipped.** Security is non-negotiable regardless of change size, type, or scope.
+
+---
+
+## 3.5.1 Determine Audit Scope
+
+Collect ALL files changed during this golden path run:
+
+```bash
+git diff --name-only HEAD
+```
+
+If files were already committed in earlier phases, also include:
+```bash
+git diff --name-only main...HEAD
+```
+
+The audit scope is the union of all changed files. Do NOT narrow scope -- every changed file gets audited.
+
+**Output:**
+```
+SECURITY AUDIT SCOPE:
+  Files: [N]
+  [list of files]
+```
+
+---
+
+## 3.5.2 Execute Deep Security Audit
+
+Run the full security audit protocol against the scoped files:
+
+1. **Launch 2-4 parallel adversarial reviewer agents** adapted to the codebase area:
+   - Backend/API code: 4 agents (Injection, Network/Leakage, DoS/Resources, Red Team Bypass)
+   - Frontend code: 3 agents (XSS/Injection, Auth/Data Exposure, Input Validation/Logic)
+   - Infrastructure/config: 2 agents (Secrets/Config, Dependencies/Supply Chain)
+
+2. **Consolidate findings** -- deduplicate across agents, take higher severity on disagreements
+
+3. **Fix ALL findings** -- CRITICAL first, then HIGH, MEDIUM, LOW. INFO documented only.
+
+4. **Verify fixes** -- import checks, input validation tests, functionality preserved
+
+5. **Loop until zero findings** -- max 5 iterations, escalate to user if still failing after 5
+
+---
+
+## 3.5.3 Attack Vector Coverage
+
+Every audit iteration MUST verify the complete attack vector checklist:
+
+### Universal
+- Hardcoded secrets / API keys / credentials
+- Error messages leaking internal details
+- Dependency vulnerabilities
+- Input validation on ALL external boundaries
+
+### Backend / API
+- SQL injection, command injection, path traversal
+- SSRF, authentication bypass, authorization bypass
+- DoS via unbounded inputs, memory leaks, race conditions
+- Response validation, type confusion
+
+### Frontend
+- XSS, open redirects, sensitive data in client state
+- CSRF, client-side auth bypass
+
+### LLM / AI Specific
+- Prompt injection, model output trust
+- Tool argument injection, vision/multimodal injection
+
+---
+
+## 3.5.4 Completion Gate
+
+The phase completes ONLY when the audit loop achieves a clean pass with zero findings.
+
+```
+SECURITY_AUDIT_GATE: PASS
+  Iterations: [N]
+  Total findings fixed: [N]
+  Breakdown: [X] CRITICAL, [X] HIGH, [X] MEDIUM, [X] LOW fixed
+  Clean pass: Iteration [N]
+```
+
+**Do NOT proceed to Phase 4 until SECURITY_AUDIT_GATE = PASS.**
+
+---
+
+## Rules
+
+1. **NEVER skip this phase** -- not for small changes, not for docs, not for config
+2. **NEVER proceed with findings unfixed** -- zero means zero
+3. **ALL severity levels get fixed** -- CRITICAL through LOW
+4. **No commit prompt** -- unlike standalone security audit commands, do NOT offer to commit here (Phase 4 handles commits)
+5. **Findings feed Phase 4** -- security fixes are verified by Phase 4's type check, build, lint, and secrets gates automatically

package/commands/massu-golden-path/references/phase-4-commit.md

@@ -0,0 +1,94 @@
+# Phase 4: Pre-Commit Verification
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 4: PRE-COMMIT VERIFICATION]
+```
+
+## 4.1 Auto-Verification Gates (ALL must pass in SINGLE run)
+
+| Gate | Command | Expected |
+|------|---------|----------|
+| 1. Pattern Scanner | `./scripts/pattern-scanner.sh` | Exit 0 |
+| 2. Type Safety (VR-TYPE) | `NODE_OPTIONS="--max-old-space-size=8192" npx tsc --noEmit` | 0 errors |
+| 3. Build (VR-BUILD) | `npm run build` | Exit 0 |
+| 4. Lint | `npm run lint` | Exit 0 |
+| 5. Prisma Validate | `npx prisma validate` | Exit 0 |
+| 6. Secrets Staged | `git diff --cached --name-only \| grep -E '\.(env\|pem\|key\|secret)'` | 0 files |
+| 7. Credentials in Code | `grep -rn "sk-\|password.*=.*['\"]" --include="*.ts" --include="*.tsx" src/ \| grep -v "process.env" \| wc -l` | 0 |
+| 8. Schema Mismatch | Extract tables from staged routers -> query columns via MCP | All exist |
+| 9. VR-RENDER | For EACH staged component: `grep "<ComponentName" src/app/**/page.tsx` | Match found |
+| 9.5. VR-COLOR | `git diff --cached \| grep "text-red-\|bg-green-\|..."` | 0 matches |
+| 9.6. VR-COUPLING | `massu_coupling_check` or `./scripts/check-coupling.sh` | Exit 0 |
+| 10. Plan Coverage | Verify ALL plan items with VR-* proof | 100% |
+| 11. VR-PLAN-STATUS | `grep "IMPLEMENTATION STATUS" [plan]` | Match |
+| 12. Dependency Security | `npm audit --audit-level=high` | 0 high/crit |
+| 13. Test Coverage | Check test files exist for new code | WARN level |
+| 14. VR-VISUAL | `bash scripts/ui-review.sh [route]` (if UI files changed) | VR_VISUAL_STATUS: PASS |
+
+For each modified file: `massu_validate_file`, `massu_security_score`, `massu_security_heatmap`. If any file scores > 7/10 risk, flag for review.
+
+Spawn `massu-pattern-reviewer` agent for deep CR rule checks, import chain validation, semantic pattern matching.
+
+## 4.2 Database Verification (All Environments)
+
+For EACH affected table, query all configured environments via MCP:
+
+| Env | MCP Prefix | Verify |
+|-----|-----------|--------|
+| DEV | `mcp__supabase__DEV__execute_sql` | Table, columns, RLS, grants |
+| PROD | `mcp__supabase__PROD__execute_sql` | Table, columns, RLS, grants |
+
+VR-DATA: If config-driven features, query actual config values and compare to code expectations.
+
+## 4.3 Help Site Auto-Sync
+
+1. Get staged files -> pass to `massu_docs_audit`
+2. For STALE/NEW pages: update MDX, set `lastVerified`, add changelog
+3. Commit to help site repo (separate git)
+4. Return to main app repo
+
+## 4.4 Quality Scoring Gate
+
+Spawn `massu-output-scorer` (sonnet): Code Clarity, Pattern Compliance, Error Handling, UX Quality, Test Coverage (1-5 each). All >= 3: PASS. Any < 3: FAIL.
+
+## 4.5 If ANY Gate Fails
+
+**DO NOT PAUSE** -- Fix automatically, re-run ALL gates, repeat until all pass.
+
+## 4.6 Auto-Learning Protocol
+
+- For each bug fixed: `massu_memory_ingest` type="bugfix", update MEMORY.md
+- For new patterns: `massu_memory_ingest` type="pattern"
+- Add detection to `scripts/pattern-scanner.sh` if grep-able
+- Codebase-wide search: no other instances of same bad pattern (CR-9)
+- Record user corrections to `memory/corrections.md`
+
+---
+
+## Phase 4 Complete -> APPROVAL POINT #3: COMMIT
+
+See `approval-points.md` for the exact format.
+
+### Commit Format
+
+```bash
+git commit -m "$(cat <<'EOF'
+[type]: [description]
+
+[Body]
+
+Changes:
+- [Change 1]
+- [Change 2]
+
+Verified:
+- Pattern scanner: PASS | Type check: 0 errors | Build: PASS
+- DB: All environments verified
+- Help site: UP TO DATE
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```

package/commands/massu-golden-path/references/phase-5-push.md

@@ -0,0 +1,116 @@
+# Phase 5: Push Verification & Push
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 5: PUSH VERIFICATION]
+```
+
+## 5.1 Pre-Flight
+
+```bash
+git log origin/main..HEAD --oneline  # Commits to push
+```
+
+## 5.2 Tier 1: Quick Re-Verification
+
+Run in parallel where possible:
+
+| Check | Command |
+|-------|---------|
+| Pattern Scanner | `./scripts/pattern-scanner.sh` |
+| VR-COUPLING | `./scripts/check-coupling.sh` |
+| VR-UX | `./scripts/check-ux-quality.sh` |
+| TypeScript | `NODE_OPTIONS="--max-old-space-size=8192" npx tsc --noEmit` |
+| Build | `npm run build` |
+| Prisma | `npx prisma validate` |
+| Schema Mismatch | `./scripts/check-schema-mismatches.sh` |
+
+## 5.3 Tier 2: Test Suite (CRITICAL)
+
+### 5.3.0 Regression Detection (MANDATORY FIRST)
+
+```bash
+# Establish baseline on main
+git stash && git checkout main -q
+npm run test:run 2>&1 | tee /tmp/baseline-tests.txt
+git checkout - -q && git stash pop -q
+
+# Run on current branch
+npm run test:run 2>&1 | tee /tmp/current-tests.txt
+
+# Compare: any test passing on main but failing now = REGRESSION
+# Regressions MUST be fixed before push
+```
+
+### 5.3.1-5.3.5 Test Execution
+
+Use **parallel Task agents** for independent checks:
+
+```
+Agent Group A (parallel):
+- Agent 1: npm run test:run (unit tests)
+- Agent 2: npm audit --audit-level=high
+- Agent 3: npx tsx scripts/detect-secrets.ts
+
+Agent Group B (parallel, after A):
+- Agent 1: npm run test:e2e (E2E tests)
+- Agent 2: npm run test:visual:run (visual regression)
+
+Sequential:
+- ./scripts/validate-router-contracts.sh
+- VR-RENDER: verify ALL new components rendered in pages
+```
+
+## 5.4 Tier 3: Security & Compliance
+
+| Check | Command |
+|-------|---------|
+| npm audit | `npm audit --audit-level=high` |
+| Secrets scan | `npx tsx scripts/detect-secrets.ts` |
+| Accessibility | `./scripts/verify-accessibility.sh` |
+| DB sync | Verify schema match across all environments |
+
+### VR-STORED-PROC (If migrations in push)
+
+```sql
+SELECT proname, prosrc FROM pg_proc
+JOIN pg_namespace n ON n.oid = pronamespace
+WHERE n.nspname = 'public' AND prosrc LIKE '%old_table_name%';
+-- Run on all environments. Expected: 0 rows.
+```
+
+### VR-RLS-AUDIT (CR-33)
+
+```sql
+SELECT c.relname FROM pg_class c
+JOIN pg_namespace n ON c.relnamespace = n.oid
+WHERE n.nspname = 'public' AND c.relkind = 'r' AND c.relrowsecurity = false;
+-- Run on all environments. Expected: 0 rows.
+```
+
+### VR-DATA (Config-Code Alignment)
+
+If push includes config-driven features, verify config keys match code expectations.
+
+### Compliance Audit Trail
+
+Generate: `massu_audit_log`, `massu_audit_report`, `massu_validation_report`.
+
+## 5.5 Tier 4: Final Gate
+
+All tiers must pass:
+
+| Tier | Status |
+|------|--------|
+| Tier 1: Quick Checks | PASS/FAIL |
+| Tier 2: Test Suite + Regression | PASS/FAIL |
+| Tier 3: Security & Compliance | PASS/FAIL |
+
+---
+
+## Phase 5 Gate -> APPROVAL POINT #4: PUSH
+
+See `approval-points.md` for the exact format.
+
+After approval: `git push origin [branch]`, then monitor CI with `./scripts/ci-status.sh --wait --max-wait 300`. If CI fails, auto-run `/massu-ci-fix` protocol.

package/commands/massu-golden-path/references/phase-5.5-production-verify.md

@@ -0,0 +1,170 @@
+# Phase 5.5: Production Verification
+
+> Reference doc for `/massu-golden-path`. Return to main file for overview.
+
+```
+[GOLDEN PATH -- PHASE 5.5: PRODUCTION VERIFICATION]
+```
+
+**Core Principle**: A feature is NOT complete until it is verified working in production with real data. "Deployed" and "working" are two completely different things.
+
+---
+
+## 5.5.1 Wait for Deployment
+
+After push and CI success, verify the deployment landed:
+
+```bash
+# Check Vercel deployment status via MCP
+# list_deployments — confirm latest is READY state
+# get_runtime_logs — check for startup errors
+```
+
+If deployment failed or errored: diagnose, fix, and re-push (loop back to Phase 5).
+
+---
+
+## 5.5.2 Auto-Detect Changed Routes
+
+Before categorizing, auto-detect which production routes were affected:
+
+```bash
+# Extract changed app routes from git diff
+git diff origin/main --name-only -- 'src/app/' | grep -E 'page\.tsx|route\.ts' | \
+  sed 's|src/app/||; s|/page\.tsx||; s|/route\.ts||; s|\[([^]]*)\]|:$1|g'
+
+# Extract changed routers (for API verification)
+git diff origin/main --name-only -- 'src/server/api/routers/' | \
+  sed 's|src/server/api/routers/||; s|\.ts||'
+
+# Extract changed cron jobs
+git diff origin/main --name-only -- 'src/app/api/cron/'
+```
+
+Each detected route becomes a verification target. UI routes get Playwright checks, API routers get data-flow checks, crons get deferred verification entries.
+
+---
+
+## 5.5.3 Categorize Verifications
+
+Review ALL plan items and changed files. Categorize each into:
+
+| Category | Timing | Examples |
+|----------|--------|---------|
+| **Immediate** | Verify now | UI pages, API endpoints, DB schema+data, feature flags, env vars |
+| **Deferred** | Verify later | Cron jobs (wait for cycle), webhooks (wait for trigger), external API syncs, email delivery |
+
+Build a verification matrix:
+
+```markdown
+| # | Feature/Change | Category | Method | Expected Result | Status |
+|---|----------------|----------|--------|-----------------|--------|
+| PV-001 | [desc] | Immediate | Playwright | Page loads, data visible | PENDING |
+| PV-002 | [desc] | Immediate | DB query (PROD) | Row count > 0 | PENDING |
+| DV-001 | [desc] | Deferred | DB query after cron | New rows after deploy | PENDING |
+```
+
+---
+
+## 5.5.4 Run Immediate Verifications
+
+For each immediate item, verify with proof:
+
+### UI Changes
+Use Playwright MCP against production URL:
+1. `browser_navigate` to production page
+2. `browser_snapshot` — verify renders correctly
+3. `browser_console_messages` — check for JS errors
+4. `browser_click` / `browser_fill_form` — test interactions
+5. Verify data displays (not empty, not placeholder, not "undefined")
+
+### API/tRPC Changes
+- Hit production endpoints or navigate to pages that use them
+- Verify data loads and mutations work
+
+### Database Changes
+Query PROD (`mcp__supabase__PROD__execute_sql`):
+```sql
+-- Verify data flows, not just schema
+SELECT COUNT(*), MAX(created_at) FROM [table]
+WHERE created_at > '[deploy_timestamp]';
+```
+
+### Feature Flags / Config
+```sql
+-- Verify flags are set correctly
+SELECT key, enabled FROM feature_flags WHERE key IN ('[flags]');
+```
+
+### Integration Chains
+Trace the full chain: trigger -> process -> store -> display
+
+```markdown
+| Step | System | Verification | Status |
+|------|--------|-------------|--------|
+| Trigger | [source] | [how verified] | PASS/FAIL |
+| Process | [handler] | [how verified] | PASS/FAIL |
+| Store | [database] | [query result] | PASS/FAIL |
+| Display | [UI page] | [screenshot] | PASS/FAIL |
+```
+
+---
+
+## 5.5.5 Generate Deferred Checklist
+
+For items that can't be verified immediately, write to `session-state/deferred-verifications.md`:
+
+```markdown
+# Deferred Production Verifications
+
+**Generated**: [YYYY-MM-DD HH:MM PST]
+**Deploy Commit**: [hash]
+**Feature**: [name]
+
+## Pending
+
+### DV-001: [Description]
+- **Type**: Cron / Webhook / External API / Background Job
+- **Expected By**: [YYYY-MM-DD HH:MM PST]
+- **Query**:
+  ```sql
+  SELECT COUNT(*) FROM [table] WHERE [condition] AND created_at > '[deploy_time]';
+  ```
+- **Expected Result**: [specific condition]
+- **Status**: PENDING
+```
+
+These are surfaced by `/massu-bearings` in the next session and verified by `/massu-production-verify --deferred`.
+
+---
+
+## 5.5.6 Phase 5.5 Gate
+
+| Condition | Result |
+|-----------|--------|
+| All immediate verifications PASS, no deferred items | **PRODUCTION VERIFIED** — proceed to Phase 6 |
+| All immediate verifications PASS, deferred items exist | **VERIFIED + DEFERRED** — proceed to Phase 6, deferred items tracked |
+| Any immediate verification FAILS | **BLOCKED** — diagnose, fix, re-push, re-verify |
+
+**If BLOCKED**: Loop back. Fix the issue, commit, push (Phase 5 again), then re-run Phase 5.5.
+
+---
+
+## 5.5.7 Report Format
+
+```
+PHASE 5.5: PRODUCTION VERIFICATION
+--------------------------------------------------------------------------
+Deploy: [hash] — READY on Vercel
+Production URL: [url]
+
+Immediate Verifications: [X]/[Y] PASSED
+  PV-001: [feature] — PASS (proof: [detail])
+  PV-002: [feature] — PASS (proof: [detail])
+
+Deferred Verifications: [N] pending
+  DV-001: [feature] — check after [time] (saved to deferred-verifications.md)
+
+Status: VERIFIED / VERIFIED + DEFERRED / BLOCKED
+--------------------------------------------------------------------------
+```