jettypod 4.1.2 → 4.1.4

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

@@ -13,24 +13,84 @@ When this skill is activated, you are helping implement a stable mode chore to a
 
 ### Overview
 
-**Stable Mode Goal:** Add error handling, validation, and edge case coverage to the speed mode implementation.
+**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 on the happy path
-- **Stable mode adds robustness** - error handling, validation, edge cases, error messages
+- **Stable mode adds COMPLETE robustness** - NOT just error handling, but comprehensive production readiness
+
+**Stable Mode is NOT just error handling. It includes:**
+
+1. **Comprehensive Error Handling**
+   - Catch all failure modes (network errors, file system errors, database errors)
+   - User-friendly error messages that explain what went wrong
+   - Graceful degradation when things fail
+   - Proper error propagation vs. recovery
+
+2. **Input Validation**
+   - Null/undefined checks before using values
+   - Type validation (is this actually a number/string/object?)
+   - Range validation (min/max values, length limits)
+   - Format validation (email format, URL format, date format)
+   - Sanitization (prevent injection attacks, XSS)
+
+3. **Edge Case Handling**
+   - Empty arrays/objects/strings
+   - Missing or optional properties
+   - Boundary values (0, -1, MAX_INT, empty string)
+   - Concurrent access (race conditions, simultaneous operations)
+   - Resource limits (too many items, files too large)
+
+4. **State Consistency & Data Integrity**
+   - Transaction handling (all-or-nothing operations)
+   - Cleanup on failure (rollback partial changes)
+   - Prevent corrupted state
+   - Handle interrupted operations
+
+5. **All BDD Scenarios Pass**
+   - 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)
 
 **Key Principles:**
-- **Build on speed implementation** - do not re-implement features, ADD to them
-- **Comprehensive error handling** - catch all failure modes, show clear error messages
-- **Input validation** - validate all inputs, handle edge cases (empty, null, max values, wrong types)
-- **Edge case coverage** - handle boundary conditions, race conditions, state consistency
-- **All BDD scenarios pass** - happy path AND error/edge case scenarios
+- **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.
 
 ---
 
+## ⚠️ 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.**
+
+For external products accepting real users, stable mode is NOT the final step. Production mode is REQUIRED for:
+- Performance optimization and load testing
+- Security hardening (rate limiting, input sanitization, authentication)
+- Monitoring and observability
+- Operational readiness (logging, metrics, alerting)
+
+**Required workflow for EXTERNAL products after stable mode implementation:**
+
+1. ✅ **Complete ALL stable mode chores** - Add error handling and edge cases
+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
+
+**For INTERNAL products (staging/preview only), stable mode IS the final step.**
+
+**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:
+- 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.
+
+---
+
 ## Implementation Steps
 
 ### Step 0: Create Additional Scenarios (If First Stable Chore)
@@ -63,6 +123,12 @@ Scenario: [Edge case title]
 - Follow existing patterns from happy path steps
 - Include proper error assertions
 
