jettypod 4.4.94 → 4.4.96

package/jettypod.js

@@ -289,6 +289,8 @@ jettypod work merge                   # Merges worktree back to main
 jettypod work cleanup <id>            # Cleanup worktree after merge
 jettypod work tests <feature-id>      # Create test worktree for BDD
 jettypod work tests merge <id>        # Merge tests to main
+jettypod work prototype start <id> <approach>  # Create prototype worktree
+jettypod work prototype merge <id>    # Merge prototype to main
 jettypod work status <id> cancelled
 jettypod backlog
 jettypod impact <file>                # Show tests/features affected
@@ -1506,6 +1508,69 @@ switch (command) {
           process.exit(1);
         }
       }
+    } else if (subcommand === 'prototype') {
+      // Handle: work prototype start <feature-id> <approach-name> OR work prototype merge <feature-id>
+      const workCommands = require('./lib/work-commands/index.js');
+
+      if (args[1] === 'merge') {
+        // work prototype merge <feature-id>
+        const featureId = parseInt(args[2]);
+        if (!featureId) {
+          console.log('Usage: jettypod work prototype merge <feature-id>');
+          console.log('');
+          console.log('Merges a prototype worktree back to main and cleans up.');
+          console.log('');
+          console.log('This command:');
+          console.log('  1. Verifies all changes are committed');
+          console.log('  2. Merges the prototype branch to main');
+          console.log('  3. Pushes to remote');
+          console.log('  4. Removes the worktree');
+          console.log('  5. Deletes the prototype branch');
+          process.exit(1);
+        }
+        try {
+          await workCommands.prototypeMerge(featureId);
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+      } else if (args[1] === 'start') {
+        // work prototype start <feature-id> <approach-name>
+        const featureId = parseInt(args[2]);
+        const approachName = args[3];
+        if (!featureId || !approachName) {
+          console.log('Usage: jettypod work prototype start <feature-id> <approach-name>');
+          console.log('');
+          console.log('Creates a worktree for building prototypes for a feature.');
+          console.log('');
+          console.log('Examples:');
+          console.log('  jettypod work prototype start 42 simple-form');
+          console.log('  jettypod work prototype start 42 wizard-flow');
+          console.log('');
+          console.log('Prototypes are written in /prototypes/feature-<id>-<approach>/ directory.');
+          console.log('When done, merge with: jettypod work prototype merge <feature-id>');
+          process.exit(1);
+        }
+        try {
+          await workCommands.prototypeWork(featureId, approachName);
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+      } else {
+        // work prototype (show usage)
+        console.log('Usage: jettypod work prototype start <feature-id> <approach-name>');
+        console.log('       jettypod work prototype merge <feature-id>');
+        console.log('');
+        console.log('Commands:');
+        console.log('  work prototype start <id> <approach>  Create a worktree for prototyping');
+        console.log('  work prototype merge <id>             Merge prototype worktree to main');
+        console.log('');
+        console.log('Examples:');
+        console.log('  jettypod work prototype start 42 simple-form');
+        console.log('  jettypod work prototype merge 42');
+        process.exit(1);
+      }
     } else {
       // CRITICAL SAFETY CHECK: Prevent work status changes from within a worktree
       // This prevents cleanup failures and orphaned worktrees

package/lib/work-commands/index.js

@@ -2126,6 +2126,253 @@ async function testsMerge(featureId) {
   return Promise.resolve();
 }
 
+/**
+ * Create a worktree for building prototypes for a feature or epic
+ * @param {number} workItemId - Feature or Epic ID to create prototype worktree for
+ * @param {string} approachName - Name of the approach being prototyped (e.g., "simple-form", "wizard")
+ * @returns {Promise<Object>} Worktree info with path and branch
+ * @throws {Error} If work item not found or not a feature/epic
+ */
+async function prototypeWork(workItemId, approachName) {
+  if (!workItemId || isNaN(workItemId) || workItemId < 1) {
+    return Promise.reject(new Error('Invalid work item ID'));
+  }
+
+  if (!approachName || typeof approachName !== 'string' || !approachName.trim()) {
+    return Promise.reject(new Error('Approach name is required (e.g., "simple-form", "wizard")'));
+  }
+
+  // Sanitize approach name for use in branch/path
+  const sanitizedApproach = approachName.trim().toLowerCase().replace(/[^a-z0-9-]/g, '-');
+
+  const paths = getPaths();
+
+  if (!fs.existsSync(paths.jettypodDir)) {
+    return Promise.reject(new Error('JettyPod not initialized. Run: jettypod init'));
+  }
+
+  if (!fs.existsSync(paths.dbPath)) {
+    return Promise.reject(new Error('Work database not found. Run: jettypod init'));
+  }
+
+  const db = getDb();
+
+  return new Promise((resolve, reject) => {
+    // Get feature or epic work item
+    db.get(
+      `SELECT * FROM work_items WHERE id = ? AND type IN ('feature', 'epic')`,
+      [workItemId],
+      async (err, workItem) => {
+        if (err) {
+          return reject(new Error(`Database error: ${err.message}`));
+        }
+
+        if (!workItem) {
+          return reject(new Error(`Feature or epic #${workItemId} not found`));
+        }
+
+        // Create worktree with prototype/ prefix
+        try {
+          const gitRoot = getGitRoot();
+          const branchPrefix = workItem.type === 'epic' ? 'prototype/epic' : 'prototype/feature';
+          const worktreeResult = await worktreeManager.createWorktree(workItem, {
+            repoPath: gitRoot,
+            branchPrefix: branchPrefix,
+            pathPrefix: `prototype-`,
+            branchSuffix: `-${sanitizedApproach}`
+          });
+
+          // Set as current work
+          setCurrentWork({
+            id: workItem.id,
+            type: workItem.type,
+            title: workItem.title,
+            status: workItem.status || 'in_progress',
+            worktreePath: worktreeResult.worktree_path,
+            branchName: worktreeResult.branch_name
+          });
+
+          console.log(`✅ Created prototype worktree: ${worktreeResult.worktree_path}`);
+          console.log(`📁 IMPORTANT: Use absolute paths for file operations:`);
+          console.log(`   ${worktreeResult.worktree_path}/prototypes/${workItem.type}-${workItemId}-${sanitizedApproach}/ (correct)`);
+          console.log(`   prototypes/... (wrong - creates in main repo)`);
+          console.log(`\nPrototyping "${approachName}" for: [#${workItem.id}] ${workItem.title}`);
+
+          resolve(worktreeResult);
+        } catch (worktreeErr) {
+          reject(new Error(`Failed to create prototype worktree: ${worktreeErr.message}`));
+        }
+      }
+    );
+  });
+}
+
+/**
+ * Merge a prototype worktree back to main and clean up
+ * @param {number} workItemId - Feature or Epic ID whose prototype worktree to merge
+ * @returns {Promise<void>}
+ */
+async function prototypeMerge(workItemId) {
+  if (!workItemId || isNaN(workItemId) || workItemId < 1) {
+    return Promise.reject(new Error('Invalid work item ID'));
+  }
+
+  // Auto-chdir to main repo if running from inside a worktree
+  const cwd = process.cwd();
+  if (cwd.includes('.jettypod-work')) {
+    const mainRepo = getGitRoot();
+    console.log('📂 Changing to main repository for merge...');
+    process.chdir(mainRepo);
+  }
+
+  const db = getDb();
+  const gitRoot = getGitRoot();
+
+  // Find the prototype worktree for this feature or epic (branch starts with prototype/feature- or prototype/epic-)
+  const worktree = await new Promise((resolve, reject) => {
+    db.get(
+      `SELECT * FROM worktrees
+       WHERE work_item_id = ?
+       AND (branch_name LIKE 'prototype/feature-%' OR branch_name LIKE 'prototype/epic-%')
+       AND status = 'active'`,
+      [workItemId],
+      (err, row) => {
+        if (err) return reject(err);
+        resolve(row);
+      }
+    );
+  });
+
+  if (!worktree) {
+    return Promise.reject(new Error(
+      `No active prototype worktree found for #${workItemId}.\n\n` +
+      `Create one with: jettypod work prototype start ${workItemId} <approach-name>`
+    ));
+  }
+
+  const worktreePath = worktree.worktree_path;
+  const branchName = worktree.branch_name;
+
+  console.log(`⏳ Merging prototype worktree for #${workItemId}...`);
+  console.log(`   Branch: ${branchName}`);
+  console.log(`   Path: ${worktreePath}`);
+
+  // Check for uncommitted changes in the worktree
+  try {
+    const status = execSync('git status --porcelain', {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (status) {
+      return Promise.reject(new Error(
+        `Uncommitted changes in prototype worktree:\n${status}\n\n` +
+        `Commit your changes first:\n` +
+        `  cd ${worktreePath}\n` +
+        `  git add .\n` +
+        `  git commit -m "Add prototype for #${workItemId}"`
+      ));
+    }
+  } catch (err) {
+    return Promise.reject(new Error(`Failed to check worktree status: ${err.message}`));
+  }
+
+  // Check if there are commits to merge
+  try {
+    const mainBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim().replace('refs/remotes/origin/', '');
+
+    const commitCount = execSync(`git rev-list --count ${mainBranch}..${branchName}`, {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (commitCount === '0') {
+      console.log('⚠️  No commits to merge - worktree has no new changes');
+    }
+  } catch (err) {
+    // Non-fatal - proceed anyway
+    console.log('⚠️  Could not check commit count, proceeding with merge');
+  }
+
+  // Merge the prototype branch to main
+  try {
+    // First, ensure we're on main
+    execSync('git checkout main', {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+
+    // Merge the prototype branch
+    execSync(`git merge ${branchName} --no-ff -m "Merge prototype for #${workItemId}"`, {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+
+    console.log('✅ Merged prototype branch to main');
+  } catch (err) {
+    return Promise.reject(new Error(
+      `Merge failed: ${err.message}\n\n` +
+      `Resolve conflicts manually, then run:\n` +
+      `  jettypod work prototype merge ${workItemId}`
+    ));
+  }
+
+  // Push to remote
+  try {
+    execSync('git push', {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+    console.log('✅ Pushed to remote');
+  } catch (err) {
+    console.log('⚠️  Failed to push (non-fatal):', err.message);
+  }
+
+  // Mark worktree as merged but DON'T delete it yet
+  // This prevents shell CWD corruption when merge is run from inside the worktree
+  await new Promise((resolve, reject) => {
+    db.run(
+      `UPDATE worktrees SET status = 'merged' WHERE id = ?`,
+      [worktree.id],
+      (err) => {
+        if (err) return reject(err);
+        resolve();
+      }
+    );
+  });
+
+  // Clear current work if it was pointing to this worktree
+  const currentWork = await getCurrentWork();
+  if (currentWork && currentWork.worktreePath === worktreePath) {
+    clearCurrentWork();
+  }
+
+  console.log('');
+  console.log(`✅ Prototype worktree for #${workItemId} merged successfully`);
+
+  // Instruct user to cleanup worktree separately - be aggressive so AI doesn't forget
+  if (fs.existsSync(worktreePath)) {
+    console.log('');
+    console.log('⚠️  CLEANUP REQUIRED - Run these commands NOW:');
+    console.log('');
+    console.log(`   cd ${gitRoot}`);
+    console.log(`   jettypod work cleanup ${workItemId}`);
+    console.log('');
+    console.log('   Worktrees accumulate until cleaned up.');
+  }
+
+  return Promise.resolve();
+}
+
 module.exports = {
   startWork,
   stopWork,
@@ -2134,5 +2381,7 @@ module.exports = {
   cleanupWorkItem,
   mergeWork,
   testsWork,
-  testsMerge
+  testsMerge,
+  prototypeWork,
+  prototypeMerge
 };

package/lib/worktree-manager.js

@@ -88,10 +88,11 @@ async function createWorktree(workItem, options = {}) {
   // Generate branch name and worktree path
   const titleSlug = slugify(workItem.title || 'item');
   const branchPrefix = options.branchPrefix || 'feature/work';
+  const branchSuffix = options.branchSuffix || '';
   const pathPrefix = options.pathPrefix || '';
-  const branchName = `${branchPrefix}-${workItem.id}-${titleSlug}`;
+  const branchName = `${branchPrefix}-${workItem.id}-${titleSlug}${branchSuffix}`;
   const worktreeBasePath = path.join(gitRoot, '.jettypod-work');
-  const worktreePath = path.join(worktreeBasePath, `${pathPrefix}${workItem.id}-${titleSlug}`);
+  const worktreePath = path.join(worktreeBasePath, `${pathPrefix}${workItem.id}-${titleSlug}${branchSuffix}`);
 
   let worktreeId = null;
   let branchCreated = false;

package/package.json

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

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

@@ -301,7 +301,7 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
 
 ```bash
 # Step 1: Merge (can run from worktree - it won't delete it)
-jettypod work merge
+jettypod work merge <bug-id>
 ```
 
 ```bash
@@ -366,7 +366,7 @@ Before ending bug-mode skill, ensure:
 
 **Merge fix (CRITICAL: cd to main repo separately):**
 ```bash
-jettypod work merge              # Merge current bug
+jettypod work merge <bug-id>     # ALWAYS include bug ID
 ```
 
 ```bash

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

@@ -67,6 +67,14 @@ Your shell's working directory was likely inside a worktree that was deleted. Th
 
 **Your task:** Acknowledge the context passed from chore-planning.
 
+**🚫 FORBIDDEN: Writing Files at This Step**
+```
+❌ Write tool to any path
+❌ Edit tool to any path
+❌ Any file creation or modification
+```
+**This is a CONTEXT step.** File writes happen in Step 5.
+
 You will receive:
 - `choreContext.chore` - Chore ID, title, description
 - `choreContext.classification` - Type and confidence
@@ -149,10 +157,34 @@ Resolve the issue before continuing.
 
 **Move to Step 3 only if worktree was created successfully.**
 
+**🔒 WORKTREE PATH LOCK**
+
+After worktree validation passes, capture and lock the path:
+- `WORKTREE_PATH` - the absolute path from the query result
+
+**Display:**
+
+```
+🔒 WORKTREE LOCK ACTIVE
+Path: ${WORKTREE_PATH}
+
+All file writes will use this path.
+```
+
+**From this point forward, ALL file operations MUST use paths starting with `${WORKTREE_PATH}/`**
+
 ### Step 3: Establish Test Baseline
 
 **Your task:** Run tests to establish baseline before making changes.
 
+**🚫 FORBIDDEN: Writing Files at This Step**
+```
+❌ Write tool to any path
+❌ Edit tool to any path
+❌ Any file creation or modification
+```
+**This is a TESTING step.** File writes happen in Step 5.
+
 **Test handling varies by type:**
 
 **For REFACTOR:**
@@ -205,6 +237,14 @@ jettypod workflow checkpoint <chore-id> --step=3
 
 **Your task:** Display warnings and constraints based on chore type.
 
+**🚫 FORBIDDEN: Writing Files at This Step**
+```
+❌ Write tool to any path
+❌ Edit tool to any path
+❌ Any file creation or modification
+```
+**This is a GUIDANCE step.** File writes happen in Step 5.
+
 **Load guidance from taxonomy:**
 
 ```javascript
@@ -258,6 +298,10 @@ const guidance = getGuidance('[chore-type]');
 
 ### Step 5: Execute with Iteration
 
+**🔒 WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured in Step 2.
+
+**✅ NOW you may write files** - worktree is locked, guidance is displayed.
+
 **Your task:** Make changes and iterate until tests pass. Max 5 iterations.
 
 ```

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

@@ -231,21 +231,50 @@ Present exactly 3 approaches. Fill in the bracketed parts with actual content ba
 
 If user wants to prototype approaches:
 
-1. Create prototype directory using the epic ID from Step 1:
-   ```bash
-   mkdir -p prototypes/epic-${EPIC_ID}-${APPROACH_NAME}
-   ```
+**Sub-step 1: Create prototype worktree**
+
+```bash
+jettypod work prototype start ${EPIC_ID} [approach-name]
+```
+
+Example (if epic ID is 5, approach is "websockets"):
+```bash
+jettypod work prototype start 5 websockets
+```
+
+This creates a worktree at `.jettypod-work/prototype-<id>-<slug>-<approach>/` where prototypes can be safely built and committed.
+
+**🛑 STOP AND CHECK:** Verify worktree was created successfully before proceeding.
 
-   **Example** (if epic ID is 5, approach is "websockets"):
+**Sub-step 2: Build prototypes in the worktree**
+
+1. Build prototypes using **absolute paths** to the worktree:
+   - `<worktree_path>/prototypes/epic-${EPIC_ID}-${APPROACH_NAME}/`
+2. Build 2-3 working prototypes demonstrating the architectural difference
+3. **Commit the prototype** in the worktree:
    ```bash
-   mkdir -p prototypes/epic-5-websockets
+   cd <worktree_path>
+   git add .
+   git commit -m "Add prototype: [approach-name] for epic #${EPIC_ID}"
    ```
 
-2. Build 2-3 working prototypes demonstrating the architectural difference
+**Sub-step 3: Test and decide**
+
+After user tests, ask which approach they prefer.
+
+**Sub-step 4: Merge prototype**
+
+After user has tested (regardless of whether they pick this approach):
+
+```bash
+jettypod work prototype merge ${EPIC_ID}
+cd <main-repo-path>
+jettypod work cleanup ${EPIC_ID}
+```
 
-3. After user tests, ask which approach they prefer
+This merges prototype files to main (in `/prototypes/` directory) and cleans up the worktree.
 
-4. When user picks a winner → Go to Step 6 (set `ARCH_DECISION_MADE = true`)
+When user picks a winner → Go to Step 6 (set `ARCH_DECISION_MADE = true`)
 
 ### Step 5C: Skip Architecture (User Already Knows)