@massu/core 0.4.2 → 0.6.0

package/commands/_shared-references/blast-radius-protocol.md

@@ -0,0 +1,76 @@
+# Shared Reference: Blast Radius Protocol
+
+**This is a shared content block. Referenced by multiple commands. Do NOT invoke directly.**
+
+---
+
+## BLAST RADIUS ANALYSIS PROTOCOL (CR-25 — MANDATORY)
+
+**MANDATORY** when ANY plan or change modifies a constant value, redirect path, route, string literal, enum value, or configuration key. See [incidents/INCIDENT-LOG.md](../../incidents/INCIDENT-LOG.md) Incident #15 for origin.
+
+### Step 1: Identify ALL Changed Values
+
+| # | Old Value | New Value | Type | Scope |
+|---|-----------|-----------|------|-------|
+| 1 | `[old]` | `[new]` | [redirect path / enum / route / config key] | codebase-wide |
+
+### Step 2: Codebase-Wide Grep for EACH Changed 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" | grep -v node_modules | wc -l
+```
+
+### Step 2.5: Codegraph Impact Analysis
+
+For each file found by grep, call `mcp__massu-codegraph__massu_impact({ file: "[relative_path]" })` to discover INDIRECT impact through import chains.
+
+### Step 2.7: Sentinel Feature Impact (CR-32)
+
+For plans that DELETE files, run `massu_sentinel_impact`. Every orphaned feature MUST have a migration target. Zero orphaned features allowed.
+
+### Step 3: Categorize EVERY Occurrence
+
+**EVERY match must be categorized. No exceptions.**
+
+| # | File | Line | Context | Action | Reason |
+|---|------|------|---------|--------|--------|
+| 1 | src/middleware.ts | 523 | Root redirect | CHANGE | Landing page |
+| 2 | src/components/Sidebar.tsx | 93 | Nav href | KEEP | Links TO target |
+
+**Disposition Summary**: Count of CHANGE / KEEP / INVESTIGATE items. INVESTIGATE must resolve to 0 before plan is final.
+
+### Step 4: Add ALL "CHANGE" Items to Plan
+
+Every "CHANGE" occurrence becomes a plan deliverable with item ID, file, change required, and phase.
+
+### Automated Blast Radius Analysis (Optional)
+
+Spawn `Task(subagent_type="massu-blast-radius-analyzer", prompt="Analyze blast radius for value changes: {old_value} -> {new_value}. Categorize every occurrence.")` for automated codebase-wide grep, codegraph impact tracing, and automatic categorization.
+
+---
+
+## Blast Radius Gate
+
+All of the following must be true:
+- All changed values identified
+- Grep run for each value
+- Every occurrence categorized
+- Zero INVESTIGATE remaining
+- All CHANGE items in plan
+- All KEEP items documented with reasons
+
+**BLAST RADIUS GATE: PASS / FAIL**
+
+---
+
+## Common Search Patterns
+
+| Change Type | Search Patterns |
+|-------------|-----------------|
+| Route/path | `href="[old]"`, `push('[old]')`, `replace('[old]')`, `redirect('[old]')`, `pathname === '[old]'` |
+| Status/enum | `=== '[old]'`, `value="[old]"`, `status: '[old]'` |
+| Table/column rename | `ctx.db.[old]`, `[old]_id`, `table_name = '[old]'` |
+| Component rename | `<[Old]`, `import.*[Old]`, `from.*[old]` |
+| Config key | `config.[old]`, `[old]:`, `"[old]"` |

package/commands/_shared-references/security-pre-screen.md

@@ -0,0 +1,64 @@
+# Shared Reference: Security Pre-Screen
+
+**This is a shared content block. Referenced by multiple commands. Do NOT invoke directly.**
+
+---
+
+## SECURITY PRE-SCREEN (Shift-Left Gate)
+
+**Purpose**: Catch security gaps BEFORE implementation/plan generation, not after. Complements (does not replace) the security-reviewer subagent that audits implemented code.
+
+### 6 Security Dimensions
+
+| # | Dimension | Trigger | Action if Triggered |
+|---|-----------|---------|---------------------|
+| S1 | PII / Sensitive Data | Feature handles names, emails, financial data, addresses | Add RLS policies + column-level access to plan |
+| S2 | Authentication | Feature needs to know WHO the user is | Verify protectedProcedure usage, add auth items |
+| S3 | Authorization | Feature restricts WHAT users can do (roles, ownership) | Add RBAC checks, RLS policies to plan |
+| S4 | Injection Surfaces | User input flows to SQL, HTML, shell, or file paths | Add Zod validation, parameterized queries to plan |
+| S5 | Secrets Management | New API keys, tokens, or credentials (CR-5) | Add AWS Secrets Manager items (P0-XXX) to plan |
+| S6 | Rate Limiting | Public endpoints or high-cost operations (AI, email, PDF) | Add rate limiting middleware to plan |
+
+### Scoring
+
+For each dimension, assign:
+- **PASS**: Not applicable or already handled
+- **N/A**: Feature does not touch this dimension
+- **BLOCK**: Unresolved concern that must be addressed before proceeding
+
+### Block Resolution
+
+| Block Type | Resolution |
+|------------|------------|
+| Self-resolvable | Add missing security deliverable (RLS policy, Zod schema, protectedProcedure, etc.) and change to PASS |
+| Requires user decision | Ask via AskUserQuestion (e.g., "Should factory portal users see all orders or only their own?") |
+| Architectural concern | Document in Risk Assessment section |
+
+### Gate
+
+```
+BLOCKS_REMAINING = count of BLOCK items
+IF BLOCKS_REMAINING > 0: DO NOT proceed. Resolve all blocks first.
+IF BLOCKS_REMAINING = 0: PASS.
+```
+
+### Skip Condition
+
+Pure read-only UI cosmetic changes (styling, copy, layout) with NO data access changes may skip this phase. Document: `Security Pre-Screen SKIPPED: [reason -- cosmetic-only, no data flow changes]`.
+
+### Pre-Screen Report Format
+
+```markdown
+## Security Pre-Screen
+
+| # | Dimension | Status | Notes |
+|---|-----------|--------|-------|
+| S1 | PII / Sensitive Data | PASS/N/A/BLOCK | [details] |
+| S2 | Authentication | PASS/N/A/BLOCK | [details] |
+| S3 | Authorization | PASS/N/A/BLOCK | [details] |
+| S4 | Injection Surfaces | PASS/N/A/BLOCK | [details] |
+| S5 | Secrets Management | PASS/N/A/BLOCK | [details] |
+| S6 | Rate Limiting | PASS/N/A/BLOCK | [details] |
+
+**SECURITY PRE-SCREEN: PASS / BLOCKED ([N] blocks remaining)**
+```

package/commands/_shared-references/test-first-protocol.md

@@ -0,0 +1,87 @@
+# Test-First Protocol for Critical Findings
+
+> Shared reference for /massu-loop and /massu-debug.
+> Inspired by Hurlicane's "evidence before assertions" pattern.
+
+## When This Applies
+
+This protocol is MANDATORY when:
+- A review agent or debug investigation identifies a CRITICAL severity finding
+- The finding involves a bug (not a style/pattern violation)
+- The fix touches logic that can be unit-tested or integration-tested
+
+This protocol is OPTIONAL (but recommended) for:
+- HIGH severity findings
+- Findings that involve data flow, state management, or business logic
+
+This protocol does NOT apply to:
+- LOW/MEDIUM pattern compliance fixes (CSS, naming, import order)
+- Documentation-only changes
+- Config/command infrastructure changes
+
+## The Protocol (4 Steps)
+
+### Step 1: Write the Failing Test
+
+Before touching ANY source code, write a test that demonstrates the bug:
+
+```typescript
+// Example: proving a serialization bug exists
+it('should serialize BigInt fields to Number', () => {
+  const result = serializeRecord({ id: BigInt(123) });
+  expect(typeof result.id).toBe('number'); // This will FAIL
+});
+```
+
+### Step 2: Verify Test Fails
+
+Run the test and confirm it fails for the expected reason:
+
+```bash
+npm test -- -t "should serialize BigInt"
+# Expected: FAIL with the specific assertion error
+# Note: This project uses Vitest. Use -t (--testNamePattern) for filtering, NOT --grep.
+```
+
+If the test PASSES (the bug doesn't reproduce in test):
+- The finding may be a false positive — investigate further
+- Or the test doesn't exercise the right code path — fix the test
+- Do NOT proceed to fix until you have a failing test
+
+### Step 3: Apply the Fix
+
+Now fix the source code. The fix should be minimal and targeted.
+
+### Step 4: Verify Test Passes
+
+```bash
+npm test -- -t "should serialize BigInt"
+# Expected: PASS
+```
+
+Run the full test suite to check for regressions:
+
+```bash
+npm test
+# Expected: ALL pass
+```
+
+## Output Format
+
+When using this protocol, report:
+
+```
+TEST-FIRST PROTOCOL for: [finding description]
+  Step 1: Test written → [file:line]
+  Step 2: Test fails → [error message confirming the bug]
+  Step 3: Fix applied → [file:line, description]
+  Step 4: Test passes → [npm test output showing pass]
+  TEST_FIRST_GATE: PASS
+```
+
+## Exceptions
+
+If the finding CANNOT be tested (e.g., race condition only in production, visual rendering issue):
+- Document WHY it can't be tested
+- Use VR-BROWSER or VR-VISUAL as the evidence-before-assertion equivalent
+- Report: `TEST_FIRST_GATE: SKIPPED — [reason]`

package/commands/_shared-references/verification-table.md

@@ -0,0 +1,52 @@
+# Shared Reference: Verification Table
+
+**This is a shared content block. Referenced by multiple commands. Do NOT invoke directly.**
+
+---
+
+## Standard VR-* Verification Gates
+
+| Type | Command | Expected | Use When |
+|------|---------|----------|----------|
+| VR-BUILD | `npm run build` | Exit 0 | Claiming production ready |
+| VR-TYPE | `npx tsc --noEmit` | 0 errors | Claiming type safety |
+| VR-TEST | `npm test` | ALL pass (MANDATORY) | ALWAYS before claiming complete |
+| VR-SCHEMA-PRE | `SELECT column_name FROM information_schema.columns WHERE table_name = 'X'` | All columns exist | BEFORE writing ANY query |
+| VR-NEGATIVE | `grep -rn "[old]" src/` | 0 matches | Claiming removal |
+| VR-GREP | `grep "[pattern]" [file]` | Match found | Claiming code added |
+| VR-RENDER | `grep "<ComponentName" src/app/**/page.tsx` | Match in page file | UI component integrated |
+| VR-COUPLING | `./scripts/check-coupling.sh` | Exit 0 | Backend features have UI exposure |
+| VR-BLAST-RADIUS | Grep codebase for ALL refs to changed value | 0 uncategorized refs | Changing any constant/path/enum |
+| VR-PLAN-COVERAGE | Item-by-item verification with proof | 100% items verified | Before claiming plan complete |
+| VR-SCHEMA-SYNC | Query same table across all environments via MCP | Column counts + names match | After ANY database migration |
+| VR-TOKEN | `scripts/audit-design-tokens.sh` | Exit 0 | CSS changes |
+| VR-BROWSER | Playwright: navigate, snapshot, console_messages, interact | 0 errors, UI works | ANY UI fix/change (CR-41) |
+| VR-SPEC-MATCH | Grep for EXACT CSS classes/structure from plan | All plan-specified strings found | UI plan items (CR-42) |
+| VR-PIPELINE | Trigger pipeline procedure, verify non-empty output | Output contains data | Data pipeline features (CR-43) |
+
+**Full VR-* reference (50+ types)**: [reference/vr-verification-reference.md](../../reference/vr-verification-reference.md)
+
+---
+
+## Auto-Verification Command Gate (Pre-Commit/Push)
+
+| Gate | Command | Must |
+|------|---------|------|
+| 1. Pattern Scanner | `./scripts/pattern-scanner.sh` | Exit 0 |
+| 2. Type Safety | `npx tsc --noEmit` | 0 errors |
+| 3. Build | `npm run build` | Exit 0 |
+| 4. Lint | `npm run lint` | Exit 0 |
+| 5. Schema | `npx prisma validate` | Exit 0 |
+| 6. Secrets Staged | `git diff --cached --name-only \| grep -E '\.(env\|pem\|key\|secret)'` | 0 files |
+| 7. Credentials | `grep -rn "sk-\|password.*=.*['\"]" --include="*.ts" --include="*.tsx" src/ \| grep -v "process.env"` | 0 matches |
+
+---
+
+## Database Environments
+
+| Environment | Description | MCP Tool Prefix |
+|-------------|-------------|-----------------|
+| DEV | Local development, testing | `mcp__supabase__DEV__` |
+| PROD | Production database | `mcp__supabase__PROD__` |
+
+> **Note**: Project-specific Supabase project IDs should be configured in the project's CLAUDE.md or `.env` file, not in shared references.

package/commands/massu-article-review.md

@@ -0,0 +1,343 @@
+---
+name: massu-article-review
+description: "When user shares a URL, article, tweet, or post and wants analysis of how it applies to the project -- 'review this', 'what do you think of this'"
+allowed-tools: WebFetch(*), WebSearch(*), Read(*), Write(*), Bash(*)
+disable-model-invocation: true
+---
+name: massu-article-review
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-14, CR-5, CR-12 enforced.
+
+# Massu Article Review: Technical Article Analysis Protocol
+
+## Objective
+
+Analyze technical articles, blog posts, and documentation to extract actionable insights for project development. Produce structured summaries with cost/benefit scoring and automatic comparison to current project approaches.
+
+---
+
+## ARGUMENTS
+
+The command accepts an optional URL argument:
+
+```
+/massu-article-review https://example.com/article
+/massu-article-review                              # Will prompt for input
+```
+
+**Arguments from $ARGUMENTS**: {{ARGUMENTS}}
+
+---
+
+## INPUT HANDLING
+
+### Priority Order
+1. If `$ARGUMENTS` contains a URL -> fetch it
+2. If user pasted article content -> use that
+3. Otherwise -> ask user for URL or content
+
+### Paywall/Login Handling
+
+**Claude Code CANNOT access authenticated sessions or bypass paywalls.**
+
+If WebFetch fails or returns incomplete content:
+
+```
+The article appears to be behind a paywall or requires login.
+
+Please provide the content using one of these methods:
+1. Copy/paste the article text directly
+2. Save as PDF from Safari and tell me the file path
+3. Use Safari Reader mode -> Export -> provide file path
+4. Save webpage as HTML and provide file path
+```
+
+---
+
+## AUTOMATIC BEHAVIORS
+
+### 1. Always Compare to Current Project Approach
+Every review MUST include comparison to existing project patterns, commands, and architecture. This is NOT optional.
+
+### 2. Always Save Review
+Every review MUST be saved to the project's documentation directory.
+
+### 3. Always Include Cost/Benefit Score
+Every review MUST include a numeric score (see scoring section).
+
+---
+
+## COST/BENEFIT SCORING
+
+Calculate a **Project Fit Score** (0-100):
+
+### Scoring Components
+
+| Component | Weight | Criteria |
+|-----------|--------|----------|
+| **Problem Relevance** | 25 pts | Does it solve a current project pain point? |
+| **Architecture Fit** | 20 pts | Compatible with the project's technology stack? |
+| **Pattern Compliance** | 20 pts | Can it follow project verification/quality patterns? |
+| **Implementation Effort** | 15 pts | Low effort = high score, high effort = low score |
+| **Risk Level** | 10 pts | Low risk = high score, high risk = low score |
+| **Maintenance Burden** | 10 pts | Low maintenance = high score |
+
+### Score Interpretation
+
+| Score | Rating | Recommendation |
+|-------|--------|----------------|
+| 80-100 | Excellent | ADOPT - implement soon |
+| 60-79 | Good | TRIAL - experiment in isolated context |
+| 40-59 | Mixed | ASSESS - needs more research |
+| 20-39 | Poor | HOLD - not suitable now |
+| 0-19 | Bad | AVOID - conflicts with project patterns |
+
+### Score Card Format
+
+```markdown
+## Project Fit Score: XX/100
+
+| Component | Score | Notes |
+|-----------|-------|-------|
+| Problem Relevance | /25 | [why] |
+| Architecture Fit | /20 | [why] |
+| Pattern Compliance | /20 | [why] |
+| Implementation Effort | /15 | [why] |
+| Risk Level | /10 | [why] |
+| Maintenance Burden | /10 | [why] |
+| **TOTAL** | **XX/100** | **[RATING]** |
+```
+
+---
+
+## ANALYSIS FRAMEWORK
+
+### 1. Executive Summary
+2-3 sentence overview of the article's main thesis.
+
+### 2. Key Points Extraction
+
+| # | Key Point | Technical Detail |
+|---|-----------|------------------|
+| 1 | [Point] | [Specifics] |
+| 2 | [Point] | [Specifics] |
+
+### 3. Technology/Tool Overview (if applicable)
+
+| Aspect | Details |
+|--------|---------|
+| **Name** | [Tool/Tech name] |
+| **Purpose** | [What it does] |
+| **Key Features** | [Main features] |
+| **Prerequisites** | [Requirements] |
+| **Maturity** | [Production-ready/Beta/Experimental] |
+| **Community** | [Downloads, stars, activity] |
+
+### 4. Current Project Approach Comparison (MANDATORY)
+
+**This section is REQUIRED for every review.**
+
+| Aspect | Article Approach | Current Project Approach | Delta |
+|--------|------------------|-------------------------|-------|
+| [Feature 1] | [How article does it] | [How project does it] | [Difference] |
+| [Feature 2] | [How article does it] | [How project does it] | [Difference] |
+
+### Commands/Patterns That Overlap
+
+| Project Asset | Overlap | Notes |
+|---------------|---------|-------|
+| `/massu-*` command | [Which one] | [How it compares] |
+| Pattern file | [Which one] | [How it compares] |
+| Existing tool | [Which one] | [How it compares] |
+
+### What Project Does Better
+- [Point 1]
+- [Point 2]
+
+### What Article Approach Does Better
+- [Point 1]
+- [Point 2]
+
+### 5. Implementation Path (if score >= 40)
+
+#### Phase 1: Assessment
+- [ ] [Action items]
+
+#### Phase 2: Trial (if applicable)
+- [ ] [Action items]
+
+#### Phase 3: Adoption (if applicable)
+- [ ] [Action items]
+
+---
+
+## SOURCE CREDIBILITY
+
+| Factor | Assessment |
+|--------|------------|
+| **Author** | [Expert/Practitioner/Unknown] |
+| **Publication** | [Official/Major blog/Personal/Unknown] |
+| **Date** | [Recent/Dated] |
+| **Evidence** | [Metrics provided/Claims only] |
+| **Community** | [Downloads/Stars/Activity] |
+
+---
+
+## REPORT FORMAT
+
+The final report saved to file:
+
+```markdown
+# Article Review: [Title]
+
+**Source**: [URL]
+**Author**: [Name]
+**Reviewed**: [Date]
+**Reviewer**: Claude (massu-article-review)
+
+---
+
+## Project Fit Score: XX/100 - [RATING]
+
+| Component | Score | Notes |
+|-----------|-------|-------|
+| Problem Relevance | /25 | |
+| Architecture Fit | /20 | |
+| Pattern Compliance | /20 | |
+| Implementation Effort | /15 | |
+| Risk Level | /10 | |
+| Maintenance Burden | /10 | |
+| **TOTAL** | **XX/100** | |
+
+**Recommendation**: ADOPT / TRIAL / ASSESS / HOLD / AVOID
+
+---
+
+## Executive Summary
+
+[2-3 sentences]
+
+---
+
+## Key Points
+
+1. [Point]
+2. [Point]
+...
+
+---
+
+## Comparison to Current Project Approach
+
+### What This Article Proposes
+[Summary]
+
+### How Project Currently Handles This
+[Summary]
+
+### Gap Analysis
+| Gap | Impact | Action |
+|-----|--------|--------|
+| [Gap] | [Impact] | [Action] |
+
+### Verdict
+[Which approach is better and why]
+
+---
+
+## Benefits
+- [Benefit 1]
+- [Benefit 2]
+
+## Concerns/Risks
+- [Concern 1]
+- [Concern 2]
+
+---
+
+## Implementation Path
+
+[If score >= 40, provide phased approach]
+
+---
+
+## Action Items
+
+- [ ] [Item 1]
+- [ ] [Item 2]
+
+---
+
+## Related Resources
+- [Link 1]
+- [Link 2]
+
+---
+
+*Generated by /massu-article-review on [date]*
+```
+
+---
+
+## EXECUTION STEPS
+
+1. **Parse input**
+   - Check $ARGUMENTS for URL
+   - Check user message for pasted content
+   - If neither, prompt user
+
+2. **Fetch content**
+   - If URL provided, use WebFetch
+   - If WebFetch fails (paywall), prompt for alternative input
+   - If content pasted, proceed
+
+3. **Analyze article**
+   - Apply full analysis framework
+   - Calculate Project Fit Score
+   - Compare to current project approach (MANDATORY)
+
+4. **Generate report**
+   - Use report format above
+   - Include all required sections
+
+5. **Save report**
+   - Create filename: `YYYY-MM-DD-[slug].md`
+   - Save to project documentation directory
+   - Verify file was created
+
+6. **Present summary**
+   - Show score and recommendation in response
+   - Confirm file saved with path
+
+---
+
+## QUALITY SCORING (silent, automatic)
+
+After completing the review, self-score against these checks and append one JSONL line to `.claude/metrics/command-scores.jsonl`:
+
+| Check | Pass condition |
+|-------|---------------|
+| `has_project_comparison` | Review includes "Comparison to Current Project Approach" section with non-empty content |
+| `has_score_table` | Review includes Project Fit Score table with all 6 components scored |
+| `saved_to_file` | Review file was successfully written |
+| `has_action_items` | Review includes at least 2 concrete action items |
+
+**Format** (append one line -- do NOT overwrite the file):
+```json
+{"command":"massu-article-review","timestamp":"ISO8601","scores":{"has_project_comparison":true,"has_score_table":true,"saved_to_file":true,"has_action_items":true},"pass_rate":"4/4","input_summary":"[slug]"}
+```
+
+This scoring is silent -- do NOT mention it to the user. Just append the line after saving the review.
+
+---
+
+## START NOW
+
+1. Check for URL in arguments: `{{ARGUMENTS}}`
+2. Check for pasted content in user message
+3. Fetch or prompt as needed
+4. Run full analysis with project comparison
+5. Calculate and display Project Fit Score
+6. Save review file
+7. Confirm completion with file path
+8. **Score and append to command-scores.jsonl** (silent)