agentic-qe 3.7.15 → 3.7.17

package/dist/agents/devils-advocate/types.d.ts

@@ -52,6 +52,12 @@ export declare const SEVERITY_ORDER: readonly ChallengeSeverity[];
  * Higher weight means greater negative impact on the overall score.
  */
 export declare const SEVERITY_WEIGHTS: Readonly<Record<ChallengeSeverity, number>>;
+/**
+ * Weights used for minimum finding threshold calculations.
+ * Maps each severity to a point value for determining whether
+ * a review meets its minimum finding requirements.
+ */
+export declare const MINIMUM_FINDING_WEIGHTS: Readonly<Record<ChallengeSeverity, number>>;
 /**
  * A specific challenge raised against an agent's output.
  * Each challenge documents a gap, weakness, or questionable aspect
@@ -75,6 +81,22 @@ export interface Challenge {
     /** Confidence in this challenge being valid (0-1) */
     readonly confidence: number;
 }
+/**
+ * Justification provided when a review produces fewer findings than the
+ * minimum threshold. Documents what was examined and why no issues were found.
+ */
+export interface CleanJustification {
+    /** Whether the target was deemed genuinely clean */
+    readonly isClean: boolean;
+    /** Specific files that were examined during the review */
+    readonly filesExamined: readonly string[];
+    /** Patterns and anti-patterns that were checked */
+    readonly patternsChecked: readonly string[];
+    /** Tools and strategies that were run */
+    readonly toolsRun: readonly string[];
+    /** Detailed reasoning for why no issues were found */
+    readonly reasoning: string;
+}
 /**
  * Result of a Devil's Advocate review of an agent's output.
  * Aggregates all challenges found and provides an overall assessment.
@@ -94,6 +116,34 @@ export interface ChallengeResult {
     readonly timestamp: number;
     /** How long the review took (ms) */
     readonly reviewDuration: number;
+    /** Clean justification when findings are below minimum threshold */
+    readonly cleanJustification?: CleanJustification;
+    /** Weighted finding score based on MINIMUM_FINDING_WEIGHTS */
+    readonly weightedFindingScore?: number;
+    /** Whether the minimum finding threshold was met */
+    readonly minimumMet?: boolean;
+}
+/**
+ * Outcome of a Devil's Advocate review, used for learning feedback.
+ * Captures which challenges were accepted or dismissed by the user.
+ */
+export interface ReviewOutcome {
+    /** What type of output was reviewed */
+    readonly targetType: ChallengeTargetType;
+    /** ID of the agent whose output was reviewed */
+    readonly targetAgentId: string;
+    /** Total number of challenges raised */
+    readonly challengeCount: number;
+    /** Number of challenges accepted by the user */
+    readonly acceptedCount: number;
+    /** Number of challenges dismissed by the user */
+    readonly dismissedCount: number;
+    /** Breakdown of challenges by severity */
+    readonly severityBreakdown: Readonly<Record<string, number>>;
+    /** Whether the minimum finding threshold was met */
+    readonly minimumMet: boolean;
+    /** ISO timestamp of when the outcome was recorded */
+    readonly timestamp: string;
 }
 /**
  * Types of challenge strategies the Devil's Advocate can employ.
@@ -135,6 +185,10 @@ export interface DevilsAdvocateConfig {
     readonly enabledStrategies: readonly ChallengeStrategyType[];
     /** Only include challenges at or above this severity. @default 'informational' */
     readonly minSeverity: ChallengeSeverity;
+    /** Minimum weighted finding score required for a review. @default 3 */
+    readonly minimumFindings: number;
+    /** How to evaluate minimum findings: 'weighted' uses severity weights, 'count' uses raw count. @default 'weighted' */
+    readonly minimumFindingsMode: 'weighted' | 'count';
 }
 /**
  * Default configuration for the Devil's Advocate agent.

package/dist/agents/devils-advocate/types.js

@@ -42,6 +42,18 @@ export const SEVERITY_WEIGHTS = {
     low: 0.03,
     informational: 0.01,
 };
+/**
+ * Weights used for minimum finding threshold calculations.
+ * Maps each severity to a point value for determining whether
+ * a review meets its minimum finding requirements.
+ */
+export const MINIMUM_FINDING_WEIGHTS = {
+    critical: 3,
+    high: 2,
+    medium: 1,
+    low: 0.5,
+    informational: 0.25,
+};
 /**
  * All valid challenge strategy types, for runtime validation.
  */
