ai-sdlc 0.2.0-alpha.55 → 0.2.0-alpha.57

package/dist/cli/commands.d.ts

@@ -66,6 +66,7 @@ export declare function run(options: {
     watch?: boolean;
     force?: boolean;
     worktree?: boolean;
+    clean?: boolean;
 }): Promise<void>;
 /**
  * Phase information for RPIV display

package/dist/cli/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands.js

@@ -2,10 +2,11 @@ import ora from 'ora';
 import fs from 'fs';
 import path from 'path';
 import * as readline from 'readline';
+import { spawnSync } from 'child_process';
 import { getSdlcRoot, loadConfig, initConfig, validateWorktreeBasePath, DEFAULT_WORKTREE_CONFIG } from '../core/config.js';
 import { initializeKanban, kanbanExists, assessState, getBoardStats, findStoryBySlug, findStoriesByStatus } from '../core/kanban.js';
 import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory, getStory, findStoryById, updateStoryField, writeStory, sanitizeStoryId, autoCompleteStoryAfterReview, incrementImplementationRetryCount, getEffectiveMaxImplementationRetries, isAtMaxImplementationRetries, updateStoryStatus } from '../core/story.js';
-import { GitWorktreeService } from '../core/worktree.js';
+import { GitWorktreeService, getLastCompletedPhase, getNextPhase } from '../core/worktree.js';
 import { ReviewDecision } from '../types/index.js';
 import { getThemedChalk } from '../core/theme.js';
 import { saveWorkflowState, loadWorkflowState, clearWorkflowState, generateWorkflowId, calculateStoryHash, hasWorkflowState, } from '../core/workflow-state.js';
@@ -18,6 +19,13 @@ import { validateGitState } from '../core/git-utils.js';
 import { StoryLogger } from '../core/story-logger.js';
 import { detectConflicts } from '../core/conflict-detector.js';
 import { getLogger } from '../core/logger.js';
+/**
+ * Branch divergence threshold for warnings
+ * When a worktree branch has diverged by more than this number of commits
+ * from the base branch (ahead or behind), a warning will be displayed
+ * suggesting the user rebase to sync with latest changes.
+ */
+const DIVERGENCE_WARNING_THRESHOLD = 10;
 /**
  * Initialize the .ai-sdlc folder structure
  */
