@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/review/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Review Types
+ *
+ * Core type definitions for the automated code review system.
+ * Scanners return raw output; classification into severity levels
+ * is handled separately by SeverityClassifier (Story 1.2).
+ *
+ * Severity model maps to BMAD governance:
+ *   CRITICAL = NON-NEGOTIABLE (blocks pipeline)
+ *   HIGH     = MUST (blocks pipeline)
+ *   MEDIUM   = SHOULD (documented as tech debt)
+ *   LOW      = MAY (noted only)
+ */
+/**
+ * Issue severity levels aligned with BMAD governance tiers
+ */
+export declare enum Severity {
+    CRITICAL = "CRITICAL",
+    HIGH = "HIGH",
+    LOW = "LOW",
+    MEDIUM = "MEDIUM"
+}
+/**
+ * Review verdict — PASS allows pipeline to continue, FAIL blocks it
+ */
+export type ReviewVerdict = 'FAIL' | 'PASS';
+/**
+ * Context provided to scanners describing what to review
+ */
+export interface ReviewContext {
+    /** Base branch to diff against (e.g., "main", "develop") */
+    baseBranch: string;
+    /** List of changed file paths (relative to projectRoot) */
+    changedFiles: string[];
+    /** Absolute path to the project root directory */
+    projectRoot: string;
+    /** List of reference file paths for context (e.g., architecture docs) */
+    referenceFiles: string[];
+    /** Absolute path to the story markdown file */
+    storyFile: string;
+    /** Story identifier (e.g., "PROJ-story-1.001") */
+    storyId: string;
+}
+/**
+ * Raw output from a scanner before classification
+ */
+export interface RawReviewOutput {
+    /** Raw scanner output (lint text, AI response, etc.) */
+    raw: string;
+    /** Identifier of the scanner that produced this output (e.g., "eslint", "claude-ai", "coderabbit") */
+    source: string;
+}
+/**
+ * A single classified issue with severity and location
+ */
+export interface ClassifiedIssue {
+    /** File path where the issue was found */
+    file: string;
+    /** Suggested fix (optional) */
+    fix?: string;
+    /** Description of the issue */
+    issue: string;
+    /** Line number where the issue occurs */
+    line: number;
+    /** Severity level of the issue */
+    severity: Severity;
+}
+/**
+ * Final review result after classification and optional self-heal iterations
+ */
+export interface ReviewResult {
+    /** All classified issues found during review */
+    issues: ClassifiedIssue[];
+    /** Number of self-heal iterations performed (0 if no retries) */
+    iterations: number;
+    /** Optional summary message */
+    message?: string;
+    /** Overall verdict — PASS or FAIL */
+    verdict: ReviewVerdict;
+}
+/**
+ * Scanner interface — all scanner implementations (lint, AI, CodeRabbit) must implement this.
+ * Mirrors the AIProviderRunner pattern: single async method with typed input/output.
+ */
+export interface ReviewScanner {
+    /**
+     * Scan the given context and produce raw review output
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from the scanner
+     */
+    scan(context: ReviewContext): Promise<RawReviewOutput>;
+}

package/dist/services/review/types.js

@@ -0,0 +1,23 @@
+/**
+ * Review Types
+ *
+ * Core type definitions for the automated code review system.
+ * Scanners return raw output; classification into severity levels
+ * is handled separately by SeverityClassifier (Story 1.2).
+ *
+ * Severity model maps to BMAD governance:
+ *   CRITICAL = NON-NEGOTIABLE (blocks pipeline)
+ *   HIGH     = MUST (blocks pipeline)
+ *   MEDIUM   = SHOULD (documented as tech debt)
+ *   LOW      = MAY (noted only)
+ */
+/**
+ * Issue severity levels aligned with BMAD governance tiers
+ */
+export var Severity;
+(function (Severity) {
+    Severity["CRITICAL"] = "CRITICAL";
+    Severity["HIGH"] = "HIGH";
+    Severity["LOW"] = "LOW";
+    Severity["MEDIUM"] = "MEDIUM";
+})(Severity || (Severity = {}));

