jettypod 4.3.0 → 4.4.1

package/skills-templates/stable-mode/SKILL.md

@@ -5,14 +5,18 @@ description: Guide implementation of stable mode chores with comprehensive testi
 
 # Stable Mode Skill
 
-**Mode Progression:**
-Feature Planning → Speed Mode → **[STABLE MODE]** → Done (Internal) OR Production Mode (External)
-
-**You are here:** Adding error handling, validation, and edge cases to speed mode implementation.
-
-**Next steps:**
-- INTERNAL projects: Feature complete after stable mode (no production mode needed)
-- EXTERNAL projects: Continue to production mode for security/scale/monitoring
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Mode Progression Flow                                               │
+│                                                                      │
+│  Feature Planning → Speed Mode → [STABLE MODE] → Production Mode     │
+│                                   ▲▲▲▲▲▲▲▲▲▲▲▲▲                      │
+│                                   YOU ARE HERE                       │
+│                                                                      │
+│  Next: After stable mode implementation, feature can be marked       │
+│        complete, or elevated to production mode if needed.           │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
 Guides Claude Code through stable mode implementation with comprehensive testing focus. Users confirm approach but Claude Code writes the code.
 
@@ -20,33 +24,13 @@ Guides Claude Code through stable mode implementation with comprehensive testing
 
 When this skill is activated, you are helping implement a stable mode chore to add comprehensive testing and error handling. Follow this structured approach:
 
-## 🔑 Critical Context
-
-**You are working in an isolated git worktree:**
-- `work start [chore-id]` created a dedicated worktree for this chore
-- All file operations must use **absolute paths** from the worktree (not relative paths)
-- The worktree has its own branch - changes are isolated from main
-- BDD tests and unit tests run in the worktree context
-
-**Worktree path is available in Step 0 output** - use it for all file operations.
-
----
-
 ### Overview
 
-**Stable Mode Goal:** Transform speed mode's "make it work" implementation into robust, reliable code with comprehensive error handling and validation.
+**Stable Mode Goal:** Transform speed mode's "prove it works" implementation into production-ready code with comprehensive robustness.
 
 **CRITICAL DISTINCTION:**
-- **Speed mode implemented ALL functionality** - every feature/function is already working (all success scenarios)
-- **Stable mode adds COMPLETE robustness** - error handling, validation, and edge cases
-
-**Key Principles:**
-- **Build on speed implementation** - do not re-implement features, ADD robustness to them
-- **Autonomous execution** - Claude Code writes code, user confirms approach
-- **Quality focus** - code should be stable, maintainable, and reliable (ready for internal use)
-
-<details>
-<summary><strong>📋 What Stable Mode Includes (click to expand)</strong></summary>
+- **Speed mode implemented ALL functionality** - every feature/function is already working on the happy path
+- **Stable mode adds COMPLETE robustness** - NOT just error handling, but comprehensive production readiness
 
 **Stable Mode is NOT just error handling. It includes:**
 
@@ -77,72 +61,34 @@ When this skill is activated, you are helping implement a stable mode chore to a
    - Handle interrupted operations
 
 5. **All BDD Scenarios Pass**
-   - Success scenarios (already passing from speed mode - required + optional features)
+   - Happy path (already passing from speed mode)
    - Error scenarios (how does it handle failures?)
    - Edge case scenarios (boundary conditions, unusual inputs)
    - Concurrent access scenarios (multiple instances)
 
-</details>
+**Key Principles:**
+- **Build on speed implementation** - do not re-implement features, ADD robustness to them
+- **Autonomous execution** - Claude Code writes code, user confirms approach
+- **Quality focus** - code should be stable, maintainable, and production-ready
 
 **User Profile:** May not know how to code - Claude Code does the implementation autonomously.
 
 ---
 
