ai-sdlc 0.2.0-alpha.5 → 0.2.0-alpha.51

package/dist/cli/commands.js

@@ -1,9 +1,11 @@
 import ora from 'ora';
 import fs from 'fs';
 import path from 'path';
-import { getSdlcRoot, loadConfig, initConfig } from '../core/config.js';
-import { initializeKanban, kanbanExists, assessState, getBoardStats, findStoryBySlug } from '../core/kanban.js';
-import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory, getStory, findStoryById } from '../core/story.js';
+import * as readline from 'readline';
+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 } from '../core/story.js';
+import { GitWorktreeService } 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';
@@ -12,6 +14,10 @@ import { getStoryFlags as getStoryFlagsUtil, formatStatus as formatStatusUtil }
 import { migrateToFolderPerStory } from './commands/migrate.js';
 import { generateReviewSummary } from '../agents/review.js';
 import { getTerminalWidth } from './formatting.js';
+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';
 /**
  * Initialize the .ai-sdlc folder structure
  */
@@ -49,7 +55,7 @@ export async function status(options) {
         console.log(c.warning('ai-sdlc not initialized. Run `ai-sdlc init` first.'));
         return;
     }
-    const assessment = assessState(sdlcRoot);
+    const assessment = await assessState(sdlcRoot);
     const stats = getBoardStats(sdlcRoot);
     console.log();
     console.log(c.bold('═══ AI SDLC Board ═══'));
@@ -114,10 +120,58 @@ export async function status(options) {
         console.log(c.success('No pending actions. Board is up to date!'));
     }
 }
+/**
+ * Validate file path for security (path traversal, symlinks, allowed directories)
+ */
+function validateFilePath(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const allowedDir = path.resolve(process.cwd());
+    // Check path traversal: resolved path must be within current directory
+    if (!resolvedPath.startsWith(allowedDir + path.sep) && resolvedPath !== allowedDir) {
+        throw new Error('Security: File path must be within current directory (path traversal detected)');
+    }
+    // Check if file exists before checking if it's a symlink
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`File not found: ${path.basename(filePath)}`);
+    }
+    // Check for symbolic links (security risk)
+    const stats = fs.lstatSync(resolvedPath);
+    if (stats.isSymbolicLink()) {
+        throw new Error('Security: Symbolic links are not allowed');
+    }
+}
+/**
+ * Validate file extension against whitelist
+ */
+function validateFileExtension(filePath) {
+    const allowedExtensions = ['.md', '.txt', '.markdown'];
+    const ext = path.extname(filePath).toLowerCase();
+    if (!allowedExtensions.includes(ext)) {
+        throw new Error(`Invalid file type: only ${allowedExtensions.join(', ')} files are allowed`);
+    }
+}
+/**
+ * Validate file size (10MB maximum)
+ */
+function validateFileSize(filePath) {
+    const maxSize = 10 * 1024 * 1024; // 10MB
+    const stats = fs.statSync(filePath);
+    if (stats.size > maxSize) {
+        const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
+        throw new Error(`File too large: ${sizeMB}MB (maximum 10MB)`);
+    }
+}
+/**
+ * Sanitize file content (strip null bytes, validate UTF-8)
+ */
+function sanitizeFileContent(content) {
+    // Strip null bytes that could truncate strings
+    return content.replace(/\0/g, '');
+}
 /**
  * Add a new story to the backlog
  */