package/dist/services/scaffolding/workflow-session-scaffolder.d.ts

@@ -0,0 +1,182 @@
+/**
+ * WorkflowSessionScaffolder
+ *
+ * Creates structured session directories with spawn output files and summary reports.
+ * Provides persistent, browsable artifacts for troubleshooting and audit trails
+ * after each workflow run.
+ */
+import type pino from 'pino';
+import type { FileManager } from '../file-system/file-manager.js';
+import type { WorkflowLogFile } from '../logging/workflow-logger.js';
+/**
+ * Configuration for creating a workflow session
+ */
+export interface WorkflowSessionConfig {
+    /** Base directory for workflow sessions (e.g., 'docs/workflow-sessions') */
+    baseDir: string;
+    /** Session prefix (e.g., 'workflow', 'bmad-run') */
+    prefix: string;
+}
+/**
+ * Spawn output payload structure
+ */
+export interface SpawnOutputPayload {
+    /** Timestamp when spawn completed */
+    completedAt?: string;
+    /** Spawn output content */
+    content: string;
+    /** Spawn execution duration in milliseconds */
+    duration?: number;
+    /** Any errors from the spawn */
+    errors?: string;
+    /** Unique spawn identifier */
+    spawnId: string;
+    /** Whether the spawn succeeded */
+    success?: boolean;
+    /** Type of spawn: epic, story, or dev */
+    type: 'dev' | 'epic' | 'story';
+}
+/**
+ * Session report summary structure
+ */
+export interface SessionReportSummary {
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Session end timestamp */
+    endedAt: string;
+    /** List of errors encountered */
+    errors: Array<{
+        error: string;
+        identifier: string;
+        phase: string;
+        timestamp: string;
+    }>;
+    /** Overall success status */
+    overallSuccess: boolean;
+    /** Phase execution counts */
+    phases: {
+        developments: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+        epics: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+        stories: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+    };
+    /** Session identifier */
+    sessionId: string;
+    /** List of spawn files written */
+    spawnFiles: string[];
+    /** Session start timestamp */
+    startedAt: string;
+}
+/**
+ * Scaffolder for workflow session directory structure
+ */
+export declare class WorkflowSessionScaffolder {
+    private readonly fileManager;
+    private readonly logger;
+    private sessionDir;
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory at `{baseDir}/{prefix}-{timestamp}/`
+     * - `spawns/` subdirectory for individual spawn output files
+     *
+     * @param config - Session configuration
+     * @returns Session directory path
+     */
+    createSessionStructure(config: WorkflowSessionConfig): Promise<string>;
+    /**
+     * Get the current session directory path
+     *
+     * @returns Session directory path or null if not created
+     */
+    getSessionDir(): null | string;
+    /**
+     * Write session report markdown file
+     *
+     * Generates SESSION_REPORT.md with execution summary, pass/fail counts,
+     * durations, and error listings.
+     *
+     * @param summary - Session execution summary
+     */
+    writeSessionReport(summary: SessionReportSummary): Promise<void>;
+    /**
+     * Write individual spawn output file
+     *
+     * Writes immediately (no buffering) to ensure partial results survive crashes.
+     *
+     * @param spawnId - Unique spawn identifier
+     * @param type - Type of spawn (epic, story, dev)
+     * @param content - Spawn output content
+     */
+    writeSpawnOutput(spawnId: string, type: 'dev' | 'epic' | 'story', content: string): Promise<void>;
+    /**
+     * Write individual spawn output file with full payload
+     *
+     * Writes immediately (no buffering) to ensure partial results survive crashes.
+     *
+     * @param payload - Full spawn output payload
+     */
+    writeSpawnOutput(payload: SpawnOutputPayload): Promise<void>;
+    /**
+     * Write workflow log YAML file
+     *
+     * Generates workflow-log.yaml machine-parseable audit trail file.
+     *
+     * @param logData - Full workflow log data (WorkflowLogFile interface)
+     */
+    writeWorkflowLog(logData: WorkflowLogFile): Promise<void>;
+    /**
+     * Build markdown content for session report
+     *
+     * @param summary - Session report summary
+     * @returns Formatted markdown content
+     * @private
+     */
+    private buildSessionReportMarkdown;
+    /**
+     * Build markdown content for spawn output file
+     *
+     * @param payload - Spawn output payload
+     * @returns Formatted markdown content
+     * @private
+     */
+    private buildSpawnMarkdown;
+    /**
+     * Capitalize first letter of a string
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     * @private
+     */
+    private capitalizeFirst;
+    /**
+     * Format duration in human-readable format
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Formatted duration string
+     * @private
+     */
+    private formatDuration;
+    /**
+     * Generate timestamp string for session directory name
+     *
+     * Format: YYYYMMDD-HHmmss
+     *
+     * @returns Formatted timestamp
+     * @private
+     */
+    private generateTimestamp;
+}

