@massu/core 0.4.0 → 0.4.2

package/commands/massu-incident.md

@@ -0,0 +1,162 @@
+---
+name: massu-incident
+description: "When a bug is confirmed, a production issue is found, or user reports 'this broke', 'incident', 'production error' — triggers incident documentation protocol"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-incident
+
+# Massu Incident: Automated Post-Mortem & Prevention Pipeline
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+## Objective
+
+When a bug is discovered that an audit should have caught, execute a
+structured post-mortem that AUTOMATICALLY:
+1. Logs the incident to INCIDENT-LOG.md
+2. Proposes a new CR rule or VR-* check
+3. Proposes a pattern-scanner addition
+4. Updates relevant protocol files with incident reminder
+
+## INPUT
+
+User provides: description of what went wrong and how it was discovered.
+
+---
+
+## STEP 1: CAPTURE INCIDENT DETAILS
+
+Gather from user and investigation:
+
+```markdown
+### Incident Capture
+- **What happened**: [user-visible bug]
+- **Root cause**: [why it happened]
+- **Discovery**: USER / AUDIT / AUTOMATED
+- **Impact**: [what broke, who was affected]
+- **Files involved**: [list]
+- **Which audit should have caught this**: [massu-plan / massu-loop / massu-commit / etc.]
+- **Why the audit missed it**: [specific reason]
+```
+
+## STEP 2: DETERMINE NEXT INCIDENT NUMBER
+
+```bash
+grep -c "^## Incident #" .claude/incidents/INCIDENT-LOG.md
+# Next number = count + 1
+```
+
+## STEP 3: LOG TO INCIDENT-LOG.md
+
+Append to `.claude/incidents/INCIDENT-LOG.md`:
+
+```markdown
+## Incident #[N]: [Short Title]
+
+**Date**: [YYYY-MM-DD]
+**Severity**: CRITICAL / HIGH / MEDIUM
+**Discovery**: USER / AUDIT / AUTOMATED
+**Root Cause**: [description]
+**Files Involved**: [list]
+**What Should Have Caught It**: [audit/protocol name]
+**Why It Was Missed**: [reason]
+**Prevention Added**: [CR-XX / VR-XX / pattern-scanner rule]
+**Lesson**: [one-line lesson]
+```
+
+## STEP 4: PROPOSE PREVENTION
+
+### 4a: New CR Rule (if pattern is new)
+If the failure mode isn't covered by existing CRs:
+- Propose CR-[N+1] with rule text
+- Add to CLAUDE.md CR table
+
+### 4b: New VR-* Check (always)
+Every incident MUST produce a verifiable check:
+- Define the verification command
+- Add to VR table in CLAUDE.md
+- Specify when to run it
+
+### 4c: Pattern Scanner Rule (if automatable)
+If the failure can be caught by grep:
+- Add rule to `scripts/pattern-scanner.sh`
+- Test it catches the original failure
+- Verify it doesn't false-positive
+
+### 4d: Protocol Update (always)
+Add incident reminder to the protocol that should have caught it:
+- Add `## INCIDENT #[N] REMINDER` section
+- Explain the failure mode
+- Explain what to check for
+
+## STEP 5: VERIFY PREVENTION WORKS
+
+```bash
+# If pattern-scanner rule added:
+./scripts/pattern-scanner.sh
+
+# If VR-* check added, run it:
+[verification command]
+```
+
+## OUTPUT
+
+```markdown
+## INCIDENT POST-MORTEM COMPLETE
+
+### Incident #[N]: [Title]
+- Logged to: INCIDENT-LOG.md
+- CR rule: [CR-XX added/updated]
+- VR check: [VR-XX added]
+- Pattern scanner: [rule added / not automatable]
+- Protocol updated: [which protocol]
+
+### Prevention Chain
+1. Pattern scanner: Will catch at pre-push
+2. Protocol: Explicit reminder in [protocol name]
+3. CR rule: Documented in CLAUDE.md
+4. MEMORY.md: Wrong vs correct pattern recorded for all future sessions
+
+**This failure mode is now prevented at 4 levels.**
+```
+
+## STEP 6: UPDATE MEMORY.md (MANDATORY)
+
+Every incident MUST be recorded in `memory/MEMORY.md` with the wrong vs correct pattern:
+
+```markdown
+## Critical Rule: CR-[XX] - [Short Title] (Incident #[N], [date])
+- [Wrong pattern description]
+- [Correct pattern description]
+- [Key insight that prevents recurrence]
+```
+
+This ensures that even without accessing the incident log, future sessions
+will have the pattern in their system prompt via MEMORY.md.
+
+## STEP 7: CODEBASE-WIDE SEARCH (CR-9)
+
+Search the ENTIRE codebase for the same bad pattern that caused the incident:
+```bash
+grep -rn "[bad_pattern]" src/ --include="*.ts" --include="*.tsx"
+```
+Fix ALL instances found. The incident that triggered this post-mortem
+may not be the only occurrence.
+
+## STEP 8: COUPLING CHECK
+
+If the incident involved a feature that was implemented but not exposed in the UI, run the coupling check to verify all backend procedures have UI exposure:
+
+```bash
+./scripts/check-coupling.sh
+# Expected: Exit 0 (no uncoupled backend features)
+```
+
+**Any backend procedure without UI exposure is a hidden feature that cannot be used - fix immediately.**
+
+## Gotchas
+
+- **Update INCIDENT-LOG.md** — every incident gets a numbered entry in `incidents/INCIDENT-LOG.md` with root cause, prevention, and CR reference
+- **Add CR if pattern emerges** — if the incident reveals a repeatable failure pattern, add a new Canonical Rule to CLAUDE.md
+- **Update pattern scanner** — if the incident could be caught by static analysis, add a check to `scripts/pattern-scanner.sh`
+- **Never blame the user** — incidents are system failures. Frame prevention as system guardrails, not user discipline

