@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/commands/stories/review.js

@@ -0,0 +1,516 @@
+/**
+ * Stories Review Command
+ *
+ * Standalone command that discovers and reviews existing story files outside
+ * the full workflow pipeline. Runs automated code review (scanners + self-heal)
+ * on matched stories and produces PASS/FAIL verdicts.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories review "docs/qa/stories/AUTH-*.md"
+ * bmad-workflow stories review "stories/*.md" --scanners ai,lint --dry-run
+ * bmad-workflow stories review "stories/*.md" --json
+ * bmad-workflow stories review "stories/*.md" --block-on CRITICAL --max-fix 5
+ * ```
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import { createAgentRunner } from '../../services/agents/agent-runner-factory.js';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { GlobMatcher } from '../../services/file-system/glob-matcher.js';
+import { PathResolver } from '../../services/file-system/path-resolver.js';
+import { DefaultReviewPhaseExecutor } from '../../services/review/review-phase-executor.js';
+import { createScanners } from '../../services/review/scanner-factory.js';
+import { SelfHealLoop } from '../../services/review/self-heal-loop.js';
+import { classify } from '../../services/review/severity-classifier.js';
+import { ReviewReporter } from '../../services/review/review-reporter.js';
+import { TechDebtTracker } from '../../services/review/tech-debt-tracker.js';
+import { Severity } from '../../services/review/types.js';
+import { WorkflowSessionScaffolder } from '../../services/scaffolding/workflow-session-scaffolder.js';
+import { StoryParserFactory } from '../../services/parsers/story-parser-factory.js';
+import * as colors from '../../utils/colors.js';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+import { agentFlags } from '../../utils/shared-flags.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** Valid scanner names */
+const VALID_SCANNERS = new Set(['ai', 'lint', 'coderabbit']);
+/** Valid severity levels for --block-on */
+const VALID_SEVERITIES = new Set(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']);
+/** Severity rank for display ordering */
+const SEVERITY_RANK = {
+    CRITICAL: 4,
+    HIGH: 3,
+    MEDIUM: 2,
+    LOW: 1,
+};
+// ─── Validation helpers (exported for unit testing) ─────────────────────────
+/**
+ * Parse and validate --scanners flag value
+ *
+ * @param value - Comma-separated scanner names
+ * @returns Array of valid scanner names
+ * @throws Error if any scanner name is invalid
+ */
+export function parseScanners(value) {
+    const scanners = value.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    for (const scanner of scanners) {
+        if (!VALID_SCANNERS.has(scanner)) {
+            throw new Error(`Unknown scanner '${scanner}'. Valid: ${Array.from(VALID_SCANNERS).join(', ')}`);
+        }
+    }
+    if (scanners.length === 0) {
+        throw new Error('At least one scanner must be specified. Valid: ai, lint, coderabbit');
+    }
+    return scanners;
+}
+/**
+ * Parse and validate --block-on flag value
+ *
+ * @param value - Comma-separated severity names
+ * @returns Array of valid severity strings
+ * @throws Error if any severity is invalid
+ */
+export function parseBlockOn(value) {
+    const severities = value.split(',').map((s) => s.trim().toUpperCase()).filter(Boolean);
+    for (const severity of severities) {
+        if (!VALID_SEVERITIES.has(severity)) {
+            throw new Error(`Unknown severity '${severity}'. Valid: ${Array.from(VALID_SEVERITIES).join(', ')}`);
+        }
+    }
+    if (severities.length === 0) {
+        throw new Error('At least one severity must be specified. Valid: CRITICAL, HIGH, MEDIUM, LOW');
+    }
+    // Use the lowest specified severity as the threshold (most permissive blocker)
+    let lowestRank = Infinity;
+    let lowestSeverity = Severity.HIGH;
+    for (const sev of severities) {
+        const rank = SEVERITY_RANK[sev] ?? 0;
+        if (rank < lowestRank) {
+            lowestRank = rank;
+            lowestSeverity = sev;
+        }
+    }
+    return lowestSeverity;
+}
+/**
+ * Validate --max-fix is a positive integer
+ *
+ * @param value - Value to validate
+ * @returns The validated integer
+ * @throws Error if value is not a positive integer
+ */
+export function validateMaxFix(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`--max-fix must be a non-negative integer, got '${value}'`);
+    }
+    return value;
+}
+// ─── Command ────────────────────────────────────────────────────────────────
+/**
+ * Stories Review Command
+ *
+ * Discovers story files via glob pattern and runs automated code review on each.
+ * Supports --dry-run (findings only, no fixes) and --json (structured CI output).
+ */
+export default class StoriesReviewCommand extends Command {
+    static args = {
+        pattern: Args.string({
+            description: 'Glob pattern to match story files',
+            required: true,
+        }),
+    };
+    static description = 'Run automated code review on stories matching a glob pattern';
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> "docs/qa/stories/AUTH-*.md"',
+            description: 'Review all AUTH stories',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --scanners ai,lint',
+            description: 'Review with specific scanners',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --dry-run',
+            description: 'Report findings without auto-fix',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --json',
+            description: 'Output structured JSON for CI pipelines',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --block-on CRITICAL --max-fix 5',
+            description: 'Custom severity threshold and fix iterations',
+        },
+    ];
+    static flags = {
+        ...agentFlags,
+        'block-on': Flags.string({
+            default: 'CRITICAL,HIGH',
+            description: 'Comma-separated severities that cause FAIL verdict (default: CRITICAL,HIGH)',
+        }),
+        'dry-run': Flags.boolean({
+            default: false,
+            description: 'Report findings without running self-heal fix loop',
+        }),
+        json: Flags.boolean({
+            default: false,
+            description: 'Output structured JSON to stdout (for CI integration)',
+        }),
+        'max-fix': Flags.integer({
+            default: 3,
+            description: 'Maximum self-heal fix iterations per story',
+        }),
+        scanners: Flags.string({
+            default: 'ai,lint',
+            description: 'Comma-separated list of scanners to run (valid: ai, lint, coderabbit)',
+        }),
+    };
+    // Service instances
+    agentRunner;
+    fileManager;
+    globMatcher;
+    logger;
+    pathResolver;
+    storyParserFactory;
+    /**
+     * Run the command
+     */
+    async run() {
+        const { args, flags } = await this.parse(StoriesReviewCommand);
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        // Initialize services
+        const provider = (flags.provider || 'claude');
+        this.initializeServices(provider);
+        this.logger.info({ correlationId, flags, pattern: args.pattern }, 'Starting stories review command');
+        try {
+            // Step 1: Validate flags
+            const config = this.validateFlags(flags);
+            // Step 2: Discover story files
+            const storyFiles = await this.discoverStories(args.pattern);
+            // Step 3: Run review on each story
+            const results = await this.reviewStories(storyFiles, config, provider);
+            // Step 4: Write results to story files and session directory
+            const sessionDir = await this.writeResults(results);
+            // Step 5: Output results
+            const duration = Date.now() - startTime;
+            if (flags.json) {
+                this.outputJson(results);
+            }
+            else {
+                this.displaySummary(results, duration, sessionDir);
+            }
+            this.logger.info({
+                correlationId,
+                duration,
+                failed: results.filter((r) => r.verdict === 'FAIL').length,
+                passed: results.filter((r) => r.verdict === 'PASS').length,
+                total: results.length,
+            }, 'Stories review command completed');
+            // Set exit code based on results
+            const hasFailures = results.some((r) => r.verdict === 'FAIL');
+            if (hasFailures) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ correlationId, error: err }, 'Command failed');
+            if (flags.json) {
+                // In JSON mode, output error as JSON
+                this.log(JSON.stringify({ error: err.message, stories: [], summary: { failed: 0, passed: 0, total: 0 } }));
+                process.exitCode = 1;
+            }
+            else {
+                this.error(colors.error(err.message), { exit: 1 });
+            }
+        }
+    }
+    // ─── Step 1: Flag Validation ────────────────────────────────────────────
+    /**
+     * Validate and parse all CLI flags into a typed config object
+     */
+    validateFlags(flags) {
+        const scanners = parseScanners(flags.scanners);
+        const blockOn = parseBlockOn(flags['block-on']);
+        const maxFix = validateMaxFix(flags['max-fix']);
+        this.logger.info({ blockOn, dryRun: flags['dry-run'], maxFix, scanners }, 'Validated review config');
+        return {
+            blockOn,
+            dryRun: flags['dry-run'],
+            maxFix,
+            reviewTimeout: flags['review-timeout'],
+            scanners,
+            timeout: flags.timeout,
+        };
+    }
+    // ─── Step 2: Story Discovery ────────────────────────────────────────────
+    /**
+     * Discover story files matching the glob pattern
+     */
+    async discoverStories(pattern) {
+        this.logger.info({ pattern }, 'Discovering story files');
+        const matches = await this.globMatcher.expandPattern(pattern);
+        if (matches.length === 0) {
+            throw new Error(`No story files matched pattern: ${pattern}`);
+        }
+        this.logger.info({ count: matches.length, pattern }, 'Story files discovered');
+        return matches;
+    }
+    // ─── Step 3: Review Execution ───────────────────────────────────────────
+    /**
+     * Review all discovered stories sequentially
+     */
+    async reviewStories(storyFiles, config, provider) {
+        const results = [];
+        // Build scanner config from flags
+        const scannerConfig = {
+            aiReview: config.scanners.includes('ai'),
+            coderabbit: config.scanners.includes('coderabbit'),
+        };
+        // Create scanners
+        const scanners = await createScanners(this.agentRunner, scannerConfig, this.logger, {
+            reviewTimeout: config.reviewTimeout,
+            timeout: config.timeout,
+        });
+        // Filter to only requested scanners
+        // LintScanner is always created by factory; remove it if not requested
+        const filteredScanners = config.scanners.includes('lint')
+            ? scanners
+            : scanners.filter((s) => !(s.constructor.name === 'LintScanner'));
+        // Build workflow config for executor
+        const workflowConfig = {
+            dryRun: config.dryRun,
+            epicInterval: 0,
+            input: '',
+            parallel: 1,
+            pipeline: false,
+            prefix: '',
+            prdInterval: 0,
+            references: [],
+            review: true,
+            reviewBlockOn: config.blockOn,
+            reviewMaxFix: config.maxFix,
+            reviewScanners: config.scanners,
+            skipDev: true,
+            skipEpics: true,
+            skipStories: true,
+            storyInterval: 0,
+            verbose: false,
+        };
+        if (config.dryRun) {
+            // Dry-run mode: run scanners once, skip self-heal loop
+            this.logger.info('Dry-run mode: scanning without self-heal');
+            for (const storyFile of storyFiles) {
+                const storyId = this.extractStoryId(storyFile);
+                this.logger.info({ storyId, storyFile }, 'Scanning story (dry-run)');
+                const context = {
+                    baseBranch: 'main',
+                    changedFiles: [],
+                    projectRoot: process.cwd(),
+                    referenceFiles: [],
+                    storyFile,
+                    storyId,
+                };
+                // Run scanners without self-heal loop
+                const rawOutputs = [];
+                for (const scanner of filteredScanners) {
+                    try {
+                        const output = await scanner.scan(context);
+                        rawOutputs.push(output);
+                    }
+                    catch (error) {
+                        this.logger.warn({ error: error.message, storyId }, 'Scanner failed, continuing');
+                    }
+                }
+                // Classify issues
+                const issues = classify(rawOutputs);
+                // Determine verdict based on blocking threshold
+                const blockingIssues = issues.filter((issue) => (SEVERITY_RANK[issue.severity] ?? 0) >= (SEVERITY_RANK[config.blockOn] ?? 0));
+                results.push({
+                    issues,
+                    iterations: 0,
+                    message: blockingIssues.length > 0
+                        ? `${blockingIssues.length} blocking issue(s) (>= ${config.blockOn})`
+                        : undefined,
+                    path: storyFile,
+                    storyId,
+                    verdict: blockingIssues.length > 0 ? 'FAIL' : 'PASS',
+                });
+            }
+        }
+        else {
+            // Full review mode: use ReviewPhaseExecutor with SelfHealLoop
+            const techDebtTracker = new TechDebtTracker(this.logger);
+            const selfHealLoop = new SelfHealLoop(filteredScanners, classify, this.agentRunner, { fixTimeout: config.timeout, maxIterations: config.maxFix }, this.logger);
+            const executor = new DefaultReviewPhaseExecutor(selfHealLoop, techDebtTracker, this.logger);
+            const reviewResults = await executor.reviewAll(storyFiles, workflowConfig);
+            for (const [storyId, result] of Array.from(reviewResults.entries())) {
+                const storyFile = storyFiles.find((f) => this.extractStoryId(f) === storyId) ?? '';
+                results.push({
+                    issues: result.issues,
+                    iterations: result.iterations,
+                    message: result.message,
+                    path: storyFile,
+                    storyId,
+                    verdict: result.verdict,
+                });
+            }
+        }
+        return results;
+    }
+    // ─── Step 4: Result Writing ─────────────────────────────────────────────
+    /**
+     * Write review results to story files and session directory
+     */
+    async writeResults(results) {
+        // Create session directory
+        const scaffolder = new WorkflowSessionScaffolder(this.fileManager, this.logger);
+        const sessionDir = await scaffolder.createSessionStructure({
+            baseDir: 'docs/workflow-sessions',
+            prefix: 'stories-review',
+        });
+        // Use ReviewReporter for all report generation
+        const reporter = new ReviewReporter(this.fileManager, this.logger);
+        // Append per-story reports to story files
+        for (const result of results) {
+            if (result.path) {
+                const reviewResult = {
+                    issues: result.issues,
+                    iterations: result.iterations,
+                    message: result.message,
+                    verdict: result.verdict,
+                };
+                await reporter.appendStoryReport(result.path, reviewResult);
+            }
+        }
+        // Build results map for session reports
+        const resultsMap = new Map();
+        for (const result of results) {
+            resultsMap.set(result.storyId, {
+                issues: result.issues,
+                iterations: result.iterations,
+                message: result.message,
+                verdict: result.verdict,
+            });
+        }
+        // Write session-level reports (summary, per-story files, tech debt backlog)
+        await reporter.writeSessionReports(sessionDir, resultsMap);
+        this.logger.info({ sessionDir }, 'Review results written to session directory');
+        return sessionDir;
+    }
+    // ─── Step 5: Output ─────────────────────────────────────────────────────
+    /**
+     * Output structured JSON to stdout (for --json mode)
+     */
+    outputJson(results) {
+        const output = {
+            stories: results.map((r) => ({
+                issues: r.issues,
+                iterations: r.iterations,
+                path: r.path,
+                verdict: r.verdict,
+            })),
+            summary: {
+                failed: results.filter((r) => r.verdict === 'FAIL').length,
+                passed: results.filter((r) => r.verdict === 'PASS').length,
+                total: results.length,
+            },
+        };
+        this.log(JSON.stringify(output, null, 2));
+    }
+    /**
+     * Display human-readable summary table
+     */
+    displaySummary(results, duration, sessionDir) {
+        const passCount = results.filter((r) => r.verdict === 'PASS').length;
+        const failCount = results.filter((r) => r.verdict === 'FAIL').length;
+        const totalIssues = results.reduce((sum, r) => sum + r.issues.length, 0);
+        // Aggregate issues by severity
+        const allIssues = results.flatMap((r) => r.issues);
+        const issuesBySeverity = this.groupIssuesBySeverity(allIssues);
+        // Box drawing
+        const boxTop = '┌──────────────────────────────────────────────┐';
+        const boxDivider = '├──────────────────────────────────────────────┤';
+        const boxBottom = '└──────────────────────────────────────────────┘';
+        this.log('');
+        this.log(boxTop);
+        this.log('│          Story Review Summary                │');
+        this.log(boxDivider);
+        this.log(`│ ${colors.success('Passed:')}            ${passCount.toString().padEnd(25)}│`);
+        this.log(`│ ${colors.error('Failed:')}            ${failCount.toString().padEnd(25)}│`);
+        this.log(`│ Total Stories:       ${results.length.toString().padEnd(25)}│`);
+        this.log(boxDivider);
+        this.log(`│ Total Issues:        ${totalIssues.toString().padEnd(25)}│`);
+        for (const [severity, issues] of Object.entries(issuesBySeverity)) {
+            if (issues.length > 0) {
+                this.log(`│   ${severity}:${' '.repeat(Math.max(1, 17 - severity.length))}${issues.length.toString().padEnd(25)}│`);
+            }
+        }
+        this.log(boxDivider);
+        this.log(`│ Duration:            ${this.formatDuration(duration).padEnd(25)}│`);
+        this.log(`│ Session:             ${sessionDir.padEnd(25).slice(0, 25)}│`);
+        this.log(boxBottom);
+        // List failed stories
+        const failedStories = results.filter((r) => r.verdict === 'FAIL');
+        if (failedStories.length > 0) {
+            this.log('');
+            this.log(colors.bold('Failed Stories:'));
+            for (const story of failedStories) {
+                const blockingCount = story.issues.filter((i) => (SEVERITY_RANK[i.severity] ?? 0) >= (SEVERITY_RANK[Severity.HIGH] ?? 0)).length;
+                this.log(colors.error(`  ${story.storyId}: ${blockingCount} blocking issue(s)`));
+            }
+        }
+        this.log('');
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────────
+    /**
+     * Initialize service dependencies
+     */
+    initializeServices(provider = 'claude') {
+        this.logger = createLogger({ namespace: 'commands:stories:review' });
+        this.logger.info({ provider }, 'Initializing services');
+        this.fileManager = new FileManager(this.logger);
+        this.pathResolver = new PathResolver(this.fileManager, this.logger);
+        this.globMatcher = new GlobMatcher(this.fileManager, this.logger);
+        this.storyParserFactory = new StoryParserFactory(this.fileManager, this.logger);
+        this.agentRunner = createAgentRunner(provider, this.logger);
+        this.logger.debug({ provider }, 'Services initialized');
+    }
+    /**
+     * Extract story ID from file path
+     * e.g., "docs/stories/PROJ-story-1.001.md" → "PROJ-story-1.001"
+     */
+    extractStoryId(filePath) {
+        const filename = filePath.split('/').pop() ?? filePath;
+        return filename.replace(/\.md$/, '');
+    }
+    /**
+     * Group issues by severity level
+     */
+    groupIssuesBySeverity(issues) {
+        const groups = {
+            CRITICAL: [],
+            HIGH: [],
+            MEDIUM: [],
+            LOW: [],
+        };
+        for (const issue of issues) {
+            if (groups[issue.severity]) {
+                groups[issue.severity].push(issue);
+            }
+        }
+        return groups;
+    }
+    /**
+     * Format duration in human-readable format
+     */
+    formatDuration(ms) {
+        if (ms < 1000)
+            return `${ms}ms`;
+        if (ms < 60_000)
+            return `${(ms / 1000).toFixed(1)}s`;
+        if (ms < 3_600_000)
+            return `${(ms / 60_000).toFixed(1)}m`;
+        return `${(ms / 3_600_000).toFixed(1)}h`;
+    }
+}

