@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/review/ai-review-scanner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AI Review Scanner
+ *
+ * Spawns a QA agent to perform structured code review on story implementations.
+ * Produces RawReviewOutput with source 'ai' for downstream SeverityClassifier parsing.
+ *
+ * Prompt enforces strict output format: SEVERITY/FILE/LINE/ISSUE/FIX blocks
+ * separated by `---`, or `REVIEW_PASS: No issues found` sentinel for clean reviews.
+ */
+import type pino from 'pino';
+import type { AIProviderRunner } from '../agents/agent-runner.js';
+import type { RawReviewOutput, ReviewContext, ReviewScanner } from './types.js';
+/** Path-specific review rule loaded from core-config.yaml */
+export interface PathRule {
+    /** Review focus areas for files matching this pattern */
+    focus: string[];
+    /** Glob pattern to match against changed files */
+    pattern: string;
+}
+/** Review configuration — subset of core-config relevant to AI review */
+export interface ReviewConfig {
+    /** Set to false to disable AI review scanner */
+    aiReview?: boolean;
+    /** Set to true to enable CodeRabbit scanner (requires CLI installed) */
+    coderabbit?: boolean;
+    /** Path-specific review rules */
+    pathRules?: PathRule[];
+}
+/**
+ * AIReviewScanner — spawns a QA agent and parses structured review output.
+ *
+ * Implements ReviewScanner interface. Uses composition over inheritance —
+ * composes AIProviderRunner, doesn't extend it.
+ */
+export declare class AIReviewScanner implements ReviewScanner {
+    private readonly agentRunner;
+    private readonly config;
+    private readonly logger;
+    private readonly timeout;
+    constructor(agentRunner: AIProviderRunner, config: ReviewConfig, logger: pino.Logger, timeout?: number);
+    /**
+     * Scan the given context by spawning a QA agent for AI-powered code review
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from the AI agent with source 'ai'
+     */
+    scan(context: ReviewContext): Promise<RawReviewOutput>;
+    /**
+     * Build the review prompt with severity definitions, output format spec,
+     * changed files, and path-specific rules.
+     */
+    private buildReviewPrompt;
+    /**
+     * Get path rules that match any of the changed files
+     */
+    private getMatchingPathRules;
+    /**
+     * Parse agent output into RawReviewOutput
+     *
+     * Handles three cases:
+     * 1. REVIEW_PASS sentinel → clean result
+     * 2. Structured output → pass raw text for SeverityClassifier
+     * 3. Malformed/empty output → graceful fallback
+     */
+    private parseAgentOutput;
+}

package/dist/services/review/ai-review-scanner.js

