@massu/core 0.4.2 → 0.6.0

package/README.md

@@ -0,0 +1,40 @@
+# @massu/core
+
+AI Engineering Governance MCP Server — session memory, feature registry, code intelligence, and rule enforcement for AI coding assistants.
+
+## Quick Start
+
+```bash
+npx massu init
+```
+
+This sets up the MCP server, configuration, and lifecycle hooks in one command.
+
+## What is Massu?
+
+Massu is a source-available [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that adds governance capabilities to AI coding assistants like Claude Code. It provides:
+
+- **51 MCP Tools** — quality analytics, cost tracking, security scoring, dependency analysis, and more
+- **11 Lifecycle Hooks** — pre-commit gates, security scanning, intent suggestion, and session management
+- **3-Database Architecture** — code graph (read-only), data (imports/mappings), and memory (sessions/analytics)
+- **Config-Driven** — all project-specific data lives in `massu.config.yaml`
+
+## Usage
+
+After `npx massu init`, your AI assistant gains access to all governance tools automatically via the MCP protocol.
+
+```bash
+# Health check
+npx massu doctor
+
+# Validate configuration
+npx massu validate-config
+```
+
+## Documentation
+
+Full documentation at [massu.ai](https://massu.ai).
+
+## License
+
+[BSL 1.1](https://github.com/massu-ai/massu/blob/main/LICENSE) — source-available. Free to use, modify, and distribute. See LICENSE for full terms.

package/agents/massu-architecture-reviewer.md

@@ -0,0 +1,104 @@
+---
+name: massu-architecture-reviewer
+description: Adversarial architecture-focused review agent that checks for design issues
+---
+
+# Massu Architecture Reviewer Agent
+
+## Purpose
+Perform an architecture-focused adversarial review. Hunt for design issues, coupling problems, and maintainability risks.
+
+## Trigger
+Spawned by massu-loop multi-perspective review phase, or manually via Task tool.
+
+## Scope
+- Read access to all source files, CLAUDE.md, pattern files
+- Execute grep/glob/bash for analysis
+- NO write access (review only)
+
+## Adversarial Architecture Mindset
+
+**You are a senior architect reviewing this code for a production system.** Your job is to find design flaws that will cause problems at scale.
+
+## Workflow
+
+### Step 1: Map the Changes
+- List all files changed/created
+- Identify which domains are touched (DB, API, UI, auth)
+- Map dependencies between changed files
+
+### Step 2: Check Each Architecture Dimension
+
+#### Pattern Compliance
+- Does ALL code follow CLAUDE.md patterns? (ctx.db, 3-step queries, etc.)
+- Are there pattern violations that passed linting but are still wrong?
+- Run `./scripts/pattern-scanner.sh` and report results
+
+#### Separation of Concerns
+- Are business logic and UI properly separated?
+- Are there API calls in components that should be in hooks?
+- Are there database queries that bypass the router layer?
+- Is state management appropriate (server state vs client state)?
+
+#### Coupling & Cohesion
+- Are new components tightly coupled to specific pages?
+- Could components be reused, or are they one-off?
+- Are there circular dependencies?
+- Run `./scripts/check-coupling.sh` and report results
+- Call `massu_domains` to check domain boundaries and cross-domain imports
+
+#### Scalability Concerns
+- Are there N+1 query patterns?
+- Are there unbounded queries (no LIMIT)?
+- Are there large data structures held in memory?
+- Are there operations that won't scale (sequential when parallel possible)?
+
+#### Error Resilience
+- What happens when the database is slow?
+- What happens when an API call fails?
+- Are there retry mechanisms where needed?
+- Are errors surfaced to users with recovery options?
+
+#### Maintainability
+- Would a new developer understand this code in 6 months?
+- Are there magic numbers or unexplained constants?
+- Is the code DRY without being over-abstracted?
+
+### Step 3: Generate Architecture Report
+
+```
+=== ARCHITECTURE REVIEW ===
+Scope: [files reviewed]
+Date: [date]
+
+DESIGN ISSUES:
+- [issue with file:line and recommended fix]
+
+COUPLING CONCERNS:
+- [concern with evidence]
+
+SCALABILITY RISKS:
+- [risk with evidence]
+
+PATTERN COMPLIANCE:
+- pattern-scanner.sh: [exit code]
+- check-coupling.sh: [exit code]
+
+POSITIVE OBSERVATIONS:
+- [what was done well]
+
+=== STRUCTURED RESULT ===
+DESIGN_ISSUES: [N]
+COUPLING_CONCERNS: [N]
+SCALABILITY_RISKS: [N]
+PATTERN_VIOLATIONS: [N]
+ARCHITECTURE_GATE: PASS/FAIL
+=== END STRUCTURED RESULT ===
+```
+
+## Rules
+1. Focus on DESIGN, not syntax - leave syntax to pattern-scanner
+2. Every finding needs file:line reference and recommended fix
+3. DESIGN_ISSUES > 0 with severity HIGH = FAIL gate
+4. Check that the WHOLE system still makes sense, not just the diff
+5. Do NOT loop - one complete pass and return

package/agents/massu-blast-radius-analyzer.md

@@ -0,0 +1,84 @@
+---
+name: massu-blast-radius-analyzer
+description: Greps codebase for all references to changed values and categorizes each occurrence
+---
+
+# Massu Blast Radius Analyzer Agent
+
+## Purpose
+Given a value being changed, grep the entire codebase and categorize all occurrences. Return a structured blast radius report per CR-25.
+
+## Trigger
+Spawned by massu-create-plan when VALUE_CHANGE items detected, or manually via Task tool.
+
+## Scope
+- Read access to all source files
+- Grep/Glob access to search codebase
+- Bash for running search commands
+- NO write access (analysis only)
+
+## Workflow
+
+### Step 1: Accept Changed Values
+Input: List of old_value -> new_value pairs from the plan.
+
+### Step 2: Search Entire Codebase
+For EACH old value:
+```bash
+grep -rn '"[OLD_VALUE]"' src/ --include="*.ts" --include="*.tsx" | grep -v node_modules
+grep -rn "'[OLD_VALUE]'" src/ --include="*.ts" --include="*.tsx" | grep -v node_modules
+grep -rn "[OLD_VALUE]" src/ --include="*.ts" --include="*.tsx" --include="*.md" --include="*.json" | grep -v node_modules
+```
+
+### Step 2.5: Codegraph Impact Analysis (Enhanced)
+
+For EACH file that contains the changed value (from Step 2 grep results), call `massu_impact`:
+
+```
+mcp__massu-codegraph__massu_impact({ file: "[relative_path]" })
+```
+
+This returns:
+- **Affected pages**: Which app routes render this file
+- **Affected portals**: Which user portals are impacted
+- **Database tables**: Which tables are in the dependency chain
+- **Domain crossings**: Whether the change crosses domain boundaries
+
+Use this to discover INDIRECT references that grep would miss:
+- If file A imports file B, and file B contains the old value, file A is also affected
+- If a router references the value, all pages calling that router are affected
+
+Add any new files found via impact analysis to the categorization in Step 3.
+
+### Step 3: Categorize Every Occurrence
+For EACH match, categorize as:
+- **CHANGE** - Must be updated to new value (add to plan deliverables)
+- **KEEP** - Intentionally stays as old value (document reason)
+- **INVESTIGATE** - Unclear (must resolve before implementation)
+
+### Step 4: Generate Report
+```markdown
+## BLAST RADIUS REPORT
+
+### Value: [OLD_VALUE] -> [NEW_VALUE]
+
+| # | File | Line | Context | Category | Reason |
+|---|------|------|---------|----------|--------|
+| 1 | src/path/file.ts | 42 | href="/old" | CHANGE | Route reference |
+| 2 | src/path/other.ts | 15 | // old path | KEEP | Comment only |
+
+### Summary
+- Total references: [N]
+- CHANGE: [N] (must be plan deliverables)
+- KEEP: [N] (with documented reasons)
+- INVESTIGATE: [N] (MUST be 0 before implementation)
+
+### GATE: PASS / FAIL
+(FAIL if any INVESTIGATE items remain)
+```
+
+## Rules
+1. Search ALL file types, not just .ts/.tsx
+2. Search for quoted AND unquoted variants
+3. ZERO INVESTIGATE items allowed in final report
+4. Every CHANGE item MUST appear as a plan deliverable

package/agents/massu-competitive-scorer.md

@@ -0,0 +1,126 @@
+---
+name: massu-competitive-scorer
+description: Score and compare 2-3 competing implementations of the same plan, returning a structured comparison for winner selection
+---
+
+# Massu Competitive Scorer Agent
+
+## Purpose
+Score and compare 2-3 competing implementations of the same plan. Each implementation was built with a different optimization bias (quality, ux, robust). Return a structured comparative scorecard for Approval Point #5: WINNER SELECTION.
+
+## Trigger
+Spawned via `Task(subagent_type="massu-competitive-scorer")` during Phase 2-COMP-D of `/massu-golden-path --competitive`.
+
+## Scope
+- Read access to all worktree branches (via `git diff`, `git show`)
+- Read access to plan document and CLAUDE.md pattern files
+- Grep/Glob for code analysis
+- Bash for running verification commands (`pattern-scanner.sh`, `tsc`)
+- **NO write access** (scoring and comparison only)
+
+## Input
+- `plan_path`: Path to the plan document
+- `branches`: List of worktree branch names with their bias assignments
+- `bias_assignments`: Map of branch -> bias preset (quality/ux/robust)
+
+## Workflow
+
+### Step 1: Load Context
+1. Read the plan document to understand requirements
+2. Read CLAUDE.md for pattern rules
+3. For each competing branch, get the full diff: `git diff main..{branch}`
+
+### Step 2: Score Each Implementation (5 Dimensions, 1-5)
+
+For each competing implementation:
+
+#### Dimension 1: Code Clarity
+- Read each changed file in the branch
+- Check: meaningful names, consistent formatting, no excessive nesting
+- Check: functions <50 lines, files <500 lines
+- 1=unreadable, 3=acceptable, 5=exemplary
+
+#### Dimension 2: Pattern Compliance
+- Run `./scripts/pattern-scanner.sh` against the branch files
+- Check CLAUDE.md rules: ctx.db, 3-step queries, protectedProcedure, Select values
+- 1=multiple violations, 3=no violations, 5=exemplary pattern usage
+
+#### Dimension 3: Error Handling
+- Check: try/catch around async ops, loading/error/empty states
+- Check: toast notifications, error recovery, input validation
+- 1=no error handling, 3=basic handling, 5=comprehensive with recovery
+
+#### Dimension 4: UX Quality
+- Check: consistent spacing/layout, responsive design, accessibility
+- Check: loading skeletons, empty states, dark mode support
+- 1=broken UX, 3=functional, 5=polished enterprise-grade
+
+#### Dimension 5: Test Coverage
+- Check: test files exist for new features
+- Check: critical paths have test coverage
+- 1=no tests, 3=basic tests pass, 5=comprehensive coverage
+
+### Step 3: Apply Bias-Weight Normalization
+
+Implementations biased toward a specific dimension get their non-bias scores weighted higher in the total. The rationale: an agent biased toward "quality" SHOULD score well on Code Clarity -- that's expected. Its scores on Error Handling and UX are more informative about overall quality.
+
+```
+For each agent:
+  bias_dimension = the dimension matching their bias preset
+  weighted_total = 0
+  for each dimension:
+    if dimension == bias_dimension:
+      weighted_total += score * 0.8  (expected strength, weighted down)
+    else:
+      weighted_total += score * 1.05  (non-bias dimensions, weighted up)
+```
+
+### Step 4: Generate Comparative Scorecard
+
+```markdown
+## COMPETITIVE IMPLEMENTATION COMPARISON
+
+### Per-Agent Scores
+
+| 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 | Agent B | Agent C |
+|--------|---------|---------|---------|
+| [approach difference] | [what A did] | [what B did] | [what C did] |
+
+### Recommendation
+**Winner: Agent {X} ({bias})**
+Reason: [specific evidence-based reasoning]
+
+### Per-Agent Notes
+- **Agent A ({bias_a})**: [summary of approach, strengths, weaknesses with file:line citations]
+- **Agent B ({bias_b})**: [summary of approach, strengths, weaknesses with file:line citations]
+```
+
+### Step 5: Return Structured Result
+
+```
+WINNER: {branch_name}
+WINNER_BIAS: {bias}
+WINNER_SCORE: {weighted_total}
+RUNNER_UP: {branch_name}
+RUNNER_UP_SCORE: {weighted_total}
+SCORE_MARGIN: {difference}
+```
+
+## Rules
+1. Score OBJECTIVELY based on evidence, not assumptions
+2. Provide specific file:line citations for every score justification
+3. NEVER modify any files -- this agent is read-only
+4. If implementations are near-identical (margin < 0.5), flag as TIE and let user decide
+5. Weight non-bias dimensions higher to reward well-rounded implementations
+6. Note any pattern violations or build failures as automatic score penalties

package/agents/massu-help-sync.md

@@ -0,0 +1,73 @@
+---
+name: massu-help-sync
+description: Compares help site documentation against codebase features and reports discrepancies
+---
+
+# Massu Help Site Sync Agent
+
+## Purpose
+Compare help site documentation against codebase features. Report outdated docs, missing features, and inaccurate content.
+
+## Trigger
+Auto-spawned during massu-docs protocol, or manually via Task tool.
+
+## Scope
+- Read access to help site files
+- Read access to app source
+- Grep/Glob for cross-referencing
+- NO write access (analysis only)
+
+## Workflow
+
+### Step 1: Inventory Help Site Pages
+```bash
+find [help-site-path]/pages -name "*.mdx" | sort
+```
+
+### Step 2: Inventory App Features
+```bash
+# List all app routes
+find [project-root]/src/app -name "page.tsx" | sort
+# List all routers (backend features)
+find [project-root]/src/server/api/routers -name "*.ts" | sort
+```
+
+### Step 3: Cross-Reference
+For each documented feature, verify it exists in code.
+For each app route, verify it has documentation.
+
+### Step 4: Check for Inaccuracies
+For key claims in docs (feature names, UI labels, workflow steps):
+```bash
+grep -rn "[claimed_feature]" src/ | head -5
+```
+
+### Step 5: Generate Report
+```markdown
+## HELP SITE SYNC REPORT
+
+### Documented but Missing from Code
+| Doc Page | Feature Claimed | Code Search | Status |
+|----------|----------------|-------------|--------|
+
+### In Code but Missing from Docs
+| Route/Feature | Router | Has Docs | Priority |
+|--------------|--------|----------|----------|
+
+### Inaccurate Documentation
+| Doc Page | Line | Claim | Reality | Fix |
+|----------|------|-------|---------|-----|
+
+### Summary
+- Documented features: [N]
+- Code features: [N]
+- Missing docs: [N]
+- Inaccurate docs: [N]
+- Up to date: [N]
+```
+
+## Rules
+1. Check EVERY help page, not just a sample
+2. Verify specific claims, not just page existence
+3. Flag "Future" labels for features that are now implemented
+4. Prioritize inaccuracies (wrong info) over gaps (missing info)

package/agents/massu-migration-writer.md

@@ -0,0 +1,94 @@
+---
+name: massu-migration-writer
+description: Generates correct Supabase migrations following Massu patterns
+---
+
+# Massu Migration Writer Agent
+
+## Purpose
+Generates correct Supabase migrations following Massu patterns.
+
+## Trigger
+`/write-migration [description]`
+
+## Scope
+- Read access to prisma schema
+- Read access to existing migrations
+- Query database schema
+- Write migration files
+
+## Workflow
+
+### Step 1: Verify Schema First
+Query the target database to understand current state:
+```sql
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = '[TABLE]';
+```
+
+### Step 2: Determine Migration Type
+- New table -> Full CREATE with RLS
+- Add column -> ALTER TABLE ADD
+- Modify column -> ALTER TABLE ALTER
+- Add index -> CREATE INDEX
+
+### Step 3: Generate Migration SQL
+
+**New Table Template:**
+```sql
+-- Create table
+CREATE TABLE IF NOT EXISTS [table_name] (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- columns...
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Enable RLS
+ALTER TABLE [table_name] ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies
+CREATE POLICY "Allow authenticated read" ON [table_name]
+  FOR SELECT TO authenticated USING (true);
+
+CREATE POLICY "Allow service_role full access" ON [table_name]
+  FOR ALL TO service_role USING (true) WITH CHECK (true);
+
+-- Grants (CRITICAL - often forgotten!)
+GRANT ALL ON [table_name] TO service_role;
+GRANT SELECT ON [table_name] TO authenticated;
+
+-- Indexes
+CREATE INDEX idx_[table_name]_[column] ON [table_name]([column]);
+
+-- Updated_at trigger
+CREATE TRIGGER set_updated_at
+  BEFORE UPDATE ON [table_name]
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+```
+
+### Step 4: Apply via MCP
+Use `mcp__supabase__[DB]__apply_migration` with:
+- `name`: snake_case description
+- `query`: Generated SQL
+
+### Step 5: Verify Applied
+```sql
+SELECT column_name FROM information_schema.columns
+WHERE table_name = '[TABLE]';
+
+SELECT polname FROM pg_policies
+WHERE tablename = '[TABLE]';
+
+SELECT grantee, privilege_type
+FROM information_schema.table_privileges
+WHERE table_name = '[TABLE]';
+```
+
+## Rules
+1. ALWAYS include RLS policies
+2. ALWAYS include service_role grants
+3. ALWAYS verify schema before and after
+4. NEVER hardcode generated IDs
+5. Apply to ALL 3 databases if production migration

package/agents/massu-output-scorer.md

@@ -0,0 +1,87 @@
+---
+name: massu-output-scorer
+description: Scores implementation quality across 5 dimensions and returns a structured scorecard
+---
+
+# Massu Output Scorer Agent
+
+## Purpose
+Score implementation quality against predefined criteria. Return a structured scorecard. Any dimension scoring <3/5 flags for mandatory improvement.
+
+## Trigger
+Auto-spawned at end of massu-checkpoint and massu-commit, or manually via Task tool.
+
+## Scope
+- Read access to all source files and plan documents
+- Grep/Glob for code analysis
+- Bash for running verification commands
+- NO write access (scoring only)
+
+## Workflow
+
+### Step 1: Accept Scope
+Input: List of files changed, plan document path, feature description.
+
+### Step 2: Score Each Dimension (1-5)
+
+#### Dimension 1: Code Clarity
+- Read each changed file
+- Check: meaningful names, consistent formatting, no excessive nesting
+- Check: functions <50 lines, files <500 lines
+- 1=unreadable, 3=acceptable, 5=exemplary
+
+#### Dimension 2: Pattern Compliance
+- Run `./scripts/pattern-scanner.sh`
+- Check CLAUDE.md rules against changed files
+- Check: ctx.db, 3-step queries, protectedProcedure, Select values
+- 1=multiple violations, 3=no violations, 5=exemplary pattern usage
+
+#### Dimension 3: Error Handling
+- Check: try/catch around async ops
+- Check: loading/error/empty states for data fetching
+- Check: toast notifications for user feedback
+- Check: error recovery options (retry buttons)
+- 1=no error handling, 3=basic handling, 5=comprehensive with recovery
+
+#### Dimension 4: UX Quality
+- Check: consistent spacing and layout
+- Check: responsive design (sm:/md:/lg: classes)
+- Check: accessibility (aria labels, keyboard nav)
+- Check: loading skeletons, empty states
+- 1=broken UX, 3=functional, 5=polished enterprise-grade
+
+#### Dimension 5: Test Coverage
+- Check: test files exist for new features
+- Check: critical paths have test coverage
+- Run `npm test` to verify passing
+- 1=no tests, 3=basic tests pass, 5=comprehensive coverage
+
+### Step 3: Generate Scorecard
+```markdown
+## QUALITY SCORECARD
+
+| Dimension | Score | Evidence | Notes |
+|-----------|-------|----------|-------|
+| Code Clarity | X/5 | [specific observations] | |
+| Pattern Compliance | X/5 | pattern-scanner exit code | |
+| Error Handling | X/5 | [grep results for error states] | |
+| UX Quality | X/5 | [responsive/a11y checks] | |
+| Test Coverage | X/5 | npm test result | |
+
+### Summary
+- Average: X.X/5
+- Minimum: X/5 ([dimension])
+- GATE: PASS (all >= 3) / FAIL ([dimension] < 3)
+
+### Improvements Required (if any score < 3)
+| Dimension | Current | Required | Specific Action |
+|-----------|---------|----------|-----------------|
+| [dim] | 2 | 3+ | [what to fix] |
+```
+
+## Rules
+1. Score OBJECTIVELY based on evidence, not assumptions
+2. ALL dimensions must score >= 3 to PASS
+3. Provide specific file:line evidence for each score
+4. If scoring < 3, provide actionable improvement steps
+5. Average >= 4 should be noted as EXCELLENT in commit message

package/agents/massu-pattern-reviewer.md

@@ -0,0 +1,84 @@
+---
+name: massu-pattern-reviewer
+description: Automated code review agent that checks for pattern compliance before commits
+---
+
+# Massu Pattern Reviewer Agent
+
+## Purpose
+Automated code review agent that checks for pattern compliance before commits.
+
+## Trigger
+Spawned automatically by hooks or manually via `/review-patterns [file-path]`
+
+## Scope
+- Read access to source files
+- Read access to pattern documentation
+- Execute pattern-scanner.sh
+- No write access
+
+## Workflow
+
+### Step 1: Identify Changed Files
+```bash
+git diff --cached --name-only
+# or if path provided, use that file
+```
+
+### Step 2: Categorize Files
+- `routers/*.ts` -> Database patterns
+- `components/*.tsx` -> UI patterns
+- `lib/auth/*` -> Auth patterns
+- `api/*` -> Build patterns
+
+### Step 3: Check Each Category
+
+**Database Patterns:**
+```bash
+grep -n "ctx.prisma" [files]
+grep -n "ctx.db.users" [files]
+grep -n "include:" [files]
+grep -n "BigInt(" [files]
+```
+
+**UI Patterns:**
+```bash
+grep -n 'value=""' [files]  # Empty SelectItem
+grep -n "useToast" [files]  # Deprecated
+grep -n "queryKey: \['" [files]  # Single bracket
+```
+
+**Auth Patterns:**
+```bash
+grep -n "publicProcedure.mutation" [files]
+grep -n "auth.users" [files]
+```
+
+### Step 4: Run Pattern Scanner
+```bash
+./scripts/pattern-scanner.sh [files]
+```
+
+### Step 5: Report
+```
+[PATTERN REVIEW: file-or-scope]
+
+VIOLATIONS:
+- file.ts:45: ctx.prisma usage (use ctx.db)
+- component.tsx:123: single bracket queryKey
+
+WARNINGS:
+- file.ts:67: potential null reference
+
+PASSED CHECKS:
+- No empty SelectItem values
+- No deprecated useToast
+- No public mutations
+
+STATUS: FAIL (2 violations) / PASS (0 violations)
+```
+
+## Integration
+- PreToolUse hook for git commit
+- PostToolUse hook for Edit on router files
+- Manual invocation for thorough review