jettypod 4.4.52 → 4.4.53

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

@@ -0,0 +1,120 @@
+# 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?

package/package.json

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

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

@@ -45,6 +45,22 @@ When this skill is activated, you are executing a standalone chore. The chore-pl
 
 ---
 
+## 🚨 SHELL CWD RECOVERY
+
+**If ALL bash commands start failing with "Error: Exit code 1" and no output:**
+
+Your shell's working directory was likely inside a worktree that was deleted. The CWD no longer exists.
+
+**Recovery steps:**
+1. Get the main repo path from your session context (look for the project path in earlier messages)
+2. Run: `cd <main-repo-path>`
+3. Verify: `pwd && ls .jettypod`
+4. Resume your work
+
+**Why this happens:** When a worktree is merged, it gets deleted. If your shell was inside that worktree directory, all subsequent commands fail because the CWD doesn't exist.
+
+---
+
 ## Implementation Steps
 
 ### Step 1: Receive and Display Context
@@ -355,12 +371,20 @@ Go back to Step 5 to fix issues.
 git add .
 git commit -m "chore: [brief description]"
 git push
+```
+
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
+The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
 
-# Switch to main repo before merging (merge cannot run from inside worktree)
-cd $(git rev-parse --show-toplevel)/..
+```bash
+# CRITICAL: cd to main repo AND merge in SAME command
+cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [chore-id]
+```
 
-# Merge to main (auto-marks chore done)
-jettypod work merge [chore-id]
+```bash
+# MANDATORY: Verify shell is in main repo
+pwd && ls .jettypod
 ```
 
 **Display:**

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

@@ -48,6 +48,27 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ---
 
+## 🚨 SHELL CWD RECOVERY
+
+**If ALL bash commands start failing with "Error: Exit code 1" and no output:**
+
+Your shell's working directory was likely inside a worktree that was deleted. The CWD no longer exists.
+
+**Recovery steps:**
+1. Get the main repo path from your session context (look for the project path in earlier messages)
+2. Run: `cd <main-repo-path>`
+3. Verify: `pwd && ls .jettypod`
+4. Resume your work
+
+**Example:**
+```bash
+cd /Users/erikspangenberg/personal-assistant && pwd
+```
+
+**Why this happens:** When a worktree is merged, it gets deleted. If your shell was inside that worktree directory, all subsequent commands fail because the CWD doesn't exist.
+
+---
+
 ## 🛑 PRE-FLIGHT VALIDATION (REQUIRED)
 
 **Before proceeding with ANY implementation, you MUST validate the worktree exists.**
@@ -592,16 +613,23 @@ More speed mode chores remain. Starting next chore:
 
 **Merge and start next:**
 
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
+The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of what was implemented]"
+```
 
-# Return to main repo and merge (cannot merge from inside worktree)
-cd $(git rev-parse --show-toplevel)/..  # Exit worktree to main repo
-jettypod work merge [current-chore-id]
+```bash
+# CRITICAL: cd to main repo AND merge in SAME command
+cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
+```
 
-# Start next speed chore
-jettypod work start [next-chore-id]
+```bash
+# Verify shell is valid, then start next chore
+pwd && jettypod work start [next-chore-id]
 ```
 
 The speed-mode skill will automatically re-invoke for the next chore.
@@ -640,15 +668,28 @@ npx cucumber-js <scenario-file-path> --name "User can reach" --format progress
 
 #### Step 7B: Merge Final Speed Chore
 
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
+The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of what was implemented]"
+```
 
-# Return to main repo and merge (cannot merge from inside worktree)
-cd $(git rev-parse --show-toplevel)/..  # Exit worktree to main repo
-jettypod work merge [current-chore-id] --with-transition
+```bash
+# CRITICAL: cd to main repo AND merge in SAME command
+# Using $(git rev-parse --show-toplevel)/.. exits worktree to main repo
+cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id] --with-transition
 ```
 
+```bash
+# MANDATORY: Verify shell is in main repo (run immediately after merge)
+pwd && ls .jettypod
+```
+
+**If you see "No such file or directory" errors:** Your shell CWD was corrupted. Get the main repo path from your session context and run `cd <main-repo-path>`.
+
 After merge, you are on main branch. Ready to generate stable mode scenarios.
 
 #### Step 7C: Generate and Propose Stable Mode Chores
@@ -708,19 +749,35 @@ Scenario: [Edge case title]
 
 **6. Commit and merge the test worktree:**
 
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
+The merge will delete the test worktree. If your shell is inside that worktree, ALL subsequent commands will fail. You MUST:
+1. Chain the cd and merge in a SINGLE bash command
+2. Verify your shell is in main repo AFTER merge
+
 ```bash
