@massu/core 0.4.2 → 0.6.0

package/reference/command-taxonomy.md

@@ -0,0 +1,178 @@
+# Command Taxonomy
+
+Categorization of all commands into the 9-type taxonomy from "Lessons from Building Claude Code: How We Use Skills."
+
+## Categories
+
+| # | Category | Description |
+|---|----------|-------------|
+| 1 | Library & API Reference | Shared knowledge, patterns, specifications |
+| 2 | Verification | Validation, testing, quality gates |
+| 3 | Data Fetching & Analysis | Database queries, metrics, analytics |
+| 4 | Business Process & Team Automation | Workflows, session management, orchestration |
+| 5 | Code Scaffolding & Templates | File generation, boilerplate, format templates |
+| 6 | Code Review | Quality analysis, simplification, auditing |
+| 7 | Deployment | Push, release, hotfix, rollback |
+| 8 | Investigation | Debugging, incident response, root cause analysis |
+| 9 | Infrastructure Operations | Dependencies, hooks, dead code, configuration |
+
+---
+
+## Full Mapping
+
+### 1. Library & API Reference (2)
+
+| Command | Purpose |
+|---------|---------|
+| `_shared-preamble` | Shared preamble injected into all commands |
+| `massu-guide` | User onboarding and system documentation |
+
+### 2. Verification (6)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-verify` | Run verification requirements (VR-*) |
+| `massu-checkpoint` | Mid-implementation checkpoint audit |
+| `massu-loop-playwright` | Browser-based E2E verification loop |
+| `massu-verify-playwright` | Single-page browser verification |
+| `massu-test` | Run test suites |
+| `massu-tdd` | Test-driven development workflow |
+
+### 3. Data Fetching & Analysis (3)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-parity` | Cross-environment schema parity check |
+| `massu-gap-enhancement-analyzer` | Gap and enhancement analysis from reports |
+| `massu-data` | Database analytics and query library |
+
+### 4. Business Process & Team Automation (6)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-golden-path` | Full autonomous plan-to-push pipeline |
+| `massu-bearings` | Morning session orientation |
+| `massu-recap` | End-of-session handoff |
+| `massu-squirrels` | Park tangential ideas mid-task |
+| `massu-create-plan` | Plan creation from requirements |
+| `massu-plan` | Plan audit for gaps |
+
+### 5. Code Scaffolding & Templates (6)
+
+| Command | Purpose |
+|---------|---------|
+| `format-supabase-migration` | SQL migration file template |
+| `format-trpc-router` | tRPC router file template |
+| `massu-scaffold-page` | New page scaffolding |
+| `massu-scaffold-router` | New tRPC router scaffolding |
+| `massu-scaffold-hook` | New hook scaffolding |
+| `massu-scaffold-mcp` | New MCP integration scaffolding |
+
+### 6. Code Review (9)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-simplify` | Post-change multi-reviewer quality analysis |
+| `massu-commit` | Pre-commit verification gates |
+| `massu-article-review` | External article/post analysis |
+| `massu-command-health` | Command quality dashboard |
+| `massu-command-improve` | Improve a specific command |
+| `massu-codebase-audit` | Full codebase quality audit |
+| `massu-ui-audit` | UI/UX quality audit |
+| `massu-feature-audit` | Feature completeness audit |
+| `massu-extended-audit` | Extended multi-dimension audit |
+
+### 7. Deployment (4)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-push` | Push with pre-push verification |
+| `massu-push-light` | Lightweight push (fewer checks) |
+| `massu-hotfix` | Emergency production fix pipeline |
+| `massu-rollback` | Deployment rollback |
+
+### 8. Investigation (2)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-debug` | Structured bug investigation with auto-learning |
+| `massu-incident` | Incident documentation and response protocol |
+
+### 9. Infrastructure Operations (12)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-deps` | Dependency health audit |
+| `massu-hooks` | Hook system inventory |
+| `massu-dead-code` | Dead code detection and removal |
+| `massu-ai-models` | AI model configuration audit |
+| `massu-batch` | Parallel code-only migrations |
+| `massu-config-audit` | Configuration consistency audit |
+| `massu-db-audit` | Database health audit |
+| `massu-db-branch` | Database branching operations |
+| `massu-import-audit` | Import chain analysis |
+| `massu-infra-audit` | Infrastructure audit |
+| `massu-migrate` | Code migration assistant |
+| `massu-session-optimization` | Session context optimization |
+
+### Cross-Cutting Orchestration (6)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-loop` | Plan implementation loop |
+| `massu-new-feature` | New feature workflow |
+| `massu-new-pattern` | New pattern documentation |
+| `massu-rebuild` | Feature rebuild with parity |
+| `massu-refactor` | Refactoring workflow |
+| `massu-learning-audit` | Learning pipeline audit |
+
+### Specialized (9)
+
+| Command | Purpose |
+|---------|---------|
+| `massu-api-contract` | API contract validation |
+| `massu-docs` | Documentation generation |
+| `massu-mobile-research` | Mobile platform research |
+| `massu-perf` | Performance analysis |
+| `massu-plan-audit` | Plan audit (subset of massu-plan) |
+| `massu-security` | Security audit |
+| `massu-type-mismatch-audit` | TypeScript type mismatch detection |
+| `careful` | Session-scoped destructive command blocking |
+| `freeze` | Session-scoped edit directory restriction |
+
+---
+
+## Coverage Analysis
+
+| Category | Count | Coverage |
+|----------|-------|----------|
+| 1. Library & API Reference | 2 | Thin -- relies on pattern files in `patterns/` and `specs/` |
+| 2. Verification | 6 | Strong |
+| 3. Data Fetching & Analysis | 3 | Moderate |
+| 4. Business Process | 6 | Strong |
+| 5. Code Scaffolding | 6 | Strong |
+| 6. Code Review | 9 | Very Strong |
+| 7. Deployment | 4 | Strong |
+| 8. Investigation | 2 | Adequate -- high quality per command |
+| 9. Infrastructure Ops | 12 | Very Strong |
+
+### Coverage Gaps
+
+1. **Library & API Reference**: Relies on pattern files rather than dedicated commands. The `_shared-preamble` + `massu-guide` cover basics, but specific API reference skills could be useful as standalone lookups. **Recommendation**: Low priority -- pattern files serve this role well.
+
+2. **Data Fetching & Analysis**: Could benefit from a dedicated analytics/dashboard skill. **Recommendation**: Monitor usage of `massu-data` before expanding.
+
+3. **Investigation**: Only 2 commands but both are comprehensive folder-based skills. Quality over quantity. **Recommendation**: No action needed.
+
+---
+
+## Folder-Based Skills
+
+Commands that have been migrated to folder-based structure for progressive disclosure:
+
+| Command | Files | Scripts |
+|---------|-------|---------|
+| `massu-golden-path/` | Reference docs | -- |
+| `massu-debug/` | Reference docs | Diagnostic scripts |
+| `massu-loop/` | Reference docs | -- |
+| `massu-data/` | Reference docs | SQL scripts |

