ai-sdlc 0.2.0-alpha.2 → 0.2.0-alpha.20

package/dist/cli/commands.js

@@ -1,15 +1,20 @@
 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, findStoryById } from '../core/kanban.js';
-import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory } 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 } from '../core/kanban.js';
+import { createStory, parseStory, resetRPIVCycle, isAtMaxRetries, unblockStory, getStory, findStoryById, updateStoryField, writeStory } 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';
 import { renderStories, renderKanbanBoard, shouldUseKanbanLayout } from './table-renderer.js';
 import { getStoryFlags as getStoryFlagsUtil, formatStatus as formatStatusUtil } from './story-utils.js';
 import { migrateToFolderPerStory } from './commands/migrate.js';
+import { generateReviewSummary } from '../agents/review.js';
+import { getTerminalWidth } from './formatting.js';
+import { validateGitState } from '../core/git-utils.js';
 /**
  * Initialize the .ai-sdlc folder structure
  */
@@ -47,7 +52,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 ═══'));
@@ -125,7 +130,7 @@ export async function add(title) {
             spinner.fail('ai-sdlc not initialized. Run `ai-sdlc init` first.');
             return;
         }
-        const story = createStory(title, sdlcRoot);
+        const story = await createStory(title, sdlcRoot);
         spinner.succeed(c.success(`Created: ${story.path}`));
         console.log(c.dim(`  ID: ${story.frontmatter.id}`));
         console.log(c.dim(`  Slug: ${story.slug}`));
@@ -203,6 +208,54 @@ 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}`));
+        }
+    }
+}
 /**
  * Run the workflow (process one action or all)
  */
@@ -212,8 +265,17 @@ 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);
+    // 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...'));
@@ -251,8 +313,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.'));
@@ -298,20 +367,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);
         }
@@ -383,7 +469,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;
@@ -424,179 +511,289 @@ 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) {
+        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})`));
-                // 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)
+    // 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);
+            }
+            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;
+                    }
                 }
             }
         }
     }
-}
-/**
- * Validate and resolve the story path for an action.
- * If the path doesn't exist, attempts to find the story by ID.
- *
- * @returns The resolved story path, or null if story cannot be found
- */
-function resolveStoryPath(action, sdlcRoot) {
-    // Check if the current path exists
-    if (fs.existsSync(action.storyPath)) {
-        return action.storyPath;
-    }
-    // Path is stale - try to find by story ID
-    const story = findStoryById(sdlcRoot, action.storyId);
-    if (story) {
-        return story.path;
-    }
-    // Story not found by ID either
-    return null;
+    finally {
+        // Restore original working directory if worktree was used
+        if (originalCwd) {
+            process.chdir(originalCwd);
+        }
+    }
 }
 /**
  * Execute a specific action
@@ -606,13 +803,19 @@ function resolveStoryPath(action, sdlcRoot) {
 async function executeAction(action, sdlcRoot) {
     const config = loadConfig();
     const c = getThemedChalk(config);
-    // Validate and resolve the story path before executing
-    const resolvedPath = resolveStoryPath(action, sdlcRoot);
-    if (!resolvedPath) {
+    // 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) {
         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}`));
-        console.log(c.dim('  The story file may have been moved or deleted.'));
+        if (error instanceof Error) {
+            console.log(c.dim(`  ${error.message}`));
+        }
         return { success: false };
     }
     // Update action path if it was stale
@@ -711,12 +914,16 @@ 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}`);
@@ -1210,7 +1417,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);
@@ -1221,7 +1428,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}/`));
@@ -1335,4 +1542,263 @@ export async function migrate(options) {
         process.exit(1);
     }
 }
+/**
+ * Helper function to prompt for removal confirmation
+ */
+async function confirmRemoval(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(message + ' (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);
+    }
+}
+/**
+ * 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