ai-sdlc 0.2.0-alpha.9 → 0.2.0

package/dist/cli/commands.js

@@ -3,8 +3,8 @@ import fs from 'fs';
 import path from 'path';
 import * as readline from 'readline';
 import { getSdlcRoot, loadConfig, initConfig, validateWorktreeBasePath, DEFAULT_WORKTREE_CONFIG } from '../core/config.js';
-import { initializeKanban, kanbanExists, assessState, getBoardStats, findStoryBySlug } from '../core/kanban.js';
-import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory, getStory, findStoryById, updateStoryField, writeStory } from '../core/story.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 { ReviewDecision } from '../types/index.js';
 import { getThemedChalk } from '../core/theme.js';
@@ -15,6 +15,9 @@ 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
  */
@@ -52,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 ═══'));
@@ -117,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();
@@ -130,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`);
     }
@@ -218,6 +342,23 @@ const GIT_MODIFYING_ACTIONS = ['implement', 'review', 'create_pr'];
 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
  */
@@ -239,6 +380,160 @@ function displayGitValidationResult(result, c) {
         }
     }
 }
+// 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)
  */
@@ -250,6 +545,26 @@ export async function run(options) {
         : undefined;
     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...'));
@@ -287,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.'));
@@ -334,15 +656,26 @@ 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();
@@ -353,7 +686,7 @@ export async function run(options) {
             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);
         }
@@ -425,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;
@@ -466,105 +800,136 @@ 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;
         }
     }
-    // Validate git state before processing actions that modify git
-    if (!options.force && requiresGitValidation(actionsToProcess)) {
-        const workingDir = path.dirname(sdlcRoot);
-        const gitValidation = validateGitState(workingDir);
-        if (!gitValidation.valid) {
-            displayGitValidationResult(gitValidation, c);
-            return;
-        }
-        if (gitValidation.warnings.length > 0) {
-            displayGitValidationResult(gitValidation, c);
-            console.log();
-        }
-    }
-    // Handle worktree creation based on flags and config
+    // 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 > config > default (disabled)
+    // Priority: CLI flags > story frontmatter > config > default (disabled)
     const worktreeConfig = config.worktree ?? DEFAULT_WORKTREE_CONFIG;
-    const shouldUseWorktree = (() => {
-        // Explicit --no-worktree disables worktrees
-        if (options.worktree === false)
-            return false;
-        // Explicit --worktree enables worktrees
-        if (options.worktree === true)
-            return true;
-        // Fall back to config default
-        return worktreeConfig.enabled;
-    })();
+    // 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) {
-            // Explicit --worktree flag without --story is an error
             console.log(c.error('Error: --worktree requires --story flag'));
             return;
         }
-        // Config-enabled worktree without --story just silently skips worktree
     }
-    if (shouldUseWorktree && options.story) {
-        const workingDir = path.dirname(sdlcRoot);
-        // 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}`));
+    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;
         }
-        // Get the target story (already loaded from --story processing above)
-        const targetStory = findStoryById(sdlcRoot, options.story) || findStoryBySlug(sdlcRoot, options.story);
-        if (!targetStory) {
-            console.log(c.error(`Error: Story not found: "${options.story}"`));
-            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();
         }
-        try {
-            // Detect base branch
-            const baseBranch = worktreeService.detectBaseBranch();
-            // Create worktree
+        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 = worktreeService.create({
-                storyId: targetStory.frontmatter.id,
-                slug: targetStory.slug,
-                baseBranch,
-            });
-            // Update story frontmatter with worktree path
-            const updatedStory = updateStoryField(targetStory, 'worktree_path', worktreePath);
-            await writeStory(updatedStory);
-            // Change to worktree directory
+            worktreePath = existingWorktreePath;
             process.chdir(worktreePath);
-            // Recalculate sdlcRoot for the worktree context
-            // Since we've changed cwd to the worktree, getSdlcRoot() will now return the worktree's .ai-sdlc path
-            // This ensures all subsequent agent operations work within the isolated worktree
             sdlcRoot = getSdlcRoot();
-            console.log(c.success(`✓ Created worktree at: ${worktreePath}`));
+            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();
         }
-        catch (error) {
-            // Restore directory on worktree creation failure
-            if (originalCwd) {
+        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;
+                }
+                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;
+            }
+        }
+    }
+    // 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)
+    if (!options.force && requiresGitValidation(actionsToProcess)) {
+        const workingDir = path.dirname(sdlcRoot);
+        const gitValidationOptions = worktreeCreated
+            ? { skipBranchCheck: true, excludePatterns: ['.ai-sdlc/**'] }
+            : {};
+        const gitValidation = validateGitState(workingDir, gitValidationOptions);
+        if (!gitValidation.valid) {
+            displayGitValidationResult(gitValidation, c);
+            if (worktreeCreated && originalCwd) {
                 process.chdir(originalCwd);
             }
-            console.log(c.error(`Failed to create worktree: ${error instanceof Error ? error.message : String(error)}`));
             return;
         }
+        if (gitValidation.warnings.length > 0) {
+            displayGitValidationResult(gitValidation, c);
+            console.log();
+        }
     }
     // Process actions with retry support for Full SDLC mode
     let currentActions = [...actionsToProcess];