-export async function add(title) {
+export async function add(title, options) {
     const spinner = ora('Creating story...').start();
     try {
         const config = loadConfig();
@@ -127,10 +181,83 @@ export async function add(title) {
             spinner.fail('ai-sdlc not initialized. Run `ai-sdlc init` first.');
             return;
         }
-        const story = createStory(title, sdlcRoot);
+        // Validate that either title or file is provided (not both, not neither)
+        if (!title && !options?.file) {
+            spinner.fail('Error: Must provide either a title or --file option');
+            console.log(c.dim('Usage:'));
+            console.log(c.dim('  ai-sdlc add "Story Title"'));
+            console.log(c.dim('  ai-sdlc add --file story.md'));
+            process.exit(1);
+        }
+        if (title && options?.file) {
+            spinner.fail('Error: Cannot provide both title and --file option');
+            console.log(c.dim('Use either:'));
+            console.log(c.dim('  ai-sdlc add "Story Title"'));
+            console.log(c.dim('  ai-sdlc add --file story.md'));
+            process.exit(1);
+        }
+        let storyTitle;
+        let storyContent;
+        // Handle file input with security validation
+        if (options?.file) {
+            spinner.text = 'Reading file...';
+            const filePath = options.file;
+            try {
+                // Security validations
+                validateFilePath(filePath);
+                validateFileExtension(filePath);
+                // Read file (includes existence check via fs.readFileSync)
+                const resolvedPath = path.resolve(filePath);
+                // Validate file size before reading
+                validateFileSize(resolvedPath);
+                // Read and sanitize content
+                const rawContent = fs.readFileSync(resolvedPath, 'utf-8');
+                storyContent = sanitizeFileContent(rawContent);
+                // Extract title from content or use filename
+                const { extractTitleFromContent } = await import('../core/story.js');
+                const extractedTitle = extractTitleFromContent(storyContent);
+                if (extractedTitle) {
+                    storyTitle = extractedTitle;
+                }
+                else {
+                    // Fall back to filename without extension
+                    storyTitle = path.basename(filePath, path.extname(filePath));
+                }
+                spinner.text = `Creating story from ${path.basename(filePath)}...`;
+            }
+            catch (error) {
+                spinner.fail('Failed to read file');
+                if (error instanceof Error) {
+                    // Sanitize error messages to avoid leaking system paths
+                    if (error.message.startsWith('Security:') || error.message.startsWith('Invalid file type:') || error.message.startsWith('File too large:')) {
+                        console.log(c.error(error.message));
+                    }
+                    else if (error.message.includes('ENOENT')) {
+                        console.log(c.error(`File not found: ${path.basename(filePath)}`));
+                    }
+                    else if (error.message.includes('EACCES') || error.message.includes('EPERM')) {
+                        console.log(c.error(`Permission denied: ${path.basename(filePath)}`));
+                    }
+                    else {
+                        console.log(c.error(`Unable to read file: ${path.basename(filePath)}`));
+                    }
+                }
+                process.exit(1);
+            }
+        }
+        else {
+            // Traditional title-only input
+            storyTitle = title;
+        }
+        // Create the story
+        const story = await createStory(storyTitle, sdlcRoot, {}, storyContent);
         spinner.succeed(c.success(`Created: ${story.path}`));
         console.log(c.dim(`  ID: ${story.frontmatter.id}`));
+        console.log(c.dim(`  Title: ${story.frontmatter.title}`));
         console.log(c.dim(`  Slug: ${story.slug}`));
+        if (options?.file) {
+            console.log(c.dim(`  Source: ${path.basename(options.file)}`));
+        }
         console.log();
         console.log(c.info('Next step:'), `ai-sdlc run`);
     }
@@ -205,6 +332,208 @@ function generateFullSDLCActions(story, c) {
     }
     return actions;
 }
+/**
+ * Actions that modify git and require validation
+ */
+const GIT_MODIFYING_ACTIONS = ['implement', 'review', 'create_pr'];
+/**
+ * Check if any actions in the list require git validation
+ */
+function requiresGitValidation(actions) {
+    return actions.some(action => GIT_MODIFYING_ACTIONS.includes(action.type));
+}
+/**
+ * Determine if worktree mode should be used based on CLI flags, story frontmatter, and config.
+ * Priority order:
+ * 1. CLI --no-worktree flag (explicit disable)
+ * 2. CLI --worktree flag (explicit enable)
+ * 3. Story frontmatter.worktree_path exists (auto-enable for resuming)
+ * 4. Config worktree.enabled (default behavior)
+ */
+export function determineWorktreeMode(options, worktreeConfig, targetStory) {
+    if (options.worktree === false)
+        return false;
+    if (options.worktree === true)
+        return true;
+    if (targetStory?.frontmatter.worktree_path)
+        return true;
+    return worktreeConfig.enabled;
+}
+/**
+ * Display git validation errors and warnings
+ */
+function displayGitValidationResult(result, c) {
+    if (result.errors.length > 0) {
+        console.log();
+        console.log(c.error('Git validation failed:'));
+        for (const error of result.errors) {
+            console.log(c.error(`  - ${error}`));
+        }
+        console.log();
+        console.log(c.info('To override this check, use --force (at your own risk)'));
+    }
+    if (result.warnings.length > 0) {
+        console.log();
+        console.log(c.warning('Git validation warnings:'));
+        for (const warning of result.warnings) {
+            console.log(c.warning(`  - ${warning}`));
+        }
+    }
+}
+// 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;
+const ANSI_OSC_ESC_PATTERN = /\x1B\][^\x1B]*\x1B\\/g;
+const ANSI_SINGLE_CHAR_PATTERN = /\x1B./g;
+const CONTROL_CHARS_PATTERN = /[\x00-\x1F\x7F-\x9F]/g;
+/**
+ * Sanitize a string for safe display in the terminal.
+ * Strips ANSI escape sequences (CSI, OSC, single-char), control characters,
+ * and truncates extremely long strings to prevent DoS attacks.
+ *
+ * This uses the same comprehensive ANSI stripping patterns as sanitizeReasonText
+ * from src/core/story.ts for consistency.
+ *
+ * @param str - The string to sanitize
+ * @returns Sanitized string safe for terminal display (max 500 chars)
+ */
+function sanitizeForDisplay(str) {
+    const cleaned = str
+        .replace(ANSI_CSI_PATTERN, '') // CSI sequences (e.g., \x1B[31m)
+        .replace(ANSI_OSC_BEL_PATTERN, '') // OSC with BEL terminator (e.g., \x1B]...\x07)
+        .replace(ANSI_OSC_ESC_PATTERN, '') // OSC with ESC\ terminator (e.g., \x1B]...\x1B\\)
+        .replace(ANSI_SINGLE_CHAR_PATTERN, '') // Single-char escapes (e.g., \x1BH)
+        .replace(CONTROL_CHARS_PATTERN, ''); // Control characters (0x00-0x1F, 0x7F-0x9F)
+    // Truncate extremely long strings (DoS protection)
+    return cleaned.length > 500 ? cleaned.slice(0, 497) + '...' : cleaned;
+}
+/**
+ * Perform pre-flight conflict check before starting work on a story in a worktree.
+ * Warns about potential file conflicts with active stories and prompts for confirmation.
+ *
+ * **Race Condition (TOCTOU):** Multiple users can pass this check simultaneously
+ * before branches are created. This is an accepted risk - the window is small
+ * (~100ms) and git will catch conflicts during merge/PR creation. Adding file
+ * locks would significantly increase complexity for minimal security gain.
+ *
+ * **Security Notes:**
+ * - sdlcRoot is normalized and validated (absolute path, no null bytes, max 1024 chars)
+ * - All display output is sanitized to prevent terminal injection attacks
+ * - Story IDs are validated with sanitizeStoryId() then stripped with sanitizeForDisplay()
+ * - Error messages are generic to prevent information leakage
+ *
+ * @param targetStory - The story to check for conflicts
+ * @param sdlcRoot - Root directory of the .ai-sdlc folder (must be absolute, validated)
+ * @param options - Command options (force flag)
+ * @param options.force - Skip conflict check if true
+ * @returns PreFlightResult indicating whether to proceed and any warnings
+ * @throws Error if sdlcRoot is invalid (not absolute, null bytes, too long)
+ */
+export async function preFlightConflictCheck(targetStory, sdlcRoot, options) {
+    const config = loadConfig();
+    const c = getThemedChalk(config);
+    // Skip if --force flag
+    if (options.force) {
+        console.log(c.warning('⚠️  Skipping conflict check (--force)'));
+        return { proceed: true, warnings: ['Conflict check skipped'] };
+    }
+    // Validate sdlcRoot parameter (normalize first to prevent bypass attacks)
+    const normalizedPath = path.normalize(sdlcRoot);
+    if (!path.isAbsolute(normalizedPath)) {
+        throw new Error('Invalid project path');
+    }
+    if (normalizedPath.includes('\0')) {
+        throw new Error('Invalid project path');
+    }
+    if (normalizedPath.length > 1024) {
+        throw new Error('Invalid project path');
+    }
+    // Check if target story is already in-progress
+    if (targetStory.frontmatter.status === 'in-progress') {
+        console.log(c.error('❌ Story is already in-progress'));
+        return { proceed: false, warnings: ['Story already in progress'] };
+    }
+    try {
+        // Query for all in-progress stories (excluding target)
+        // Use normalizedPath for all subsequent operations
+        const activeStories = findStoriesByStatus(normalizedPath, 'in-progress')
+            .filter(s => s.frontmatter.id !== targetStory.frontmatter.id);
+        if (activeStories.length === 0) {
+            console.log(c.success('✓ Conflict check: No overlapping files with active stories'));
+            return { proceed: true, warnings: [] };
+        }
+        // Run conflict detection (use normalizedPath)
+        const workingDir = path.dirname(normalizedPath);
+        const result = detectConflicts([targetStory, ...activeStories], workingDir, 'main');
+        // Filter conflicts involving target story
+        const relevantConflicts = result.conflicts.filter(conflict => conflict.storyA === targetStory.frontmatter.id || conflict.storyB === targetStory.frontmatter.id);
+        // Filter out 'none' severity conflicts (keep all displayable conflicts including low)
+        const displayableConflicts = relevantConflicts.filter(conflict => conflict.severity !== 'none');
+        if (displayableConflicts.length === 0) {
+            console.log(c.success('✓ Conflict check: No overlapping files with active stories'));
+            return { proceed: true, warnings: [] };
+        }
+        // Sort conflicts by severity (high -> medium -> low)
+        const severityOrder = { high: 0, medium: 1, low: 2, none: 3 };
+        const sortedConflicts = displayableConflicts.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+        // Display conflicts
+        console.log();
+        console.log(c.warning('⚠️  Potential conflicts detected:'));
+        console.log();
+        for (const conflict of sortedConflicts) {
+            const otherStoryId = conflict.storyA === targetStory.frontmatter.id ? conflict.storyB : conflict.storyA;
+            // Two-stage sanitization: validate structure, then strip for display
+            try {
+                const validatedTargetId = sanitizeStoryId(targetStory.frontmatter.id);
+                const validatedOtherId = sanitizeStoryId(otherStoryId);
+                const sanitizedTargetId = sanitizeForDisplay(validatedTargetId);
+                const sanitizedOtherId = sanitizeForDisplay(validatedOtherId);
+                console.log(c.warning(`   ${sanitizedTargetId} may conflict with ${sanitizedOtherId}:`));
+            }
+            catch (error) {
+                // If validation fails, show generic error (defensive)
+                console.log(c.warning(`   Story may have conflicting changes (invalid ID format)`));
+            }
+            // Display shared files
+            for (const file of conflict.sharedFiles) {
+                const severityLabel = conflict.severity === 'high' ? c.error('High') :
+                    conflict.severity === 'medium' ? c.warning('Medium') :
+                        c.info('Low');
+                const sanitizedFile = sanitizeForDisplay(file);
+                console.log(`   - ${severityLabel}: ${sanitizedFile} (both stories modify this file)`);
+            }
+            // Display shared directories
+            for (const dir of conflict.sharedDirectories) {
+                const severityLabel = conflict.severity === 'high' ? c.error('High') :
+                    conflict.severity === 'medium' ? c.warning('Medium') :
+                        c.info('Low');
+                const sanitizedDir = sanitizeForDisplay(dir);
+                console.log(`   - ${severityLabel}: ${sanitizedDir} (both stories modify files in this directory)`);
+            }
+            console.log();
+            const sanitizedRecommendation = sanitizeForDisplay(conflict.recommendation);
+            console.log(c.dim(`   Recommendation: ${sanitizedRecommendation}`));
+            console.log();
+        }
+        // Non-interactive mode: default to declining
+        if (!process.stdin.isTTY) {
+            console.log(c.dim('Non-interactive mode: conflicts require --force to proceed'));
+            return { proceed: false, warnings: ['Conflicts detected'] };
+        }
+        // Interactive mode: prompt user
+        const shouldContinue = await confirmRemoval('Continue anyway?');
+        return {
+            proceed: shouldContinue,
+            warnings: shouldContinue ? ['User confirmed with conflicts'] : ['Conflicts detected']
+        };
+    }
+    catch (error) {
+        // Fail-open: allow proceeding if conflict detection fails
+        console.log(c.warning('⚠️  Conflict detection unavailable'));
+        console.log(c.dim('Proceeding without conflict check...'));
+        return { proceed: true, warnings: ['Conflict detection failed'] };
+    }
+}
 /**
  * Run the workflow (process one action or all)
  */
