@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/stories/qa.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Stories QA Command
+ *
+ * Executes QA workflow for stories matching glob patterns sequentially.
+ * Runs QA agent for deep dive review, then Dev agent for fix-forward,
+ * with configurable retry loops until gate passes or max retries reached.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories qa "docs/qa/stories/AUTH-*.md"
+ * bmad-workflow stories qa "docs/qa/stories/*.md" --max-retries 3
+ * bmad-workflow stories qa "stories/*.md" --qa-prompt "Focus on security"
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * Stories QA Command
+ *
+ * Runs QA review and dev fix-forward cycles for stories sequentially.
+ * CRITICAL: No parallel execution - stories are processed one at a time.
+ */
+export default class StoriesQaCommand extends Command {
+    static args: {
+        pattern: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        'dev-prompt': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        interval: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'max-retries': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'qa-prompt': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        reference: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private agentRunner;
+    private fileManager;
+    private globMatcher;
+    private logger;
+    private pathResolver;
+    private storyParserFactory;
+    /**
+     * Run the command
+     */
+    run(): Promise<void>;
+    /**
+     * Append QA workflow summary to story file
+     */
+    private appendQaSummaryToStory;
+    /**
+     * Build Claude CLI prompt for Dev fix-forward
+     */
+    private buildDevFixPrompt;
+    /**
+     * Build Claude CLI prompt for QA review
+     */
+    private buildQaPrompt;
+    /**
+     * Display countdown timer between stories
+     */
+    private displayCountdown;
+    /**
+     * Display summary report
+     */
+    private displaySummaryReport;
+    /**
+     * Extract gate status from story content or gate file
+     * This is a simple heuristic - looks for Gate: STATUS pattern in story
+     * IMPORTANT: Returns the LAST occurrence since QA reviews are appended
+     */
+    private extractGateStatus;
+    /**
+     * Initialize service dependencies
+     */
+    private initializeServices;
+    /**
+     * Match story files using glob pattern
+     */
+    private matchStoryFiles;
+    /**
+     * Move story to appropriate folder based on gate status
+     */
+    private moveStoryBasedOnGate;
+    /**
+     * Process stories sequentially through QA workflow
+     */
+    private qaStoriesSequentially;
+    /**
+     * Process a single story through QA workflow
+     */
+    private qaStory;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}

package/dist/commands/stories/qa.js

@@ -0,0 +1,530 @@
+/**
+ * Stories QA Command
+ *
+ * Executes QA workflow for stories matching glob patterns sequentially.
+ * Runs QA agent for deep dive review, then Dev agent for fix-forward,
+ * with configurable retry loops until gate passes or max retries reached.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories qa "docs/qa/stories/AUTH-*.md"
+ * bmad-workflow stories qa "docs/qa/stories/*.md" --max-retries 3
+ * bmad-workflow stories qa "stories/*.md" --qa-prompt "Focus on security"
+ * ```
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import path from 'node:path';
+import { isEpicStory } from '../../models/story.js';
+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 { StoryParserFactory } from '../../services/parsers/story-parser-factory.js';
+import * as colors from '../../utils/colors.js';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+import { createSpinner } from '../../utils/progress.js';
+/**
+ * Agent timeout in milliseconds (30 minutes)
+ * QA and Dev agents need longer timeouts for comprehensive analysis
+ */
+const AGENT_TIMEOUT_MS = 1_800_000;
+/**
+ * Stories QA Command
+ *
+ * Runs QA review and dev fix-forward cycles for stories sequentially.
+ * CRITICAL: No parallel execution - stories are processed one at a time.
+ */
+export default class StoriesQaCommand extends Command {
+    static args = {
+        pattern: Args.string({
+            description: 'Glob pattern to match story files',
+            required: true,
+        }),
+    };
+    static description = 'Execute QA workflow for stories: deep dive review, dev fix-forward, and gate validation';
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> "docs/qa/stories/AUTH-*.md"',
+            description: 'QA all AUTH stories in qa folder',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "docs/qa/stories/*.md" --max-retries 3',
+            description: 'QA stories with up to 3 fix-forward cycles',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --qa-prompt "Focus on security vulnerabilities"',
+            description: 'QA with custom prompt instructions',
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "stories/*.md" --interval 60',
+            description: 'QA stories with 60s countdown between each',
+        },
+    ];
+    static flags = {
+        'dev-prompt': Flags.string({
+            description: 'Custom prompt/instructions for dev fix-forward phase',
+            helpGroup: 'Prompt Customization',
+        }),
+        interval: Flags.integer({
+            default: 30,
+            description: 'Seconds to wait between stories',
+        }),
+        'max-retries': Flags.integer({
+            default: 2,
+            description: 'Maximum QA → Dev fix cycles before giving up (0 = QA only, no fix-forward)',
+        }),
+        provider: Flags.string({
+            default: 'claude',
+            description: 'AI provider to use (claude or gemini)',
+            options: ['claude', 'gemini'],
+        }),
+        'qa-prompt': Flags.string({
+            description: 'Custom prompt/instructions for QA review phase',
+            helpGroup: 'Prompt Customization',
+        }),
+        reference: Flags.string({
+            description: 'Additional context files for agents',
+            multiple: true,
+        }),
+    };
+    // Service instances
+    agentRunner;
+    fileManager;
+    globMatcher;
+    logger;
+    pathResolver;
+    storyParserFactory;
+    /**
+     * Run the command
+     */
+    async run() {
+        const { args, flags } = await this.parse(StoriesQaCommand);
+        const startTime = Date.now();
+        const correlationId = generateCorrelationId();
+        // Initialize services with selected provider
+        const provider = (flags.provider || 'claude');
+        this.initializeServices(provider);
+        this.logger.info({
+            correlationId,
+            flags,
+            pattern: args.pattern,
+        }, 'Starting stories QA command');
+        try {
+            // Match story files using glob pattern
+            const storyFiles = await this.matchStoryFiles(args.pattern);
+            if (storyFiles.length === 0) {
+                this.log(colors.warning(`No story files matched pattern: ${args.pattern}`));
+                return;
+            }
+            this.log(colors.info(`Found ${storyFiles.length} story file(s) to QA`));
+            this.log('');
+            // Process stories sequentially
+            const results = await this.qaStoriesSequentially(storyFiles, flags);
+            // Display summary report
+            const duration = Date.now() - startTime;
+            this.displaySummaryReport(results, duration);
+            this.logger.info({
+                correlationId,
+                duration,
+                failed: results.filter((r) => !r.success).length,
+                passed: results.filter((r) => r.finalGate === 'PASS').length,
+                succeeded: results.filter((r) => r.success).length,
+                total: results.length,
+            }, 'Stories QA command completed');
+            // Exit with error if any stories failed
+            const failedCount = results.filter((r) => !r.success).length;
+            if (failedCount > 0) {
+                this.error(colors.error(`${failedCount} story QA(s) failed`), { exit: 1 });
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ correlationId, error: err }, 'Command failed');
+            this.error(colors.error(err.message), { exit: 1 });
+        }
+    }
+    /**
+     * Append QA workflow summary to story file
+     */
+    async appendQaSummaryToStory(storyPath, result, totalRetries) {
+        const content = await this.fileManager.readFile(storyPath);
+        const timestamp = new Date().toISOString();
+        const summary = `
+
+## QA Workflow Summary
+
+### Workflow Date: ${timestamp.split('T')[0]}
+
+### Final Gate Status: ${result.finalGate}
+
+### Workflow Statistics
+- Retries Used: ${result.retriesUsed}/${totalRetries}
+- Final Location: ${result.movedTo === 'done' ? 'docs/done/stories' : result.movedTo === 'stories' ? 'docs/stories (returned for rework)' : 'unchanged'}
+- Success: ${result.success ? 'Yes' : 'No'}
+${result.error ? `- Error: ${result.error}` : ''}
+
+### Workflow Phases Completed
+1. [${result.retriesUsed >= 0 ? 'x' : ' '}] Initial QA Deep Dive Review
+${result.retriesUsed > 0 ? `2. [x] Dev Fix-Forward (${result.retriesUsed} cycle${result.retriesUsed > 1 ? 's' : ''})` : ''}
+${result.finalGate === 'PASS' ? '3. [x] Final QA Validation - PASSED' : result.finalGate === 'WAIVED' ? '3. [x] Final QA Validation - WAIVED' : '3. [ ] Final QA Validation - Not Passed'}
+`;
+        // Append summary to file
+        await this.fileManager.writeFile(storyPath, content + summary);
+        this.logger.info({ storyPath }, 'Appended QA workflow summary to story');
+    }
+    /**
+     * Build Claude CLI prompt for Dev fix-forward
+     */
+    buildDevFixPrompt(storyPath, customPrompt, references) {
+        let prompt = `@.bmad-core/agents/dev.md\n\n`;
+        prompt += `*review-qa ${storyPath}\n\n`;
+        if (references && references.length > 0) {
+            prompt += 'References:\n';
+            for (const ref of references) {
+                const resolvedPath = path.resolve(ref);
+                prompt += `@${resolvedPath}\n`;
+            }
+            prompt += '\n';
+        }
+        // Default dev fix-forward instructions
+        const defaultInstructions = `Fix forward based on QA findings:
+- Read the QA Results section and gate file for this story
+- Address all high-severity issues first
+- Fix medium and low severity issues
+- Add missing tests to close coverage gaps
+- Update the story's Dev Agent Record section
+- Run all tests to ensure fixes don't break functionality
+- Set status to Ready for Review when complete`;
+        prompt += customPrompt || defaultInstructions;
+        prompt += '\n\n*yolo mode* always update the story file as you go\n';
+        return prompt;
+    }
+    /**
+     * Build Claude CLI prompt for QA review
+     */
+    buildQaPrompt(storyPath, customPrompt, references) {
+        let prompt = `@.bmad-core/agents/qa.md\n\n`;
+        prompt += `*review ${storyPath}\n\n`;
+        if (references && references.length > 0) {
+            prompt += 'References:\n';
+            for (const ref of references) {
+                const resolvedPath = path.resolve(ref);
+                prompt += `@${resolvedPath}\n`;
+            }
+            prompt += '\n';
+        }
+        // Default QA deep dive instructions
+        const defaultInstructions = `Perform a comprehensive deep dive review of this story implementation:
+- Analyze each acceptance criterion against the actual implementation
+- Review code quality, architecture patterns, and best practices
+- Check test coverage and test quality
+- Identify security vulnerabilities and performance issues
+- Validate error handling and edge cases
+- Assess technical debt and maintainability
+- Update the story's QA Results section with detailed findings
+- Create/update the gate file with your assessment (PASS/CONCERNS/FAIL/WAIVED)`;
+        prompt += customPrompt || defaultInstructions;
+        prompt += '\n\n*yolo mode* always update the story file as you go\n';
+        return prompt;
+    }
+    /**
+     * Display countdown timer between stories
+     */
+    async displayCountdown(intervalSeconds) {
+        /* eslint-disable no-await-in-loop */
+        for (let remaining = intervalSeconds; remaining > 0; remaining--) {
+            process.stdout.write(`\r${colors.warning(`⏳ Next story in ${remaining}s...`)}`);
+            await this.sleep(1000);
+        }
+        /* eslint-enable no-await-in-loop */
+        process.stdout.write('\r' + ' '.repeat(40) + '\r'); // Clear countdown line
+    }
+    /**
+     * Display summary report
+     */
+    displaySummaryReport(results, duration) {
+        const passCount = results.filter((r) => r.finalGate === 'PASS').length;
+        const concernsCount = results.filter((r) => r.finalGate === 'CONCERNS').length;
+        const failCount = results.filter((r) => r.finalGate === 'FAIL').length;
+        const waivedCount = results.filter((r) => r.finalGate === 'WAIVED').length;
+        const errorCount = results.filter((r) => !r.success).length;
+        const movedToDone = results.filter((r) => r.movedTo === 'done').length;
+        const movedBack = results.filter((r) => r.movedTo === 'stories').length;
+        // Box drawing
+        const boxTop = '┌─────────────────────────────────────────┐';
+        const boxDivider = '├─────────────────────────────────────────┤';
+        const boxBottom = '└─────────────────────────────────────────┘';
+        this.log('');
+        this.log(boxTop);
+        this.log('│         Story QA Summary                │');
+        this.log(boxDivider);
+        this.log(`│ ${colors.success('PASS:')}            ${passCount.toString().padEnd(20)}│`);
+        if (concernsCount > 0) {
+            this.log(`│ ${colors.warning('CONCERNS:')}        ${concernsCount.toString().padEnd(20)}│`);
+        }
+        if (failCount > 0) {
+            this.log(`│ ${colors.error('FAIL:')}            ${failCount.toString().padEnd(20)}│`);
+        }
+        if (waivedCount > 0) {
+            this.log(`│ WAIVED:           ${waivedCount.toString().padEnd(20)}│`);
+        }
+        if (errorCount > 0) {
+            this.log(`│ ${colors.error('Errors:')}          ${errorCount.toString().padEnd(20)}│`);
+        }
+        this.log(boxDivider);
+        this.log(`│ Moved to Done:    ${movedToDone.toString().padEnd(20)}│`);
+        this.log(`│ Returned to Dev:  ${movedBack.toString().padEnd(20)}│`);
+        this.log(boxDivider);
+        this.log(`│ Duration:         ${(duration / 1000).toFixed(2)}s${' '.repeat(15)}│`);
+        this.log(boxBottom);
+        // List details for non-PASS stories
+        const nonPassStories = results.filter((r) => r.finalGate !== 'PASS' || !r.success);
+        if (nonPassStories.length > 0) {
+            this.log('');
+            this.log(colors.bold('Stories Requiring Attention:'));
+            for (const result of nonPassStories) {
+                const status = result.success ? result.finalGate : 'ERROR';
+                const statusColor = status === 'CONCERNS' ? colors.warning : colors.error;
+                this.log(statusColor(`  ${status}: ${result.storyNumber} - ${path.basename(result.storyPath)}${result.error ? ` (${result.error})` : ''}`));
+            }
+        }
+        this.log('');
+    }
+    /**
+     * Extract gate status from story content or gate file
+     * This is a simple heuristic - looks for Gate: STATUS pattern in story
+     * IMPORTANT: Returns the LAST occurrence since QA reviews are appended
+     */
+    extractGateStatus(storyContent) {
+        // Look for ALL "Gate: STATUS" patterns and use the LAST one (most recent review)
+        const gateMatches = [...storyContent.matchAll(/\*?\*?Gate:\*?\*?\s*(PASS|CONCERNS|FAIL|WAIVED)/gi)];
+        if (gateMatches.length > 0) {
+            const lastMatch = gateMatches.at(-1);
+            return lastMatch[1].toUpperCase();
+        }
+        // Look for "Gate Status" section with status (also get last match)
+        const statusMatches = [...storyContent.matchAll(/###\s*Gate\s*Status[\s\S]*?(PASS|CONCERNS|FAIL|WAIVED)/gi)];
+        if (statusMatches.length > 0) {
+            const lastMatch = statusMatches.at(-1);
+            return lastMatch[1].toUpperCase();
+        }
+        return 'UNKNOWN';
+    }
+    /**
+     * Initialize service dependencies
+     */
+    initializeServices(provider = 'claude') {
+        this.logger = createLogger({ namespace: 'commands:stories:qa' });
+        this.logger.info({ provider }, 'Initializing services with AI provider');
+        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 successfully');
+    }
+    /**
+     * Match story files using glob pattern
+     */
+    async matchStoryFiles(pattern) {
+        this.logger.info({ pattern }, 'Matching story files with glob pattern');
+        // Expand glob pattern
+        const matches = await this.globMatcher.expandPattern(pattern);
+        this.logger.info({ matchCount: matches.length, pattern }, 'Glob pattern matching complete');
+        return matches;
+    }
+    /**
+     * Move story to appropriate folder based on gate status
+     */
+    async moveStoryBasedOnGate(storyPath, gateStatus) {
+        try {
+            if (gateStatus === 'PASS' || gateStatus === 'WAIVED') {
+                // Move to done/stories
+                const doneStoryDir = this.pathResolver.getDoneStoryDir();
+                const destPath = path.join(doneStoryDir, path.basename(storyPath));
+                // Ensure done directory exists
+                await this.fileManager.createDirectory(doneStoryDir);
+                await this.fileManager.moveFile(storyPath, destPath);
+                this.logger.info({ destPath, gateStatus, storyPath }, 'Moved story to done folder');
+                return 'done';
+            }
+            if (gateStatus === 'FAIL' || gateStatus === 'CONCERNS') {
+                // Move back to stories for rework
+                const storyDir = this.pathResolver.getStoryDir();
+                const destPath = path.join(storyDir, path.basename(storyPath));
+                // Only move if not already in stories dir (normalize paths for comparison)
+                if (path.resolve(path.dirname(storyPath)) !== path.resolve(storyDir)) {
+                    await this.fileManager.moveFile(storyPath, destPath);
+                    this.logger.info({ destPath, gateStatus, storyPath }, 'Moved story back to stories folder for rework');
+                    return 'stories';
+                }
+                return 'none';
+            }
+            return 'none';
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err, storyPath }, 'Failed to move story');
+            return 'none';
+        }
+    }
+    /**
+     * Process stories sequentially through QA workflow
+     */
+    async qaStoriesSequentially(storyFiles, flags) {
+        const results = [];
+        const total = storyFiles.length;
+        /* eslint-disable no-await-in-loop */
+        // Sequential loop - DO NOT use Promise.all - await in loop is REQUIRED here
+        for (let index = 0; index < storyFiles.length; index++) {
+            const storyPath = storyFiles[index];
+            const storyNum = index + 1;
+            this.log(colors.bold(`\n[${storyNum}/${total}] QA: ${path.basename(storyPath)}`));
+            // Parse story metadata
+            const spinner = createSpinner('Parsing story metadata...');
+            spinner.start();
+            let storyMetadata;
+            try {
+                storyMetadata = await this.storyParserFactory.parseStory(storyPath);
+                const storyId = storyMetadata.id;
+                spinner.succeed(colors.success(`Story ${storyId}: ${storyMetadata.title}`));
+            }
+            catch (error) {
+                const err = error;
+                spinner.fail(colors.error(`Failed to parse story: ${err.message}`));
+                results.push({
+                    error: `Parse error: ${err.message}`,
+                    finalGate: 'UNKNOWN',
+                    movedTo: 'none',
+                    retriesUsed: 0,
+                    storyNumber: 'unknown',
+                    storyPath,
+                    success: false,
+                });
+                continue; // Skip to next story
+            }
+            // Run QA workflow
+            const result = await this.qaStory(storyPath, storyMetadata, {
+                'dev-prompt': flags['dev-prompt'],
+                'max-retries': flags['max-retries'],
+                'qa-prompt': flags['qa-prompt'],
+                reference: flags.reference,
+            });
+            results.push(result);
+            // Display result
+            if (result.finalGate === 'PASS') {
+                this.log(colors.success(`  ✓ PASSED - Moved to done`));
+            }
+            else if (result.finalGate === 'WAIVED') {
+                this.log(colors.warning(`  ⚠ WAIVED - Moved to done`));
+            }
+            else if (result.success) {
+                this.log(colors.warning(`  ⚠ ${result.finalGate} - Returned for rework`));
+            }
+            else {
+                this.log(colors.error(`  ✗ Error: ${result.error}`));
+            }
+            // Display countdown timer before next story (except for last story)
+            if (index < storyFiles.length - 1) {
+                await this.displayCountdown(flags.interval);
+            }
+        }
+        /* eslint-enable no-await-in-loop */
+        return results;
+    }
+    /**
+     * Process a single story through QA workflow
+     */
+    async qaStory(storyPath, storyMetadata, flags) {
+        const storyNumber = isEpicStory(storyMetadata) ? storyMetadata.number : storyMetadata.id;
+        let retriesUsed = 0;
+        let currentGate = 'UNKNOWN';
+        this.logger.info({ storyNumber, storyPath }, 'Starting story QA workflow');
+        try {
+            // Phase 1: Initial QA Deep Dive
+            this.log(colors.info('  Phase 1: QA Deep Dive Review...'));
+            const qaPrompt = this.buildQaPrompt(storyPath, flags['qa-prompt'], flags.reference);
+            const qaResult = await this.agentRunner.runAgent(qaPrompt, {
+                agentType: 'tea',
+                timeout: AGENT_TIMEOUT_MS,
+            });
+            if (!qaResult.success) {
+                throw new Error(`QA agent failed: ${qaResult.errors}`);
+            }
+            // Read story to get gate status
+            let storyContent = await this.fileManager.readFile(storyPath);
+            currentGate = this.extractGateStatus(storyContent);
+            this.log(colors.info(`  Initial Gate: ${currentGate}`));
+            // Phase 2: Dev Fix-Forward Loop (if needed and retries allowed)
+            while ((currentGate === 'CONCERNS' || currentGate === 'FAIL') && retriesUsed < flags['max-retries']) {
+                retriesUsed++;
+                this.log(colors.warning(`  Phase 2: Dev Fix-Forward (Retry ${retriesUsed}/${flags['max-retries']})...`));
+                // Run Dev agent to fix issues (sequential retry loop by design)
+                const devPrompt = this.buildDevFixPrompt(storyPath, flags['dev-prompt'], flags.reference);
+                // eslint-disable-next-line no-await-in-loop
+                const devResult = await this.agentRunner.runAgent(devPrompt, {
+                    agentType: 'dev',
+                    timeout: AGENT_TIMEOUT_MS,
+                });
+                if (!devResult.success) {
+                    this.logger.warn({ errors: devResult.errors, retriesUsed }, 'Dev fix-forward failed, continuing...');
+                    // Continue anyway - QA will re-evaluate
+                }
+                // Phase 3: Re-run QA to validate fixes
+                this.log(colors.info(`  Phase 3: QA Re-validation (Retry ${retriesUsed})...`));
+                // eslint-disable-next-line no-await-in-loop
+                const reQaResult = await this.agentRunner.runAgent(qaPrompt, {
+                    agentType: 'tea',
+                    timeout: AGENT_TIMEOUT_MS,
+                });
+                if (!reQaResult.success) {
+                    this.logger.warn({ errors: reQaResult.errors, retriesUsed }, 'QA re-validation failed, continuing...');
+                }
+                // Re-read story to get updated gate status
+                // eslint-disable-next-line no-await-in-loop
+                storyContent = await this.fileManager.readFile(storyPath);
+                currentGate = this.extractGateStatus(storyContent);
+                this.log(colors.info(`  Gate after retry ${retriesUsed}: ${currentGate}`));
+            }
+            // Append QA workflow summary to story
+            const result = {
+                finalGate: currentGate,
+                movedTo: 'none',
+                retriesUsed,
+                storyNumber,
+                storyPath,
+                success: true,
+            };
+            await this.appendQaSummaryToStory(storyPath, result, flags['max-retries']);
+            // Move story based on final gate status
+            result.movedTo = await this.moveStoryBasedOnGate(storyPath, currentGate);
+            this.logger.info({
+                finalGate: currentGate,
+                movedTo: result.movedTo,
+                retriesUsed,
+                storyNumber,
+            }, 'Story QA workflow completed');
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err, storyNumber, storyPath }, 'Story QA workflow failed');
+            return {
+                error: err.message,
+                finalGate: currentGate,
+                movedTo: 'none',
+                retriesUsed,
+                storyNumber,
+                storyPath,
+                success: false,
+            };
+        }
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    async sleep(ms) {
+        // eslint-disable-next-line no-promise-executor-return -- Simple setTimeout wrapper
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}