jettypod 4.1.2 → 4.1.4

package/docs/COMPLETE-TESTING-STRATEGY.md

@@ -0,0 +1,970 @@
+# Complete Testing Strategy for JettyPod
+
+**Date**: 2025-11-14
+**Purpose**: Honest, comprehensive testing strategy incorporating ALL test types
+**Scope**: Unit, Integration, E2E, Performance, Security, Contract, Visual, Mutation
+
+---
+
+## Honesty First: What We Actually Need
+
+### The Truth About Testing
+
+**You don't need every test type.** You need the right tests for your project.
+
+**JettyPod is a CLI tool with:**
+- Local database (SQLite)
+- Git integration
+- File system operations
+- No UI (no visual regression tests needed)
+- No external APIs (no contract tests needed yet)
+- Single-user (no load tests needed yet)
+
+**Therefore, prioritize:**
+1. ✅ **Unit tests** - Most important (fast, reliable)
+2. ✅ **Integration tests** - Important (BDD scenarios)
+3. ✅ **E2E tests** - Some (full CLI workflows)
+4. ⚠️ **Performance tests** - Basic (timing checks)
+5. ⚠️ **Security tests** - Basic (input validation)
+6. ❌ **Visual tests** - Not needed (no UI)
+7. ❌ **Contract tests** - Not needed yet (no external APIs)
+8. ❌ **Mutation tests** - Nice to have (not MVP)
+
+---
+
+## The Test Pyramid (Applied to JettyPod)
+
+```
+                 /\
+                /  \
+               / E2E \          10% - Full CLI workflows
+              /-------\         (~10 tests)
+             /  BDD    \        30% - Feature scenarios
+            /-----------\       (~30 scenarios)
+           /    Unit     \      60% - Function/module tests
+          /_______________\     (~100+ tests)
+```
+
+### Why This Ratio?
+
+**Unit tests (60%):**
+- Test pure functions in lib/
+- Fast (milliseconds)
+- Reliable (no dependencies)
+- Easy to debug
+- Cheap to maintain
+
+**Integration/BDD tests (30%):**
+- Test modules working together
+- Medium speed (seconds)
+- Some setup required
+- Test user workflows
+- Living documentation
+
+**E2E tests (10%):**
+- Test complete system
+- Slow (minutes)
+- Brittle (environment-dependent)
+- High maintenance
+- Catch integration gaps
+
+---
+
+## Test Type 1: Unit Tests (Jest)
+
+### What to Unit Test
+
+**Everything in lib/ directory:**
+```
+lib/
+  ├── merge-lock.js          → merge-lock.test.js
+  ├── validators.js          → validators.test.js
+  ├── database.js            → database.test.js
+  ├── git-helpers.js         → git-helpers.test.js
+  ├── decisions-helpers.js   → decisions-helpers.test.js
+  └── current-work.js        → current-work.test.js
+```
+
+**What makes a good unit test:**
+- Tests ONE function/method
+- No external dependencies (or mocked)
+- Fast (< 100ms per test)
+- Deterministic (same input = same output)
+- Independent (can run in any order)
+
+### Example: Comprehensive Unit Test
+
+```javascript
+// lib/validators.test.js
+const { validateWorkItemTitle, validateMode, validateStatus } = require('./validators');
+
+describe('validateWorkItemTitle', () => {
+  describe('valid titles', () => {
+    it('accepts standard title', () => {
+      expect(validateWorkItemTitle('Add login feature')).toBe(true);
+    });
+
+    it('accepts title with numbers', () => {
+      expect(validateWorkItemTitle('Fix bug #123')).toBe(true);
+    });
+
+    it('accepts title with special characters', () => {
+      expect(validateWorkItemTitle('Add @mentions support')).toBe(true);
+    });
+
+    it('accepts minimum length title', () => {
+      expect(validateWorkItemTitle('Fix')).toBe(true);
+    });
+  });
+
+  describe('invalid titles', () => {
+    it('rejects null', () => {
+      expect(validateWorkItemTitle(null)).toBe(false);
+    });
+
+    it('rejects undefined', () => {
+      expect(validateWorkItemTitle(undefined)).toBe(false);
+    });
+
+    it('rejects empty string', () => {
+      expect(validateWorkItemTitle('')).toBe(false);
+    });
+
+    it('rejects whitespace only', () => {
+      expect(validateWorkItemTitle('   ')).toBe(false);
+    });
+
+    it('rejects too long title', () => {
+      const longTitle = 'a'.repeat(501);
+      expect(validateWorkItemTitle(longTitle)).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles title at max length', () => {
+      const maxTitle = 'a'.repeat(500);
+      expect(validateWorkItemTitle(maxTitle)).toBe(true);
+    });
+
+    it('trims whitespace before validation', () => {
+      expect(validateWorkItemTitle('  Valid title  ')).toBe(true);
+    });
+
+    it('handles unicode characters', () => {
+      expect(validateWorkItemTitle('Add 日本語 support')).toBe(true);
+    });
+  });
+});
+
+describe('validateMode', () => {
+  it('accepts speed mode', () => {
+    expect(validateMode('speed')).toBe(true);
+  });
+
+  it('accepts stable mode', () => {
+    expect(validateMode('stable')).toBe(true);
+  });
+
+  it('accepts production mode', () => {
+    expect(validateMode('production')).toBe(true);
+  });
+
+  it('rejects invalid mode', () => {
+    expect(validateMode('fast')).toBe(false);
+  });
+
+  it('rejects null', () => {
+    expect(validateMode(null)).toBe(false);
+  });
+
+  it('is case sensitive', () => {
+    expect(validateMode('Speed')).toBe(false);
+  });
+});
+```
+
+### Unit Test Best Practices
+
+**1. Use descriptive test names:**
+```javascript
+// ❌ Bad
+it('works', () => { ... });
+
+// ✅ Good
+it('returns false when title exceeds 500 characters', () => { ... });
+```
+
+**2. Arrange-Act-Assert pattern:**
+```javascript
+it('calculates queue position correctly', () => {
+  // Arrange
+  const queue = [
+    { id: 1, timestamp: 100 },
+    { id: 2, timestamp: 200 },
+    { id: 3, timestamp: 300 }
+  ];
+
+  // Act
+  const position = getQueuePosition(queue, 2);
+
+  // Assert
+  expect(position).toBe(1); // 0-indexed
+});
+```
+
+**3. One assertion per test (when possible):**
+```javascript
+// ❌ Too many concerns
+it('validates and sanitizes input', () => {
+  expect(validate(input)).toBe(true);
+  expect(sanitize(input)).toBe(cleaned);
+  expect(process(cleaned)).toBe(result);
+});
+
+// ✅ Separate concerns
+it('validates input', () => {
+  expect(validate(input)).toBe(true);
+});
+
+it('sanitizes input', () => {
+  expect(sanitize(input)).toBe(cleaned);
+});
+
+it('processes sanitized input', () => {
+  expect(process(cleaned)).toBe(result);
+});
+```
+
+**4. Test error conditions:**
+```javascript
+describe('error handling', () => {
+  it('throws when database is locked', () => {
+    mockDb.isLocked = true;
+    expect(() => acquireLock()).toThrow('Database is locked');
+  });
+
+  it('throws with helpful message when file not found', () => {
+    expect(() => readConfig('/nonexistent')).toThrow(/Config file not found/);
+  });
+});
+```
+
+**5. Mock external dependencies:**
+```javascript
+// ❌ Bad - depends on real file system
+it('reads config file', () => {
+  const config = readConfig('.jettypod/config.json');
+  expect(config).toBeDefined();
+});
+
+// ✅ Good - mocked file system
+jest.mock('fs');
+it('reads config file', () => {
+  fs.readFileSync.mockReturnValue('{"key": "value"}');
+  const config = readConfig('.jettypod/config.json');
+  expect(config.key).toBe('value');
+});
+```
+
+### When to Write Unit Tests
+
+**In workflow:**
+- **Stable mode**: When adding error handling logic
+- **Standalone chores**: When implementing utility functions
+- **Refactoring**: Before changing implementation
+
+**What to unit test:**
+- ✅ Pure functions (no side effects)
+- ✅ Business logic
+- ✅ Validation functions
+- ✅ Utility functions
+- ✅ Error handling paths
+- ✅ Edge cases and boundary conditions
+
+**What NOT to unit test:**
+- ❌ External libraries (trust they're tested)
+- ❌ Configuration files (use schema validation)
+- ❌ Generated code
+- ❌ Trivial getters/setters
+
+---
+
+## Test Type 2: Integration Tests (BDD/Cucumber)
+
+### What to Integration Test
+
+**User workflows that span multiple modules:**
+- Work item lifecycle (create → start → complete)
+- Git integration (hooks, branches, worktrees)
+- Feature workflow (planning → speed → stable → production)
+- Database operations with business logic
+
+### Integration vs Unit Tests
+
+| Unit Test | Integration Test |
+|-----------|------------------|
+| Single function | Multiple modules |
+| Mocked dependencies | Real dependencies |
+| Milliseconds | Seconds |
+| Testing implementation | Testing behavior |
+| Easy to debug | Harder to debug |
+
+### Example: Integration Test (BDD)
+
+```gherkin
+# features/work-lifecycle.feature
+
+Feature: Work Item Lifecycle
+  Test complete workflow from creation to completion
+
+Background:
+  Given I have initialized jettypod with git
+  And I am on the main branch
+
+Scenario: Create and complete a chore
+  When I create a chore "Fix merge lock bug"
+  Then a work item should exist with title "Fix merge lock bug"
+  And the work item status should be "todo"
+
+  When I start work on the chore
+  Then a git worktree should be created
+  And the work item status should be "in_progress"
+  And current work should be set to the chore
+
+  When I make a commit with message "Fix bug"
+  Then the work item status should be "in_progress"
+
+  When I merge the branch to main
+  Then the work item status should be "done"
+  And the worktree should be cleaned up
+  And current work should be cleared
+
+Scenario: Multiple chores in sequence
+  Given I have a feature "User Authentication"
+  When I create a chore "Implement login" under the feature
+  And I create a chore "Add password reset" under the feature
+  Then both chores should have mode "speed"
+
+  When I start work on "Implement login"
+  And I complete the chore
+  Then I can start work on "Add password reset"
+  And the first chore should remain done
+```
+
+### Integration Test Step Definitions
+
+```javascript
+// features/step_definitions/work-lifecycle.steps.js
+
+const { Given, When, Then } = require('@cucumber/cucumber');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getDb } = require('../../lib/database');
+
+// Setup and cleanup using test safety patterns
+const { Before, After } = require('@cucumber/cucumber');
+
+Before(function() {
+  // Track created items for cleanup
+  this.createdFiles = [];
+  this.createdDirs = [];
+  this.testWorkItems = [];
+
+  // Create isolated test environment
+  this.testDir = path.join(process.cwd(), '.test-temp', `test-${Date.now()}`);
+  fs.mkdirSync(this.testDir, { recursive: true });
+  this.createdDirs.push(this.testDir);
+
+  // Initialize test database
+  this.testDb = path.join(this.testDir, 'work.db');
+  process.env.JETTYPOD_DB = this.testDb;
+});
+
+After(function() {
+  // Cleanup test environment
+  if (this.testDir && fs.existsSync(this.testDir)) {
+    try {
+      fs.rmSync(this.testDir, { recursive: true, force: true });
+    } catch (e) {
+      console.error('Cleanup failed:', e);
+    }
+  }
+
+  // Close database connections
+  const db = getDb();
+  if (db) {
+    db.close();
+  }
+});
+
+// Step implementations
+When('I create a chore {string}', function(title) {
+  const { create } = require('../../features/work-tracking');
+  const result = create('chore', title);
+
+  this.lastWorkItemId = result.id;
+  this.testWorkItems.push(result.id);
+});
+
+Then('a work item should exist with title {string}', function(expectedTitle) {
+  const db = getDb();
+  const item = db.prepare('SELECT * FROM work_items WHERE id = ?').get(this.lastWorkItemId);
+
+  expect(item).toBeDefined();
+  expect(item.title).toBe(expectedTitle);
+});
+
+When('I start work on the chore', function() {
+  const { startWork } = require('../../features/work-tracking');
+  startWork(this.lastWorkItemId);
+});
+
+Then('a git worktree should be created', function() {
+  const worktrees = execSync('git worktree list', { encoding: 'utf-8' });
+  const workItemBranch = `feature/work-${this.lastWorkItemId}`;
+
+  expect(worktrees).toContain(workItemBranch);
+});
+```
+
+### Integration Test Best Practices
+
+**1. Test realistic workflows:**
+```gherkin
+# ✅ Good - realistic user workflow
+Scenario: Developer completes a feature
+  Given I have a feature "Login" with 3 chores
+  When I complete all chores in speed mode
+  Then the feature should auto-elevate to stable mode
+  And stable mode chores should be auto-generated
+
+# ❌ Bad - testing internals
+Scenario: Database query returns correct result
+  When I execute SQL "SELECT * FROM work_items"
+  Then the result should have correct columns
+```
+
+**2. Use Background for common setup:**
+```gherkin
+Background:
+  Given I have initialized jettypod with git
+  And I am on the main branch
+  And no work is currently in progress
+```
+
+**3. Tag scenarios for selective running:**
+```gherkin
+@wip
+Scenario: Feature under development
+  ...
+
+@slow
+Scenario: Complex workflow with many steps
+  ...
+
+@production
+Scenario: Security hardening validation
+  ...
+```
+
+**4. Keep scenarios independent:**
+```gherkin
+# ❌ Bad - depends on previous scenario
+Scenario: Create feature
+  When I create feature "Login"
+
+Scenario: Add chore to feature
+  When I add chore to "Login"  # Assumes Login exists
+
+# ✅ Good - independent
+Scenario: Add chore to feature
+  Given I have a feature "Login"
+  When I add chore to the feature
+```
+
+---
+
+## Test Type 3: End-to-End Tests
+
+### What Makes E2E Different
+
+**Integration tests:**
+- Test modules working together
+- May use test doubles/mocks
+- Run in test environment
+- Focus on specific workflows
+
+**E2E tests:**
+- Test ENTIRE system as user sees it
+- NO mocks (real everything)
+- Production-like environment
+- Test critical paths only
+
+### E2E Test Strategy for JettyPod
+
+**Critical paths to E2E test:**
+1. First-time user initialization
+2. Feature planning → implementation → completion
+3. Git hook integration (real git commits)
+4. Worktree creation and cleanup
+5. Database migration/initialization
+
+### Example: E2E Test
+
+```javascript
+// test/e2e/complete-workflow.e2e.test.js
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+describe('E2E: Complete Feature Workflow', () => {
+  let testDir;
+  let originalCwd;
+
+  beforeEach(() => {
+    // Create completely isolated environment
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jettypod-e2e-'));
+    originalCwd = process.cwd();
+    process.chdir(testDir);
+
+    // Initialize real git repo
+    execSync('git init');
+    execSync('git config user.email "test@example.com"');
+    execSync('git config user.name "Test User"');
+
+    // Create initial commit (git requires one)
+    fs.writeFileSync('README.md', '# Test Project');
+    execSync('git add .');
+    execSync('git commit -m "Initial commit"');
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test('Complete feature workflow from init to done', () => {
+    // 1. Initialize jettypod
+    const initOutput = execSync('node /path/to/jettypod.js init', {
+      encoding: 'utf-8'
+    });
+    expect(initOutput).toContain('JettyPod initialized');
+    expect(fs.existsSync('.jettypod/work.db')).toBe(true);
+
+    // 2. Create feature
+    const createOutput = execSync(
+      'node /path/to/jettypod.js work create feature "User Login"',
+      { encoding: 'utf-8' }
+    );
+    expect(createOutput).toContain('Created feature');
+    const featureId = parseInt(createOutput.match(/ID: (\d+)/)[1]);
+
+    // 3. Start feature planning (manual for E2E)
+    execSync(`node /path/to/jettypod.js work start ${featureId}`);
+
+    // Create BDD scenario manually (simulating skill output)
+    fs.mkdirSync('features', { recursive: true });
+    fs.writeFileSync('features/user-login.feature', `
+Feature: User Login
+  Scenario: User logs in successfully
+    Given I am on the login page
+    When I enter valid credentials
+    Then I am redirected to dashboard
+    `);
+
+    // 4. Transition to implementation
+    execSync(
+      `node /path/to/jettypod.js work implement ${featureId} --winner="Simple form"`,
+      { encoding: 'utf-8' }
+    );
+
+    // 5. Create and complete speed mode chore
+    const choreOutput = execSync(
+      `node /path/to/jettypod.js work create chore "Implement login form" --parent=${featureId}`,
+      { encoding: 'utf-8' }
+    );
+    const choreId = parseInt(choreOutput.match(/ID: (\d+)/)[1]);
+
+    execSync(`node /path/to/jettypod.js work start ${choreId}`);
+
+    // Check worktree was created
+    const worktrees = execSync('git worktree list', { encoding: 'utf-8' });
+    expect(worktrees).toContain(`work-${choreId}`);
+
+    // Make commit (should trigger post-commit hook)
+    fs.writeFileSync('login.js', 'module.exports = function login() {}');
+    execSync('git add .');
+    execSync('git commit -m "Implement login"');
+
+    // 6. Merge to main (should trigger post-merge hook)
+    execSync('git checkout main');
+    execSync(`git merge feature/work-${choreId}-implement-login-form`);
+
+    // Check work item marked as done
+    const statusOutput = execSync(
+      `node /path/to/jettypod.js work show ${choreId}`,
+      { encoding: 'utf-8' }
+    );
+    expect(statusOutput).toContain('Status: done');
+
+    // Check worktree cleaned up
+    const finalWorktrees = execSync('git worktree list', { encoding: 'utf-8' });
+    expect(finalWorktrees).not.toContain(`work-${choreId}`);
+
+  }, 30000); // 30 second timeout for E2E
+
+  test('Git hooks work correctly', () => {
+    execSync('node /path/to/jettypod.js init');
+
+    const choreId = parseInt(
+      execSync('node /path/to/jettypod.js work create chore "Test hooks"', {
+        encoding: 'utf-8'
+      }).match(/ID: (\d+)/)[1]
+    );
+
+    execSync(`node /path/to/jettypod.js work start ${choreId}`);
+
+    // Check initial status
+    let status = execSync(`node /path/to/jettypod.js work show ${choreId}`, {
+      encoding: 'utf-8'
+    });
+    expect(status).toContain('Status: todo');
+
+    // Make first commit - should trigger post-commit hook
+    fs.writeFileSync('test.js', 'console.log("test")');
+    execSync('git add .');
+    execSync('git commit -m "Test commit"');
+
+    // Check status updated to in_progress
+    status = execSync(`node /path/to/jettypod.js work show ${choreId}`, {
+      encoding: 'utf-8'
+    });
+    expect(status).toContain('Status: in_progress');
+
+    // Merge to main - should trigger post-merge hook
+    execSync('git checkout main');
+    execSync(`git merge feature/work-${choreId}-test-hooks`);
+
+    // Check status updated to done
+    status = execSync(`node /path/to/jettypod.js work show ${choreId}`, {
+      encoding: 'utf-8'
+    });
+    expect(status).toContain('Status: done');
+  }, 30000);
+});
+```
+
+### E2E Test Best Practices
+
+**1. Only test critical paths:**
+- Don't duplicate integration test coverage
+- Focus on "user can accomplish their goal"
+- Test with real data, real environment
+
+**2. Make tests resilient:**
+```javascript
+// ❌ Brittle - depends on exact output format
+expect(output).toBe('Created feature #1: User Login');
+
+// ✅ Resilient - checks essential information
+expect(output).toContain('Created feature');
+expect(output).toMatch(/ID: \d+/);
+expect(output).toContain('User Login');
+```
+
+**3. Clean up properly:**
+```javascript
+afterEach(() => {
+  // Always clean up, even if test failed
+  try {
+    process.chdir(originalCwd);
+    fs.rmSync(testDir, { recursive: true, force: true });
+  } catch (e) {
+    console.error('E2E cleanup failed:', e);
+  }
+});
+```
+
+**4. Use longer timeouts:**
+```javascript
+test('complete workflow', () => {
+  // E2E tests are slower
+}, 30000); // 30 seconds
+```
+
+---
+
+## Test Type 4: Performance Tests
+
+### What to Performance Test
+
+**For JettyPod (CLI tool):**
+- Command execution time
+- Database query performance
+- File operations (especially with many worktrees)
+- Git operations
+
+### Performance Testing Strategy
+
+```javascript
+// test/performance/commands.perf.test.js
+
+describe('Performance: Command Execution', () => {
+  test('work create should complete in under 100ms', () => {
+    const start = Date.now();
+
+    execSync('node jettypod.js work create chore "Test"');
+
+    const duration = Date.now() - start;
+    expect(duration).toBeLessThan(100);
+  });
+
+  test('backlog command scales with many work items', () => {
+    // Create 1000 work items
+    for (let i = 0; i < 1000; i++) {
+      execSync(`node jettypod.js work create chore "Item ${i}"`);
+    }
+
+    const start = Date.now();
+    execSync('node jettypod.js backlog');
+    const duration = Date.now() - start;
+
+    // Should still be under 500ms with 1000 items
+    expect(duration).toBeLessThan(500);
+  });
+});
+```
+
+### Performance Test with BDD
+
+```gherkin
+# features/performance.feature
+
+@performance
+Feature: Performance Requirements
+  Ensure commands execute within acceptable time limits
+
+Scenario: Work item creation is fast
+  Given I have 100 existing work items
+  When I create a new work item
+  Then it should complete in under 100ms
+
+Scenario: Backlog scales with large datasets
+  Given I have 1000 work items
+  When I run the backlog command
+  Then it should complete in under 500ms
+  And it should return all items
+
+Scenario: Git operations don't block
+  Given I have 50 worktrees
+  When I create a new worktree
+  Then it should complete in under 2 seconds
+```
+
+```javascript
+// features/step_definitions/performance.steps.js
+
+When('I create a new work item', function() {
+  this.startTime = Date.now();
+  execSync('node jettypod.js work create chore "Test"');
+  this.duration = Date.now() - this.startTime;
+});
+
+Then('it should complete in under {int}ms', function(maxMs) {
+  expect(this.duration).toBeLessThan(maxMs);
+});
+```
+
+---
+
+## Test Type 5: Security Tests
+
+### What to Security Test
+
+**For JettyPod:**
+- SQL injection in database queries
+- Command injection in git operations
+- Path traversal in file operations
+- Input validation
+
+### Security Testing Examples
+
+```javascript
+// test/security/injection.test.js
+
+describe('Security: SQL Injection Prevention', () => {
+  test('prevents SQL injection in work item title', () => {
+    const maliciousTitle = "'; DROP TABLE work_items; --";
+
+    const { create } = require('../../features/work-tracking');
+    const result = create('chore', maliciousTitle);
+
+    // Should escape SQL properly
+    expect(result.id).toBeDefined();
+
+    // Table should still exist
+    const db = getDb();
+    const items = db.prepare('SELECT * FROM work_items').all();
+    expect(items).toBeDefined();
+  });
+
+  test('prevents SQL injection in search', () => {
+    const maliciousSearch = "' OR '1'='1";
+
+    const { search } = require('../../features/work-tracking');
+    const results = search(maliciousSearch);
+
+    // Should not return all items
+    expect(results.length).toBe(0);
+  });
+});
+
+describe('Security: Command Injection Prevention', () => {
+  test('prevents command injection in git operations', () => {
+    const maliciousMessage = 'commit"; rm -rf /; echo "';
+
+    expect(() => {
+      execSync(`git commit -m "${maliciousMessage}"`);
+    }).not.toThrow();
+
+    // System should still be intact
+    expect(fs.existsSync('.')).toBe(true);
+  });
+});
+
+describe('Security: Path Traversal Prevention', () => {
+  test('prevents path traversal in file operations', () => {
+    const maliciousPath = '../../../../etc/passwd';
+
+    const { readConfig } = require('../../lib/config');
+
+    expect(() => {
+      readConfig(maliciousPath);
+    }).toThrow(/Invalid path/);
+  });
+});
+```
+
+---
+
+## Test Coverage Strategy
+
+### Coverage Goals
+
+```javascript
+// jest.config.js
+module.exports = {
+  collectCoverageFrom: [
+    'lib/**/*.js',
+    'features/**/*.js',
+    '!**/*.test.js',
+    '!**/node_modules/**',
+    '!**/__tests__/**'
+  ],
+  coverageThresholds: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    },
+    // Stricter for core library code
+    'lib/**/*.js': {
+      branches: 90,
+      functions: 90,
+      lines: 90,
+      statements: 90
+    }
+  },
+  coverageReporters: ['text', 'text-summary', 'html', 'lcov']
+};
+```
+
+### What Coverage Numbers Mean
+
+**Lines covered: 80%** = 80% of code lines executed during tests
+**Branches covered: 80%** = 80% of if/else paths tested
+**Functions covered: 80%** = 80% of functions called
+**Statements covered: 80%** = 80% of statements executed
+
+**100% coverage ≠ bug-free code**
+- Coverage measures execution, not correctness
+- Can have 100% coverage with bad assertions
+- Focus on meaningful tests, not coverage %
+
+---
+
+## Complete Testing Checklist
+
+### Feature Workflow Testing
+
+**Feature-Planning:**
+- [ ] Dry-run BDD scenarios (syntax validation)
+- [ ] Step definitions match scenario steps
+- [ ] Test safety hooks in place
+
+**Speed-Mode:**
+- [ ] Happy path BDD scenario passes
+- [ ] Basic unit tests for new functions
+- [ ] No regressions in existing tests
+
+**Stable-Mode:**
+- [ ] All BDD scenarios pass (happy + error + edge)
+- [ ] Unit tests for error handling logic
+- [ ] Integration tests for module interactions
+- [ ] Test coverage >= 80% for new code
+
+**Production-Mode:**
+- [ ] Production BDD scenarios pass
+- [ ] Security tests for vulnerabilities
+- [ ] Performance tests meet targets
+- [ ] No regressions in full test suite
+
+### Standalone Chore Testing
+
+- [ ] Unit tests for new functionality
+- [ ] Integration tests if touching multiple modules
+- [ ] No regressions in existing tests
+- [ ] Test coverage >= 80% for changes
+
+---
+
+## Summary: Realistic Testing Strategy
+
+### What You Actually Need
+
+**Priority 1 (Must Have):**
+1. ✅ Unit tests for lib/ code (60% of tests)
+2. ✅ BDD integration tests for workflows (30% of tests)
+3. ✅ Test safety infrastructure (cleanup hooks)
+4. ✅ Pre-commit/pre-push git hooks
+
+**Priority 2 (Should Have):**
+5. ✅ E2E tests for critical paths (10% of tests)
+6. ✅ Basic performance tests (timing checks)
+7. ✅ Test coverage tracking (80% threshold)
+
+**Priority 3 (Nice to Have):**
+8. ⚠️ Security tests (injection prevention)
+9. ⚠️ Mutation testing (test quality)
+
+**Not Needed (For Your Project):**
+- ❌ Visual regression tests (no UI)
+- ❌ Contract tests (no external APIs yet)
+- ❌ Load tests (single-user CLI)
+- ❌ Accessibility tests (no UI)
+
+### The Honest Truth
+
+You don't need ALL testing best practices. You need:
+- **Fast unit tests** that give immediate feedback
+- **Reliable integration tests** that catch workflow bugs
+- **Selective E2E tests** for critical paths
+- **Smart git hooks** that don't kill velocity
+
+The previous document (TDD-INFRASTRUCTURE-STRATEGY.md) had the git hooks and timing strategy right. This document fills in the gaps on WHAT to test and HOW to test it properly.
+
+**Together they form a complete strategy.**