jettypod 4.1.4 → 4.1.6

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

@@ -5,6 +5,19 @@ description: Guide implementation of stable mode chores with comprehensive testi
 
 # Stable Mode Skill
 
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  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.
 
 ## Instructions
@@ -62,6 +75,23 @@ When this skill is activated, you are helping implement a stable mode chore to a
 
 ---
 
+## Quick Reference: Async Boundaries
+
+**Where Claude Code MUST wait for user confirmation:**
+
+| Phase | Location | Why |
+|-------|----------|-----|
+| Step 3 Phase 1 | Before implementing | User confirms implementation approach |
+
+**Where Claude Code executes autonomously:**
+- Step 0: Create additional scenarios (if first stable chore)
+- Step 1: Scenario analysis
+- Step 2: Speed mode implementation review
+- Step 3 Phase 2: Autonomous execution loop
+- Step 4: Completion check and routing
+
+---
+
 ## ⚠️ CRITICAL: Stable Mode Workflow Requirements for External Products
 
 **If the product is EXTERNAL (project_state: 'external'), DO NOT mark features as complete after stable mode.**
@@ -93,6 +123,11 @@ The validation will require you to either:
 
 ## Implementation Steps
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 1: AUTONOMOUS SETUP
+     No user input required - Claude Code executes independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 0: Create Additional Scenarios (If First Stable Chore)
 
 **CRITICAL:** If this is the FIRST stable mode chore for this feature, you must ADD edge case scenarios and step definitions.