package/commands/massu-plan-audit.md

@@ -0,0 +1,64 @@
+---
+name: massu-plan-audit
+description: "When user wants to create a plan AND audit it to zero gaps in one flow, says 'plan audit', 'create and audit plan', or needs the combined create-then-audit workflow"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*), Task(*)
+---
+
+# Massu Plan-Audit: Autonomous Plan Creation + Zero-Gap Audit
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+## Workflow Position
+This command COMBINES /massu-create-plan + /massu-plan into ONE uninterrupted flow.
+**DISTINCT FROM**: `/massu-plan` (audit-only loop) and `/massu-create-plan` (plan creation only). This command is the autonomous combination of both.
+
+## What This Command Does
+1. Phase A: Create the plan (follows massu-create-plan protocol)
+2. Phase B: IMMEDIATELY transition to audit loop (follows massu-plan protocol)
+3. Phase C: Loop until zero gaps (no user intervention needed)
+4. Phase D: Present zero-gap plan to user and STOP
+
+## CRITICAL: NO MODE CONFUSION
+- Do NOT enter plan mode. Work in normal mode throughout.
+- Do NOT ask user "should I audit now?" — just do it.
+- Do NOT exit early after plan creation — audit is MANDATORY.
+- The ONLY stopping point is after a clean zero-gap audit pass.
+
+## Execution Protocol
+
+### Phase A: Plan Creation
+1. Parse $ARGUMENTS as task description
+2. Follow massu-create-plan Phase 1-6 (requirements, DB check, codebase check, patterns, security, generation)
+3. Write plan document to `.claude/plans/[date]-[name].md`
+4. Do NOT present plan to user yet — proceed directly to Phase B
+
+### Phase B: Audit Loop (IMMEDIATE — no pause)
+5. Spawn massu-plan-auditor subagent for audit iteration 1
+6. Parse GAPS_DISCOVERED from result
+7. If gaps > 0: fix plan document, spawn another iteration
+8. If gaps == 0: proceed to Phase C
+9. Maximum 10 iterations
+
+### Phase C: Present to User
+10. Output plan summary with zero-gap certification
+11. STOP and WAIT for user to run /massu-loop
+
+## Rules
+| Rule | Meaning |
+|------|---------|
+| No plan mode | Stay in normal mode throughout |
+| No pauses between phases | A→B transition is automatic |
+| Audit is mandatory | Creating plan without auditing = INCOMPLETE |
+| Zero gaps required | Only zero-gap plan is presentable |
+| Max 10 audit iterations | Bail and report if not converging |
+| **VR-SPEC-MATCH** | For EVERY plan item with specific CSS classes, component names, layout instructions, or visual specs — the plan MUST include those EXACT strings as verifiable specs. If a plan item says "add a sidebar" without specifying classes/structure, that is a specificity gap. |
+
+## Literal Spec Verification (Auditor Instruction)
+
+**MANDATORY during every audit pass**: For EVERY plan item that contains specific CSS classes, component names, layout instructions, or visual specifications:
+
+1. **Extract** the literal strings from the plan item (e.g., `ml-6`, `border-l-2`, `grid-cols-3`, `<Badge variant="outline">`)
+2. **If auditing a plan document (pre-implementation)**: Verify each item has enough literal spec detail to enable VR-SPEC-MATCH during implementation. If an item says "add a card" but doesn't specify classes → **SPECIFICITY GAP**
+3. **If auditing implementation (post-implementation)**: Grep the implementation files for those EXACT strings. Missing string = **VR-SPEC-MATCH failure = gap**
+
+This prevents the failure mode where plans specify visual requirements loosely and implementations diverge from intent.