@@ -608,7 +973,8 @@ export async function run(options) {
                         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);
+                        // Using action.storyId - available from action loop context
+                        await clearWorkflowState(sdlcRoot, action.storyId);
                         return;
                     }
                     // We can retry - reset RPIV cycle and loop back
@@ -624,7 +990,7 @@ export async function run(options) {
                     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);
+                    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}`));
@@ -673,7 +1039,7 @@ export async function run(options) {
                         storyContentHash: calculateStoryHash(action.storyPath),
                     },
                 };
-                await saveWorkflowState(state, sdlcRoot);
+                await saveWorkflowState(state, sdlcRoot, action.storyId);
                 console.log(c.dim(`  ✓ Progress saved (${completedActions.length} actions completed)`));
             }
             currentActionIndex++;
@@ -695,7 +1061,8 @@ export async function run(options) {
                                 console.log(c.dim(`Retry attempts: ${retryAttempt}`));
                             }
                             console.log(c.dim(`Story is now ready for PR creation.`));
-                            await clearWorkflowState(sdlcRoot);
+                            // Using action.storyId - available from action loop context
+                            await clearWorkflowState(sdlcRoot, action.storyId);
                             console.log(c.dim('Checkpoint cleared.'));
                         }
                         else {
@@ -709,10 +1076,11 @@ export async function run(options) {
                 }
                 else {
                     // Normal auto mode: re-assess state
-                    const newAssessment = assessState(sdlcRoot);
+                    const newAssessment = await assessState(sdlcRoot);
                     if (newAssessment.recommendedActions.length === 0) {
                         console.log(c.success('\n✓ All actions completed!'));
-                        await clearWorkflowState(sdlcRoot);
+                        // Using action.storyId - available from action loop context
+                        await clearWorkflowState(sdlcRoot, action.storyId);
                         console.log(c.dim('Checkpoint cleared.'));
                         break;
                     }
@@ -735,61 +1103,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) {
@@ -813,6 +1211,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':
@@ -846,7 +1246,7 @@ 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,
@@ -861,17 +1261,34 @@ async function executeAction(action, sdlcRoot) {
                 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}`));
             }
         }
@@ -927,14 +1344,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
@@ -942,6 +1373,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
@@ -1349,7 +1784,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);
@@ -1360,7 +1795,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}/`));
@@ -1478,12 +1913,15 @@ export async function migrate(options) {
  * 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(message + ' (y/N): ', (answer) => {
+        rl.question(sanitizedMessage + ' (y/N): ', (answer) => {
             rl.close();
             resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
         });
@@ -1503,7 +1941,7 @@ async function handleWorktreeCleanup(story, config, c) {
     // Check if worktree exists
     if (!fs.existsSync(worktreePath)) {
         console.log(c.warning(`  Note: Worktree path no longer exists: ${worktreePath}`));
-        const updated = updateStoryField(story, 'worktree_path', undefined);
+        const updated = await updateStoryField(story, 'worktree_path', undefined);
         await writeStory(updated);
         console.log(c.dim('  Cleared worktree_path from frontmatter'));
         return;
@@ -1532,14 +1970,14 @@ async function handleWorktreeCleanup(story, config, c) {
         }
         const service = new GitWorktreeService(workingDir, resolvedBasePath);
         service.remove(worktreePath);
-        const updated = updateStoryField(story, 'worktree_path', undefined);
+        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 = updateStoryField(story, 'worktree_path', undefined);
+        const updated = await updateStoryField(story, 'worktree_path', undefined);
         await writeStory(updated);
     }
 }
@@ -1654,9 +2092,9 @@ export async function addWorktree(storyId) {
             baseBranch,
         });
         // Update story frontmatter
-        const updatedStory = updateStoryField(story, 'worktree_path', worktreePath);
+        const updatedStory = await updateStoryField(story, 'worktree_path', worktreePath);
         const branchName = service.getBranchName(story.frontmatter.id, story.slug);
-        const storyWithBranch = updateStoryField(updatedStory, 'branch', branchName);
+        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}`));
@@ -1723,7 +2161,7 @@ export async function removeWorktree(storyId, options) {
         // Remove the worktree
         service.remove(worktreePath);
         // Clear worktree_path from frontmatter
-        const updatedStory = updateStoryField(story, 'worktree_path', undefined);
+        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}`));