package/reference/cr-rules-reference.md

@@ -0,0 +1,76 @@
+# Canonical Rules (CR) — Full Reference
+
+All CR rules with verification types and reference links.
+
+| ID | Rule | Verification Type | Reference |
+|----|------|-------------------|-----------|
+| CR-1 | Never claim state without proof | VR-* | [protocols/verification.md](../protocols/verification.md) |
+| CR-2 | Never assume database schema | VR-SCHEMA | [protocols/verification.md](../protocols/verification.md) |
+| CR-3 | Never commit secrets | git status check | Incident records |
+| CR-4 | Verify removals with negative grep | VR-NEGATIVE | [protocols/plan-implementation.md](../protocols/plan-implementation.md) |
+| CR-5 | ALL secrets MUST use secure credential management | VR-SECRETS | [patterns/security-patterns.md](../patterns/security-patterns.md) |
+| CR-6 | Read plan file, not memory | Plan file open | [protocols/plan-implementation.md](../protocols/plan-implementation.md) |
+| CR-7 | Check ALL items in plan, not "most" | VR-COUNT | [protocols/plan-implementation.md](../protocols/plan-implementation.md) |
+| CR-8 | Created components MUST be rendered | VR-RENDER | Incident records |
+| CR-9 | Fix ALL issues encountered, whether from current changes or pre-existing | VR-FIX-ALL | Incident records |
+| CR-10 | Plan document MUST have completion status | VR-PLAN-STATUS | [protocols/plan-implementation.md](../protocols/plan-implementation.md) |
+| CR-11 | NEVER stop loop until 100% plan coverage | VR-PLAN-COVERAGE | Implementation loop protocol |
+| CR-12 | After compaction, NEVER escalate beyond AUTHORIZED_COMMAND | VR-PROTOCOL | [protocols/recovery.md](../protocols/recovery.md) |
+| CR-13 | Plan UI specs MUST match implementation | VR-PLAN-SPEC | [protocols/plan-implementation.md](../protocols/plan-implementation.md) |
+| CR-14 | ALL solutions MUST be enterprise-grade | Design review | [protocols/verification.md](../protocols/verification.md) |
+| CR-15 | Edge Runtime files MUST NOT import Node.js deps | VR-EDGE | [patterns/build-patterns.md](../patterns/build-patterns.md) |
+| CR-16 | Native/heavy packages MUST be externalized | VR-EXTERN | [patterns/build-patterns.md](../patterns/build-patterns.md) |
+| CR-17 | ALWAYS fix ALL issues encountered | VR-FIX | [protocols/verification.md](../protocols/verification.md) |
+| CR-18 | Import chains MUST NOT pull heavy deps | VR-IMPORT | [patterns/build-patterns.md](../patterns/build-patterns.md) |
+| CR-19 | Builds MUST have ZERO warnings | VR-LINT | [patterns/build-patterns.md](../patterns/build-patterns.md) |
+| CR-20 | ALL tests MUST pass before claiming complete | VR-TEST | [protocols/verification.md](../protocols/verification.md) |
+| CR-21 | Database configs MUST match code expectations | VR-DATA | [protocols/verification.md](../protocols/verification.md) |
+| CR-22 | Backend procedures MUST be called from UI | VR-COUPLING | [protocols/verification.md](../protocols/verification.md) |
+| CR-23 | ALL protocol commands MUST be followed exactly | VR-PROTOCOL | Incident records |
+| CR-24 | Changing values requires codebase-wide blast radius analysis | VR-BLAST-RADIUS | Plan creation protocol |
+| CR-25 | Before editing UI, verify file serves target URL | VR-ROUTE | Incident records |
+| CR-26 | After table migrations, audit ALL stored procedures | VR-STORED-PROC | Incident records |
+| CR-27 | Config map lookups MUST have fallback defaults for dynamic keys | VR-CONFIG-GUARD | Incident records |
+| CR-28 | Rebuilds MUST audit old implementation for feature parity BEFORE deleting | VR-PARITY | Incident records |
+| CR-29 | ALWAYS propose the most robust, enterprise-grade solution | VR-QUALITY | [protocols/verification.md](../protocols/verification.md) |
+| CR-30 | ALL public tables MUST have RLS enabled | VR-RLS-AUDIT | Incident records |
+| CR-31 | ALL fixes MUST be auto-learned: ingest to memory, record pattern, update scanner | VR-LEARNING | All command protocols |
+| CR-32 | ALL database migrations MUST be applied to ALL environments | VR-SCHEMA-SYNC | Incident records |
+| CR-33 | Stagnating loops MUST bail and replan, not grind | VR-PROTOCOL | Implementation loop protocol |
+| CR-34 | ALL significant work MUST be persisted to memory BEFORE session ends | VR-MEMORY | [protocols/verification.md](../protocols/verification.md) |
+| CR-35 | Propose approach before multi-file changes | VR-APPROACH | [protocols/verification.md](../protocols/verification.md) |
+| CR-36 | ALL overlays MUST use Sheet, NEVER Dialog (except AlertDialog) | VR-UI | Incident records |
+| CR-37 | ALL UI fixes MUST be browser-verified via Playwright before claiming done | VR-BROWSER | Incident records |
+| CR-38 | Plan UI specs (CSS classes, structure, layout) MUST match implementation exactly | VR-SPEC-MATCH | [protocols/verification.md](../protocols/verification.md) |
+| CR-39 | Data pipeline features MUST be triggered end-to-end with non-empty output verified | VR-PIPELINE | [protocols/verification.md](../protocols/verification.md) |
+| CR-40 | After every debug fix, scanner MUST be updated with detection rule for the root cause pattern | VR-LEARNING | Incident records |
+| CR-41 | After context compaction during implementation, re-read plan file from disk and rebuild item tracking before proceeding | VR-PLAN-COVERAGE | Incident records |
+| CR-42 | ALL exported service functions MUST be wired to a consumer (tRPC router, API route, or cron). No half-built features. | VR-UNWIRED | Scanner enforcement |
+| CR-43 | ALL data-writing features MUST be verified write->store->read->display end-to-end before claiming complete | VR-ROUNDTRIP | [reference/vr-verification-reference.md](vr-verification-reference.md) |
+
+---
+
+## Full Core Principles (22)
+
+1. **NO SHORTCUTS** - Quality over speed, always
+2. **COMPLETE VERIFICATION** - Proof, not claims
+3. **ZERO ASSUMPTIONS** - Query, don't guess
+4. **ALL ITEMS** - "Most of them" is not "all of them"
+5. **NEGATIVE VERIFICATION** - Removals need grep returning 0
+6. **SESSION STATE** - Record decisions and failures
+7. **PATTERN COMPLIANCE** - Read patterns, show proof
+8. **ENHANCEMENT PRINCIPLE** - If it would improve the system, add it NOW (no skipping, no workarounds)
+9. **ENTERPRISE-GRADE ONLY** - Every solution must be permanent, production-ready, error-free
+10. **NEVER SKIP** - Solve ALL problems as encountered, never postpone or use stopgaps
+11. **NEVER STOP EARLY** - Loop continues until 100% plan coverage, no exceptions, no early termination
+12. **SECRETS SECURED** - All secrets use secure credential management, never plain env vars
+13. **PROTOCOLS ARE MANDATORY** - Slash commands are execution instructions; reading is not following
+14. **BLAST RADIUS FIRST** - When changing any value, grep entire codebase before planning; documented sync patterns are necessary but not sufficient
+15. **CONTEXT HYGIENE** - Use subagents for exploration, /clear between unrelated tasks, update session state before compaction
+16. **FIX EVERYTHING ENCOUNTERED** - Every issue found during work MUST be fixed immediately, whether from current changes or pre-existing; "not in scope" is never valid
+17. **MIGRATIONS HIT ALL ENVIRONMENTS** - Every schema change MUST be applied to all environments in the same session; a migration applied to 1 database is incomplete
+18. **SIMPLEST CORRECT SOLUTION** - When fixing or building, choose the simplest approach that is correct and complete. CR-9 mandates fixing all issues; this principle mandates fixing them simply. If scope expands beyond the original task, flag it before expanding.
+19. **ELEGANCE CHECK** - For non-trivial changes, pause and ask: "Is there a more elegant way?" If a fix feels hacky, implement the elegant solution. Skip for simple, obvious fixes. Would a staff engineer approve this approach?
+20. **ONE TASK PER SUBAGENT** - Each spawned agent gets a single focused task. Parallel spawning is encouraged but each agent receives one isolated concern. Never combine unrelated tasks in one spawn.
+21. **MEMORY IS MANDATORY** - ALL significant decisions, fixes, patterns, errors, config changes, new tools, and architectural learnings MUST be persisted to memory files BEFORE the session ends or /clear. Knowledge lost to session end is unrecoverable.
+22. **PROPOSE FIRST** - For non-trivial tasks (>2 files, unfamiliar API, multiple valid approaches), propose approach in 2-3 bullets before implementing. Include which existing codebase patterns/utilities to use. Skip for simple fixes with obvious implementations.

