jettypod 4.1.2 → 4.1.4

package/docs/TDD-INFRASTRUCTURE-STRATEGY.md

@@ -0,0 +1,1374 @@
+# TDD Infrastructure & Testing Strategy for JettyPod
+
+**Date**: 2025-11-14
+**Scope**: Test-Driven Development strategy across Feature Planning → Speed → Stable → Production modes, plus standalone chores
+**Focus**: WHEN tests run, WHAT tests run, maximum velocity + quality assurance
+
+---
+
+## Executive Summary
+
+**Philosophy**: Tests should run at the right time, in the right place, with the right scope to maximize feedback velocity while maintaining quality gates.
+
+**Key Insight**: Your pre-commit hook is currently **disabled** (`.git/hooks/pre-commit.disabled`). This is actually smart for your workflow, but you need a better strategy.
+
+**Recommendation**: Different test execution strategies for different workflow phases + smart git hooks that adapt to context.
+
+---
+
+## Current State Analysis
+
+### What You Have Today
+
+**Test Infrastructure:**
+- ✅ Jest for unit tests
+- ✅ Cucumber for BDD tests
+- ✅ Test cleanup script
+- ✅ `npm test` runs: unit → BDD → cleanup
+
+**Git Hooks:**
+- ✅ `post-commit`: Updates work item status todo → in_progress, regenerates docs
+- ✅ `post-merge`: Updates work item status → done when merging to main
+- ⚠️ `pre-commit`: **DISABLED** - would run full test suite
+
+**Test Script:**
+```json
+"test": "npm run test:unit && npm run test:bdd && npm run test:cleanup"
+```
+
+**Problems with current pre-commit hook:**
+1. Runs ENTIRE test suite on every commit → slow
+2. Blocks commits during TDD red-green-refactor cycle
+3. Not context-aware (speed mode vs stable mode have different needs)
+4. No differentiation between local commits vs push to remote
+
+**Why it's disabled**: Smart move. Full test suite on every commit kills velocity.
+
+---
+
+## The TDD Testing Strategy
+
+### Core Principle: Context-Aware Testing
+
+Different workflow phases need different test strategies:
+
+| Phase | Test Focus | Speed Need | Quality Gate |
+|-------|-----------|------------|--------------|
+| **Feature-planning** | Infrastructure validation | Very fast | Syntax check |
+| **Speed-mode** | Happy path only | Fast iteration | BDD happy path passes |
+| **Stable-mode** | Comprehensive coverage | Thorough validation | All BDD scenarios pass |
+| **Production-mode** | Security/scale/compliance | Thorough validation | Production scenarios pass |
+| **Standalone chore** | Isolated functionality | Fast iteration | Relevant tests pass |
+
+---
+
+## Test Execution Timeline: WHEN to Run Tests
+
+### 1. Feature-Planning Phase
+
+**Test Activity:**
+- ✅ Write BDD scenario (happy path)
+- ✅ Write step definitions
+- ✅ **NEW**: Validate test infrastructure
+
+**When tests run:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ After creating .feature + .steps.js files:                 │
+│   → Dry-run validation (5 seconds)                         │
+│   → Ensures syntax correct + steps match                   │
+│   → Catches errors BEFORE speed-mode starts                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**No git hook needed** - skill executes validation internally.
+
+**Command:**
+```bash
+npx cucumber-js --dry-run features/[feature-slug].feature
+```
+
+**What this catches:**
+- Step definition syntax errors
+- Missing step implementations
+- Gherkin syntax errors
+- Import/require errors
+
+**Why dry-run not full execution:**
+- Implementation doesn't exist yet
+- Just validating test infrastructure
+- Very fast (< 5s)
+
+---
+
+### 2. Speed-Mode Phase
+
+**Test Activity:**
+- ✅ Implement code to make happy path pass
+- ✅ Run BDD tests continuously
+- ✅ Iterate until tests pass
+
+**When tests run:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ During implementation (inside skill loop):                  │
+│   → After each code change                                  │
+│   → Only BDD tests for THIS feature                        │
+│   → Fast feedback loop (30-60s)                            │
+│                                                             │
+│ Before marking chore done:                                  │
+│   → Full feature BDD test suite                            │
+│   → Ensures happy path works end-to-end                    │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before commit (pre-commit hook - SMART VERSION):           │
+│   → Quick smoke test (30s)                                 │
+│   → Only tests related to changed files                    │
+│   → Can be skipped with --no-verify if iterating          │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before push (pre-push hook - NEW):                         │
+│   → Full test suite (unit + BDD)                           │
+│   → Harder to bypass                                        │
+│   → Quality gate before sharing work                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Git hooks strategy:**
+- **pre-commit**: FAST, FOCUSED, BYPASSABLE - for rapid iteration
+- **pre-push**: COMPREHENSIVE, MANDATORY - before sharing
+
+---
+
+### 3. Stable-Mode Phase
+
+**Test Activity:**
+- ✅ Add error handling + validation
+- ✅ Create error/edge case scenarios
+- ✅ Run comprehensive test suite
+- ✅ Ensure no regressions
+
+**When tests run:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ During implementation (inside skill loop):                  │
+│   → After each code change                                  │
+│   → ALL BDD scenarios for feature                          │
+│   → Regression check (happy path still works)              │
+│   → Timeout protection (60s)                               │
+│                                                             │
+│ Before marking chore done:                                  │
+│   → Full feature BDD test suite                            │
+│   → All unit tests (if any created)                        │
+│   → Ensures comprehensive coverage                         │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before commit (pre-commit hook - SMART VERSION):           │
+│   → Run tests for changed files + dependencies             │
+│   → ~1-2 minutes acceptable (more thorough phase)          │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before push (pre-push hook):                               │
+│   → FULL test suite (unit + BDD + cleanup)                 │
+│   → Hard requirement                                        │
+│   → Quality gate before merge                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 4. Production-Mode Phase
+
+**Test Activity:**
+- ✅ Add security/scale/compliance scenarios
+- ✅ Implement production hardening
+- ✅ Run production scenarios
+
+**When tests run:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ During implementation (inside skill loop):                  │
+│   → After each code change                                  │
+│   → Production scenarios with @production tag               │
+│   → Longer timeout (2 minutes)                             │
+│   → May include performance benchmarks                     │
+│                                                             │
+│ Before marking chore done:                                  │
+│   → ALL scenarios (happy + error + production)             │
+│   → Full regression suite                                   │
+│   → Performance benchmarks (if defined)                    │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before push (pre-push hook):                               │
+│   → FULL test suite including production scenarios         │
+│   → Performance regression check                            │
+│   → Security test validation                               │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before merge to main (CI/CD - RECOMMENDED):                │
+│   → Full test suite on clean checkout                      │
+│   → Performance benchmarks against baseline                │
+│   → Security scanning                                       │
+│   → Final quality gate                                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 5. Standalone Chore Phase
+
+**Test Activity:**
+- ✅ Write tests for isolated functionality
+- ✅ Implement with safety patterns
+- ✅ Run relevant tests only
+
+**When tests run:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ During implementation (TDD cycle):                          │
+│   → After each code change                                  │
+│   → Only tests for THIS chore's scope                      │
+│   → Fast iteration (< 30s)                                 │
+│                                                             │
+│ Before marking chore done:                                  │
+│   → Tests for chore scope                                   │
+│   → Smoke test to ensure no breakage elsewhere            │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before commit (pre-commit hook - SMART VERSION):           │
+│   → Tests for changed files                                 │
+│   → Quick smoke test                                        │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ Before push (pre-push hook):                               │
+│   → Full test suite (ensure no regressions)                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Smart Git Hooks Design
+
+### Problem with Current Approach
+
+**Your disabled pre-commit hook:**
+```javascript
+// Runs EVERYTHING on EVERY commit
+execSync('npm test', { stdio: 'inherit' });
+```
+
+**Why this kills velocity:**
+1. Full test suite might take 2-5 minutes
+2. Blocks TDD red-green-refactor cycle
+3. Discourages frequent commits
+4. Tempts developers to use `--no-verify` always
+
+### Solution: Context-Aware Hooks
+
+#### Smart Pre-Commit Hook (NEW)
+
+**Philosophy**: Fast, focused, helpful during iteration.
+
+```javascript
+#!/usr/bin/env node
+// Smart pre-commit hook: Fast, focused tests
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Skip if not a real project
+if (!fs.existsSync('package.json')) process.exit(0);
+
+// Get current work context
+const currentWorkPath = '.jettypod/current-work.json';
+let currentWork = null;
+let workMode = null;
+
+if (fs.existsSync(currentWorkPath)) {
+  currentWork = JSON.parse(fs.readFileSync(currentWorkPath, 'utf-8'));
+  workMode = currentWork.mode; // speed, stable, production
+}
+
+// Get changed files
+const changedFiles = execSync('git diff --cached --name-only', { encoding: 'utf-8' })
+  .split('\n')
+  .filter(f => f.trim());
+
+console.log(`\n🧪 Running focused tests (${workMode || 'general'} mode)...\n`);
+
+try {
+  // Strategy varies by mode
+  if (workMode === 'speed') {
+    // SPEED MODE: Very fast, just syntax and current feature
+    console.log('Speed mode: Fast validation only');
+
+    // 1. Lint changed files
+    const jsFiles = changedFiles.filter(f => f.endsWith('.js'));
+    if (jsFiles.length > 0) {
+      console.log('  → Linting changed files...');
+      // Could add: execSync(`eslint ${jsFiles.join(' ')}`, { stdio: 'inherit' });
+    }
+
+    // 2. If feature file changed, validate it
+    const featureFiles = changedFiles.filter(f => f.endsWith('.feature'));
+    if (featureFiles.length > 0) {
+      console.log('  → Validating BDD scenarios...');
+      featureFiles.forEach(f => {
+        execSync(`npx cucumber-js --dry-run ${f}`, { stdio: 'inherit' });
+      });
+    }
+
+    // 3. Run only tests for current feature (if working on feature)
+    if (currentWork && currentWork.parent_id) {
+      const db = require('./.jettypod/work.db');
+      // Get feature's scenario file
+      // Run only that feature's tests
+      console.log('  → Testing current feature only...');
+      // execSync('npx cucumber-js features/current-feature.feature', { stdio: 'inherit' });
+    }
+
+    console.log('\n✅ Speed mode validation passed (~15s)\n');
+
+  } else if (workMode === 'stable') {
+    // STABLE MODE: More thorough, but still focused
+    console.log('Stable mode: Focused regression testing');
+
+    // 1. Run unit tests for changed files
+    const testFiles = changedFiles
+      .filter(f => f.endsWith('.js') && !f.includes('node_modules'))
+      .map(f => f.replace(/\.js$/, '.test.js'))
+      .filter(f => fs.existsSync(f));
+
+    if (testFiles.length > 0) {
+      console.log('  → Running unit tests for changed files...');
+      execSync(`npx jest ${testFiles.join(' ')}`, { stdio: 'inherit' });
+    }
+
+    // 2. Run current feature's full BDD suite
+    if (currentWork && currentWork.parent_id) {
+      console.log('  → Running full BDD suite for current feature...');
+      // Run all scenarios for this feature
+    }
+
+    console.log('\n✅ Stable mode validation passed (~45s)\n');
+
+  } else if (workMode === 'production') {
+    // PRODUCTION MODE: Comprehensive, including production scenarios
+    console.log('Production mode: Comprehensive validation');
+
+    // Run full suite but with focus on production scenarios
+    execSync('npm run test:unit', { stdio: 'inherit' });
+    execSync('npx cucumber-js --tags "@production"', { stdio: 'inherit' });
+
+    console.log('\n✅ Production mode validation passed (~90s)\n');
+
+  } else {
+    // STANDALONE CHORE or NO CONTEXT: Focused on changed files only
+    console.log('Standalone: Testing changed files only');
+
+    // Run tests that match changed files
+    const testPattern = changedFiles
+      .filter(f => f.endsWith('.js'))
+      .map(f => path.basename(f, '.js'))
+      .join('|');
+
+    if (testPattern) {
+      execSync(`npx jest --testNamePattern="${testPattern}"`, { stdio: 'inherit' });
+    }
+
+    console.log('\n✅ Focused tests passed (~20s)\n');
+  }
+
+  console.log('💡 Tip: Use --no-verify to skip if iterating rapidly\n');
+  process.exit(0);
+
+} catch (err) {
+  console.log('\n❌ Tests failed!\n');
+  console.log('Options:');
+  console.log('  1. Fix the failing tests');
+  console.log('  2. Use --no-verify to skip (not recommended)');
+  console.log('  3. Use git commit --amend to adjust\n');
+  process.exit(1);
+}
+```
+
+**Key features:**
+- ⚡ Context-aware: Different strategies for speed/stable/production
+- ⚡ Fast: 15-90s depending on mode
+- ⚡ Focused: Only tests relevant to changes
+- ⚡ Bypassable: Can skip with --no-verify for rapid iteration
+- ⚡ Helpful: Tells you what it's doing and why
+
+---
+
+#### Smart Pre-Push Hook (NEW)
+
+**Philosophy**: Comprehensive quality gate before sharing.
+
+```javascript
+#!/usr/bin/env node
+// Pre-push hook: Comprehensive quality gate
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+console.log('\n🚀 Running full test suite before push...\n');
+console.log('This ensures code quality before sharing with team.\n');
+
+try {
+  // ALWAYS run full suite before push
+  console.log('1/3 Running unit tests...');
+  execSync('npm run test:unit', { stdio: 'inherit' });
+
+  console.log('\n2/3 Running BDD tests...');
+  execSync('npm run test:bdd', { stdio: 'inherit' });
+
+  console.log('\n3/3 Running cleanup validation...');
+  execSync('npm run test:cleanup', { stdio: 'inherit' });
+
+  console.log('\n✅ All tests passed! Push approved.\n');
+  process.exit(0);
+
+} catch (err) {
+  console.log('\n❌ Tests failed! Push blocked.\n');
+  console.log('⚠️  Pre-push hooks are harder to bypass (intentionally).\n');
+  console.log('Options:');
+  console.log('  1. Fix the failing tests (recommended)');
+  console.log('  2. Use --no-verify to force push (use sparingly)\n');
+  console.log('Why this matters:');
+  console.log('  • Pushing broken code affects the whole team');
+  console.log('  • CI/CD will fail anyway');
+  console.log('  • Better to catch issues locally\n');
+  process.exit(1);
+}
+```
+
+**Key features:**
+- 🛡️ Comprehensive: Full test suite always
+- 🛡️ Quality gate: Before sharing with team
+- 🛡️ Clear messaging: Explains why it matters
+- 🛡️ Harder to bypass: Requires explicit --no-verify
+
+---
+
+### Hook Comparison
+
+| Hook | When | Speed | Scope | Bypassable | Purpose |
+|------|------|-------|-------|------------|---------|
+| **pre-commit** | Every commit | Fast (15-90s) | Focused on changes | Yes (--no-verify) | Rapid iteration feedback |
+| **pre-push** | Before push | Full (2-5min) | Complete test suite | Technically yes, discouraged | Quality gate before sharing |
+| **post-commit** | After commit | Instant | No tests | N/A | Status tracking + docs |
+| **post-merge** | After merge to main | Instant | No tests | N/A | Mark work done |
+
+---
+
+## Test Organization Strategy
+
+### Test Types and When to Use Them
+
+#### 1. Unit Tests (Jest)
+
+**What:** Test isolated functions/modules in isolation.
+
+**When to write:**
+- Stable mode (when adding error handling)
+- Standalone chores (for utility functions)
+- Complex algorithms or business logic
+
+**When to run:**
+- During development (watch mode)
+- Pre-commit (for changed files)
+- Pre-push (all unit tests)
+
+**Structure:**
+```
+lib/
+  merge-lock.js
+  merge-lock.test.js        ← Unit tests here
+  validators.js
+  validators.test.js        ← Unit tests here
+```
+
+**Example:**
+```javascript
+// lib/validators.test.js
+describe('validateEmail', () => {
+  it('accepts valid emails', () => {
+    expect(validateEmail('user@example.com')).toBe(true);
+  });
+
+  it('rejects invalid emails', () => {
+    expect(validateEmail('not-an-email')).toBe(false);
+  });
+
+  it('handles null/undefined', () => {
+    expect(validateEmail(null)).toBe(false);
+    expect(validateEmail(undefined)).toBe(false);
+  });
+});
+```
+
+**Characteristics:**
+- ✅ Very fast (milliseconds)
+- ✅ No external dependencies
+- ✅ Great for TDD
+- ✅ Easy to debug
+- ✅ High coverage possible
+
+---
+
+#### 2. BDD Integration Tests (Cucumber)
+
+**What:** Test complete user workflows end-to-end.
+
+**When to write:**
+- Feature-planning (happy path)
+- Stable mode (error + edge cases)
+- Production mode (security/scale/compliance)
+
+**When to run:**
+- During implementation (inside skill loops)
+- Pre-commit (for current feature)
+- Pre-push (all features)
+
+**Structure:**
+```
+features/
+  merge-lock.feature              ← Gherkin scenarios
+  step_definitions/
+    merge-lock.steps.js           ← Step implementations
+  support/
+    hooks.js                      ← Before/After hooks
+    world.js                      ← Shared context
+```
+
+**Example:**
+```gherkin
+# features/merge-lock.feature
+
+Feature: Merge Lock Protection
+  Prevent simultaneous merges that could corrupt work state
+
+Scenario: Acquire lock successfully
+  Given no merge is in progress
+  When I start a merge operation
+  Then I acquire the merge lock
+  And the lock file exists
+
+Scenario: Lock blocks concurrent merge (Stable mode)
+  Given a merge is already in progress
+  When I attempt to start another merge
+  Then I receive a "merge in progress" error
+  And the second merge is blocked
+```
+
+**Characteristics:**
+- ⚠️ Slower (seconds per scenario)
+- ✅ Tests real integration
+- ✅ Readable by non-developers
+- ✅ Living documentation
+- ⚠️ Harder to debug
+
+---
+
+#### 3. Test Safety Infrastructure (Hooks)
+
+**What:** Ensure tests don't corrupt production code.
+
+**When to write:**
+- ALWAYS when writing BDD step definitions
+- Reference ai-test-writing-requirements.md patterns
+
+**Structure:**
+```javascript
+// features/support/hooks.js
+
+const { Before, After } = require('@cucumber/cucumber');
+const fs = require('fs');
+
+Before(function() {
+  // Track everything created
+  this.createdFiles = [];
+  this.createdDirs = [];
+
+  // Snapshot critical files
+  this.snapshots = {
+    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.snapshots?.packageJson) {
+    fs.writeFileSync('package.json', this.snapshots.packageJson);
+  }
+
+  // Clean up created files
+  this.createdFiles?.forEach(file => {
+    if (fs.existsSync(file)) {
+      try { fs.unlinkSync(file); } catch (e) {}
+    }
+  });
+
+  // Clean up created directories (reverse order)
+  this.createdDirs?.reverse().forEach(dir => {
+    if (fs.existsSync(dir)) {
+      try { fs.rmSync(dir, { recursive: true }); } catch (e) {}
+    }
+  });
+});
+```
+
+**Characteristics:**
+- ✅ Prevents test pollution
+- ✅ Protects production code
+- ✅ Required for safe BDD tests
+- ✅ Automatic cleanup
+
+---
+
+## Recommended Testing Strategy by Workflow Phase
+
+### Feature-Planning Phase
+
+**Goal**: Validate test infrastructure, not implementation.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tests Written:                                              │
+│   ✅ BDD happy path scenario                                │
+│   ✅ Step definitions (with safety patterns)               │
+│                                                             │
+│ Tests Run:                                                  │
+│   ✅ Dry-run validation (syntax check)                     │
+│   ⏱️  ~5 seconds                                            │
+│                                                             │
+│ Git Hooks:                                                  │
+│   ❌ None (validation inside skill)                        │
+│                                                             │
+│ Quality Gate:                                               │
+│   ✅ BDD infrastructure valid                              │
+│   ✅ Step definitions match scenario                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Skill integration:**
+```javascript
+// At end of feature-planning skill
+console.log('🧪 Validating BDD infrastructure...');
+
+try {
+  execSync(`npx cucumber-js --dry-run ${scenarioFile}`, {
+    stdio: 'pipe',
+    timeout: 5000
+  });
+
+  console.log('✅ BDD infrastructure validated');
+  console.log('✅ Step definitions match scenario steps');
+  console.log('✅ Ready for speed-mode implementation');
+
+} catch (err) {
+  console.error('❌ BDD infrastructure broken:');
+  console.error(err.message);
+  console.log('\n⚠️  Fix step definitions before proceeding');
+  console.log('Common issues:');
+  console.log('  • Missing step definition for a Given/When/Then');
+  console.log('  • Syntax error in step definition');
+  console.log('  • Import/require error');
+  return; // Don't proceed
+}
+```
+
+---
+
+### Speed-Mode Phase
+
+**Goal**: Make happy path work, iterate fast.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tests Written:                                              │
+│   (inherited from feature-planning)                         │
+│                                                             │
+│ Tests Run During Implementation:                            │
+│   🔄 BDD happy path for current feature                    │
+│   ⏱️  After each code change (~30s)                        │
+│   🔄 Iterate until passing                                 │
+│                                                             │
+│ Tests Run Before Chore Complete:                            │
+│   ✅ Full feature BDD suite (happy path)                   │
+│   ⏱️  ~60s                                                  │
+│                                                             │
+│ Git Hooks:                                                  │
+│   pre-commit: Fast focused tests (~15s)                     │
+│   pre-push: Full suite (before sharing)                    │
+│                                                             │
+│ Quality Gate:                                               │
+│   ✅ Happy path scenario passes                            │
+│   ✅ Feature works end-to-end (no error handling yet)      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Skill integration:**
+```javascript
+// Inside speed-mode implementation loop
+let iteration = 0;
+const MAX_ITERATIONS = 10;
+
+while (iteration < MAX_ITERATIONS) {
+  iteration++;
+
+  // 1. Make code changes
+  console.log(`✍️  Implementing (iteration ${iteration})...`);
+  // ... use Edit/Write tools ...
+
+  // 2. Run BDD tests for THIS feature only
+  console.log('🧪 Testing happy path...');
+
+  try {
+    const result = execSync(
+      `npx cucumber-js ${featureFile}`,
+      { encoding: 'utf-8', timeout: 30000 }
+    );
+
+    // Check if happy path passed
+    if (result.includes('1 scenario (1 passed)')) {
+      console.log('✅ Happy path scenario passes!');
+      break;
+    } else {
+      console.log('❌ Scenario still failing, iterating...');
+    }
+
+  } catch (err) {
+    console.log('❌ Tests failed:', err.message);
+    // Analyze and iterate
+  }
+}
+```
+
+---
+
+### Stable-Mode Phase
+
+**Goal**: Add comprehensive robustness, ensure no regressions.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tests Written:                                              │
+│   ✅ BDD error handling scenarios                          │
+│   ✅ BDD edge case scenarios                               │
+│   ✅ Step definitions for above                            │
+│   ✅ (Optional) Unit tests for error handling logic        │
+│                                                             │
+│ Tests Run During Implementation:                            │
+│   🔄 ALL BDD scenarios for feature                         │
+│   🔄 Regression check (happy path still works)             │
+│   ⏱️  After each code change (~60s)                        │
+│   🔄 Iterate with timeout protection                       │
+│                                                             │
+│ Tests Run Before Chore Complete:                            │
+│   ✅ Full feature BDD suite (all scenarios)                │
+│   ✅ All unit tests (if any)                               │
+│   ⏱️  ~90s                                                  │
+│                                                             │
+│ Git Hooks:                                                  │
+│   pre-commit: Focused regression tests (~45s)              │
+│   pre-push: Full suite (comprehensive)                     │
+│                                                             │
+│ Quality Gate:                                               │
+│   ✅ All BDD scenarios pass                                │
+│   ✅ Error handling comprehensive                          │
+│   ✅ Edge cases covered                                    │
+│   ✅ No regressions                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Skill integration:**
+```javascript
+// Inside stable-mode implementation loop
+const MAX_ITERATIONS = 10;
+const TEST_TIMEOUT = 60000;
+
+let iteration = 0;
+let allPass = false;
+
+while (!allPass && iteration < MAX_ITERATIONS) {
+  iteration++;
+  console.log(`\n🔄 Stable mode iteration ${iteration}/${MAX_ITERATIONS}`);
+
+  // 1. Add error handling
+  console.log('✍️  Adding error handling...');
+  // ... use Edit tool ...
+
+  // 2. Run ALL scenarios for this feature
+  console.log('🧪 Running all scenarios (happy + error + edge)...');
+
+  try {
+    const result = execSync(
+      `npx cucumber-js ${featureFile}`,
+      {
+        encoding: 'utf-8',
+        timeout: TEST_TIMEOUT,
+        killSignal: 'SIGTERM'
+      }
+    );
+
+    // Check if ALL scenarios passed
+    const scenarioCount = result.match(/(\d+) scenarios? \((\d+) passed\)/);
+    if (scenarioCount && scenarioCount[1] === scenarioCount[2]) {
+      console.log('✅ All scenarios pass!');
+
+      // Also check no regressions in other features (smoke test)
+      console.log('🧪 Smoke testing other features...');
+      const smokeResult = execSync('npx cucumber-js --tags "not @wip"', {
+        encoding: 'utf-8',
+        timeout: 30000
+      });
+
+      if (!smokeResult.includes('failed')) {
+        console.log('✅ No regressions detected');
+        allPass = true;
+      } else {
+        console.log('⚠️  Regressions detected, adjusting...');
+      }
+
+    } else {
+      console.log('❌ Some scenarios failing, iterating...');
+    }
+
+  } catch (err) {
+    console.log('❌ Tests failed:', err.message);
+    // Analyze and iterate
+  }
+}
+```
+
+---
+
+### Production-Mode Phase
+
+**Goal**: Harden for production with security/scale/compliance.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tests Written:                                              │
+│   ✅ BDD production scenarios (@production tag)             │
+│   ✅ Security test scenarios                                │
+│   ✅ Performance benchmark scenarios (optional)             │
+│   ✅ Step definitions for above                            │
+│                                                             │
+│ Tests Run During Implementation:                            │
+│   🔄 Production scenarios only                              │
+│   ⏱️  After each code change (~2min)                       │
+│   🔄 Iterate until passing                                 │
+│                                                             │
+│ Tests Run Before Chore Complete:                            │
+│   ✅ ALL scenarios (happy + error + edge + production)     │
+│   ✅ Performance benchmarks (if defined)                    │
+│   ✅ Full regression suite                                  │
+│   ⏱️  ~3-5min                                               │
+│                                                             │
+│ Git Hooks:                                                  │
+│   pre-commit: Focused production tests (~90s)               │
+│   pre-push: Full comprehensive suite                        │
+│                                                             │
+│ Quality Gate:                                               │
+│   ✅ All production scenarios pass                          │
+│   ✅ Security requirements met                             │
+│   ✅ Performance targets achieved                          │
+│   ✅ Compliance validated                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Skill integration:**
+```javascript
+// Inside production-mode implementation loop
+const MAX_ITERATIONS = 10;
+const PRODUCTION_TEST_TIMEOUT = 120000; // 2 minutes
+
+let iteration = 0;
+let productionPass = false;
+
+while (!productionPass && iteration < MAX_ITERATIONS) {
+  iteration++;
+
+  // 1. Add production hardening
+  console.log('✍️  Adding production hardening...');
+  // ... security, rate limiting, monitoring, etc ...
+
+  // 2. Run production scenarios
+  console.log('🧪 Running production scenarios...');
+
+  try {
+    const result = execSync(
+      `npx cucumber-js --tags "@production" ${featureFile}`,
+      {
+        encoding: 'utf-8',
+        timeout: PRODUCTION_TEST_TIMEOUT
+      }
+    );
+
+    if (result.includes('passed')) {
+      console.log('✅ Production scenarios pass!');
+
+      // 3. Run full regression suite
+      console.log('🧪 Running full regression suite...');
+      const fullResult = execSync('npx cucumber-js', {
+        encoding: 'utf-8',
+        timeout: 180000 // 3 minutes
+      });
+
+      if (!fullResult.includes('failed')) {
+        console.log('✅ Full regression suite passes!');
+        productionPass = true;
+      }
+    }
+
+  } catch (err) {
+    console.log('❌ Production tests failed, iterating...');
+  }
+}
+```
+
+---
+
+### Standalone Chore Phase
+
+**Goal**: Test isolated functionality without breaking anything.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Tests Written:                                              │
+│   ✅ Unit tests for new functionality                       │
+│   ✅ BDD scenarios if user-facing                           │
+│   ✅ Safety patterns (hooks for cleanup)                    │
+│                                                             │
+│ Tests Run During Implementation:                            │
+│   🔄 Tests for THIS chore only                              │
+│   ⏱️  Fast iteration (< 30s)                               │
+│   🔄 TDD red-green-refactor cycle                          │
+│                                                             │
+│ Tests Run Before Chore Complete:                            │
+│   ✅ Tests for chore scope                                  │
+│   ✅ Smoke test (ensure no breakage)                        │
+│   ⏱️  ~45s                                                  │
+│                                                             │
+│ Git Hooks:                                                  │
+│   pre-commit: Tests for changed files (~20s)                │
+│   pre-push: Full suite (ensure no regressions)             │
+│                                                             │
+│ Quality Gate:                                               │
+│   ✅ New functionality works                                │
+│   ✅ No regressions in existing features                   │
+│   ✅ Safety patterns prevent corruption                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Implementation approach:**
+```javascript
+// Standalone chore TDD cycle
+// 1. Write test first (RED)
+describe('new utility function', () => {
+  it('handles the new case', () => {
+    expect(newFunction('input')).toBe('expected');
+  });
+});
+
+// Run: npm run test:unit:watch (watch mode for fast feedback)
+
+// 2. Implement (GREEN)
+function newFunction(input) {
+  return 'expected';
+}
+
+// 3. Refactor and ensure tests still pass
+
+// Before commit:
+// - Run tests for this file
+// - Smoke test other functionality
+```
+
+---
+
+## Test Execution Speed Targets
+
+### Speed is Critical for TDD
+
+| Test Type | Target Speed | Max Acceptable | Notes |
+|-----------|-------------|----------------|-------|
+| Dry-run validation | < 5s | 10s | Feature-planning phase |
+| Unit test (single file) | < 1s | 5s | Fast feedback loop |
+| Unit test (all) | < 30s | 60s | Pre-push acceptable |
+| BDD single scenario | < 10s | 30s | Integration overhead |
+| BDD single feature | < 30s | 60s | Multiple scenarios |
+| BDD all features | < 2min | 5min | Full regression |
+| Pre-commit hook | < 30s | 90s | Must not kill velocity |
+| Pre-push hook | < 3min | 5min | Comprehensive acceptable |
+
+**Why speed matters:**
+- Slow tests = developers skip tests
+- Fast feedback = more frequent testing
+- TDD requires fast red-green-refactor cycle
+
+**How to keep tests fast:**
+- ✅ Mock external dependencies
+- ✅ Use in-memory databases for tests
+- ✅ Parallelize test execution
+- ✅ Smart test selection (changed files only)
+- ✅ Separate fast unit tests from slow integration tests
+
+---
+
+## Git Hook Implementation Guide
+
+### Step 1: Install Smart Pre-Commit Hook
+
+**Create:** `.git/hooks/pre-commit`
+
+```bash
+#!/usr/bin/env node
+
+// [Full smart pre-commit hook code from earlier]
+```
+
+**Make executable:**
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+### Step 2: Install Smart Pre-Push Hook
+
+**Create:** `.git/hooks/pre-push`
+
+```bash
+#!/usr/bin/env node
+
+// [Full pre-push hook code from earlier]
+```
+
+**Make executable:**
+```bash
+chmod +x .git/hooks/pre-push
+```
+
+---
+
+### Step 3: Keep Existing Hooks
+
+**Keep:** `.git/hooks/post-commit` ✅
+**Keep:** `.git/hooks/post-merge` ✅
+
+These are perfect as-is for workflow tracking.
+
+---
+
+### Step 4: Update Skills to Reference Hooks
+
+**In feature-planning skill:**
+```javascript
+console.log(`
+✅ BDD infrastructure validated
+
+ℹ️  Testing Strategy:
+  • Feature-planning: Infrastructure validated ✅ (you are here)
+  • Speed-mode: Happy path tests (fast iteration)
+  • Stable-mode: Comprehensive error/edge tests
+  • Production-mode: Security/scale/compliance tests
+
+Git hooks will help:
+  • pre-commit: Fast focused tests during development
+  • pre-push: Full suite before sharing with team
+`);
+```
+
+---
+
+## Test Organization Best Practices
+
+### File Structure
+
+```
+jettypod-source/
+├── lib/
+│   ├── merge-lock.js              ← Implementation
+│   ├── merge-lock.test.js         ← Unit tests
+│   ├── validators.js
+│   └── validators.test.js
+│
+├── features/
+│   ├── merge-lock.feature         ← BDD scenarios
+│   ├── git-hooks.feature
+│   │
+│   ├── step_definitions/
+│   │   ├── merge-lock.steps.js    ← Step implementations
+│   │   └── git-hooks.steps.js
+│   │
+│   └── support/
+│       ├── hooks.js               ← Before/After cleanup
+│       └── world.js               ← Shared context
+│
+├── scripts/
+│   └── test-cleanup.js            ← Post-test cleanup
+│
+├── .git/hooks/
+│   ├── pre-commit                 ← Smart fast hook
+│   ├── pre-push                   ← Comprehensive gate
+│   ├── post-commit                ← Status tracking
+│   └── post-merge                 ← Mark done
+│
+└── package.json
+    └── scripts:
+        ├── test                   ← Run all tests
+        ├── test:unit              ← Unit tests only
+        ├── test:bdd               ← BDD tests only
+        ├── test:unit:watch        ← TDD watch mode
+        └── test:cleanup           ← Clean artifacts
+```
+
+---
+
+### Naming Conventions
+
+**Unit Tests:**
+- `[module].test.js` - matches implementation file
+- Example: `merge-lock.js` → `merge-lock.test.js`
+
+**BDD Features:**
+- `[feature-slug].feature` - Gherkin scenarios
+- Example: `merge-lock.feature`
+
+**Step Definitions:**
+- `[feature-slug].steps.js` - implements steps
+- Example: `merge-lock.steps.js`
+
+**Test Artifacts:**
+- Prefix with `test_` or `temp_` for easy cleanup
+- Example: `test_work.db`, `temp_config.json`
+
+---
+
+## Recommended Package.json Scripts
+
+```json
+{
+  "scripts": {
+    // Main test command - runs everything
+    "test": "npm run test:unit && npm run test:bdd && npm run test:cleanup",
+
+    // Unit tests
+    "test:unit": "NODE_ENV=test jest",
+    "test:unit:watch": "NODE_ENV=test jest --watch",
+    "test:unit:coverage": "NODE_ENV=test jest --coverage",
+
+    // BDD tests
+    "test:bdd": "NODE_ENV=test cucumber-js",
+    "test:bdd:wip": "NODE_ENV=test cucumber-js --tags @wip",
+    "test:bdd:production": "NODE_ENV=test cucumber-js --tags @production",
+
+    // Focused testing (for pre-commit)
+    "test:focused": "NODE_ENV=test jest --onlyChanged && cucumber-js --tags @wip",
+
+    // Cleanup
+    "test:cleanup": "node scripts/test-cleanup.js",
+
+    // Dry-run validation (for feature-planning)
+    "test:validate": "cucumber-js --dry-run",
+
+    // Pre-push simulation (run locally)
+    "test:pre-push": "npm test"
+  }
+}
+```
+
+---
+
+## Integration with CI/CD (Future)
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/test.yml
+name: Test Suite
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '18'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run unit tests
+      run: npm run test:unit
+
+    - name: Run BDD tests
+      run: npm run test:bdd
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v2
+      if: always()
+```
+
+**Why CI/CD is the ultimate quality gate:**
+- Clean environment (no local state)
+- Enforced on all PRs
+- Can't be bypassed
+- Tracks test history
+- Integrates with deployment
+
+---
+
+## Summary: Test Execution Timeline
+
+### Feature Workflow Timeline
+
+```
+Feature-Planning:
+  ├─ Write scenarios + step definitions
+  ├─ 🧪 Dry-run validation (~5s)
+  └─ ✅ Test infrastructure validated
+
+Speed-Mode (per chore):
+  ├─ Implement code
+  ├─ 🧪 Test happy path (~30s per iteration)
+  ├─ 🔄 Iterate until passing
+  ├─ 📝 Commit (pre-commit hook: ~15s)
+  └─ ✅ Happy path works
+
+Stable-Mode (per chore):
+  ├─ Add error/edge scenarios
+  ├─ Add error handling
+  ├─ 🧪 Test all scenarios (~60s per iteration)
+  ├─ 🔄 Iterate until passing
+  ├─ 📝 Commit (pre-commit hook: ~45s)
+  └─ ✅ Comprehensive coverage
+
+Production-Mode (per chore):
+  ├─ Add production scenarios
+  ├─ Add security/scale hardening
+  ├─ 🧪 Test production scenarios (~2min per iteration)
+  ├─ 🔄 Iterate until passing
+  ├─ 📝 Commit (pre-commit hook: ~90s)
+  └─ ✅ Production-ready
+
+Before Push (any phase):
+  ├─ 🚀 Pre-push hook runs
+  ├─ 🧪 Full test suite (~3min)
+  └─ ✅ Quality gate passed
+
+After Merge to Main:
+  ├─ 🪝 Post-merge hook
+  ├─ 📋 Mark work done
+  └─ ✅ Workflow complete
+```
+
+---
+
+## Recommendations Summary
+
+### Immediate Actions
+
+1. **✅ Enable smart pre-commit hook**
+   - Context-aware testing
+   - Fast feedback (15-90s depending on mode)
+   - Bypassable for rapid iteration
+
+2. **✅ Add pre-push hook**
+   - Comprehensive quality gate
+   - Full test suite before sharing
+   - Harder to bypass
+
+3. **✅ Add dry-run validation to feature-planning**
+   - 5-second syntax check
+   - Catches broken tests immediately
+   - Prevents wasted time in speed-mode
+
+4. **✅ Integrate test safety patterns**
+   - Reference ai-test-writing-requirements.md in skills
+   - Ensure all BDD tests use cleanup hooks
+   - Prevent test corruption
+
+### Future Enhancements
+
+5. **⚠️ Add CI/CD pipeline**
+   - GitHub Actions for automated testing
+   - Test on every PR
+   - Ultimate quality gate
+
+6. **⚠️ Add test coverage tracking**
+   - Jest coverage reports
+   - Track coverage trends
+   - Identify untested code
+
+7. **⚠️ Add performance benchmarking**
+   - Track test execution time
+   - Identify slow tests
+   - Optimize test suite
+
+---
+
+## Conclusion
+
+### The Problem You're Solving
+
+**Old approach (disabled pre-commit):**
+- ❌ Full test suite on every commit → kills velocity
+- ❌ Developers use --no-verify to bypass
+- ❌ No differentiation between rapid iteration vs sharing code
+
+**New approach (smart hooks):**
+- ✅ Fast focused tests during development
+- ✅ Comprehensive tests before sharing
+- ✅ Context-aware (speed/stable/production modes)
+- ✅ Appropriate at each workflow phase
+
+### Key Principles
+
+1. **Test at the right time** - Not all tests need to run always
+2. **Test the right things** - Focus on what changed
+3. **Test fast enough** - Speed enables frequency
+4. **Test comprehensively when it matters** - Before sharing/merging
+5. **Make tests helpful, not annoying** - Good UX increases adoption
+
+### Final Recommendation
+
+**Your pre-commit hook being disabled was a symptom of poor test execution strategy, not a problem with testing itself.**
+
+The solution isn't "no pre-commit hook" but rather "smart pre-commit hook that adapts to context and runs fast enough to be helpful."
+
+Implement:
+- Smart pre-commit (fast, focused, bypassable)
+- Smart pre-push (comprehensive, quality gate)
+- Dry-run validation in feature-planning
+- Context-aware test execution in all skills
+
+This gives you maximum velocity during development while maintaining strong quality gates before sharing code.