jettypod 3.0.1

package/docs/TEST-REWRITE-PLAN.md

@@ -0,0 +1,261 @@
+# JettyPod Test Rewrite Plan
+
+## Current State
+- **32 total scenarios**: 6 passing, 8 failing, 18 undefined
+- Tests written for legacy dual-standards system
+- Many step definitions missing or outdated
+- No unit tests (only BDD with Cucumber)
+
+## Goal
+Rewrite tests to match the new comprehensive standards engine that uses violation-based progressive disclosure.
+
+---
+
+## Phase 1: Remove Legacy Test Scenarios
+**Priority: High | Estimated: 30 minutes**
+
+### Tasks:
+- [ ] Remove/update scenarios that test for `.jettypod/standards.json` creation
+- [ ] Remove tests checking for "Legacy Standards" section in CLAUDE.md
+- [ ] Remove tests for old standards filtering (by stage/priority/bundle)
+- [ ] Remove tests expecting mode-specific formatting (speed/discovery/production)
+
+### Files to Update:
+- `.gherkin/features/01-initialization.feature`
+- `.gherkin/features/05-standards-filtering.feature`
+- `.gherkin/features/06-claude-generation.feature`
+
+---
+
+## Phase 2: Add New Standards Engine Tests
+**Priority: Critical | Estimated: 1 hour**
+
+### New Test Scenarios Needed:
+
+#### 2.1 Violation Tracking Tests
+```gherkin
+Feature: Violation-Based Standards
+  Scenario: Standards appear after threshold
+    Given JettyPod is initialized
+    When I record 2 violations for "file.naming.constants"
+    Then CLAUDE.md should not contain "SCREAMING_SNAKE"
+    When I record 1 more violation for "file.naming.constants"
+    Then CLAUDE.md should contain "SCREAMING_SNAKE for constants (3 violations)"
+```
+
+#### 2.2 Critical Standards Tests
+```gherkin
+Feature: Critical Standards Always Show
+  Scenario: Critical standards appear immediately
+    Given JettyPod is initialized in "starting" stage
+    And bundles are ["core"]
+    When I run "jettypod generate"
+    Then CLAUDE.md should contain all critical standards for core bundle
+    And CLAUDE.md should not contain non-critical standards without violations
+```
+
+#### 2.3 Bundle Detection Tests
+```gherkin
+Feature: Automatic Bundle Detection
+  Scenario: React standards auto-include when React detected
+    Given package.json contains React dependency
+    When I run "jettypod generate"
+    Then CLAUDE.md should contain React critical standards
+```
+
+#### 2.4 Mode Filtering Tests
+```gherkin
+Feature: Mode-Based Filtering
+  Scenario: Speed mode filters by priority
+    Given JettyPod is in speed mode
+    And "test.medium.standard" has 5 violations (medium priority)
+    When I run "jettypod generate"
+    Then CLAUDE.md should not contain "test.medium.standard"
+    
+  Scenario: Discovery mode shows all violated standards
+    Given JettyPod is in discovery mode
+    And "test.medium.standard" has 3 violations
+    When I run "jettypod generate"
+    Then CLAUDE.md should contain "test.medium.standard"
+```
+
+---
+
+## Phase 3: Fix Existing Step Definitions
+**Priority: High | Estimated: 45 minutes**
+
+### Step Definitions to Add/Fix:
+
+```javascript
+// Violation simulation
+Given('{string} has {int} violations', function(standardId, count) {
+  // Clear existing violations for this standard
+  const violationsPath = '.jettypod/violations.json';
+  let violations = {};
+  if (fs.existsSync(violationsPath)) {
+    violations = JSON.parse(fs.readFileSync(violationsPath));
+  }
+  violations[standardId] = {
+    count: count,
+    lastSeen: new Date().toISOString()
+  };
+  fs.writeFileSync(violationsPath, JSON.stringify(violations, null, 2));
+});
+
+// Check for specific standards sections
+Then('CLAUDE.md should contain all critical standards for {word} bundle', function(bundle) {
+  const claude = readClaude();
+  const library = JSON.parse(fs.readFileSync('lib/comprehensive-standards-full.json'));
+  const criticalStandards = Object.values(library.standards)
+    .filter(s => s.bundle === bundle && s.priority === 'critical');
+  
+  criticalStandards.forEach(standard => {
+    expect(claude).to.include(standard.shortRule);
+  });
+});
+
+// Verify violation counts
+Then('CLAUDE.md should contain {string} with {int} violations', function(text, count) {
+  const claude = readClaude();
+  expect(claude).to.include(`${text} (${count} violations)`);
+});
+
+// Check standards NOT present
+Then('CLAUDE.md should not contain non-critical standards without violations', function() {
+  const claude = readClaude();
+  const standardsSection = claude.match(/<standards>([\s\S]*?)<\/standards>/);
+  if (standardsSection) {
+    // Should only have CRITICAL RULES section, no WATCH section if no violations
+    expect(standardsSection[1]).to.not.include('WATCH:');
+  }
+});
+```
+
+---
+
+## Phase 4: Create Unit Tests
+**Priority: Medium | Estimated: 1 hour**
+
+### New Unit Test Files:
+- `tests/standards-engine.test.js`
+- `tests/violation-tracking.test.js`
+
+### Test Coverage Needed:
+```javascript
+// tests/standards-engine.test.js
+describe('StandardsEngine', () => {
+  describe('prescribe()', () => {
+    it('should include critical standards for active bundles')
+    it('should include React criticals when React detected')
+    it('should add standards that exceed violation threshold')
+    it('should filter by mode (speed vs discovery)')
+    it('should respect stage filtering')
+  });
+  
+  describe('recordViolation()', () => {
+    it('should create violation record if none exists')
+    it('should increment violation count')
+    it('should update lastSeen timestamp')
+    it('should not modify comprehensive standards file')
+  });
+  
+  describe('formatForClaude()', () => {
+    it('should separate critical and violated standards')
+    it('should show violation counts in WATCH section')
+    it('should not include non-violated standards in WATCH')
+  });
+});
+```
+
+---
+
+## Phase 5: Clean Up Test Structure
+**Priority: Low | Estimated: 30 minutes**
+
+### Improvements:
+- [ ] Consolidate duplicate step definitions
+- [ ] Add helper functions for common operations
+- [ ] Improve test data setup/teardown
+- [ ] Add test utilities file for shared functions
+
+### Helper Functions Needed:
+```javascript
+// test-helpers.js
+function resetJettyPod() {
+  // Clean .jettypod directory
+  // Reset violations
+  // Set default config
+}
+
+function setViolations(violations) {
+  // Set specific violation state for testing
+}
+
+function assertStandardPresent(standardId) {
+  // Check if standard appears in CLAUDE.md
+}
+
+function assertStandardAbsent(standardId) {
+  // Verify standard does NOT appear
+}
+```
+
+---
+
+## Phase 6: Documentation
+**Priority: Low | Estimated: 15 minutes**
+
+### Documentation Updates:
+- [ ] Update README with test running instructions
+- [ ] Document test structure and patterns
+- [ ] Add troubleshooting guide for common test failures
+- [ ] Document how to add new test scenarios
+
+---
+
+## Implementation Order
+
+1. **Immediate (Fix Breaking Tests)**
+   - Add missing step definitions
+   - Fix regex patterns for Cucumber expressions
+   - Update paths and file references
+
+2. **Next (Remove Legacy)**
+   - Clean out old standards.json checks
+   - Remove legacy formatting tests
+   - Update CLAUDE.md content assertions
+
+3. **Then (Add New Coverage)**
+   - Implement violation threshold tests
+   - Add bundle detection tests
+   - Create mode filtering tests
+
+4. **Finally (Nice to Have)**
+   - Add unit tests for standards engine
+   - Improve test organization
+   - Add documentation
+
+---
+
+## Success Criteria
+
+- [ ] All 32 scenarios have proper step definitions (no undefined)
+- [ ] Tests accurately reflect new standards engine behavior
+- [ ] Violation tracking is properly tested
+- [ ] Critical standards always-show behavior is verified
+- [ ] Mode filtering (speed vs others) is tested
+- [ ] Stage cumulative filtering is tested
+- [ ] Bundle detection (React) is tested
+- [ ] Test run completes in under 10 seconds
+- [ ] No false positives or flaky tests
+
+---
+
+## Notes
+
+- Focus on integration tests over unit tests initially
+- Prioritize testing the user-facing behavior
+- Keep tests simple and readable
+- Avoid testing implementation details
+- Each test should have a clear purpose
+- Use descriptive test names that explain the behavior

