jettypod 4.4.61 → 4.4.62

package/claude-hooks/feature-planning-guardrails.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+/**
+ * Feature-Planning Skill Guardrails Hook
+ *
+ * Infers current workflow step from observable DB state and validates tool calls.
+ * Provides actionable guidance when blocking actions.
+ *
+ * Feature detection priority:
+ * 1. feature_state passed in (for testing)
+ * 2. Active test worktree in cwd
+ * 3. Current in_progress feature from DB
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read hook input from stdin
+let input = '';
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', async () => {
+  try {
+    const hookInput = JSON.parse(input);
+    const { tool_name, tool_input, cwd, feature_state } = hookInput;
+
+    // Use provided feature_state (for testing) or detect from context
+    let state = feature_state;
+    if (!state || !state.id) {
+      state = await detectFeatureState(cwd);
+    }
+
+    // If still no feature state, allow (not in feature-planning context)
+    if (!state || !state.id) {
+      allow();
+      return;
+    }
+
+    // Validate the tool call against feature state
+    const result = validateToolCall(state, tool_name, tool_input, cwd);
+
+    if (result.allowed) {
+      allow();
+    } else {
+      deny(result.message, result.hint);
+    }
+  } catch (err) {
+    // On error, allow (fail open)
+    allow();
+  }
+});
+
+/**
+ * Detect active feature state from context
+ */
+async function detectFeatureState(cwd) {
+  const dbPath = findDatabasePath(cwd);
+  if (!dbPath) return null;
+
+  try {
+    // Try to use better-sqlite3 for sync queries
+    const sqlite3 = require('better-sqlite3');
+    const db = sqlite3(dbPath, { readonly: true });
+
+    // Check for active test worktree first (we're in test-writing phase)
+    const testWorktree = db.prepare(`
+      SELECT wt.work_item_id, wt.worktree_path, wt.status
+      FROM worktrees wt
+      WHERE wt.status = 'active' AND wt.worktree_path LIKE '%tests-%'
+      LIMIT 1
+    `).get();
+
+    if (testWorktree) {
+      // Found active test worktree - get feature state
+      const feature = db.prepare(`
+        SELECT id, phase, scenario_file
+        FROM work_items
+        WHERE id = ?
+      `).get(testWorktree.work_item_id);
+
+      if (feature) {
+        const choreCount = db.prepare(`
+          SELECT COUNT(*) as count FROM work_items WHERE parent_id = ? AND type = 'chore'
+        `).get(feature.id).count;
+
+        db.close();
+        return {
+          id: feature.id,
+          phase: feature.phase || 'discovery',
+          scenarioFile: feature.scenario_file,
+          choreCount,
+          testWorktree: {
+            path: testWorktree.worktree_path,
+            status: testWorktree.status
+          }
+        };
+      }
+    }
+
+    // Check for in_progress feature in discovery phase
+    const discoveryFeature = db.prepare(`
+      SELECT id, phase, scenario_file
+      FROM work_items
+      WHERE type = 'feature' AND phase = 'discovery' AND status = 'in_progress'
+      LIMIT 1
+    `).get();
+
+    if (discoveryFeature) {
+      const choreCount = db.prepare(`
+        SELECT COUNT(*) as count FROM work_items WHERE parent_id = ? AND type = 'chore'
+      `).get(discoveryFeature.id).count;
+
+      db.close();
+      return {
+        id: discoveryFeature.id,
+        phase: 'discovery',
+        scenarioFile: discoveryFeature.scenario_file,
+        choreCount,
+        testWorktree: null
+      };
+    }
+
+    // Check for in_progress chore whose parent feature needs guardrails
+    const activeChore = db.prepare(`
+      SELECT wi.id, wi.parent_id, parent.phase, parent.scenario_file
+      FROM work_items wi
+      JOIN work_items parent ON wi.parent_id = parent.id
+      WHERE wi.type = 'chore' AND wi.status = 'in_progress'
+        AND parent.type = 'feature'
+        AND (parent.phase = 'discovery' OR parent.scenario_file IS NULL)
+      LIMIT 1
+    `).get();
+
+    if (activeChore) {
+      const choreCount = db.prepare(`
+        SELECT COUNT(*) as count FROM work_items WHERE parent_id = ? AND type = 'chore'
+      `).get(activeChore.parent_id).count;
+
+      // Check for test worktree on the feature
+      const featureTestWorktree = db.prepare(`
+        SELECT worktree_path, status FROM worktrees
+        WHERE work_item_id = ? AND worktree_path LIKE '%tests-%' AND status = 'active'
+      `).get(activeChore.parent_id);
+
+      db.close();
+      return {
+        id: activeChore.parent_id,
+        phase: activeChore.phase || 'discovery',
+        scenarioFile: activeChore.scenario_file,
+        choreCount,
+        testWorktree: featureTestWorktree ? {
+          path: featureTestWorktree.worktree_path,
+          status: featureTestWorktree.status
+        } : null
+      };
+    }
+
+    db.close();
+    return null;
+  } catch (err) {
+    // better-sqlite3 not available or error - fall back to CLI
+    return detectFeatureStateCLI(dbPath, cwd);
+  }
+}
+
+/**
+ * Detect feature state using sqlite3 CLI (fallback)
+ */
+function detectFeatureStateCLI(dbPath, cwd) {
+  const { spawnSync } = require('child_process');
+
+  // Check for discovery phase feature
+  const result = spawnSync('sqlite3', [
+    dbPath,
+    `SELECT id, phase, scenario_file FROM work_items WHERE type = 'feature' AND phase = 'discovery' AND status = 'in_progress' LIMIT 1`
+  ], { encoding: 'utf-8' });
+
+  if (result.stdout && result.stdout.trim()) {
+    const [id, phase, scenarioFile] = result.stdout.trim().split('|');
+    return {
+      id: parseInt(id),
+      phase: phase || 'discovery',
+      scenarioFile: scenarioFile || null,
+      choreCount: 0,
+      testWorktree: null
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Find the jettypod database path
+ */
+function findDatabasePath(cwd) {
+  let dir = cwd || process.cwd();
+  while (dir !== path.dirname(dir)) {
+    const dbPath = path.join(dir, '.jettypod', 'work.db');
+    if (fs.existsSync(dbPath)) {
+      return dbPath;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Infer current workflow step from feature state
+ */
+function inferStep(state) {
+  if (!state) return { step: 'unknown', reason: 'Feature not found' };
+
+  // Discovery phase: Steps 1-7
+  if (state.phase === 'discovery') {
+    return { step: 'discovery', reason: 'Phase is discovery' };
+  }
+
+  // Implementation phase: Steps 8+
+  if (state.phase === 'implementation') {
+    // Step 8D: Test worktree active - writing tests
+    if (state.testWorktree?.status === 'active') {
+      return {
+        step: 'test-writing',
+        reason: 'Test worktree active',
+        worktreePath: state.testWorktree.path
+      };
+    }
+
+    // Step 8E+: Tests merged (scenario_file set), ready for chore implementation
+    if (state.scenarioFile) {
+      return { step: 'ready-for-chores', reason: 'Tests merged, implementation can begin' };
+    }
+
+    // Step 8C done: Chores exist, need to create test worktree
+    if (state.choreCount > 0) {
+      return { step: 'pre-test-worktree', reason: 'Chores exist, waiting for test worktree' };
+    }
+
+    return { step: 'implementation-no-chores', reason: 'Implementation phase but no chores' };
+  }
+
+  return { step: 'unknown', reason: `Unknown phase: ${state.phase}` };
+}
+
+/**
+ * Validate a tool call against current feature-planning state
+ */
+function validateToolCall(state, toolName, toolInput, cwd) {
+  const stepInfo = inferStep(state);
+  const featureId = state.id;
+
+  // Fail open for unknown/invalid states - allow action if we can't determine state
+  if (stepInfo.step === 'unknown') {
+    return { allowed: true };
+  }
+
+  // === WRITE/EDIT OPERATIONS ===
+  if (toolName === 'Write' || toolName === 'Edit') {
+    const filePath = toolInput.file_path || '';
+
+    // Check if this is a BDD file write (features/*.feature or features/**/*.steps.js)
+    const isBddFile = /features\/.*\.(feature|steps\.js)$/.test(filePath) ||
+                      filePath.includes('features/') && (filePath.endsWith('.feature') || filePath.includes('.steps.'));
+
+    if (isBddFile) {
+      // During discovery: block all BDD writes
+      if (stepInfo.step === 'discovery') {
+        return {
+          allowed: false,
+          message: 'Cannot write BDD files during discovery phase',
+          hint: `Complete discovery first, then use: jettypod work tests start ${featureId}`
+        };
+      }
+
+      // During test-writing: only allow writes TO the worktree
+      if (stepInfo.step === 'test-writing') {
+        const worktreePath = stepInfo.worktreePath;
+        // Extract the worktree directory name (e.g., ".jettypod-work/tests-100-login")
+        const worktreeDirMatch = worktreePath.match(/\.jettypod-work\/tests-\d+-[^/]+/);
+        const worktreeDir = worktreeDirMatch ? worktreeDirMatch[0] : null;
+
+        // Check if file path is inside the worktree (handles both absolute and relative paths)
+        const isInWorktree = filePath.includes(worktreePath) ||
+                             filePath.startsWith(worktreePath) ||
+                             (worktreeDir && filePath.includes(worktreeDir));
+
+        if (!isInWorktree) {
+          return {
+            allowed: false,
+            message: 'BDD files must be written to the test worktree',
+            hint: `Write to: ${worktreePath}/features/`
+          };
+        }
+        // Writing to worktree is allowed
+        return { allowed: true };
+      }
+
+      // Pre-test-worktree or ready-for-chores: block direct writes
+      if (stepInfo.step === 'pre-test-worktree') {
+        return {
+          allowed: false,
+          message: 'Cannot write BDD files - create test worktree first',
+          hint: `Use: jettypod work tests start ${featureId}`
+        };
+      }
+
+      // Even in ready-for-chores, direct writes to features/ should go through worktree
+      return {
+        allowed: false,
+        message: 'BDD file writes should use a test worktree',
+        hint: `Use: jettypod work tests start ${featureId}`
+      };
+    }
+
+    // During discovery: allow prototype writes, block others
+    if (stepInfo.step === 'discovery') {
+      if (filePath.includes('prototypes/') || filePath.startsWith('prototypes/')) {
+        return { allowed: true };
+      }
+      // Allow other non-BDD writes during discovery (like CLAUDE.md updates)
+      return { allowed: true };
+    }
+  }
+
+  // === BASH COMMANDS ===
+  if (toolName === 'Bash') {
+    const command = toolInput.command || '';
+
+    // Block chore creation during discovery
+    if (/jettypod\s+work\s+create\s+chore/.test(command)) {
+      if (stepInfo.step === 'discovery') {
+        return {
+          allowed: false,
+          message: 'Cannot create chores during discovery phase',
+          hint: 'Get user confirmation on proposed chores first'
+        };
+      }
+    }
+
+    // Block work start in certain states
+    if (/jettypod\s+work\s+start\s+\d+/.test(command)) {
+      // Allow test worktree creation (work tests start)
+      if (/jettypod\s+work\s+tests\s+start/.test(command)) {
+        return { allowed: true };
+      }
+
+      // Block if test worktree is active (need to merge first)
+      if (stepInfo.step === 'test-writing') {
+        return {
+          allowed: false,
+          message: 'Cannot start chore while test worktree is active',
+          hint: `Merge tests first: jettypod work tests merge ${featureId}`
+        };
+      }
+
+      // Block if pre-test-worktree (need to write tests first)
+      if (stepInfo.step === 'pre-test-worktree') {
+        return {
+          allowed: false,
+          message: 'Cannot start chore before tests are written',
+          hint: `Create test worktree first: jettypod work tests start ${featureId}`
+        };
+      }
+    }
+
+    // Allow test worktree commands
+    if (/jettypod\s+work\s+tests\s+(start|merge)/.test(command)) {
+      return { allowed: true };
+    }
+  }
+
+  // Default: allow
+  return { allowed: true };
+}
+
+/**
+ * Allow the action
+ */
+function allow() {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow"
+    }
+  }));
+  process.exit(0);
+}
+
+/**
+ * Deny the action with explanation
+ */
+function deny(message, hint) {
+  const reason = `❌ ${message}\n\n💡 Hint: ${hint}`;
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}

package/claude-hooks/global-guardrails.js

@@ -24,6 +24,27 @@ function debug(category, data) {
   console.error(`[guardrails] ${JSON.stringify(logEntry)}`);
 }
 
+/**
+ * Get the current git ref
+ */
+function getCurrentRef(cwd) {
+  try {
+    const { spawnSync } = require('child_process');
+    const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: cwd || process.cwd(),
+      encoding: 'utf-8',
+      timeout: 5000
+    });
+    if (result.status === 0) {
+      return result.stdout.trim();
+    }
+  } catch (err) {
+    debug('git_ref', { error: err.message });
+  }
+  return null;
+}
+
+
 // Read hook input from stdin
 let input = '';
 process.stdin.on('data', chunk => input += chunk);