-## 🧪 Unit Testing in Stable Mode - True TDD
-
-**Unit tests are written DURING implementation, not after.**
-
-**The TDD workflow (each iteration):**
-1. **Identify next failing BDD step** - Which error/edge case scenario step needs to pass?
-2. **Write unit test for the validation/error handling** - Test the specific error condition
-3. **Watch unit test fail (RED)** - Confirm test catches the missing validation
-4. **Write minimal code** - Add error handling, validation, or edge case handling
-5. **Run unit test (GREEN)** - Verify the validation/error handling works in isolation
-6. **Run BDD scenarios** - Check if this makes any error/edge case BDD steps pass
-7. **Next iteration** - Repeat for next failing step
-
-**What to unit test in stable mode:**
-- Validation functions (null checks, type checks, range validation)
-- Error handling logic (catch blocks, error recovery)
-- Edge case handling (empty arrays, boundary values)
-- State consistency (transaction rollback, cleanup on failure)
-
-**Unit test scope in stable mode:**
-```javascript
-// ✅ Stable mode unit tests (error paths and edge cases)
-test('createUser throws ValidationError for null email', () => {
-  expect(() => createUser('John', null)).toThrow(ValidationError);
-  expect(() => createUser('John', null)).toThrow('Email is required');
-});
-
-test('createUser handles empty string email', () => {
-  expect(() => createUser('John', '')).toThrow(ValidationError);
-});
-
-test('getUserById returns null for non-existent user', () => {
-  const user = getUserById(99999);
-  expect(user).toBeNull();
-});
-```
-
----
-
 ## Quick Reference: Async Boundaries
 
 **Where Claude Code MUST wait for user confirmation:**
 
-| Phase | Location | Why | Condition |
-|-------|----------|-----|-----------|
-| Step 3A | Before implementing (conditional) | User confirms implementation approach | Only if approach is ambiguous or multiple valid paths |
+| Phase | Location | Why |
+|-------|----------|-----|
+| Step 3 Phase 1 | Before implementing | User confirms implementation approach |
 
 **Where Claude Code executes autonomously:**
-- Step 0: Initialize context
+- Step 0: Create additional scenarios (if first stable chore)
 - Step 1: Scenario analysis
 - Step 2: Speed mode implementation review
-- Step 3: Decision to skip/ask for confirmation
-- Step 4: Establish RED baseline
-- Step 5: RED→GREEN→REFACTOR loop (true TDD)
-- Step 6: Check progress and route to next chore or completion
+- Step 3 Phase 2: Autonomous execution loop
+- Step 4: Completion check and routing
 
 ---
 
@@ -159,7 +105,7 @@ For external products accepting real users, stable mode is NOT the final step. P
 **Required workflow for EXTERNAL products after stable mode implementation:**
 
 1. ✅ **Complete ALL stable mode chores** - Add error handling and edge cases
-2. ✅ **Set feature to production mode** - Use `jettypod work set-mode <feature-id> production`
+2. ✅ **Generate production mode chores** - Use `jettypod work elevate <feature-id> production`
 3. ✅ **Implement production mode chores** - Add performance, security, monitoring
 4. ❌ **NEVER mark feature complete in stable mode for external products** - This bypasses critical production hardening
 
@@ -168,8 +114,8 @@ For external products accepting real users, stable mode is NOT the final step. P
 **If you attempt to mark an external product feature complete while in stable mode, the system will block you with an error.**
 
 The validation will require you to either:
-- Set feature to production mode: `jettypod work set-mode <feature-id> production`
-- Or explicitly force skip (not recommended): `jettypod work set-mode <feature-id> production --force`
+- Generate production mode chores: `jettypod work elevate <feature-id> production`
+- Or explicitly skip (not recommended): `jettypod work set-mode <feature-id> production --force`
 
 **Remember:** Stable mode makes it robust. Production mode makes it ready for real users at scale.
 
@@ -177,34 +123,48 @@ The validation will require you to either:
 
 ## Implementation Steps
 
-### Step 0: Initialize Stable Mode Context
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 1: AUTONOMOUS SETUP
+     No user input required - Claude Code executes independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
 
-**You are now in stable mode,** implementing a chore to add error handling and edge case coverage.
+### Step 0: Create Additional Scenarios (If First Stable Chore)
 
-**Get the current work context:**
+**CRITICAL:** If this is the FIRST stable mode chore for this feature, you must ADD edge case scenarios and step definitions.
 