package/docs/ai-test-writing-requirements.md

@@ -0,0 +1,219 @@
+# AI Test Writing Requirements
+
+## Overview
+This document provides guidelines for AI assistants when writing tests for this codebase. These requirements balance safety with practicality.
+
+## Core Principles
+
+### 1. Track Everything You Create
+- Maintain lists of all files and directories created during tests
+- Ensure cleanup even if tests fail
+- Use try/catch blocks around cleanup operations
+
+### 2. Snapshot and Restore Critical Files
+- Take snapshots of critical files (package.json, config files) before tests
+- Restore them in After hooks unconditionally
+- Verify restoration was successful
+
+### 3. Clean Up Test Artifacts
+- Remove all test-created files (temp_*, test_*, etc.)
+- Clean up test directories you explicitly created
+- Never delete production directories (lib/, src/, node_modules/)
+
+## Required Test Structure
+
+```javascript
+const { Before, After } = require('@cucumber/cucumber');
+const fs = require('fs');
+const path = require('path');
+
+// Initialize tracking
+function initializeTracking(context) {
+  context.createdFiles = [];
+  context.createdDirs = [];
+  context.modifiedFiles = new Map();
+}
+
+Before(function() {
+  // Initialize tracking
+  initializeTracking(this);
+  
+  // Snapshot critical files
+  this.originalSnapshot = {
+    packageJson: fs.existsSync('package.json') 
+      ? fs.readFileSync('package.json', 'utf-8') 
+      : null,
+    config: fs.existsSync('.jettypod/config.json')
+      ? fs.readFileSync('.jettypod/config.json', 'utf-8')
+      : null
+  };
+});
+
+After(function() {
+  // Restore critical files FIRST
+  if (this.originalSnapshot?.packageJson) {
+    fs.writeFileSync('package.json', this.originalSnapshot.packageJson);
+  }
+  
+  // Clean up created files
+  if (this.createdFiles) {
+    this.createdFiles.forEach(file => {
+      if (fs.existsSync(file)) {
+        try { fs.unlinkSync(file); } catch (e) {}
+      }
+    });
+  }
+  
+  // Clean up created directories (in reverse order)
+  if (this.createdDirs) {
+    [...this.createdDirs].reverse().forEach(dir => {
+      if (fs.existsSync(dir)) {
+        try { fs.rmSync(dir, { recursive: true }); } catch (e) {}
+      }
+    });
+  }
+});
+```
+
+## Safe Patterns
+
+### Creating Test Files
+```javascript
+//  GOOD - Track what you create
+Given('I create a test file', function() {
+  const filename = 'test_file.js';
+  fs.writeFileSync(filename, '// test content');
+  this.createdFiles.push(filename);
+});
+```
+
+### Modifying Existing Files
+```javascript
+//  GOOD - Snapshot before modifying
+Given('package.json contains React', function() {
+  if (!this.packageBackup) {
+    this.packageBackup = fs.readFileSync('package.json', 'utf-8');
+  }
+  const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+  pkg.dependencies = pkg.dependencies || {};
+  pkg.dependencies.react = '^18.0.0';
+  fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
+});
+```
+
+### Creating Directories
+```javascript
+//  GOOD - Track all levels
+Given('I create nested directories', function() {
+  const dir = 'test/nested/dir';
+  fs.mkdirSync(dir, { recursive: true });
+  
+  // Track all levels for cleanup
+  const parts = dir.split('/');
+  let currentPath = '';
+  parts.forEach(part => {
+    currentPath = currentPath ? `${currentPath}/${part}` : part;
+    if (!this.createdDirs.includes(currentPath)) {
+      this.createdDirs.push(currentPath);
+    }
+  });
+});
+```
+
+## Dangerous Patterns to Avoid
+
+### L NEVER Do These:
+
+1. **Direct package.json modification without backup**
+```javascript
+// L WRONG - No backup
+fs.writeFileSync('package.json', modifiedContent);
+```
+
+2. **Cleanup with dangerous patterns**
+```javascript
+// L WRONG - Could delete production directories
+const dirsToDelete = ['lib', 'src', 'node_modules'];
+dirsToDelete.forEach(dir => fs.rmSync(dir, { recursive: true }));
+```
+
+3. **Untracked file creation**
+```javascript
+// L WRONG - Not tracked for cleanup
+fs.writeFileSync('test.js', 'content');
+// No this.createdFiles.push('test.js');
+```
+
+4. **Assuming cleanup will run**
+```javascript
+// L WRONG - Cleanup might not run if test crashes
+After(function() {
+  // Critical cleanup here might never execute
+});
+```
+
+## Simplified Approach (Recommended)
+
+For most tests, use a simplified approach that:
+1. Runs in the current directory (not isolated)
+2. Tracks all created files/directories
+3. Takes snapshots of critical files
+4. Restores everything in After hooks
+
+This approach is simpler than full isolation but still safe because:
+- All changes are tracked and reversed
+- Critical files are protected by snapshots
+- Cleanup is guaranteed even on failure
+
+## Testing Checklist
+
+When writing tests, ensure:
+- [ ] All created files are tracked in `this.createdFiles`
+- [ ] All created directories are tracked in `this.createdDirs`
+- [ ] package.json is snapshotted before any modification
+- [ ] Config files are snapshotted before changes
+- [ ] After hook restores all snapshots
+- [ ] After hook removes all tracked items
+- [ ] No production directories in cleanup lists
+- [ ] Cleanup uses try/catch to continue on errors
+- [ ] Test artifacts use clear naming (test_*, temp_*)
+
+## Advanced: Full Isolation (Optional)
+
+For complete safety, tests can run in isolated temp directories:
+
+```javascript
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+Before(function() {
+  // Create isolated test directory
+  this.testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+  
+  // Copy only necessary files
+  [.jettypod.js', 'package.json', 'lib'].forEach(item => {
+    // Copy to test directory
+  });
+  
+  process.chdir(this.testDir);
+});
+
+After(function() {
+  process.chdir(this.originalCwd);
+  fs.rmSync(this.testDir, { recursive: true, force: true });
+});
+```
+
+However, this approach has complications with module loading and is often overkill for most test scenarios.
+
+## Summary
+
+The key to safe test writing is:
+1. **Track everything** you create or modify
+2. **Snapshot** critical files before changes
+3. **Restore** everything in After hooks
+4. **Never** assume cleanup will run
+5. **Never** delete production directories
+
+Following these guidelines ensures tests can't corrupt the production codebase while keeping the test implementation simple and maintainable.