ai-sdlc 0.2.0 → 0.3.0-alpha.1

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 } from '../core/story.js';
-import { GitWorktreeService } from '../core/worktree.js';
+import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory, getStory, findStoryById, updateStoryField, writeStory, sanitizeStoryId, autoCompleteStoryAfterReview, incrementImplementationRetryCount, getEffectiveMaxImplementationRetries, isAtMaxImplementationRetries, updateStoryStatus } from '../core/story.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
  */
@@ -279,6 +287,35 @@ function validateAutoStoryOptions(options) {
             '  - ai-sdlc run --story <id> --step <phase> (single phase)');
     }
 }
+/**
+ * Validates flag combinations for --batch conflicts
+ * @throws Error if conflicting flags are detected
+ */
+function validateBatchOptions(options) {
+    if (!options.batch) {
+        return; // No batch flag, nothing to validate
+    }
+    // --batch and --story are mutually exclusive
+    if (options.story) {
+        throw new Error('Cannot combine --batch with --story flag.\n' +
+            'Use either:\n' +
+            '  - ai-sdlc run --batch S-001,S-002,S-003 (batch processing)\n' +
+            '  - ai-sdlc run --auto --story <id> (single story)');
+    }
+    // --batch and --watch are mutually exclusive
+    if (options.watch) {
+        throw new Error('Cannot combine --batch with --watch flag.\n' +
+            'Use either:\n' +
+            '  - ai-sdlc run --batch S-001,S-002,S-003 (batch processing)\n' +
+            '  - ai-sdlc run --watch (daemon mode)');
+    }
+    // --batch and --continue are mutually exclusive
+    if (options.continue) {
+        throw new Error('Cannot combine --batch with --continue flag.\n' +
+            'Batch mode does not support resuming from checkpoints.\n' +
+            'Use: ai-sdlc run --batch S-001,S-002,S-003');
+    }
+}
 /**
  * Determines if a specific phase should be executed based on story state
  * @param story The story to check
@@ -380,6 +417,51 @@ function displayGitValidationResult(result, c) {
         }
     }
 }
+/**
+ * Display detailed information about an existing worktree
+ */
+function displayExistingWorktreeInfo(status, c) {
+    console.log();
+    console.log(c.warning('A worktree already exists for this story:'));
+    console.log();
+    console.log(c.bold('  Worktree Path:'), status.path);
+    console.log(c.bold('  Branch:       '), status.branch);
+    if (status.lastCommit) {
+        console.log(c.bold('  Last Commit:  '), `${status.lastCommit.hash.substring(0, 7)} - ${status.lastCommit.message}`);
+        console.log(c.bold('  Committed:    '), status.lastCommit.timestamp);
+    }
+    const statusLabel = status.workingDirectoryStatus === 'clean'
+        ? c.success('clean')
+        : c.warning(status.workingDirectoryStatus);
+    console.log(c.bold('  Working Dir:  '), statusLabel);
+    if (status.modifiedFiles.length > 0) {
+        console.log();
+        console.log(c.warning('  Modified files:'));
+        for (const file of status.modifiedFiles.slice(0, 5)) {
+            console.log(c.dim(`    M ${file}`));
+        }
+        if (status.modifiedFiles.length > 5) {
+            console.log(c.dim(`    ... and ${status.modifiedFiles.length - 5} more`));
+        }
+    }
+    if (status.untrackedFiles.length > 0) {
+        console.log();
+        console.log(c.warning('  Untracked files:'));
+        for (const file of status.untrackedFiles.slice(0, 5)) {
+            console.log(c.dim(`    ? ${file}`));
+        }
+        if (status.untrackedFiles.length > 5) {
+            console.log(c.dim(`    ... and ${status.untrackedFiles.length - 5} more`));
+        }
+    }
+    console.log();
+    console.log(c.info('To resume work in this worktree:'));
+    console.log(c.dim(`  cd ${status.path}`));
+    console.log();
+    console.log(c.info('To remove the worktree and start fresh:'));
+    console.log(c.dim(`  ai-sdlc worktrees remove ${status.storyId}`));
+    console.log();
+}
 // ANSI escape sequence patterns for sanitization
 const ANSI_CSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
 const ANSI_OSC_BEL_PATTERN = /\x1B\][^\x07]*\x07/g;
@@ -448,8 +530,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'] };
     }
@@ -534,6 +616,149 @@ export async function preFlightConflictCheck(targetStory, sdlcRoot, options) {
         return { proceed: true, warnings: ['Conflict detection failed'] };
     }
 }
