@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/commands/workflow.js

@@ -1,5 +1,9 @@
 import { Args, Command, Flags } from '@oclif/core';
+import { basename } from 'node:path';
+import { parseDuration } from '../utils/duration.js';
 import { createAgentRunner, isProviderSupported } from '../services/agents/agent-runner-factory.js';
+import { getRegisteredScannerNames } from '../services/review/scanner-factory.js';
+import { Severity } from '../services/review/types.js';
 import { FileManager } from '../services/file-system/file-manager.js';
 import { PathResolver } from '../services/file-system/path-resolver.js';
 import { BatchProcessor } from '../services/orchestration/batch-processor.js';
@@ -8,6 +12,8 @@ import { StoryTypeDetector } from '../services/orchestration/story-type-detector
 import { WorkflowOrchestrator } from '../services/orchestration/workflow-orchestrator.js';
 import { EpicParser } from '../services/parsers/epic-parser.js';
 import { PrdParser } from '../services/parsers/prd-parser.js';
+import { WorkflowSessionScaffolder } from '../services/scaffolding/workflow-session-scaffolder.js';
+import { WorkflowReporter } from '../services/WorkflowReporter.js';
 import * as colors from '../utils/colors.js';
 import { formatBox, formatTable } from '../utils/formatters.js';
 import { createLogger } from '../utils/logger.js';
@@ -77,13 +83,47 @@ export default class Workflow extends Command {
         }),
         prefix: Flags.string({
             default: '',
-            description: 'Filename prefix for generated files',
+            description: 'Filename prefix for generated files and session directory name',
+        }),
+        'session-prefix': Flags.string({
+            description: 'Session directory prefix (default: derived from input filename, e.g., PRD-feature.md → feature)',
         }),
         provider: Flags.string({
             default: 'claude',
             description: 'AI provider to use (claude, gemini, or opencode)',
             options: ['claude', 'gemini', 'opencode'],
         }),