@@ -0,0 +1,142 @@
+/**
+ * AI Review Scanner
+ *
+ * Spawns a QA agent to perform structured code review on story implementations.
+ * Produces RawReviewOutput with source 'ai' for downstream SeverityClassifier parsing.
+ *
+ * Prompt enforces strict output format: SEVERITY/FILE/LINE/ISSUE/FIX blocks
+ * separated by `---`, or `REVIEW_PASS: No issues found` sentinel for clean reviews.
+ */
+/** Default AI review timeout: 5 minutes (NFR1) */
+const DEFAULT_AI_REVIEW_TIMEOUT = 300_000;
+/**
+ * Simple glob matcher for path rules.
+ * Supports `**` (any path segments) and `*` (single segment wildcard).
+ */
+function matchGlob(file, pattern) {
+    // Escape regex special chars, then convert glob wildcards
+    const regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex chars (not * and ?)
+        .replace(/\*\*/g, '{{GLOBSTAR}}') // placeholder for **
+        .replace(/\*/g, '[^/]*') // * matches within a segment
+        .replace(/\?/g, '[^/]') // ? matches single char
+        .replace(/\{\{GLOBSTAR\}\}/g, '.*'); // ** matches across segments
+    return new RegExp(`^${regexStr}$`).test(file);
+}
+/**
+ * AIReviewScanner — spawns a QA agent and parses structured review output.
+ *
+ * Implements ReviewScanner interface. Uses composition over inheritance —
+ * composes AIProviderRunner, doesn't extend it.
+ */
+export class AIReviewScanner {
+    agentRunner;
+    config;
+    logger;
+    timeout;
+    constructor(agentRunner, config, logger, timeout) {
+        this.agentRunner = agentRunner;
+        this.config = config;
+        this.logger = logger;
+        this.timeout = timeout ?? DEFAULT_AI_REVIEW_TIMEOUT;
+    }
+    /**
+     * Scan the given context by spawning a QA agent for AI-powered code review
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from the AI agent with source 'ai'
+     */
+    async scan(context) {
+        this.logger.info({ changedFiles: context.changedFiles, storyId: context.storyId }, 'Starting AI review scan');
+        const prompt = this.buildReviewPrompt(context);
+        const references = [context.storyFile, ...context.changedFiles, ...context.referenceFiles];
+        try {
+            const result = await this.agentRunner.runAgent(prompt, {
+                agentType: 'qa',
+                references,
+                timeout: this.timeout,
+            });
+            this.logger.info({ duration: result.duration, exitCode: result.exitCode, storyId: context.storyId, success: result.success }, 'AI review scan completed');
+            return this.parseAgentOutput(result);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err.message, storyId: context.storyId }, 'AI review scan failed');
+            return {
+                raw: `AI_REVIEW_ERROR: ${err.message}`,
+                source: 'ai',
+            };
+        }
+    }
+    /**
+     * Build the review prompt with severity definitions, output format spec,
+     * changed files, and path-specific rules.
+     */
+    buildReviewPrompt(context) {
+        const sections = [];
+        // Preamble
+        sections.push('You are a senior code reviewer performing a structured quality review.', 'Review the following changed files for the given story and report any issues found.', '');
+        // Severity definitions (Architecture Section 5.1)
+        sections.push('## Severity Definitions', '', 'CRITICAL — Security vulnerabilities, data loss risks, authentication/authorization bypasses, injection flaws. Maps to NON-NEGOTIABLE governance tier.', 'HIGH — Logic errors, missing error handling, broken functionality, race conditions, missing input validation. Maps to MUST governance tier.', 'MEDIUM — Code style violations, missing tests, poor naming, missing documentation, unnecessary complexity. Maps to SHOULD governance tier (tech debt).', 'LOW — Minor suggestions, optional improvements, cosmetic issues, nitpicks. Maps to MAY governance tier (noted only).', '');
+        // Output format spec
+        sections.push('## Output Format', '', 'For each issue found, output a block with these fields:', '', 'SEVERITY: <CRITICAL|HIGH|MEDIUM|LOW>', 'FILE: <relative file path>', 'LINE: <line number>', 'ISSUE: <description of the issue>', 'FIX: <suggested fix>', '', 'Separate multiple issue blocks with a line containing only `---`.', '', 'If no issues are found, output exactly:', 'REVIEW_PASS: No issues found', '', 'Do NOT include any other text, explanations, or markdown formatting outside of these blocks.', '');
+        // Changed files
+        sections.push('## Changed Files', '');
+        for (const file of context.changedFiles) {
+            sections.push(`- ${file}`);
+        }
+        sections.push('');
+        // Story context
+        sections.push(`## Story`, '', `Story file: ${context.storyFile}`, `Story ID: ${context.storyId}`, '');
+        // Path-specific rules
+        const matchingRules = this.getMatchingPathRules(context.changedFiles);
+        if (matchingRules.length > 0) {
+            sections.push('## Path-Specific Review Focus', '');
+            for (const rule of matchingRules) {
+                sections.push(`Files matching \`${rule.pattern}\`:`);
+                for (const focus of rule.focus) {
+                    sections.push(`  - ${focus}`);
+                }
+                sections.push('');
+            }
+        }
+        return sections.join('\n');
+    }
+    /**
+     * Get path rules that match any of the changed files
+     */
+    getMatchingPathRules(changedFiles) {
+        const pathRules = this.config.pathRules ?? [];
+        if (pathRules.length === 0 || changedFiles.length === 0) {
+            return [];
+        }
+        return pathRules.filter((rule) => changedFiles.some((file) => matchGlob(file, rule.pattern)));
+    }
+    /**
+     * Parse agent output into RawReviewOutput
+     *
+     * Handles three cases:
+     * 1. REVIEW_PASS sentinel → clean result
+     * 2. Structured output → pass raw text for SeverityClassifier
+     * 3. Malformed/empty output → graceful fallback
+     */
+    parseAgentOutput(result) {
+        const output = result.output.trim();
+        // Empty or failed output
+        if (!output || !result.success) {
+            const raw = output || result.errors || 'AI_REVIEW_ERROR: No output from agent';
+            this.logger.warn({ exitCode: result.exitCode, hasOutput: !!output }, 'AI review produced no usable output');
+            return { raw, source: 'ai' };
+        }
+        // REVIEW_PASS sentinel
+        if (output.includes('REVIEW_PASS:')) {
+            this.logger.info('AI review passed with no issues found');
+            return {
+                raw: 'REVIEW_PASS: No issues found',
+                source: 'ai',
+            };
+        }
+        // Structured output — pass through for SeverityClassifier
+        return { raw: output, source: 'ai' };
+    }
+}

