jettypod 4.4.82 → 4.4.84

package/lib/db-export.js

@@ -83,17 +83,16 @@ async function exportWorkDb() {
   try {
     fs.writeFileSync(outputPath, JSON.stringify(data, null, 2), 'utf8');
   } catch (err) {
-    // Log warning but don't throw - we don't want to block git operations
-    console.error('Pre-commit hook warning: Failed to export work.json');
+    // Throw error to block commit - snapshot backup is critical
+    let message = 'Failed to export work.json';
     if (err.code === 'EACCES') {
-      console.error('  Permission denied - check directory permissions');
+      message += ': Permission denied - check directory permissions';
     } else if (err.code === 'ENOSPC') {
-      console.error('  No space left on device');
+      message += ': No space left on device';
     } else {
-      console.error(`  ${err.message}`);
+      message += `: ${err.message}`;
     }
-    console.error('  Commit will proceed but snapshots were not updated');
-    // Return path anyway so commit can continue
+    throw new Error(message);
   }
 
   return outputPath;
@@ -115,15 +114,16 @@ async function exportDatabaseDb() {
     try {
       fs.writeFileSync(outputPath, JSON.stringify({}, null, 2), 'utf8');
     } catch (err) {
-      console.error('Pre-commit hook warning: Failed to export database.json');
+      // Throw error to block commit - snapshot backup is critical
+      let message = 'Failed to export database.json';
       if (err.code === 'EACCES') {
-        console.error('  Permission denied - check directory permissions');
+        message += ': Permission denied - check directory permissions';
       } else if (err.code === 'ENOSPC') {
-        console.error('  No space left on device');
+        message += ': No space left on device';
       } else {
-        console.error(`  ${err.message}`);
+        message += `: ${err.message}`;
       }
-      console.error('  Commit will proceed but snapshots were not updated');
+      throw new Error(message);
     }
     return outputPath;
   }
@@ -142,15 +142,18 @@ async function exportDatabaseDb() {
         try {
           fs.writeFileSync(outputPath, JSON.stringify(data, null, 2), 'utf8');
         } catch (writeErr) {
-          console.error('Pre-commit hook warning: Failed to export database.json');
+          // Throw error to block commit - snapshot backup is critical
+          let message = 'Failed to export database.json';
           if (writeErr.code === 'EACCES') {
-            console.error('  Permission denied - check directory permissions');
+            message += ': Permission denied - check directory permissions';
           } else if (writeErr.code === 'ENOSPC') {
-            console.error('  No space left on device');
+            message += ': No space left on device';
           } else {
-            console.error(`  ${writeErr.message}`);
+            message += `: ${writeErr.message}`;
           }
-          console.error('  Commit will proceed but snapshots were not updated');
+          db.close();
+          reject(new Error(message));
+          return;
         }
 
         db.close((closeErr) => {

package/lib/db-import.js

@@ -2,6 +2,109 @@ const fs = require('fs');
 const path = require('path');
 const { getDb, getJettypodDir } = require('./database');
 
+// Valid values for work_items fields
+const VALID_TYPES = ['epic', 'feature', 'chore', 'bug'];
+const VALID_STATUSES = ['backlog', 'todo', 'in_progress', 'done', 'cancelled'];
+
+/**
+ * Validate a single work item against the schema
+ * @param {Object} item - Work item to validate
+ * @param {number} index - Index in array for error messages
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+function validateWorkItem(item, index) {
+  const errors = [];
+
+  if (typeof item !== 'object' || item === null) {
+    return { valid: false, errors: [`Item ${index}: must be an object`] };
+  }
+
+  // Required: id must be a number
+  if (item.id === undefined || item.id === null) {
+    errors.push(`Item ${index}: missing required field 'id'`);
+  } else if (typeof item.id !== 'number' || !Number.isInteger(item.id)) {
+    errors.push(`Item ${index}: 'id' must be an integer`);
+  }
+
+  // Required: type must be a valid string
+  if (item.type === undefined || item.type === null) {
+    errors.push(`Item ${index}: missing required field 'type'`);
+  } else if (typeof item.type !== 'string') {
+    errors.push(`Item ${index}: 'type' must be a string`);
+  } else if (!VALID_TYPES.includes(item.type)) {
+    errors.push(`Item ${index}: 'type' must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+
+  // Required: title must be a string
+  if (item.title === undefined || item.title === null) {
+    errors.push(`Item ${index}: missing required field 'title'`);
+  } else if (typeof item.title !== 'string') {
+    errors.push(`Item ${index}: 'title' must be a string`);
+  }
+
+  // Optional: status must be valid if present
+  if (item.status !== undefined && item.status !== null) {
+    if (typeof item.status !== 'string') {
+      errors.push(`Item ${index}: 'status' must be a string`);
+    } else if (!VALID_STATUSES.includes(item.status)) {
+      errors.push(`Item ${index}: 'status' must be one of: ${VALID_STATUSES.join(', ')}`);
+    }
+  }
+
+  // Optional: parent_id must be integer if present
+  if (item.parent_id !== undefined && item.parent_id !== null) {
+    if (typeof item.parent_id !== 'number' || !Number.isInteger(item.parent_id)) {
+      errors.push(`Item ${index}: 'parent_id' must be an integer`);
+    }
+  }
+
+  // Optional: epic_id must be integer if present
+  if (item.epic_id !== undefined && item.epic_id !== null) {
+    if (typeof item.epic_id !== 'number' || !Number.isInteger(item.epic_id)) {
+      errors.push(`Item ${index}: 'epic_id' must be an integer`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate work.json data structure and content
+ * @param {Object} data - Parsed JSON data
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+function validateWorkJson(data) {
+  const errors = [];
+
+  if (typeof data !== 'object' || data === null) {
+    return { valid: false, errors: ['Data must be an object'] };
+  }
+
+  // work_items must be present and an array
+  if (!data.work_items) {
+    return { valid: false, errors: ['Missing required field: work_items'] };
+  }
+
+  if (!Array.isArray(data.work_items)) {
+    return { valid: false, errors: ['work_items must be an array'] };
+  }
+
+  // Validate each work item
+  data.work_items.forEach((item, index) => {
+    const result = validateWorkItem(item, index);
+    errors.push(...result.errors);
+  });
+
+  // Check for duplicate IDs
+  const ids = data.work_items.map(item => item.id).filter(id => id !== undefined);
+  const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (duplicates.length > 0) {
+    errors.push(`Duplicate work item IDs found: ${[...new Set(duplicates)].join(', ')}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
 /**
  * Import tables from JSON structure into a database
  * @param {sqlite3.Database} db - Database connection
@@ -86,6 +189,18 @@ async function importWorkDb() {
     const jsonContent = fs.readFileSync(jsonPath, 'utf8');
     const data = JSON.parse(jsonContent);
 
+    // Validate schema before importing
+    const validation = validateWorkJson(data);
+    if (!validation.valid) {
+      console.error('Post-checkout hook warning: work.json schema validation failed');
+      validation.errors.slice(0, 5).forEach(err => console.error(`  - ${err}`));
+      if (validation.errors.length > 5) {
+        console.error(`  ... and ${validation.errors.length - 5} more errors`);
+      }
+      console.error('  Database will remain in previous state');
+      return jsonPath;
+    }
+
     const db = getDb();
     await importTables(db, data);
 
@@ -189,5 +304,9 @@ async function importAll() {
 module.exports = {
   importWorkDb,
   importDatabaseDb,
-  importAll
+  importAll,
+  validateWorkJson,
+  validateWorkItem,
+  VALID_TYPES,
+  VALID_STATUSES
 };

package/lib/git-hooks/pre-commit

@@ -55,23 +55,63 @@ if (!checkBranchRestriction()) {
   process.exit(1);
 }
 
-// Check if we're in a real project (not a test directory)
-const packageJsonPath = path.join(process.cwd(), 'package.json');
-if (!fs.existsSync(packageJsonPath)) {
-  // Skip tests in test directories
-  process.exit(0);
-}
+// Export database snapshots (runs for all commits where .jettypod exists)
+async function exportSnapshots() {
+  const jettypodDir = path.join(process.cwd(), '.jettypod');
+  if (!fs.existsSync(jettypodDir)) {
+    return; // No JettyPod directory, skip export
+  }
+
+  console.log('\n📸 Exporting database snapshots...\n');
 
-console.log('\n🧪 Running tests before commit...\n');
+  try {
+    const { exportAll } = require('../db-export');
+    const paths = await exportAll();
 
-try {
-  // Run tests
-  execSync('npm test', { stdio: 'inherit' });
+    // Stage the snapshot files
+    execSync(`git add "${paths.work}" "${paths.database}"`, {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
 
-  console.log('\n✅ Tests passed! Proceeding with commit.\n');
-  process.exit(0);
-} catch (err) {
-  console.log('\n❌ Tests failed! Commit blocked.\n');
-  console.log('Fix the failing tests or use --no-verify to skip this check.\n');
-  process.exit(1);
+    console.log('✅ Snapshots exported and staged\n');
+  } catch (err) {
+    console.error('');
+    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.error('❌ Snapshot export failed! Commit blocked.');
+    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.error('');
+    console.error(`Error: ${err.message}`);
+    console.error('');
+    console.error('This prevents data loss - your work items must be backed up.');
+    console.error('Check disk space and directory permissions.');
+    console.error('');
+    process.exit(1);
+  }
 }
+
+// Main async flow
+(async () => {
+  // Export snapshots first (before tests, so they're included in commit)
+  await exportSnapshots();
+
+  // Check if we're in a real project (not a test directory)
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    // Skip tests in test directories
+    process.exit(0);
+  }
+
+  console.log('🧪 Running tests before commit...\n');
+
+  try {
+    // Run tests
+    execSync('npm test', { stdio: 'inherit' });
+
+    console.log('\n✅ Tests passed! Proceeding with commit.\n');
+    process.exit(0);
+  } catch (err) {
+    console.log('\n❌ Tests failed! Commit blocked.\n');
+    console.log('Fix the failing tests or use --no-verify to skip this check.\n');
+    process.exit(1);
+  }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.82",
+  "version": "4.4.84",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {

package/skills-templates/bug-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bug-planning
-description: Guide structured bug investigation with symptom capture, hypothesis testing, and root cause identification. Creates bug work item for direct implementation. Use when user reports a bug, mentions unexpected behavior, or says "investigate bug".
+description: Guide structured bug investigation with symptom capture, hypothesis testing, and root cause identification. Invoked by plan-routing when user reports a bug, mentions unexpected behavior, or describes something broken. (project)
 ---
 
 # Bug Planning Skill

package/skills-templates/chore-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chore-planning
-description: Guide standalone chore planning with automatic type classification and routing to chore-mode. Use when the implementation approach is obvious - refactoring, bug fixes, infrastructure, or simple enhancements where there's no UX decision to make. Key question - "Does this need UX exploration?" No → chore-planning. Yes → feature-planning instead.
+description: Guide standalone chore planning with automatic type classification and routing to chore-mode. Invoked by plan-routing for substantial technical work - refactoring, infrastructure, migrations, or enhancements where the implementation approach is obvious. (project)
 ---
 
 # Chore Planning Skill

package/skills-templates/epic-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: epic-planning
-description: Guide epic planning with feature brainstorming and optional architectural decision prototyping. Use when user asks to plan an epic, mentions planning features for an epic, says "help me plan epic", or when they just created an epic and want to break it down into features.
+description: Guide epic planning with feature brainstorming and optional architectural decision prototyping. Invoked by plan-routing for large multi-feature initiatives that need to be broken down into features. (project)
 ---
 
 # Epic Planning Skill

package/skills-templates/feature-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-planning
-description: Guide feature planning with UX approach exploration and BDD scenario generation. Use when implementing NEW user-facing behavior that requires UX decisions (multiple valid approaches to discuss). NOT for simple/obvious changes like copy tweaks, styling fixes, or adding straightforward functionality. Key question - "Does this need UX exploration?" Yes → feature-planning.
+description: Guide feature planning with UX approach exploration and BDD scenario generation. Invoked by plan-routing when implementing NEW user-facing behavior that requires UX decisions (multiple valid approaches to explore). (project)
 ---
 
 # Feature Planning Skill
@@ -63,49 +63,8 @@ jettypod workflow start feature-planning <feature-id>
 
 This creates an execution record for session resume.
 
-### Step 1B: Route Simple Improvements
-
-**CRITICAL:** Before proceeding with full feature planning, determine if this is a simple improvement.
-
-**Ask the user:**
-
-```
-Is this:
-1. **Simple improvement** - A basic enhancement to existing functionality (e.g., copy change, styling tweak, minor behavior adjustment)
-2. **New functionality** - Adding new capabilities, even if small
-
-Simple improvements skip the full feature planning workflow and use a lightweight process.
-```
-
-**⚡ WAIT for user response.**
-
-**If user says "simple improvement" (or 1):**
-
-Display:
-```
-This is a simple improvement. Routing to the lightweight simple-improvement workflow...
-```
-
-**Then IMMEDIATELY invoke simple-improvement using the Skill tool:**
-```
-Use the Skill tool with skill: "simple-improvement"
-```
-
-**Feature-planning skill ends here for simple improvements.** The simple-improvement skill takes over.
-
----
-
-**If user says "new functionality" (or 2):**
-
-Display:
-```
-Got it - this is new functionality. Let's explore the best approach...
-```
-
 **Proceed to Step 2** (or Step 3 if this is a standalone feature with no parent epic).
 
----
-
 ### Step 2: Check Epic Architectural Decisions
 
 **Skip this step and proceed to Step 3 if `PARENT_EPIC_ID` from Step 1 is null (standalone feature).**

package/skills-templates/plan-routing/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: plan-routing
+description: Route work requests to the appropriate planning skill. Use when user describes work they want to do - "build X", "fix Y", "add Z", "plan W". Analyzes intent and complexity to route to bug-planning, chore-planning, feature-planning, epic-planning, or simple-improvement. (project)
+---
+
+# Plan Routing Skill
+
+Routes user work requests to the correct planning workflow with minimal friction.
+
+## Instructions
+
+When this skill is activated, you are helping route a user's work request to the appropriate planning skill. Follow this structured approach:
+
+### Step 1: Extract Intent Signals
+
+From the user's request, identify work type and complexity signals:
+
+**Work type signals:**
+| Signal Words | Likely Route |
+|--------------|--------------|
+| fix, bug, broken, crash, error, not working, regression | bug-planning |
+| refactor, rename, move, clean up, upgrade, migrate, infrastructure | chore-planning |
+| add, build, create, implement, new feature, capability, workflow | feature-planning |
+| epic, initiative, project, roadmap, multi-feature | epic-planning |
+| tweak, change, update, adjust + small scope | simple-improvement |
+
+**Complexity signals:**
+| Signal | Indicates |
+|--------|-----------|
+| "quick", "small", "just", "simple", "tweak" | Lower complexity |
+| "feature", "workflow", "experience", "redesign" | Higher complexity |
+| References specific file/function | Lower complexity |
+| Describes user-facing behavior change | Higher complexity |
+
+### Step 2: Gather Context (Silent - No Questions)
+
+Before routing, quickly probe the codebase for context. **Do NOT ask the user for this information.**
+
+```bash
+# Check for related existing code
+jettypod impact "<key-term-from-request>"
+```
+
+```bash
+# Check for existing work items
+jettypod backlog | grep -i "<key-term>"
+```
+
+**Assess from results:**
+- Existing code? → Likely modification vs creation
+- Related work items? → May already be planned
+- How many files affected? → Complexity indicator
+
+### Step 3: Route with Stated Assumption
+
+**DO NOT ASK a routing question.** State your routing decision with reasoning.
+
+## Routing Decision Tree
+
+```
+User request
+     │
+     ▼
+Contains bug/fix/broken/error signals?
+     ├─► Yes → bug-planning
+     │
+     ▼
+Describes large multi-feature initiative?
+     ├─► Yes → epic-planning
+     │
+     ▼
+Does this need UX exploration?
+(Multiple valid approaches? User-facing behavior with design choices?)
+     ├─► Yes → feature-planning
+     │
+     ▼
+Is this substantial technical work?
+(Refactoring, infrastructure, migrations, multi-file changes)
+     ├─► Yes → chore-planning
+     │
+     ▼
+Is this a simple, obvious change?
+(Copy, styling, config, minor behavior tweak, one clear approach)
+     └─► Yes → simple-improvement
+```
+
+## Route Definitions
+
+| Route | When to Use | Progression |
+|-------|-------------|-------------|
+| **bug-planning** | Something is broken/not working as expected | Investigation → fix |
+| **epic-planning** | Large initiative spanning multiple features | Break down → plan features |
+| **feature-planning** | New user-facing behavior with UX decisions to make | UX exploration → BDD → speed → stable → production |
+| **chore-planning** | Substantial technical work, clear implementation | speed → stable → production |
+| **simple-improvement** | Obvious change, no UX decisions, small scope | Direct implementation |
+
+## Routing Examples
+
+**→ bug-planning**
+- "The login button doesn't work on mobile"
+- "Getting a crash when I save"
+- "Users are seeing a 500 error"
+
+**→ epic-planning**
+- "We need a full authentication system"
+- "Build out the reporting dashboard"
+- "Plan the v2 API migration"
+
+**→ feature-planning**
+- "Add drag-and-drop reordering for cards"
+- "Implement user notifications"
+- "Build a search feature"
+
+*(Multiple valid UX approaches exist)*
+
+**→ chore-planning**
+- "Refactor the auth module to use the new pattern"
+- "Migrate from Moment.js to date-fns"
+- "Add TypeScript to the utils folder"
+- "Set up CI/CD pipeline"
+
+*(Technical work, obvious approach, but substantial)*
+
+**→ simple-improvement**
+- "Change the button text from 'Submit' to 'Save'"
+- "Make the error message more descriptive"
+- "Add a loading spinner to the save button"
+- "Change the header color to blue"
+- "Add a tooltip to the settings icon"
+
+*(One obvious implementation, no UX exploration needed, just do it)*
+
+## Stating Your Routing Decision
+
+**Bug:**
+```
+Sounds like a bug - [X] isn't working as expected. Let me help you investigate.
+```
+Then invoke bug-planning skill.
+
+**Epic:**
+```
+This is a larger initiative with multiple features. Let's break it down.
+```
+Then invoke epic-planning skill.
+
+**Feature:**
+```
+This adds new user-facing behavior with some design choices to explore. Let me suggest a few approaches.
+```
+Then invoke feature-planning skill.
+
+**Chore:**
+```
+This is technical work with a clear implementation path. Let me help you plan it out.
+```
+Then invoke chore-planning skill.
+
+**Simple improvement:**
+```
+This is a straightforward change. Let me implement it.
+```
+Then invoke simple-improvement skill.
+
+---
+
+**If genuinely ambiguous (rare - should be <20% of cases):**
+```
+I could approach "[brief description]" as:
+- A **simple improvement** - just implement the obvious solution
+- A **feature** - explore a few UX approaches first
+
+Which feels right?
+```
+
+Only ask when you truly cannot decide based on signals and context.
+
+### Step 4: Invoke Target Skill
+
+After stating your routing decision, immediately invoke the appropriate skill using the Skill tool:
+- `bug-planning`
+- `chore-planning`
+- `feature-planning`
+- `epic-planning`
+- `simple-improvement`
+
+**This skill ends after invocation.** The target skill takes over.
+# Stable mode: Verified ambiguous request handling exists

package/skills-templates/simple-improvement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: simple-improvement
-description: Guide implementation of simple improvements to existing functionality. Use when feature-planning routes here for basic enhancements like copy changes, styling tweaks, or minor behavior adjustments. (project)
+description: Guide implementation of simple improvements to existing functionality. Invoked by plan-routing for straightforward changes like copy changes, styling tweaks, or minor behavior adjustments where the implementation is obvious. (project)
 ---
 
 # Simple Improvement Skill