agentic-qe 3.7.21 → 3.8.0

package/dist/coordination/coherence-action-gate.js

@@ -0,0 +1,512 @@
+/**
+ * Coherence-Gated Agent Actions (Task 3.2, ADR-083)
+ *
+ * Evaluates agent actions through three stacked filters with
+ * heuristic scoring with CUSUM drift detection:
+ *   1. Structural filter: Action type familiarity and context completeness check
+ *   2. Shift filter: Confidence-risk alignment with CUSUM change detection
+ *   3. Evidence filter: Multiplicative context evidence accumulation score
+ *
+ * Decisions: PERMIT / DEFER / DENY
+ *   - PERMIT: all filters pass (scores above permit thresholds)
+ *   - DEFER: one or more filters marginal (needs human review)
+ *   - DENY: one or more filters clearly fail
+ *
+ * Advisory mode by default: logs decisions but does not block execution.
+ *
+ * TypeScript implementation (no native package exists for this —
+ * heuristic filters work well without native computation).
+ *
+ * @module coordination/coherence-action-gate
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+import { createLogger } from '../logging/logger-factory.js';
+import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
+const logger = createLogger('CoherenceActionGate');
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_THRESHOLDS = {
+    structuralPermit: 0.4,
+    structuralDeny: 0.2,
+    shiftPermit: 0.5,
+    shiftDeny: 0.25,
+    evidencePermit: 0.5,
+    evidenceDeny: 0.2,
+    combinedPermit: 0.5,
+    combinedDeny: 0.25,
+};
+/** Weights for combining filter scores */
+const FILTER_WEIGHTS = {
+    structural: 0.3,
+    shift: 0.35,
+    evidence: 0.35,
+};
+/** Risk level multipliers (higher risk = stricter evaluation) */
+const RISK_MULTIPLIERS = {
+    low: 1.0,
+    medium: 0.9,
+    high: 0.75,
+    critical: 0.6,
+};
+/** Maximum evaluations to retain for statistics */
+const MAX_EVALUATION_HISTORY = 1000;
+// ============================================================================
+// CoherenceActionGate Implementation
+// ============================================================================
+/**
+ * Three-filter coherence gate for agent action evaluation.
+ *
+ * Evaluates whether an agent action should proceed by running it through
+ * structural, shift, and evidence filters. Advisory mode by default.
+ *
+ * @example
+ * ```typescript
+ * const gate = new CoherenceActionGate();
+ * const evaluation = gate.evaluate({
+ *   type: 'generate-test',
+ *   domain: 'test-generation',
+ *   confidence: 0.85,
+ *   context: { filePath: 'src/service.ts' },
+ *   riskLevel: 'medium',
+ * });
+ * if (evaluation.decision === 'DENY') {
+ *   console.warn('Action denied:', evaluation.reasoning);
+ * }
+ * ```
+ */
+export class CoherenceActionGate {
+    thresholds;
+    advisoryMode;
+    nativeAvailable = null;
+    // Statistics tracking
+    evaluationHistory = [];
+    permitCount = 0;
+    deferCount = 0;
+    denyCount = 0;
+    totalCombinedScore = 0;
+    totalStructuralScore = 0;
+    totalShiftScore = 0;
+    totalEvidenceScore = 0;
+    // CUSUM state for shift detection
+    cusumHigh = 0;
+    cusumLow = 0;
+    cusumMean = 0.7; // Target mean confidence
+    cusumK = 0.05; // Allowance parameter (half the shift to detect)
+    cusumH = 4.0; // Decision threshold
+    cusumSampleCount = 0;
+    cusumAlertActive = false;
+    constructor(options) {
+        this.advisoryMode = options?.advisory ?? true;
+        this.thresholds = {
+            ...DEFAULT_THRESHOLDS,
+            ...options?.thresholds,
+        };
+    }
+    // ==========================================================================
+    // Core API
+    // ==========================================================================
+    /**
+     * Evaluate an agent action through the three-filter pipeline.
+     *
+     * @param action - The agent action to evaluate
+     * @returns Full evaluation with decision, scores, and reasoning
+     */
+    evaluate(action) {
+        const structuralScore = this.computeStructuralScore(action);
+        const shiftScore = this.computeShiftScore(action);
+        const evidenceScore = this.computeEvidenceScore(action);
+        const combinedScore = structuralScore * FILTER_WEIGHTS.structural +
+            shiftScore * FILTER_WEIGHTS.shift +
+            evidenceScore * FILTER_WEIGHTS.evidence;
+        // Apply risk multiplier
+        const riskMultiplier = RISK_MULTIPLIERS[action.riskLevel] ?? 1.0;
+        const adjustedCombined = combinedScore * riskMultiplier;
+        const decision = this.computeDecision(structuralScore, shiftScore, evidenceScore, adjustedCombined);
+        const reasoning = this.buildReasoning(action, decision, structuralScore, shiftScore, evidenceScore, adjustedCombined);
+        const evaluation = {
+            decision,
+            structuralScore,
+            shiftScore,
+            evidenceScore,
+            combinedScore: adjustedCombined,
+            reasoning,
+            advisory: this.advisoryMode,
+        };
+        this.recordEvaluation(evaluation);
+        logger.debug('Action gate evaluation', {
+            action: action.type,
+            domain: action.domain,
+            decision,
+            combinedScore: adjustedCombined,
+            advisory: this.advisoryMode,
+        });
+        return evaluation;
+    }
+    /**
+     * Get aggregate statistics for observability.
+     */
+    getStatistics() {
+        const total = this.evaluationHistory.length;
+        return {
+            totalEvaluations: total,
+            permitCount: this.permitCount,
+            deferCount: this.deferCount,
+            denyCount: this.denyCount,
+            averageCombinedScore: total > 0 ? this.totalCombinedScore / total : 0,
+            averageStructuralScore: total > 0 ? this.totalStructuralScore / total : 0,
+            averageShiftScore: total > 0 ? this.totalShiftScore / total : 0,
+            averageEvidenceScore: total > 0 ? this.totalEvidenceScore / total : 0,
+            advisoryMode: this.advisoryMode,
+        };
+    }
+    /**
+     * Update thresholds at runtime.
+     *
+     * @param config - Partial threshold overrides
+     */
+    configureThresholds(config) {
+        this.thresholds = {
+            ...this.thresholds,
+            ...config,
+        };
+        logger.info('Action gate thresholds updated', {
+            thresholds: this.thresholds,
+        });
+    }
+    /**
+     * Get the current threshold configuration.
+     */
+    getThresholds() {
+        return { ...this.thresholds };
+    }
+    /**
+     * Whether advisory mode is active.
+     */
+    isAdvisory() {
+        return this.advisoryMode;
+    }
+    /**
+     * Get the evaluation history (bounded).
+     */
+    getEvaluationHistory() {
+        return [...this.evaluationHistory];
+    }
+    /**
+     * Clear evaluation history and reset statistics.
+     */
+    resetStatistics() {
+        this.evaluationHistory = [];
+        this.permitCount = 0;
+        this.deferCount = 0;
+        this.denyCount = 0;
+        this.totalCombinedScore = 0;
+        this.totalStructuralScore = 0;
+        this.totalShiftScore = 0;
+        this.totalEvidenceScore = 0;
+        this.resetCusum();
+    }
+    /**
+     * Reset CUSUM change detection state.
+     */
+    resetCusum() {
+        this.cusumHigh = 0;
+        this.cusumLow = 0;
+        this.cusumAlertActive = false;
+        this.cusumSampleCount = 0;
+    }
+    // ==========================================================================
+    // Filter 1: Structural
+    // ==========================================================================
+    /**
+     * Structural filter: Action type familiarity and context completeness check.
+     *
+     * Considers:
+     * - Action type familiarity (known vs unknown action types)
+     * - Domain alignment (is the action appropriate for this domain?)
+     * - Context completeness (does the action have sufficient context?)
+     *
+     * Higher score = better structural fit.
+     */
+    computeStructuralScore(action) {
+        let score = 0.5; // Baseline
+        // Action type familiarity - known action types score higher
+        const knownActionTypes = [
+            'generate-test', 'modify-code', 'analyze-coverage',
+            'scan-security', 'assess-quality', 'validate-contracts',
+            'test-accessibility', 'execute-tests', 'index-code',
+            'predict-defects', 'validate-requirements', 'deploy',
+            'run-chaos', 'optimize-learning',
+        ];
+        if (knownActionTypes.includes(action.type)) {
+            score += 0.2;
+        }
+        // Domain alignment - check if context references this domain
+        const contextStr = JSON.stringify(action.context).toLowerCase();
+        if (contextStr.includes(action.domain.toLowerCase())) {
+            score += 0.15;
+        }
+        // Context completeness - more context keys = more structural support
+        const contextKeys = Object.keys(action.context);
+        if (contextKeys.length >= 3) {
+            score += 0.15;
+        }
+        else if (contextKeys.length >= 1) {
+            score += 0.05;
+        }
+        return Math.min(Math.max(score, 0), 1);
+    }
+    // ==========================================================================
+    // Filter 2: Shift Detection
+    // ==========================================================================
+    /**
+     * Shift filter: Confidence-risk alignment with CUSUM change detection.
+     *
+     * Considers:
+     * - Confidence level (low confidence suggests distributional shift)
+     * - Risk level alignment (high risk with low confidence = shift)
+     * - Context consistency (presence of contradictory signals)
+     * - CUSUM cumulative sum control chart for persistent drift detection
+     *
+     * Higher score = less distributional shift detected.
+     */
+    computeShiftScore(action) {
+        let score = action.confidence; // Start with agent's own confidence
+        // Risk-confidence alignment penalty
+        // High risk actions with low confidence suggest distributional shift
+        const riskValues = {
+            low: 0.25, medium: 0.5, high: 0.75, critical: 1.0,
+        };
+        const riskValue = riskValues[action.riskLevel] ?? 0.5;
+        const riskConfidenceGap = Math.max(0, riskValue - action.confidence);
+        // Penalize when risk is high but confidence is low
+        score -= riskConfidenceGap * 0.3;
+        // Context staleness check - look for timestamp or freshness signals
+        const context = action.context;
+        if (context.stale === true || context.outdated === true) {
+            score -= 0.3;
+        }
+        // If context has explicit shift markers
+        if (context.distributionShift === true || context.contextChanged === true) {
+            score -= 0.4;
+        }
+        // CUSUM change detection
+        this.cusumSampleCount++;
+        const x = action.confidence;
+        this.cusumHigh = Math.max(0, this.cusumHigh + (x - this.cusumMean) - this.cusumK);
+        this.cusumLow = Math.max(0, this.cusumLow - (x - this.cusumMean) - this.cusumK);
+        if (this.cusumHigh > this.cusumH || this.cusumLow > this.cusumH) {
+            // Persistent drift detected
+            score -= 0.2;
+            if (!this.cusumAlertActive) {
+                this.cusumAlertActive = true;
+                logger.warn('CUSUM shift detected', { cusumHigh: this.cusumHigh, cusumLow: this.cusumLow });
+            }
+        }
+        else {
+            this.cusumAlertActive = false;
+        }
+        return Math.min(Math.max(score, 0), 1);
+    }
+    // ==========================================================================
+    // Filter 3: Evidence (Multiplicative Accumulation)
+    // ==========================================================================
+    /**
+     * Evidence filter: Multiplicative context evidence accumulation score.
+     *
+     * Uses multiplicative accumulation where each piece of evidence
+     * compounds on the previous score. Multiple negative signals compound
+     * more aggressively than additive scoring.
+     *
+     * Considers:
+     * - Supporting evidence in context (test results, coverage data, etc.)
+     * - Evidence against (errors, failures, warnings)
+     * - Risk-level specific evidence requirements
+     *
+     * Higher score = more evidence supporting the action.
+     */
+    computeEvidenceScore(action) {
+        let evidence = 0.5; // Start at neutral
+        const context = action.context;
+        // Positive evidence signals - multiplicative accumulation
+        const positiveKeys = [
+            'testResults', 'coverageData', 'securityScan',
+            'qualityReport', 'peerReview', 'analysisResult',
+            'validationPassed', 'precedent', 'historicalSuccess',
+        ];
+        for (const key of positiveKeys) {
+            if (context[key] !== undefined && context[key] !== null) {
+                evidence *= (1 + 0.15); // Each positive signal boosts by 15%
+            }
+        }
+        // Negative evidence signals - multiplicative reduction
+        const negativeKeys = [
+            'errors', 'failures', 'warnings', 'regressions',
+            'conflictingResults', 'noTestCoverage',
+        ];
+        for (const key of negativeKeys) {
+            if (context[key] !== undefined && context[key] !== null) {
+                evidence *= (1 - 0.18); // Each negative signal reduces by 18%
+            }
+        }
+        // Action-specific evidence requirements
+        if (action.riskLevel === 'critical' || action.riskLevel === 'high') {
+            // High-risk actions need more evidence - raise the bar
+            if (!context.testResults && !context.peerReview) {
+                evidence -= 0.15;
+            }
+        }
+        // Bonus for explicit evidence count
+        if (typeof context.evidenceCount === 'number') {
+            const evidenceCount = context.evidenceCount;
+            evidence += Math.min(evidenceCount * 0.05, 0.2);
+        }
+        return Math.min(Math.max(evidence, 0), 1);
+    }
+    // ==========================================================================
+    // Decision Logic
+    // ==========================================================================
+    /**
+     * Determine the final PERMIT/DEFER/DENY decision from filter scores.
+     *
+     * Logic:
+     * - DENY if any individual filter is below its deny threshold
+     * - DENY if combined score is below combined deny threshold
+     * - PERMIT if all filters are above their permit thresholds AND
+     *   combined score is above combined permit threshold
+     * - DEFER otherwise (marginal - needs human review)
+     */
+    computeDecision(structural, shift, evidence, combined) {
+        // Check for clear DENY
+        if (structural < this.thresholds.structuralDeny)
+            return 'DENY';
+        if (shift < this.thresholds.shiftDeny)
+            return 'DENY';
+        if (evidence < this.thresholds.evidenceDeny)
+            return 'DENY';
+        if (combined < this.thresholds.combinedDeny)
+            return 'DENY';
+        // Check for clear PERMIT
+        if (structural >= this.thresholds.structuralPermit &&
+            shift >= this.thresholds.shiftPermit &&
+            evidence >= this.thresholds.evidencePermit &&
+            combined >= this.thresholds.combinedPermit) {
+            return 'PERMIT';
+        }
+        // Marginal - needs review
+        return 'DEFER';
+    }
+    // ==========================================================================
+    // Reasoning & Statistics
+    // ==========================================================================
+    /**
+     * Build a human-readable reasoning string.
+     */
+    buildReasoning(action, decision, structural, shift, evidence, combined) {
+        const parts = [];
+        parts.push(`Decision: ${decision} for ${action.type} (${action.domain}).`);
+        parts.push(`Scores: structural=${structural.toFixed(2)}, ` +
+            `shift=${shift.toFixed(2)}, evidence=${evidence.toFixed(2)}, ` +
+            `combined=${combined.toFixed(2)}.`);
+        if (decision === 'DENY') {
+            if (structural < this.thresholds.structuralDeny) {
+                parts.push('Structural filter failed: action does not fit codebase graph.');
+            }
+            if (shift < this.thresholds.shiftDeny) {
+                parts.push('Shift filter failed: significant context distribution shift detected.');
+            }
+            if (evidence < this.thresholds.evidenceDeny) {
+                parts.push('Evidence filter failed: insufficient evidence to justify action.');
+            }
+            if (combined < this.thresholds.combinedDeny) {
+                parts.push('Combined score below minimum threshold.');
+            }
+        }
+        else if (decision === 'DEFER') {
+            const marginalFilters = [];
+            if (structural < this.thresholds.structuralPermit)
+                marginalFilters.push('structural');
+            if (shift < this.thresholds.shiftPermit)
+                marginalFilters.push('shift');
+            if (evidence < this.thresholds.evidencePermit)
+                marginalFilters.push('evidence');
+            if (marginalFilters.length > 0) {
+                parts.push(`Marginal filters: ${marginalFilters.join(', ')}. Human review recommended.`);
+            }
+        }
+        if (this.advisoryMode) {
+            parts.push('(Advisory mode: decision logged only, not enforced.)');
+        }
+        return parts.join(' ');
+    }
+    /**
+     * Record an evaluation for statistics tracking.
+     */
+    recordEvaluation(evaluation) {
+        this.evaluationHistory.push(evaluation);
+        if (this.evaluationHistory.length > MAX_EVALUATION_HISTORY) {
+            this.evaluationHistory = this.evaluationHistory.slice(-MAX_EVALUATION_HISTORY);
+        }
+        this.totalCombinedScore += evaluation.combinedScore;
+        this.totalStructuralScore += evaluation.structuralScore;
+        this.totalShiftScore += evaluation.shiftScore;
+        this.totalEvidenceScore += evaluation.evidenceScore;
+        switch (evaluation.decision) {
+            case 'PERMIT':
+                this.permitCount++;
+                break;
+            case 'DEFER':
+                this.deferCount++;
+                break;
+            case 'DENY':
+                this.denyCount++;
+                break;
+        }
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a CoherenceActionGate instance.
+ *
+ * @param options - Optional configuration
+ * @returns A new CoherenceActionGate instance
+ */
+export function createCoherenceActionGate(options) {
+    return new CoherenceActionGate(options);
+}
+// ============================================================================
+// Task Executor Integration Helper
+// ============================================================================
+/**
+ * Evaluate a task execution action through the coherence gate.
+ *
+ * This is the integration point called by the task executor. It checks
+ * the feature flag, creates an AgentAction from task metadata, and
+ * returns the evaluation result.
+ *
+ * @param taskType - The type of task being executed
+ * @param domain - The domain the task targets
+ * @param confidence - Confidence level (0-1)
+ * @param riskLevel - Risk classification
+ * @param context - Additional context
+ * @param gate - Optional pre-existing gate instance (for reuse)
+ * @returns The gate evaluation, or null if the feature flag is off
+ */
+export function evaluateTaskAction(taskType, domain, confidence, riskLevel, context, gate) {
+    const flags = getRuVectorFeatureFlags();
+    if (!flags.useCoherenceActionGate) {
+        return null;
+    }
+    const effectiveGate = gate ?? new CoherenceActionGate();
+    const action = {
+        type: taskType,
+        domain,
+        confidence,
+        context,
+        riskLevel,
+    };
+    return effectiveGate.evaluate(action);
+}
+//# sourceMappingURL=coherence-action-gate.js.map

package/dist/coordination/index.d.ts

@@ -33,4 +33,8 @@ export type { FleetId, FederatedService, FederatedMessage, FederatedMessageType,
 export { DynamicScaler, createDynamicScaler, DEFAULT_SCALING_POLICY, DEFAULT_DYNAMIC_SCALING_CONFIG, } from './dynamic-scaling';
 export type { WorkloadMetrics, ScalingDecision, ScalingAction, ScalingPolicy, ScalingEvent, ScalerStats, DynamicScalingConfig, ScaleExecutor, } from './dynamic-scaling';
 export * from './mixins';
+export * from './behavior-tree';
+export type { BehaviorTreeExecutionResult } from './workflow-orchestrator';
+export { ReasoningQEC, createReasoningQEC, processReasoning, DEFAULT_QEC_CONFIG, } from './reasoning-qec';
+export type { ReasoningProblem, ReasoningPath, ReasoningStep, Syndrome, CorrectedReasoning, CorrectionEntry, ValidationResult, ValidationIssue, ReasoningQECConfig, } from './reasoning-qec';
 //# sourceMappingURL=index.d.ts.map

package/dist/coordination/index.js

@@ -93,4 +93,12 @@ export { DynamicScaler, createDynamicScaler, DEFAULT_SCALING_POLICY, DEFAULT_DYN
 // Coordination Mixins (CONSENSUS-MIXIN-001)
 // ============================================================================
 export * from './mixins';
+// ============================================================================
+// Behavior Tree Orchestration (Task 4.4: RuVector Integration)
+// ============================================================================
+export * from './behavior-tree';
+// ============================================================================
+// Reasoning QEC (Task 4.5: Quantum Error Correction for AI Reasoning)
+// ============================================================================
+export { ReasoningQEC, createReasoningQEC, processReasoning, DEFAULT_QEC_CONFIG, } from './reasoning-qec';
 //# sourceMappingURL=index.js.map