+        mcp: Flags.boolean({
+            default: false,
+            description: 'Enable MCP tool injection for pipeline phases via Docker gateway',
+            helpGroup: 'MCP',
+        }),
+        'mcp-phases': Flags.string({
+            description: 'Comma-separated list of phases to inject MCP tools into (valid: epic,story,dev,review,qa)',
+            helpGroup: 'MCP',
+        }),
+        'mcp-preset': Flags.string({
+            description: 'MCP preset name to use for tool configuration (overrides config file)',
+            helpGroup: 'MCP',
+        }),
+        review: Flags.boolean({
+            default: false,
+            description: 'Enable automated code review phase between dev and QA',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-block-on': Flags.string({
+            description: 'Minimum severity to block story from QA (critical|high|medium|low)',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-max-fix': Flags.integer({
+            description: 'Maximum self-heal fix iterations (default: from config or 3)',
+            helpGroup: 'Review Workflow',
+        }),
+        'review-scanners': Flags.string({
+            description: 'Scanner names to run (e.g., lint, ai, coderabbit). Repeatable.',
+            helpGroup: 'Review Workflow',
+            multiple: true,
+        }),
         qa: Flags.boolean({
             default: false,
             description: 'Run QA workflow after development completes',
@@ -118,9 +158,17 @@ export default class Workflow extends Command {
             default: 60,
             description: 'Seconds between story development',
         }),
-        timeout: Flags.integer({
+        timeout: Flags.custom({
+            parse: async (input) => parseDuration(input),
+        })({
             default: 2_700_000,
-            description: 'Agent execution timeout in milliseconds (default: 2700000 = 45 minutes)',
+            description: 'Agent execution timeout — accepts durations like 30s, 5m, 1h, 90m, or raw milliseconds (default: 45m)',
+        }),
+        'review-timeout': Flags.custom({
+            parse: async (input) => parseDuration(input),
+        })({
+            description: 'AI review scanner timeout — overrides --timeout for review phase only (default: 5m)',
+            helpGroup: 'Review Workflow',
         }),
         'max-retries': Flags.integer({
             default: 0,
@@ -133,12 +181,15 @@ export default class Workflow extends Command {
         verbose: Flags.boolean({
             char: 'v',
             default: false,
-            description: 'Detailed output mode',
+            description: 'Show detailed output with spawn output streamed inline. In verbose mode, each spawn\'s output is displayed in real-time with visual delimiters. In non-TTY environments (e.g., CI/CD pipelines), output automatically falls back to plain-text format without ANSI escape codes.',
         }),
     };
     cancelled = false;
     logger;
     orchestrator;
+    reporter;
+    scaffolder;
+    sessionDir = null;
     /**
      * Main command execution
      *
@@ -160,13 +211,44 @@ export default class Workflow extends Command {
                 this.error(`Unsupported provider: ${flags.provider}. Use 'claude', 'gemini', or 'opencode'.`, { exit: 1 });
             }
             // Initialize services with parallel concurrency and provider
-            await this.initializeServices(flags.parallel, flags.provider);
+            await this.initializeServices(flags.parallel, flags.provider, flags.verbose);
             // Register signal handlers
             this.registerSignalHandlers();
+            // Initialize session scaffolder and create session structure
+            await this.initializeSession(args.input, flags['session-prefix']);
             // Show dry-run banner if applicable
             if (flags['dry-run']) {
                 this.displayDryRunBanner();
             }
+            // Validate review flags when --review is enabled
+            if (flags.review) {
+                // Validate --review-scanners against registered scanner names
+                if (flags['review-scanners'] && flags['review-scanners'].length > 0) {
+                    const validScanners = getRegisteredScannerNames();
+                    const invalidScanners = flags['review-scanners'].filter((s) => !validScanners.includes(s));
+                    if (invalidScanners.length > 0) {
+                        this.error(`Unknown --review-scanners value(s): ${invalidScanners.join(', ')}. Valid scanners are: ${validScanners.join(', ')}`, { exit: 1 });
+                    }
+                }
+                // Validate --review-max-fix is non-negative
+                if (flags['review-max-fix'] !== undefined && flags['review-max-fix'] < 0) {
+                    this.error(`--review-max-fix must be a non-negative integer, got: ${flags['review-max-fix']}`, { exit: 1 });
+                }
+                // Validate --review-block-on against severity enum
+                if (flags['review-block-on'] !== undefined) {
+                    const validSeverities = ['critical', 'high', 'medium', 'low'];
+                    if (!validSeverities.includes(flags['review-block-on'])) {
+                        this.error(`Invalid --review-block-on value: ${flags['review-block-on']}. Valid values are: ${validSeverities.join(', ')}`, { exit: 1 });
+                    }
+                }
+            }
+            // Map --review-block-on string to Severity enum
+            const severityMap = {
+                critical: Severity.CRITICAL,
+                high: Severity.HIGH,
+                low: Severity.LOW,
+                medium: Severity.MEDIUM,
+            };
             // Build workflow configuration
             const config = {
                 autoFix: flags['auto-fix'],
@@ -175,6 +257,9 @@ export default class Workflow extends Command {
                 epicInterval: flags['epic-interval'],
                 input: args.input,
                 maxRetries: flags['max-retries'],
+                mcp: flags.mcp || undefined,
+                mcpPhases: flags['mcp-phases'] ? flags['mcp-phases'].split(',').map((s) => s.trim()) : undefined,
+                mcpPreset: flags['mcp-preset'],
                 model: flags.model,
                 parallel: flags.parallel,
                 pipeline: flags.pipeline,
@@ -186,6 +271,11 @@ export default class Workflow extends Command {
                 qaRetries: flags['qa-retries'],
                 references: flags.reference || [],
                 retryBackoffMs: flags['retry-backoff'],
+                review: flags.review,
+                reviewBlockOn: flags['review-block-on'] ? severityMap[flags['review-block-on']] : undefined,
+                reviewMaxFix: flags['review-max-fix'],
+                reviewScanners: flags['review-scanners'],
+                reviewTimeout: flags['review-timeout'],
                 skipDev: flags['skip-dev'],
                 skipEpics: flags['skip-epics'],
                 skipStories: flags['skip-stories'],
@@ -193,6 +283,35 @@ export default class Workflow extends Command {
                 timeout: flags.timeout,
                 verbose: flags.verbose,
             };
+            // Validate --mcp-phases when --mcp is enabled
+            if (config.mcp && config.mcpPhases) {
+                const validPhases = ['epic', 'story', 'dev', 'review', 'qa'];
+                const invalidPhases = config.mcpPhases.filter((p) => !validPhases.includes(p));
+                if (invalidPhases.length > 0) {
+                    this.error(`Invalid --mcp-phases value(s): ${invalidPhases.join(', ')}. Valid phases are: ${validPhases.join(', ')}`, { exit: 1 });
+                }
+            }
+            // MCP gateway health pre-check (AC: #5, #6)
+            if (config.mcp) {
+                try {
+                    const gatewayUrl = 'http://localhost:8080';
+                    const healthUrl = `${gatewayUrl}/health`;
+                    const response = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+                    if (response.ok) {
+                        if (flags.verbose) {
+                            this.log(colors.info('MCP gateway is healthy'));
+                        }
+                    }
+                    else {
+                        this.log(colors.warning(`MCP gateway returned status ${response.status} — continuing without MCP`));
+                        config.mcp = false;
+                    }
+                }
+                catch {
+                    this.log(colors.warning('MCP gateway is not reachable — continuing without MCP'));
+                    config.mcp = false;
+                }
+            }
             // Log configuration if verbose
             if (flags.verbose) {
                 this.logger.info({ config }, 'Workflow configuration');
@@ -201,21 +320,37 @@ export default class Workflow extends Command {
             // Execute workflow
             this.log(colors.info('\nStarting workflow orchestration...\n'));
             const result = await this.orchestrator.execute(config);
+            // Wait for reporter listr2 tasks to complete and clean up
+            await this.reporter?.waitForCompletion();
+            // Write session report on completion (includes cancellation case)
+            await this.finalizeSession(result, config);
+            // Build dashboard summary from workflow result
+            const dashboardSummary = this.buildDashboardSummary(result);
+            // Display final dashboard using reporter (AC: #4)
+            this.reporter?.displayFinalDashboard(dashboardSummary);
+            this.reporter?.dispose();
+            // Display failure details if any
+            if (result.totalFailures > 0) {
+                this.displayFailureDetails(result);
+            }
+            // Dry run reminder
+            if (config.dryRun) {
+                this.log('\n' + colors.warning('No files were created (dry-run mode)'));
+            }
             // Check for cancellation
             if (this.cancelled) {
                 this.log('\n' + colors.warning('Workflow cancelled by user'));
-                this.displayFinalSummary(result, config);
                 process.exit(130); // Standard interrupted exit code
             }
-            // Display final summary
-            this.displayFinalSummary(result, config);
             // Exit with appropriate code
             if (!result.overallSuccess) {
                 this.error('Workflow completed with failures', { exit: 1 });
             }
-            this.log('\n' + colors.success('✓ Workflow completed successfully!'));
+            this.log('\n' + colors.success('Workflow completed successfully!'));
         }
         catch (error) {
+            // Clean up reporter on error
+            this.reporter?.dispose();
             this.logger?.error({ error: error.message }, 'Workflow command failed');
             // Display user-friendly error
             this.log('\n' + colors.error('✗ Workflow failed:'));
@@ -223,6 +358,251 @@ export default class Workflow extends Command {
             this.error('Workflow execution failed', { exit: 1 });
         }
     }
+    /**
+     * Collect all errors from workflow result into a flat list
+     *
+     * @param result - Workflow execution result
+     * @returns Array of error entries with phase context
+     * @private
+     */
+    collectErrors(result) {
+        const errors = [];
+        const now = new Date().toISOString();
+        if (result.epicPhase?.failures) {
+            for (const failure of result.epicPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'epic',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.storyPhase?.failures) {
+            for (const failure of result.storyPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'story',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.devPhase?.failures) {
+            for (const failure of result.devPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'dev',
+                    timestamp: now,
+                });
+            }
+        }
+        if (result.qaPhase?.failures) {
+            for (const failure of result.qaPhase.failures) {
+                errors.push({
+                    error: failure.error,
+                    identifier: failure.identifier,
+                    phase: 'qa',
+                    timestamp: now,
+                });
+            }
+        }
+        return errors;
+    }
+    /**
+     * Build dashboard summary from workflow result for final display
+     *
+     * @param result - Workflow execution result
+     * @returns DashboardSummary for the reporter's final dashboard
+     * @private
+     */
+    buildDashboardSummary(result) {
+        const phases = [];
+        // Add phases in order: epic, story, dev, qa
+        if (result.epicPhase && !result.epicPhase.skipped) {
+            phases.push({
+                duration: result.epicPhase.duration,
+                failed: result.epicPhase.failures.length,
+                name: 'epic',
+                passed: result.epicPhase.success,
+            });
+        }
+        if (result.storyPhase && !result.storyPhase.skipped) {
+            phases.push({
+                duration: result.storyPhase.duration,
+                failed: result.storyPhase.failures.length,
+                name: 'story',
+                passed: result.storyPhase.success,
+            });
+        }
+        if (result.devPhase && !result.devPhase.skipped) {
+            phases.push({
+                duration: result.devPhase.duration,
+                failed: result.devPhase.failures.length,
+                name: 'dev',
+                passed: result.devPhase.success,
+            });
+        }
+        if (result.qaPhase && !result.qaPhase.skipped) {
+            phases.push({
+                duration: result.qaPhase.duration,
+                failed: result.qaPhase.failures.length,
+                name: 'qa',
+                passed: result.qaPhase.success,
+            });
+        }
+        // Build session report path from session directory
+        const sessionReportPath = this.sessionDir ? `${this.sessionDir}/SESSION_REPORT.md` : undefined;
+        return {
+            failedCount: result.totalFailures,
+            passedCount: result.totalFilesProcessed - result.totalFailures,
+            phases,
+            sessionReportPath,
+            totalDuration: result.totalDuration,
+            totalSpawns: result.totalFilesProcessed,
+        };
+    }
+    /**
+     * Create callbacks object wired to scaffolder for incremental artifact writing
+     *
+     * All callbacks are wrapped in try-catch to prevent scaffolder errors from
+     * interrupting workflow execution (AC: #9).
+     * @returns WorkflowCallbacks object with scaffolder integration
+     * @private
+     */
+    createScaffolderCallbacks() {
+        return {
+            onSpawnComplete: (context) => {
+                // Write spawn output immediately for crash resilience (AC: #8)
+                try {
+                    // Map phaseName to spawn type
+                    const typeMap = {
+                        dev: 'dev',
+                        epic: 'epic',
+                        story: 'story',
+                    };
+                    const spawnType = typeMap[context.phaseName] || 'dev';
+                    // Fire-and-forget write to not block workflow
+                    this.scaffolder
+                        .writeSpawnOutput({
+                        completedAt: context.endTime ? new Date(context.endTime).toISOString() : undefined,
+                        content: context.output || '',
+                        duration: context.duration,
+                        errors: context.error,
+                        spawnId: context.spawnId,
+                        success: context.success,
+                        type: spawnType,
+                    })
+                        .catch((writeError) => {
+                        this.logger.warn({ error: writeError.message, spawnId: context.spawnId }, 'Async spawn output write failed');
+                    });
+                }
+                catch (error) {
+                    // Log but don't propagate - workflow must continue (AC: #9)
+                    this.logger.warn({ error: error.message, spawnId: context.spawnId }, 'Failed to write spawn output');
+                }
+            },
+        };
+    }
+    /**
+     * Merge multiple callback objects into a single callbacks object
+     *
+     * When the same callback is defined in multiple sources, all handlers are called
+     * in sequence (fire-and-forget). This enables dual-channel output where scaffolder
+     * and reporter receive events independently.
+     *
+     * @param sources - Array of WorkflowCallbacks objects to merge
+     * @returns Merged WorkflowCallbacks object
+     * @private
+     */
+    mergeCallbacks(...sources) {
+        const merged = {};
+        const callbackNames = [
+            'onPhaseStart',
+            'onPhaseComplete',
+            'onLayerStart',
+            'onLayerComplete',
+            'onSpawnStart',
+            'onSpawnComplete',
+            'onSpawnOutput',
+            'onError',
+        ];
+        for (const name of callbackNames) {
+            const handlers = sources.map((s) => s[name]).filter(Boolean);
+            if (handlers.length > 0) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ;
+                merged[name] = (...args) => {
+                    for (const handler of handlers) {
+                        try {
+                            handler(...args);
+                        }
+                        catch (error) {
+                            // Fire-and-forget: log but don't propagate callback errors
+                            const errMsg = error instanceof Error ? error.message : String(error);
+                            this.logger?.warn({ callback: name, error: errMsg }, 'Callback error');
+                        }
+                    }
+                };
+            }
+        }
+        return merged;
+    }
+    /**
+     * Derive session prefix from input filename
+     *
+     * Extracts meaningful prefix from input path:
+     * - PRD-feature.md → feature
+     * - PRD-my-project.md → my-project
+     * - epic-001.md → epic-001
+     *
+     * @param inputPath - Input file path
+     * @returns Derived prefix string
+     * @private
+     */
+    derivePrefixFromFilename(inputPath) {
+        const filename = basename(inputPath, '.md');
+        // Handle PRD-* pattern
+        if (filename.startsWith('PRD-')) {
+            return filename.slice(4); // Remove 'PRD-' prefix
+        }
+        // Use filename as-is for other patterns
+        return filename;
+    }
+    /**
+     * Display detailed failure information for each phase
+     *
+     * @param result - Workflow result with all phase data
+     * @private
+     */
+    displayFailureDetails(result) {
+        this.log('\n' + colors.error('Failures:'));
+        if (result.epicPhase?.failures.length) {
+            this.log(colors.error(`  Epic Phase:`));
+            for (const failure of result.epicPhase.failures) {
+                this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+            }
+        }
+        if (result.storyPhase?.failures.length) {
+            this.log(colors.error(`  Story Phase:`));
+            for (const failure of result.storyPhase.failures) {
+                this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+            }
+        }
+        if (result.devPhase?.failures.length) {
+            this.log(colors.error(`  Development Phase:`));
+            for (const failure of result.devPhase.failures) {
+                this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+            }
+        }
+        if (result.qaPhase?.failures.length) {
+            this.log(colors.error(`  QA Phase:`));
+            for (const failure of result.qaPhase.failures) {
+                this.log(colors.error(`    • ${failure.identifier}: ${failure.error}`));
+            }
+        }
+    }
     /**
      * Display dry-run banner
      *
@@ -345,6 +725,11 @@ export default class Workflow extends Command {
         if (config.dryRun) {
             this.log('\n' + colors.warning('No files were created (dry-run mode)'));
         }
+        // Display session directory path (AC: #7)
+        if (this.sessionDir) {
+            const sessionBanner = formatBox('Session Directory', `${this.sessionDir}\n\nView spawn outputs, session report, and workflow log at this location.`);
+            this.log('\n' + colors.info(sessionBanner));
+        }
     }
     /**
      * Display phase header with visual separator
@@ -361,17 +746,73 @@ export default class Workflow extends Command {
         this.log(colors.bold(`║  ${header}  ║`));
         this.log(colors.bold(`╚${separator}╝`) + '\n');
     }
+    /**
+     * Finalize session by writing session report and workflow log
+     *
+     * Called on workflow completion (success or failure).
+     * Errors are caught and logged but don't interrupt workflow completion.
+     *
+     * @param result - Workflow execution result
+     * @param _config - Workflow configuration used (unused for now)
+     * @private
+     */
+    async finalizeSession(result, _config) {
+        if (!this.sessionDir) {
+            this.logger.warn('Session directory not initialized, skipping session finalization');
+            return;
+        }
+        try {
+            // Build session report summary from workflow result
+            const sessionId = basename(this.sessionDir);
+            const now = new Date().toISOString();
+            const summary = {
+                duration: result.totalDuration,
+                endedAt: now,
+                errors: this.collectErrors(result),
+                overallSuccess: result.overallSuccess,
+                phases: {
+                    developments: {
+                        completed: result.devPhase?.success ?? 0,
+                        failed: result.devPhase?.failures.length ?? 0,
+                        total: (result.devPhase?.success ?? 0) + (result.devPhase?.failures.length ?? 0),
+                    },
+                    epics: {
+                        completed: result.epicPhase?.success ?? 0,
+                        failed: result.epicPhase?.failures.length ?? 0,
+                        total: (result.epicPhase?.success ?? 0) + (result.epicPhase?.failures.length ?? 0),
+                    },
+                    stories: {
+                        completed: result.storyPhase?.success ?? 0,
+                        failed: result.storyPhase?.failures.length ?? 0,
+                        total: (result.storyPhase?.success ?? 0) + (result.storyPhase?.failures.length ?? 0),
+                    },
+                },
+                sessionId,
+                spawnFiles: [], // Will be populated by scaffolder internals if needed
+                startedAt: new Date(Date.now() - result.totalDuration).toISOString(),
+            };
+            await this.scaffolder.writeSessionReport(summary);
+            this.logger.info({ sessionDir: this.sessionDir }, 'Session report written');
+            // Note: workflow-log.yaml would require WorkflowLogger integration
+            // which is optional per the orchestrator config. For now, session report
+            // is the primary artifact.
+        }
+        catch (error) {
+            this.logger.warn({ error: error.message }, 'Failed to finalize session');
+        }
+    }
     /**
      * Initialize services and dependencies
      *
      * Creates all service instances needed for workflow orchestration.
      * @param maxConcurrency - Maximum number of concurrent operations
      * @param provider - AI provider to use (claude or gemini)
+     * @param verbose - Enable verbose output mode
      * @private
      */
-    async initializeServices(maxConcurrency = 3, provider = 'claude') {
-        // Create logger
-        this.logger = createLogger({ namespace: 'commands:workflow' });
+    async initializeServices(maxConcurrency = 3, provider = 'claude', verbose = false) {
+        // Create logger — suppress INFO logs in non-verbose mode to keep terminal clean
+        this.logger = createLogger({ level: verbose ? 'info' : 'warn', namespace: 'commands:workflow' });
         this.logger.info({ provider }, 'Initializing services with AI provider');
         // Create file system services
         const fileManager = new FileManager(this.logger);
@@ -387,10 +828,20 @@ export default class Workflow extends Command {
         const inputDetector = new InputDetector(fileManager, this.logger);
         // Create story type detector for auto-documentation
         const storyTypeDetector = new StoryTypeDetector(this.logger);
-        // Create orchestrator
+        // Create session scaffolder for workflow artifacts
+        this.scaffolder = new WorkflowSessionScaffolder(fileManager, this.logger);
+        // Create workflow reporter for live progress visualization (AC: #1)
+        this.reporter = new WorkflowReporter({
+            nonTTY: !process.stdout.isTTY,
+            verbose,
+        });
+        // Merge scaffolder callbacks with reporter callbacks for dual-channel output (AC: #1)
+        const callbacks = this.mergeCallbacks(this.createScaffolderCallbacks(), this.reporter.getCallbacks());
+        // Create orchestrator with merged callbacks
         this.orchestrator = new WorkflowOrchestrator({
             agentRunner,
             batchProcessor,
+            callbacks,
             epicParser,
             fileManager,
             inputDetector,
@@ -399,7 +850,29 @@ export default class Workflow extends Command {
             prdParser,
             storyTypeDetector,
         });
-        this.logger.info({ provider }, 'Services initialized successfully');
+        this.logger.info({ provider, verbose }, 'Services initialized successfully');
+    }
+    /**
+     * Initialize session scaffolder and create session directory structure
+     *
+     * @param inputPath - Input file path for prefix derivation
+     * @param sessionPrefix - Optional explicit session prefix
+     * @private
+     */
+    async initializeSession(inputPath, sessionPrefix) {
+        try {
+            // Derive prefix: explicit flag > derived from filename
+            const prefix = sessionPrefix || this.derivePrefixFromFilename(inputPath);
+            this.sessionDir = await this.scaffolder.createSessionStructure({
+                baseDir: 'docs/workflow-sessions',
+                prefix,
+            });
+            this.logger.info({ prefix, sessionDir: this.sessionDir }, 'Workflow session initialized');
+        }
+        catch (error) {
+            // Log but don't fail workflow - session is optional (AC: #9)
+            this.logger.warn({ error: error.message }, 'Failed to initialize session structure');
+        }
     }
     /**
      * Register SIGINT handler for graceful cancellation