package/commands/massu-recap.md

@@ -0,0 +1,164 @@
+---
+name: massu-recap
+description: "When user says 'done for today', 'wrapping up', 'end session', 'handoff', or is about to close the terminal"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-recap
+
+# Massu Recap: Session Handoff
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+---
+
+## Purpose
+
+Answer one question: **"What happened this session and what does the next session need to know?"**
+
+This command captures the current session's work, updates session state, and ensures nothing is lost before the session ends. It is the counterpart to `/massu-bearings` — recap writes the handoff note that bearings reads tomorrow.
+
+**Privilege level**: Level 1.5 (reads state + writes to session-state files only, no code changes).
+
+---
+
+## Data Sources
+
+Read these to build the session summary:
+
+| # | Source | What to extract |
+|---|--------|----------------|
+| 1 | `session-state/CURRENT.md` | What was planned, active task |
+| 2 | `git log --since="6am" --oneline` | Commits made this session |
+| 3 | `git diff --stat` | Uncommitted changes |
+| 4 | `session-state/squirrels.md` | Ideas parked during session |
+| 5 | `.claude/plans/*.md` | Plan progress (items completed vs total) |
+| 6 | `memory/MEMORY.md` | Whether memory was updated this session |
+
+---
+
+## Actions (Execute in Order)
+
+### Step 1: Generate Session Summary
+
+Present to terminal:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RECAP — [date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+WHAT GOT DONE
+  - [commit hash] [message]
+  - [commit hash] [message]
+  - [non-committed work: files changed, what was done]
+  (or "No commits this session")
+
+WHAT'S STILL OPEN
+  - [incomplete item 1 — status/progress]
+  - [incomplete item 2]
+  (or "All planned work completed")
+
+NEW DISCOVERIES
+  - [issue found but not yet addressed]
+  - [pattern violation noticed]
+  (or "None")
+
+SQUIRRELS ADDED ([N] new)
+  - [idea 1]
+  (or "No new squirrels this session")
+
+UNCOMMITTED CHANGES
+  [git diff --stat output or "Working tree clean"]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 2: Memory Persistence Check
+
+Check whether significant work was done this session:
+
+| Signal | Indicates significant work |
+|--------|---------------------------|
+| Commits made | Yes |
+| Plan items completed | Yes |
+| Bugs fixed | Yes |
+| New patterns discovered | Yes |
+| User corrections received | Yes |
+| Architecture decisions made | Yes |
+
+If significant work detected:
+```
+MEMORY CHECK
+  Significant work detected: [list signals]
+  Memory updated this session: YES / NO
+
+  [If NO]: You should persist key learnings to memory/ before ending.
+  Suggested memory writes:
+    - [topic]: [what to record]
+```
+
+If no significant work: skip this section.
+
+### Step 3: Update Session State
+
+Update `session-state/CURRENT.md` with:
+- Final status of the session's work
+- Any open items carrying forward
+- Failed approaches (if any)
+- Next steps for the next session
+
+### Step 4: Archive Decision
+
+If the active task in CURRENT.md is fully complete:
+- Ask user: "Task [name] appears complete. Archive session state? (yes/no)"
+- If yes: `mv session-state/CURRENT.md session-state/archive/YYYY-MM-DD-[desc].md`
+- Create fresh CURRENT.md for next session
+- If no: leave CURRENT.md as-is
+
+If the task is still in progress:
+- Do NOT archive — just update CURRENT.md with current state
+- Do NOT ask about archiving
+
+---
+
+## What Recap Does NOT Do
+
+- Does NOT commit code (use `/massu-commit`)
+- Does NOT push to remote (use `/massu-push`)
+- Does NOT modify source code or configuration
+- Does NOT auto-promote squirrels (that requires explicit `/massu-squirrels promote`)
+- Does NOT write to memory/ files directly (it reminds you to, but doesn't do it for you)
+
+---
+
+## Edge Cases
+
+- **No CURRENT.md**: Create one with the session summary as the initial content
+- **No commits today**: Focus on uncommitted changes and discoveries
+- **No squirrels.md**: Skip the squirrels section
+- **Multiple sessions in one day**: Use `git log --since="6am"` to capture the current session (adjust if user started later)
+- **Session was just reading/research**: Still worth a recap — record what was learned and any decisions made
+
+---
+
+## Recap History
+
+After presenting the recap output, append a JSONL line to `.claude/metrics/recap-history.jsonl`:
+
+```json
+{"timestamp":"ISO","session_duration_approx":"3h","commits":2,"plans_completed":1,"incidents":0,"memories_written":3}
+```
+
+On next recap, read last 3 entries from `recap-history.jsonl` to compare session productivity. If no history file exists, skip comparisons.
+
+---
+
+## START NOW
+
+1. Read all data sources in parallel
+2. Generate and present the session summary
+3. Run the memory persistence check
+4. Update CURRENT.md with final state
+5. Append recap-history.jsonl entry
+6. If task is complete, ask about archiving
+7. Confirm: "Recap complete. Ready for next session."

package/commands/massu-scaffold-hook.md

@@ -0,0 +1,96 @@
+---
+name: massu-scaffold-hook
+description: "When user wants to create a new Claude Code hook — scaffolds the hook script, adds to settings.json, sets up profile gating"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New Hook
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+Creates a complete Claude Code hook following the 3-tier profile system.
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `scripts/hooks/[hook-name].sh` | Hook script |
+| Entry in `.claude/settings.json` | Hook registration under lifecycle event |
+
+## Hook Lifecycle Events
+
+| Event | Fires When | Use For |
+|-------|-----------|---------|
+| `PreToolUse` | Before a tool runs | Blocking destructive ops, validation, logging |
+| `PostToolUse` | After a tool runs | Auditing, pattern scanning, metrics |
+| `SessionStart` | Session starts/resumes/compacts | Context injection, state loading |
+
+## Template — Hook Script
+
+```bash
+#!/usr/bin/env bash
+# [Hook Name] — [brief description]
+# Profile: [minimal|standard|strict]
+source "$(dirname "$0")/hook-gate.sh" [tier] [hook-name] 2>/dev/null || true
+set -euo pipefail
+
+# Read tool input from stdin
+TOOL_INPUT=$(cat)
+
+# Extract relevant fields (adapt per event type)
+# For PreToolUse: tool_input contains the tool's parameters
+# For PostToolUse: tool_input contains tool output + parameters
+
+# Your hook logic here
+
+# Output options:
+# - Exit 0 silently (no feedback)
+# - Echo JSON for structured feedback:
+#   echo '{"decision":"block","reason":"..."}'  (PreToolUse only)
+#   echo '{"message":"..."}' (advisory feedback)
+
+exit 0
+```
+
+## Template — settings.json Entry
+
+```json
+{
+  "matcher": "ToolName|OtherTool",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "PROFILE=${LIMN_HOOK_PROFILE:-strict}; [ \"$PROFILE\" = \"minimal\" ] && exit 0; bash \"$CLAUDE_PROJECT_DIR/scripts/hooks/hook-name.sh\""
+    }
+  ]
+}
+```
+
+## Profile Tiers
+
+| Tier | When to Use | Gate Pattern |
+|------|------------|--------------|
+| `critical` | Security, secrets, rate limiting | NO gate — always runs |
+| `standard` | Pattern feedback, session lifecycle | `source hook-gate.sh standard hook-name` |
+| `strict` | Advisory, CSS audit, auto-review | `source hook-gate.sh strict hook-name` |
+
+## Gotchas
+
+- **stdin piping**: Hook receives tool input via stdin — `TOOL_INPUT=$(cat)` must be first
+- **Exit codes**: Exit 0 = success/allow, non-zero = hook failure (not tool blocking)
+- **hook-gate.sh sourcing**: MUST use `2>/dev/null || true` suffix (hook-gate may not exist in CI)
+- **Inline PROFILE check**: settings.json entry needs `PROFILE=${LIMN_HOOK_PROFILE:-strict}` prefix for minimal profile bypass
+- **jq dependency**: Use `jq` for JSON parsing (installed on dev machine), never grep for JSON fields
+- **Performance**: Hooks run on every tool invocation — keep under 10ms for standard tier
+
+## Process
+
+1. Ask user: What event? What tool? What should the hook do?
+2. Determine profile tier (critical/standard/strict)
+3. Create hook script in `scripts/hooks/`
+4. Add entry to `.claude/settings.json` under appropriate event
+5. Test by invoking the relevant tool
+
+## START NOW
+
+Ask the user what the hook should do, which lifecycle event it fires on, and which tool it should match.

package/commands/massu-scaffold-page.md

@@ -0,0 +1,108 @@
+---
+name: massu-scaffold-page
+description: "When user wants to create a new page, route, or section in the app — scaffolds the page component, layout, loading/error states, and tRPC integration"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New Page
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+Creates a complete Next.js App Router page following all project patterns.
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Main page component with Suspense boundary |
+| `loading.tsx` | Skeleton loading state |
+| `error.tsx` | Error boundary with retry |
+
+## Template
+
+### page.tsx
+```tsx
+import { Suspense } from 'react';
+import { PageContent } from './page-content';
+import Loading from './loading';
+
+export default function Page() {
+  return (
+    <div className="page-container">
+      <Suspense fallback={<Loading />}>
+        <PageContent />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### page-content.tsx (with params)
+```tsx
+'use client';
+
+import { use } from 'react';
+import { api } from '@/trpc/react';
+
+export function PageContent({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = use(params);
+  const { data, isLoading } = api.routerName.getById.useQuery({ id });
+
+  if (isLoading) return <Loading />;
+
+  return (
+    <>
+      <PageHeader title="Page Title" />
+      {/* Page content */}
+    </>
+  );
+}
+```
+
+### loading.tsx
+```tsx
+import { Skeleton } from '@/components/ui/skeleton';
+
+export default function Loading() {
+  return (
+    <div className="page-container">
+      <Skeleton className="h-8 w-48 mb-6" />
+      <Skeleton className="h-64 w-full" />
+    </div>
+  );
+}
+```
+
+### error.tsx
+```tsx
+'use client';
+
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div className="page-container">
+      <h2>Something went wrong</h2>
+      <p className="text-muted-foreground">{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Gotchas
+
+- **ALWAYS use `page-container`** class on root div — never `container mx-auto`
+- **Suspense boundaries** are REQUIRED for pages using `use(params)` or `useSearchParams()`
+- **protectedProcedure** for ALL tRPC queries that need auth
+- **Breadcrumbs**: Add to PageHeader if page is nested (e.g., `/dashboard/settings/[id]`)
+
+## Process
+
+1. Ask user: What URL path? What data does it fetch?
+2. Determine route segment: `src/app/(app)/[section]/[subsection]/`
+3. Create all 3 files (page.tsx, loading.tsx, error.tsx)
+4. If data-fetching: verify tRPC router exists, add query
+5. Run `npx tsc --noEmit` to verify types
+
+## START NOW
+
+Ask the user what page to create and where it should live in the route hierarchy.