jettypod 4.4.21 → 4.4.23

package/lib/work-commands/index.js

@@ -0,0 +1,1603 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getDb, getDbPath, getJettypodDir } = require('../../lib/database');
+const { getCurrentWork, setCurrentWork, clearCurrentWork, getCurrentWorkPath } = require('../../lib/current-work');
+const { VALID_STATUSES } = require('../../lib/constants');
+const { updateCurrentWork } = require('../../lib/claudemd');
+const { createFeatureBranchName, createOrCheckoutBranch } = require('../../lib/git');
+const config = require('../../lib/config');
+const { getBugWorkflowForTerminal } = require('../../lib/bug-workflow');
+const worktreeFacade = require('../../lib/worktree-facade');
+const worktreeManager = require('../../lib/worktree-manager');
+const { getGitRoot } = require('../../lib/git-root');
+
+/**
+ * Get paths to JettyPod files and directories
+ * @returns {Object} Paths object with jettypodDir, currentWorkPath, dbPath, claudePath
+ */
+function getPaths() {
+  return {
+    jettypodDir: getJettypodDir(),
+    currentWorkPath: getCurrentWorkPath(),
+    dbPath: getDbPath(),
+    claudePath: path.join(process.cwd(), 'CLAUDE.md')
+  };
+}
+
+/**
+ * Start work on a work item
+ * @param {number} id - Work item ID to start
+ * @returns {Promise<Object>} Work item, current work, and branch name
+ * @throws {Error} If ID is invalid, JettyPod not initialized, database missing, or work item not found
+ */
+async function startWork(id) {
+  // Input validation
+  if (!id || isNaN(id) || id < 1) {
+    return Promise.reject(new Error('Invalid work item ID'));
+  }
+
+  const paths = getPaths();
+
+  // Check jettypod directory exists
+  if (!fs.existsSync(paths.jettypodDir)) {
+    return Promise.reject(new Error('JettyPod not initialized. Run: jettypod init'));
+  }
+
+  // Check database exists
+  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 work item
+    db.get(`
+      SELECT w.*,
+             p.title as parent_title, p.id as parent_id, p.scenario_file as parent_scenario_file, p.mode as parent_mode,
+             e.title as epic_title, e.id as epic_id
+      FROM work_items w
+      LEFT JOIN work_items p ON w.parent_id = p.id
+      LEFT JOIN work_items e ON w.epic_id = e.id AND w.epic_id != w.id
+      WHERE w.id = ?
+    `, [id], (err, workItem) => {
+      if (err) {
+        return reject(new Error(`Database error: ${err.message}`));
+      }
+
+      if (!workItem) {
+        return reject(new Error(`Work item #${id} not found`));
+      }
+
+      // Prevent starting features directly - must start chores instead
+      if (workItem.type === 'feature') {
+        // Find available chores for this feature
+        db.all(
+          `SELECT id, title, status FROM work_items WHERE parent_id = ? AND type = 'chore' ORDER BY id`,
+          [workItem.id],
+          (err, chores) => {
+            if (err) {
+              return reject(new Error(`Cannot start a feature directly. Start one of its chores instead.`));
+            }
+
+            let errorMsg = `Cannot start feature #${id} directly.\n\n`;
+
+            if (chores && chores.length > 0) {
+              const todoChores = chores.filter(c => c.status === 'todo' || c.status === 'backlog');
+              const inProgressChores = chores.filter(c => c.status === 'in_progress');
+
+              if (inProgressChores.length > 0) {
+                errorMsg += `In-progress chore:\n`;
+                inProgressChores.forEach(c => {
+                  errorMsg += `  jettypod work start ${c.id}  # ${c.title}\n`;
+                });
+                errorMsg += `\n`;
+              }
+
+              if (todoChores.length > 0) {
+                errorMsg += `Available chores to start:\n`;
+                todoChores.forEach(c => {
+                  errorMsg += `  jettypod work start ${c.id}  # ${c.title}\n`;
+                });
+              } else if (inProgressChores.length === 0) {
+                errorMsg += `No chores available. Create chores first or check if feature is complete.`;
+              }
+            } else {
+              errorMsg += `This feature has no chores yet. Use the feature-planning skill to plan it:\n`;
+              errorMsg += `  Tell Claude: "Help me plan feature #${id}"`;
+            }
+
+            return reject(new Error(errorMsg));
+          }
+        );
+        return; // Exit early - callback will handle resolve/reject
+      }
+
+      // Prevent starting epics directly
+      if (workItem.type === 'epic') {
+        return reject(new Error(`Cannot start epic #${id} directly. Start a feature or chore instead.\n\nUse: jettypod backlog  # to see available work items`));
+      }
+
+      // Update status to in_progress if currently todo
+      const finalStatus = workItem.status === 'todo' ? 'in_progress' : workItem.status;
+
+      const updateAndContinue = async () => {
+        // Create current work file
+        const currentWork = {
+          id: workItem.id,
+          title: workItem.title,
+          type: workItem.type,
+          status: finalStatus,
+          parent_id: workItem.parent_id,
+          parent_title: workItem.parent_title,
+          epic_id: workItem.epic_id,
+          epic_title: workItem.epic_title
+        };
+
+        try {
+          setCurrentWork(currentWork);
+        } catch (err) {
+          return reject(new Error(`Failed to write current work file: ${err.message}`));
+        }
+
+        // ✅ BULLETPROOF WORKTREE ARCHITECTURE (Epic #1783)
+        // Using transactional worktree-facade with atomic rollback and graceful degradation
+        let worktreeResult = null;
+        let worktreeId = null;
+
+        try {
+          const { isGitRepo } = require('../../lib/git');
+
+          if (isGitRepo()) {
+            // Use bulletproof worktree-facade for isolated work
+            worktreeResult = await worktreeFacade.startWork(workItem, {
+            repoPath: getGitRoot(),
+            db: db
+          });
+
+          if (worktreeResult.mode === 'worktree') {
+            // Worktree created successfully
+            worktreeId = worktreeResult.worktree.id;
+            console.log(`✅ Created worktree: ${worktreeResult.path}`);
+            console.log(`📁 IMPORTANT: Use absolute paths for file operations:`);
+            console.log(`   ${worktreeResult.path}/lib/file.js (correct)`);
+            console.log(`   lib/file.js (wrong - creates in main repo)`);
+
+            // Create worktree-specific session file with work context
+            // Session file is gitignored to prevent merge conflicts
+            const { writeSessionFile } = require('../../lib/session-writer');
+            const modeToUse = (workItem.type === 'chore' && workItem.parent_mode)
+              ? workItem.parent_mode
+              : workItem.mode;
+
+            if (modeToUse) {
+              try {
+                // Change to worktree directory to write session file there
+                const originalCwd = process.cwd();
+                process.chdir(worktreeResult.path);
+                writeSessionFile(currentWork, modeToUse, {
+                  epicId: workItem.epic_id,
+                  epicTitle: workItem.epic_title
+                });
+                process.chdir(originalCwd);
+              } catch (sessionError) {
+                // Session file is important but not critical - warn but don't fail
+                console.warn(`Warning: Failed to create session file: ${sessionError.message}`);
+              }
+            }
+          } else {
+            // Fell back to main repository
+            console.warn(`⚠️  Working in main repository (worktree creation failed)`);
+            if (worktreeResult.error) {
+              console.warn(`   Reason: ${worktreeResult.error.message}`);
+            }
+          }
+        }
+      } catch (gitError) {
+        // Git operations unavailable - continue without worktree
+        console.warn(`Warning: Git operations unavailable: ${gitError.message}`);
+      }
+
+
+      // Update CLAUDE.md with work item's mode
+      // For chores, inherit the parent feature's mode
+      const modeToUse = (workItem.type === 'chore' && workItem.parent_mode)
+        ? workItem.parent_mode
+        : workItem.mode;
+      updateCurrentWork(currentWork, modeToUse);
+
+      // Display output
+      let output = `Working on: [#${workItem.id}] ${workItem.title} (${workItem.type})`;
+      if (workItem.parent_title) {
+        output = `Working on: [#${workItem.id}] ${workItem.title} (${workItem.type} of #${workItem.parent_id} ${workItem.parent_title})`;
+      }
+      console.log(output);
+
+      // Display bug workflow guidance for bugs
+      // Only display if workItem has a type (defensive check)
+      if (workItem && workItem.type === 'bug') {
+        try {
+          console.log(getBugWorkflowForTerminal());
+        } catch (err) {
+          // Silently fail if workflow display fails - don't block work start
+          // This is a non-critical feature
+        }
+      }
+
+      // Display epic discovery guidance for epics with needs_discovery
+      if (workItem && workItem.type === 'epic' && workItem.needs_discovery) {
+        // Check if decisions have been recorded
+        db.all(
+          `SELECT * FROM discovery_decisions WHERE work_item_id = ?`,
+          [workItem.id],
+          (err, decisions) => {
+            if (err || !decisions || decisions.length === 0) {
+              console.log('');
+              console.log('⚠️  This epic needs architectural discovery before building features.');
+              console.log('');
+              console.log('💬 Recommended: Talk to Claude Code');
+              console.log(`   Say: "Let's do epic discovery for #${workItem.id}"`);
+              console.log('');
+              console.log('   Claude Code will guide you through:');
+              console.log('   • Suggesting 3 architectural options');
+              console.log('   • Building prototypes');
+              console.log('   • Recording your decisions');
+              console.log('');
+            }
+          }
+        );
+      }
+
+      // Auto-trigger feature discovery for features in discovery phase
+      if (workItem && workItem.type === 'feature' && workItem.phase === 'discovery') {
+        console.log('');
+        console.log('✨ Feature Discovery Mode');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        console.log('This feature is in discovery phase. Claude Code will help you:');
+        console.log('  1. Explore 3 different UX approaches');
+        console.log('  2. (Optional) Build throwaway prototypes');
+        console.log('  3. Choose the winning approach');
+        console.log('  4. Generate BDD scenarios for the happy path');
+        console.log('  5. Transition to implementation (speed mode)');
+        console.log('');
+        console.log('💬 Claude Code is ready to guide you through feature discovery.');
+        console.log('');
+        console.log('📋 The feature-planning skill will automatically activate.');
+        console.log('');
+      }
+
+      // Auto-trigger mode skills for chores in speed or stable mode
+      if (workItem && workItem.type === 'chore' && workItem.parent_id) {
+        // Validate parent feature exists
+        if (!workItem.parent_title) {
+          console.log('');
+          console.log('⚠️  Warning: Parent feature not found');
+          console.log('');
+          console.log(`This chore references parent feature #${workItem.parent_id}, but that feature`);
+          console.log('does not exist in the database.');
+          console.log('');
+          console.log('Suggestion: Check the parent_id or create the missing feature.');
+          console.log('');
+        }
+        // Validate scenario file exists
+        else if (!workItem.parent_scenario_file) {
+          console.log('');
+          console.log('⚠️  Warning: Parent feature has no scenario file');
+          console.log('');
+          console.log(`Parent feature #${workItem.parent_id} "${workItem.parent_title}" does not have`);
+          console.log('a scenario file set.');
+          console.log('');
+          console.log('Suggestion: Create a BDD scenario file for the feature and update scenario_file.');
+          console.log('');
+        }
+        else if (!fs.existsSync(path.join(process.cwd(), workItem.parent_scenario_file))) {
+          console.log('');
+          console.log('⚠️  Warning: Scenario file not found');
+          console.log('');
+          console.log(`Parent feature references scenario file: ${workItem.parent_scenario_file}`);
+          console.log('but the file does not exist on disk.');
+          console.log('');
+          console.log('Suggestion: Create the scenario file or update the feature.scenario_file path.');
+          console.log('');
+        }
+        else if (workItem.mode === 'speed') {
+          console.log('');
+          console.log('🚀 Speed Mode Skill Activated');
+          console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+          console.log('');
+          console.log('Claude Code will autonomously:');
+          console.log('  1. Analyze the BDD scenario for this feature');
+          console.log('  2. Analyze the codebase to understand patterns');
+          console.log('  3. Propose an implementation approach');
+          console.log('  4. Implement until the happy path scenario passes');
+          console.log('  5. Generate stable mode chores for comprehensive testing');
+          console.log('');
+          console.log('💬 The speed-mode skill is now active.');
+          console.log('   Claude Code will guide you through implementation.');
+          console.log('');
+        } else if (workItem.mode === 'stable') {
+          console.log('');
+          console.log('🧪 Stable Mode Skill Activated');
+          console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+          console.log('');
+          console.log('Claude Code will autonomously:');
+          console.log('  1. Analyze the BDD scenario to implement');
+          console.log('  2. Review the existing speed mode implementation');
+          console.log('  3. Propose comprehensive error handling approach');
+          console.log('  4. Implement with proper validation and edge case coverage');
+          console.log('  5. Ensure all BDD scenarios pass');
+          console.log('');
+          console.log('💬 The stable-mode skill is now active.');
+          console.log('   Claude Code will guide you through comprehensive testing.');
+          console.log('');
+        }
+      }
+
+        // Return work item, current work, and branch name (from worktree if created)
+        const branchName = worktreeResult && worktreeResult.worktree
+          ? worktreeResult.worktree.branch_name
+          : null;
+        resolve({ workItem, currentWork, branchName });
+      };
+
+      // Update status to in_progress if currently todo
+      if (workItem.status === 'todo') {
+        db.run(`UPDATE work_items SET status = 'in_progress' WHERE id = ?`, [id], (err) => {
+          if (err) {
+            return reject(new Error(`Failed to update status: ${err.message}`));
+          }
+
+          // If this is a chore, also set parent feature to in_progress
+          if (workItem.type === 'chore' && workItem.parent_id) {
+            db.run(
+              `UPDATE work_items SET status = 'in_progress' WHERE id = ? AND status IN ('backlog', 'todo')`,
+              [workItem.parent_id],
+              (err) => {
+                // Non-fatal - continue even if parent update fails
+                if (!err) {
+                  // Check if we actually updated (status was backlog/todo)
+                  db.get('SELECT status FROM work_items WHERE id = ?', [workItem.parent_id], (err, parent) => {
+                    if (!err && parent && parent.status === 'in_progress') {
+                      console.log(`✓ Feature #${workItem.parent_id} marked in_progress`);
+                    }
+                  });
+                }
+                updateAndContinue();
+              }
+            );
+          } else {
+            updateAndContinue();
+          }
+        });
+      } else {
+        // Even if chore is already in_progress, ensure parent feature is too
+        if (workItem.type === 'chore' && workItem.parent_id) {
+          db.run(
+            `UPDATE work_items SET status = 'in_progress' WHERE id = ? AND status IN ('backlog', 'todo')`,
+            [workItem.parent_id],
+            () => updateAndContinue()
+          );
+        } else {
+          updateAndContinue();
+        }
+      }
+    });
+  });
+}
+
+/**
+ * Stop work on current work item
+ * @param {string|null} newStatus - Optional status to set (e.g., 'done', 'blocked')
+ * @returns {Promise<Object|null>} Work item ID and status, or null if no active work
+ * @throws {Error} If status is invalid, database missing, or file operations fail
+ */
+function stopWork(newStatus = null) {
+  const paths = getPaths();
+
+  const currentWork = getCurrentWork();
+  if (!currentWork) {
+    console.log('No active work item');
+    return Promise.resolve(null);
+  }
+
+  // Validate status if provided
+  if (newStatus && !VALID_STATUSES.includes(newStatus)) {
+    return Promise.reject(new Error(`Invalid status: ${newStatus}`));
+  }
+
+  return new Promise((resolve, reject) => {
+    if (newStatus) {
+      if (!fs.existsSync(paths.dbPath)) {
+        return reject(new Error('Work database not found'));
+      }
+
+      const db = getDb();
+
+      // Validate mode transition before marking as done
+      if (newStatus === 'done') {
+        validateModeTransition(db, currentWork, async (validationErr) => {
+          if (validationErr) {
+            db.close();
+            return reject(validationErr);
+          }
+
+          // Check if work item has an active worktree
+          const worktree = await worktreeManager.getWorktreeForWorkItem(currentWork.id, { db });
+          const cwd = process.cwd();
+          const inWorktree = cwd.includes('.jettypod-work');
+
+          if (worktree && worktree.status === 'active' && !inWorktree) {
+            // Work item has active worktree, but we're in main
+            // Run merge workflow with branch from database (no chdir needed)
+            db.close();
+            console.log(`⚠️  Work item #${currentWork.id} has an active worktree`);
+            console.log(`   Running merge workflow for branch: ${worktree.branch_name}\n`);
+
+            try {
+              // Pass branch name directly - no need to chdir into worktree
+              const mergeResult = await mergeWork({ featureBranch: worktree.branch_name });
+              return resolve(mergeResult);
+            } catch (mergeErr) {
+              return reject(new Error(`Merge failed: ${mergeErr.message}`));
+            }
+          }
+
+          // Validation passed, proceed with status update
+          updateWorkItemStatus();
+        });
+      } else {
+        // Not marking as done, skip validation
+        updateWorkItemStatus();
+      }
+
+      function updateWorkItemStatus() {
+        db.run(`UPDATE work_items SET status = ? WHERE id = ?`, [newStatus, currentWork.id], async (err) => {
+          if (err) {
+            return reject(new Error(`Database error: ${err.message}`));
+          }
+
+          // No need to clear worktree session - status-based approach handles this automatically
+
+        // Get work item and worktree details from worktrees table
+        db.get(`SELECT * FROM work_items WHERE id = ?`, [currentWork.id], async (getErr, workItem) => {
+          if (getErr) {
+            return reject(new Error(`Failed to get work item: ${getErr.message}`));
+          }
+
+          // Check if there's an active worktree for this work item
+          const worktree = await worktreeManager.getWorktreeForWorkItem(currentWork.id, { db });
+
+          // If status is 'done' and there's a worktree, check for conflicts before merging
+          if (newStatus === 'done' && worktree && worktree.status === 'active') {
+            try {
+              const { isGitRepo } = require('../../lib/git');
+
+              if (isGitRepo()) {
+                // Get current branch from worktree
+                const worktreeBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+                  cwd: worktree.worktree_path,
+                  encoding: 'utf8'
+                }).trim();
+
+                // Test merge to detect conflicts (without actually merging)
+                try {
+                  const mergeResult = execSync(`git merge --no-commit --no-ff ${worktreeBranch}`, {
+                    cwd: process.cwd(),
+                    encoding: 'utf8',
+                    stdio: 'pipe'
+                  });
+
+                  // No conflicts - complete the merge
+                  try {
+                    execSync(`git commit -m "Merge work item #${currentWork.id}: ${workItem.title}"`, {
+                      cwd: process.cwd(),
+                      stdio: 'pipe'
+                    });
+                    console.log(`✓ Merged branch "${worktreeBranch}" to main`);
+
+                    // Cleanup: Use bulletproof worktree-facade for cleanup
+                    try {
+                      const cleanupResult = await worktreeFacade.stopWork(worktree.id, {
+                        repoPath: getGitRoot(),
+                        db: db,
+                        deleteBranch: true  // Delete branch after successful merge
+                      });
+
+                      if (cleanupResult.success) {
+                        console.log(`✓ Removed worktree: ${worktree.worktree_path}`);
+                        console.log(`✓ Deleted branch: ${worktreeBranch}`);
+                      } else {
+                        // CRITICAL: Cleanup failures must be fatal - do not swallow errors
+                        // Orphaned worktrees prevent recreation and cause confusion
+                        const userMsg = cleanupResult.error?.userMessage || cleanupResult.error?.message;
+                        console.error(`\n❌ Failed to cleanup worktree: ${userMsg || 'Unknown error'}`);
+                        console.error('This may leave orphaned worktree files.');
+                        console.error('Please manually cleanup before continuing.\n');
+                        process.exit(1);
+                      }
+                    } catch (cleanupErr) {
+                      // CRITICAL: Cleanup failures must be fatal - do not swallow errors
+                      console.error(`\n❌ Failed to cleanup worktree: ${cleanupErr.message}`);
+                      console.error('This may leave orphaned worktree files.');
+                      console.error('Please manually cleanup before continuing.\n');
+                      process.exit(1);
+                    }
+                  } catch (commitErr) {
+                    // Failed to commit - abort the merge
+                    console.warn(`Warning: Failed to commit merge: ${commitErr.message}`);
+                    try {
+                      execSync('git merge --abort', { cwd: process.cwd(), stdio: 'pipe' });
+                    } catch (abortErr) {
+                      // Ignore abort errors
+                    }
+                  }
+                } catch (mergeErr) {
+                  // Merge failed - could be conflicts or other error
+                  const errorOutput = mergeErr.stdout || mergeErr.stderr || mergeErr.message || '';
+                  const hasConflict = errorOutput.includes('CONFLICT') || errorOutput.includes('conflict');
+
+                  // Check if there are unmerged files (another indicator of conflicts)
+                  let hasUnmergedFiles = false;
+                  try {
+                    const statusOutput = execSync('git status', {
+                      cwd: process.cwd(),
+                      encoding: 'utf8',
+                      stdio: 'pipe'
+                    });
+                    hasUnmergedFiles = statusOutput.includes('Unmerged paths') || statusOutput.includes('both modified');
+                  } catch (statusErr) {
+                    // Ignore status check errors
+                  }
+
+                  if (hasConflict || hasUnmergedFiles) {
+                    // Abort the failed merge attempt
+                    try {
+                      execSync('git merge --abort', { cwd: process.cwd(), stdio: 'pipe' });
+                    } catch (abortErr) {
+                      // Ignore abort errors
+                    }
+
+                    // Get list of conflicting files
+                    let conflictingFiles = [];
+                    try {
+                      const diffOutput = execSync('git diff --name-only --diff-filter=U', {
+                        cwd: testMergeDir,
+                        encoding: 'utf8'
+                      });
+                      conflictingFiles = diffOutput.trim().split('\n').filter(f => f);
+                    } catch (diffErr) {
+                      // Ignore errors getting file list
+                    }
+
+                    // Don't clear current work - keep worktree for conflict resolution
+                    console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+                    console.log(`⚠️  MERGE CONFLICT DETECTED`);
+                    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+                    console.log();
+                    console.log(`Cannot auto-merge worktree branch "${worktreeBranch}" to main.`);
+
+                    if (conflictingFiles.length > 0) {
+                      console.log();
+                      console.log(`Conflicting files:`);
+                      conflictingFiles.forEach(file => console.log(`  - ${file}`));
+                    }
+
+                    console.log();
+                    console.log(`Worktree preserved at: ${worktree.worktree_path}`);
+                    console.log();
+                    console.log(`To resolve conflicts:`);
+                    console.log();
+                    console.log(`  1. Switch to main and pull latest changes:`);
+                    console.log(`     cd ${process.cwd()}`);
+                    console.log(`     git pull origin main`);
+                    console.log();
+                    console.log(`  2. In your worktree, merge the updated main:`);
+                    console.log(`     cd ${worktree.worktree_path}`);
+                    console.log(`     git merge main`);
+                    console.log();
+                    console.log(`  3. Resolve conflicts in each file, then:`);
+                    console.log(`     git add <resolved-files>`);
+                    console.log(`     git commit`);
+                    console.log();
+                    console.log(`  4. Return to main and retry the merge:`);
+                    console.log(`     cd ${process.cwd()}`);
+                    console.log(`     git merge ${worktreeBranch}`);
+                    console.log();
+                    console.log(`  5. Clean up worktree after successful merge:`);
+                    console.log(`     git worktree remove "${worktree.worktree_path}"`);
+                    console.log(`     git branch -d ${worktreeBranch}`);
+                    console.log();
+                    console.log(`Alternative: If conflicts are complex, consider rebasing:`);
+                    console.log(`     cd ${worktree.worktree_path}`);
+                    console.log(`     git rebase main`);
+                    console.log(`     # Resolve conflicts as prompted`);
+                    console.log(`     git rebase --continue`);
+                    console.log();
+                    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+
+                    return resolve({ id: currentWork.id, status: newStatus, conflicts: true, conflictingFiles });
+                  }
+
+                  // Some other merge error - abort and continue
+                  try {
+                    execSync('git merge --abort', { cwd: process.cwd(), stdio: 'pipe' });
+                  } catch (abortErr) {
+                    // Ignore abort errors
+                  }
+
+                  // Log the error but don't fail the stop command
+                  console.warn(`Warning: Merge test failed: ${errorOutput}`);
+                }
+              }
+            } catch (conflictCheckErr) {
+              console.warn(`Warning: Failed to check for conflicts: ${conflictCheckErr.message}`);
+            }
+          }
+
+          // For non-done statuses, clean up worktree if one exists (without merging)
+          if (newStatus !== 'done' && worktree && worktree.status === 'active') {
+            try {
+              // Clean up worktree without merging (deleteBranch=false to preserve work)
+              const cleanupResult = await worktreeFacade.stopWork(worktree.id, {
+                repoPath: getGitRoot(),
+                db: db,
+                deleteBranch: false  // Keep branch for cancelled/blocked work
+              });
+
+              if (cleanupResult.success) {
+                console.log(`✓ Cleaned up worktree: ${worktree.worktree_path}`);
+                console.log(`  Branch preserved: ${worktree.branch_name}`);
+              }
+            } catch (cleanupErr) {
+              console.warn(`Warning: Failed to cleanup worktree: ${cleanupErr.message}`);
+            }
+          }
+
+          // Check if this completes all stable mode chores for the parent feature
+          checkStableModeCompletion(db, currentWork, newStatus, (completionErr) => {
+            if (completionErr) {
+              console.warn(`Warning: ${completionErr.message}`);
+            }
+
+            try {
+              clearCurrentWork();
+            } catch (unlinkErr) {
+              return reject(new Error(`Failed to remove current work file: ${unlinkErr.message}`));
+            }
+
+            console.log(`Stopped work on #${currentWork.id}, status set to ${newStatus}`);
+            resolve({ id: currentWork.id, status: newStatus });
+          });
+        });
+      });
+      }
+    } else {
+      try {
+        clearCurrentWork();
+      } catch (err) {
+        return reject(new Error(`Failed to remove current work file: ${err.message}`));
+      }
+
+      console.log(`Stopped work on #${currentWork.id}`);
+      resolve({ id: currentWork.id });
+    }
+  });
+}
+
+/**
+ * Validate mode transition before marking work item as done
+ * @param {Object} db - Database connection
+ * @param {Object} currentWork - Current work item being completed
+ * @param {Function} callback - Callback function (err) => void
+ */
+function validateModeTransition(db, currentWork, callback) {
+  // Input validation - ensure we have valid parameters
+  if (!db || typeof db.get !== 'function') {
+    return callback(new Error('Invalid database connection provided to validateModeTransition'));
+  }
+
+  if (!currentWork || typeof currentWork !== 'object') {
+    return callback(new Error('Invalid currentWork object provided to validateModeTransition'));
+  }
+
+  if (!callback || typeof callback !== 'function') {
+    throw new Error('Callback function is required for validateModeTransition');
+  }
+
+  // Only validate features (chores inherit mode from parent)
+  if (currentWork.type !== 'feature') {
+    return callback(null);
+  }
+
+  // Validate currentWork.id exists
+  if (!currentWork.id) {
+    return callback(new Error('Current work item has no ID'));
+  }
+
+  // Get feature details including mode
+  db.get(`
+    SELECT id, title, mode, type
+    FROM work_items
+    WHERE id = ?
+  `, [currentWork.id], (err, feature) => {
+    if (err) {
+      return callback(new Error(`Failed to get feature details: ${err.message}`));
+    }
+
+    if (!feature) {
+      return callback(new Error(`Feature #${currentWork.id} not found`));
+    }
+
+    // Handle null or undefined mode - allow completion if no mode set
+    if (!feature.mode) {
+      return callback(null);
+    }
+
+    // Check if feature is in speed mode
+    if (feature.mode === 'speed') {
+      // Check if stable mode chores exist
+      db.get(`
+        SELECT COUNT(*) as stable_chore_count
+        FROM work_items
+        WHERE parent_id = ?
+          AND type = 'chore'
+          AND mode = 'stable'
+      `, [feature.id], (countErr, result) => {
+        if (countErr) {
+          return callback(new Error(`Failed to check stable chores: ${countErr.message}`));
+        }
+
+        // Validate result object
+        if (!result || typeof result.stable_chore_count !== 'number') {
+          return callback(new Error('Invalid result from stable chore count query'));
+        }
+
+        // If no stable chores exist, block completion
+        if (result.stable_chore_count === 0) {
+          const error = new Error(
+            `❌ Cannot mark speed mode feature as complete\n\n` +
+            `Speed mode features must transition to stable mode before completion.\n` +
+            `The speed mode implementation proves the happy path works, but the feature\n` +
+            `is incomplete without error handling, validation, and edge case coverage.\n\n` +
+            `Next steps:\n` +
+            `  1. Generate stable mode chores: jettypod work elevate ${feature.id} stable\n` +
+            `  2. Implement stable mode chores to add error handling\n` +
+            `  3. Then mark feature as complete\n\n` +
+            `To skip stable mode (not recommended):\n` +
+            `  jettypod work set-mode ${feature.id} stable --force\n` +
+            `  jettypod work complete ${feature.id}`
+          );
+          return callback(error);
+        }
+
+        // Stable chores exist, allow completion
+        callback(null);
+      });
+    } else if (feature.mode === 'stable') {
+      // Check if product is external - wrap in try-catch for config errors
+      let projectConfig;
+      let isExternal = false;
+
+      try {
+        projectConfig = config.read();
+        isExternal = projectConfig && projectConfig.project_state === 'external';
+      } catch (configErr) {
+        // If config can't be read, fail safe and don't block completion
+        console.warn(`Warning: Could not read project config: ${configErr.message}`);
+        console.warn('Assuming internal project - allowing completion without production mode');
+        return callback(null);
+      }
+
+      if (!isExternal) {
+        // Internal product, no production mode required
+        return callback(null);
+      }
+
+      // External product - check if production mode chores exist
+      db.get(`
+        SELECT COUNT(*) as production_chore_count
+        FROM work_items
+        WHERE parent_id = ?
+          AND type = 'chore'
+          AND mode = 'production'
+      `, [feature.id], (countErr, result) => {
+        if (countErr) {
+          return callback(new Error(`Failed to check production chores: ${countErr.message}`));
+        }
+
+        // Validate result object
+        if (!result || typeof result.production_chore_count !== 'number') {
+          return callback(new Error('Invalid result from production chore count query'));
+        }
+
+        // If no production chores exist, block completion
+        if (result.production_chore_count === 0) {
+          const error = new Error(
+            `❌ Cannot mark stable mode feature as complete for external product\n\n` +
+            `External products require production mode hardening before completion.\n` +
+            `Stable mode adds error handling, but production mode ensures the feature\n` +
+            `can handle real-world scale, security threats, and operational requirements.\n\n` +
+            `Next steps:\n` +
+            `  1. Generate production mode chores: jettypod work elevate ${feature.id} production\n` +
+            `  2. Implement production hardening (performance, security, monitoring)\n` +
+            `  3. Then mark feature as complete\n\n` +
+            `To skip production mode (not recommended for external products):\n` +
+            `  jettypod work set-mode ${feature.id} production --force\n` +
+            `  jettypod work complete ${feature.id}`
+          );
+          return callback(error);
+        }
+
+        // Production chores exist, allow completion
+        callback(null);
+      });
+    } else {
+      // Not in speed or stable mode, no validation needed
+      callback(null);
+    }
+  });
+}
+
+/**
+ * Check if stable mode is complete for a feature and trigger production chore generation
+ * @param {Object} db - Database connection
+ * @param {Object} currentWork - Current work item that was just completed
+ * @param {string} newStatus - Status that was just set
+ * @param {Function} callback - Callback function
+ */
+async function checkStableModeCompletion(db, currentWork, newStatus, callback) {
+  // Only check if:
+  // 1. Current work is a chore
+  // 2. Status was just set to 'done'
+  // 3. Current work has a parent (feature)
+  if (currentWork.type !== 'chore' || newStatus !== 'done' || !currentWork.parent_id) {
+    return callback(null);
+  }
+
+  // Get parent feature details and check its mode
+  db.get(`
+    SELECT id, title, mode, type
+    FROM work_items
+    WHERE id = ?
+  `, [currentWork.parent_id], async (err, parent) => {
+    if (err) {
+      return callback(new Error(`Failed to get parent feature: ${err.message}`));
+    }
+
+    if (!parent) {
+      return callback(new Error(`Parent feature #${currentWork.parent_id} not found`));
+    }
+
+    // Only proceed if parent is a feature in stable mode
+    if (parent.type !== 'feature' || parent.mode !== 'stable') {
+      return callback(null);
+    }
+
+    // Check if all stable chores for this feature are done
+    db.get(`
+      SELECT COUNT(*) as incomplete_count
+      FROM work_items
+      WHERE parent_id = ?
+        AND type = 'chore'
+        AND mode = 'stable'
+        AND status != 'done'
+    `, [parent.id], async (countErr, result) => {
+      if (countErr) {
+        return callback(new Error(`Failed to check stable chore completion: ${countErr.message}`));
+      }
+
+      // If all stable chores are done, stable mode is complete
+      if (result.incomplete_count === 0) {
+        console.log('');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('✅ STABLE MODE COMPLETE');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        console.log(`All stable chores for feature #${parent.id} "${parent.title}" are done.`);
+        console.log('');
+
+        // NOTE: Production mode transition is handled by the stable-mode skill
+        // The skill will:
+        //  1. Ask user if they want to add production scenarios
+        //  2. Add production scenarios to the feature file (BDD hot context)
+        //  3. Create production chores FROM those scenarios
+        //  4. Elevate feature to production mode
+        //
+        // Production chores are NOT auto-generated from git analysis.
+        // They come from BDD scenarios in the feature file.
+      }
+
+      callback(null);
+    });
+  });
+}
+
+/**
+ * Generate production chores and get user confirmation
+ * @param {Object} feature - Feature object with id and title
+ */
+async function generateAndConfirmProductionChores(feature) {
+  const { analyzeImplementation, generateProductionChores } = require('../../lib/production-chore-generator');
+  const readline = require('readline');
+
+  console.log('🔍 Analyzing implementation for production gaps...');
+  console.log('');
+
+  // Analyze implementation
+  let analysisResult;
+  try {
+    analysisResult = await analyzeImplementation(feature.id);
+  } catch (analysisErr) {
+    console.error(`Failed to analyze implementation: ${analysisErr.message}`);
+    return;
+  }
+
+  // Display warning if no git commits found
+  if (analysisResult.warning) {
+    console.log(`⚠️  ${analysisResult.warning}`);
+    console.log('');
+  }
+
+  console.log(`✅ Analyzed ${analysisResult.filesAnalyzed.length} implementation files`);
+  console.log('');
+
+  // Generate production chore proposals
+  const proposedChores = generateProductionChores(analysisResult, feature.title);
+
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('📋 PROPOSED PRODUCTION CHORES');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('These production chores will be created:');
+  console.log('');
+
+  proposedChores.forEach((chore, index) => {
+    console.log(`${index + 1}. ${chore.title}`);
+    console.log(`   ${chore.description.split('\n')[0]}`);
+    console.log('');
+  });
+
+  // Get user confirmation
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question('Create these production chores? (yes/skip): ', async (answer) => {
+      rl.close();
+
+      const response = answer.trim().toLowerCase();
+
+      if (response === 'yes' || response === 'y') {
+        console.log('');
+        console.log('Creating production chores...');
+
+        try {
+          await createProductionChoresAndElevate(feature, proposedChores);
+          console.log('');
+          console.log(`✅ Created ${proposedChores.length} production chores. Feature elevated to production mode.`);
+          console.log('');
+        } catch (createErr) {
+          console.error(`Failed to create production chores: ${createErr.message}`);
+        }
+      } else {
+        console.log('');
+        console.log('⏭️  Skipped production chore creation');
+        console.log('   You can generate them later by talking to Claude Code');
+        console.log('');
+      }
+
+      resolve();
+    });
+  });
+}
+
+/**
+ * Create production chores and elevate feature to production mode (if external)
+ * @param {Object} feature - Feature object
+ * @param {Array} proposedChores - Array of chore proposals
+ */
+async function createProductionChoresAndElevate(feature, proposedChores) {
+  const { create } = require('../work-tracking');
+  const projectConfig = config.read();
+
+  // Create production chores
+  for (const chore of proposedChores) {
+    await create('chore', chore.title, chore.description, feature.id, null, false);
+  }
+
+  // Always elevate feature to production mode
+  // (Feature #611 controls visibility in backlog, not mode elevation)
+  const db = getDb();
+  await new Promise((resolve, reject) => {
+    db.run('UPDATE work_items SET mode = ? WHERE id = ?', ['production', feature.id], (err) => {
+      if (err) return reject(err);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Clean up orphaned worktrees for completed work items
+ * @param {Object} options - Cleanup options
+ * @param {boolean} options.dryRun - If true, only show what would be cleaned up
+ * @returns {Promise<Object>} Cleanup results
+ */
+async function cleanupWorktrees(options = {}) {
+  const { dryRun = false } = options;
+  const db = getDb();
+
+  // Get all active worktrees with their work item statuses
+  const query = `
+    SELECT w.id as worktree_id, w.work_item_id, w.worktree_path, w.branch_name,
+           wi.status as work_status, wi.title
+    FROM worktrees w
+    JOIN work_items wi ON w.work_item_id = wi.id
+    WHERE w.status = 'active'
+    AND wi.status IN ('done', 'cancelled')
+  `;
+
+  const orphanedWorktrees = await new Promise((resolve, reject) => {
+    db.all(query, (err, rows) => {
+      if (err) reject(err);
+      else resolve(rows || []);
+    });
+  });
+
+  if (orphanedWorktrees.length === 0) {
+    return {
+      success: true,
+      cleaned: 0,
+      message: 'No orphaned worktrees found'
+    };
+  }
+
+  console.log(`\nFound ${orphanedWorktrees.length} orphaned worktrees:\n`);
+
+  const results = {
+    success: true,
+    cleaned: 0,
+    failed: 0,
+    errors: []
+  };
+
+  for (const wt of orphanedWorktrees) {
+    console.log(`  #${wt.work_item_id} (${wt.work_status}): ${wt.title}`);
+    console.log(`    Path: ${wt.worktree_path}`);
+    console.log(`    Branch: ${wt.branch_name}`);
+
+    if (dryRun) {
+      console.log(`    [DRY RUN] Would clean up`);
+      continue;
+    }
+
+    try {
+      const cleanupResult = await worktreeFacade.stopWork(wt.worktree_id, {
+        repoPath: getGitRoot(),
+        db: db,
+        deleteBranch: wt.work_status === 'done'  // Delete branch only for done items
+      });
+
+      if (cleanupResult.success) {
+        console.log(`    ✓ Cleaned up\n`);
+        results.cleaned++;
+      } else {
+        console.log(`    ⚠ Cleanup had warnings\n`);
+        results.cleaned++;
+      }
+    } catch (err) {
+      console.log(`    ✗ Failed: ${err.message}\n`);
+      results.failed++;
+      results.errors.push({ workItemId: wt.work_item_id, error: err.message });
+    }
+  }
+
+  return results;
+}
+
+// Re-export getCurrentWork from shared module for backwards compatibility
+// (used by jettypod.js)
+
+/**
+ * Merge current work into main branch
+ * Pushes feature branch, checks out main, merges, and pushes main
+ * Post-merge hook will mark work item as done and cleanup worktree
+ * @param {Object} options - Merge options
+ * @param {boolean} options.withTransition - Hold lock for transition phase (BDD generation)
+ * @param {boolean} options.releaseLock - Release held lock only (no merge)
+ * @returns {Promise<void|Object>} Returns {lockHeld: true} if withTransition, void otherwise
+ * @throws {Error} If no current work, git operations fail, or not in git repo
+ */
+async function mergeWork(options = {}) {
+  const { withTransition = false, releaseLock = false, featureBranch = null, workItemId = null } = options;
+
+  // Handle lock release-only mode first (can run from anywhere)
+  if (releaseLock) {
+    const mergeLock = require('../../lib/merge-lock');
+    const db = getDb();
+
+    console.log('⏳ Releasing merge lock...');
+    try {
+      await new Promise((resolve, reject) => {
+        db.run(
+          `DELETE FROM merge_locks`,
+          [],
+          (err) => {
+            if (err) return reject(err);
+            resolve();
+          }
+        );
+      });
+
+      console.log('✅ Merge lock released');
+      return Promise.resolve();
+    } catch (err) {
+      return Promise.reject(new Error(`Failed to release merge lock: ${err.message}`));
+    }
+  }
+
+  // CRITICAL: Refuse to run from inside a worktree
+  // Running merge from inside the worktree that will be deleted poisons the shell session
+  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'));
+  }
+
+  // Get current work - either from explicit ID or branch detection
+  let currentWork;
+  if (workItemId) {
+    // Explicit work item ID provided - look it up
+    const db = getDb();
+    currentWork = await new Promise((resolve, reject) => {
+      db.get(
+        `SELECT wi.id, wi.title, wi.type, wi.status, wi.parent_id, wi.epic_id
+         FROM work_items wi WHERE wi.id = ?`,
+        [workItemId],
+        (err, row) => {
+          if (err) return reject(err);
+          resolve(row);
+        }
+      );
+    });
+    if (!currentWork) {
+      return Promise.reject(new Error(`Work item #${workItemId} not found.`));
+    }
+  } else {
+    // No explicit ID - try branch detection
+    currentWork = await getCurrentWork();
+    if (!currentWork) {
+      return Promise.reject(new Error(
+        'No current work detected.\n\n' +
+        'Either:\n' +
+        '  1. Run from inside a worktree, or\n' +
+        '  2. Specify work item ID: jettypod work merge <id>'
+      ));
+    }
+  }
+
+  // Ensure we're in a git repo
+  let gitRoot;
+  try {
+    gitRoot = getGitRoot();
+  } catch (err) {
+    return Promise.reject(new Error('Not in a git repository'));
+  }
+
+  // Acquire merge lock to coordinate multiple instances
+  const mergeLock = require('../../lib/merge-lock');
+  const db = getDb();
+
+  console.log('⏳ Acquiring merge lock...');
+  let lock;
+  try {
+    lock = await mergeLock.acquireMergeLock(db, currentWork.id, null, {
+      maxWait: 120000,    // 2 minutes
+      pollInterval: 2000  // Check every 2 seconds
+    });
+    console.log('✅ Merge lock acquired');
+  } catch (lockErr) {
+    if (lockErr.message.includes('timeout')) {
+      return Promise.reject(new Error(
+        'Merge lock timeout: Another instance is merging.\n' +
+        'This usually resolves in 30-60 seconds. Please retry:\n' +
+        '  jettypod work merge'
+      ));
+    }
+    return Promise.reject(new Error(`Failed to acquire merge lock: ${lockErr.message}`));
+  }
+
+  // Wrap all merge operations in try/finally to ensure lock release
+  try {
+    // Get feature branch - either passed explicitly, from worktree DB, or from current CWD
+    let currentBranch;
+    if (featureBranch) {
+      // Branch passed from caller (e.g., status transition with worktree)
+      currentBranch = featureBranch;
+    } else if (workItemId) {
+      // Explicit work item ID - look up branch from worktrees table
+      const worktreeRecord = await new Promise((resolve, reject) => {
+        db.get(
+          `SELECT branch_name FROM worktrees WHERE work_item_id = ? AND status = 'active'`,
+          [workItemId],
+          (err, row) => {
+            if (err) return reject(err);
+            resolve(row);
+          }
+        );
+      });
+      if (!worktreeRecord) {
+        return Promise.reject(new Error(
+          `No active worktree found for work item #${workItemId}.\n\n` +
+          `The work item must have an active worktree to merge.`
+        ));
+      }
+      currentBranch = worktreeRecord.branch_name;
+    } else {
+      // Detect from current branch in CWD
+      try {
+        currentBranch = execSync('git branch --show-current', {
+          cwd: process.cwd(),
+          encoding: 'utf8',
+          stdio: 'pipe'
+        }).trim();
+      } catch (err) {
+        return Promise.reject(new Error(`Failed to get current branch: ${err.message}`));
+      }
+
+      if (!currentBranch) {
+        return Promise.reject(new Error('Not on a branch (detached HEAD?)'));
+      }
+
+      if (currentBranch === 'main' || currentBranch === 'master') {
+        return Promise.reject(new Error('Already on main branch. Cannot merge from main to main.'));
+      }
+    }
+
+    // Check for uncommitted changes
+    try {
+        const statusOutput = execSync('git status --porcelain', {
+        cwd: gitRoot,
+        encoding: 'utf8',
+        stdio: 'pipe'
+      }).trim();
+  
+      if (statusOutput) {
+        // Parse the status to show what's uncommitted
+        const lines = statusOutput.split('\n');
+        const staged = lines.filter(line => /^[MADRC]/.test(line));
+        const unstaged = lines.filter(line => /^.[MD]/.test(line));
+        // Ignore untracked files - they don't affect merging
+  
+        // Only fail on staged or unstaged changes (not untracked)
+        if (staged.length > 0 || unstaged.length > 0) {
+          let errorDetails = `Uncommitted changes detected in:\n  ${gitRoot}\n`;
+          if (staged.length > 0) {
+            errorDetails += `\nStaged files (${staged.length}):\n${staged.map(l => '  ' + l).join('\n')}`;
+          }
+          if (unstaged.length > 0) {
+            errorDetails += `\n\nUnstaged changes (${unstaged.length}):\n${unstaged.map(l => '  ' + l).join('\n')}`;
+          }
+
+          errorDetails += '\n\nTo proceed, run:\n';
+          errorDetails += `  cd ${gitRoot} && git add -A && git commit -m "your message"\n\n`;
+          errorDetails += 'Or stash them:\n';
+          errorDetails += `  cd ${gitRoot} && git stash\n\n`;
+          errorDetails += 'Then retry:\n';
+          errorDetails += '  jettypod work merge';
+
+          return Promise.reject(new Error(errorDetails));
+        }
+      }
+    } catch (err) {
+      return Promise.reject(new Error(`Failed to check git status: ${err.message}`));
+    }
+  
+    console.log(`Merging work item #${currentWork.id}: ${currentWork.title}`);
+    console.log(`Branch: ${currentBranch}`);
+  
+    // Step 1: Push feature branch to remote
+    try {
+      console.log('Pushing feature branch to remote...');
+      execSync(`git push -u origin ${currentBranch}`, {
+        cwd: gitRoot,
+        stdio: 'inherit'
+      });
+    } catch (err) {
+      const errorMsg = err.message.toLowerCase();
+      const isNetworkError = errorMsg.includes('could not resolve host') ||
+                            errorMsg.includes('failed to connect') ||
+                            errorMsg.includes('connection timed out') ||
+                            errorMsg.includes('network') ||
+                            errorMsg.includes('connection refused');
+  
+      if (isNetworkError) {
+        return Promise.reject(new Error(
+          `Network error while pushing feature branch.\n\n` +
+          `To resolve:\n` +
+          `1. Check network connection\n` +
+          `2. Retry: jettypod work merge\n` +
+          `\nIf network is working, check authentication:\n` +
+          `git config --get remote.origin.url`
+        ));
+      }
+  
+      return Promise.reject(new Error(`Failed to push feature branch: ${err.message}`));
+    }
+  
+    // Step 2: Detect and checkout default branch
+    let defaultBranch;
+    try {
+      // Try to get the default branch from git config
+      defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+        cwd: gitRoot,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim().replace('refs/remotes/origin/', '');
+    } catch {
+      // Fallback: check which common branch names exist
+      try {
+        execSync('git rev-parse --verify main', { cwd: gitRoot, stdio: 'pipe' });
+        defaultBranch = 'main';
+      } catch {
+        try {
+          execSync('git rev-parse --verify master', { cwd: gitRoot, stdio: 'pipe' });
+          defaultBranch = 'master';
+        } catch {
+          return Promise.reject(new Error('Could not detect default branch (tried main, master)'));
+        }
+      }
+    }
+  
+    try {
+      console.log(`Checking out ${defaultBranch}...`);
+      execSync(`git checkout ${defaultBranch}`, {
+        cwd: gitRoot,
+        stdio: 'inherit'
+      });
+    } catch (err) {
+      return Promise.reject(new Error(`Failed to checkout ${defaultBranch}: ${err.message}`));
+    }
+
+    // Step 3: Check for unpushed commits on local main before pulling
+    // This protects work being done directly on main by other instances
+    try {
+      execSync('git fetch origin', { cwd: gitRoot, stdio: 'pipe' });
+      const unpushed = execSync(`git log origin/${defaultBranch}..${defaultBranch} --oneline`, {
+        cwd: gitRoot,
+        encoding: 'utf8',
+        stdio: 'pipe'
+      }).trim();
+
+      if (unpushed) {
+        const commitCount = unpushed.split('\n').length;
+        return Promise.reject(new Error(
+          `Local ${defaultBranch} has ${commitCount} unpushed commit(s).\n\n` +
+          `This could indicate another instance is working on ${defaultBranch}.\n\n` +
+          `To resolve:\n` +
+          `1. Push local changes: git push origin ${defaultBranch}\n` +
+          `2. Or reset to remote: git reset --hard origin/${defaultBranch}\n` +
+          `3. Then retry: jettypod work merge`
+        ));
+      }
+    } catch (err) {
+      if (!err.message.includes('unpushed')) {
+        return Promise.reject(new Error(`Failed to check for unpushed commits: ${err.message}`));
+      }
+      throw err;
+    }
+
+    // Step 4: Pull latest default branch
+    try {
+      console.log(`Updating ${defaultBranch} from remote...`);
+      execSync(`git pull origin ${defaultBranch}`, {
+        cwd: gitRoot,
+        stdio: 'inherit'
+      });
+    } catch (err) {
+      const errorMsg = err.message.toLowerCase();
+      const isNetworkError = errorMsg.includes('could not resolve host') ||
+                            errorMsg.includes('failed to connect') ||
+                            errorMsg.includes('connection timed out') ||
+                            errorMsg.includes('network') ||
+                            errorMsg.includes('connection refused');
+  
+      if (isNetworkError) {
+        // We're already on main, so need to get back to feature branch
+        try {
+          execSync(`git checkout ${currentBranch}`, { cwd: gitRoot, stdio: 'pipe' });
+        } catch (checkoutErr) {
+          // Ignore checkout errors
+        }
+  
+        return Promise.reject(new Error(
+          `Network error while pulling main branch.\n\n` +
+          `Current state: Switched back to ${currentBranch}\n\n` +
+          `To resolve:\n` +
+          `1. Check network connection\n` +
+          `2. Retry: jettypod work merge`
+        ));
+      }
+  
+      // For non-network errors, still try to get back to feature branch
+      try {
+        execSync(`git checkout ${currentBranch}`, { cwd: gitRoot, stdio: 'pipe' });
+      } catch (checkoutErr) {
+        // Ignore checkout errors
+      }
+  
+      return Promise.reject(new Error(`Failed to pull ${defaultBranch}: ${err.message}`));
+    }
+  
+    // Step 4: Merge feature branch into default branch
+    try {
+      console.log(`Merging ${currentBranch} into ${defaultBranch}...`);
+      execSync(`git merge --no-ff ${currentBranch} -m "Merge work item #${currentWork.id}"`, {
+        cwd: gitRoot,
+        stdio: 'inherit'
+      });
+    } catch (err) {
+      // Check if merge failed due to conflicts
+      let hasConflicts = false;
+      try {
+        const statusOutput = execSync('git status', {
+          cwd: gitRoot,
+          encoding: 'utf8',
+          stdio: 'pipe'
+        });
+        hasConflicts = statusOutput.includes('Unmerged paths') ||
+                       statusOutput.includes('both modified') ||
+                       statusOutput.includes('Merge conflict');
+      } catch (statusErr) {
+        // Ignore status check errors
+      }
+  
+      if (hasConflicts) {
+        // Abort the merge and provide helpful error message
+        try {
+          execSync('git merge --abort', { cwd: gitRoot, stdio: 'pipe' });
+        } catch (abortErr) {
+          // Ignore abort errors
+        }
+  
+        return Promise.reject(new Error(
+          `Merge conflicts detected between ${currentBranch} and ${defaultBranch}.\n\n` +
+          `To resolve:\n` +
+          `1. Manually merge: git checkout ${defaultBranch} && git merge ${currentBranch}\n` +
+          `2. Resolve conflicts in the affected files\n` +
+          `3. Stage resolved files: git add <files>\n` +
+          `4. Complete merge: git commit\n` +
+          `5. Push: git push origin ${defaultBranch}\n` +
+          `6. Mark work as done: jettypod work status ${currentWork.id} done`
+        ));
+      }
+  
+      return Promise.reject(new Error(`Failed to merge ${currentBranch}: ${err.message}`));
+    }
+  
+    // Step 5: Push default branch to remote
+    try {
+      console.log(`Pushing ${defaultBranch} to remote...`);
+      execSync(`git push origin ${defaultBranch}`, {
+        cwd: gitRoot,
+        stdio: 'inherit'
+      });
+    } catch (err) {
+      const errorMsg = err.message.toLowerCase();
+      const isNetworkError = errorMsg.includes('could not resolve host') ||
+                            errorMsg.includes('failed to connect') ||
+                            errorMsg.includes('connection timed out') ||
+                            errorMsg.includes('network') ||
+                            errorMsg.includes('connection refused');
+  
+      if (isNetworkError) {
+        return Promise.reject(new Error(
+          `Network error while pushing merged ${defaultBranch} branch.\n\n` +
+          `Current state: ${defaultBranch} branch is merged locally but NOT pushed to remote\n` +
+          `Feature branch: ${currentBranch} (already pushed)\n\n` +
+          `To resolve:\n` +
+          `1. Check network connection\n` +
+          `2. Push ${defaultBranch} manually: git push origin ${defaultBranch}\n` +
+          `3. Mark work as done: jettypod work status ${currentWork.id} done`
+        ));
+      }
+  
+      return Promise.reject(new Error(`Failed to push ${defaultBranch}: ${err.message}`));
+    }
+  
+    console.log(`✓ Successfully merged work item #${currentWork.id}`);
+
+    if (withTransition) {
+      // Hold lock for transition phase (BDD generation)
+      console.log('⚠️  Merge lock held for transition phase');
+      console.log('   Skills will release lock after generating stable scenarios');
+      console.log('   Release lock with: jettypod work merge --release-lock');
+      return Promise.resolve({ lockHeld: true });
+    }
+
+    // Mark work item as done
+    console.log('Marking work item as done...');
+    await new Promise((resolve, reject) => {
+      db.run(
+        `UPDATE work_items SET status = 'done', completed_at = datetime('now') WHERE id = ?`,
+        [currentWork.id],
+        (err) => {
+          if (err) return reject(err);
+          resolve();
+        }
+      );
+    });
+
+    // Get worktree info from database
+    const worktree = await new Promise((resolve, reject) => {
+      db.get(
+        `SELECT id, worktree_path, branch_name FROM worktrees WHERE work_item_id = ? AND status = 'active'`,
+        [currentWork.id],
+        (err, row) => {
+          if (err) return reject(err);
+          resolve(row);
+        }
+      );
+    });
+
+    // Clean up worktree if it exists
+    if (worktree && worktree.worktree_path && fs.existsSync(worktree.worktree_path)) {
+      console.log('Cleaning up worktree...');
+      try {
+        // Remove the git worktree
+        execSync(`git worktree remove "${worktree.worktree_path}" --force`, {
+          cwd: gitRoot,
+          stdio: 'pipe'
+        });
+
+        // Delete worktree record from database
+        await new Promise((resolve, reject) => {
+          db.run(
+            `DELETE FROM worktrees WHERE id = ?`,
+            [worktree.id],
+            (err) => {
+              if (err) return reject(err);
+              resolve();
+            }
+          );
+        });
+
+        console.log('✅ Worktree cleaned up');
+      } catch (worktreeErr) {
+        console.warn(`Warning: Failed to clean up worktree: ${worktreeErr.message}`);
+        // Non-fatal - continue with merge success
+      }
+    }
+
+    console.log(`✅ Work item #${currentWork.id} marked as done`);
+    return Promise.resolve();
+  } finally {
+    // Release lock unless holding for transition
+    if (lock && !withTransition) {
+      try {
+        await lock.release();
+        console.log('✅ Merge lock released');
+      } catch (releaseErr) {
+        console.warn(`Warning: Failed to release merge lock: ${releaseErr.message}`);
+      }
+    }
+  }
+}
+
+module.exports = {
+  startWork,
+  stopWork,
+  getCurrentWork,
+  cleanupWorktrees,
+  mergeWork
+};