+/**
+ * Process multiple stories sequentially through full SDLC
+ * Internal function used by batch mode
+ */
+async function processBatchInternal(storyIds, sdlcRoot, options) {
+    const startTime = Date.now();
+    const config = loadConfig();
+    const c = getThemedChalk(config);
+    const { formatBatchProgress, formatBatchSummary, logStoryCompletion, promptContinueOnError } = await import('./batch-processor.js');
+    const result = {
+        total: storyIds.length,
+        succeeded: 0,
+        failed: 0,
+        skipped: 0,
+        errors: [],
+        duration: 0,
+    };
+    console.log();
+    console.log(c.bold('═══ Starting Batch Processing ═══'));
+    console.log(c.dim(`  Stories: ${storyIds.join(', ')}`));
+    console.log(c.dim(`  Dry run: ${options.dryRun ? 'yes' : 'no'}`));
+    console.log();
+    // Process each story sequentially
+    for (let i = 0; i < storyIds.length; i++) {
+        const storyId = storyIds[i];
+        // Get story and check status
+        let story;
+        try {
+            story = getStory(sdlcRoot, storyId);
+        }
+        catch (error) {
+            result.failed++;
+            result.errors.push({
+                storyId,
+                error: `Story not found: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            console.log(c.error(`[${i + 1}/${storyIds.length}] ✗ Story not found: ${storyId}`));
+            console.log();
+            // Ask if user wants to continue (or abort in non-interactive)
+            const shouldContinue = await promptContinueOnError(storyId, c);
+            if (!shouldContinue) {
+                console.log(c.warning('Batch processing aborted.'));
+                break;
+            }
+            continue;
+        }
+        // Skip if already done
+        if (story.frontmatter.status === 'done') {
+            result.skipped++;
+            console.log(c.dim(`[${i + 1}/${storyIds.length}] ⊘ Skipping ${storyId} (already completed)`));
+            console.log();
+            continue;
+        }
+        // Show progress header
+        const progress = {
+            currentIndex: i,
+            total: storyIds.length,
+            currentStory: story,
+        };
+        console.log(c.info(formatBatchProgress(progress)));
+        console.log();
+        // Dry-run mode: just show what would be done
+        if (options.dryRun) {
+            console.log(c.dim('  Would process story through full SDLC'));
+            console.log(c.dim(`  Status: ${story.frontmatter.status}`));
+            console.log();
+            result.succeeded++;
+            continue;
+        }
+        // Process story through full SDLC by recursively calling run()
+        // We set auto: true to ensure full SDLC execution
+        try {
+            await run({
+                auto: true,
+                story: storyId,
+                dryRun: false,
+                worktree: options.worktree,
+                force: options.force,
+            });
+            // Check if story completed successfully (moved to done)
+            const finalStory = getStory(sdlcRoot, storyId);
+            if (finalStory.frontmatter.status === 'done') {
+                result.succeeded++;
+                logStoryCompletion(storyId, true, c);
+            }
+            else {
+                // Story didn't reach done state - treat as failure
+                result.failed++;
+                result.errors.push({
+                    storyId,
+                    error: `Story did not complete (status: ${finalStory.frontmatter.status})`,
+                });
+                logStoryCompletion(storyId, false, c);
+                // Ask if user wants to continue (or abort in non-interactive)
+                const shouldContinue = await promptContinueOnError(storyId, c);
+                if (!shouldContinue) {
+                    console.log(c.warning('Batch processing aborted.'));
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            result.failed++;
+            result.errors.push({
+                storyId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            logStoryCompletion(storyId, false, c);
+            // Ask if user wants to continue (or abort in non-interactive)
+            const shouldContinue = await promptContinueOnError(storyId, c);
+            if (!shouldContinue) {
+                console.log(c.warning('Batch processing aborted.'));
+                break;
+            }
+        }
+        console.log();
+    }
+    // Display final summary
+    result.duration = Date.now() - startTime;
+    const summaryLines = formatBatchSummary(result);
+    summaryLines.forEach((line) => {
+        if (line.includes('✓')) {
+            console.log(c.success(line));
+        }
+        else if (line.includes('✗')) {
+            console.log(c.error(line));
+        }
+        else if (line.includes('⊘')) {
+            console.log(c.warning(line));
+        }
+        else if (line.startsWith('  -')) {
+            console.log(c.dim(line));
+        }
+        else {
+            console.log(line);
+        }
+    });
+    // Return non-zero exit code if any failures occurred
+    if (result.failed > 0) {
+        process.exitCode = 1;
+    }
+    return result;
+}
 /**
  * Run the workflow (process one action or all)
  */
@@ -554,6 +779,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
@@ -572,6 +798,51 @@ export async function run(options) {
         await startDaemon({ maxIterations: maxIterationsOverride });
         return; // Daemon runs indefinitely
     }
+    // Handle batch mode
+    if (options.batch) {
+        // Validate batch options first
+        try {
+            validateBatchOptions(options);
+        }
+        catch (error) {
+            console.log(c.error(`Error: ${error instanceof Error ? error.message : String(error)}`));
+            return;
+        }
+        // Import batch validation modules
+        const { parseStoryIdList, deduplicateStoryIds, validateStoryIds } = await import('./batch-validator.js');
+        // Parse and validate story IDs
+        const rawStoryIds = parseStoryIdList(options.batch);
+        if (rawStoryIds.length === 0) {
+            console.log(c.error('Error: Empty batch - no story IDs provided'));
+            console.log(c.dim('Usage: ai-sdlc run --batch S-001,S-002,S-003'));
+            return;
+        }
+        // Deduplicate story IDs
+        const storyIds = deduplicateStoryIds(rawStoryIds);
+        if (storyIds.length < rawStoryIds.length) {
+            const duplicateCount = rawStoryIds.length - storyIds.length;
+            console.log(c.dim(`Note: Removed ${duplicateCount} duplicate story ID(s)`));
+        }
+        // Validate all stories exist before processing
+        const validation = validateStoryIds(storyIds, sdlcRoot);
+        if (!validation.valid) {
+            console.log(c.error('Error: Batch validation failed'));
+            console.log();
+            for (const error of validation.errors) {
+                console.log(c.error(`  - ${error.message}`));
+            }
+            console.log();
+            console.log(c.dim('Fix the errors above and try again.'));
+            return;
+        }
+        // Process the batch using internal function
+        await processBatchInternal(storyIds, sdlcRoot, {
+            dryRun: options.dryRun,
+            worktree: options.worktree,
+            force: options.force,
+        });
+        return; // Batch processing complete
+    }
     // Valid step names for --step option
     const validSteps = ['refine', 'research', 'plan', 'implement', 'review'];
     // Validate --step option early
@@ -839,17 +1110,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
@@ -864,59 +1272,274 @@ export async function run(options) {
                 return;
             }
             const worktreeService = new GitWorktreeService(workingDir, resolvedBasePath);
-            // 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;
+            // Check for existing worktree NOT recorded in story frontmatter
+            // 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) {
+                // 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;
             }
         }
     }
     // Validate git state before processing actions that modify git
     // Skip protected branch check if worktree mode is active (worktree is on feature branch)
-    // Exclude .ai-sdlc/** from clean check when worktree was created (story file was just updated)
+    // Skip clean check entirely when worktree was just created:
+    // - The worktree starts from a clean base branch
+    // - npm install may modify package-lock.json
+    // - Story file was just updated with worktree_path
+    // - There's no prior user work to protect in a fresh worktree
     if (!options.force && requiresGitValidation(actionsToProcess)) {
         const workingDir = path.dirname(sdlcRoot);
         const gitValidationOptions = worktreeCreated
-            ? { skipBranchCheck: true, excludePatterns: ['.ai-sdlc/**'] }
+            ? { skipBranchCheck: true, skipCleanCheck: true }
             : {};
         const gitValidation = validateGitState(workingDir, gitValidationOptions);
         if (!gitValidation.valid) {
@@ -1013,6 +1636,56 @@ export async function run(options) {
                         return;
                     }
                 }
+                else if (reviewResult.decision === ReviewDecision.RECOVERY) {
+                    // Implementation recovery: reset implementation_complete and increment implementation retry count
+                    // This is distinct from REJECTED which resets the entire RPIV cycle
+                    const story = parseStory(action.storyPath);
+                    const config = loadConfig();
+                    const retryCount = story.frontmatter.implementation_retry_count || 0;
+                    const maxRetries = getEffectiveMaxImplementationRetries(story, config);
+                    const maxRetriesDisplay = Number.isFinite(maxRetries) ? maxRetries : '∞';
+                    console.log();
+                    console.log(c.warning(`🔄 Implementation recovery triggered (attempt ${retryCount + 1}/${maxRetriesDisplay})`));
+                    console.log(c.dim(`  Reason: ${story.frontmatter.last_restart_reason || 'No source code changes detected'}`));
+                    // Increment implementation retry count
+                    await incrementImplementationRetryCount(story);
+                    // Check if we've exceeded max implementation retries after incrementing
+                    const freshStory = parseStory(action.storyPath);
+                    if (isAtMaxImplementationRetries(freshStory, config)) {
+                        console.log();
+                        console.log(c.error('═'.repeat(50)));
+                        console.log(c.error(`✗ Implementation recovery failed - maximum retries reached`));
+                        console.log(c.error('═'.repeat(50)));
+                        console.log(c.dim(`Story has reached the maximum implementation retry limit (${maxRetries}).`));
+                        console.log(c.warning('Marking story as blocked. Manual intervention required.'));
+                        // Mark story as blocked
+                        await updateStoryStatus(freshStory, 'blocked');
+                        console.log(c.info('Story status updated to: blocked'));
+                        await clearWorkflowState(sdlcRoot, action.storyId);
+                        process.exit(1);
+                    }
+                    // Regenerate actions to restart from implementation phase
+                    const newActions = generateFullSDLCActions(freshStory, c);
+                    if (newActions.length > 0) {
+                        currentActions = newActions;
+                        currentActionIndex = 0;
+                        console.log(c.info(`  → Restarting from ${newActions[0].type} phase`));
+                        console.log();
+                        continue; // Restart the loop with new actions
+                    }
+                    else {
+                        console.log(c.error('Error: No actions generated for recovery. Manual intervention required.'));
+                        process.exit(1);
+                    }
+                }
+                else if (reviewResult.decision === ReviewDecision.FAILED) {
+                    // Review agent failed - don't increment retry count
+                    console.log();
+                    console.log(c.error(`✗ Review process failed: ${reviewResult.error || 'Unknown error'}`));
+                    console.log(c.warning('This does not count as a retry attempt. You can retry manually.'));
+                    await clearWorkflowState(sdlcRoot, action.storyId);
+                    process.exit(1);
+                }
             }
             // Save checkpoint after successful action
             if (actionResult.success) {
@@ -1230,6 +1903,53 @@ async function executeAction(action, sdlcRoot) {
                         }
                     },
                 });
+                // Auto-complete story if review was approved
+                if (result && result.success) {
+                    const reviewResult = result;
+                    let story = parseStory(action.storyPath);
+                    story = await autoCompleteStoryAfterReview(story, config, reviewResult);
+                    // Log auto-completion if it occurred
+                    if (reviewResult.decision === ReviewDecision.APPROVED && config.reviewConfig.autoCompleteOnApproval) {
+                        spinner.text = c.success('Review approved - auto-completing story');
+                        storyLogger?.log('INFO', `Story auto-completed after review approval: "${story.frontmatter.title}"`);
+                        // Auto-create PR in automated mode
+                        const workflowState = await loadWorkflowState(sdlcRoot, story.frontmatter.id);
+                        const isAutoMode = workflowState?.context.options.auto ?? false;
+                        if (isAutoMode || config.reviewConfig.autoCreatePROnApproval) {
+                            try {
+                                // Create PR (this will automatically commit any uncommitted changes)
+                                spinner.text = c.dim('Creating pull request...');
+                                const { createPullRequest } = await import('../agents/review.js');
+                                const prResult = await createPullRequest(action.storyPath, sdlcRoot);
+                                if (prResult.success) {
+                                    spinner.text = c.success('Review approved - PR created');
+                                    storyLogger?.log('INFO', `PR created successfully for ${story.frontmatter.id}`);
+                                }
+                                else {
+                                    // PR creation failed - mark as blocked
+                                    const { updateStoryStatus } = await import('../core/story.js');
+                                    const blockedStory = await updateStoryStatus(story, 'blocked');
+                                    await writeStory(blockedStory);
+                                    spinner.text = c.warning('Review approved but PR creation failed - story marked as blocked');
+                                    storyLogger?.log('WARN', `PR creation failed for ${story.frontmatter.id}: ${prResult.error || 'Unknown error'}`);
+                                }
+                            }
+                            catch (error) {
+                                // Error during PR creation - mark as blocked
+                                const { updateStoryStatus } = await import('../core/story.js');
+                                const blockedStory = await updateStoryStatus(story, 'blocked');
+                                await writeStory(blockedStory);
+                                const errorMsg = error instanceof Error ? error.message : String(error);
+                                spinner.text = c.warning(`Review approved but auto-PR failed: ${errorMsg}`);
+                                storyLogger?.log('ERROR', `Auto-PR failed for ${story.frontmatter.id}: ${errorMsg}`);
+                            }
+                        }
+                        // Handle worktree cleanup if story has a worktree
+                        if (story.frontmatter.worktree_path) {
+                            await handleWorktreeCleanup(story, config, c);
+                        }
+                    }
+                }
                 break;
             case 'rework':
                 const { runReworkAgent } = await import('../agents/rework.js');
@@ -1981,6 +2701,15 @@ async function handleWorktreeCleanup(story, config, c) {
         await writeStory(updated);
     }
 }
+/**
+ * Security: Escape shell arguments for safe use in commands
+ * For use with execSync when shell execution is required
+ * @internal Exported for testing
+ */
+export function escapeShellArg(arg) {
+    // Replace single quotes with '\'' and wrap in single quotes
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
 /**
  * List all ai-sdlc managed worktrees
  */