@@ -144,43 +179,43 @@ Scenario: [Edge case title]
 **Code to get scenario (with error handling):**
 
 ```javascript
+// --- Imports ---
 const { getCurrentWork } = require('../../lib/current-work');
 const { getDb } = require('../../lib/database');
 const fs = require('fs');
 const path = require('path');
 
-try {
-  const currentWork = getCurrentWork();
-
-  // Error handling: Check if current work exists
-  if (!currentWork) {
-    console.error('❌ No current work found. Run: jettypod work start <chore-id>');
-    return;
-  }
+(async () => {
+  try {
+    const currentWork = await getCurrentWork();
 
-  // Error handling: Check if parent exists
-  if (!currentWork.parent_id) {
-    console.error('❌ Current work has no parent feature. This chore must be part of a feature.');
-    return;
-  }
+    // --- Validate current work ---
+    if (!currentWork) {
+      console.error('❌ No current work found. Run: jettypod work start <chore-id>');
+      return;
+    }
 
-  const db = getDb();
-  db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], (err, feature) => {
-    // Error handling: Database errors
-    if (err) {
-      console.error('❌ Database error:', err.message);
-      db.close();
+    if (!currentWork.parent_id) {
+      console.error('❌ Current work has no parent feature. This chore must be part of a feature.');
       return;
     }
 
-    // Error handling: Feature not found
+    // --- Get parent feature ---
+    const db = getDb();
+    const feature = await new Promise((resolve, reject) => {
+      db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], (err, row) => {
+        if (err) reject(err);
+        else resolve(row);
+      });
+    });
+
+    // --- Validate feature ---
     if (!feature) {
       console.error('❌ Parent feature not found in database.');
       db.close();
       return;
     }
 
-    // Error handling: No scenario file
     if (!feature.scenario_file) {
       console.error('❌ Feature has no scenario_file. Cannot determine what to implement.');
       console.log('Suggestion: Create a scenario file and update the feature.');
@@ -188,9 +223,9 @@ try {
       return;
     }
 
+    // --- Validate scenario file exists ---
     const scenarioPath = path.join(process.cwd(), feature.scenario_file);
 
-    // Error handling: Scenario file doesn't exist
     if (!fs.existsSync(scenarioPath)) {
       console.error(`❌ Scenario file not found: ${scenarioPath}`);
       console.log('Suggestion: Create the scenario file or update the feature.scenario_file path.');
@@ -198,7 +233,7 @@ try {
       return;
     }
 
-    // Error handling: File read errors
+    // --- Read scenario content ---
     let scenarioContent;
     try {
       scenarioContent = fs.readFileSync(scenarioPath, 'utf8');
@@ -208,7 +243,7 @@ try {
       return;
     }
 
-    // Error handling: Empty scenario file
+    // --- Validate content ---
     if (!scenarioContent || scenarioContent.trim().length === 0) {
       console.error('❌ Scenario file is empty.');
       db.close();
@@ -217,28 +252,27 @@ try {
 
     // Parse all scenarios...
     db.close();
-  });
-} catch (err) {
-  console.error('❌ Unexpected error in Step 1:', err.message);
-  return;
-}
+  } catch (err) {
+    console.error('❌ Unexpected error in Step 1:', err.message);
+    return;
+  }
+})();
 ```
 
 **Identify target scenario (with error handling):**
 
 ```javascript
-// Parse scenarios from Gherkin content
+// --- Parse scenarios from Gherkin ---
 const scenarios = [];
 const scenarioBlocks = scenarioContent.split(/\nScenario:/);
 
-// Error handling: No scenarios found
 if (scenarioBlocks.length < 2) {
   console.error('❌ No scenarios found in scenario file.');
   console.log('Suggestion: Add Gherkin scenarios to the feature file.');
   return;
 }
 
-// Parse each scenario
+// --- Extract scenario titles ---
 for (let i = 1; i < scenarioBlocks.length; i++) {
   const block = 'Scenario:' + scenarioBlocks[i];
   const titleMatch = block.match(/Scenario:\s*(.+)/);
@@ -246,11 +280,11 @@ for (let i = 1; i < scenarioBlocks.length; i++) {
   scenarios.push({ title, content: block });
 }
 
-// Match scenario to chore
+// --- Match scenario to chore ---
 const choreDesc = currentWork.description.toLowerCase();
 let targetScenario = null;
 
-// Try to match by scenario number in chore description
+// --- Try match by scenario number ---
 const scenarioNumMatch = choreDesc.match(/scenario\s+(\d+)/);
 if (scenarioNumMatch) {
   const num = parseInt(scenarioNumMatch[1]);
@@ -259,14 +293,12 @@ if (scenarioNumMatch) {
   }
 }
 
-// Try to match by keywords if no number match
+// --- Try match by keywords ---
 if (!targetScenario) {
   for (const scenario of scenarios) {
     const scenarioLower = scenario.title.toLowerCase();
-    // Skip happy path (usually first scenario)
-    if (scenarios.indexOf(scenario) === 0) continue;
+    if (scenarios.indexOf(scenario) === 0) continue; // Skip happy path
 
-    // Match keywords from chore description
     const keywords = choreDesc.split(/\s+/).filter(w => w.length > 3);
     const matches = keywords.filter(k => scenarioLower.includes(k));
 
@@ -277,7 +309,7 @@ if (!targetScenario) {
   }
 }
 
-// Error handling: No matching scenario
+// --- Handle no match ---
 if (!targetScenario) {
   console.error('❌ Cannot match chore to any scenario in feature file.');
   console.log('Available scenarios:');
@@ -318,35 +350,28 @@ Now reviewing speed mode implementation...
 **Find speed mode files (with error handling):**
 
 ```javascript
+// --- Imports and setup ---
 const { exec } = require('child_process');
 const util = require('util');
 const execPromise = util.promisify(exec);
 