package/dist/commands/workflow.d.ts

@@ -33,7 +33,15 @@ export default class Workflow extends Command {
         'prd-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         prefix: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'session-prefix': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        mcp: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'mcp-phases': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'mcp-preset': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        review: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'review-block-on': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'review-max-fix': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'review-scanners': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         qa: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'qa-prompt': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'qa-retries': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
@@ -43,6 +51,7 @@ export default class Workflow extends Command {
         'skip-stories': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'story-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'review-timeout': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'max-retries': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'retry-backoff': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -50,12 +59,72 @@ export default class Workflow extends Command {
     private cancelled;
     private logger;
     private orchestrator;
+    private reporter;
+    private scaffolder;
+    private sessionDir;
     /**
      * Main command execution
      *
      * Orchestrates the complete workflow with progress tracking and summary display.
      */
     run(): Promise<void>;
+    /**
+     * Collect all errors from workflow result into a flat list
+     *
+     * @param result - Workflow execution result
+     * @returns Array of error entries with phase context
+     * @private
+     */
+    private collectErrors;
+    /**
+     * Build dashboard summary from workflow result for final display
+     *
+     * @param result - Workflow execution result
+     * @returns DashboardSummary for the reporter's final dashboard
+     * @private
+     */
+    private buildDashboardSummary;
+    /**
+     * 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
+     */
+    private createScaffolderCallbacks;
+    /**
+     * 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
+     */
+    private mergeCallbacks;
+    /**
+     * 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
+     */
+    private derivePrefixFromFilename;
+    /**
+     * Display detailed failure information for each phase
+     *
+     * @param result - Workflow result with all phase data
+     * @private
+     */
+    private displayFailureDetails;
     /**
      * Display dry-run banner
      *
@@ -82,15 +151,35 @@ export default class Workflow extends Command {
      * @private
      */
     private displayPhaseHeader;
+    /**
+     * 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
+     */
+    private finalizeSession;
     /**
      * 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
      */
     private initializeServices;
+    /**
+     * Initialize session scaffolder and create session directory structure
+     *
+     * @param inputPath - Input file path for prefix derivation
+     * @param sessionPrefix - Optional explicit session prefix
+     * @private
+     */
+    private initializeSession;
     /**
      * Register SIGINT handler for graceful cancellation
      *