-# Commit in the test worktree
-cd <worktree-path>
-git add features/
-git commit -m "test: Add stable mode BDD scenarios and step definitions
+# First: Commit in the test worktree (separate command is OK here)
+cd <worktree-path> && git add features/ && git commit -m "test: Add stable mode BDD scenarios and step definitions
 
 Added error handling and edge case scenarios for stable mode.
 - [N] new stable mode scenarios
 - Step definitions for validation and error handling"
+```
+
+```bash
+# 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>
+```
 
-# Return to main repo and merge
+```bash
+# MANDATORY: Verify shell is in main repo (run this immediately after merge)
+pwd && ls .jettypod
+```
+
+**If you see "No such file or directory" errors:** Your shell CWD was corrupted. Run:
+```bash
 cd <main-repo-path>
-jettypod work tests merge <feature-id>
 ```
 
 **7. Present proposal to user:**

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

@@ -52,6 +52,22 @@ When this skill is activated, you are helping implement a stable mode chore to a
 
 ---
 
+## 🚨 SHELL CWD RECOVERY
+
+**If ALL bash commands start failing with "Error: Exit code 1" and no output:**
+
+Your shell's working directory was likely inside a worktree that was deleted. The CWD no longer exists.
+
+**Recovery steps:**
+1. Get the main repo path from your session context (look for the project path in earlier messages)
+2. Run: `cd <main-repo-path>`
+3. Verify: `pwd && ls .jettypod`
+4. Resume your work
+
+**Why this happens:** When a worktree is merged, it gets deleted. If your shell was inside that worktree directory, all subsequent commands fail because the CWD doesn't exist.
+
+---
+
 ## 🛑 PRE-FLIGHT VALIDATION (REQUIRED)
 
 **Before proceeding with ANY implementation, you MUST validate the worktree exists.**
@@ -556,16 +572,23 @@ More stable mode chores remain. Starting next chore:
 
 **Merge and start next:**
 
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
+The merge will delete the worktree. Chain commands to ensure shell is in main repo BEFORE deletion.
+
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of error handling added]"
+```
 
-# Return to main repo and merge (cannot merge from inside worktree)
-cd $(git rev-parse --show-toplevel)/..  # Exit worktree to main repo
-jettypod work merge [current-chore-id]
+```bash
+# CRITICAL: cd to main repo AND merge in SAME command
+cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
+```
 
-# Start next stable chore
-jettypod work start [next-chore-id]
+```bash
+# Verify shell is valid, then start next chore
+pwd && jettypod work start [next-chore-id]
 ```
 
 The stable-mode skill will automatically re-invoke for the next chore.
@@ -584,10 +607,20 @@ If the query returns no remaining chores, proceed to Step 7.
 
 **First, merge the final stable chore:**
 
+**🚨 CRITICAL: Shell CWD Corruption Prevention**
+
 ```bash
 git add . && git commit -m "feat: [brief description of error handling added]"
-cd $(git rev-parse --show-toplevel)/..  # Exit worktree to main repo
-jettypod work merge [current-chore-id]
+```
+
+```bash
+# CRITICAL: cd to main repo AND merge in SAME command
+cd $(git rev-parse --show-toplevel)/.. && jettypod work merge [current-chore-id]
+```
+
+```bash
+# MANDATORY: Verify shell is in main repo
+pwd && ls .jettypod
 ```
 
 **Then check project state:**