jettypod 4.4.53 → 4.4.55

package/claude-hooks/global-guardrails.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Global Guardrails Hook
+ *
+ * Enforces actions that are ALWAYS allowed and ALWAYS blocked regardless of
+ * skill or context. Runs before any contextual/skill-specific validators.
+ *
+ * Claude Code PreToolUse Hook
+ */
+
+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', () => {
+  try {
+    const hookInput = JSON.parse(input);
+    const result = evaluateRequest(hookInput);
+
+    if (result.allowed) {
+      allow();
+    } else {
+      deny(result.message, result.hint);
+    }
+  } catch (err) {
+    // On parse error, allow (fail open)
+    console.error('Hook error:', err.message);
+    allow();
+  }
+});
+
+/**
+ * Evaluate the request and return allow/deny decision
+ */
+function evaluateRequest(hookInput) {
+  const { tool_name, tool_input, cwd, active_worktree_path, current_branch } = hookInput;
+
+  // ALWAYS ALLOW: Read operations
+  if (tool_name === 'Read' || tool_name === 'Glob' || tool_name === 'Grep') {
+    return { allowed: true };
+  }
+
+  // Handle Bash commands
+  if (tool_name === 'Bash') {
+    return evaluateBashCommand(tool_input.command || '', current_branch, cwd);
+  }
+
+  // Handle Write/Edit operations
+  if (tool_name === 'Write' || tool_name === 'Edit') {
+    return evaluateWriteOperation(tool_input.file_path || '', active_worktree_path, cwd);
+  }
+
+  // Default: allow unknown tools
+  return { allowed: true };
+}
+
+/**
+ * Evaluate Bash command against global rules
+ */
+function evaluateBashCommand(command, currentBranch, cwd) {
+  // BLOCKED: Force push
+  if (/git\s+push\s+.*--force/.test(command) || /git\s+push\s+-f\b/.test(command)) {
+    return {
+      allowed: false,
+      message: 'Force push is blocked',
+      hint: 'Force pushing can destroy history. Use regular push or create a PR.'
+    };
+  }
+
+  // BLOCKED: Direct commit to main
+  if (/git\s+commit\b/.test(command) && currentBranch === 'main') {
+    return {
+      allowed: false,
+      message: 'Direct commits to main are blocked',
+      hint: 'Use jettypod work start to create a feature branch first.'
+    };
+  }
+
+  // BLOCKED: Manual worktree creation
+  if (/git\s+worktree\s+add\b/.test(command)) {
+    return {
+      allowed: false,
+      message: 'Manual worktree creation is blocked',
+      hint: 'Use jettypod work start to create worktrees.'
+    };
+  }
+
+  // BLOCKED: Manual branch creation
+  if (/git\s+checkout\s+-b\b/.test(command) || /git\s+branch\s+(?!-d|-D)/.test(command)) {
+    return {
+      allowed: false,
+      message: 'Manual branch creation is blocked',
+      hint: 'Use jettypod work start to create branches.'
+    };
+  }
+
+  // BLOCKED: Direct SQL mutation to work.db
+  if (/sqlite3\s+.*work\.db/.test(command)) {
+    const sqlCommand = command.toLowerCase();
+    // Allow SELECT, block mutations
+    if (/\b(update|insert|delete|drop|alter|create)\b/i.test(sqlCommand)) {
+      return {
+        allowed: false,
+        message: 'Direct database mutations are blocked',
+        hint: 'Use jettypod CLI commands to modify work items.'
+      };
+    }
+  }
+
+  // BLOCKED: Merge from inside worktree (causes CWD corruption)
+  if (/jettypod\s+(work|tests)\s+merge/.test(command)) {
+    if (cwd && /\.jettypod-work\//.test(cwd)) {
+      return {
+        allowed: false,
+        message: 'Cannot merge from inside a worktree. CWD would be deleted.',
+        hint: 'Run: cd /Users/erikspangenberg/jettypod-source && jettypod work merge <id>'
+      };
+    }
+  }
+
+  // ALLOWED: Git read-only commands
+  if (/git\s+(status|log|diff|show|branch\s*$|remote|fetch)\b/.test(command)) {
+    return { allowed: true };
+  }
+
+  // ALLOWED: Jettypod read-only commands
+  if (/jettypod\s+(backlog|status|work\s+status|impact)\b/.test(command)) {
+    return { allowed: true };
+  }
+
+  // Default: allow other commands
+  return { allowed: true };
+}
+
+/**
+ * Find the jettypod database path
+ * @param {string} cwd - Starting directory
+ * @returns {string|null} Database path or null
+ */
+function findDatabasePath(cwd) {
+  let dir = 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;
+}
+
+/**
+ * Get the active worktree path from database
+ * @param {string} cwd - Current working directory
+ * @returns {string|null} Active worktree path or null
+ */
+function getActiveWorktreePathFromDB(cwd) {
+  const dbPath = findDatabasePath(cwd);
+  if (!dbPath) {
+    return null;
+  }
+
+  try {
+    // Try better-sqlite3 first
+    const sqlite3 = require('better-sqlite3');
+    const db = sqlite3(dbPath, { readonly: true });
+    const row = db.prepare(
+      `SELECT worktree_path FROM worktrees WHERE status = 'active' LIMIT 1`
+    ).get();
+    db.close();
+    return row ? row.worktree_path : null;
+  } catch (err) {
+    // Fall back to CLI
+    const { spawnSync } = require('child_process');
+    const result = spawnSync('sqlite3', [
+      dbPath,
+      `SELECT worktree_path FROM worktrees WHERE status = 'active' LIMIT 1`
+    ], { encoding: 'utf-8' });
+
+    if (result.error || result.status !== 0) {
+      return null;
+    }
+    return result.stdout.trim() || null;
+  }
+}
+
+/**
+ * Evaluate Write/Edit operation against global rules
+ */
+function evaluateWriteOperation(filePath, inputWorktreePath, cwd) {
+  // Query database for active worktree, fall back to input if provided
+  const activeWorktreePath = getActiveWorktreePathFromDB(cwd) || inputWorktreePath;
+
+  // Normalize paths
+  const normalizedPath = path.resolve(cwd || '.', filePath);
+  const normalizedWorktree = activeWorktreePath ? path.resolve(cwd || '.', activeWorktreePath) : null;
+
+  // BLOCKED: Protected files (skills, hooks)
+  const protectedPatterns = [
+    /\.claude\/skills\//i,
+    /claude-hooks\//i,
+    /\.jettypod\/hooks\//i
+  ];
+
+  for (const pattern of protectedPatterns) {
+    if (pattern.test(normalizedPath) || pattern.test(filePath)) {
+      return {
+        allowed: false,
+        message: 'Protected file - cannot modify',
+        hint: 'Skill and hook files are protected. Modify them through proper channels.'
+      };
+    }
+  }
+
+  // Check if path is in a worktree
+  const isInWorktree = /\.jettypod-work\//.test(filePath) || /\.jettypod-work\//.test(normalizedPath);
+
+  if (isInWorktree) {
+    // If we have an active worktree, check if this write is to it
+    if (activeWorktreePath) {
+      // SECURITY: Only use normalized path comparison to prevent traversal attacks
+      // The filePath.includes() check was vulnerable to "../" escapes
+      const isActiveWorktree = normalizedPath.startsWith(normalizedWorktree + path.sep) ||
+                               normalizedPath === normalizedWorktree;
+
+      if (isActiveWorktree) {
+        return { allowed: true };
+      } else {
+        return {
+          allowed: false,
+          message: 'Not your active worktree',
+          hint: 'You can only write to your currently active worktree.'
+        };
+      }
+    }
+    // No active worktree tracked but path looks like worktree - block
+    return {
+      allowed: false,
+      message: 'Not your active worktree',
+      hint: 'You can only write to your currently active worktree.'
+    };
+  }
+
+  // BLOCKED: Write to main repo (not in worktree)
+  return {
+    allowed: false,
+    message: 'Cannot write to main repository',
+    hint: 'Use jettypod work start to create a worktree first.'
+  };
+}
+
+/**
+ * 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 || 'Check your action.'}`;
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}

package/jettypod.js

@@ -785,6 +785,14 @@ async function initializeProject() {
     fs.chmodSync(enforceHookDest, 0o755);
   }
 
+  // Install global-guardrails hook
+  const guardrailsHookSource = path.join(__dirname, 'claude-hooks', 'global-guardrails.js');
+  const guardrailsHookDest = path.join('.jettypod', 'hooks', 'global-guardrails.js');
+  if (fs.existsSync(guardrailsHookSource)) {
+    fs.copyFileSync(guardrailsHookSource, guardrailsHookDest);
+    fs.chmodSync(guardrailsHookDest, 0o755);
+  }
+
   // Create Claude Code settings
   if (!fs.existsSync('.claude')) {
     fs.mkdirSync('.claude', { recursive: true });
@@ -800,15 +808,24 @@ async function initializeProject() {
         PreToolUse: [
           {
             matcher: 'Edit',
-            hooks: [{ type: 'command', command: '.jettypod/hooks/protect-claude-md.js' }]
+            hooks: [
+              { type: 'command', command: '.jettypod/hooks/global-guardrails.js' },
+              { type: 'command', command: '.jettypod/hooks/protect-claude-md.js' }
+            ]
           },
           {
             matcher: 'Write',
-            hooks: [{ type: 'command', command: '.jettypod/hooks/protect-claude-md.js' }]
+            hooks: [
+              { type: 'command', command: '.jettypod/hooks/global-guardrails.js' },
+              { type: 'command', command: '.jettypod/hooks/protect-claude-md.js' }
+            ]
           },
           {
             matcher: 'Bash',
-            hooks: [{ type: 'command', command: '.jettypod/hooks/enforce-skill-activation.js' }]
+            hooks: [
+              { type: 'command', command: '.jettypod/hooks/global-guardrails.js' },
+              { type: 'command', command: '.jettypod/hooks/enforce-skill-activation.js' }
+            ]
           }
         ]
       }

package/package.json

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

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

@@ -19,7 +19,7 @@ When this skill is activated, you are helping discover the best approach for a f
 |---------|----------|------|-------|
 | `work implement <feature-id>` | Transition feature to implementation phase | After chores created (Step 8C) | Feature Planning |
 | `work tests start <feature-id>` | Create worktree for test authoring | After transition (Step 8D) | Feature Planning |
-| `work tests merge <feature-id>` | Merge tests to main, cleanup worktree | After tests validated (Step 8D) | Feature Planning |
+| `cd <main-repo> && work tests merge <feature-id>` | Merge tests to main, cleanup worktree | After tests validated (Step 8D) | Feature Planning |
 | `work start <chore-id>` | Start implementing a specific chore | After tests merged (Step 8E) | Speed Mode |
 
 **CRITICAL:** All commands are run by **Claude**, not the user. The distinction is:
@@ -653,7 +653,8 @@ Write your BDD files to:
   <worktree>/features/email-login.feature
   <worktree>/features/step_definitions/email-login.steps.js
 
-When done, run: jettypod work tests merge 42
+When done, cd to main repo and merge:
+  cd /path/to/main/repo && jettypod work tests merge 42
 ```
 
 **🛑 STOP AND CHECK:** Verify worktree was created successfully. If you see an error, investigate before continuing.
@@ -735,10 +736,16 @@ sqlite3 .jettypod/work.db "UPDATE work_items SET scenario_file = 'features/${FEA
 
 **Sub-step 5: Merge tests to main**
 
+**⚠️ CRITICAL: The merge will delete the worktree.** Your shell is currently inside it. Chain commands to ensure shell is in main repo BEFORE deletion:
+
 ```bash
-jettypod work tests merge ${FEATURE_ID}
+# CRITICAL: cd to main repo AND merge in SAME command
+# This ensures shell is in main repo BEFORE worktree deletion
+cd <main-repo-path> && jettypod work tests merge ${FEATURE_ID}
 ```
 
+If you run the merge while your shell is in the worktree, subsequent commands will fail with "No such file or directory".
+
 This will:
 - Commit changes in the worktree
 - Merge to main
@@ -913,6 +920,6 @@ Before completing feature planning, ensure:
 - [ ] **Test worktree created** with `work tests start` (Step 8D)
 - [ ] **BDD files written** in worktree (Step 8D)
 - [ ] **BDD infrastructure validated** with dry-run (Step 8D)
-- [ ] **Tests merged to main** with `work tests merge` (Step 8D)
+- [ ] **Tests merged to main** with `cd <main-repo> && work tests merge` (Step 8D)
 - [ ] First chore started with `work start [chore-id]` (Step 8E)
 - [ ] **Speed-mode skill invoked using Skill tool** (Step 8E)

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

@@ -827,7 +827,7 @@ Repeat for each confirmed chore. **Do NOT use `--mode` flag** - chores inherit m
 **3. Release merge lock:**
 
 ```bash
-jettypod work merge --release-lock
+cd <main-repo> && jettypod work merge --release-lock
 ```
 
 **🔄 WORKFLOW COMPLETE: Speed mode finished**
@@ -926,12 +926,12 @@ Before ending speed-mode skill, ensure:
 
 ## Command Reference
 
-**Complete chores (run from main repo, not worktree):**
+**Complete chores (CRITICAL: cd to main repo BEFORE merge - worktree will be deleted):**
 ```bash
-jettypod work merge <id>         # Merge chore by ID (recommended)
-jettypod work merge              # Merge current chore (requires being on feature branch)
-jettypod work merge --with-transition  # Hold lock for transition phase
-jettypod work merge --release-lock     # Release held lock
+cd <main-repo> && jettypod work merge <id>   # Merge chore by ID (recommended)
+cd <main-repo> && jettypod work merge        # Merge current chore
+cd <main-repo> && jettypod work merge --with-transition  # Hold lock for transition
+cd <main-repo> && jettypod work merge --release-lock     # Release held lock
 ```
 
 **Start chores:**
@@ -942,7 +942,8 @@ jettypod work start <chore-id>   # Create worktree and start chore
 **Create test worktree (for writing BDD scenarios):**
 ```bash
 jettypod work tests <feature-id>        # Create worktree for writing tests
-jettypod work tests merge <feature-id>  # Merge tests back to main
+# CRITICAL: cd to main repo BEFORE merge (worktree will be deleted)
+cd <main-repo> && jettypod work tests merge <feature-id>
 ```
 
 **Set feature mode (BEFORE creating chores):**

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

@@ -743,10 +743,10 @@ Before ending stable-mode skill, ensure:
 
 ## Command Reference
 
-**Complete chores (run from main repo, not worktree):**
+**Complete chores (CRITICAL: cd to main repo BEFORE merge - worktree will be deleted):**
 ```bash
-jettypod work merge <id>         # Merge chore by ID (recommended)
-jettypod work merge              # Merge current chore (requires being on feature branch)
+cd <main-repo> && jettypod work merge <id>   # Merge chore by ID (recommended)
+cd <main-repo> && jettypod work merge        # Merge current chore
 ```
 
 **Start chores:**
@@ -776,7 +776,7 @@ jettypod work set-mode <feature-id> production  # Set feature to production mode
 - Parallel worktrees branch from main independently
 
 **Process:**
-1. Complete chore → `jettypod work merge`
+1. Complete chore → `cd <main-repo> && jettypod work merge` (CRITICAL: cd first!)
 2. Start next chore → `jettypod work start <next-id>`
 3. Repeat
 

package/docs/command-whitelist-feature-planning.md

@@ -1,120 +0,0 @@
-# Command Whitelist Matrix: Feature Planning
-
-This document defines what commands/actions are allowed at each step of the feature-planning skill. Hooks should enforce these rules and redirect the agent when violations occur.
-
-## Matrix
-
-| Step | Description | Allowed Commands | Blocked Commands | Redirect Message |
-|------|-------------|------------------|------------------|------------------|
-| **1** | Get feature context | `work show`, `workflow start`, `backlog` | Any file writes, `work create`, `work start`, `work implement` | "You're in Step 1 - get context first with `work show <id>`" |
-| **2** | Check epic decisions | `decisions --epic=X` | File writes, `work create`, `work start` | "Check for epic decisions before suggesting approaches" |
-| **3** | Suggest 3 UX approaches | Read-only (Read, Glob, Grep) | File writes, `work create`, `work start` | "Wait for user to pick an approach - no changes yet" |
-| **4** | Optional prototyping | Write to `prototypes/` only | Writes to `features/`, `src/`, `work create`, `work start` | "Prototypes go in prototypes/ - no production code yet" |
-| **5** | Choose winner | `workflow checkpoint` | File writes, `work create`, `work start` | "Wait for user to confirm winner" |
-| **6A** | Define integration contract | Read-only | File writes | "Define how users reach the feature first" |
-| **6B** | Propose BDD scenarios | Read-only, `workflow checkpoint` | **Write to `features/`**, `work create`, `work start` | "**BDD files are written in Step 8D in a worktree, not now**" |
-| **7** | Propose chores | Read-only (analyze codebase) | `work create`, `work start`, file writes | "Propose chores to user first - don't create yet" |
-| **8B** | Create chores | `work create chore` | `work start`, writes to `features/` | "Create all chores before transitioning" |
-| **8C** | Execute transition | `work implement`, `workflow checkpoint` | `work start` | "Transition the feature before starting chores" |
-| **8D** | Write tests in worktree | `work tests start`, `work tests merge`, Write to **worktree path only**, `cucumber-js --dry-run` | Write to main repo paths, `work start` | "Write tests in the worktree, not main repo" |
-| **8E** | Start first chore | `work start`, `workflow complete` | - | "Start the chore, then invoke speed-mode" |
-
-## Key Enforcement Points
-
-### 0. Allowlist-First Enforcement
-
-**Principle:** Each step defines what IS allowed, not what's blocked. Anything not explicitly allowed is rejected.
-
-This is simpler to reason about, safer by default, and guides the agent toward correct behavior rather than away from incorrect behavior.
-
-**Enforcement logic:**
-1. Check if command/action is in the step's allowlist → allow
-2. Check if it matches a global bypass pattern (see below) → block with specific message
-3. Otherwise → block with generic "not allowed at this step" + list what IS allowed
-
-### 1. Common Bypass Patterns (Global Blocks)
-
-Agents sometimes try shortcuts that bypass CLI commands entirely. Catch the common ones:
-
-- **Direct SQL:** `sqlite3` commands, raw SQL (`INSERT`, `UPDATE`, `DELETE`) in bash
-- **Inline Node execution:** `node -e` with database operations
-
-**Redirect Message:** "Use CLI commands to modify work items, not direct SQL. Run `jettypod help` to see available commands."
-
-We don't need to catch every possible bypass - these cover ~95% of cases. The redirect message does the real work.
-
-### 2. Step 6B is the Critical Trap
-
-The agent often tries to write `.feature` files in Step 6B after proposing scenarios. This must be blocked.
-
-**Rule:** Block all writes to `features/**` until Step 8D, and only then to the worktree path.
-
-### 3. Worktree Path Validation
-
-In Step 8D, writes are only allowed to the active worktree path (`.jettypod-work/tests-*`), not anywhere in the main repo.
-
-**Rule:** If a write targets a path that doesn't start with the active worktree path, block it.
-
-### 4. Order Enforcement
-
-The following commands have strict ordering:
-1. `work create chore` - Only in Step 8B (after user confirms chores)
-2. `work implement` - Only in Step 8C (after chores created)
-3. `work tests start` - Only in Step 8D (after implement)
-4. `work tests merge` - Only in Step 8D (after tests written)
-5. `work start` - Only in Step 8E (after tests merged)
-
-**Rule:** Each command should validate the previous step completed.
-
-## Context Required for Enforcement
-
-Hooks need access to:
-- **Current skill:** `feature-planning`
-- **Current step:** 1-8E (from workflow checkpoint)
-- **Feature ID:** The work item being planned
-- **Worktree path:** For Step 8D validation (from `worktrees` table)
-
-## Example Hook Logic
-
-```javascript
-// Pseudocode for pre-command hook
-function validateCommand(command, context) {
-  const { skill, step, featureId, worktreePath } = context;
-
-  if (skill !== 'feature-planning') return { allowed: true };
-
-  // Step 6B: Block writes to features/
-  if (step === '6B' && command.type === 'write' && command.path.includes('features/')) {
-    return {
-      allowed: false,
-      message: "BDD files are written in Step 8D in a worktree, not now. You're proposing scenarios - wait for user confirmation."
-    };
-  }
-
-  // Step 8D: Only allow writes to worktree
-  if (step === '8D' && command.type === 'write') {
-    if (!command.path.startsWith(worktreePath)) {
-      return {
-        allowed: false,
-        message: `Write tests in the worktree (${worktreePath}), not the main repo.`
-      };
-    }
-  }
-
-  // Block work start until Step 8E
-  if (command.name === 'work start' && step !== '8E') {
-    return {
-      allowed: false,
-      message: `Cannot start chores yet. Complete steps through 8D first (tests must be merged to main).`
-    };
-  }
-
-  return { allowed: true };
-}
-```
-
-## Open Questions
-
-1. **Step granularity:** Should we track sub-steps like 8B, 8C, 8D, 8E separately, or group them as "Step 8"?
-2. **Read operations:** Should we restrict what files can be read at certain steps, or only writes?
-3. **Skill transitions:** How do we handle the handoff to speed-mode at Step 8E?