package/dist/services/scaffolding/workflow-session-scaffolder.js

@@ -0,0 +1,236 @@
+/**
+ * WorkflowSessionScaffolder
+ *
+ * Creates structured session directories with spawn output files and summary reports.
+ * Provides persistent, browsable artifacts for troubleshooting and audit trails
+ * after each workflow run.
+ */
+import * as yaml from 'js-yaml';
+import { join } from 'node:path';
+/**
+ * Scaffolder for workflow session directory structure
+ */
+export class WorkflowSessionScaffolder {
+    fileManager;
+    logger;
+    sessionDir = null;
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory at `{baseDir}/{prefix}-{timestamp}/`
+     * - `spawns/` subdirectory for individual spawn output files
+     *
+     * @param config - Session configuration
+     * @returns Session directory path
+     */
+    async createSessionStructure(config) {
+        const timestamp = this.generateTimestamp();
+        const sessionDirName = `${config.prefix}-${timestamp}`;
+        const sessionDir = join(config.baseDir, sessionDirName);
+        this.logger.info({ prefix: config.prefix, sessionDir }, 'Creating workflow session structure');
+        // Create root session directory
+        await this.fileManager.createDirectory(sessionDir);
+        // Create spawns subdirectory
+        await this.fileManager.createDirectory(join(sessionDir, 'spawns'));
+        this.sessionDir = sessionDir;
+        this.logger.info({ sessionDir }, 'Workflow session structure created');
+        return sessionDir;
+    }
+    /**
+     * Get the current session directory path
+     *
+     * @returns Session directory path or null if not created
+     */
+    getSessionDir() {
+        return this.sessionDir;
+    }
+    /**
+     * Write session report markdown file
+     *
+     * Generates SESSION_REPORT.md with execution summary, pass/fail counts,
+     * durations, and error listings.
+     *
+     * @param summary - Session execution summary
+     */
+    async writeSessionReport(summary) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing session report');
+        }
+        const reportPath = join(this.sessionDir, 'SESSION_REPORT.md');
+        this.logger.info({ reportPath, sessionId: summary.sessionId }, 'Writing session report');
+        const markdownContent = this.buildSessionReportMarkdown(summary);
+        await this.fileManager.writeFile(reportPath, markdownContent);
+        this.logger.info({ reportPath }, 'Session report written');
+    }
+    async writeSpawnOutput(spawnIdOrPayload, type, content) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing spawn output');
+        }
+        // Normalize to payload
+        const payload = typeof spawnIdOrPayload === 'string'
+            ? {
+                content: content,
+                spawnId: spawnIdOrPayload,
+                type: type,
+            }
+            : spawnIdOrPayload;
+        const fileName = `${payload.type}-${payload.spawnId}.md`;
+        const filePath = join(this.sessionDir, 'spawns', fileName);
+        this.logger.info({ filePath, spawnId: payload.spawnId, type: payload.type }, 'Writing spawn output');
+        // Build markdown content with metadata header
+        const markdownContent = this.buildSpawnMarkdown(payload);
+        // Immediate write for crash resilience
+        await this.fileManager.writeFile(filePath, markdownContent);
+        this.logger.info({ filePath, spawnId: payload.spawnId }, 'Spawn output written');
+    }
+    /**
+     * Write workflow log YAML file
+     *
+     * Generates workflow-log.yaml machine-parseable audit trail file.
+     *
+     * @param logData - Full workflow log data (WorkflowLogFile interface)
+     */
+    async writeWorkflowLog(logData) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing workflow log');
+        }
+        const logPath = join(this.sessionDir, 'workflow-log.yaml');
+        this.logger.info({ logPath, workflowId: logData.metadata.workflowId }, 'Writing workflow log');
+        const yamlContent = yaml.dump(logData, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+        });
+        await this.fileManager.writeFile(logPath, yamlContent);
+        this.logger.info({ logPath }, 'Workflow log written');
+    }
+    /**
+     * Build markdown content for session report
+     *
+     * @param summary - Session report summary
+     * @returns Formatted markdown content
+     * @private
+     */
+    buildSessionReportMarkdown(summary) {
+        const statusIcon = summary.overallSuccess ? '✅' : '❌';
+        const durationStr = this.formatDuration(summary.duration);
+        let md = `# Workflow Session Report\n\n`;
+        // Metadata section
+        md += `## Metadata\n\n`;
+        md += `- **Session ID:** ${summary.sessionId}\n`;
+        md += `- **Status:** ${statusIcon} ${summary.overallSuccess ? 'Completed Successfully' : 'Completed with Failures'}\n`;
+        md += `- **Started:** ${summary.startedAt}\n`;
+        md += `- **Ended:** ${summary.endedAt}\n`;
+        md += `- **Duration:** ${durationStr}\n\n`;
+        // Execution summary table
+        md += `## Execution Summary\n\n`;
+        md += `| Phase | Total | Completed | Failed | Pass Rate |\n`;
+        md += `|-------|-------|-----------|--------|------------|\n`;
+        for (const [phase, counts] of Object.entries(summary.phases)) {
+            const passRate = counts.total > 0 ? ((counts.completed / counts.total) * 100).toFixed(1) : '0.0';
+            md += `| ${this.capitalizeFirst(phase)} | ${counts.total} | ${counts.completed} | ${counts.failed} | ${passRate}% |\n`;
+        }
+        md += `\n`;
+        // Error listings (if any)
+        if (summary.errors.length > 0) {
+            md += `## Errors (${summary.errors.length})\n\n`;
+            for (const error of summary.errors) {
+                md += `### ${error.phase.toUpperCase()} - ${error.identifier}\n\n`;
+                md += `- **Timestamp:** ${error.timestamp}\n`;
+                md += `- **Error:** ${error.error}\n\n`;
+            }
+        }
+        // Spawn file inventory
+        md += `## Spawn Files\n\n`;
+        if (summary.spawnFiles.length > 0) {
+            for (const file of summary.spawnFiles) {
+                md += `- \`${file}\`\n`;
+            }
+        }
+        else {
+            md += `_No spawn files generated_\n`;
+        }
+        md += `\n---\n\n`;
+        md += `<!-- Powered by BMAD™ Core -->\n`;
+        return md;
+    }
+    /**
+     * Build markdown content for spawn output file
+     *
+     * @param payload - Spawn output payload
+     * @returns Formatted markdown content
+     * @private
+     */
+    buildSpawnMarkdown(payload) {
+        const statusIcon = payload.success === false ? '❌' : payload.success === true ? '✅' : '⏳';
+        const durationStr = payload.duration ? this.formatDuration(payload.duration) : 'N/A';
+        let md = `# ${payload.type.toUpperCase()} Spawn: ${payload.spawnId}\n\n`;
+        md += `## Metadata\n\n`;
+        md += `- **Spawn ID:** ${payload.spawnId}\n`;
+        md += `- **Type:** ${payload.type}\n`;
+        md += `- **Status:** ${statusIcon} ${payload.success === false ? 'Failed' : payload.success === true ? 'Success' : 'Unknown'}\n`;
+        md += `- **Duration:** ${durationStr}\n`;
+        if (payload.completedAt) {
+            md += `- **Completed At:** ${payload.completedAt}\n`;
+        }
+        md += `\n`;
+        if (payload.errors) {
+            md += `## Errors\n\n`;
+            md += `\`\`\`\n${payload.errors}\n\`\`\`\n\n`;
+        }
+        md += `## Output\n\n`;
+        md += `${payload.content}\n\n`;
+        md += `---\n\n`;
+        md += `<!-- Powered by BMAD™ Core -->\n`;
+        return md;
+    }
+    /**
+     * Capitalize first letter of a string
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     * @private
+     */
+    capitalizeFirst(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+    /**
+     * Format duration in human-readable format
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Formatted duration string
+     * @private
+     */
+    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`;
+    }
+    /**
+     * Generate timestamp string for session directory name
+     *
+     * Format: YYYYMMDD-HHmmss
+     *
+     * @returns Formatted timestamp
+     * @private
+     */
+    generateTimestamp() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const day = String(now.getDate()).padStart(2, '0');
+        const hours = String(now.getHours()).padStart(2, '0');
+        const minutes = String(now.getMinutes()).padStart(2, '0');
+        const seconds = String(now.getSeconds()).padStart(2, '0');
+        return `${year}${month}${day}-${hours}${minutes}${seconds}`;
+    }
+}

package/dist/services/validation/config-validator.d.ts

@@ -8,6 +8,53 @@
 import type pino from 'pino';
 import { z } from 'zod';
 import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * Zod schema for review configuration section
+ *
+ * Defines scanners, severity thresholds, self-heal limits, and path rules
+ * for automated code review in the BMAD workflow pipeline.
+ */
+export declare const reviewConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    pathRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        focus: z.ZodString;
+        pattern: z.ZodString;
+    }, z.core.$strip>>>;
+    scanners: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        ai: "ai";
+        coderabbit: "coderabbit";
+        lint: "lint";
+    }>>>;
+    selfHeal: z.ZodDefault<z.ZodObject<{
+        fixAgent: z.ZodDefault<z.ZodString>;
+        fixTimeout: z.ZodDefault<z.ZodNumber>;
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    severity: z.ZodDefault<z.ZodObject<{
+        blockOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+        documentOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+        ignoreOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            CRITICAL: "CRITICAL";
+            HIGH: "HIGH";
+            LOW: "LOW";
+            MEDIUM: "MEDIUM";
+        }>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Inferred TypeScript type from review config Zod schema
+ */
+export type ReviewConfig = z.infer<typeof reviewConfigSchema>;
 /**
  * Zod schema for core configuration
  *
@@ -22,6 +69,43 @@ declare const configSchema: z.ZodObject<{
     qa: z.ZodOptional<z.ZodObject<{
         qaLocation: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    review: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        pathRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            focus: z.ZodString;
+            pattern: z.ZodString;
+        }, z.core.$strip>>>;
+        scanners: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            ai: "ai";
+            coderabbit: "coderabbit";
+            lint: "lint";
+        }>>>;
+        selfHeal: z.ZodDefault<z.ZodObject<{
+            fixAgent: z.ZodDefault<z.ZodString>;
+            fixTimeout: z.ZodDefault<z.ZodNumber>;
+            maxIterations: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        severity: z.ZodDefault<z.ZodObject<{
+            blockOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+            documentOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+            ignoreOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                CRITICAL: "CRITICAL";
+                HIGH: "HIGH";
+                LOW: "LOW";
+                MEDIUM: "MEDIUM";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * Inferred TypeScript type from Zod schema