-```bash
-sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.parent_id, parent.title as parent_title, parent.scenario_file, wt.worktree_path, wt.branch_name FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id LEFT JOIN worktrees wt ON wi.id = wt.work_item_id WHERE wi.status = 'in_progress' AND wi.type = 'chore'"
-```
+**Check if scenarios exist beyond happy path:**
+1. Read the feature's `.feature` file
+2. Count scenarios - if only 1 (happy path), ADD edge case scenarios
+3. Update step definitions to include new scenarios
 
-**Display to user:**
+**Add to `.feature` file:**
+```gherkin
+# Error handling scenario
+Scenario: [Error case title]
+  Given [setup for error condition]
+  When [action that triggers error]
+  Then [expected error handling]
+  And [system remains stable]
 
+# Edge case scenario
+Scenario: [Edge case title]
+  Given [edge condition setup]
+  When [action at boundary]
+  Then [expected edge case behavior]
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🛡️  STABLE MODE: Implementing Chore #[id]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Chore: [title]
-Feature: #[parent-id] [parent-title]
-Worktree: [worktree_path]
-Branch: [branch_name]
-
-Analyzing stable mode BDD scenarios to determine what error handling and validation to add...
-```
+**Add to `features/step_definitions/[feature-slug].steps.js`:**
+- Implement Given/When/Then steps for new scenarios
+- Follow existing patterns from happy path steps
+- Include proper error assertions
 
-**Then proceed to Step 1.**
+**Update unit tests with edge cases:**
+- Speed mode generated basic unit tests with TODO placeholders
+- Stable mode should fill in edge case tests for error handling
+- Add tests for: null/undefined inputs, invalid data, boundary conditions
+- Use existing test files at `test/[path]/[file].test.js`
 
----
+**IMPORTANT:** Only do this ONCE per feature (first stable chore). Subsequent stable chores implement existing scenarios.
 
 ### Step 1: Analyze Scenario to Implement
 
@@ -212,18 +172,21 @@ Analyzing stable mode BDD scenarios to determine what error handling and validat
 
 **Your task:**
 1. Get current work item and parent feature's scenario file
-2. Read the full scenario file (should have success scenarios + stable mode error/edge case scenarios)
+2. Read the full scenario file (should now have happy path + edge cases)
 3. Identify which scenario this chore addresses
 4. Extract requirements from the scenario's Given/When/Then steps
-5. Check chore description for breadcrumbs (implementation guidance from feature-planning)
-
-**NOTE:** Scenarios and step definitions already exist, created by the speed-mode skill during transition to stable mode. Chore descriptions may contain breadcrumbs with implementation guidance (files to modify, patterns to follow, functions to add validation to).
 
 **To get scenario information, use these commands:**
 
 ```bash
-# Get current work (chore) and its parent feature with scenario_file
-sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, wi.parent_id, parent.title as parent_title, parent.scenario_file, parent.mode FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
+# Get current work (chore) and its parent feature
+jettypod work current
+
+# Get parent feature details including scenario_file
+jettypod work show <parent-feature-id>
+
+# Or query database directly for scenario file
+sqlite3 .jettypod/work.db "SELECT id, title, scenario_file, mode FROM work_items WHERE id = <parent-feature-id>"
 ```
 
 **Then read the scenario file** using the Read tool on the path returned by `scenario_file`.
@@ -260,12 +223,6 @@ What needs to happen:
 • [When] Action/condition: [requirement]
 • [Then] Expected behavior: [requirement]
 
-[If breadcrumbs exist in chore description:]
-Implementation guidance:
-• Files: [files to modify]
-• Patterns: [patterns to follow]
-• Functions: [specific functions to add validation to]
-
 Now reviewing speed mode implementation...
 ```
 
@@ -309,7 +266,7 @@ Then use the Read tool to examine the implementation files.
 
 Current Implementation:
 • Files: [list]
-• Success scenarios: ✅ Working (from speed mode)
+• Happy path: ✅ Working
 • Error handling: ❌ Missing [specific gaps]
 • Validation: ❌ Missing [specific gaps]
 • Edge cases: ❌ Not handled [specific gaps]
@@ -322,286 +279,392 @@ To pass the target scenario, I need to:
 Now proposing comprehensive implementation...
 ```
 
