agentic-qe 3.7.16 → 3.7.18

package/dist/mcp/services/task-router.d.ts

@@ -51,6 +51,16 @@ export interface TaskRoutingResult {
     readonly patternHints?: readonly PatternHint[];
     /** Pattern context formatted for agent prompts (Phase 5.2) */
     readonly patternContext?: string;
+    /** Overlay config overrides for the routed agent (BMAD-002) */
+    readonly overlayConfig?: {
+        minimumFindings?: number;
+        maxParallelAgents?: number;
+        preferredFrameworks?: string[];
+        severityThresholds?: Record<string, number>;
+        needsContext?: boolean;
+    };
+    /** Compiled context from ContextCompiler (BMAD-005) */
+    compiledContext?: string;
 }
 /**
  * Routing log entry for metrics and debugging
@@ -113,6 +123,7 @@ export declare class TaskRouterService {
     private readonly modelRouter;
     private readonly minCutRouter;
     private readonly routingLog;
+    private readonly contextCompiler;
     private disposed;
     private constructor();
     /**

package/dist/mcp/services/task-router.js

@@ -9,6 +9,8 @@
  */
 import { createModelRouter, createModelRouterWithAgentBooster, TIER_METADATA, } from '../../integrations/agentic-flow';
 import { createMinCutRoutingService, } from './mincut-routing-service.js';
+import { getAgentOverlayConfig } from '../../routing/qe-agent-registry.js';
+import { ContextCompiler, formatContextForPrompt } from '../../context/compiler.js';
 /**
  * Default Task Router configuration
  */