@@ -214,8 +543,28 @@ export async function run(options) {
     const maxIterationsOverride = options.maxIterations !== undefined
         ? parseInt(options.maxIterations, 10)
         : undefined;
-    const sdlcRoot = getSdlcRoot();
+    let sdlcRoot = getSdlcRoot();
     const c = getThemedChalk(config);
+    const logger = getLogger();
+    logger.debug('workflow', 'Run command initiated', {
+        auto: options.auto,
+        dryRun: options.dryRun,
+        continue: options.continue,
+        story: options.story,
+        step: options.step,
+        watch: options.watch,
+        worktree: options.worktree,
+        force: options.force,
+    });
+    // Migrate global workflow state to story-specific location if needed
+    // Only run when NOT continuing (to avoid interrupting resumed workflows)
+    if (!options.continue) {
+        const { migrateGlobalWorkflowState } = await import('../core/workflow-state.js');
+        const migrationResult = await migrateGlobalWorkflowState(sdlcRoot);
+        if (migrationResult.migrated) {
+            console.log(c.info(migrationResult.message));
+        }
+    }
     // Handle daemon/watch mode
     if (options.watch) {
         console.log(c.info('🚀 Starting daemon mode...'));
@@ -253,8 +602,15 @@ export async function run(options) {
     let completedActions = [];
     let storyContentHash;
     if (options.continue) {
-        // Try to load existing state
-        const existingState = await loadWorkflowState(sdlcRoot);
+        // Determine storyId for loading state
+        // If --story is provided, use it; otherwise, try to infer from existing state
+        let resumeStoryId;
+        // First try: use --story flag if provided
+        if (options.story) {
+            resumeStoryId = options.story;
+        }
+        // Try to load existing state (with or without storyId)
+        const existingState = await loadWorkflowState(sdlcRoot, resumeStoryId);
         if (!existingState) {
             console.log(c.error('Error: No checkpoint found.'));
             console.log(c.dim('Remove --continue flag to start a new workflow.'));
@@ -300,20 +656,37 @@ export async function run(options) {
         console.log();
     }
     else {
+        // Early validation of story ID format before any operations that use it
+        // This prevents sanitizeStoryId from throwing before we can show a nice error
+        if (options.story && !/^[a-z0-9_-]+$/i.test(options.story.toLowerCase().trim())) {
+            console.log(c.error('Invalid story ID format. Only letters, numbers, hyphens, and underscores are allowed.'));
+            return;
+        }
         // Check if there's an existing state and suggest --continue
-        if (hasWorkflowState(sdlcRoot) && !options.dryRun) {
+        // Check both global and story-specific state
+        const hasGlobalState = hasWorkflowState(sdlcRoot);
+        const hasStoryState = options.story ? hasWorkflowState(sdlcRoot, options.story) : false;
+        if ((hasGlobalState || hasStoryState) && !options.dryRun) {
             console.log(c.info('Note: Found previous checkpoint. Use --continue to resume.'));
             console.log();
         }
         // Start new workflow
         workflowId = generateWorkflowId();
     }
-    let assessment = assessState(sdlcRoot);
+    let assessment = await assessState(sdlcRoot);
+    // Hoist targetStory to outer scope so it can be reused for worktree checks
+    let targetStory = null;
     // Filter actions by story if --story flag is provided
     if (options.story) {
         const normalizedInput = options.story.toLowerCase().trim();
+        // SECURITY: Validate story ID format to prevent path traversal and injection
+        // Only allow alphanumeric characters, hyphens, and underscores
+        if (!/^[a-z0-9_-]+$/i.test(normalizedInput)) {
+            console.log(c.error('Invalid story ID format. Only letters, numbers, hyphens, and underscores are allowed.'));
+            return;
+        }
         // Try to find story by ID first, then by slug (case-insensitive)
-        let targetStory = findStoryById(sdlcRoot, normalizedInput);
+        targetStory = findStoryById(sdlcRoot, normalizedInput);
         if (!targetStory) {
             targetStory = findStoryBySlug(sdlcRoot, normalizedInput);
         }
@@ -385,7 +758,8 @@ export async function run(options) {
         }
         // Clear state if workflow is complete
         if (options.continue || hasWorkflowState(sdlcRoot)) {
-            await clearWorkflowState(sdlcRoot);
+            // Using options.story - action not yet created in early exit path
+            await clearWorkflowState(sdlcRoot, options.story);
             console.log(c.dim('Checkpoint cleared.'));
         }
         return;
@@ -426,163 +800,304 @@ export async function run(options) {
         actionsToProcess = remainingActions;
         if (actionsToProcess.length === 0) {
             console.log(c.success('All actions from checkpoint already completed!'));
-            await clearWorkflowState(sdlcRoot);
+            // Using options.story - action not yet created in early exit path
+            await clearWorkflowState(sdlcRoot, options.story);
             console.log(c.dim('Checkpoint cleared.'));
             return;
         }
     }
-    // Process actions with retry support for Full SDLC mode
-    let currentActions = [...actionsToProcess];
-    let currentActionIndex = 0;
-    let retryAttempt = 0;
-    const MAX_DISPLAY_RETRIES = 3; // For display purposes
-    while (currentActionIndex < currentActions.length) {
-        const action = currentActions[currentActionIndex];
-        const totalActions = currentActions.length;
-        // Enhanced progress indicator for full SDLC mode
-        if (isFullSDLC && totalActions > 1) {
-            const retryIndicator = retryAttempt > 0 ? ` (retry ${retryAttempt})` : '';
-            console.log(c.info(`\n═══ Phase ${currentActionIndex + 1}/${totalActions}: ${action.type.toUpperCase()}${retryIndicator} ═══`));
-        }
-        const actionResult = await executeAction(action, sdlcRoot);
-        // Handle action failure in full SDLC mode
-        if (!actionResult.success && isFullSDLC) {
-            console.log();
-            console.log(c.error(`✗ Phase ${action.type} failed`));
-            console.log(c.dim(`Completed ${currentActionIndex} of ${totalActions} phases`));
-            console.log(c.info('Fix the error above and use --continue to resume.'));
+    // Handle worktree creation based on flags, config, and story frontmatter
+    // IMPORTANT: This must happen BEFORE git validation because:
+    // 1. Worktree mode allows running from protected branches (main/master)
+    // 2. The worktree will be created on a feature branch
+    let worktreePath;
+    let originalCwd;
+    let worktreeCreated = false;
+    // Determine if worktree should be used
+    // Priority: CLI flags > story frontmatter > config > default (disabled)
+    const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
+    // Reuse targetStory from earlier lookup (DRY - avoids duplicate story lookup)
+    const shouldUseWorktree = determineWorktreeMode(options, worktreeConfig, targetStory);
+    // Validate that worktree mode requires --story
+    if (shouldUseWorktree && !options.story) {
+        if (options.worktree === true) {
+            console.log(c.error('Error: --worktree requires --story flag'));
             return;
         }
-        // Handle review rejection in Full SDLC mode - trigger retry loop
-        if (isFullSDLC && action.type === 'review' && actionResult.reviewResult) {
-            const reviewResult = actionResult.reviewResult;
-            if (reviewResult.decision === ReviewDecision.REJECTED) {
-                // Load fresh story state and config for retry check
-                const story = parseStory(action.storyPath);
-                const config = loadConfig();
-                // Check if we're at max retries (pass CLI override if provided)
-                if (isAtMaxRetries(story, config, maxIterationsOverride)) {
-                    console.log();
-                    console.log(c.error('═'.repeat(50)));
-                    console.log(c.error(`✗ Review failed - maximum retries reached`));
-                    console.log(c.error('═'.repeat(50)));
-                    console.log(c.dim(`Story has reached the maximum retry limit.`));
-                    console.log(c.dim(`Issues found: ${reviewResult.issues.length}`));
-                    console.log(c.warning('Manual intervention required to address the review feedback.'));
-                    console.log(c.info('You can:'));
-                    console.log(c.dim('  1. Fix issues manually and run again'));
-                    console.log(c.dim('  2. Reset retry count in the story frontmatter'));
-                    await clearWorkflowState(sdlcRoot);
-                    return;
+    }
+    if (shouldUseWorktree && options.story && targetStory) {
+        // PRE-FLIGHT CHECK: Run conflict detection before creating worktree
+        const preFlightResult = await preFlightConflictCheck(targetStory, sdlcRoot, options);
+        if (!preFlightResult.proceed) {
+            console.log(c.error('❌ Aborting. Complete active stories first or use --force.'));
+            return;
+        }
+        // Log warnings if user proceeded despite conflicts (skip internal flag messages)
+        if (preFlightResult.warnings.length > 0 && !preFlightResult.warnings.includes('Conflict check skipped')) {
+            preFlightResult.warnings.forEach(w => console.log(c.dim(`  ⚠ ${w}`)));
+            console.log();
+        }
+        const workingDir = path.dirname(sdlcRoot);
+        // Check if story already has an existing worktree (resume scenario)
+        const existingWorktreePath = targetStory.frontmatter.worktree_path;
+        if (existingWorktreePath && fs.existsSync(existingWorktreePath)) {
+            // Reuse existing worktree
+            originalCwd = process.cwd();
+            worktreePath = existingWorktreePath;
+            process.chdir(worktreePath);
+            sdlcRoot = getSdlcRoot();
+            worktreeCreated = true;
+            console.log(c.success(`✓ Resuming in existing worktree: ${worktreePath}`));
+            console.log(c.dim(`  Branch: ai-sdlc/${targetStory.frontmatter.id}-${targetStory.slug}`));
+            console.log();
+        }
+        else {
+            // Create new worktree
+            // Resolve worktree base path from config
+            let resolvedBasePath;
+            try {
+                resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+            }
+            catch (error) {
+                console.log(c.error(`Configuration Error: ${error instanceof Error ? error.message : String(error)}`));
+                console.log(c.dim('Fix worktree.basePath in .ai-sdlc.json or remove it to use default location'));
+                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;
                 }
-                // We can retry - reset RPIV cycle and loop back
-                const currentRetry = (story.frontmatter.retry_count || 0) + 1;
-                // Use CLI override, then story-specific, then config default
-                const effectiveMaxRetries = maxIterationsOverride !== undefined
-                    ? maxIterationsOverride
-                    : (story.frontmatter.max_retries ?? config.reviewConfig?.maxRetries ?? Infinity);
-                const maxRetriesDisplay = Number.isFinite(effectiveMaxRetries) ? effectiveMaxRetries : '∞';
+                console.log(c.success(`✓ Created worktree at: ${worktreePath}`));
+                console.log(c.dim(`  Branch: ai-sdlc/${targetStory.frontmatter.id}-${targetStory.slug}`));
                 console.log();
-                console.log(c.warning(`⟳ Review rejected with ${reviewResult.issues.length} issue(s) - initiating rework (attempt ${currentRetry}/${maxRetriesDisplay})`));
-                // Display executive summary
-                const summary = generateReviewSummary(reviewResult.issues, getTerminalWidth());
-                console.log(c.dim(`  Summary: ${summary}`));
-                // Reset the RPIV cycle (this increments retry_count and resets flags)
-                resetRPIVCycle(story, reviewResult.feedback);
-                // Log what's being reset
-                console.log(c.dim(`  → Reset plan_complete, implementation_complete, reviews_complete`));
-                console.log(c.dim(`  → Retry count: ${currentRetry}/${maxRetriesDisplay}`));
-                // Regenerate actions starting from the phase that needs rework
-                // For now, we restart from 'plan' since that's the typical flow after research
-                const freshStory = parseStory(action.storyPath);
-                const newActions = generateFullSDLCActions(freshStory, c);
-                if (newActions.length > 0) {
-                    // Replace remaining actions with the new sequence
-                    currentActions = newActions;
-                    currentActionIndex = 0;
-                    retryAttempt++;
-                    console.log(c.info(`  → Restarting SDLC from ${newActions[0].type} phase`));
-                    console.log();
-                    continue; // Restart the loop with new actions
-                }
-                else {
-                    // No actions to retry (shouldn't happen but handle gracefully)
-                    console.log(c.error('Error: No actions generated for retry. Manual intervention required.'));
-                    return;
+            }
+            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;
             }
         }
-        // Save checkpoint after successful action
-        if (actionResult.success) {
-            completedActions.push({
-                type: action.type,
-                storyId: action.storyId,
-                storyPath: action.storyPath,
-                completedAt: new Date().toISOString(),
-            });
-            const state = {
-                version: '1.0',
-                workflowId,
-                timestamp: new Date().toISOString(),
-                currentAction: null,
-                completedActions,
-                context: {
-                    sdlcRoot,
-                    options: {
-                        auto: options.auto,
-                        dryRun: options.dryRun,
-                        story: options.story,
-                        fullSDLC: isFullSDLC,
-                    },
-                    storyContentHash: calculateStoryHash(action.storyPath),
-                },
-            };
-            await saveWorkflowState(state, sdlcRoot);
-            console.log(c.dim(`  ✓ Progress saved (${completedActions.length} actions completed)`));
-        }
-        currentActionIndex++;
-        // Re-assess after each action in auto mode
-        if (options.auto) {
-            // For full SDLC mode, check if all phases are complete (and review passed)
-            if (isFullSDLC) {
-                // Check if we've completed all actions in our sequence
-                if (currentActionIndex >= currentActions.length) {
-                    // Verify the review actually passed (reviews_complete should be true)
-                    const finalStory = parseStory(action.storyPath);
-                    if (finalStory.frontmatter.reviews_complete) {
+    }
+    // Validate git state before processing actions that modify git
+    // Skip protected branch check if worktree mode is active (worktree is on feature branch)
+    // 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, skipCleanCheck: true }
+            : {};
+        const gitValidation = validateGitState(workingDir, gitValidationOptions);
+        if (!gitValidation.valid) {
+            displayGitValidationResult(gitValidation, c);
+            if (worktreeCreated && originalCwd) {
+                process.chdir(originalCwd);
+            }
+            return;
+        }
+        if (gitValidation.warnings.length > 0) {
+            displayGitValidationResult(gitValidation, c);
+            console.log();
+        }
+    }
+    // Process actions with retry support for Full SDLC mode
+    let currentActions = [...actionsToProcess];
+    let currentActionIndex = 0;
+    let retryAttempt = 0;
+    const MAX_DISPLAY_RETRIES = 3; // For display purposes
+    try {
+        while (currentActionIndex < currentActions.length) {
+            const action = currentActions[currentActionIndex];
+            const totalActions = currentActions.length;
+            // Enhanced progress indicator for full SDLC mode
+            if (isFullSDLC && totalActions > 1) {
+                const retryIndicator = retryAttempt > 0 ? ` (retry ${retryAttempt})` : '';
+                console.log(c.info(`\n═══ Phase ${currentActionIndex + 1}/${totalActions}: ${action.type.toUpperCase()}${retryIndicator} ═══`));
+            }
+            const actionResult = await executeAction(action, sdlcRoot);
+            // Handle action failure in full SDLC mode
+            if (!actionResult.success && isFullSDLC) {
+                console.log();
+                console.log(c.error(`✗ Phase ${action.type} failed`));
+                console.log(c.dim(`Completed ${currentActionIndex} of ${totalActions} phases`));
+                console.log(c.info('Fix the error above and use --continue to resume.'));
+                return;
+            }
+            // Handle review rejection in Full SDLC mode - trigger retry loop
+            if (isFullSDLC && action.type === 'review' && actionResult.reviewResult) {
+                const reviewResult = actionResult.reviewResult;
+                if (reviewResult.decision === ReviewDecision.REJECTED) {
+                    // Load fresh story state and config for retry check
+                    const story = parseStory(action.storyPath);
+                    const config = loadConfig();
+                    // Check if we're at max retries (pass CLI override if provided)
+                    if (isAtMaxRetries(story, config, maxIterationsOverride)) {
                         console.log();
-                        console.log(c.success('═'.repeat(50)));
-                        console.log(c.success(`✓ Full SDLC completed successfully!`));
-                        console.log(c.success('═'.repeat(50)));
-                        console.log(c.dim(`Completed phases: ${currentActions.length}`));
-                        if (retryAttempt > 0) {
-                            console.log(c.dim(`Retry attempts: ${retryAttempt}`));
-                        }
-                        console.log(c.dim(`Story is now ready for PR creation.`));
-                        await clearWorkflowState(sdlcRoot);
-                        console.log(c.dim('Checkpoint cleared.'));
+                        console.log(c.error('═'.repeat(50)));
+                        console.log(c.error(`✗ Review failed - maximum retries reached`));
+                        console.log(c.error('═'.repeat(50)));
+                        console.log(c.dim(`Story has reached the maximum retry limit.`));
+                        console.log(c.dim(`Issues found: ${reviewResult.issues.length}`));
+                        console.log(c.warning('Manual intervention required to address the review feedback.'));
+                        console.log(c.info('You can:'));
+                        console.log(c.dim('  1. Fix issues manually and run again'));
+                        console.log(c.dim('  2. Reset retry count in the story frontmatter'));
+                        // Using action.storyId - available from action loop context
+                        await clearWorkflowState(sdlcRoot, action.storyId);
+                        return;
                     }
-                    else {
-                        // This shouldn't happen if our logic is correct, but handle it
+                    // We can retry - reset RPIV cycle and loop back
+                    const currentRetry = (story.frontmatter.retry_count || 0) + 1;
+                    // Use CLI override, then story-specific, then config default
+                    const effectiveMaxRetries = maxIterationsOverride !== undefined
+                        ? maxIterationsOverride
+                        : (story.frontmatter.max_retries ?? config.reviewConfig?.maxRetries ?? Infinity);
+                    const maxRetriesDisplay = Number.isFinite(effectiveMaxRetries) ? effectiveMaxRetries : '∞';
+                    console.log();
+                    console.log(c.warning(`⟳ Review rejected with ${reviewResult.issues.length} issue(s) - initiating rework (attempt ${currentRetry}/${maxRetriesDisplay})`));
+                    // Display executive summary
+                    const summary = generateReviewSummary(reviewResult.issues, getTerminalWidth());
+                    console.log(c.dim(`  Summary: ${summary}`));
+                    // Reset the RPIV cycle (this increments retry_count and resets flags)
+                    await resetRPIVCycle(story, reviewResult.feedback);
+                    // Log what's being reset
+                    console.log(c.dim(`  → Reset plan_complete, implementation_complete, reviews_complete`));
+                    console.log(c.dim(`  → Retry count: ${currentRetry}/${maxRetriesDisplay}`));
+                    // Regenerate actions starting from the phase that needs rework
+                    // For now, we restart from 'plan' since that's the typical flow after research
+                    const freshStory = parseStory(action.storyPath);
+                    const newActions = generateFullSDLCActions(freshStory, c);
+                    if (newActions.length > 0) {
+                        // Replace remaining actions with the new sequence
+                        currentActions = newActions;
+                        currentActionIndex = 0;
+                        retryAttempt++;
+                        console.log(c.info(`  → Restarting SDLC from ${newActions[0].type} phase`));
                         console.log();
-                        console.log(c.warning('All phases executed but reviews_complete is false.'));
-                        console.log(c.dim('This may indicate an issue with the review process.'));
+                        continue; // Restart the loop with new actions
+                    }
+                    else {
+                        // No actions to retry (shouldn't happen but handle gracefully)
+                        console.log(c.error('Error: No actions generated for retry. Manual intervention required.'));
+                        return;
                     }
-                    break;
                 }
             }
-            else {
-                // Normal auto mode: re-assess state
-                const newAssessment = assessState(sdlcRoot);
-                if (newAssessment.recommendedActions.length === 0) {
-                    console.log(c.success('\n✓ All actions completed!'));
-                    await clearWorkflowState(sdlcRoot);
-                    console.log(c.dim('Checkpoint cleared.'));
-                    break;
+            // Save checkpoint after successful action
+            if (actionResult.success) {
+                completedActions.push({
+                    type: action.type,
+                    storyId: action.storyId,
+                    storyPath: action.storyPath,
+                    completedAt: new Date().toISOString(),
+                });
+                const state = {
+                    version: '1.0',
+                    workflowId,
+                    timestamp: new Date().toISOString(),
+                    currentAction: null,
+                    completedActions,
+                    context: {
+                        sdlcRoot,
+                        options: {
+                            auto: options.auto,
+                            dryRun: options.dryRun,
+                            story: options.story,
+                            fullSDLC: isFullSDLC,
+                        },
+                        storyContentHash: calculateStoryHash(action.storyPath),
+                    },
+                };
+                await saveWorkflowState(state, sdlcRoot, action.storyId);
+                console.log(c.dim(`  ✓ Progress saved (${completedActions.length} actions completed)`));
+            }
+            currentActionIndex++;
+            // Re-assess after each action in auto mode
+            if (options.auto) {
+                // For full SDLC mode, check if all phases are complete (and review passed)
+                if (isFullSDLC) {
+                    // Check if we've completed all actions in our sequence
+                    if (currentActionIndex >= currentActions.length) {
+                        // Verify the review actually passed (reviews_complete should be true)
+                        const finalStory = parseStory(action.storyPath);
+                        if (finalStory.frontmatter.reviews_complete) {
+                            console.log();
+                            console.log(c.success('═'.repeat(50)));
+                            console.log(c.success(`✓ Full SDLC completed successfully!`));
+                            console.log(c.success('═'.repeat(50)));
+                            console.log(c.dim(`Completed phases: ${currentActions.length}`));
+                            if (retryAttempt > 0) {
+                                console.log(c.dim(`Retry attempts: ${retryAttempt}`));
+                            }
+                            console.log(c.dim(`Story is now ready for PR creation.`));
+                            // Using action.storyId - available from action loop context
+                            await clearWorkflowState(sdlcRoot, action.storyId);
+                            console.log(c.dim('Checkpoint cleared.'));
+                        }
+                        else {
+                            // This shouldn't happen if our logic is correct, but handle it
+                            console.log();
+                            console.log(c.warning('All phases executed but reviews_complete is false.'));
+                            console.log(c.dim('This may indicate an issue with the review process.'));
+                        }
+                        break;
+                    }
+                }
+                else {
+                    // Normal auto mode: re-assess state
+                    const newAssessment = await assessState(sdlcRoot);
+                    if (newAssessment.recommendedActions.length === 0) {
+                        console.log(c.success('\n✓ All actions completed!'));
+                        // Using action.storyId - available from action loop context
+                        await clearWorkflowState(sdlcRoot, action.storyId);
+                        console.log(c.dim('Checkpoint cleared.'));
+                        break;
+                    }
                 }
             }
         }
     }
+    finally {
+        // Restore original working directory if worktree was used
+        if (originalCwd) {
+            process.chdir(originalCwd);
+        }
+    }
 }
 /**
  * Execute a specific action
@@ -592,61 +1107,91 @@ export async function run(options) {
 async function executeAction(action, sdlcRoot) {
     const config = loadConfig();
     const c = getThemedChalk(config);
-    // Resolve story by ID to get current path (handles moves between folders)
-    let resolvedPath;
+    const globalLogger = getLogger();
+    const actionStartTime = Date.now();
+    // Log action start to global logger
+    globalLogger.info('action', `Starting action: ${action.type}`, {
+        storyId: action.storyId,
+        actionType: action.type,
+        storyPath: action.storyPath,
+    });
+    // Initialize per-story logger
+    const maxLogs = config.logging?.maxFiles ?? 5;
+    let storyLogger = null;
+    let spinner = null;
     try {
-        const story = getStory(sdlcRoot, action.storyId);
-        resolvedPath = story.path;
+        storyLogger = new StoryLogger(action.storyId, sdlcRoot, maxLogs);
+        storyLogger.log('INFO', `Starting action: ${action.type} for story ${action.storyId}`);
     }
     catch (error) {
-        console.log(c.error(`Error: Story not found for action "${action.type}"`));
-        console.log(c.dim(`  Story ID: ${action.storyId}`));
-        console.log(c.dim(`  Original path: ${action.storyPath}`));
-        if (error instanceof Error) {
-            console.log(c.dim(`  ${error.message}`));
-        }
-        return { success: false };
+        // If logger initialization fails, continue without logging (console-only)
+        console.warn(`Warning: Failed to initialize logger: ${error instanceof Error ? error.message : String(error)}`);
     }
-    // Update action path if it was stale
-    if (resolvedPath !== action.storyPath) {
-        console.log(c.warning(`Note: Story path updated (file was moved)`));
-        console.log(c.dim(`  From: ${action.storyPath}`));
-        console.log(c.dim(`  To: ${resolvedPath}`));
-        action.storyPath = resolvedPath;
-    }
-    // Store phase completion state BEFORE action execution (to detect transitions)
-    const storyBeforeAction = parseStory(action.storyPath);
-    const prevPhaseState = {
-        research_complete: storyBeforeAction.frontmatter.research_complete,
-        plan_complete: storyBeforeAction.frontmatter.plan_complete,
-        implementation_complete: storyBeforeAction.frontmatter.implementation_complete,
-        reviews_complete: storyBeforeAction.frontmatter.reviews_complete,
-        status: storyBeforeAction.frontmatter.status,
-    };
-    const spinner = ora(formatAction(action, true, c)).start();
-    const baseText = formatAction(action, true, c);
-    // Create agent progress callback for real-time updates
-    const onAgentProgress = (event) => {
-        switch (event.type) {
-            case 'session_start':
-                spinner.text = `${baseText} ${c.dim('(session started)')}`;
-                break;
-            case 'tool_start':
-                // Show which tool is being executed
-                const toolName = event.toolName || 'unknown';
-                const shortName = toolName.replace(/^(mcp__|Mcp)/, '').substring(0, 30);
-                spinner.text = `${baseText} ${c.dim(`→ ${shortName}`)}`;
-                break;
-            case 'tool_end':
-                // Keep showing the action, tool completed
-                spinner.text = baseText;
-                break;
-            case 'completion':
-                spinner.text = `${baseText} ${c.dim('(completing...)')}`;
-                break;
-        }
-    };
     try {
+        // Resolve story by ID to get current path (handles moves between folders)
+        let resolvedPath;
+        try {
+            const story = getStory(sdlcRoot, action.storyId);
+            resolvedPath = story.path;
+        }
+        catch (error) {
+            const errorMsg = `Error: Story not found for action "${action.type}"`;
+            storyLogger?.log('ERROR', errorMsg);
+            storyLogger?.log('ERROR', `  Story ID: ${action.storyId}`);
+            storyLogger?.log('ERROR', `  Original path: ${action.storyPath}`);
+            console.log(c.error(errorMsg));
+            console.log(c.dim(`  Story ID: ${action.storyId}`));
+            console.log(c.dim(`  Original path: ${action.storyPath}`));
+            if (error instanceof Error) {
+                storyLogger?.log('ERROR', `  ${error.message}`);
+                console.log(c.dim(`  ${error.message}`));
+            }
+            return { success: false };
+        }
+        // Update action path if it was stale
+        if (resolvedPath !== action.storyPath) {
+            storyLogger?.log('WARN', `Note: Story path updated (file was moved)`);
+            storyLogger?.log('WARN', `  From: ${action.storyPath}`);
+            storyLogger?.log('WARN', `  To: ${resolvedPath}`);
+            console.log(c.warning(`Note: Story path updated (file was moved)`));
+            console.log(c.dim(`  From: ${action.storyPath}`));
+            console.log(c.dim(`  To: ${resolvedPath}`));
+            action.storyPath = resolvedPath;
+        }
+        // Store phase completion state BEFORE action execution (to detect transitions)
+        const storyBeforeAction = parseStory(action.storyPath);
+        const prevPhaseState = {
+            research_complete: storyBeforeAction.frontmatter.research_complete,
+            plan_complete: storyBeforeAction.frontmatter.plan_complete,
+            implementation_complete: storyBeforeAction.frontmatter.implementation_complete,
+            reviews_complete: storyBeforeAction.frontmatter.reviews_complete,
+            status: storyBeforeAction.frontmatter.status,
+        };
+        spinner = ora(formatAction(action, true, c)).start();
+        const baseText = formatAction(action, true, c);
+        // Create agent progress callback for real-time updates
+        const onAgentProgress = (event) => {
+            if (!spinner)
+                return; // Guard against null spinner
+            switch (event.type) {
+                case 'session_start':
+                    spinner.text = `${baseText} ${c.dim('(session started)')}`;
+                    break;
+                case 'tool_start':
+                    // Show which tool is being executed
+                    const toolName = event.toolName || 'unknown';
+                    const shortName = toolName.replace(/^(mcp__|Mcp)/, '').substring(0, 30);
+                    spinner.text = `${baseText} ${c.dim(`→ ${shortName}`)}`;
+                    break;
+                case 'tool_end':
+                    // Keep showing the action, tool completed
+                    spinner.text = baseText;
+                    break;
+                case 'completion':
+                    spinner.text = `${baseText} ${c.dim('(completing...)')}`;
+                    break;
+            }
+        };
         // Import and run the appropriate agent
         let result;
         switch (action.type) {
@@ -670,6 +1215,8 @@ async function executeAction(action, sdlcRoot) {
                 const { runReviewAgent } = await import('../agents/review.js');
                 result = await runReviewAgent(action.storyPath, sdlcRoot, {
                     onVerificationProgress: (phase, status, message) => {
+                        if (!spinner)
+                            return; // Guard against null spinner
                         const phaseLabel = phase === 'build' ? 'Building' : 'Testing';
                         switch (status) {
                             case 'starting':
@@ -687,6 +1234,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');
@@ -703,28 +1297,49 @@ async function executeAction(action, sdlcRoot) {
                 // Update story status to done (no file move in new architecture)
                 const { updateStoryStatus } = await import('../core/story.js');
                 const storyToMove = parseStory(action.storyPath);
-                const updatedStory = updateStoryStatus(storyToMove, 'done');
+                const updatedStory = await updateStoryStatus(storyToMove, 'done');
                 result = {
                     success: true,
                     story: updatedStory,
                     changesMade: ['Updated story status to done'],
                 };
+                // Worktree cleanup prompt (if story has a worktree)
+                if (storyToMove.frontmatter.worktree_path) {
+                    await handleWorktreeCleanup(storyToMove, config, c);
+                }
                 break;
             default:
                 throw new Error(`Unknown action type: ${action.type}`);
         }
         // Check if agent succeeded
+        const actionDuration = Date.now() - actionStartTime;
         if (result && !result.success) {
             spinner.fail(c.error(`Failed: ${formatAction(action, true, c)}`));
+            storyLogger?.log('ERROR', `Action failed: ${formatAction(action, false, c)}`);
+            globalLogger.warn('action', `Action failed: ${action.type}`, {
+                storyId: action.storyId,
+                actionType: action.type,
+                durationMs: actionDuration,
+                error: result.error,
+            });
             if (result.error) {
+                storyLogger?.log('ERROR', `  Error: ${result.error}`);
                 console.error(c.error(`  Error: ${result.error}`));
             }
             return { success: false };
         }
         spinner.succeed(c.success(formatAction(action, true, c)));
+        storyLogger?.log('INFO', `Action completed successfully: ${formatAction(action, false, c)}`);
+        globalLogger.info('action', `Action completed: ${action.type}`, {
+            storyId: action.storyId,
+            actionType: action.type,
+            durationMs: actionDuration,
+            changesCount: result?.changesMade?.length ?? 0,
+        });
         // Show changes made
         if (result && result.changesMade.length > 0) {
             for (const change of result.changesMade) {
+                storyLogger?.log('INFO', `  → ${change}`);
                 console.log(c.dim(`  → ${change}`));
             }
         }
@@ -780,14 +1395,28 @@ async function executeAction(action, sdlcRoot) {
         return { success: true };
     }
     catch (error) {
-        spinner.fail(c.error(`Failed: ${formatAction(action, true, c)}`));
+        const exceptionDuration = Date.now() - actionStartTime;
+        if (spinner) {
+            spinner.fail(c.error(`Failed: ${formatAction(action, true, c)}`));
+        }
+        else {
+            console.error(c.error(`Failed: ${formatAction(action, true, c)}`));
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        storyLogger?.log('ERROR', `Exception during action execution: ${errorMessage}`);
+        globalLogger.error('action', `Action exception: ${action.type}`, {
+            storyId: action.storyId,
+            actionType: action.type,
+            durationMs: exceptionDuration,
+            error: errorMessage,
+        });
         console.error(error);
         // Show phase checklist with error indication (if file still exists)
         try {
             const story = parseStory(action.storyPath);
             console.log(c.dim(`  Progress: ${renderPhaseChecklist(story, c)}`));
             // Update story with error
-            story.frontmatter.last_error = error instanceof Error ? error.message : String(error);
+            story.frontmatter.last_error = errorMessage;
         }
         catch {
             // File may have been moved - skip progress display
@@ -795,6 +1424,10 @@ async function executeAction(action, sdlcRoot) {
         // Don't throw - let the workflow continue if in auto mode
         return { success: false };
     }
+    finally {
+        // Always close logger, even if action fails or throws
+        storyLogger?.close();
+    }
 }
 /**
  * Get phase information for an action type
@@ -1202,7 +1835,7 @@ function isEmptySection(content) {
 /**
  * Unblock a story from the blocked folder and move it back to the workflow
  */
-export function unblock(storyId, options) {
+export async function unblock(storyId, options) {
     const spinner = ora('Unblocking story...').start();
     const config = loadConfig();
     const c = getThemedChalk(config);
@@ -1213,7 +1846,7 @@ export function unblock(storyId, options) {
             return;
         }
         // Unblock the story (using renamed import to avoid naming conflict)
-        const unblockedStory = unblockStory(storyId, sdlcRoot, options);
+        const unblockedStory = await unblockStory(storyId, sdlcRoot, options);
         // Determine destination folder from updated path
         const destinationFolder = unblockedStory.path.match(/\/([^/]+)\/[^/]+\.md$/)?.[1] || 'unknown';
         spinner.succeed(c.success(`Unblocked story ${storyId}, moved to ${destinationFolder}/`));
@@ -1327,4 +1960,275 @@ export async function migrate(options) {
         process.exit(1);
     }
 }
+/**
+ * Helper function to prompt for removal confirmation
+ */
+async function confirmRemoval(message) {
+    // Sanitize message to prevent terminal injection attacks
+    // Use consistent sanitizeForDisplay() for all terminal output
+    const sanitizedMessage = sanitizeForDisplay(message);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(sanitizedMessage + ' (y/N): ', (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+/**
+ * Handle worktree cleanup when story moves to done
+ * Prompts user in interactive mode to remove worktree
+ */
+async function handleWorktreeCleanup(story, config, c) {
+    const worktreePath = story.frontmatter.worktree_path;
+    if (!worktreePath)
+        return;
+    const sdlcRoot = getSdlcRoot();
+    const workingDir = path.dirname(sdlcRoot);
+    const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
+    // Check if worktree exists
+    if (!fs.existsSync(worktreePath)) {
+        console.log(c.warning(`  Note: Worktree path no longer exists: ${worktreePath}`));
+        const updated = await updateStoryField(story, 'worktree_path', undefined);
+        await writeStory(updated);
+        console.log(c.dim('  Cleared worktree_path from frontmatter'));
+        return;
+    }
+    // Only prompt in interactive mode
+    if (!process.stdin.isTTY) {
+        console.log(c.dim(`  Worktree preserved (non-interactive mode): ${worktreePath}`));
+        return;
+    }
+    // Prompt for cleanup
+    console.log();
+    console.log(c.info(`  Story has a worktree at: ${worktreePath}`));
+    const shouldRemove = await confirmRemoval('  Remove worktree?');
+    if (!shouldRemove) {
+        console.log(c.dim('  Worktree preserved'));
+        return;
+    }
+    // Remove worktree
+    try {
+        let resolvedBasePath;
+        try {
+            resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+        }
+        catch {
+            resolvedBasePath = path.dirname(worktreePath);
+        }
+        const service = new GitWorktreeService(workingDir, resolvedBasePath);
+        service.remove(worktreePath);
+        const updated = await updateStoryField(story, 'worktree_path', undefined);
+        await writeStory(updated);
+        console.log(c.success('  ✓ Worktree removed'));
+    }
+    catch (error) {
+        console.log(c.warning(`  Failed to remove worktree: ${error instanceof Error ? error.message : String(error)}`));
+        // Clear frontmatter anyway (user may have manually deleted)
+        const updated = await updateStoryField(story, 'worktree_path', undefined);
+        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
+ */
+export async function listWorktrees() {
+    const config = loadConfig();
+    const c = getThemedChalk(config);
+    try {
+        const sdlcRoot = getSdlcRoot();
+        const workingDir = path.dirname(sdlcRoot);
+        const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
+        // Resolve worktree base path
+        let resolvedBasePath;
+        try {
+            resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+        }
+        catch (error) {
+            // If basePath doesn't exist yet, create an empty list response
+            console.log();
+            console.log(c.bold('═══ Worktrees ═══'));
+            console.log();
+            console.log(c.dim('No worktrees found.'));
+            console.log(c.dim('Use `ai-sdlc worktrees add <story-id>` to create one.'));
+            console.log();
+            return;
+        }
+        const service = new GitWorktreeService(workingDir, resolvedBasePath);
+        const worktrees = service.list();
+        console.log();
+        console.log(c.bold('═══ Worktrees ═══'));
+        console.log();
+        if (worktrees.length === 0) {
+            console.log(c.dim('No worktrees found.'));
+            console.log(c.dim('Use `ai-sdlc worktrees add <story-id>` to create one.'));
+        }
+        else {
+            // Table header
+            console.log(c.dim('Story ID'.padEnd(12) + 'Branch'.padEnd(40) + 'Status'.padEnd(10) + 'Path'));
+            console.log(c.dim('─'.repeat(80)));
+            for (const wt of worktrees) {
+                const storyId = wt.storyId || 'unknown';
+                const branch = wt.branch.length > 38 ? wt.branch.substring(0, 35) + '...' : wt.branch;
+                const status = wt.exists ? c.success('exists') : c.error('missing');
+                const displayPath = wt.path.length > 50 ? '...' + wt.path.slice(-47) : wt.path;
+                console.log(storyId.padEnd(12) +
+                    branch.padEnd(40) +
+                    (wt.exists ? 'exists    ' : 'missing   ') +
+                    displayPath);
+            }
+            console.log();
+            console.log(c.dim(`Total: ${worktrees.length} worktree(s)`));
+        }
+        console.log();
+    }
+    catch (error) {
+        console.log(c.error(`Error listing worktrees: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+}
+/**
+ * Create a worktree for a specific story
+ */
+export async function addWorktree(storyId) {
+    const spinner = ora('Creating worktree...').start();
+    const config = loadConfig();
+    const c = getThemedChalk(config);
+    try {
+        const sdlcRoot = getSdlcRoot();
+        const workingDir = path.dirname(sdlcRoot);
+        if (!kanbanExists(sdlcRoot)) {
+            spinner.fail('ai-sdlc not initialized. Run `ai-sdlc init` first.');
+            return;
+        }
+        // Find the story
+        const story = findStoryById(sdlcRoot, storyId) || findStoryBySlug(sdlcRoot, storyId);
+        if (!story) {
+            spinner.fail(c.error(`Story not found: "${storyId}"`));
+            console.log(c.dim('Use `ai-sdlc status` to see available stories.'));
+            return;
+        }
+        // Check if story already has a worktree
+        if (story.frontmatter.worktree_path) {
+            spinner.fail(c.error(`Story already has a worktree: ${story.frontmatter.worktree_path}`));
+            return;
+        }
+        // Resolve worktree base path
+        const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
+        let resolvedBasePath;
+        try {
+            resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+        }
+        catch (error) {
+            spinner.fail(c.error(`Configuration Error: ${error instanceof Error ? error.message : String(error)}`));
+            console.log(c.dim('Fix worktree.basePath in .ai-sdlc.json or remove it to use default location'));
+            return;
+        }
+        const service = new GitWorktreeService(workingDir, resolvedBasePath);
+        // Validate git state
+        const validation = service.validateCanCreateWorktree();
+        if (!validation.valid) {
+            spinner.fail(c.error(validation.error || 'Cannot create worktree'));
+            return;
+        }
+        // Detect base branch
+        const baseBranch = service.detectBaseBranch();
+        // Create the worktree
+        const worktreePath = service.create({
+            storyId: story.frontmatter.id,
+            slug: story.slug,
+            baseBranch,
+        });
+        // Update story frontmatter
+        const updatedStory = await updateStoryField(story, 'worktree_path', worktreePath);
+        const branchName = service.getBranchName(story.frontmatter.id, story.slug);
+        const storyWithBranch = await updateStoryField(updatedStory, 'branch', branchName);
+        await writeStory(storyWithBranch);
+        spinner.succeed(c.success(`Created worktree for ${story.frontmatter.id}`));
+        console.log(c.dim(`  Path: ${worktreePath}`));
+        console.log(c.dim(`  Branch: ${branchName}`));
+        console.log(c.dim(`  Base: ${baseBranch}`));
+    }
+    catch (error) {
+        spinner.fail(c.error('Failed to create worktree'));
+        console.error(c.error(`  ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+}
+/**
+ * Remove a worktree for a specific story
+ */
+export async function removeWorktree(storyId, options) {
+    const config = loadConfig();
+    const c = getThemedChalk(config);
+    try {
+        const sdlcRoot = getSdlcRoot();
+        const workingDir = path.dirname(sdlcRoot);
+        if (!kanbanExists(sdlcRoot)) {
+            console.log(c.warning('ai-sdlc not initialized. Run `ai-sdlc init` first.'));
+            return;
+        }
+        // Find the story
+        const story = findStoryById(sdlcRoot, storyId) || findStoryBySlug(sdlcRoot, storyId);
+        if (!story) {
+            console.log(c.error(`Story not found: "${storyId}"`));
+            console.log(c.dim('Use `ai-sdlc status` to see available stories.'));
+            return;
+        }
+        // Check if story has a worktree
+        if (!story.frontmatter.worktree_path) {
+            console.log(c.warning(`Story ${storyId} does not have a worktree.`));
+            return;
+        }
+        const worktreePath = story.frontmatter.worktree_path;
+        // Confirm removal (unless --force)
+        if (!options?.force) {
+            console.log();
+            console.log(c.warning('About to remove worktree:'));
+            console.log(c.dim(`  Story: ${story.frontmatter.title}`));
+            console.log(c.dim(`  Path: ${worktreePath}`));
+            console.log();
+            const confirmed = await confirmRemoval('Are you sure you want to remove this worktree?');
+            if (!confirmed) {
+                console.log(c.dim('Cancelled.'));
+                return;
+            }
+        }
+        const spinner = ora('Removing worktree...').start();
+        // Resolve worktree base path
+        const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
+        let resolvedBasePath;
+        try {
+            resolvedBasePath = validateWorktreeBasePath(worktreeConfig.basePath, workingDir);
+        }
+        catch {
+            // If basePath doesn't exist, use the worktree path's parent
+            resolvedBasePath = path.dirname(worktreePath);
+        }
+        const service = new GitWorktreeService(workingDir, resolvedBasePath);
+        // Remove the worktree
+        service.remove(worktreePath);
+        // Clear worktree_path from frontmatter
+        const updatedStory = await updateStoryField(story, 'worktree_path', undefined);
+        await writeStory(updatedStory);
+        spinner.succeed(c.success(`Removed worktree for ${story.frontmatter.id}`));
+        console.log(c.dim(`  Path: ${worktreePath}`));
+    }
+    catch (error) {
+        console.log(c.error(`Failed to remove worktree: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+}
 //# sourceMappingURL=commands.js.map