-### Step 3: Decide if Confirmation Needed
-
-**Evaluate if you need user confirmation before implementing:**
-
-**Skip confirmation (proceed directly to Step 4) if:**
-- Chore description is comprehensive (specific validation/error handling described)
-- Implementation approach is clear and unambiguous
-- Only one reasonable way to add the error handling
-- Similar patterns exist in codebase to follow
-
-**Ask for confirmation (Step 3A) if:**
-- Multiple valid error handling approaches exist
-- Chore description is vague about specific validation
-- Architectural choice impacts other features
-- You're uncertain about the right approach
+**Move to Step 3 automatically.**
 
-### Step 3A: Propose Implementation Approach (Conditional)
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 2: USER CONFIRMATION REQUIRED
+     ⚡ ASYNC BOUNDARY - Must wait for user response before proceeding
+     ═══════════════════════════════════════════════════════════════════════════ -->
 
-**⚡ ASYNC BOUNDARY - Only execute this if confirmation needed**
+### Step 3: Propose and Execute Comprehensive Implementation
 
-**Present your analysis and proposal to the user:**
+**Two phases: Propose (get user confirmation) → Execute (autonomous)**
 
-```
-💡 Implementation Proposal
-
-I see multiple ways to approach this error handling. Here's what I'm thinking:
+#### Phase 1: Propose Comprehensive Implementation
 
-**Option I'm recommending:**
-• Error handling strategy: [specific approach]
-• Validation approach: [what to validate and how]
-• Why: [rationale - why this over alternatives]
-
-**Alternative considered:**
-• [Brief description] - not choosing because [reason]
+**Present your analysis and proposal:**
 
 ```
+💡 Comprehensive Implementation Proposal
 
-**⚡ WAIT for user confirmation or adjustments.**
+Based on scenario and code analysis, here's how I'll add proper error handling and make the scenario pass:
 
-If user adjusts: revise proposal and confirm again before proceeding.
+**Changes needed:**
+1. [File]: Add [specific error handling/validation]
+2. [File]: Add [specific edge case handling]
+3. [File]: Add [specific tests]
 
-**If you skipped this step:** Proceed directly to Step 4.
+**Error handling approach:**
+• [Specific errors to catch and how to handle them]
+• [User-friendly error messages]
+• [Graceful failure behavior]
 
----
+**Validation approach:**
+• [Input validation checks]
+• [Boundary condition handling]
+• [State validation]
 
-### Step 4: Establish RED Baseline
+**Why this approach:**
+[Brief explanation of how this satisfies the scenario with proper quality]
 
-**CRITICAL:** After user confirms (or skips confirmation), execute autonomously - no permission needed for code changes.
-
-Before writing any implementation code, run tests to establish the RED state:
-
-```bash
-# Get current work and parent feature's scenario file
-sqlite3 .jettypod/work.db "SELECT wi.id, wi.parent_id, parent.scenario_file FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
-# This gives you the chore ID, parent feature ID, and path to the .feature file
-
-# Run BDD tests to establish RED baseline
-npx cucumber-js <scenario-file-path> --format progress
+Sound good? I'll implement this autonomously once you confirm.
 ```
 
-Parse the output to identify:
-- Total steps and how many are failing
-- Which specific stable mode steps are failing (error/edge case scenarios)
-- The first error message
+**WAIT for user confirmation or adjustments.**
 
-This establishes your RED baseline - stable mode scenarios should be failing initially.
+If user adjusts: revise proposal and confirm again.
 
