jettypod 3.0.1

package/docs/DECISIONS.md

@@ -0,0 +1,68 @@
+# Architectural and Technical Decisions
+
+This document records key decisions made during project discovery and epic planning.
+
+---
+
+## Project-Level Decisions
+
+### UX Approach & Tech Stack
+
+**Decision:** prototypes/test
+
+**Rationale:** Testing
+
+**Date:** 10/30/2025
+
+---
+
+## Epic-Level Decisions
+
+### Epic #237: Real-time Collaboration
+
+**Architecture:** WebSockets with Socket.io
+
+*Rationale:* Bidirectional communication needed, Socket.io provides automatic fallbacks and reconnection
+
+*Date:* 10/29/2025
+
+**State Management:** Redux Toolkit
+
+*Rationale:* Need centralized state for connection status across multiple components
+
+*Date:* 10/29/2025
+
+**Error Handling:** Exponential backoff with jitter for reconnection
+
+*Rationale:* Prevents thundering herd when server recovers, jitter distributes reconnection attempts evenly
+
+*Date:* 10/31/2025
+
+**Testing Strategy:** Integration tests with mock Socket.io server
+
+*Rationale:* Allows testing reconnection logic and state synchronization without real server dependency
+
+*Date:* 10/31/2025
+
+---
+
+### Epic #238: Real-time System
+
+**Architecture:** WebSockets
+
+*Rationale:* Real-time bidirectional communication required
+
+*Date:* 10/29/2025
+
+---
+
+### Epic #242: Epic Needs Discovery
+
+**Architecture:** GraphQL API
+
+*Rationale:* Flexible querying and strong typing needed for complex data requirements
+
+*Date:* 10/29/2025
+
+---
+

package/docs/README.md

@@ -0,0 +1,48 @@
+# JettyPod Documentation
+
+## 📁 Documentation Structure
+
+### Core Documentation
+- **[Project Plan](plans/jettypod-project-plan.md)** - Full project roadmap with epics and stories
+- **[Epic 2 Implementation Summary](epic2-implementation-summary.md)** - Latest completed features
+- **[User QA Checklist](epic2-qa-user-checklist.md)** - User-oriented testing guide
+
+### Methodology & Standards
+- **[core-jettypod-methodology/](core-jettypod-methodology/)** - JettyPod operating guides and standards
+  - `jettypod-operating-guide.md` - Core methodology
+  - `jettypod-comprehensive-standards.md` - Coding standards
+  - `jettypod-technical-checklist.md` - Technical requirements
+
+### Technical Documentation
+- **[Claude Interceptor Setup](claude-interceptor-setup.md)** - Natural language detection setup
+- **[QA Checklist](epic2-qa-checklist.md)** - Technical QA for Epic 2
+
+### Research & Explorations
+- **[explorations/](explorations/)** - Research and experiments
+  - `claude-interception-analysis.md` - Different interception approaches
+  - `use-case-detection-methods.md` - Detection method research
+  - `context-management-requirements.md` - Context system design
+
+### Implementation Plans
+- **[plans/implementation-plans/](plans/implementation-plans/)** - Detailed story implementations
+- **[qa/](qa/)** - QA checklists and test plans
+
+## 📊 Current Status
+
+### ✅ Completed
+- Epic 1: Basic CLAUDE.md management
+- Epic 2: Use case detection & smart mode selection
+
+### 🚀 In Progress
+- Epic 3: Pattern detection & learning
+
+### 📅 Planned
+- Epic 4: Natural language intelligence
+- Epic 5: VS Code extension
+- Epic 6: PM experience optimization
+
+## 🔗 Quick Links
+
+- [Back to Main README](../README.md)
+- [Quick Start Guide](../QUICK_START.md)
+- [Installation Guide](../INSTALLATION.md)

package/docs/STANDARDS-SYSTEM-DOCUMENTATION.md