@@ -493,8 +501,8 @@ export async function preFlightConflictCheck(targetStory, sdlcRoot, options) {
     if (normalizedPath.length > 1024) {
         throw new Error('Invalid project path');
     }
-    // Check if target story is already in-progress
-    if (targetStory.frontmatter.status === 'in-progress') {
+    // Check if target story is already in-progress (allow if resuming existing worktree)
+    if (targetStory.frontmatter.status === 'in-progress' && !targetStory.frontmatter.worktree_path) {
         console.log(c.error('❌ Story is already in-progress'));
         return { proceed: false, warnings: ['Story already in progress'] };
     }
@@ -599,6 +607,7 @@ export async function run(options) {
         step: options.step,
         watch: options.watch,
         worktree: options.worktree,
+        clean: options.clean,
         force: options.force,
     });
     // Migrate global workflow state to story-specific location if needed
@@ -884,17 +893,154 @@ export async function run(options) {
         }
         const workingDir = path.dirname(sdlcRoot);
         // Check if story already has an existing worktree (resume scenario)
+        // Note: We check only if existingWorktreePath is set, not if it exists.
+        // The validation logic will handle missing directories/branches.
         const existingWorktreePath = targetStory.frontmatter.worktree_path;
-        if (existingWorktreePath && fs.existsSync(existingWorktreePath)) {
+        if (existingWorktreePath) {
+            // Validate worktree before resuming
+            const resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+            // Security validation: ensure worktree_path is within the configured base directory
+            const absoluteWorktreePath = path.resolve(existingWorktreePath);
+            const absoluteBasePath = path.resolve(resolvedBasePath);
+            if (!absoluteWorktreePath.startsWith(absoluteBasePath)) {
+                console.log(c.error('Security Error: worktree_path is outside configured base directory'));
+                console.log(c.dim(`  Worktree path: ${absoluteWorktreePath}`));
+                console.log(c.dim(`  Expected base: ${absoluteBasePath}`));
+                return;
+            }
+            // Warn if story is marked as done but has an existing worktree
+            if (targetStory.frontmatter.status === 'done') {
+                console.log(c.warning('⚠ Story is marked as done but has an existing worktree'));
+                console.log(c.dim('  This may be a stale worktree that should be cleaned up.'));
+                console.log();
+                // Prompt user for confirmation to proceed
+                const rl = readline.createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                });
+                const answer = await new Promise((resolve) => {
+                    rl.question(c.dim('Continue with this worktree? (y/N): '), (ans) => {
+                        rl.close();
+                        resolve(ans.toLowerCase().trim());
+                    });
+                });
+                if (answer !== 'y' && answer !== 'yes') {
+                    console.log(c.dim('Aborted. Consider removing the worktree_path from the story frontmatter.'));
+                    return;
+                }
+                console.log();
+            }
+            const worktreeService = new GitWorktreeService(workingDir, resolvedBasePath);
+            const branchName = worktreeService.getBranchName(targetStory.frontmatter.id, targetStory.slug);
+            const validation = worktreeService.validateWorktreeForResume(existingWorktreePath, branchName);
+            if (!validation.canResume) {
+                console.log(c.error('Cannot resume worktree:'));
+                validation.issues.forEach(issue => console.log(c.dim(`  ✗ ${issue}`)));
+                if (validation.requiresRecreation) {
+                    const branchExists = !validation.issues.includes('Branch does not exist');
+                    const dirMissing = validation.issues.includes('Worktree directory does not exist');
+                    const dirExists = !dirMissing;
+                    // Case 1: Directory missing but branch exists - recreate worktree from existing branch
+                    // Case 2: Directory exists but branch missing - recreate with new branch
+                    if ((branchExists && dirMissing) || (!branchExists && dirExists)) {
+                        const reason = branchExists
+                            ? 'Branch exists - automatically recreating worktree directory'
+                            : 'Directory exists - automatically recreating worktree with new branch';
+                        console.log(c.dim(`\n✓ ${reason}`));
+                        try {
+                            // Remove the old worktree reference if it exists
+                            const removeResult = spawnSync('git', ['worktree', 'remove', existingWorktreePath, '--force'], {
+                                cwd: workingDir,
+                                encoding: 'utf-8',
+                                shell: false,
+                                stdio: ['ignore', 'pipe', 'pipe'],
+                            });
+                            // Create the worktree at the same path
+                            // If branch exists, checkout that branch; otherwise create a new branch
+                            const baseBranch = worktreeService.detectBaseBranch();
+                            const worktreeAddArgs = branchExists
+                                ? ['worktree', 'add', existingWorktreePath, branchName]
+                                : ['worktree', 'add', '-b', branchName, existingWorktreePath, baseBranch];
+                            const addResult = spawnSync('git', worktreeAddArgs, {
+                                cwd: workingDir,
+                                encoding: 'utf-8',
+                                shell: false,
+                                stdio: ['ignore', 'pipe', 'pipe'],
+                            });
+                            if (addResult.status !== 0) {
+                                throw new Error(`Failed to recreate worktree: ${addResult.stderr}`);
+                            }
+                            // Install dependencies in the recreated worktree
+                            worktreeService.installDependencies(existingWorktreePath);
+                            console.log(c.success(`✓ Worktree recreated at ${existingWorktreePath}`));
+                            getLogger().info('worktree', `Recreated worktree for ${targetStory.frontmatter.id} at ${existingWorktreePath}`);
+                        }
+                        catch (error) {
+                            console.log(c.error(`Failed to recreate worktree: ${error instanceof Error ? error.message : String(error)}`));
+                            console.log(c.dim('Please manually remove the worktree_path from the story frontmatter and try again.'));
+                            return;
+                        }
+                    }
+                    else {
+                        console.log(c.dim('\nWorktree needs manual intervention. Please remove the worktree_path from the story frontmatter and try again.'));
+                        return;
+                    }
+                }
+                else {
+                    return;
+                }
+            }
             // Reuse existing worktree
             originalCwd = process.cwd();
             worktreePath = existingWorktreePath;
             process.chdir(worktreePath);
             sdlcRoot = getSdlcRoot();
             worktreeCreated = true;
+            // Re-load story from worktree context to get current state
+            const worktreeStory = findStoryById(sdlcRoot, targetStory.frontmatter.id);
+            if (worktreeStory) {
+                targetStory = worktreeStory;
+            }
+            // Get phase information for resume context
+            const lastPhase = getLastCompletedPhase(targetStory);
+            const nextPhase = getNextPhase(targetStory);
+            // Get worktree status for uncommitted changes info
+            const worktreeInfo = {
+                path: existingWorktreePath,
+                branch: branchName,
+                storyId: targetStory.frontmatter.id,
+                exists: true,
+            };
+            const worktreeStatus = worktreeService.getWorktreeStatus(worktreeInfo);
+            // Check branch divergence
+            const divergence = worktreeService.checkBranchDivergence(branchName);
             console.log(c.success(`✓ Resuming in existing worktree: ${worktreePath}`));
-            console.log(c.dim(`  Branch: ai-sdlc/${targetStory.frontmatter.id}-${targetStory.slug}`));
+            console.log(c.dim(`  Branch: ${branchName}`));
+            if (lastPhase) {
+                console.log(c.dim(`  Last completed phase: ${lastPhase}`));
+            }
+            if (nextPhase) {
+                console.log(c.dim(`  Next phase: ${nextPhase}`));
+            }
+            // Display uncommitted changes if present
+            if (worktreeStatus.workingDirectoryStatus !== 'clean') {
+                const totalChanges = worktreeStatus.modifiedFiles.length + worktreeStatus.untrackedFiles.length;
+                console.log(c.dim(`  Uncommitted changes: ${totalChanges} file(s)`));
+                if (worktreeStatus.modifiedFiles.length > 0) {
+                    console.log(c.dim(`    Modified: ${worktreeStatus.modifiedFiles.slice(0, 3).join(', ')}${worktreeStatus.modifiedFiles.length > 3 ? '...' : ''}`));
+                }
+                if (worktreeStatus.untrackedFiles.length > 0) {
+                    console.log(c.dim(`    Untracked: ${worktreeStatus.untrackedFiles.slice(0, 3).join(', ')}${worktreeStatus.untrackedFiles.length > 3 ? '...' : ''}`));
+                }
+            }
+            // Warn if branch has diverged significantly
+            if (divergence.diverged && (divergence.ahead > DIVERGENCE_WARNING_THRESHOLD || divergence.behind > DIVERGENCE_WARNING_THRESHOLD)) {
+                console.log(c.warning(`  ⚠ Branch has diverged from base: ${divergence.ahead} ahead, ${divergence.behind} behind`));
+                console.log(c.dim(`    Consider rebasing to sync with latest changes`));
+            }
             console.log();
+            // Log resume event
+            getLogger().info('worktree', `Resumed worktree for ${targetStory.frontmatter.id} at ${worktreePath}`);
         }
         else {
             // Create new worktree
@@ -913,55 +1059,256 @@ export async function run(options) {
             // This catches scenarios where workflow was interrupted after worktree creation
             // but before the story file was updated
             const existingWorktree = worktreeService.findByStoryId(targetStory.frontmatter.id);
+            let shouldCreateNewWorktree = !existingWorktree || !existingWorktree.exists;
             if (existingWorktree && existingWorktree.exists) {
-                const worktreeStatus = worktreeService.getWorktreeStatus(existingWorktree);
-                getLogger().info('worktree', `Detected existing worktree for ${targetStory.frontmatter.id} at ${existingWorktree.path}`);
-                displayExistingWorktreeInfo(worktreeStatus, c);
-                return;
-            }
-            // Validate git state for worktree creation
-            const validation = worktreeService.validateCanCreateWorktree();
-            if (!validation.valid) {
-                console.log(c.error(`Error: ${validation.error}`));
-                return;
-            }
-            try {
-                // Detect base branch
-                const baseBranch = worktreeService.detectBaseBranch();
-                // Create worktree
-                originalCwd = process.cwd();
-                worktreePath = worktreeService.create({
-                    storyId: targetStory.frontmatter.id,
-                    slug: targetStory.slug,
-                    baseBranch,
-                });
-                // Change to worktree directory BEFORE updating story
-                // This ensures story updates happen in the worktree, not on main
-                // (allows parallel story launches from clean main)
-                process.chdir(worktreePath);
-                // Recalculate sdlcRoot for the worktree context
-                sdlcRoot = getSdlcRoot();
-                worktreeCreated = true;
-                // Now update story frontmatter with worktree path (writes to worktree copy)
-                // Re-resolve target story in worktree context
-                const worktreeStory = findStoryById(sdlcRoot, targetStory.frontmatter.id);
-                if (worktreeStory) {
-                    const updatedStory = await updateStoryField(worktreeStory, 'worktree_path', worktreePath);
-                    await writeStory(updatedStory);
-                    // Update targetStory reference for downstream use
-                    targetStory = updatedStory;
+                // Handle --clean flag: cleanup and restart
+                if (options.clean) {
+                    console.log(c.warning('Existing worktree found - cleaning up before restart...'));
+                    console.log();
+                    const worktreeStatus = worktreeService.getWorktreeStatus(existingWorktree);
+                    const unpushedResult = worktreeService.hasUnpushedCommits(existingWorktree.path);
+                    const commitCount = worktreeService.getCommitCount(existingWorktree.path);
+                    const branchOnRemote = worktreeService.branchExistsOnRemote(existingWorktree.branch);
+                    // Display summary of what will be deleted
+                    console.log(c.bold('Cleanup Summary:'));
+                    console.log(c.dim('─'.repeat(60)));
+                    console.log(`${c.dim('Worktree Path:')}    ${worktreeStatus.path}`);
+                    console.log(`${c.dim('Branch:')}          ${worktreeStatus.branch}`);
+                    console.log(`${c.dim('Total Commits:')}   ${commitCount}`);
+                    console.log(`${c.dim('Unpushed Commits:')} ${unpushedResult.hasUnpushed ? c.warning(unpushedResult.count.toString()) : c.success('0')}`);
+                    console.log(`${c.dim('Modified Files:')}  ${worktreeStatus.modifiedFiles.length > 0 ? c.warning(worktreeStatus.modifiedFiles.length.toString()) : c.success('0')}`);
+                    console.log(`${c.dim('Untracked Files:')} ${worktreeStatus.untrackedFiles.length > 0 ? c.warning(worktreeStatus.untrackedFiles.length.toString()) : c.success('0')}`);
+                    console.log(`${c.dim('Remote Branch:')}   ${branchOnRemote ? c.warning('EXISTS') : c.dim('none')}`);
+                    console.log();
+                    // Warn about data loss
+                    if (worktreeStatus.modifiedFiles.length > 0 || worktreeStatus.untrackedFiles.length > 0 || unpushedResult.hasUnpushed) {
+                        console.log(c.error('⚠ WARNING: This will DELETE all uncommitted and unpushed work!'));
+                        console.log();
+                    }
+                    // Check for --force flag to skip confirmation
+                    const forceCleanup = options.force;
+                    if (!forceCleanup) {
+                        // Prompt for confirmation
+                        const confirmed = await new Promise((resolve) => {
+                            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                            rl.question(c.warning('Are you sure you want to proceed? (y/N): '), (answer) => {
+                                rl.close();
+                                resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+                            });
+                        });
+                        if (!confirmed) {
+                            console.log(c.info('Cleanup cancelled.'));
+                            return;
+                        }
+                    }
+                    console.log();
+                    const cleanupSpinner = ora('Cleaning up worktree...').start();
+                    try {
+                        // Remove worktree (force remove to handle uncommitted changes)
+                        const forceRemove = worktreeStatus.modifiedFiles.length > 0 || worktreeStatus.untrackedFiles.length > 0;
+                        worktreeService.remove(existingWorktree.path, forceRemove);
+                        cleanupSpinner.text = 'Worktree removed, deleting branch...';
+                        // Delete local branch
+                        worktreeService.deleteBranch(existingWorktree.branch, true);
+                        // Optionally delete remote branch if it exists
+                        if (branchOnRemote) {
+                            if (!forceCleanup) {
+                                cleanupSpinner.stop();
+                                const deleteRemote = await new Promise((resolve) => {
+                                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                                    rl.question(c.warning('Branch exists on remote. Delete it too? (y/N): '), (answer) => {
+                                        rl.close();
+                                        resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+                                    });
+                                });
+                                if (deleteRemote) {
+                                    cleanupSpinner.start('Deleting remote branch...');
+                                    worktreeService.deleteRemoteBranch(existingWorktree.branch);
+                                }
+                                cleanupSpinner.start();
+                            }
+                            else {
+                                // --force provided, skip remote deletion by default (safer)
+                                cleanupSpinner.text = 'Skipping remote branch deletion (use manual cleanup if needed)';
+                            }
+                        }
+                        // Reset story workflow state
+                        cleanupSpinner.text = 'Resetting story state...';
+                        const { resetWorkflowState } = await import('../core/story.js');
+                        targetStory = await resetWorkflowState(targetStory);
+                        // Clear workflow checkpoint if exists
+                        if (hasWorkflowState(sdlcRoot, targetStory.frontmatter.id)) {
+                            await clearWorkflowState(sdlcRoot, targetStory.frontmatter.id);
+                        }
+                        cleanupSpinner.succeed(c.success('✓ Cleanup complete - ready to create fresh worktree'));
+                        console.log();
+                    }
+                    catch (error) {
+                        cleanupSpinner.fail(c.error('Cleanup failed'));
+                        console.log(c.error(`Error: ${error instanceof Error ? error.message : String(error)}`));
+                        return;
+                    }
+                    // After cleanup, create a fresh worktree
+                    shouldCreateNewWorktree = true;
+                }
+                else {
+                    // Not cleaning - resume in existing worktree (S-0063 feature)
+                    getLogger().info('worktree', `Detected existing worktree for ${targetStory.frontmatter.id} at ${existingWorktree.path}`);
+                    // Validate the existing worktree before resuming
+                    const branchName = worktreeService.getBranchName(targetStory.frontmatter.id, targetStory.slug);
+                    const validation = worktreeService.validateWorktreeForResume(existingWorktree.path, branchName);
+                    if (!validation.canResume) {
+                        console.log(c.error('Detected existing worktree but cannot resume:'));
+                        validation.issues.forEach(issue => console.log(c.dim(`  ✗ ${issue}`)));
+                        if (validation.requiresRecreation) {
+                            const branchExists = !validation.issues.includes('Branch does not exist');
+                            const dirMissing = validation.issues.includes('Worktree directory does not exist');
+                            const dirExists = !dirMissing;
+                            // Case 1: Directory missing but branch exists - recreate worktree from existing branch
+                            // Case 2: Directory exists but branch missing - recreate with new branch
+                            if ((branchExists && dirMissing) || (!branchExists && dirExists)) {
+                                const reason = branchExists
+                                    ? 'Branch exists - automatically recreating worktree directory'
+                                    : 'Directory exists - automatically recreating worktree with new branch';
+                                console.log(c.dim(`\n✓ ${reason}`));
+                                try {
+                                    // Remove the old worktree reference if it exists
+                                    const removeResult = spawnSync('git', ['worktree', 'remove', existingWorktree.path, '--force'], {
+                                        cwd: workingDir,
+                                        encoding: 'utf-8',
+                                        shell: false,
+                                        stdio: ['ignore', 'pipe', 'pipe'],
+                                    });
+                                    // Create the worktree at the same path
+                                    // If branch exists, checkout that branch; otherwise create a new branch
+                                    const baseBranch = worktreeService.detectBaseBranch();
+                                    const worktreeAddArgs = branchExists
+                                        ? ['worktree', 'add', existingWorktree.path, branchName]
+                                        : ['worktree', 'add', '-b', branchName, existingWorktree.path, baseBranch];
+                                    const addResult = spawnSync('git', worktreeAddArgs, {
+                                        cwd: workingDir,
+                                        encoding: 'utf-8',
+                                        shell: false,
+                                        stdio: ['ignore', 'pipe', 'pipe'],
+                                    });
+                                    if (addResult.status !== 0) {
+                                        throw new Error(`Failed to recreate worktree: ${addResult.stderr}`);
+                                    }
+                                    // Install dependencies in the recreated worktree
+                                    worktreeService.installDependencies(existingWorktree.path);
+                                    console.log(c.success(`✓ Worktree recreated at ${existingWorktree.path}`));
+                                    getLogger().info('worktree', `Recreated worktree for ${targetStory.frontmatter.id} at ${existingWorktree.path}`);
+                                }
+                                catch (error) {
+                                    console.log(c.error(`Failed to recreate worktree: ${error instanceof Error ? error.message : String(error)}`));
+                                    console.log(c.dim('Please manually remove it with:'));
+                                    console.log(c.dim(`  git worktree remove ${existingWorktree.path}`));
+                                    return;
+                                }
+                            }
+                            else {
+                                console.log(c.dim('\nWorktree needs manual intervention. Please remove it manually with:'));
+                                console.log(c.dim(`  git worktree remove ${existingWorktree.path}`));
+                                return;
+                            }
+                        }
+                        else {
+                            return;
+                        }
+                    }
+                    // Automatically resume in the existing worktree
+                    originalCwd = process.cwd();
+                    worktreePath = existingWorktree.path;
+                    process.chdir(worktreePath);
+                    sdlcRoot = getSdlcRoot();
+                    worktreeCreated = true;
+                    // Update story frontmatter with worktree path (sync state)
+                    const worktreeStory = findStoryById(sdlcRoot, targetStory.frontmatter.id);
+                    if (worktreeStory) {
+                        const updatedStory = await updateStoryField(worktreeStory, 'worktree_path', worktreePath);
+                        await writeStory(updatedStory);
+                        targetStory = updatedStory;
+                    }
+                    // Get phase information for resume context
+                    const lastPhase = getLastCompletedPhase(targetStory);
+                    const nextPhase = getNextPhase(targetStory);
+                    // Get worktree status for uncommitted changes info
+                    const worktreeStatus = worktreeService.getWorktreeStatus(existingWorktree);
+                    // Check branch divergence
+                    const divergence = worktreeService.checkBranchDivergence(branchName);
+                    console.log(c.success(`✓ Resuming in existing worktree: ${worktreePath}`));
+                    console.log(c.dim(`  Branch: ${branchName}`));
+                    console.log(c.dim(`  (Worktree path synced to story frontmatter)`));
+                    if (lastPhase) {
+                        console.log(c.dim(`  Last completed phase: ${lastPhase}`));
+                    }
+                    if (nextPhase) {
+                        console.log(c.dim(`  Next phase: ${nextPhase}`));
+                    }
+                    // Display uncommitted changes if present
+                    if (worktreeStatus.workingDirectoryStatus !== 'clean') {
+                        const totalChanges = worktreeStatus.modifiedFiles.length + worktreeStatus.untrackedFiles.length;
+                        console.log(c.dim(`  Uncommitted changes: ${totalChanges} file(s)`));
+                        if (worktreeStatus.modifiedFiles.length > 0) {
+                            console.log(c.dim(`    Modified: ${worktreeStatus.modifiedFiles.slice(0, 3).join(', ')}${worktreeStatus.modifiedFiles.length > 3 ? '...' : ''}`));
+                        }
+                        if (worktreeStatus.untrackedFiles.length > 0) {
+                            console.log(c.dim(`    Untracked: ${worktreeStatus.untrackedFiles.slice(0, 3).join(', ')}${worktreeStatus.untrackedFiles.length > 3 ? '...' : ''}`));
+                        }
+                    }
+                    // Warn if branch has diverged significantly
+                    if (divergence.diverged && (divergence.ahead > DIVERGENCE_WARNING_THRESHOLD || divergence.behind > DIVERGENCE_WARNING_THRESHOLD)) {
+                        console.log(c.warning(`  ⚠ Branch has diverged from base: ${divergence.ahead} ahead, ${divergence.behind} behind`));
+                        console.log(c.dim(`    Consider rebasing to sync with latest changes`));
+                    }
+                    console.log();
                 }
-                console.log(c.success(`✓ Created worktree at: ${worktreePath}`));
-                console.log(c.dim(`  Branch: ai-sdlc/${targetStory.frontmatter.id}-${targetStory.slug}`));
-                console.log();
             }
-            catch (error) {
-                // Restore directory on worktree creation failure
-                if (originalCwd) {
-                    process.chdir(originalCwd);
+            if (shouldCreateNewWorktree) {
+                // Validate git state for worktree creation
+                const validation = worktreeService.validateCanCreateWorktree();
+                if (!validation.valid) {
+                    console.log(c.error(`Error: ${validation.error}`));
+                    return;
+                }
+                try {
+                    // Detect base branch
+                    const baseBranch = worktreeService.detectBaseBranch();
+                    // Create worktree
+                    originalCwd = process.cwd();
+                    worktreePath = worktreeService.create({
+                        storyId: targetStory.frontmatter.id,
+                        slug: targetStory.slug,
+                        baseBranch,
+                    });
+                    // Change to worktree directory BEFORE updating story
+                    // This ensures story updates happen in the worktree, not on main
+                    // (allows parallel story launches from clean main)
+                    process.chdir(worktreePath);
+                    // Recalculate sdlcRoot for the worktree context
+                    sdlcRoot = getSdlcRoot();
+                    worktreeCreated = true;
+                    // Now update story frontmatter with worktree path (writes to worktree copy)
+                    // Re-resolve target story in worktree context
+                    const worktreeStory = findStoryById(sdlcRoot, targetStory.frontmatter.id);
+                    if (worktreeStory) {
+                        const updatedStory = await updateStoryField(worktreeStory, 'worktree_path', worktreePath);
+                        await writeStory(updatedStory);
+                        // Update targetStory reference for downstream use
+                        targetStory = updatedStory;
+                    }
+                    console.log(c.success(`✓ Created worktree at: ${worktreePath}`));
+                    console.log(c.dim(`  Branch: ai-sdlc/${targetStory.frontmatter.id}-${targetStory.slug}`));
+                    console.log();
+                }
+                catch (error) {
+                    // Restore directory on worktree creation failure
+                    if (originalCwd) {
+                        process.chdir(originalCwd);
+                    }
+                    console.log(c.error(`Failed to create worktree: ${error instanceof Error ? error.message : String(error)}`));
+                    return;
                 }
-                console.log(c.error(`Failed to create worktree: ${error instanceof Error ? error.message : String(error)}`));
-                return;
             }
         }
     }