-**Display RED baseline:**
-```
-🔴 Establishing RED baseline...
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 3: AUTONOMOUS EXECUTION
+     User has confirmed - Claude Code executes iteration loop independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
 
-RED Baseline: 3 of 11 steps failing (stable mode scenarios)
+#### Phase 2: Autonomous Execution
 
-Failing steps:
-  ✖ Then it should throw a validation error
-  ✖ And the error message should be "Email is required"
-  ✖ When I provide an empty string as input
+**CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
 
-First error:
-  Step: Then it should throw a validation error
-  Error: Error: Expected function to throw but it didn't
+**Execution loop (with iteration limits and error handling):**
 
-🎯 Goal: Make all stable mode scenarios pass
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔄 ITERATION LOOP: Stable Mode Scenario                                │
+     │                                                                         │
+     │ Progress Tracking:                                                      │
+     │ • Display: "Iteration X/10" at start of each cycle                     │
+     │ • Track: scenarios passing, steps passing, newly passing               │
+     │ • Goal: Target scenario + all scenarios pass                           │
+     │                                                                         │
+     │ Return Points:                                                          │
+     │ • CHECKPOINT_ITERATION: Resume at specific iteration number            │
+     │ • CHECKPOINT_SCENARIO: Resume with known scenario status               │
+     │ • If session interrupted, can resume from last known iteration         │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
 
-Now implementing...
+```javascript
+// --- Imports ---
+const {
+  MAX_ITERATIONS, TEST_TIMEOUT, runBddTestWithTimeout,
+  runBddScenarioWithTimeout, getScenarioLineByName,
+  parseTestProgress, extractErrors, findNewlyPassingSteps
+} = require('../../.claude/skills/speed-mode/test-runner');
+
+// --- Find scenario line number ---
+const scenarioLine = getScenarioLineByName(feature.scenario_file, targetScenario.title);
+if (!scenarioLine) {
+  console.error('❌ Cannot find scenario line number for:', targetScenario.title);
+  return;
+}
+
+let iteration = 0;
+let scenarioPasses = false;
+let previousResult = null;
+
+// --- Main iteration loop ---
+// 📊 PROGRESS: Iteration {iteration}/{MAX_ITERATIONS} | Scenario: {scenarioPasses ? 'PASS' : 'FAIL'}
+while (!scenarioPasses && iteration < MAX_ITERATIONS) {
+  iteration++;
+  console.log(`\n🔄 Iteration ${iteration}/${MAX_ITERATIONS}`);
+
+  // --- Make code changes ---
+  try {
+    console.log('✍️  Adding error handling to [file]...');
+    // ... use Edit tool ...
+    console.log('✅ Updated [file]');
+  } catch (editErr) {
+    console.error('❌ Error modifying files:', editErr.message);
+    continue;
+  }
+
+  // --- Run tests ---
+  console.log('🧪 Running tests...');
+  const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine, TEST_TIMEOUT);
+
+  // --- Handle timeout ---
+  if (result.timedOut) {
+    console.error('❌ Tests timed out after 60 seconds');
+    console.log('Suggestion: Check for blocking operations or missing async/await');
+    break;
+  }
+
+  // --- Parse and track progress ---
+  const currentResult = parseTestProgress(result.stdout);
+  const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
+
+  console.log(`\n📊 Progress: ${currentResult.passed}/${currentResult.total} steps passing`);
+
+  if (newlyPassing.length > 0) {
+    console.log(`\n✅ Newly passing:`);
+    newlyPassing.forEach(step => console.log(`  • ${step}`));
+  }
+
+  // --- Check for success ---
+  if (currentResult.passed === currentResult.total && currentResult.total > 0) {
+    console.log('\n✅ Target scenario passing!');
+
+    // --- Run full verification ---
+    console.log('\n🔍 Running full verification (all scenarios)...');
+    const fullResult = await runBddTestWithTimeout(feature.scenario_file, TEST_TIMEOUT);
+
+    if (fullResult.timedOut) {
+      console.log('⚠️  Full verification timed out');
+    } else if (fullResult.exitCode !== 0) {
+      const fullProgress = parseTestProgress(fullResult.stdout + fullResult.stderr);
+      console.log(`⚠️  Regressions found: ${fullProgress.total - fullProgress.passed} scenarios failing`);
+      scenarioPasses = false;
+    } else {
+      console.log('✅ Full verification passed!');
+      scenarioPasses = true;
+    }
+  } else {
+    // --- Display errors ---
+    console.log(`\n❌ ${currentResult.total - currentResult.passed} scenarios still failing`);
+    const errors = extractErrors(result.stdout + result.stderr);
+    if (errors.errors.length > 0) {
+      console.log('\n🔧 Next failure to address:');
+      console.log(`  Step: ${errors.errors[0].step}`);
+      console.log(`  Error: ${errors.errors[0].message}`);
+    }
+  }
+
+  previousResult = currentResult;
+}
+
+// --- Handle max iterations reached ---
+if (!scenarioPasses && iteration >= MAX_ITERATIONS) {
+  console.error('\n❌ Maximum iterations reached without passing scenario');
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('🛑 Unable to make scenario pass automatically');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('\nPossible reasons:');
+  console.log('• Scenario requirements may need clarification');
+  console.log('• Implementation approach may need rethinking');
+  console.log('• External dependencies may be missing');
+  console.log('\nHow would you like to proceed?');
+  console.log('  1. Review changes made so far');
+  console.log('  2. Try a different approach');
+  console.log('  3. Debug manually');
+  return;
+}
+```
+
+**Display progress:**
+```
+🔄 Iteration 1/10
+
+✍️  Adding error handling to [file]...
+✅ Updated [file]
+
+🧪 Running tests...
+✅ Target scenario passes!
+✅ All scenarios still passing!
+```
+
+**Stable mode focus:**
+- **Add to existing implementation** - speed mode already implemented all features
+- **Comprehensive error handling** - wrap existing code with try/catch, handle failures gracefully
+- **Input validation** - add checks before existing logic (null checks, type checks, range validation)
+- **Edge case handling** - handle empty arrays, missing properties, boundary values, concurrent access
+- **Clear error messages** - user-friendly, actionable feedback for all failure modes
+- **All BDD scenarios pass** - happy path (already passing from speed) AND error/edge scenarios
+
+**When all scenarios pass:**
+
+```
+🎉 Stable mode scenario passes!
+
+Implementation complete:
+• Modified: [list files]
+• Error handling: ✅ Comprehensive
+• Validation: ✅ Complete
+• All scenarios: ✅ Passing
+```
+
+**Run unit test coverage (if configured):**
+```bash
+# If project has coverage configured, run it:
+npm run test:coverage
+# Or with Jest:
+npx jest --coverage
 ```
 
----
-
-### Step 5: RED→GREEN→REFACTOR Loop
-
-**Execute autonomously** - iterate until tests pass (max 10 iterations).
-
-**Each iteration (True TDD):**
-
-1. **Identify next failing BDD step** - Which error/edge case scenario step to tackle?
-2. **Write unit test** - Test the validation/error handling needed (watch it fail - RED)
-3. **Write minimal implementation** - Add error handling, validation, or edge case code
-4. **Run unit test** - Verify it passes (GREEN)
-5. **Run BDD scenarios** - Check if BDD step now passes
-6. **Display progress** - Show what's passing, what's next
-7. **Continue or exit** - If all BDD scenarios pass → REFACTOR. Otherwise, repeat.
-
-**Show progress each iteration:**
-```
-━━━ Iteration 3/10 ━━━
-📝 Unit test: test/user.test.js - validates email format
-   RED: Test fails - no validation exists yet
-✍️  Implementation: src/user.js - added email format validation
-   GREEN: Unit test passes
-🧪 Running BDD scenarios...
-📊 Progress: 9/11 BDD steps passing
-✅ Newly passing: Then it should throw a validation error
-🔧 Next failure: And the error message should be user-friendly
-    BDD step: Then the error message should be "Email format is invalid"
-```
+Note: Coverage tracking is project-specific. Check your package.json for the appropriate coverage command.
 
-**When GREEN achieved:**
+**Display coverage summary:**
 ```