-// Try to find files from git history
 let speedModeFiles = [];
 
 try {
-  // Get commits for this feature
+  // --- Search git history for feature commits ---
   const featureName = feature.title.toLowerCase().replace(/\s+/g, '-');
   const { stdout: gitLog } = await execPromise(
     `git log --oneline --all --grep="${featureName}" -10`
   );
 
-  // Error handling: No commits found
+  // --- Handle no commits found ---
   if (!gitLog || gitLog.trim().length === 0) {
     console.log('⚠️  No git commits found for this feature.');
-    console.log('Asking user for files created in speed mode...');
-
-    // Ask user which files were created
     console.log('\n📝 Which files did speed mode create/modify for this feature?');
-    console.log('(List file paths, one per line, or type "none" if no files exist)\n');
-
-    // Wait for user response...
-    // If user says "none", handle gracefully
     return;
   }
 
-  // Get files changed in those commits
+  // --- Extract files from commits ---
   const commits = gitLog.trim().split('\n').map(line => line.split(' ')[0]);
 
   for (const commit of commits) {
@@ -355,24 +380,16 @@ try {
       const fileList = files.trim().split('\n').filter(f => f.length > 0);
       speedModeFiles.push(...fileList);
     } catch (diffErr) {
-      // Ignore errors for individual commits
       continue;
     }
   }
 
-  // Remove duplicates
+  // --- Remove duplicates and validate ---
   speedModeFiles = [...new Set(speedModeFiles)];
 
-  // Error handling: No files found
   if (speedModeFiles.length === 0) {
     console.error('❌ No files found in git history for this feature.');
-    console.log('Suggestion: Either:');
-    console.log('  1. Specify files manually');
-    console.log('  2. Check if speed mode committed changes');
-    console.log('  3. Start fresh if speed mode was not completed\n');
-
-    // Ask user for files
-    console.log('📝 Which files should be reviewed? (or type "start-fresh" to begin from scratch)');
+    console.log('📝 Which files should be reviewed?');
     return;
   }
 
@@ -380,26 +397,22 @@ try {
 
 } catch (gitErr) {
   console.error('⚠️  Git error:', gitErr.message);
-  console.log('Falling back to manual file specification...\n');
-
   console.log('📝 Which files did speed mode create/modify?');
   return;
 }
 
-// Validate files are readable
+// --- Validate files are readable ---
 const readableFiles = [];
 const unreadableFiles = [];
 
 for (const filePath of speedModeFiles) {
   const fullPath = path.join(process.cwd(), filePath);
 
-  // Error handling: File doesn't exist
   if (!fs.existsSync(fullPath)) {
     console.log(`⚠️  File no longer exists: ${filePath}`);
     continue;
   }
 
-  // Error handling: File not readable
   try {
     fs.accessSync(fullPath, fs.constants.R_OK);
     readableFiles.push(filePath);
@@ -409,16 +422,15 @@ for (const filePath of speedModeFiles) {
   }
 }
 
-// Error handling: No readable files
+// --- Final validation ---
 if (readableFiles.length === 0) {
   console.error('❌ No readable speed mode files found.');
-  console.log('Cannot proceed without existing implementation to review.');
-  console.log('\nSuggestion: Verify that speed mode was completed or start implementation from scratch.');
+  console.log('Suggestion: Verify speed mode was completed or start from scratch.');
   return;
 }
 
 if (unreadableFiles.length > 0) {
-  console.log(`⚠️  ${unreadableFiles.length} files cannot be read - skipping them`);
+  console.log(`⚠️  ${unreadableFiles.length} files cannot be read - skipping`);
 }
 
 speedModeFiles = readableFiles;
@@ -452,6 +464,11 @@ Now proposing comprehensive implementation...
 
 **Move to Step 3 automatically.**
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 2: USER CONFIRMATION REQUIRED
+     ⚡ ASYNC BOUNDARY - Must wait for user response before proceeding
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 3: Propose and Execute Comprehensive Implementation
 
 **Two phases: Propose (get user confirmation) → Execute (autonomous)**
@@ -490,26 +507,40 @@ Sound good? I'll implement this autonomously once you confirm.
 
 If user adjusts: revise proposal and confirm again.
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 3: AUTONOMOUS EXECUTION
+     User has confirmed - Claude Code executes iteration loop independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 #### Phase 2: Autonomous Execution
 
 **CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
 
 **Execution loop (with iteration limits and error handling):**
 
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔄 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         │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
+
 ```javascript
-// Import test-runner utilities
+// --- Imports ---
 const {
-  MAX_ITERATIONS,
-  TEST_TIMEOUT,
-  runBddTestWithTimeout,
-  runBddScenarioWithTimeout,
-  getScenarioLineByName,
-  parseTestProgress,
-  extractErrors,
-  findNewlyPassingSteps
+  MAX_ITERATIONS, TEST_TIMEOUT, runBddTestWithTimeout,
+  runBddScenarioWithTimeout, getScenarioLineByName,
+  parseTestProgress, extractErrors, findNewlyPassingSteps
 } = require('../../.claude/skills/speed-mode/test-runner');
 
-// Identify target scenario line from targetScenario.title
+// --- Find scenario line number ---
 const scenarioLine = getScenarioLineByName(feature.scenario_file, targetScenario.title);
 if (!scenarioLine) {
   console.error('❌ Cannot find scenario line number for:', targetScenario.title);
@@ -520,42 +551,37 @@ 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}`);
 
-  // 1. Modify existing files using Edit tool
+  // --- Make code changes ---
   try {
-    // Add error handling, validation, error messages, etc.
     console.log('✍️  Adding error handling to [file]...');
     // ... use Edit tool ...
     console.log('✅ Updated [file]');
   } catch (editErr) {
     console.error('❌ Error modifying files:', editErr.message);
-    console.log('Retrying with adjusted approach...');
     continue;
   }
 
-  // 2. Run tests with timeout - only target scenario during iteration
+  // --- Run tests ---
   console.log('🧪 Running tests...');
-
   const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine, TEST_TIMEOUT);
 