package/reference/hook-execution-order.md

@@ -0,0 +1,148 @@
+# Hook Execution Order Reference
+
+**Purpose**: Authoritative reference for hook execution ordering across all event types in `.claude/settings.json`.
+
+**Scope**: Project hooks only (`.claude/settings.json`). User hooks (`~/.claude/settings.json`) run in a separate pipeline and are not covered here.
+
+**Enforcement**: Run `scripts/hooks/validate-hook-order.sh` to verify ordering constraints. Exit 0 = valid.
+
+---
+
+## Ordering Principles
+
+1. **Security-critical hooks run first** -- secret filters, rate limiters, integrity checks
+2. **Blocking hooks before advisory** -- hooks that can reject/block run before informational ones
+3. **Data-writing hooks before data-reading hooks** -- producers before consumers
+4. **Observability hooks run last** -- trackers, advisors, and audit logs
+
+---
+
+## SessionStart (4 hooks)
+
+Context initialization -> CR-12 enforcement -> advisories -> security scan.
+
+| position: 1 | `session-start.js` | standard | Context initialization, memory injection |
+|---|---|---|---|
+| position: 2 | AUTHORIZED_COMMAND display | critical (inline) | CR-12 enforcement -- must display before any work |
+| position: 3 | `surface-review-findings.sh` | advisory/strict | Surface findings from previous session's auto-review |
+| position: 4 | `memory-integrity-check.sh` | critical (no gate) | Security scan of memory files for anti-patterns |
+
+**Dependencies**:
+- `session-start.js` MUST be position 1 -- writes DB state other hooks may read
+- `memory-integrity-check.sh` runs last -- safety net that catches issues regardless of prior hooks
+
+---
+
+## PreToolUse (6 hooks)
+
+Security blocking -> advisory warnings -> matcher-specific -> observability.
+
+| position: 1 | `pattern-scanner.sh --quick` | standard | Bash(git push) -- block pushes with pattern violations |
+|---|---|---|---|
+| position: 2 | CR-24 blast radius advisory | standard | Edit -- warn on path/route changes |
+| position: 3 | `validate-features.sh` | standard | Bash(git commit) -- validate feature registry before commit |
+| position: 4 | CR-30 deletion sentinel | strict | Bash(rm) -- warn on src/ file deletions |
+| position: 5 | `mcp-rate-limiter.sh` | critical | MCP tools -- rate-limit database queries |
+| position: 6 | `command-invocation-tracker.sh` | standard | Skill -- observability, no blocking |
+
+**Dependencies**:
+- `pattern-scanner.sh` should run early -- gates bad pushes before other hooks fire
+- `mcp-rate-limiter.sh` is matcher-specific (MCP only) -- position among Bash hooks is irrelevant
+- `command-invocation-tracker.sh` MUST be last -- pure observability, no blocking
+
+---
+
+## PostToolUse (11 hooks)
+
+Security scan -> immediate feedback -> context tracking -> incident capture -> memory sync -> observability.
+
+| position: 1 | CI monitor | standard | Bash(git push) -- immediate push feedback |
+|---|---|---|---|
+| position: 2 | `output-secret-filter.sh` | critical | Bash\|Read\|mcp -- scan output for leaked secrets |
+| position: 3 | `pattern-feedback.sh` | standard | Edit\|Write -- immediate pattern violation feedback |
+| position: 4 | `post-edit-context.js` | strict | Edit\|Write -- detailed semantic analysis |
+| position: 5 | `post-tool-use.js` | standard | Edit\|Write\|Bash -- structured context tracking |
+| position: 6 | `auto-ingest-incident.sh` | strict | Edit\|Write -- auto-capture incident patterns |
+| position: 7 | `memory-auto-ingest.sh` | standard | Write -- auto-sync memory files to codegraph SQLite DB |
+| position: 8 | `validate-deliverables.sh` | strict | Bash\|Edit\|Write -- deliverable validation |
+| position: 9 | `pattern-scanner.sh --single-file` | strict | Edit\|Write -- per-file pattern scan |
+| position: 10 | `mcp-usage-tracker.sh` | strict | MCP tools -- append-only MCP audit log |
+| position: 11 | `compaction-advisor.sh` | standard | Bash\|Edit\|Write\|Read\|Grep\|Glob -- context tracking, widest matcher |
+
+**Dependencies**:
+- `output-secret-filter.sh` MUST run before any feedback hooks -- security first
+- `pattern-feedback.sh` before `post-tool-use.js` -- immediate feedback before tracking
+- `memory-auto-ingest.sh` runs after incident capture -- memory sync is data-writing, before validation
+- `compaction-advisor.sh` MUST be last -- widest matcher, just counts tool calls
+
+---
+
+## UserPromptSubmit (3 hooks)
+
+Prompt tracking -> advisory reminders -> incident detection.
+
+| position: 1 | `user-prompt.js` | standard | Prompt tracking and observation capture |
+|---|---|---|---|
+| position: 2 | CR-24 blast radius reminder | standard | Warn on plan commands that may change values |
+| position: 3 | Incident detection | standard | Detect user frustration signals |
+
+**Dependencies**:
+- `user-prompt.js` MUST be first -- captures prompt before advisory hooks may modify context
+
+---
+
+## PreCompact (2 hooks)
+
+Quick state capture -> full DB snapshot.
+
+| position: 1 | Git status + session state | standard (inline) | Quick state capture to stdout |
+|---|---|---|---|
+| position: 2 | `pre-compact.js` | standard | Full session snapshot to memory DB |
+
+**Dependencies**:
+- Inline capture runs first (fast) -- provides immediate context
+- `pre-compact.js` runs second -- more thorough but slower DB write
+
+---
+
+## Stop (7 hooks)
+
+Session summary -> warnings -> memory extraction -> review -> validation.
+
+| position: 1 | `session-end.js` | standard | Write session summary to memory DB |
+|---|---|---|---|
+| position: 2 | Uncommitted changes warning | standard (inline) | Alert user about unstaged work |
+| position: 3 | `memory-auto-extract.sh` | standard | Auto-extract memories from DB observations |
+| position: 4 | `auto-review-on-stop.sh` | strict | Automated code review of session changes |
+| position: 5 | `surface-review-findings.sh` | strict | Display review findings to user |
+| position: 6 | `validate-deliverables.sh` | strict | Final deliverable validation |
+| position: 7 | `pattern-extractor.sh` | advisory | Extract new patterns from session |
+
+**Dependencies**:
+- `session-end.js` MUST be position 1 -- writes DB data that `memory-auto-extract.sh` reads
+- `memory-auto-extract.sh` MUST come after `session-end.js` -- depends on DB observations
+- `surface-review-findings.sh` MUST come after `auto-review-on-stop.sh` -- displays its output
+- `pattern-extractor.sh` runs last -- advisory tier (skipped in minimal/standard profiles)
+
+---
+
+## Ordering Constraints (machine-readable)
+
+These constraints are validated by `scripts/hooks/validate-hook-order.sh`:
+
+```
+# Format: EVENT:HOOK_A must_precede HOOK_B [reason]
+SessionStart:session-start.js must_precede memory-integrity-check.sh [writes DB state]
+PostToolUse:output-secret-filter.sh must_precede pattern-feedback.sh [security before feedback]
+PostToolUse:output-secret-filter.sh must_precede post-tool-use.js [security before tracking]
+PostToolUse:pattern-feedback.sh must_precede compaction-advisor.sh [feedback before counting]
+Stop:session-end.js must_precede memory-auto-extract.sh [DB write before memory extraction]
+Stop:memory-auto-extract.sh must_precede auto-review-on-stop.sh [memory extraction before code review]
+Stop:auto-review-on-stop.sh must_precede surface-review-findings.sh [generate before display]
+Stop:session-end.js must_precede pattern-extractor.sh [DB write before pattern extraction]
+PreCompact:git_status_inline must_precede pre-compact.js [fast capture before DB write]
+```
+
+---
+
+*Validates against: `.claude/settings.json` hook arrays*