+**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
@@ -431,11 +497,28 @@ If user adjusts: revise proposal and confirm again.
 **Execution loop (with iteration limits and error handling):**
 
 ```javascript
-const MAX_ITERATIONS = 10; // Prevent infinite loops
-const TEST_TIMEOUT = 60000; // 60 second timeout per test run
+// Import test-runner utilities
+const {
+  MAX_ITERATIONS,
+  TEST_TIMEOUT,
+  runBddTestWithTimeout,
+  runBddScenarioWithTimeout,
+  getScenarioLineByName,
+  parseTestProgress,
+  extractErrors,
+  findNewlyPassingSteps
+} = require('../../.claude/skills/speed-mode/test-runner');
+
+// Identify target scenario line from targetScenario.title
+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;
 
 while (!scenarioPasses && iteration < MAX_ITERATIONS) {
   iteration++;
@@ -453,73 +536,67 @@ while (!scenarioPasses && iteration < MAX_ITERATIONS) {
     continue;
   }
 
-  // 2. Run tests with timeout
+  // 2. Run tests with timeout - only target scenario during iteration
   console.log('🧪 Running tests...');
 
-  let testsPassed = false;
-  try {
-    const { exec } = require('child_process');
-    const util = require('util');
-    const execPromise = util.promisify(exec);
-
-    const { stdout, stderr } = await execPromise('npm run test:bdd -- features/[feature-slug].feature', {
-      timeout: TEST_TIMEOUT,
-      killSignal: 'SIGTERM'
-    });
-
-    // Parse BDD test output to check if target scenario passes
-    // Step definitions (created during feature discovery) execute your code
-    const targetScenarioPassed = stdout.includes('[scenario-title]') && stdout.includes('✓');
-
-    if (targetScenarioPassed) {
-      console.log('✅ Target scenario passes!');
+  const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine, TEST_TIMEOUT);
 
-      // Check if ALL scenarios still pass
-      const allPass = !stdout.includes('✗') && !stdout.includes('failing');
+  // Check for 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;
+  }
 
-      if (allPass) {
-        console.log('✅ All scenarios still passing!');
-        scenarioPasses = true;
-      } else {
-        console.log('⚠️  Target scenario passes but other scenarios broke.');
-        console.log('Adjusting to fix regressions...');
-      }
-    } else {
-      console.log('❌ Target scenario still failing');
+  // Parse results
+  const currentResult = parseTestProgress(result.stdout);
 
-      // Extract failure reason from test output
-      const failureMatch = stdout.match(/AssertionError: (.+)/);
-      const failureReason = failureMatch ? failureMatch[1] : 'Unknown failure';
+  // Track progress
+  const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
 
-      console.log(`Reason: ${failureReason}`);
-      console.log('Analyzing and adjusting...');
-    }
+  // Display progress
+  console.log(`\n📊 Progress: ${currentResult.passed}/${currentResult.total} steps passing`);
 
-  } catch (testErr) {
-    // Error handling: Test timeout
-    if (testErr.killed && testErr.signal === 'SIGTERM') {
-      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');
+  if (newlyPassing.length > 0) {
+    console.log(`\n✅ Newly passing:`);
+    newlyPassing.forEach(step => console.log(`  • ${step}`));
+  }
 
-      // Ask user if they want to continue
-      console.log('\n⚠️  Test timeout - continue trying? (yes/no)');
-      // If no, break
-      break;
+  // Check if target scenario passes
+  if (currentResult.passed === currentResult.total && currentResult.total > 0) {
+    console.log('\n✅ Target scenario passing!');
+
+    // Run full verification (all scenarios) once for regression detection
+    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(`⚠️  Full verification found regressions: ${fullProgress.total - fullProgress.passed} scenarios failing`);
+      console.log('Continuing iterations to fix regressions...');
+      scenarioPasses = false;
+    } else {
+      console.log('✅ Full verification passed - all scenarios passing!');
+      scenarioPasses = true;
     }
-
-    // Error handling: Test execution errors
-    console.error('❌ Test execution error:', testErr.message);
-
-    // Check if it's a missing test file
-    if (testErr.message.includes('No tests found') || testErr.message.includes('Cannot find module')) {
-      console.error('Test file might not exist or is misconfigured.');
-      console.log('Suggestion: Create the test file or check test configuration');
-      break;
+  } else {
+    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('Retrying...');
   }
+
+  // Update previousResult for next iteration
+  previousResult = currentResult;
 }
 
 // Error handling: Max iterations reached
@@ -580,6 +657,43 @@ 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}`));
+}
+```
+
+**Display coverage summary:**
+```
+📊 Unit Test Coverage Report
+─────────────────────────────
+Statements: ✅ 85.23%
+Branches:   ✅ 82.15%
+Functions:  ✅ 88.50%
+Lines:      ✅ 84.90%
+─────────────────────────────
+✅ All coverage metrics meet 80% threshold
+```
+
 ### 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.**
@@ -621,25 +735,65 @@ db.get(`
 });
 ```
 
-**If all stable chores are done AND project is INTERNAL:**
+**CRITICAL: Check project state to determine next step:**
+
+Check if project is internal or external:
+```bash
+# Check project_state in database
+node jettypod.js work show 1 | grep "Project state:"
+# OR read CLAUDE.md <project_state> tag
+```
+
+---
+
+### Option A: Project is INTERNAL
+
+**For internal projects, stable mode is the FINAL state.**
+
+**ACTION REQUIRED:** Mark the feature as done:
+```bash
+node jettypod.js work status [feature-id] done
+```
+
+Then display to user:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ FEATURE COMPLETE!
+✅ FEATURE #[id] COMPLETE!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Feature: [Feature Title]
+Status: ✅ DONE
+
 What we accomplished:
 ✅ All BDD scenarios passing (happy path + error handling + edge cases)
 ✅ Comprehensive error handling and validation
-✅ Feature stable and ready to use
+✅ 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.
 
-This is an internal project - no production hardening needed.
+Feature is complete and ready to use!
 
-If you later transition to external state, production chores will be
-automatically generated from production standards.
+Note: If you later transition to external state (accepting real users),
+you can run the external-transition skill to generate production chores.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**If all stable chores are done AND project is EXTERNAL:**
+**End skill.** The feature is DONE.
+
+---
+
+### Option B: Project is EXTERNAL
+
+**For external projects, continue to production mode.**
 
 Use the Skill tool to invoke the production-mode skill:
 
@@ -696,18 +850,73 @@ Remaining stable mode chores: [count]
 
 **Mark current chore as done:**
 
-Use Bash tool to commit, push, and merge to main:
+⚠️ **CRITICAL: Exclude CLAUDE.md from commits in worktrees**
+
+CLAUDE.md contains work tracking metadata that changes frequently and causes merge conflicts. When committing in a worktree, **always reset CLAUDE.md** before committing:
+
 ```bash
