@massu/core 0.4.0 → 0.4.2

package/commands/_shared-preamble.md

@@ -74,3 +74,13 @@ After every bug fix or issue resolution:
 2. Check if pattern scanner should be updated - Can the check be automated?
 3. Update session state - Record in `.claude/session-state/CURRENT.md`
 4. Search codebase-wide for same bad pattern (CR-9) and fix all instances
+
+Full protocol: [_shared-references/auto-learning-protocol.md](_shared-references/auto-learning-protocol.md)
+
+## Folder-Based Skills
+
+Some commands are folder-based skills (directories instead of single files). For these:
+1. Read the main `.md` file first (contains overview + START NOW)
+2. Check the `## Skill Contents` table for available reference docs
+3. Load reference docs on-demand as needed during execution
+4. Helper scripts in `scripts/` can be executed directly

package/commands/massu-batch.md

@@ -0,0 +1,327 @@
+---
+name: massu-batch
+description: "When user wants to apply the same code-only change across multiple files in parallel — 'batch update', 'apply to all', 'migrate these files'"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-batch
+
+# Massu Batch: Parallel Code Migration via Worktree Agents
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+---
+
+## Workflow Position
+
+```
+/massu-batch [migration] → /massu-simplify → /massu-commit → /massu-push
+```
+
+**This command is for CODE-ONLY migrations. It REFUSES database work.**
+
+---
+
+## What This Command Does
+
+Takes a migration description, identifies all affected files, splits them into batches, and spawns parallel agents in isolated git worktrees. Each agent transforms its files independently, runs checks, and the results merge back into your branch.
+
+**Best for**: Import renames, component swaps, API call updates, class name migrations, pattern replacements across 5+ files.
+
+**NOT for**: New features, database migrations, changes requiring cross-file coordination.
+
+---
+
+## EXECUTION PROTOCOL
+
+### Step 1: Parse Migration Description
+
+Read `$ARGUMENTS` for the migration description.
+
+If no arguments provided, ask:
+- **Search pattern**: What to find (glob pattern or grep pattern)
+- **Transformation**: What to change it to
+- **Scope**: Directory to limit search (default: `src/`)
+
+### Step 2: DB Guard (Safety Gate — MANDATORY)
+
+**This step CANNOT be skipped. No exceptions.**
+
+Check the migration description for these keywords:
+```
+migration, schema, ALTER, CREATE TABLE, DROP, column, RLS, GRANT,
+database, prisma, supabase, ctx.db, ctx.prisma, $queryRaw, execute_sql
+```
+
+And check target file paths for:
+```
+src/server/api/routers/
+src/lib/db
+prisma/
+supabase/migrations/
+```
+
+**If ANY check triggers**: HALT immediately with:
+
+```
+## DB GUARD: Migration Blocked
+
+This migration touches database-related code. Database migrations require
+sequential coordination across environments.
+
+/massu-batch is designed for code-only migrations:
+  - Import path changes
+  - Component library swaps
+  - API call updates
+  - Renaming patterns
+  - Style/class name migrations
+  - Utility function swaps
+
+To proceed with database work: /massu-create-plan → /massu-loop
+```
+
+**STOP HERE. Do not proceed. Do not offer workarounds.**
+
+### Step 3: Identify Affected Files
+
+```bash
+# Use Grep to find all files matching the migration pattern
+grep -rn "[search_pattern]" src/ --include="*.ts" --include="*.tsx" -l
+```
+
+If 0 files found: "No files match the migration pattern. Check your search pattern." STOP.
+If < 5 files found: "Only N files affected. Consider making these changes manually instead of using /massu-batch." Offer to proceed anyway or cancel.
+
+### Step 4: Planning Phase (Interactive — Requires User Approval)
+
+Split files into batches:
+- **Batch size**: 5-8 files per agent
+- **Minimum agents**: 2 (otherwise manual is faster)
+- **Maximum agents**: 15 (beyond this, consolidation risk increases)
+- **Grouping strategy**: Group files from the same directory together when possible
+
+Present the plan:
+
+```markdown
+## Batch Migration Plan
+
+**Migration**: [description]
+**Search pattern**: [pattern]
+**Total files**: N
+**Batches**: M agents x ~K files each
+
+| Batch | Files | Directory |
+|-------|-------|-----------|
+| 1 | file1.tsx, file2.tsx, file3.tsx, file4.tsx, file5.tsx | src/components/ |
+| 2 | file6.tsx, file7.tsx, file8.tsx, file9.tsx | src/app/ |
+| 3 | file10.tsx, file11.tsx, file12.tsx | src/lib/ |
+
+Each agent will:
+1. Apply the transformation to its assigned files
+2. Run pattern-scanner.sh --single-file on each changed file
+3. Run tsc type check
+4. Report results
+```
+
+**Wait for explicit user approval. Do NOT proceed without it.**
+
+### Step 5: Execution Phase (Parallel Worktree Agents)
+
+Spawn all agents simultaneously using the Agent tool with `isolation: "worktree"`:
+
+```
+FOR each batch (IN PARALLEL):
+  result_{batch_id} = Agent(
+    subagent_type="general-purpose",
+    isolation="worktree",
+    model="sonnet",
+    description="Batch {batch_id}: migrate {N} files",
+    prompt="
+      You are a CODE MIGRATION AGENT. Apply this transformation to the assigned files.
+
+      ## Migration
+      {migration_description}
+
+      ## Transformation Rule
+      FIND: {search_pattern}
+      REPLACE WITH: {replacement_pattern}
+
+      ## Assigned Files
+      {file_list_for_this_batch}
+
+      ## Instructions
+      For EACH file in your assignment:
+      1. Read the file completely
+      2. Apply the transformation — change ONLY what matches the pattern
+      3. Do NOT modify unrelated code
+      4. Do NOT add comments about the migration
+      5. Do NOT change formatting or whitespace beyond the transformation
+      6. Save the file
+
+      After ALL files are modified:
+      7. Run: ./scripts/pattern-scanner.sh --single-file [file] for each changed file
+      8. If pattern-scanner finds violations, fix them
+      9. Run: NODE_OPTIONS='--max-old-space-size=8192' npx tsc --noEmit
+      10. If tsc finds errors in your changed files, fix them
+
+      ## Output Format (MANDATORY)
+      Return this EXACT structure:
+
+      BATCH_ID: {batch_id}
+      FILES_MODIFIED: [count]
+      PATTERN_SCANNER: PASS | FAIL
+      TSC_CHECK: PASS | FAIL
+      CHANGES:
+      - [file]: [brief description of change]
+      - [file]: [brief description of change]
+      ERRORS: [any errors encountered, or NONE]
+    "
+  )
+END FOR
+```
+
+**All agents run simultaneously.** This is the core parallelization benefit.
+
+### Step 6: Consolidation Phase
+
+After ALL agents complete:
+
+1. **Collect results** from each agent
+2. **Check for failures**:
+   - If any agent's worktree has changes, the branch name is returned
+   - Failed agents: log the failure, mark batch as needs-retry
+3. **Merge worktree branches**:
+   ```bash
+   # For each successful agent's worktree branch:
+   git merge [worktree-branch] --no-edit
+   # If merge conflict: flag for manual resolution
+   ```
+4. **Handle conflicts**:
+   - Conflicts should be RARE since files don't overlap between batches
+   - If conflicts occur: report to user with conflicting files and stop
+   - User can resolve manually and re-run verification
+
+### Step 7: Verification Phase
+
+Run on the consolidated result:
+
+```bash
+# Full pattern scanner
+./scripts/pattern-scanner.sh
+
+# Full type check
+NODE_OPTIONS="--max-old-space-size=8192" npx tsc --noEmit
+
+# Build check
+npm run build
+```
+
+### Step 8: Output Structured Result
+
+```markdown
+## /massu-batch Results
+
+**Migration**: [description]
+**Total files**: N across M batches
+**Duration**: Xs
+
+| Batch | Files | Agent Status | Pattern Scanner | TSC |
+|-------|-------|-------------|-----------------|-----|
+| 1 | 5 | PASS | PASS | PASS |
+| 2 | 5 | PASS | PASS | PASS |
+| 3 | 3 | PASS | PASS | PASS |
+
+### Consolidated Verification
+
+| Check | Status |
+|-------|--------|
+| Pattern Scanner (full) | PASS / FAIL |
+| TypeScript (full) | PASS / FAIL |
+| Build | PASS / FAIL |
+
+BATCH_GATE: PASS
+
+### Changes Summary
+- [file]: [change]
+- [file]: [change]
+...
+
+### Next Steps
+1. Run /massu-simplify for efficiency review (recommended)
+2. Run /massu-commit to commit
+3. Run /massu-push to push
+```
+
+If verification fails:
+
+```
+BATCH_GATE: FAIL
+
+### Failures
+- [check]: [error details]
+
+### Recovery Options
+1. Fix the failing files manually, then re-run verification
+2. Run /massu-batch again with adjusted scope
+3. Abort and use /massu-loop for sequential implementation
+```
+
+### Step 9: Cleanup
+
+Worktrees are auto-cleaned by the Agent tool. If any remain:
+
+```bash
+# List lingering worktrees
+git worktree list
+
+# Remove if needed (user confirmation required)
+git worktree remove [path]
+```
+
+---
+
+## SAFETY RULES
+
+| Rule | Enforcement |
+|------|-------------|
+| **No database changes** | DB guard inline keyword check + path check |
+| **User approval required** | Interactive approval before execution phase |
+| **No file overlap between batches** | Planning phase ensures each file appears in exactly one batch |
+| **Per-agent verification** | Each agent runs pattern-scanner + tsc before completing |
+| **Consolidated verification** | Full checks run after merge |
+| **Merge conflicts halt execution** | No automatic conflict resolution |
+
+---
+
+## EXAMPLES
+
+```bash
+# Rename an import path
+/massu-batch "change all imports from @/components/ui/old-button to @/components/ui/button"
+
+# Replace a deprecated hook
+/massu-batch "replace all useToast() calls with the new toast() pattern from @/components/ui/sonner"
+
+# Migrate CSS classes
+/massu-batch "replace className='container mx-auto' with className='page-container' in all page files"
+
+# Update API calls
+/massu-batch "update all fetch('/api/v1/...') calls to fetch('/api/v2/...') in src/lib/integrations/"
+```
+
+---
+
+## WHEN NOT TO USE THIS COMMAND
+
+| Scenario | Use Instead |
+|----------|-------------|
+| Database/schema changes | `/massu-loop` |
+| < 5 files affected | Manual changes + `/massu-simplify` |
+| New feature development | `/massu-create-plan` → `/massu-loop` |
+| Cross-file dependencies | `/massu-loop` (sequential is safer) |
+| Changes needing plan coverage | `/massu-loop` (has plan audit loop) |
+
+## Gotchas
+
+- **NEVER for database work** — batch migrations are CODE-ONLY. Database migrations must be applied to all environments in sequence, which requires coordination that parallel agents cannot provide
+- **Worktree isolation** — each agent runs in a git worktree. Changes must be mergeable. Agents editing the same file will cause merge conflicts
+- **One task per agent** — each worktree agent gets exactly one plan item. Never combine unrelated items in a single agent