-  // Check for timeout
+  // --- Handle timeout ---
   if (result.timedOut) {
     console.error('❌ Tests timed out after 60 seconds');
-    console.log('This might indicate an infinite loop or hung process.');
     console.log('Suggestion: Check for blocking operations or missing async/await');
     break;
   }
 
-  // Parse results
+  // --- Parse and track progress ---
   const currentResult = parseTestProgress(result.stdout);
-
-  // Track progress
   const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
 
-  // Display progress
   console.log(`\n📊 Progress: ${currentResult.passed}/${currentResult.total} steps passing`);
 
   if (newlyPassing.length > 0) {
@@ -563,11 +589,11 @@ while (!scenarioPasses && iteration < MAX_ITERATIONS) {
     newlyPassing.forEach(step => console.log(`  • ${step}`));
   }
 
-  // Check if target scenario passes
+  // --- Check for success ---
   if (currentResult.passed === currentResult.total && currentResult.total > 0) {
     console.log('\n✅ Target scenario passing!');
 
-    // Run full verification (all scenarios) once for regression detection
+    // --- Run full verification ---
     console.log('\n🔍 Running full verification (all scenarios)...');
     const fullResult = await runBddTestWithTimeout(feature.scenario_file, TEST_TIMEOUT);
 
@@ -575,31 +601,27 @@ while (!scenarioPasses && iteration < MAX_ITERATIONS) {
       console.log('⚠️  Full verification timed out');
     } else if (fullResult.exitCode !== 0) {
       const fullProgress = parseTestProgress(fullResult.stdout + fullResult.stderr);
-      console.log(`⚠️  Full verification found regressions: ${fullProgress.total - fullProgress.passed} scenarios failing`);
-      console.log('Continuing iterations to fix regressions...');
+      console.log(`⚠️  Regressions found: ${fullProgress.total - fullProgress.passed} scenarios failing`);
       scenarioPasses = false;
     } else {
-      console.log('✅ Full verification passed - all scenarios passing!');
+      console.log('✅ Full verification passed!');
       scenarioPasses = true;
     }
   } else {
+    // --- Display errors ---
     console.log(`\n❌ ${currentResult.total - currentResult.passed} scenarios still failing`);
-
-    // Extract and display errors
     const errors = extractErrors(result.stdout + result.stderr);
     if (errors.errors.length > 0) {
       console.log('\n🔧 Next failure to address:');
-      const firstError = errors.errors[0];
-      console.log(`  Step: ${firstError.step}`);
-      console.log(`  Error: ${firstError.message}`);
+      console.log(`  Step: ${errors.errors[0].step}`);
+      console.log(`  Error: ${errors.errors[0].message}`);
     }
   }
 
-  // Update previousResult for next iteration
   previousResult = currentResult;
 }
 