package/dist/services/review/coderabbit-scanner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CodeRabbit Scanner (Stub)
+ *
+ * Placeholder for future CodeRabbit integration (Epic 2/3).
+ * Implements ReviewScanner interface to allow scanner-factory to
+ * compile and dynamically import this module.
+ */
+import type pino from 'pino';
+import type { RawReviewOutput, ReviewContext, ReviewScanner } from './types.js';
+/**
+ * CodeRabbitScanner — runs CodeRabbit CLI for AI-powered code review.
+ *
+ * Stub implementation — will be fully implemented in a future story.
+ */
+export declare class CodeRabbitScanner implements ReviewScanner {
+    private readonly logger;
+    constructor(logger: pino.Logger);
+    /**
+     * Scan the given context using CodeRabbit CLI
+     *
+     * @param _context - Review context describing what to scan
+     * @returns Raw output from CodeRabbit
+     */
+    scan(_context: ReviewContext): Promise<RawReviewOutput>;
+}

package/dist/services/review/coderabbit-scanner.js

@@ -0,0 +1,31 @@
+/**
+ * CodeRabbit Scanner (Stub)
+ *
+ * Placeholder for future CodeRabbit integration (Epic 2/3).
+ * Implements ReviewScanner interface to allow scanner-factory to
+ * compile and dynamically import this module.
+ */
+/**
+ * CodeRabbitScanner — runs CodeRabbit CLI for AI-powered code review.
+ *
+ * Stub implementation — will be fully implemented in a future story.
+ */
+export class CodeRabbitScanner {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Scan the given context using CodeRabbit CLI
+     *
+     * @param _context - Review context describing what to scan
+     * @returns Raw output from CodeRabbit
+     */
+    async scan(_context) {
+        this.logger.warn('CodeRabbitScanner is a stub — not yet implemented');
+        return {
+            raw: 'CODERABBIT_NOT_IMPLEMENTED: This scanner is a placeholder for future implementation',
+            source: 'coderabbit',
+        };
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Review Services
+ *
+ * Type definitions, interfaces, and classification for the automated code review system.
+ */
+export { AIReviewScanner } from './ai-review-scanner.js';
+export type { PathRule, ReviewConfig } from './ai-review-scanner.js';
+export { CodeRabbitScanner } from './coderabbit-scanner.js';
+export { LintScanner } from './lint-scanner.js';
+export { DefaultReviewPhaseExecutor } from './review-phase-executor.js';
+export type { ReviewPhaseExecutor } from './review-phase-executor.js';
+export { ReviewQueue } from './review-queue.js';
+export { createScanners } from './scanner-factory.js';
+export type { ScannerTimeouts } from './scanner-factory.js';
+export { SelfHealLoop } from './self-heal-loop.js';
+export type { ClassifyFn, SelfHealConfig } from './self-heal-loop.js';
+export { classify } from './severity-classifier.js';
+export { TechDebtTracker } from './tech-debt-tracker.js';
+export { Severity } from './types.js';
+export type { ClassifiedIssue, RawReviewOutput, ReviewContext, ReviewResult, ReviewScanner, ReviewVerdict, } from './types.js';

package/dist/services/review/index.js

@@ -0,0 +1,15 @@
+/**
+ * Review Services
+ *
+ * Type definitions, interfaces, and classification for the automated code review system.
+ */
+export { AIReviewScanner } from './ai-review-scanner.js';
+export { CodeRabbitScanner } from './coderabbit-scanner.js';
+export { LintScanner } from './lint-scanner.js';
+export { DefaultReviewPhaseExecutor } from './review-phase-executor.js';
+export { ReviewQueue } from './review-queue.js';
+export { createScanners } from './scanner-factory.js';
+export { SelfHealLoop } from './self-heal-loop.js';
+export { classify } from './severity-classifier.js';
+export { TechDebtTracker } from './tech-debt-tracker.js';
+export { Severity } from './types.js';

package/dist/services/review/lint-scanner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * LintScanner Service
+ *
+ * Runs ESLint and tsc on changed files and returns structured raw output.
+ * Always available in every review pass — provides deterministic, tool-based
+ * code quality findings regardless of AI scanner availability.
+ *
+ * Returns RawReviewOutput; classification into ClassifiedIssue[] happens
+ * separately in SeverityClassifier (Story 1.2).
+ */
+import type pino from 'pino';
+import type { RawReviewOutput, ReviewContext, ReviewScanner } from './types.js';
+/**
+ * LintScanner — runs ESLint and tsc and returns raw output.
+ *
+ * Implements ReviewScanner interface. Both tools run in parallel via
+ * Promise.all so wall-clock time is max(eslint, tsc), not the sum.
+ */
+export declare class LintScanner implements ReviewScanner {
+    private readonly execOptions;
+    private readonly logger;
+    constructor(logger: pino.Logger, timeout?: number);
+    /**
+     * Scan the given context with ESLint and tsc
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from lint tools
+     */
+    scan(context: ReviewContext): Promise<RawReviewOutput>;
+    /**
+     * Run ESLint with --format json on the changed files
+     *
+     * @returns ESLint JSON output string, or null if skipped/timed out
+     */
+    private runEslint;
+    /**
+     * Run tsc with --noEmit --pretty false on the project
+     *
+     * @returns tsc error output string, or null if skipped/timed out
+     */
+    private runTsc;
+    /**
+     * Check if any of the candidate files exist in the given directory
+     */
+    private hasAnyFile;
+}

package/dist/services/review/lint-scanner.js

@@ -0,0 +1,172 @@
+/**
+ * LintScanner Service
+ *
+ * Runs ESLint and tsc on changed files and returns structured raw output.
+ * Always available in every review pass — provides deterministic, tool-based
+ * code quality findings regardless of AI scanner availability.
+ *
+ * Returns RawReviewOutput; classification into ClassifiedIssue[] happens
+ * separately in SeverityClassifier (Story 1.2).
+ */
+import { exec } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/** ESLint config file candidates (v8 legacy + v9 flat config) */
+const ESLINT_CONFIG_FILES = [
+    '.eslintrc',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.json',
+    '.eslintrc.yml',
+    '.eslintrc.yaml',
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+];
+/** Default lint timeout: 30 seconds (NFR2) */
+const DEFAULT_LINT_TIMEOUT = 30_000;
+/**
+ * LintScanner — runs ESLint and tsc and returns raw output.
+ *
+ * Implements ReviewScanner interface. Both tools run in parallel via
+ * Promise.all so wall-clock time is max(eslint, tsc), not the sum.
+ */
+export class LintScanner {
+    execOptions;
+    logger;
+    constructor(logger, timeout) {
+        this.logger = logger;
+        this.execOptions = {
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+            timeout: timeout ?? DEFAULT_LINT_TIMEOUT,
+        };
+    }
+    /**
+     * Scan the given context with ESLint and tsc
+     *
+     * @param context - Review context describing what to scan
+     * @returns Raw output from lint tools
+     */
+    async scan(context) {
+        const { changedFiles, projectRoot } = context;
+        const [eslintOutput, tscOutput] = await Promise.all([
+            this.runEslint(changedFiles, projectRoot),
+            this.runTsc(projectRoot),
+        ]);
+        // Both tools unavailable
+        if (eslintOutput === null && tscOutput === null) {
+            return {
+                raw: 'NO_LINT_TOOLS_AVAILABLE: Neither ESLint nor tsc are configured in this project',
+                source: 'lint',
+            };
+        }
+        // Only ESLint
+        if (eslintOutput !== null && tscOutput === null) {
+            return { raw: eslintOutput, source: 'lint-eslint' };
+        }
+        // Only tsc
+        if (eslintOutput === null && tscOutput !== null) {
+            return { raw: tscOutput, source: 'lint-tsc' };
+        }
+        // Both
+        return { raw: eslintOutput + '\n' + tscOutput, source: 'lint' };
+    }
+    /**
+     * Run ESLint with --format json on the changed files
+     *
+     * @returns ESLint JSON output string, or null if skipped/timed out
+     */
+    async runEslint(changedFiles, projectRoot) {
+        if (changedFiles.length === 0) {
+            this.logger.info('ESLint: no changed files to lint, skipping');
+            return null;
+        }
+        // Check for any ESLint config file
+        const hasConfig = await this.hasAnyFile(projectRoot, ESLINT_CONFIG_FILES);
+        if (!hasConfig) {
+            this.logger.info('ESLint: no configuration file found in project root, skipping');
+            return null;
+        }
+        const fileArgs = changedFiles.join(' ');
+        const command = `npx eslint --format json ${fileArgs}`;
+        try {
+            const { stdout } = await execAsync(command, {
+                ...this.execOptions,
+                cwd: projectRoot,
+                shell: process.env.SHELL || '/bin/bash',
+            });
+            return stdout;
+        }
+        catch (error) {
+            const execError = error;
+            // Timeout
+            if (execError.killed === true && execError.signal === 'SIGTERM') {
+                this.logger.warn({ timeout: this.execOptions.timeout }, 'ESLint: timed out, skipping');
+                return null;
+            }
+            // ESLint exits 1 when lint errors are found — stdout still has valid JSON
+            if (execError.stdout) {
+                return execError.stdout;
+            }
+            this.logger.warn({ error: error.message }, 'ESLint: execution failed');
+            return null;
+        }
+    }
+    /**
+     * Run tsc with --noEmit --pretty false on the project
+     *
+     * @returns tsc error output string, or null if skipped/timed out
+     */
+    async runTsc(projectRoot) {
+        const tsconfigPath = join(projectRoot, 'tsconfig.json');
+        try {
+            await access(tsconfigPath);
+        }
+        catch {
+            this.logger.info('tsc: no tsconfig.json found in project root, skipping');
+            return null;
+        }
+        const command = 'npx tsc --noEmit --pretty false';
+        try {
+            const { stdout, stderr } = await execAsync(command, {
+                ...this.execOptions,
+                cwd: projectRoot,
+                shell: process.env.SHELL || '/bin/bash',
+            });
+            const output = (stdout + '\n' + stderr).trim();
+            return output || null;
+        }
+        catch (error) {
+            const execError = error;
+            // Timeout
+            if (execError.killed === true && execError.signal === 'SIGTERM') {
+                this.logger.warn({ timeout: this.execOptions.timeout }, 'tsc: timed out, skipping');
+                return null;
+            }
+            // tsc exits 2 when type errors are found — stdout/stderr still has valid output
+            const output = ((execError.stdout || '') + '\n' + (execError.stderr || '')).trim();
+            if (output) {
+                return output;
+            }
+            this.logger.warn({ error: error.message }, 'tsc: execution failed');
+            return null;
+        }
+    }
+    /**
+     * Check if any of the candidate files exist in the given directory
+     */
+    async hasAnyFile(directory, candidates) {
+        for (const file of candidates) {
+            try {
+                await access(join(directory, file));
+                return true;
+            }
+            catch {
+                // File doesn't exist, try next
+            }
+        }
+        return false;
+    }
+}

package/dist/services/review/review-config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Review Configuration Builder
+ *
+ * Merges review configuration from core-config.yaml with CLI flag overrides.
+ * CLI flags always take precedence over config file values. When neither is
+ * provided, hardcoded defaults are used.
+ */
+import type { ReviewConfig } from '../validation/config-validator.js';
+import { Severity } from './types.js';
+/**
+ * CLI flag values that can override config file settings.
+ * All fields are optional — only provided flags override config.
+ */
+export interface ReviewCliFlags {
+    /** Comma-separated severity levels that block the pipeline */
+    blockOn?: string;
+    /** Maximum self-heal iterations */
+    maxFix?: number;
+    /** Comma-separated scanner IDs */
+    scanners?: string;
+}
+/**
+ * Merged review configuration used at runtime
+ */
+export interface MergedReviewConfig {
+    enabled: boolean;
+    pathRules: Array<{
+        focus: string;
+        pattern: string;
+    }>;
+    scanners: string[];
+    selfHeal: {
+        fixAgent: string;
+        fixTimeout: number;
+        maxIterations: number;
+    };
+    severity: {
+        blockOn: string[];
+        documentOn: string[];
+        ignoreOn: string[];
+    };
+}
+/**
+ * Build merged review configuration from config file defaults and CLI flag overrides.
+ *
+ * Merge precedence: CLI flags > config file > hardcoded defaults.
+ *
+ * @param coreConfig - Review section from core-config.yaml (may be undefined)
+ * @param cliFlags - CLI flag values (may be undefined or partially provided)
+ * @returns Fully resolved review configuration
+ */
+export declare function buildReviewConfig(coreConfig?: ReviewConfig, cliFlags?: ReviewCliFlags): MergedReviewConfig;
+/**
+ * Convert merged severity.blockOn array to a single Severity threshold.
+ *
+ * Returns the lowest (most permissive) severity from the blockOn list,
+ * matching the pattern used by the review phase executor.
+ *
+ * @param blockOn - Array of severity level strings
+ * @returns Single Severity enum value (lowest rank in the list)
+ */
+export declare function blockOnToSeverity(blockOn: string[]): Severity;

package/dist/services/review/review-config.js

@@ -0,0 +1,91 @@
+/**
+ * Review Configuration Builder
+ *
+ * Merges review configuration from core-config.yaml with CLI flag overrides.
+ * CLI flags always take precedence over config file values. When neither is
+ * provided, hardcoded defaults are used.
+ */
+import { Severity } from './types.js';
+/**
+ * Hardcoded defaults used when neither config file nor CLI flags provide a value
+ */
+const DEFAULTS = {
+    enabled: false,
+    pathRules: [],
+    scanners: ['ai', 'lint'],
+    selfHeal: {
+        fixAgent: 'dev',
+        fixTimeout: 300_000,
+        maxIterations: 3,
+    },
+    severity: {
+        blockOn: ['CRITICAL', 'HIGH'],
+        documentOn: ['MEDIUM'],
+        ignoreOn: ['LOW'],
+    },
+};
+/**
+ * Build merged review configuration from config file defaults and CLI flag overrides.
+ *
+ * Merge precedence: CLI flags > config file > hardcoded defaults.
+ *
+ * @param coreConfig - Review section from core-config.yaml (may be undefined)
+ * @param cliFlags - CLI flag values (may be undefined or partially provided)
+ * @returns Fully resolved review configuration
+ */
+export function buildReviewConfig(coreConfig, cliFlags) {
+    // Start with defaults
+    const base = {
+        enabled: coreConfig?.enabled ?? DEFAULTS.enabled,
+        pathRules: coreConfig?.pathRules ?? DEFAULTS.pathRules,
+        scanners: coreConfig?.scanners ?? DEFAULTS.scanners,
+        selfHeal: {
+            fixAgent: coreConfig?.selfHeal?.fixAgent ?? DEFAULTS.selfHeal.fixAgent,
+            fixTimeout: coreConfig?.selfHeal?.fixTimeout ?? DEFAULTS.selfHeal.fixTimeout,
+            maxIterations: coreConfig?.selfHeal?.maxIterations ?? DEFAULTS.selfHeal.maxIterations,
+        },
+        severity: {
+            blockOn: coreConfig?.severity?.blockOn ?? DEFAULTS.severity.blockOn,
+            documentOn: coreConfig?.severity?.documentOn ?? DEFAULTS.severity.documentOn,
+            ignoreOn: coreConfig?.severity?.ignoreOn ?? DEFAULTS.severity.ignoreOn,
+        },
+    };
+    // Apply CLI flag overrides
+    if (cliFlags?.scanners) {
+        base.scanners = cliFlags.scanners.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    }
+    if (cliFlags?.blockOn) {
+        base.severity.blockOn = cliFlags.blockOn.split(',').map((s) => s.trim().toUpperCase()).filter(Boolean);
+    }
+    if (cliFlags?.maxFix !== undefined) {
+        base.selfHeal.maxIterations = cliFlags.maxFix;
+    }
+    return base;
+}
+/**
+ * Convert merged severity.blockOn array to a single Severity threshold.
+ *
+ * Returns the lowest (most permissive) severity from the blockOn list,
+ * matching the pattern used by the review phase executor.
+ *
+ * @param blockOn - Array of severity level strings
+ * @returns Single Severity enum value (lowest rank in the list)
+ */
+export function blockOnToSeverity(blockOn) {
+    const SEVERITY_RANK = {
+        CRITICAL: 4,
+        HIGH: 3,
+        LOW: 1,
+        MEDIUM: 2,
+    };
+    let lowestRank = Infinity;
+    let lowestSeverity = Severity.HIGH;
+    for (const sev of blockOn) {
+        const rank = SEVERITY_RANK[sev] ?? 0;
+        if (rank < lowestRank) {
+            lowestRank = rank;
+            lowestSeverity = sev;
+        }
+    }
+    return lowestSeverity;
+}