@@ -62,6 +74,8 @@ export const DEFAULT_DEVILS_ADVOCATE_CONFIG = {
     maxChallengesPerReview: 20,
     enabledStrategies: ALL_CHALLENGE_STRATEGY_TYPES,
     minSeverity: 'informational',
+    minimumFindings: 3,
+    minimumFindingsMode: 'weighted',
 };
 // ============================================================================
 // Type Guards

package/dist/agents/overlay-loader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Agent Overlay Loader (BMAD-002)
+ *
+ * Discovers, validates, and applies agent customization overlays from
+ * .claude/agent-overrides/*.yaml files.
+ */
+import { AgentOverlay, OverlayLoadResult, AppliedOverlay } from './overlay-schema.js';
+/**
+ * Load all overlay files from the overrides directory.
+ */
+export declare function loadOverlays(projectRoot: string): OverlayLoadResult;
+/**
+ * Apply an overlay to agent markdown content.
+ * Returns the modified content and a record of what was applied.
+ */
+export declare function applyOverlayToContent(agentContent: string, overlay: AgentOverlay): {
+    content: string;
+    applied: AppliedOverlay;
+};
+/**
+ * Get overlay for a specific agent by name.
+ */
+export declare function getOverlayForAgent(overlays: AgentOverlay[], agentName: string): AgentOverlay | undefined;
+/**
+ * Get config overrides for a specific agent.
+ */
+export declare function getAgentConfigOverrides(overlays: AgentOverlay[], agentName: string): AgentOverlay['config'] | undefined;
+//# sourceMappingURL=overlay-loader.d.ts.map

package/dist/agents/overlay-loader.js