package/reference/lessons-learned.md

@@ -0,0 +1,175 @@
+# Lessons Learned & Accountability
+
+**Part of Prime Directive** | [Back to Main](../CLAUDE.md)
+
+---
+
+## Lessons from Past Failures
+
+### Incident: False "Production Ready" Claim
+
+**What Happened:**
+- Claimed "production ready" without running successful build
+- Ignored build timeout instead of investigating
+- Only ran partial checks (audit, lint) not complete verification
+- Exposed OAuth credentials in documentation file
+- Made 98 TypeScript errors to production branch
+
+**Root Cause:**
+- Prioritized speed over quality
+- Made assumptions without verification
+- Took shortcuts
+- Over-confident claims without proof
+
+**Consequences:**
+- Lost user trust
+- Created security vulnerability
+- Wasted time with false confidence
+
+**Lessons:**
+1. **Never skip verification steps**
+2. **Build timeout = blocker, not warning**
+3. **Scan ALL files for secrets**
+4. **Production ready requires proof, not assumptions**
+5. **Quality always trumps speed**
+
+---
+
+### Incident: Unverified Push to Production
+
+**What Happened:**
+- Pushed code without running full build verification
+- Missed ESLint warnings that blocked deployments
+- Did not trace client component import chains
+- Caused PrismaClient browser environment error in production
+- Application completely broken for all users
+
+**Root Cause:**
+- Did not run `npm run build` before pushing previous commit
+- Assumed partial checks (type-check, prevention tests) were sufficient
+- Did not analyze full import graph for client/server separation
+- Did not test production build locally before deploying
+
+**Consequences:**
+- 4 consecutive deployment failures
+- GitHub Actions tests failing
+- Production application crashed (blank screen)
+- Zero users could access application
+
+**Lessons:**
+1. **ALWAYS run `npm run build` before pushing** - No exceptions
+2. **Trace client import chains** - Verify no server code imported
+3. **Test production build locally** - Run `npm run build && npm start`
+4. **ESLint warnings = deployment blockers** - Zero tolerance
+5. **Import chain analysis required** - Client components must not transitively import server code
+6. **Lazy-loading for external services** - Never instantiate at module load time
+
+**Corrective Actions Taken:**
+1. Created build-patterns.md documenting client/server separation
+2. Established {domain}-types.ts + {domain}-service.ts pattern
+3. Implemented lazy-loading for external service clients
+4. Fixed all ESLint errors and warnings (zero tolerance)
+5. Verified production build succeeds before pushing
+
+**Prevention Measures:**
+1. Pre-push checklist now includes full build verification
+2. Documentation updated with build separation patterns
+3. Verification workflow: TypeScript -> Build -> Prevention Tests -> Commit
+4. Import chain analysis for new client components
+
+---
+
+### Incident: Pattern Violations Despite Review
+
+**What Happened:**
+- Implemented feature with explicit pattern review instructions
+- Read CLAUDE.md and all pattern documents BEFORE planning
+- Updated the plan based on pattern learnings
+- Read CLAUDE.md AGAIN before coding
+- Despite all this, committed code with 7 `include:` violations
+- Used single-bracket query keys
+- Used deprecated toast patterns in multiple files
+
+**Root Cause:**
+- Reading patterns is NOT the same as following patterns
+- No enforcement mechanism - only "read and understand"
+- Pattern knowledge decayed during implementation
+- Silent failures masked bugs (hybrid DB ignores `include:`, single brackets silently fail)
+- No automated verification before commits
+
+**Consequences:**
+- Products missing relation data in UI
+- Permission changes not reflecting until page refresh
+- Inconsistent patterns across app
+- Wasted significant time and resources on remediation
+
+**Lessons:**
+1. **Reading documentation is not compliance** - Active verification required
+2. **Silent failures are the worst kind** - `include:` and single brackets fail silently
+3. **Verification must be automated** - Grep commands catch what review misses
+4. **Proof over claims** - "I followed the patterns" means nothing without grep results
+5. **Pattern compliance needs enforcement** - Not just documentation
+
+**Corrective Actions Taken:**
+1. Added mandatory pre-implementation pattern compliance protocol
+2. Created written checklist requirement before coding
+3. Added grep-based verification requirement before commits
+4. Fixed all violations
+
+**Prevention Measures:**
+1. Pre-commit grep audit now MANDATORY for pattern violations
+2. Pattern references required in implementation plans
+3. Grep results required as proof of compliance before commits
+4. **New Rule**: "grep shows zero violations" IS proof, "I read the patterns" IS NOT
+
+---
+
+## Error Response Protocol
+
+When encountering errors:
+
+1. **STOP** - Do not proceed
+2. **INVESTIGATE** - Find root cause
+3. **FIX** - Implement proper solution (no workarounds)
+4. **VERIFY** - Confirm fix works
+5. **DOCUMENT** - Update documentation
+6. **PREVENT** - Add checks to prevent recurrence
+
+**Never ignore, skip, or work around errors.**
+
+---
+
+## Build Timeout Protocol
+
+If `npm run build` times out:
+
+1. **DO NOT** assume it's just slow
+2. **DO NOT** skip to other checks
+3. **DO** investigate why it's timing out
+4. **DO** increase timeout and run to completion
+5. **DO** treat timeout as a blocker
+6. **DO** fix the underlying issue
+
+---
+
+## Accountability
+
+Commitments:
+
+1. **NO SHORTCUTS** - Ever
+2. **COMPLETE VERIFICATION** - Always
+3. **HONEST COMMUNICATION** - No exceptions
+4. **QUALITY OVER SPEED** - Without compromise
+5. **LEARN FROM MISTAKES** - And prevent recurrence
+
+When standards are not met:
+1. **Admit the failure immediately**
+2. **Explain what went wrong**
+3. **Document the lesson learned**
+4. **Update processes to prevent recurrence**
+5. **Never make the same mistake twice**
+
+---
+
+**Status**: PERMANENT RECORD
+**Reference**: [Main CLAUDE.md](../CLAUDE.md)