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

package/dist/core/task-progress.js

@@ -0,0 +1,280 @@
+/**
+ * Task progress tracking for resumable implementations
+ *
+ * Persists task-level progress in story files as markdown tables,
+ * enabling orchestrator to resume from last completed task after interruptions.
+ */
+import fs from 'fs';
+import path from 'path';
+import writeFileAtomic from 'write-file-atomic';
+const TASK_PROGRESS_SECTION = '## Task Progress';
+/**
+ * Parse progress table from markdown content
+ *
+ * Expected format:
+ * ## Task Progress
+ *
+ * | Task | Status | Started | Completed |
+ * |------|--------|---------|-----------|
+ * | T1 | completed | 2026-01-16T10:00:00Z | 2026-01-16T10:05:00Z |
+ * | T2 | in_progress | 2026-01-16T10:05:30Z | - |
+ *
+ * @param content - Story file markdown content
+ * @returns Array of TaskProgress objects (empty if section missing or corrupted)
+ */
+export function parseProgressTable(content) {
+    const sectionIndex = content.indexOf(TASK_PROGRESS_SECTION);
+    if (sectionIndex === -1) {
+        return [];
+    }
+    // Find the table rows (skip header and separator)
+    const afterSection = content.slice(sectionIndex);
+    const lines = afterSection.split('\n');
+    const taskProgress = [];
+    let foundTable = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip section header, empty lines, and markdown table separator
+        if (!trimmed || trimmed.startsWith('#') || trimmed.match(/^\|[\s-:|]+\|$/)) {
+            continue;
+        }
+        // Stop at next section
+        if (trimmed.startsWith('##') && !trimmed.includes(TASK_PROGRESS_SECTION)) {
+            break;
+        }
+        // Parse table row
+        if (trimmed.startsWith('|')) {
+            foundTable = true;
+            const cells = trimmed
+                .split('|')
+                .map(cell => cell.trim())
+                .filter(cell => cell.length > 0);
+            // Skip header row
+            if (cells[0] === 'Task' || cells[1] === 'Status') {
+                continue;
+            }
+            // Validate we have at least 4 columns
+            if (cells.length < 4) {
+                console.warn(`[task-progress] Skipping malformed table row: ${trimmed}`);
+                continue;
+            }
+            const [taskId, statusStr, startedStr, completedStr] = cells;
+            // Validate status
+            const validStatuses = ['pending', 'in_progress', 'completed', 'failed'];
+            if (!validStatuses.includes(statusStr)) {
+                console.warn(`[task-progress] Invalid status '${statusStr}' for task ${taskId}, skipping row`);
+                continue;
+            }
+            const progress = {
+                taskId,
+                status: statusStr,
+            };
+            // Parse timestamps (handle "-" as missing)
+            if (startedStr && startedStr !== '-') {
+                progress.startedAt = startedStr;
+            }
+            if (completedStr && completedStr !== '-') {
+                progress.completedAt = completedStr;
+            }
+            // Handle error column if present (5th column)
+            if (cells.length >= 5 && cells[4] && cells[4] !== '-') {
+                progress.error = cells[4];
+            }
+            taskProgress.push(progress);
+        }
+    }
+    if (foundTable && taskProgress.length === 0) {
+        console.warn('[task-progress] Found progress table but no valid task rows, table may be corrupted');
+    }
+    return taskProgress;
+}
+/**
+ * Generate markdown table from TaskProgress array
+ *
+ * @param progress - Array of task progress entries
+ * @returns Markdown table string
+ */
+export function generateProgressTable(progress) {
+    const rows = [];
+    // Header
+    rows.push('| Task | Status | Started | Completed |');
+    rows.push('|------|--------|---------|-----------|');
+    // Task rows
+    for (const task of progress) {
+        const started = task.startedAt || '-';
+        const completed = task.completedAt || '-';
+        rows.push(`| ${task.taskId} | ${task.status} | ${started} | ${completed} |`);
+    }
+    return rows.join('\n');
+}
+/**
+ * Read story file content
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @returns Story file content
+ * @throws Error if file doesn't exist or can't be read
+ */
+export async function readStoryFile(storyPath) {
+    try {
+        return await fs.promises.readFile(storyPath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Story file not found: ${path.basename(storyPath)}`);
+        }
+        if (error.code === 'EACCES' || error.code === 'EPERM') {
+            throw new Error(`Permission denied reading story file: ${path.basename(storyPath)}`);
+        }
+        throw new Error(`Failed to read story file: ${error.message}`);
+    }
+}
+/**
+ * Write story file content atomically with retry logic
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @param content - New story content
+ * @throws Error after all retries exhausted
+ */
+export async function writeStoryFile(storyPath, content) {
+    const maxRetries = 3;
+    const retryDelays = [100, 200, 400]; // Exponential backoff
+    // Ensure parent directory exists first (outside retry loop)
+    const storyDir = path.dirname(storyPath);
+    await fs.promises.mkdir(storyDir, { recursive: true });
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            // Atomic write
+            await writeFileAtomic(storyPath, content, { encoding: 'utf-8' });
+            return; // Success
+        }
+        catch (error) {
+            const isLastAttempt = attempt === maxRetries - 1;
+            // Don't retry on permission errors - throw immediately
+            if (error.code === 'EACCES' || error.code === 'EPERM') {
+                throw new Error(`Permission denied writing story file: ${path.basename(storyPath)}`);
+            }
+            if (isLastAttempt) {
+                throw new Error(`Failed to write story file after ${maxRetries} attempts`);
+            }
+            // Wait before retry
+            await new Promise(resolve => setTimeout(resolve, retryDelays[attempt]));
+        }
+    }
+}
+/**
+ * Get all task progress entries from story file
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @returns Array of TaskProgress objects (empty if section missing)
+ */
+export async function getTaskProgress(storyPath) {
+    const content = await readStoryFile(storyPath);
+    return parseProgressTable(content);
+}
+/**
+ * Initialize progress tracking for a list of tasks
+ *
+ * Creates "## Task Progress" section with all tasks in 'pending' status.
+ * If section already exists, logs warning and skips initialization.
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @param taskIds - Array of task IDs (e.g., ['T1', 'T2', 'T3'])
+ */
+export async function initializeTaskProgress(storyPath, taskIds) {
+    const content = await readStoryFile(storyPath);
+    // Check if progress section already exists
+    if (content.includes(TASK_PROGRESS_SECTION)) {
+        console.warn('[task-progress] Progress section already exists, skipping initialization');
+        return;
+    }
+    // Create initial progress entries (all pending)
+    const progress = taskIds.map(taskId => ({
+        taskId,
+        status: 'pending',
+    }));
+    const progressTable = generateProgressTable(progress);
+    const progressSection = `\n${TASK_PROGRESS_SECTION}\n\n${progressTable}\n`;
+    // Append to end of file
+    const newContent = content.trimEnd() + '\n' + progressSection;
+    await writeStoryFile(storyPath, newContent);
+}
+/**
+ * Update a specific task's status and timestamps
+ *
+ * Modifies the task row in the progress table and writes back to disk atomically.
+ * Sets timestamps based on status transitions:
+ * - 'in_progress': Sets startedAt (if not already set)
+ * - 'completed' or 'failed': Sets completedAt
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @param taskId - Task ID to update (e.g., 'T1')
+ * @param status - New status
+ * @param error - Optional error message (only used with 'failed' status)
+ * @throws Error if task not found in progress table
+ */
+export async function updateTaskProgress(storyPath, taskId, status, error) {
+    const content = await readStoryFile(storyPath);
+    const progress = parseProgressTable(content);
+    // Find task to update
+    const taskIndex = progress.findIndex(t => t.taskId === taskId);
+    if (taskIndex === -1) {
+        throw new Error(`Task ${taskId} not found in progress table`);
+    }
+    const task = progress[taskIndex];
+    const now = new Date().toISOString();
+    // Update status
+    task.status = status;
+    // Set timestamps based on status transition
+    if (status === 'in_progress' && !task.startedAt) {
+        task.startedAt = now;
+    }
+    if (status === 'completed' || status === 'failed') {
+        task.completedAt = now;
+    }
+    // Store error message if provided
+    if (error) {
+        task.error = error;
+    }
+    // Regenerate table
+    const newTable = generateProgressTable(progress);
+    // Replace progress section in content
+    const sectionIndex = content.indexOf(TASK_PROGRESS_SECTION);
+    if (sectionIndex === -1) {
+        throw new Error('Progress section disappeared during update, this should not happen');
+    }
+    // Find next section or end of file
+    const afterSection = content.slice(sectionIndex + TASK_PROGRESS_SECTION.length);
+    const nextSectionMatch = afterSection.match(/\n## [^#]/);
+    const nextSectionOffset = nextSectionMatch
+        ? sectionIndex + TASK_PROGRESS_SECTION.length + nextSectionMatch.index
+        : content.length;
+    // Rebuild content
+    const beforeSection = content.slice(0, sectionIndex);
+    const afterNextSection = content.slice(nextSectionOffset);
+    const newContent = `${beforeSection}${TASK_PROGRESS_SECTION}\n\n${newTable}\n${afterNextSection}`;
+    await writeStoryFile(storyPath, newContent);
+}
+/**
+ * Get list of task IDs with status 'pending'
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @returns Array of pending task IDs
+ */
+export async function getPendingTasks(storyPath) {
+    const progress = await getTaskProgress(storyPath);
+    return progress
+        .filter(task => task.status === 'pending')
+        .map(task => task.taskId);
+}
+/**
+ * Get the task ID currently in 'in_progress' status
+ *
+ * @param storyPath - Absolute path to story.md file
+ * @returns Task ID or null if no task is in progress
+ */
+export async function getCurrentTask(storyPath) {
+    const progress = await getTaskProgress(storyPath);
+    const currentTask = progress.find(task => task.status === 'in_progress');
+    return currentTask ? currentTask.taskId : null;
+}
+//# sourceMappingURL=task-progress.js.map

package/dist/core/task-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-progress.js","sourceRoot":"","sources":["../../src/core/task-progress.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-state.d.ts

@@ -6,9 +6,16 @@
  */
 import { WorkflowExecutionState, WorkflowStateValidationResult } from '../types/workflow-state.js';
 /**
- * Get the path to the workflow state file
+ * Get the path to the workflow state file.
+ *
+ * SECURITY: storyId is sanitized using sanitizeStoryId() to prevent path traversal attacks.
+ * Never construct paths manually - always use this function to ensure proper sanitization.
+ *
+ * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
+ * @returns Path to the workflow state file (story-specific or global)
  */
-export declare function getStateFilePath(sdlcRoot: string): string;
+export declare function getStateFilePath(sdlcRoot: string, storyId?: string): string;
 /**
  * Generate a unique workflow ID based on timestamp
  */
@@ -24,15 +31,17 @@ export declare function calculateStoryHash(storyPath: string): string;
  *
  * @param state - The workflow execution state to save
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  */
-export declare function saveWorkflowState(state: WorkflowExecutionState, sdlcRoot: string): Promise<void>;
+export declare function saveWorkflowState(state: WorkflowExecutionState, sdlcRoot: string, storyId?: string): Promise<void>;
 /**
  * Load workflow state from disk
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  * @returns The workflow state, or null if no state file exists
  */
-export declare function loadWorkflowState(sdlcRoot: string): Promise<WorkflowExecutionState | null>;
+export declare function loadWorkflowState(sdlcRoot: string, storyId?: string): Promise<WorkflowExecutionState | null>;
 /**
  * Validate workflow state structure
  *
@@ -44,13 +53,43 @@ export declare function validateWorkflowState(state: any): WorkflowStateValidati
  * Clear workflow state (delete the state file)
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  */
-export declare function clearWorkflowState(sdlcRoot: string): Promise<void>;
+export declare function clearWorkflowState(sdlcRoot: string, storyId?: string): Promise<void>;
 /**
  * Check if workflow state exists
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  * @returns True if state file exists
  */
-export declare function hasWorkflowState(sdlcRoot: string): boolean;
+export declare function hasWorkflowState(sdlcRoot: string, storyId?: string): boolean;
+/**
+ * Migrate global workflow state to story-specific location.
+ *
+ * Call this function at CLI startup (before loading workflow state) to automatically
+ * move legacy global state files to the new per-story location.
+ *
+ * Migration behavior:
+ * - Extracts story ID from context.options.story, completedActions, or currentAction
+ * - Skips migration if workflow is currently in progress (currentAction set)
+ * - Skips migration if no story ID can be determined
+ * - Validates target file if it already exists before deleting global file
+ * - Deletes global file only after successful write to target location
+ *
+ * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @returns Promise resolving to migration result object:
+ *   - migrated: boolean - true if migration was performed, false if skipped
+ *   - message: string - Human-readable description of what happened
+ *
+ * @example
+ * const result = await migrateGlobalWorkflowState(sdlcRoot);
+ * if (result.migrated) {
+ *   console.log(result.message); // "Successfully migrated workflow state to story S-0033"
+ * }
+ */
+export declare function migrateGlobalWorkflowState(sdlcRoot: string): Promise<{
+    migrated: boolean;
+    message: string;
+}>;
 //# sourceMappingURL=workflow-state.d.ts.map

package/dist/core/workflow-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-state.d.ts","sourceRoot":"","sources":["../../src/core/workflow-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAE9B,MAAM,4BAA4B,CAAC;AAKpC;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA6BxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,6BAA6B,CAyC/E;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG1D"}
+{"version":3,"file":"workflow-state.d.ts","sourceRoot":"","sources":["../../src/core/workflow-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAE9B,MAAM,4BAA4B,CAAC;AAQpC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAuCxC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,6BAA6B,CAyC/E;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAG5E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA0IjD"}

package/dist/core/workflow-state.js

@@ -8,12 +8,26 @@ import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 import writeFileAtomic from 'write-file-atomic';
+import { STORIES_FOLDER } from '../types/index.js';
+import { sanitizeStoryId } from './story.js';
+import { getLogger } from './logger.js';
 const STATE_FILE_NAME = '.workflow-state.json';
 const CURRENT_VERSION = '1.0';
 /**
- * Get the path to the workflow state file
+ * Get the path to the workflow state file.
+ *
+ * SECURITY: storyId is sanitized using sanitizeStoryId() to prevent path traversal attacks.
+ * Never construct paths manually - always use this function to ensure proper sanitization.
+ *
+ * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
+ * @returns Path to the workflow state file (story-specific or global)
  */
-export function getStateFilePath(sdlcRoot) {
+export function getStateFilePath(sdlcRoot, storyId) {
+    if (storyId) {
+        const sanitized = sanitizeStoryId(storyId);
+        return path.join(sdlcRoot, STORIES_FOLDER, sanitized, STATE_FILE_NAME);
+    }
     return path.join(sdlcRoot, STATE_FILE_NAME);
 }
 /**
@@ -44,17 +58,33 @@ export function calculateStoryHash(storyPath) {
  *
  * @param state - The workflow execution state to save
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  */
-export async function saveWorkflowState(state, sdlcRoot) {
-    const statePath = getStateFilePath(sdlcRoot);
+export async function saveWorkflowState(state, sdlcRoot, storyId) {
+    const logger = getLogger();
+    const statePath = getStateFilePath(sdlcRoot, storyId);
     const stateJson = JSON.stringify(state, null, 2);
+    logger.debug('workflow-state', 'Saving workflow state', {
+        workflowId: state.workflowId,
+        storyId,
+        actionCount: state.completedActions.length,
+    });
     try {
-        // Ensure the directory exists
-        await fs.promises.mkdir(sdlcRoot, { recursive: true });
+        // Ensure the directory exists (including story subdirectories)
+        const stateDir = path.dirname(statePath);
+        await fs.promises.mkdir(stateDir, { recursive: true });
         // Write atomically to prevent corruption
         await writeFileAtomic(statePath, stateJson, { encoding: 'utf-8' });
     }
     catch (error) {
+        // Specific permission error handling
+        if (error && typeof error === 'object' && 'code' in error) {
+            const code = error.code;
+            if (code === 'EACCES' || code === 'EPERM') {
+                throw new Error(`Permission denied: Cannot write workflow state to ${statePath}. ` +
+                    `Check file permissions for the directory and ensure it is writable.`);
+            }
+        }
         throw new Error(`Failed to save workflow state: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
@@ -62,13 +92,16 @@ export async function saveWorkflowState(state, sdlcRoot) {
  * Load workflow state from disk
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  * @returns The workflow state, or null if no state file exists
  */
-export async function loadWorkflowState(sdlcRoot) {
-    const statePath = getStateFilePath(sdlcRoot);
+export async function loadWorkflowState(sdlcRoot, storyId) {
+    const logger = getLogger();
+    const statePath = getStateFilePath(sdlcRoot, storyId);
     try {
         // Check if file exists
         if (!fs.existsSync(statePath)) {
+            logger.debug('workflow-state', 'No workflow state found', { storyId });
             return null;
         }
         // Read and parse the state file
@@ -79,10 +112,17 @@ export async function loadWorkflowState(sdlcRoot) {
         if (!validation.valid) {
             throw new Error(`Invalid state file: ${validation.errors.join(', ')}`);
         }
+        logger.debug('workflow-state', 'Loaded workflow state', {
+            workflowId: state.workflowId,
+            storyId,
+            actionCount: state.completedActions.length,
+            ageMs: Date.now() - new Date(state.timestamp).getTime(),
+        });
         return state;
     }
     catch (error) {
         if (error instanceof SyntaxError) {
+            logger.error('workflow-state', 'Corrupted state file', { statePath });
             throw new Error(`Corrupted workflow state file at ${statePath}. ` +
                 `Delete the file to start fresh: rm "${statePath}"`);
         }
@@ -136,9 +176,10 @@ export function validateWorkflowState(state) {
  * Clear workflow state (delete the state file)
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  */
-export async function clearWorkflowState(sdlcRoot) {
-    const statePath = getStateFilePath(sdlcRoot);
+export async function clearWorkflowState(sdlcRoot, storyId) {
+    const statePath = getStateFilePath(sdlcRoot, storyId);
     try {
         if (fs.existsSync(statePath)) {
             await fs.promises.unlink(statePath);
@@ -153,10 +194,158 @@ export async function clearWorkflowState(sdlcRoot) {
  * Check if workflow state exists
  *
  * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @param storyId - Optional story ID for per-story state isolation
  * @returns True if state file exists
  */
-export function hasWorkflowState(sdlcRoot) {
-    const statePath = getStateFilePath(sdlcRoot);
+export function hasWorkflowState(sdlcRoot, storyId) {
+    const statePath = getStateFilePath(sdlcRoot, storyId);
     return fs.existsSync(statePath);
 }
+/**
+ * Migrate global workflow state to story-specific location.
+ *
+ * Call this function at CLI startup (before loading workflow state) to automatically
+ * move legacy global state files to the new per-story location.
+ *
+ * Migration behavior:
+ * - Extracts story ID from context.options.story, completedActions, or currentAction
+ * - Skips migration if workflow is currently in progress (currentAction set)
+ * - Skips migration if no story ID can be determined
+ * - Validates target file if it already exists before deleting global file
+ * - Deletes global file only after successful write to target location
+ *
+ * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @returns Promise resolving to migration result object:
+ *   - migrated: boolean - true if migration was performed, false if skipped
+ *   - message: string - Human-readable description of what happened
+ *
+ * @example
+ * const result = await migrateGlobalWorkflowState(sdlcRoot);
+ * if (result.migrated) {
+ *   console.log(result.message); // "Successfully migrated workflow state to story S-0033"
+ * }
+ */
+export async function migrateGlobalWorkflowState(sdlcRoot) {
+    const globalStatePath = getStateFilePath(sdlcRoot);
+    // Check if global state file exists
+    if (!fs.existsSync(globalStatePath)) {
+        return { migrated: false, message: 'No global workflow state file found' };
+    }
+    try {
+        // Read and parse the global state
+        const content = await fs.promises.readFile(globalStatePath, 'utf-8');
+        const state = JSON.parse(content);
+        // Check if workflow in progress IMMEDIATELY after reading state
+        if (state.currentAction) {
+            return {
+                migrated: false,
+                message: 'Skipping migration: workflow currently in progress. Complete or reset workflow before migrating.',
+            };
+        }
+        // Determine the story ID from the state
+        let storyId;
+        // Try to get story ID from context.options.story first
+        if (state.context?.options?.story) {
+            storyId = state.context.options.story;
+        }
+        // Fallback to first completed action's storyId
+        if (!storyId && state.completedActions && state.completedActions.length > 0) {
+            const firstAction = state.completedActions[0];
+            if (firstAction && 'storyId' in firstAction) {
+                storyId = firstAction.storyId;
+            }
+        }
+        // If no story ID found, leave state in place
+        if (!storyId) {
+            return {
+                migrated: false,
+                message: 'Cannot migrate: no story ID found in workflow state. Manual migration required.',
+            };
+        }
+        // SECURITY: Sanitize story ID to prevent path traversal
+        let sanitizedStoryId;
+        try {
+            sanitizedStoryId = sanitizeStoryId(storyId);
+        }
+        catch (error) {
+            return {
+                migrated: false,
+                message: `Cannot migrate: invalid story ID "${storyId}". ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        // Check if target location already exists (idempotent)
+        const targetPath = getStateFilePath(sdlcRoot, sanitizedStoryId);
+        if (fs.existsSync(targetPath)) {
+            // Validate existing target is not corrupt before deleting global backup
+            try {
+                const targetContent = await fs.promises.readFile(targetPath, 'utf-8');
+                const targetState = JSON.parse(targetContent);
+                const validation = validateWorkflowState(targetState);
+                if (!validation.valid) {
+                    return {
+                        migrated: false,
+                        message: `Target state file exists but is invalid. Keeping global file as backup. Manual intervention required. Errors: ${validation.errors.join(', ')}`,
+                    };
+                }
+                // Target is valid, safe to delete global
+                await fs.promises.unlink(globalStatePath);
+                return {
+                    migrated: true,
+                    message: `Global workflow state already migrated to story ${sanitizedStoryId}. Removed duplicate global file.`,
+                };
+            }
+            catch (error) {
+                return {
+                    migrated: false,
+                    message: `Target state file exists but is corrupted. Keeping global file as backup. Manual intervention required. Error: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+        // Create target directory
+        const targetDir = path.dirname(targetPath);
+        await fs.promises.mkdir(targetDir, { recursive: true });
+        // Write to target location atomically
+        const stateJson = JSON.stringify(state, null, 2);
+        await writeFileAtomic(targetPath, stateJson, { encoding: 'utf-8' });
+        // Verify target file was created successfully
+        if (!fs.existsSync(targetPath)) {
+            throw new Error('Target state file was not created successfully');
+        }
+        // Delete global file only after successful write
+        await fs.promises.unlink(globalStatePath);
+        return {
+            migrated: true,
+            message: `Successfully migrated workflow state from global to story-specific location: ${sanitizedStoryId}`,
+        };
+    }
+    catch (error) {
+        // Specific error handling for common cases
+        if (error && typeof error === 'object' && 'code' in error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                return {
+                    migrated: false,
+                    message: 'Global state file disappeared during migration. No action taken.',
+                };
+            }
+            if (code === 'EACCES' || code === 'EPERM') {
+                return {
+                    migrated: false,
+                    message: `Permission denied during migration. Check file permissions for: ${globalStatePath}`,
+                };
+            }
+        }
+        if (error instanceof SyntaxError) {
+            return {
+                migrated: false,
+                message: 'Global state file contains invalid JSON. Manual migration required.',
+            };
+        }
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            migrated: false,
+            message: `Migration failed: ${errorMsg}`,
+        };
+    }
+}
 //# sourceMappingURL=workflow-state.js.map