-🎉 GREEN: All stable mode scenarios passing!
+📊 Unit Test Coverage Report
+─────────────────────────────
+Statements: ✅ 85.23%
+Branches:   ✅ 82.15%
+Functions:  ✅ 88.50%
+Lines:      ✅ 84.90%
+─────────────────────────────
+✅ All coverage metrics meet 80% threshold
 ```
 
-**Then REFACTOR (quick pass, 5 min max):**
-- Extract duplicated validation logic
-- Rename unclear error variables
-- Simplify complex error handling
-- Remove dead code
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 4: COMPLETION AND ROUTING
+     Conditional phase - route based on project state (internal vs external)
+     ═══════════════════════════════════════════════════════════════════════════ -->
 
-**Re-run tests after refactor** to ensure nothing broke.
+### Step 4: Check for Production Mode (When All Stable Chores Complete)
 
-<details>
-<summary><strong>📋 TDD Loop Guidelines (click to expand)</strong></summary>
+**CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete. Otherwise skip to marking chore as done.**
 
-**Iteration strategy:**
-- Start with first failing stable mode step
-- Make minimal change to pass that step
-- Run tests immediately
-- Move to next failure
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔍 COMPLETION CHECK: Stable Chores                                     │
+     │                                                                         │
+     │ Progress Tracking:                                                      │
+     │ • Query: Count incomplete chores for feature                           │
+     │ • Display: "X chores remaining" or "All complete"                      │
+     │ • Action: Route based on project state (internal vs external)          │
+     │                                                                         │
+     │ Return Point:                                                           │
+     │ • CHECKPOINT_CHORE_COUNT: Known incomplete count from last check       │
+     │ • CHECKPOINT_PROJECT_STATE: Known project state for routing            │
+     │ • If session interrupted, re-query to get current counts               │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
 
-**If stuck after 5 iterations:**
-- Review approach - is there a simpler validation?
-- Check assumptions - are you handling the right error?
-- Break down the change - can you add validation incrementally?
-
-**Max 10 iterations:**
-- If you hit max without GREEN, stop
-- Display final progress and suggest next steps
-- Consider breaking chore into smaller pieces
-
-</details>
-
----
-
-**CRITICAL: Check if ALL stable mode chores are complete. Route to next chore if any remain.**
-
-**Check for incomplete stable chores:**
+**Check completion status and project state:**
 
 ```bash
 # Get current work to find parent feature ID