@@ -83,12 +104,24 @@ function evaluateRequest(hookInput) {
   return { allowed: true };
 }
 
+/**
+ * Strip heredoc content from command to avoid false positives.
+ * Heredocs contain user text that shouldn't trigger guardrails.
+ */
+function stripHeredocContent(command) {
+  // Match heredoc: <<'DELIM' or <<DELIM or <<"DELIM" ... DELIM
+  return command.replace(/<<-?['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '<<HEREDOC_STRIPPED');
+}
+
 /**
  * Evaluate Bash command against global rules
  */
-function evaluateBashCommand(command, currentBranch, cwd) {
+function evaluateBashCommand(command, inputRef, cwd) {
+  const currentBranch = inputRef || getCurrentRef(cwd);
+  // Strip heredoc content to avoid false positives on user-provided text
+  const strippedCommand = stripHeredocContent(command);
   // BLOCKED: Force push
-  if (/git\s+push\s+.*--force/.test(command) || /git\s+push\s+-f\b/.test(command)) {
+  if (/git\s+push\s+.*--force/.test(strippedCommand) || /git\s+push\s+-f\b/.test(strippedCommand)) {
     return {
       allowed: false,
       message: 'Force push is blocked',
@@ -96,8 +129,17 @@ function evaluateBashCommand(command, currentBranch, cwd) {
     };
   }
 
+  // BLOCKED: Hard reset (destructive)
+  if (/git\s+reset\s+--hard\b/.test(strippedCommand)) {
+    return {
+      allowed: false,
+      message: 'Hard reset is blocked',
+      hint: 'Hard reset destroys uncommitted work. Use git stash or git reset --soft instead.'
+    };
+  }
+
   // BLOCKED: Direct commit to main
-  if (/git\s+commit\b/.test(command) && currentBranch === 'main') {
+  if (/git\s+commit\b/.test(strippedCommand) && currentBranch === 'main') {
     return {
       allowed: false,
       message: 'Direct commits to main are blocked',
@@ -106,7 +148,7 @@ function evaluateBashCommand(command, currentBranch, cwd) {
   }
 
   // BLOCKED: Manual worktree creation
-  if (/git\s+worktree\s+add\b/.test(command)) {
+  if (/git\s+worktree\s+add\b/.test(strippedCommand)) {
     return {
       allowed: false,
       message: 'Manual worktree creation is blocked',
@@ -115,7 +157,7 @@ function evaluateBashCommand(command, currentBranch, cwd) {
   }
 
   // BLOCKED: Manual branch creation
-  if (/git\s+checkout\s+-b\b/.test(command) || /git\s+branch\s+(?!-d|-D)/.test(command)) {
+  if (/git\s+checkout\s+-b\b/.test(strippedCommand) || /git\s+branch\s+(?!-d|-D)/.test(strippedCommand)) {
     return {
       allowed: false,
       message: 'Manual branch creation is blocked',
@@ -124,7 +166,7 @@ function evaluateBashCommand(command, currentBranch, cwd) {
   }
 
   // BLOCKED: Direct SQL mutation to work.db
-  if (/sqlite3\s+.*work\.db/.test(command)) {
+  if (/sqlite3\s+.*work\.db/.test(strippedCommand)) {
     const sqlCommand = command.toLowerCase();
     // Allow SELECT, block mutations
     if (/\b(update|insert|delete|drop|alter|create)\b/i.test(sqlCommand)) {
@@ -136,25 +178,14 @@ function evaluateBashCommand(command, currentBranch, cwd) {
     }
   }
 
-  // BLOCKED: Merge from inside worktree (causes CWD corruption)
-  // Matches: jettypod work merge, jettypod work tests merge
-  if (/jettypod\s+work\s+(tests\s+)?merge/.test(command)) {
-    if (cwd && /\.jettypod-work\//.test(cwd)) {
-      return {
-        allowed: false,
-        message: 'Cannot merge from inside a worktree - your shell CWD would be deleted, corrupting the session.',
-        hint: 'First run: cd <main-repo-path>\nThen retry the merge command.'
-      };
-    }
-  }
 
   // ALLOWED: Git read-only commands
-  if (/git\s+(status|log|diff|show|branch\s*$|remote|fetch)\b/.test(command)) {
+  if (/git\s+(status|log|diff|show|branch\s*$|remote|fetch)\b/.test(strippedCommand)) {
     return { allowed: true };
   }
 
   // ALLOWED: Jettypod read-only commands
-  if (/jettypod\s+(backlog|status|work\s+status|impact)\b/.test(command)) {
+  if (/jettypod\s+(backlog|status|work\s+status|impact)\b/.test(strippedCommand)) {
     return { allowed: true };
   }
 

package/lib/work-commands/index.js

@@ -1171,19 +1171,12 @@ async function mergeWork(options = {}) {
     }
   }
 
-  // CRITICAL: Refuse to run from inside a worktree
-  // Running merge from inside the worktree that will be deleted poisons the shell session
+  // Auto-chdir to main repo if running from inside a worktree
   const cwd = process.cwd();
   if (cwd.includes('.jettypod-work')) {
     const mainRepo = getGitRoot();
-    console.error('❌ Cannot merge from inside a worktree.');
-    console.error('');
-    console.error('   The merge will delete this worktree, breaking your shell session.');
-    console.error('');
-    console.error('   Run from the main repository instead:');
-    console.error(`   cd ${mainRepo}`);
-    console.error('   jettypod work merge');
-    return Promise.reject(new Error('Cannot merge from inside a worktree'));
+    console.log('📂 Changing to main repository for merge...');
+    process.chdir(mainRepo);
   }
 
   // Get current work - either from explicit ID or branch detection
@@ -1735,18 +1728,12 @@ async function testsMerge(featureId) {
     return Promise.reject(new Error('Invalid feature ID'));
   }
 
-  // CRITICAL: Refuse to run from inside a worktree
+  // Auto-chdir to main repo if running from inside a worktree
   const cwd = process.cwd();
   if (cwd.includes('.jettypod-work')) {
     const mainRepo = getGitRoot();
-    console.error('❌ Cannot merge from inside a worktree.');
-    console.error('');
-    console.error('   The merge will delete this worktree, breaking your shell session.');
-    console.error('');
-    console.error('   Run from the main repository instead:');
-    console.error(`   cd ${mainRepo}`);
-    console.error(`   jettypod work tests merge ${featureId}`);
-    return Promise.reject(new Error('Cannot merge from inside a worktree'));
+    console.log('📂 Changing to main repository for merge...');
+    process.chdir(mainRepo);
   }
 
   const db = getDb();

package/package.json

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