-// Error handling: Max iterations reached
+// --- Handle max iterations reached ---
 if (!scenarioPasses && iteration >= MAX_ITERATIONS) {
   console.error('\n❌ Maximum iterations reached without passing scenario');
   console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -609,15 +631,7 @@ if (!scenarioPasses && iteration >= MAX_ITERATIONS) {
   console.log('• Scenario requirements may need clarification');
   console.log('• Implementation approach may need rethinking');
   console.log('• External dependencies may be missing');
-  console.log('• Test assertions may be incorrect');
-  console.log('\nSuggestions:');
-  console.log('1. Review the scenario and verify it\'s achievable');
-  console.log('2. Check test output for specific failure patterns');
-  console.log('3. Try a different implementation approach');
-  console.log('4. Ask for help if stuck\n');
-
-  // Ask user how to proceed
-  console.log('How would you like to proceed?');
+  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');
@@ -657,31 +671,16 @@ Implementation complete:
 • All scenarios: ✅ Passing
 ```
 
-**Run unit test coverage tracking:**
-```javascript
-const { trackFeatureCoverage } = require('../../lib/coverage-tracker');
-
-// Track coverage for modified implementation files
-const implementationFiles = [
-  // List of .js files modified during implementation (exclude test files)
-];
-
-console.log('\n📊 Running unit test coverage...');
-const coverageResult = trackFeatureCoverage(implementationFiles, {
-  coverageThreshold: 80, // 80% coverage target
-  verbose: false
-});
-
-console.log(coverageResult.report);
-
-if (!coverageResult.success) {
-  console.log('\n⚠️  Coverage below 80% threshold');
-  console.log('Consider adding more unit tests to cover edge cases');
-  console.log('\nTest files:');
-  coverageResult.testFiles.forEach(f => console.log(`  • ${f}`));
-}
+**Run unit test coverage (if configured):**
+```bash
+# If project has coverage configured, run it:
+npm run test:coverage
+# Or with Jest:
+npx jest --coverage
 ```
 
+Note: Coverage tracking is project-specific. Check your package.json for the appropriate coverage command.
+
 **Display coverage summary:**
 ```
 📊 Unit Test Coverage Report
@@ -694,45 +693,77 @@ Lines:      ✅ 84.90%
 ✅ All coverage metrics meet 80% threshold
 ```
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 4: COMPLETION AND ROUTING
+     Conditional phase - route based on project state (internal vs external)
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 4: Check for Production Mode (When All Stable Chores Complete)
 
 **CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete. Otherwise skip to marking chore as done.**
 
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔍 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               │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
+
 **Check completion status and project state:**
 ```javascript
+// --- Imports ---
 const { getDb } = require('../../lib/database');
 const { getCurrentWork } = require('../../lib/current-work');
 
-const currentWork = getCurrentWork();
-const featureId = currentWork.parent_id;
-
-const db = getDb();
-db.get(`
-  SELECT COUNT(*) as incomplete_count
-  FROM work_items
-  WHERE parent_id = ?
-    AND type = 'chore'
-    AND status NOT IN ('done', 'cancelled')
-`, [featureId], (err, result) => {
+(async () => {
+  // --- Get current work context ---
+  const currentWork = await getCurrentWork();
+  const featureId = currentWork.parent_id;
+  const db = getDb();
+
+  // --- Query for incomplete chores ---
+  const result = await new Promise((resolve, reject) => {
+    db.get(`
+      SELECT COUNT(*) as incomplete_count
+      FROM work_items
+      WHERE parent_id = ?
+        AND type = 'chore'
+        AND status NOT IN ('done', 'cancelled')
+    `, [featureId], (err, row) => {
+      if (err) reject(err);
+      else resolve(row);
+    });
+  });
+
+  // --- Handle all chores complete ---
   if (result.incomplete_count === 0) {
-    // All stable chores done - check project state
-    db.get('SELECT project_state FROM project_config WHERE id = 1', (err, config) => {
-      const projectState = config?.project_state || 'internal';
-
-      if (projectState === 'internal') {
-        // Internal project - stable mode is complete
-        console.log('Internal project - no production mode needed');
-      } else {
-        // External project - invoke production-mode skill
-        console.log('External project - auto-generating production chores from standards');
-      }
+    const config = await new Promise((resolve, reject) => {
+      db.get('SELECT project_state FROM project_config WHERE id = 1', (err, row) => {
+        if (err) reject(err);
+        else resolve(row);
+      });
     });
+    const projectState = config?.project_state || 'internal';
+
+    // --- Route based on project state ---
+    if (projectState === 'internal') {
+      console.log('Internal project - no production mode needed');
+    } else {
+      console.log('External project - auto-generating production chores');
+    }
   } else {
-    // More chores remain - just mark this one done
     console.log(`\n📋 ${result.incomplete_count} stable mode chores remaining`);
   }
+
   db.close();
-});
+})();
 ```
 
 **CRITICAL: Check project state to determine next step:**