-sqlite3 .jettypod/work.db "SELECT wi.parent_id FROM work_items wi WHERE wi.status = 'in_progress'"
-
-# Get list of remaining stable chores (excluding current chore)
-sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND mode = 'stable' AND status != 'done' AND id != <current-chore-id> ORDER BY created_at LIMIT 1"
-```
+jettypod work current
 
-**If stable chores remain, display and start next chore:**
+# Count incomplete chores for the feature
+sqlite3 .jettypod/work.db "SELECT COUNT(*) FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND status NOT IN ('done', 'cancelled')"
 
+# Check project state
+sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Stable Mode Chore Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-✅ Error handling and validation scenarios pass for this chore
 
-More stable mode chores remain. Starting next chore:
-#[next-chore-id]: [next-chore-title]
-```
+Based on the results:
+- If incomplete_count > 0: More stable chores remain
+- If incomplete_count = 0 AND project_state = 'internal': Feature is complete
+- If incomplete_count = 0 AND project_state = 'external': Need to generate production chores
 
-**Then immediately merge current chore and start next:**
+**CRITICAL: Check project state to determine next step:**
 
+Check if project is internal or external:
 ```bash
-# Commit changes in the worktree
-git add . && git commit -m "feat: [brief description of error handling added]"
-
-# Merge current chore - this automatically marks it as done
-jettypod work merge
-
-# Start next stable chore
-jettypod work start [next-chore-id]
+# Check project_state in database
+node jettypod.js work show 1 | grep "Project state:"
+# OR read CLAUDE.md <project_state> tag
 ```
 
-**CRITICAL: Use ONLY `jettypod work merge` to complete chores.**
-- ❌ DO NOT use `jettypod work status <id> done`
-- ❌ DO NOT use `jettypod work complete <id>`
-- ❌ DO NOT use `jettypod work set-mode <id> done`
-- ✅ ONLY use `jettypod work merge`
-
-The merge command handles everything: pushes branch, merges to main, marks chore done, cleans up worktree.
-
-The stable-mode skill will automatically re-invoke for the next chore.
-
-**If all stable chores are done (count = 0), continue to Step 6 below.**
-
 ---
 
-### Step 6: Route to Completion (After All Stable Chores Complete)
+### Option A: Project is INTERNAL
 
-**CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete.**
-
-**Check project state:**
+**For internal projects, stable mode is the FINAL state.**
 
-```bash
-# Check project_state in database (RECOMMENDED - always up to date)
-sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
-
-# OR read CLAUDE.md from git root (NOT from CWD - worktrees may have stale copies)
-grep -A1 "<project_state>" "$(git rev-parse --show-toplevel)/CLAUDE.md" | tail -1
-```
-
-⚠️ **CRITICAL:** If reading CLAUDE.md, always read from git root using `$(git rev-parse --show-toplevel)/CLAUDE.md`, NOT from current directory. Worktrees branch from main and may have stale project_state values.
-
-**Route based on project state:**
-
-**If project_state = 'internal':**
-
-Mark the feature as done:
+**ACTION REQUIRED:** Mark the feature as done:
 ```bash
 node jettypod.js work status [feature-id] done
 ```
 