package/commands/massu-bearings.md

@@ -0,0 +1,204 @@
+---
+name: massu-bearings
+description: "When user starts a new session, says 'good morning', asks 'where was I', 'what should I work on', or needs session orientation after being away"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+name: massu-bearings
+
+# Massu Bearings: Session Orientation
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+---
+
+## Purpose
+
+Answer one question: **"Where am I and what should I focus on?"**
+
+This is a READ-ONLY orientation command. It reads session state, recent history, parked ideas, and open plans, then presents a concise human-readable briefing. It does NOT modify any files.
+
+**Privilege level**: Level 1 (read-only) — same as `massu-create-plan` in recovery.md hierarchy.
+
+**This does NOT replace the recovery protocol** (`protocols/recovery.md`). Recovery is the full post-compaction restoration procedure. Bearings is the quick "good morning" briefing that layers on top.
+
+---
+
+## Data Sources
+
+Read these in parallel where possible:
+
+| # | Source | What to extract |
+|---|--------|----------------|
+| 1 | `session-state/CURRENT.md` | Active task, status, decisions, blockers |
+| 2 | Last 5 session archives (by date) | Recent completed work, patterns |
+| 3 | `session-state/squirrels.md` | Parked ideas count and list |
+| 4 | `.claude/plans/*.md` | Any open/in-progress plans |
+| 5 | `git log --oneline -10` | Recent commits for context |
+| 6 | `git diff --stat` | Any uncommitted changes |
+| 7 | `memory/corrections.md` | Active correction rules |
+| 8 | `memory/auto-patterns/*.md` | Auto-extracted pattern candidates (status: candidate) |
+| 9 | `.claude/metrics/command-scores.jsonl` | Command quality scores — flag any below 60% on last 3 runs |
+| 10 | `.claude/metrics/command-invocations.jsonl` | Command usage frequency — top/least used in last 7 days |
+| 11 | `.claude/metrics/bearings-history.jsonl` | Previous bearings runs — show trends |
+| 12 | `.claude/commands/` (ls -d */`) | Detect folder-based skills (directories vs flat files) |
+
+---
+
+## Output Format
+
+Present directly to terminal. Do NOT write to a file.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+BEARINGS — [date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CURRENT STATE
+  Status: [active task or "No active task"]
+  Branch: [current git branch]
+  Uncommitted: [N files changed / clean]
+
+STILL OPEN
+  - [item 1 from CURRENT.md or recent archives]
+  - [item 2]
+
+RECENTLY COMPLETED (last 3-5)
+  - [commit hash] [message] ([date])
+  - [commit hash] [message] ([date])
+
+OPEN PLANS
+  - [plan name] — [status, items remaining]
+  (or "No open plans")
+
+PARKED IDEAS ([N] squirrels)
+  - [idea 1]
+  - [idea 2]
+  (or "No parked squirrels")
+
+SUGGESTED FOCUS
+  1. [highest priority item — why]
+  2. [next priority item — why]
+  3. [optional third item]
+
+PATTERN CANDIDATES ([N] pending review)
+  - [date] [title] (confidence: X/15) — review and promote or dismiss
+  (or "No auto-extracted patterns")
+
+COMMAND HEALTH ALERTS
+  ! [command] — [X]% on last 3 runs. Weakest: [check_name]
+  (or "All commands healthy (above 60%)")
+
+COMMAND USAGE (last 7 days)
+  Top:   [command] (N invocations), [command] (N), [command] (N)
+  Least: [command] (N invocations), [command] (N)
+  (or "No invocation data yet")
+
+FOLDER-BASED SKILLS
+  [list any commands that are directories: massu-golden-path, massu-debug, massu-loop, massu-data]
+  (or "No folder-based skills detected")
+
+ACTIVE WARNINGS
+  - [any correction rules or memory enforcement reminders]
+  (or "No active warnings")
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Suggested Focus Logic
+
+Prioritize items in this order:
+1. **Blockers** — anything marked as blocked in CURRENT.md
+2. **In-progress tasks** — partially completed work from last session
+3. **Open plan items** — next items in an active plan
+4. **Aging squirrels** — ideas parked > 7 days ago (mention but don't auto-promote)
+5. **New work** — only if nothing else is open
+
+Keep to 2-3 items. This is a focus list, not an inventory.
+
+---
+
+## Auto-Extracted Pattern Candidates
+
+Check `memory/auto-patterns/` for files with `status: candidate` in frontmatter. For each candidate:
+- Read the title and confidence score
+- Display in the PATTERN CANDIDATES section
+- If confidence >= 12/15, mark as "HIGH — consider promoting to corrections.md"
+- If confidence 8-11/15, mark as "MEDIUM — review in next implementation session"
+
+To act on candidates:
+- **Promote**: Move key content to `memory/corrections.md` or `patterns-quickref.md`, change status to `promoted`
+- **Dismiss**: Change status to `dismissed` (auto-cleanup after 60 days)
+- **Ignore**: Leave as `candidate` (auto-dismissed after 30 days)
+
+---
+
+## Command Health Alerts Logic
+
+Read `.claude/metrics/command-scores.jsonl`. If the file is empty or missing, show "All commands healthy (above 60%)".
+
+For each command in the file:
+1. Parse all JSONL lines for that command
+2. Take the last 3 runs
+3. Calculate average pass rate (e.g., "3/4" = 75%, "2/5" = 40%)
+4. If average < 60%, flag as alert with the weakest check name
+5. Display in COMMAND HEALTH ALERTS section
+
+If no commands are below 60%, show "All commands healthy (above 60%)".
+
+---
+
+## Edge Cases
+
+- **No CURRENT.md**: Say "No active session state. Starting fresh."
+- **No archives**: Say "No session history found. This appears to be a new project."
+- **No squirrels.md**: Skip the squirrels section (don't create the file — that's `/massu-squirrels`' job)
+- **No open plans**: Say "No open plans"
+- **No corrections.md**: Skip the warnings section
+
+---
+
+## Gotchas
+
+- **Read-only command** — bearings READS state, it does NOT modify files or start work. Wait for user direction after presenting findings
+- **Don't start working unprompted** — after showing bearings, wait for the user to tell you what to work on. Don't assume the suggested focus is approved
+- **Session state may be stale** — CURRENT.md may be from a previous session that ended abruptly. Cross-reference with git log for ground truth
+- **Archive files are historical** — session-state/archive/ files show past work but should not drive current decisions unless user references them
+
+---
+
+## Bearings History
+
+After presenting the bearings output, append a JSONL line to `.claude/metrics/bearings-history.jsonl`:
+
+```json
+{"timestamp":"ISO","branch":"main","uncommitted":3,"open_plans":1,"squirrels":5,"suggested_focus":"item"}
+```
+
+On next bearings run, read last 5 entries from `bearings-history.jsonl` to show trends:
+- "Uncommitted files trending up: 1 → 3 → 5"
+- "Open plans stable at 1"
+- If no history file exists, skip trends.
+
+---
+
+## Command Usage Logic
+
+Read `.claude/metrics/command-invocations.jsonl`. Filter to last 7 days by `timestamp` field. Group by `skill`, count invocations, sort descending. Show top 3 and bottom 2. If no data exists, show "No invocation data yet".
+
+---
+
+## Folder-Based Skill Detection
+
+Run `ls -d .claude/commands/*/` to find commands that are directories. Display the list in FOLDER-BASED SKILLS section. Each folder-based skill has a `## Skill Contents` table in its main file listing sub-files.
+
+---
+
+## START NOW
+
+1. Read all data sources in parallel (CURRENT.md, archives, squirrels, plans, git log, git diff, corrections, metrics, bearings-history)
+2. Synthesize into the output format above
+3. Present to terminal
+4. Append bearings-history.jsonl entry
+5. Do NOT start working on anything — wait for user to choose what to focus on

package/commands/massu-ci-fix.md

@@ -0,0 +1,148 @@
+---
+name: massu-ci-fix
+description: "When CI fails after push — auto-diagnoses failures, fixes, commits, and re-pushes. 'ci fix', 'fix ci', 'ci failed', 'workflow failed'"
+allowed-tools: Bash(*), Read(*), Edit(*), Write(*), Grep(*), Glob(*)
+---
+name: massu-ci-fix
+
+# Massu CI Fix: Auto-Diagnose and Fix CI Failures
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding.
+
+## Objective
+
+Automatically pull CI failure logs, diagnose root cause, fix, commit, and re-push. Zero cognitive load.
+
+---
+
+## EXECUTION FLOW
+
+### Step 1: Identify Failed Runs
+
+```bash
+# Get failed runs for current commit
+gh run list --commit $(git rev-parse HEAD) --limit 5 --json status,conclusion,name,databaseId | jq '.[] | select(.conclusion == "failure")'
+```
+
+If no failures found, check the most recent run on the branch:
+```bash
+gh run list --branch $(git branch --show-current) --limit 3
+```
+
+### Step 2: Pull Failure Logs
+
+For EACH failed run:
+```bash
+gh run view [RUN_ID] --log-failed 2>&1 | tail -100
+```
+
+Extract:
+- **Failed step name**
+- **Error message**
+- **File and line number** (if available)
+- **Exit code**
+
+### Step 3: Diagnose
+
+Map the failure to a known pattern:
+
+| CI Step | Common Cause | Fix Strategy |
+|---------|-------------|--------------|
+| TypeScript | Type error in committed code | Fix the type error |
+| ESLint | Lint violation | Fix or disable with justification |
+| Build | Import error, missing dep | Fix import or install dep |
+| Tests | Test failure | Fix test or code |
+
+### Step 4: Fix
+
+1. Apply the fix
+2. Run the same check locally to verify:
+   ```bash
+   # Run the specific check that failed
+   npm run build  # or whatever CI step failed
+   ```
+3. Verify fix passes locally
+
+### Step 5: Commit and Re-Push
+
+```bash
+git add [fixed files]
+git commit -m "fix(ci): [description of fix]
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+git push origin $(git branch --show-current)
+```
+
+### Step 6: Monitor Re-Run
+
+```bash
+# Wait for CI to complete (check periodically)
+gh run list --branch $(git branch --show-current) --limit 1
+```
+
+If CI fails again, loop back to Step 2 (max 3 attempts).
+
+---
+
+## LOOP CONTROL
+
+```
+attempt = 0
+MAX_ATTEMPTS = 3
+
+WHILE attempt < MAX_ATTEMPTS:
+  attempt += 1
+
+  1. Pull failure logs
+  2. Diagnose
+  3. Fix
+  4. Verify locally
+  5. Commit + push
+  6. Wait for CI
+
+  IF CI passes:
+    Output: "CI fixed in {attempt} attempt(s)"
+    BREAK
+  ELSE:
+    Output: "Attempt {attempt} failed, retrying..."
+    CONTINUE
+
+IF attempt == MAX_ATTEMPTS AND still failing:
+  Output: "CI still failing after 3 attempts. Manual investigation needed."
+  Show: last failure logs
+```
+
+---
+
+## OUTPUT FORMAT
+
+```
+== CI FIX ==
+
+Failed Run: [workflow name] (#[run_id])
+Failed Step: [step_name]
+Error: [error message]
+
+Diagnosis: [root cause]
+Fix: [what was changed]
+
+Local Verification: [check command] -> PASS
+Committed: fix(ci): [description]
+Pushed: origin/[branch]
+
+CI Status: Monitoring...
+  [step]: success
+
+CI FIXED (1 attempt)
+```
+
+---
+
+## START NOW
+
+1. Identify failed CI runs
+2. Pull logs for each failure
+3. Diagnose, fix, verify locally
+4. Commit and push
+5. Monitor CI
+6. Loop if needed (max 3)