-git add . && git commit -m "feat: [brief description of what was implemented]" && git push
+git checkout HEAD -- CLAUDE.md  # Reset CLAUDE.md to avoid merge conflicts
+git add .                        # Stage other changes
+git commit -m "feat: [brief description of what was implemented]"
+git push
 ```
 
-Then merge to main (which auto-marks chore as done via git hooks):
+Then use the merge command to merge to main (which auto-marks chore as done via post-merge hook):
 ```bash
-git checkout main && git pull && git merge [branch-name] && git push
+jettypod work merge
 ```
 
 The post-merge hook will automatically mark the chore as done when merged to main.
 
+---
+
+⚠️ **CRITICAL: SEQUENTIAL WORKFLOW FOR STABLE MODE CHORES**
+
+**Stable mode chores MUST be completed sequentially, not in parallel.**
+
+**Why Sequential?**
+- Multiple chores modify the same files (e.g., lib/merge-lock.js, step definitions)
+- Later chores build on earlier implementations
+- Tests and BDD scenarios depend on cumulative changes
+- Parallel worktrees branch from main independently, missing each other's changes
+
+**MANDATORY PROCESS:**
+
+After completing EACH stable chore:
+1. ✅ Commit changes in worktree (excluding CLAUDE.md)
+2. ✅ Push worktree branch
+3. ✅ **Merge to main immediately**
+4. ✅ **Push main**
+5. ✅ ONLY THEN start the next stable chore
+
+**DO NOT:**
+❌ Start multiple stable chores without merging previous ones
+❌ Leave stable chores unmerged "for later"
+❌ Assume worktrees will have each other's changes
+
+**Example correct flow:**
+```bash
+# Complete chore #1854
+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 && git push
+jettypod work merge
+
+# NOW start chore #1856 (main has #1854 + #1855's changes)
+jettypod work start 1856
+```
+
+If you fail to follow this sequential process, later worktrees will be missing earlier implementations, causing:
+- Missing functions/exports
+- Incomplete test coverage
+- Step definition errors
+- Duplicate work
+
 **End skill.**
 
 

package/.claude/PROTECT_SKILLS.md

@@ -1,28 +0,0 @@
-# ⚠️ CRITICAL: Skills Directory Protection
-
-The `.claude/skills/` directory contains essential skill files:
-- epic-planning
-- feature-planning
-- speed-mode
-- stable-mode
-
-**These files should NEVER be deleted or modified by automated processes.**
-
-If skills go missing, restore from git:
-```bash
-git restore .claude/skills/
-```
-
-## Root Cause Investigation
-
-The skills have been mysteriously deleted multiple times. Safety checks added to:
-- `features/work-commands/steps.js`
-- `features/work-commands/simple-steps.js`
-
-All `fs.rmSync()` operations now verify the target is in `/tmp/` before deleting.
-
-**If this keeps happening, check:**
-1. IDE file watchers or plugins
-2. Git hooks or operations
-3. Claude Code's internal file management
-4. Any other test cleanup scripts

package/.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".jettypod/hooks/protect-claude-md.js"
-          }
-        ]
-      },
-      {
-        "matcher": "Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".jettypod/hooks/protect-claude-md.js"
-          }
-        ]
-      }
-    ]
-  }
-}

package/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git reset:*)",
-      "Bash(mv:*)",
-      "Bash(npm install)",
-      "Bash(npx cucumber-js:*)",
-      "Bash(git add:*)",
-      "Bash(npm test:*)",
-      "Bash(npx cucumber:*)",
-      "Bash(find:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}