-Display:
+Then display to user:
+
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✅ FEATURE #[id] COMPLETE!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Feature: [Feature Title]
 Status: ✅ DONE
 
 What we accomplished:
-✅ All BDD scenarios passing (success + error handling + edge cases)
+✅ All BDD scenarios passing (happy path + error handling + edge cases)
 ✅ Comprehensive error handling and validation
 ✅ Input validation and edge case coverage
 ✅ State consistency and data integrity
+✅ All code merged to main and pushed to GitHub
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 INTERNAL PROJECT - STABLE MODE IS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 This is an internal project - stable mode is the end state.
+No production hardening needed.
+
 Feature is complete and ready to use!
 
-Note: If you later transition to external (accepting real users),
-run the external-transition skill to generate production chores.
+Note: If you later transition to external state (accepting real users),
+you can run the external-transition skill to generate production chores.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**End skill.** Feature is DONE.
+**End skill.** The feature is DONE.
 
 ---
 
-**If project_state = 'external':**
+### Option B: Project is EXTERNAL
+
+**For external projects, continue to production mode.**
+
+Use the Skill tool to invoke the production-mode skill:
 
-Use Skill tool to invoke production-mode:
+```javascript
+// Use Skill tool to invoke: production-mode
+// The production-mode skill will:
+// 1. Detect feature context (Scenario A/B/C)
+// 2. Generate production scenarios from standards
+// 3. Append scenarios to feature file
+// 4. Create production chores
+```
+
+Display to user:
 
-Display:
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✅ ALL STABLE MODE CHORES COMPLETE!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 What we accomplished:
-✅ All BDD scenarios passing (success + error handling + edge cases)
+✅ All BDD scenarios passing (happy path + error handling + edge cases)
 ✅ Comprehensive error handling and validation
 ✅ Feature stable and ready for production hardening
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🚀 AUTO-GENERATING PRODUCTION CHORES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 This project is external - invoking production-mode skill to:
   • Detect feature context (authentication/data/general)
   • Generate production scenarios from standards
   • Create production chores with proper scope
+
+[Invoke production-mode skill - it handles the rest autonomously]
 ```
 
-Then invoke production-mode skill. **End skill.**
+**If stable chores remain:**
 
----
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Stable Mode Chore Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What we accomplished:
+✅ Scenario passes with proper error handling
+✅ Input validation added
+✅ Edge cases handled
+
+Remaining stable mode chores: [count]
+
+**Next step:** Continue with next stable mode chore
+  jettypod work start [next-stable-chore-id]
+```
+
+**Mark current chore as done:**
 
 ⚠️ **CRITICAL: Exclude CLAUDE.md from commits in worktrees**
 
@@ -619,17 +682,6 @@ Then use the merge command to merge to main (which auto-marks chore as done via
 jettypod work merge
 ```
 
-<details>
-<summary>💡 Multi-instance coordination (click to expand)</summary>
-
-The merge command uses a merge lock to prevent conflicts when multiple instances complete work simultaneously:
-- First instance acquires lock → merges → releases lock
-- Second instance waits → then acquires lock → merges
-- No manual coordination needed - happens automatically
-
-If you see "Acquiring merge lock..." message, another instance is merging. Wait 30-60 seconds.
-</details>
-
 The post-merge hook will automatically mark the chore as done when merged to main.
 
 ---
@@ -661,15 +713,15 @@ After completing EACH stable chore:
 **Example correct flow:**
 ```bash
 # Complete chore #1854
-git add . && git commit -m "feat: [description]"
-jettypod work merge  # Automatically pushes, merges, and cleans up
+git add . && git commit && git push
+jettypod work merge
 
 # NOW start chore #1855 (main has #1854's changes)
 jettypod work start 1855
 
 # Complete chore #1855
-git add . && git commit -m "feat: [description]"
-jettypod work merge  # Automatically pushes, merges, and cleans up
+git add . && git commit && git push
+jettypod work merge
 
 # NOW start chore #1856 (main has #1854 + #1855's changes)
 jettypod work start 1856