@@ -0,0 +1,374 @@
+# JettyPod Standards System - Complete Technical Documentation
+
+## System Overview
+
+The JettyPod standards system is an adaptive, violation-based code standards enforcement mechanism that progressively reveals standards to Claude AI based on actual violations detected during development. It starts minimal and grows based on real mistakes, avoiding overwhelming developers with unnecessary rules.
+
+---
+
+## User Journeys & Use Cases
+
+### Journey 1: Fresh Project Initialization
+
+**Starting state:** New project directory, no JettyPod configuration
+
+**Step-by-step process:**
+
+1. **User runs:** `jettypod init`
+
+2. **System creates `.jettypod/config.json`:**
+   ```json
+   {
+     "name": "project-name",
+     "mode": "discovery",    // default
+     "stage": "starting",     // or detected based on file count
+     "useCase": "exploring",  // default
+     "bundles": ["core"]      // default
+   }
+   ```
+
+3. **System generates CLAUDE.md with:**
+
+   - NO violations file exists yet (`.jettypod/violations.json` not created)
+   - StandardsEngine loads `lib/comprehensive-standards-full.json` (114 standards)
+   - Prescribes ONLY critical standards from "core" bundle that match stage
+   - For "starting" stage with "core" bundle, this typically includes 7 critical standards:
+     - project.structure.directory
+     - file.naming.component  
+     - file.naming.utility
+     - data.immutability.ids
+     - data.immutability.dates
+     - data.money.storage
+     - error.handling.user_feedback
+
+5. **What appears in CLAUDE.md:**
+   ```xml
+   <standards>
+   CRITICAL RULES - ALWAYS FOLLOW:
+   • Feature-based structure (❌ Flat structure with all files in src/)
+   • PascalCase.tsx for components (❌ user-profile.tsx)
+   • camelCase for utils (❌ format-date.ts)
+   • UUID strings for IDs (❌ 123 (number ID))
+   • ISO 8601 date strings (❌ Date objects in state)
+   • Money as cents (❌ 19.99 as float)
+   • Toast + Sentry for errors (❌ Silent failures)
+   </standards>
+   
+   ```
+
+---
+
+### Journey 2: First Standards Violation
+
+**Starting state:** Project initialized, working in speed mode, no violations yet
+
+**Step-by-step process:**
+
+1. **User codes:** Creates file named `user-profile.tsx` (wrong naming)
+
+2. **User runs:** `jettypod violation file.naming.component`
+
+3. **System executes:**
+   - Creates `.jettypod/violations.json` (first time only)
+   - Adds entry:
+     ```json
+     {
+       "file.naming.component": {
+         "count": 1,
+         "lastSeen": "2025-09-05T16:27:31.928Z"
+       }
+     }
+     ```
+   - Outputs: `📝 Recorded violation for file.naming.component (total: 1)`
+   - Does NOT regenerate CLAUDE.md (threshold not met)
+
+4. **What changes in CLAUDE.md:** NOTHING - threshold is 3, only at 1
+
+5. **User violates same standard 2 more times:**
+   - Run: `jettypod violation file.naming.component` 
+   - Count goes to 2, no CLAUDE.md change
+   - Run: `jettypod violation file.naming.component`
+   - Count goes to 3, threshold reached!
+
+6. **On 3rd violation:**
+   - System outputs: `⚠️  This standard will now appear in CLAUDE.md`
+   - Automatically runs `jettypod generate`
+   - CLAUDE.md now shows... NOTHING NEW (it was already critical!)
+
+---
+
+### Journey 3: Non-Critical Standard Violation
+
+**Starting state:** Speed mode, starting stage, some violations recorded
+
+**Step-by-step process:**
+
+1. **User violates a HIGH priority standard:** `SCREAMING_SNAKE` for constants
+   - Run: `jettypod violation file.naming.constants` (count: 1)
+   - Run: `jettypod violation file.naming.constants` (count: 2)
+   - Nothing appears yet
+
+2. **Third violation:** `jettypod violation file.naming.constants`
+   - Count reaches 3 (threshold met)
+   - System outputs: `⚠️  This standard will now appear in CLAUDE.md`
+   - Regenerates CLAUDE.md
+
+3. **What appears in CLAUDE.md (Speed Mode):**
+   ```xml
+   <standards>
+   CRITICAL RULES - ALWAYS FOLLOW:
+   • Feature-based structure (❌ Flat structure with all files in src/)
+   • PascalCase.tsx for components (❌ user-profile.tsx)
+   [... other critical rules ...]
+   
+   WATCH: You've violated these before:
+   • SCREAMING_SNAKE for constants (3 violations)
+   </standards>
+   ```
+
+4. **Important:** In speed mode, this ONLY works for HIGH priority
+   - If you violate a MEDIUM priority standard 100 times, it will NEVER appear
+   - Speed mode filter: critical (always) + high (if violated)
+
+---
+
+### Journey 4: Switching Modes
+
+**Starting state:** Speed mode with some violations recorded
+
+**Step-by-step process:**
+
+1. **Current state in speed mode:**
+   - 7 critical standards showing
+   - 1 high priority standard with 3 violations showing
+   - 2 medium priority standards with 5 violations each (NOT showing)
+
+2. **User runs:** `jettypod discovery`
+   - Changes mode in `.jettypod/config.json`
+
+3. **User runs:** `jettypod generate`
+
+4. **What changes in CLAUDE.md:**
+   - Same 7 critical standards (still showing)
+   - Same 1 high priority with violations (still showing)
+   - NOW ALSO: 2 medium priority standards appear in WATCH section!
+   - Discovery mode shows ALL priorities that meet threshold
+
+5. **Format stays the same:**
+   - Still uses shortRule + antipattern format
+   - The `mode` parameter doesn't affect formatting
+   - Only affects which standards are prescribed
+
+---
+
+### Journey 5: Adding a Bundle
+
+**Starting state:** Core bundle only, React project
+
+**Step-by-step process:**
+
+1. **User runs:** `jettypod standards add auth`
+
+2. **System updates `.jettypod/config.json`:**
+   ```json
+   "bundles": ["core", "auth"]
+   ```
+
+3. **User runs:** `jettypod generate` (or it auto-runs)
+
+4. **New critical standards from auth bundle appear:**
+   ```xml
+   <standards>
+   CRITICAL RULES - ALWAYS FOLLOW:
+   • Feature-based structure (❌ Flat structure with all files in src/)
+   [... other core critical ...]
+   • bcrypt with 10+ rounds (❌ Plain text passwords)
+   • JWT with refresh tokens (❌ Session cookies only)
+   </standards>
+   ```
+
+5. **React Detection (automatic):**
+   - System checks package.json for "react" in dependencies/devDependencies
+   - If found, automatically includes critical React standards
+   - User doesn't need to add "react" bundle manually for critical standards
+
+---
+
+### Journey 6: Stage Progression
+
+**Starting state:** "starting" stage with violations
+
+**Step-by-step process:**
+
+1. **Current stage: "starting"**
+   - Shows standards with stages: ["empty"] or ["starting"] or ["empty", "starting"]
+   - Has 20 eligible standards based on stage
+
+2. **User runs:** `jettypod stage growing`
+
+3. **System updates stage in config.json**
+
+4. **User runs:** `jettypod generate`
+
+5. **What changes:**
+   - Now shows standards with stages including "growing"
+   - Cumulative: still shows all "empty" and "starting" standards
+   - Plus new ones marked for "growing" stage
+   - Might jump from 20 to 35 eligible standards
+
+6. **Stage Order (cumulative):**
+   - empty → shows only "empty" standards
+   - starting → shows "empty" + "starting"
+   - growing → shows "empty" + "starting" + "growing"
+   - mature → shows "empty" + "starting" + "growing" + "mature"
+   - production → shows ALL standards
+
+---
+
+### Journey 7: Invalid Standard Violation
+
+**Starting state:** Any state
+
+**Step-by-step process:**
+
+1. **User runs:** `jettypod violation some.fake.standard`
+
+2. **System behavior:**
+   - Does NOT validate the ID exists
+   - Creates/updates violation record anyway
+   - Saves to `.jettypod/violations.json`:
+     ```json
+     {
+       "some.fake.standard": {
+         "count": 1,
+         "lastSeen": "2025-09-05T16:30:00.000Z"
+       }
+     }
+     ```
+
+3. **On reaching threshold (3 violations):**
+   - Shows warning message as usual
+   - Regenerates CLAUDE.md
+   - But standard never appears (doesn't exist in library)
+   - Violation remains in file forever
+
+---
+
+### Journey 8: Development Workflow Over Time
+
+**Day 1: Project Start**
+- Init in "starting" stage
+- See 7 critical core standards
+
+**Day 3: First mistakes**
+- Violate `file.naming.constants` 3 times
+- New section appears: "WATCH: You've violated these before"
+- Now seeing 8 standards total
+
+**Day 7: Adding authentication**
+- Run: `jettypod standards add auth`
+- 2 new critical auth standards appear
+- Now seeing 10 standards total
+
+**Day 14: Growing pains**
+- Run: `jettypod stage growing`
+- 5 more critical standards become eligible
+- Previous violations still showing
+- Now seeing 15 standards total
+
+**Day 30: Cleanup attempt**
+- Want to reset violations
+- Must manually delete `.jettypod/violations.json`
+- After regeneration, back to only critical standards
+- Lost history of what was problematic
+
+---
+
+## System Limitations & Gotchas
+
+### Things That Don't Work As Expected:
+
+1. **Violations Never Expire**
+   - Once recorded, violations persist forever
+   - No decay or time-based reduction
+   - Only way to reset: delete `.jettypod/violations.json`
+
+2. **No Validation**
+   - Can record violations for non-existent standards
+   - These take up space but never appear in CLAUDE.md
+   - No warning that standard ID is invalid
+
+3. **No Validation**
+   - Can record violations for non-existent standards
+   - These take up space but never appear in CLAUDE.md
+   - No warning that standard ID is invalid
+
+3. **Mode Parameter Ignored in Formatting**
+   - `formatForClaude(prescribed, mode)` receives mode but doesn't use it
+   - Format is always: shortRule + antipattern
+   - Mode only affects which standards are prescribed, not how they look
+
+4. **React Detection Is Shallow**
+   - Only checks dependencies and devDependencies
+   - Doesn't check peerDependencies
+   - Doesn't detect React-based frameworks (Next.js, etc.)
+
+5. **Threshold Is Hardcoded**
+   - Always 3 for every standard
+   - Can't have different thresholds for different severities
+   - Can't adjust based on team preferences
+
+---
+
+## File System State at Each Stage
+
+### After Init:
+```
+.jettypod/
+  config.json         # Configuration
+CLAUDE.md            # Generated with critical standards only
+```
+
+### After First Violation:
+```
+.jettypod/
+  config.json
+  violations.json     # NEW: Created with first violation
+CLAUDE.md            # Unchanged if under threshold
+```
+
+### After Threshold Reached:
+```
+.jettypod/
+  config.json
+  violations.json     # Updated count
+CLAUDE.md            # REGENERATED: Now includes violated standard
+```
+
+### After Mode/Stage Change:
+```
+.jettypod/
+  config.json         # Updated mode/stage
+  violations.json     # Unchanged
+CLAUDE.md            # Must manually regenerate
+```
+
+---
+
+## Quick Reference: What Triggers CLAUDE.md Changes
+
+### Automatic Regeneration:
+- When violation threshold (3) is reached for any standard
+- During `jettypod init`
+
+### Manual Regeneration Required:
+- After changing mode: `jettypod speed/discovery/production/recovery`
+- After changing stage: `jettypod stage <stage>`
+- After adding bundles: `jettypod standards add <bundle>`
+- After changing use case: `jettypod use-case <case>`
+
+### What Never Triggers Changes:
+- Violations below threshold
+- Editing violations.json manually
+- Changing comprehensive-standards-full.json
+- Installing React (must regenerate after)