@@ -47,10 +49,12 @@ export class TaskRouterService {
     modelRouter;
     minCutRouter;
     routingLog = [];
+    contextCompiler;
     disposed = false;
     constructor(config, modelRouter) {
         this.config = config;
         this.modelRouter = modelRouter;
+        this.contextCompiler = new ContextCompiler();
         this.minCutRouter = createMinCutRoutingService({
             enableLogging: config.enableLogging,
         });
@@ -188,6 +192,26 @@ export class TaskRouterService {
         const patternContext = patternHints && patternHints.length > 0
             ? this.formatPatternContext(patternHints)
             : undefined;
+        // Check for overlay config overrides for the routed agent
+        const agentType = input.agentType;
+        const overlayConfig = agentType
+            ? (getAgentOverlayConfig(agentType) || getAgentOverlayConfig(agentType.replace('v3-qe-', 'qe-')))
+            : undefined;
+        // Compile context if file paths are provided (BMAD-005)
+        let compiledContext;
+        if (input.filePaths && input.filePaths.length > 0) {
+            try {
+                const compiled = await this.contextCompiler.compile({
+                    targetFiles: input.filePaths,
+                    agentType: input.agentType || 'unknown',
+                    taskDescription: input.task,
+                });
+                compiledContext = formatContextForPrompt(compiled);
+            }
+            catch {
+                // Non-blocking — context compilation failure should not affect routing
+            }
+        }
         return {
             decision: effectiveDecision,
             executionStrategy,
@@ -202,6 +226,8 @@ export class TaskRouterService {
             logEntry,
             patternHints,
             patternContext,
+            overlayConfig,
+            compiledContext,
         };
     }
     /**

package/dist/routing/qe-agent-registry.d.ts

@@ -23,6 +23,7 @@
  */
 import type { QEAgentProfile, AgentCapability, ProgrammingLanguage, TestFramework, ComplexityLevel } from './types.js';
 import type { QEDomain } from '../learning/qe-patterns.js';
+import type { AgentOverlay } from '../agents/overlay-schema.js';
 /**
  * All QE agents in the registry
  */
@@ -91,4 +92,14 @@ export declare function getAgentsByPerformance(domain?: QEDomain): QEAgentProfil
  * Reset all agent performance metrics (for testing)
  */
 export declare function resetAgentPerformanceMetrics(): void;
+/**
+ * Initialize overlay configurations from project root.
+ * Loads all .claude/agent-overrides/*.yaml files and caches their config sections.
+ */
+export declare function initializeOverlays(projectRoot: string): void;
+/**
+ * Get overlay configuration for a specific agent.
+ * Returns undefined if no overlay exists for the agent.
+ */
+export declare function getAgentOverlayConfig(agentId: string): AgentOverlay['config'] | undefined;
 //# sourceMappingURL=qe-agent-registry.d.ts.map

package/dist/routing/qe-agent-registry.js

@@ -21,6 +21,7 @@
  * - V3 Specialized: {name} (cross-cutting, no v3-qe prefix, e.g., memory-specialist)
  * - Legacy/V2 Compatibility: qe-* (deprecated, use v3-qe-* instead)
  */
+import { loadOverlays } from '../agents/overlay-loader.js';
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -1174,4 +1175,37 @@ export function resetAgentPerformanceMetrics() {
     }
     console.error('[AgentRegistry] Reset all agent performance metrics');
 }
+// ============================================================================
+// Agent Customization Overlays (BMAD-002)
+// ============================================================================
+/** Module-level cache of overlay configs keyed by agent ID */
+let overlayConfigs = new Map();
+/**
+ * Initialize overlay configurations from project root.
+ * Loads all .claude/agent-overrides/*.yaml files and caches their config sections.
+ */
+export function initializeOverlays(projectRoot) {
+    overlayConfigs = new Map();
+    const result = loadOverlays(projectRoot);
+    for (const overlay of result.overlays) {
+        if (overlay.config) {
+            overlayConfigs.set(overlay.agent, overlay.config);
+        }
+    }
+    if (overlayConfigs.size > 0) {
+        console.error(`[AgentRegistry] Loaded overlay configs for ${overlayConfigs.size} agent(s): ${[...overlayConfigs.keys()].join(', ')}`);
+    }
+    if (result.warnings.length > 0) {
+        for (const warning of result.warnings) {
+            console.error(`[AgentRegistry] Overlay warning: ${warning}`);
+        }
+    }
+}
+/**
+ * Get overlay configuration for a specific agent.
+ * Returns undefined if no overlay exists for the agent.
+ */
+export function getAgentOverlayConfig(agentId) {
+    return overlayConfigs.get(agentId);
+}
 //# sourceMappingURL=qe-agent-registry.js.map

package/dist/routing/qe-task-router.d.ts

@@ -17,6 +17,7 @@ export declare class QETaskRouter {
     private agentEmbeddings;
     private initialized;
     private embeddingCache;
+    private contextCompiler;
     /** Optional witness chain for audit trail of routing decisions (ADR-070) */
     private _witnessChain;
     set witnessChain(wc: WitnessChain | null);

package/dist/routing/qe-task-router.js

@@ -9,8 +9,9 @@
  */
 import { performance } from 'perf_hooks';
 import { DEFAULT_ROUTER_CONFIG } from './types.js';
-import { QE_AGENT_REGISTRY, getAgentById } from './qe-agent-registry.js';
+import { QE_AGENT_REGISTRY, getAgentById, getAgentOverlayConfig, initializeOverlays } from './qe-agent-registry.js';
 import { computeRealEmbedding, cosineSimilarity, } from '../learning/real-embeddings.js';
+import { ContextCompiler, formatContextForPrompt } from '../context/compiler.js';
 // ============================================================================
 // Task Keyword Detection
 // ============================================================================
@@ -130,6 +131,7 @@ export class QETaskRouter {
     agentEmbeddings = new Map();
     initialized = false;
     embeddingCache = new Map();
+    contextCompiler = null;
     /** Optional witness chain for audit trail of routing decisions (ADR-070) */
     _witnessChain = null;
     set witnessChain(wc) { this._witnessChain = wc; }
@@ -142,12 +144,15 @@ export class QETaskRouter {
     async initialize() {
         if (this.initialized)
             return;
+        // Load overlay configs so routing can apply user customizations
+        initializeOverlays(process.cwd());
         // Compute embedding for each agent based on their description and capabilities
         for (const agent of QE_AGENT_REGISTRY) {
             const text = this.buildAgentEmbeddingText(agent);
             const embedding = await computeRealEmbedding(text);
             this.agentEmbeddings.set(agent.id, embedding);
         }
+        this.contextCompiler = new ContextCompiler();
         this.initialized = true;
     }
     /**
@@ -209,7 +214,23 @@ export class QETaskRouter {
             }, 'qe-task-router');
         }
         catch { /* best-effort witness */ }
-        return {
+        // Compile context for the recommended agent (if files provided)
+        let compiledContext;
+        const filePaths = task.context?.files;
+        if (filePaths && filePaths.length > 0 && this.contextCompiler) {
+            try {
+                const context = await this.contextCompiler.compile({
+                    targetFiles: filePaths,
+                    agentType: topScore.agent,
+                    taskDescription: task.description,
+                });
+                compiledContext = formatContextForPrompt(context);
+            }
+            catch {
+                // Context compilation failure is non-blocking
+            }
+        }
+        const decision = {
             recommended: topScore.agent,
             confidence: topScore.combinedScore,
             alternatives,
@@ -223,6 +244,10 @@ export class QETaskRouter {
             latencyMs,
             timestamp: new Date(),
         };
+        if (compiledContext) {
+            decision.compiledContext = compiledContext;
+        }
+        return decision;
     }
     /**
      * Detect QE domain from task description
@@ -372,6 +397,13 @@ export class QETaskRouter {
         if (task.context?.previousAgent === agent.id) {
             bonus += 0.05;
         }
+        // Bonus from overlay config (user customizations)
+        const overlayConfig = getAgentOverlayConfig(agent.id) || getAgentOverlayConfig(agent.id.replace('v3-qe-', 'qe-'));
+        if (overlayConfig?.preferredFrameworks && task.framework) {
+            if (overlayConfig.preferredFrameworks.includes(task.framework)) {
+                bonus += 0.1;
+            }
+        }
         // 5. Combined weighted score
         const { weights } = this.config;
         const combinedScore = Math.min(1.0, (weights.similarity * similarityScore) +

package/dist/routing/types.d.ts

@@ -112,6 +112,8 @@ export interface QERoutingDecision {
     readonly latencyMs: number;
     /** Timestamp */
     readonly timestamp: Date;
+    /** Compiled context for the recommended agent (if files provided) */
+    compiledContext?: string;
 }
 /**
  * Routing weights for combining scores

package/dist/validation/index.d.ts

@@ -20,4 +20,7 @@ export { TriggerOptimizer, createTriggerOptimizer, parseSkillFrontmatter, } from
 export type { SkillMetadata, TriggerAnalysisConfig, TriggerAnalysisResult, TriggerSuggestion, TriggerOptimizationReport, } from './trigger-optimizer.js';
 export { VersionComparator, createVersionComparator, } from './version-comparator.js';
 export type { VersionComparisonConfig, SkillVersion, VersionComparisonResult, VersionResult, ComparisonStats, TestCaseComparison, } from './version-comparator.js';
+export { runPipeline, formatPipelineReport, } from './pipeline.js';
+export type { StepCategory, StepSeverity, StepStatus, Finding, ValidationContext, ValidationStep, StepResult, PipelineConfig, PipelineResult, } from './pipeline.js';
+export { REQUIREMENTS_VALIDATION_STEPS, createRequirementsPipeline, formatCheckStep, completenessCheckStep, investCriteriaStep, smartAcceptanceStep, testabilityScoreStep, vagueTermStep, informationDensityStep, traceabilityCheckStep, implementationLeakageStep, domainComplianceStep, dependencyAnalysisStep, bddScenarioStep, holisticQualityStep, } from './steps/requirements.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/validation/index.js

@@ -36,4 +36,14 @@ export { TriggerOptimizer, createTriggerOptimizer, parseSkillFrontmatter, } from
 // Version Comparator (ADR-056: A/B testing between skill versions)
 // ============================================================================
 export { VersionComparator, createVersionComparator, } from './version-comparator.js';
+// ============================================================================
+// Structured Validation Pipeline (BMAD-003)
+// ============================================================================
+export { runPipeline, formatPipelineReport, } from './pipeline.js';
+// ============================================================================
+// Requirements Validation Steps (BMAD-003)
+// ============================================================================
+export { REQUIREMENTS_VALIDATION_STEPS, createRequirementsPipeline, 
+// Individual steps
+formatCheckStep, completenessCheckStep, investCriteriaStep, smartAcceptanceStep, testabilityScoreStep, vagueTermStep, informationDensityStep, traceabilityCheckStep, implementationLeakageStep, domainComplianceStep, dependencyAnalysisStep, bddScenarioStep, holisticQualityStep, } from './steps/requirements.js';
 //# sourceMappingURL=index.js.map

package/dist/validation/pipeline.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Structured Validation Pipeline Framework (BMAD-003)
+ *
+ * Generic pipeline runner that executes validation steps sequentially,
+ * enforcing gates and producing structured reports.
+ */
+export type StepCategory = 'format' | 'content' | 'quality' | 'traceability' | 'compliance';
+export type StepSeverity = 'blocking' | 'warning' | 'info';
+export type StepStatus = 'pass' | 'fail' | 'warn' | 'skip';
+export interface Finding {
+    id: string;
+    stepId: string;
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    title: string;
+    description: string;
+    location?: string;
+    suggestion?: string;
+}
+export interface ValidationContext {
+    /** The content being validated (requirements doc, code, etc.) */
+    content: string;
+    /** File path if applicable */
+    filePath?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Results from previous steps (accumulated) */
+    previousResults: StepResult[];
+}
+export interface ValidationStep {
+    id: string;
+    name: string;
+    category: StepCategory;
+    severity: StepSeverity;
+    description?: string;
+    execute(context: ValidationContext): Promise<StepResult>;
+}
+export interface StepResult {
+    stepId: string;
+    stepName: string;
+    status: StepStatus;
+    score: number;
+    findings: Finding[];
+    evidence: string[];
+    duration: number;
+}
+export interface PipelineConfig {
+    /** Pipeline identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Steps to execute */
+    steps: ValidationStep[];
+    /** Continue past blocking failures */
+    continueOnFailure?: boolean;
+    /** Only run specific steps (by id) */
+    stepFilter?: string[];
+    /** Weights for score calculation (step category -> weight) */
+    categoryWeights?: Record<StepCategory, number>;
+}
+export interface PipelineResult {
+    pipelineId: string;
+    pipelineName: string;
+    overall: 'pass' | 'fail' | 'warn';
+    score: number;
+    steps: StepResult[];
+    blockers: Finding[];
+    halted: boolean;
+    haltedAt?: string;
+    totalDuration: number;
+    timestamp: string;
+}
+/**
+ * Execute a validation pipeline.
+ */
+export declare function runPipeline(config: PipelineConfig, content: string, filePath?: string, metadata?: Record<string, unknown>): Promise<PipelineResult>;
+/**
+ * Format pipeline result as markdown report.
+ */
+export declare function formatPipelineReport(result: PipelineResult): string;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/validation/pipeline.js

@@ -0,0 +1,173 @@
+/**
+ * Structured Validation Pipeline Framework (BMAD-003)
+ *
+ * Generic pipeline runner that executes validation steps sequentially,
+ * enforcing gates and producing structured reports.
+ */
+const DEFAULT_CATEGORY_WEIGHTS = {
+    format: 0.10,
+    content: 0.30,
+    quality: 0.25,
+    traceability: 0.20,
+    compliance: 0.15,
+};
+/**
+ * Execute a validation pipeline.
+ */
+export async function runPipeline(config, content, filePath, metadata) {
+    const startTime = Date.now();
+    const weights = config.categoryWeights || DEFAULT_CATEGORY_WEIGHTS;
+    const context = {
+        content,
+        filePath,
+        metadata,
+        previousResults: [],
+    };
+    const stepResults = [];
+    const blockers = [];
+    let halted = false;
+    let haltedAt;
+    // Filter steps if specified
+    const stepsToRun = config.stepFilter
+        ? config.steps.filter(s => config.stepFilter.includes(s.id))
+        : config.steps;
+    for (const step of stepsToRun) {
+        const stepStart = Date.now();
+        let result;
+        try {
+            result = await step.execute(context);
+        }
+        catch (err) {
+            result = {
+                stepId: step.id,
+                stepName: step.name,
+                status: 'fail',
+                score: 0,
+                findings: [{
+                        id: `${step.id}-error`,
+                        stepId: step.id,
+                        severity: 'critical',
+                        title: `Step execution failed: ${step.name}`,
+                        description: err.message,
+                    }],
+                evidence: ['Step threw an exception during execution'],
+                duration: Date.now() - stepStart,
+            };
+        }
+        // Ensure duration is set
+        if (!result.duration) {
+            result.duration = Date.now() - stepStart;
+        }
+        stepResults.push(result);
+        context.previousResults.push(result);
+        // Check for blocking failure
+        if (step.severity === 'blocking' && result.status === 'fail') {
+            blockers.push(...result.findings);
+            if (!config.continueOnFailure) {
+                halted = true;
+                haltedAt = step.id;
+                break;
+            }
+        }
+    }
+    // Calculate overall score (weighted average by category)
+    const categoryScores = {};
+    for (const result of stepResults) {
+        const step = config.steps.find(s => s.id === result.stepId);
+        if (!step)
+            continue;
+        if (!categoryScores[step.category]) {
+            categoryScores[step.category] = { total: 0, count: 0 };
+        }
+        categoryScores[step.category].total += result.score;
+        categoryScores[step.category].count += 1;
+    }
+    let weightedScore = 0;
+    let totalWeight = 0;
+    for (const [category, { total, count }] of Object.entries(categoryScores)) {
+        const avgScore = count > 0 ? total / count : 0;
+        const weight = weights[category] || 0.1;
+        weightedScore += avgScore * weight;
+        totalWeight += weight;
+    }
+    const finalScore = totalWeight > 0 ? Math.round(weightedScore / totalWeight) : 0;
+    // Determine overall status
+    let overall;
+    if (blockers.length > 0) {
+        overall = 'fail';
+    }
+    else if (stepResults.some(r => r.status === 'warn')) {
+        overall = 'warn';
+    }
+    else if (finalScore >= 70) {
+        overall = 'pass';
+    }
+    else {
+        overall = 'warn';
+    }
+    return {
+        pipelineId: config.id,
+        pipelineName: config.name,
+        overall,
+        score: finalScore,
+        steps: stepResults,
+        blockers,
+        halted,
+        haltedAt,
+        totalDuration: Date.now() - startTime,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Format pipeline result as markdown report.
+ */
+export function formatPipelineReport(result) {
+    const lines = [];
+    const statusLabel = result.overall === 'pass' ? 'PASS' : result.overall === 'fail' ? 'FAIL' : 'WARN';
+    lines.push(`# Validation Report: ${result.pipelineName}`);
+    lines.push('');
+    lines.push(`**Overall**: ${statusLabel} | **Score**: ${result.score}/100 | **Duration**: ${result.totalDuration}ms`);
+    if (result.halted) {
+        lines.push(`**Halted at**: ${result.haltedAt} (blocking failure)`);
+    }
+    lines.push('');
+    // Step results table
+    lines.push('## Step Results');
+    lines.push('');
+    lines.push('| # | Step | Status | Score | Findings | Duration |');
+    lines.push('|---|------|--------|-------|----------|----------|');
+    for (let i = 0; i < result.steps.length; i++) {
+        const step = result.steps[i];
+        lines.push(`| ${i + 1} | ${step.stepName} | ${step.status.toUpperCase()} | ${step.score} | ${step.findings.length} | ${step.duration}ms |`);
+    }
+    lines.push('');
+    // Blockers
+    if (result.blockers.length > 0) {
+        lines.push('## Blockers');
+        lines.push('');
+        for (const blocker of result.blockers) {
+            lines.push(`- **${blocker.title}** (${blocker.severity}): ${blocker.description}`);
+            if (blocker.suggestion) {
+                lines.push(`  - Suggestion: ${blocker.suggestion}`);
+            }
+        }
+        lines.push('');
+    }
+    // Detailed findings
+    const allFindings = result.steps.flatMap(s => s.findings);
+    if (allFindings.length > 0) {
+        lines.push('## All Findings');
+        lines.push('');
+        for (const finding of allFindings) {
+            lines.push(`- [${finding.severity.toUpperCase()}] **${finding.title}**: ${finding.description}`);
+            if (finding.location)
+                lines.push(`  - Location: ${finding.location}`);
+            if (finding.suggestion)
+                lines.push(`  - Fix: ${finding.suggestion}`);
+        }
+    }
+    lines.push('');
+    lines.push(`_Generated: ${result.timestamp}_`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/validation/steps/requirements.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Requirements Validation Steps (BMAD-003)
+ *
+ * 13 structured validation steps for requirements documents,
+ * inspired by BMAD-METHOD's PRD validation.
+ */
+import type { ValidationStep } from '../pipeline.js';
+export declare const formatCheckStep: ValidationStep;
+export declare const completenessCheckStep: ValidationStep;
+export declare const investCriteriaStep: ValidationStep;
+export declare const smartAcceptanceStep: ValidationStep;
+export declare const testabilityScoreStep: ValidationStep;
+export declare const vagueTermStep: ValidationStep;
+export declare const informationDensityStep: ValidationStep;
+export declare const traceabilityCheckStep: ValidationStep;
+export declare const implementationLeakageStep: ValidationStep;
+export declare const domainComplianceStep: ValidationStep;
+export declare const dependencyAnalysisStep: ValidationStep;
+export declare const bddScenarioStep: ValidationStep;
+export declare const holisticQualityStep: ValidationStep;
+/**
+ * All 13 requirements validation steps in order.
+ */
+export declare const REQUIREMENTS_VALIDATION_STEPS: ValidationStep[];
+/**
+ * Create a requirements validation pipeline config.
+ */
+export declare function createRequirementsPipeline(options?: {
+    continueOnFailure?: boolean;
+    stepFilter?: string[];
+}): import('../pipeline.js').PipelineConfig;
+//# sourceMappingURL=requirements.d.ts.map