@@ -0,0 +1,232 @@
+/**
+ * Agent Overlay Loader (BMAD-002)
+ *
+ * Discovers, validates, and applies agent customization overlays from
+ * .claude/agent-overrides/*.yaml files.
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import { validateOverlay } from './overlay-schema.js';
+const OVERRIDES_DIR = '.claude/agent-overrides';
+/**
+ * Parse YAML-like overlay files.
+ * Uses a simple parser to avoid adding a yaml dependency.
+ * Supports basic key-value pairs and nested objects.
+ */
+function parseSimpleYaml(content) {
+    const result = {};
+    const lines = content.split('\n');
+    let currentSection = null;
+    let currentSubSection = null;
+    let currentArray = null;
+    let currentArrayKey = null;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\r$/, '');
+        // Skip comments and empty lines
+        if (line.trim().startsWith('#') || line.trim() === '')
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        // Array item
+        if (trimmed.startsWith('- ')) {
+            const value = trimmed.slice(2).trim().replace(/^["']|["']$/g, '');
+            if (currentArray) {
+                currentArray.push(value);
+            }
+            continue;
+        }
+        // Flush any pending array
+        if (currentArray && currentArrayKey) {
+            if (currentSubSection && currentSection) {
+                const section = result[currentSection] || {};
+                section[currentArrayKey] = currentArray;
+                result[currentSection] = section;
+            }
+            else if (currentSection) {
+                const section = result[currentSection] || {};
+                section[currentArrayKey] = currentArray;
+                result[currentSection] = section;
+            }
+            currentArray = null;
+            currentArrayKey = null;
+        }
+        // Key-value pair
+        const match = trimmed.match(/^(\w[\w.-]*)\s*:\s*(.*)$/);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        const value = rawValue.trim().replace(/^["']|["']$/g, '');
+        if (indent === 0) {
+            // Top-level key
+            if (value === '' || value === undefined) {
+                currentSection = key;
+                currentSubSection = null;
+                if (!result[key])
+                    result[key] = {};
+            }
+            else {
+                result[key] = parseValue(value);
+                currentSection = null;
+                currentSubSection = null;
+            }
+        }
+        else if (indent <= 4 && currentSection) {
+            if (value === '' || value === undefined) {
+                // Sub-section or array start
+                currentSubSection = key;
+                currentArray = [];
+                currentArrayKey = key;
+            }
+            else {
+                const section = result[currentSection] || {};
+                section[key] = parseValue(value);
+                result[currentSection] = section;
+            }
+        }
+    }
+    // Flush final array
+    if (currentArray && currentArrayKey && currentSection) {
+        const section = result[currentSection] || {};
+        section[currentArrayKey] = currentArray;
+        result[currentSection] = section;
+    }
+    return result;
+}
+function parseValue(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null')
+        return null;
+    const num = Number(value);
+    if (!isNaN(num) && value !== '')
+        return num;
+    return value;
+}
+/**
+ * Load all overlay files from the overrides directory.
+ */
+export function loadOverlays(projectRoot) {
+    const overlaysDir = join(projectRoot, OVERRIDES_DIR);
+    const result = {
+        overlays: [],
+        warnings: [],
+        errors: [],
+    };
+    if (!existsSync(overlaysDir)) {
+        return result;
+    }
+    let files;
+    try {
+        files = readdirSync(overlaysDir).filter(f => (f.endsWith('.yaml') || f.endsWith('.yml')) && !f.startsWith('_'));
+    }
+    catch (err) {
+        result.errors.push(`Failed to read overrides directory: ${err.message}`);
+        return result;
+    }
+    for (const file of files) {
+        const filePath = join(overlaysDir, file);
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const parsed = parseSimpleYaml(content);
+            // Infer agent name from filename if not specified
+            if (!parsed.agent) {
+                const agentName = basename(file).replace(/\.(override|customize)\.(yaml|yml)$/, '');
+                parsed.agent = agentName;
+            }
+            const validationErrors = validateOverlay(parsed);
+            if (validationErrors.length > 0) {
+                result.warnings.push(`Overlay ${file} has validation issues: ${validationErrors.join('; ')}. Loading without overlay.`);
+                continue;
+            }
+            result.overlays.push(parsed);
+        }
+        catch (err) {
+            result.warnings.push(`Failed to parse overlay ${file}: ${err.message}. Agent loads without overlay.`);
+        }
+    }
+    return result;
+}
+/**
+ * Apply an overlay to agent markdown content.
+ * Returns the modified content and a record of what was applied.
+ */
+export function applyOverlayToContent(agentContent, overlay) {
+    let content = agentContent;
+    const applied = {
+        agentName: overlay.agent,
+        overlayFile: `${overlay.agent}.override.yaml`,
+        replacedFields: [],
+        appendedFields: [],
+        configOverrides: [],
+    };
+    // Apply replacements in frontmatter-like sections
+    if (overlay.replace) {
+        if (overlay.replace.description) {
+            // Replace description in markdown metadata comment or first paragraph
+            const descRegex = /^(description:\s*).+$/m;
+            if (descRegex.test(content)) {
+                content = content.replace(descRegex, `$1${overlay.replace.description}`);
+                applied.replacedFields.push('description');
+            }
+        }
+        if (overlay.replace.domains) {
+            const domainRegex = /^(domain:\s*).+$/m;
+            if (domainRegex.test(content)) {
+                content = content.replace(domainRegex, `$1${overlay.replace.domains.join(', ')}`);
+                applied.replacedFields.push('domains');
+            }
+        }
+        if (overlay.replace.complexity) {
+            const complexityRegex = /^(complexity:\s*).+$/m;
+            if (complexityRegex.test(content)) {
+                content = content.replace(complexityRegex, `$1${overlay.replace.complexity}`);
+                applied.replacedFields.push('complexity');
+            }
+        }
+    }
+    // Append additional content
+    if (overlay.append) {
+        if (overlay.append.instructions) {
+            content += `\n\n## Custom Instructions (User Override)\n\n${overlay.append.instructions}\n`;
+            applied.appendedFields.push('instructions');
+        }
+        if (overlay.append.capabilities && overlay.append.capabilities.length > 0) {
+            const capsSection = overlay.append.capabilities.map(c => `- ${c}`).join('\n');
+            content += `\n\n### Additional Capabilities (User Override)\n\n${capsSection}\n`;
+            applied.appendedFields.push('capabilities');
+        }
+        if (overlay.append.tags && overlay.append.tags.length > 0) {
+            // Append tags to existing tags line or add new
+            const tagsRegex = /^(tags:\s*).+$/m;
+            if (tagsRegex.test(content)) {
+                content = content.replace(tagsRegex, (match) => {
+                    const existing = match.replace(/^tags:\s*/, '').split(',').map(t => t.trim());
+                    const merged = [...new Set([...existing, ...overlay.append.tags])];
+                    return `tags: ${merged.join(', ')}`;
+                });
+            }
+            applied.appendedFields.push('tags');
+        }
+    }
+    // Track config overrides
+    if (overlay.config) {
+        applied.configOverrides = Object.keys(overlay.config);
+    }
+    return { content, applied };
+}
+/**
+ * Get overlay for a specific agent by name.
+ */
+export function getOverlayForAgent(overlays, agentName) {
+    return overlays.find(o => o.agent === agentName);
+}
+/**
+ * Get config overrides for a specific agent.
+ */
+export function getAgentConfigOverrides(overlays, agentName) {
+    const overlay = getOverlayForAgent(overlays, agentName);
+    return overlay?.config;
+}
+//# sourceMappingURL=overlay-loader.js.map

package/dist/agents/overlay-schema.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agent Customization Overlay Schema (BMAD-002)
+ *
+ * Allows users to customize agent behavior via .claude/agent-overrides/*.yaml
+ * files that survive `aqe init` reinstalls.
+ */
+export interface AgentOverlay {
+    /** Agent identifier, e.g. "qe-test-architect" */
+    agent: string;
+    /** Fields that REPLACE base agent content */
+    replace?: {
+        description?: string;
+        domains?: string[];
+        complexity?: string;
+    };
+    /** Fields that APPEND to base agent content */
+    append?: {
+        /** Additional instructions appended to agent .md body */
+        instructions?: string;
+        /** Additional capabilities */
+        capabilities?: string[];
+        /** Additional tags */
+        tags?: string[];
+    };
+    /** Runtime configuration overrides */
+    config?: {
+        /** For review agents - minimum weighted findings */
+        minimumFindings?: number;
+        /** Maximum parallel agents for orchestrators */
+        maxParallelAgents?: number;
+        /** Preferred test frameworks */
+        preferredFrameworks?: string[];
+        /** Severity thresholds per category */
+        severityThresholds?: Record<string, number>;
+        /** Context compilation opt-out */
+        needsContext?: boolean;
+    };
+}
+export interface OverlayLoadResult {
+    overlays: AgentOverlay[];
+    warnings: string[];
+    errors: string[];
+}
+export interface AppliedOverlay {
+    agentName: string;
+    overlayFile: string;
+    replacedFields: string[];
+    appendedFields: string[];
+    configOverrides: string[];
+}
+/**
+ * Validates an overlay object against the schema.
+ * Returns validation errors (empty array = valid).
+ */
+export declare function validateOverlay(overlay: unknown): string[];
+//# sourceMappingURL=overlay-schema.d.ts.map

package/dist/agents/overlay-schema.js

@@ -0,0 +1,77 @@
+/**
+ * Agent Customization Overlay Schema (BMAD-002)
+ *
+ * Allows users to customize agent behavior via .claude/agent-overrides/*.yaml
+ * files that survive `aqe init` reinstalls.
+ */
+/**
+ * Validates an overlay object against the schema.
+ * Returns validation errors (empty array = valid).
+ */
+export function validateOverlay(overlay) {
+    const errors = [];
+    if (!overlay || typeof overlay !== 'object') {
+        errors.push('Overlay must be a non-null object');
+        return errors;
+    }
+    const obj = overlay;
+    if (!obj.agent || typeof obj.agent !== 'string') {
+        errors.push('Overlay must have a string "agent" field');
+    }
+    if (obj.replace !== undefined) {
+        if (typeof obj.replace !== 'object' || obj.replace === null) {
+            errors.push('"replace" must be an object');
+        }
+        else {
+            const replace = obj.replace;
+            if (replace.description !== undefined && typeof replace.description !== 'string') {
+                errors.push('"replace.description" must be a string');
+            }
+            if (replace.domains !== undefined && !Array.isArray(replace.domains)) {
+                errors.push('"replace.domains" must be an array');
+            }
+            if (replace.complexity !== undefined && typeof replace.complexity !== 'string') {
+                errors.push('"replace.complexity" must be a string');
+            }
+        }
+    }
+    if (obj.append !== undefined) {
+        if (typeof obj.append !== 'object' || obj.append === null) {
+            errors.push('"append" must be an object');
+        }
+        else {
+            const append = obj.append;
+            if (append.instructions !== undefined && typeof append.instructions !== 'string') {
+                errors.push('"append.instructions" must be a string');
+            }
+            if (append.capabilities !== undefined && !Array.isArray(append.capabilities)) {
+                errors.push('"append.capabilities" must be an array');
+            }
+            if (append.tags !== undefined && !Array.isArray(append.tags)) {
+                errors.push('"append.tags" must be an array');
+            }
+        }
+    }
+    if (obj.config !== undefined) {
+        if (typeof obj.config !== 'object' || obj.config === null) {
+            errors.push('"config" must be an object');
+        }
+        else {
+            const config = obj.config;
+            if (config.minimumFindings !== undefined && typeof config.minimumFindings !== 'number') {
+                errors.push('"config.minimumFindings" must be a number');
+            }
+            if (config.maxParallelAgents !== undefined && typeof config.maxParallelAgents !== 'number') {
+                errors.push('"config.maxParallelAgents" must be a number');
+            }
+            if (config.preferredFrameworks !== undefined && !Array.isArray(config.preferredFrameworks)) {
+                errors.push('"config.preferredFrameworks" must be an array');
+            }
+            if (config.needsContext !== undefined && typeof config.needsContext !== 'boolean') {
+                errors.push('"config.needsContext" must be a boolean');
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=overlay-schema.js.map

package/dist/analysis/branch-enumerator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Branch Enumerator Utility (BMAD-004)
+ *
+ * Mechanically enumerates all branching constructs in TypeScript/JavaScript files
+ * without subjective risk scoring. Reports every unhandled path for completeness.
+ *
+ * Design: Strategy pattern (BranchEnumerator interface) for future multi-language support.
+ * Uses regex-based pattern matching (NOT AST parsing) to keep the utility lightweight
+ * and avoid parser version issues (Gap 5).
+ */
+export type SupportedLanguage = 'typescript' | 'javascript';
+export type ConstructType = 'if-without-else' | 'switch-no-default' | 'switch-missing-break' | 'try-empty-catch' | 'try-no-finally' | 'optional-chaining-null-path' | 'nullish-coalescing-fallback' | 'logical-or-falsy' | 'logical-and-short-circuit' | 'promise-no-catch' | 'array-callback-empty' | 'ternary-complex' | 'type-guard-unhandled';
+export interface UnhandledBranch {
+    file: string;
+    line: number;
+    column: number;
+    language: SupportedLanguage;
+    construct: ConstructType;
+    triggerCondition: string;
+    currentHandling: string;
+    suggestedGuard: string;
+    severity: 'high' | 'medium' | 'low';
+}
+export interface BranchEnumerator {
+    /** Enumerate all unhandled branches in source code. */
+    enumerate(sourceCode: string, filePath: string): UnhandledBranch[];
+    /** Supported language */
+    readonly language: SupportedLanguage;
+}
+export interface EnumerationResult {
+    file: string;
+    language: SupportedLanguage;
+    branches: UnhandledBranch[];
+    totalConstructs: number;
+    unhandledCount: number;
+    duration: number;
+}
+/**
+ * TypeScript/JavaScript branch enumerator.
+ * Uses line-by-line pattern matching for reliability.
+ */
+export declare class TSBranchEnumerator implements BranchEnumerator {
+    readonly language: SupportedLanguage;
+    constructor(language?: SupportedLanguage);
+    enumerate(sourceCode: string, filePath: string): UnhandledBranch[];
+    /**
+     * Check if an if-statement has a matching else.
+     * Simple heuristic: look for 'else' at same or lower indentation within ~30 lines.
+     */
+    private findMatchingElse;
+    /**
+     * Extract the block (curly braces content) starting near a line.
+     */
+    private extractBlock;
+}
+/**
+ * Enumerate branches in a source file.
+ */
+export declare function enumerateBranches(sourceCode: string, filePath: string, language?: SupportedLanguage): EnumerationResult;
+/**
+ * Format enumeration result as markdown.
+ */
+export declare function formatBranchReport(result: EnumerationResult): string;
+/**
+ * Format enumeration result as JSON.
+ */
+export declare function formatBranchJSON(result: EnumerationResult): string;
+//# sourceMappingURL=branch-enumerator.d.ts.map