agentic-qe 3.9.29 → 3.9.31

package/dist/integrations/agentic-flow/onnx-embeddings/embedding-generator.js

@@ -7,7 +7,6 @@
  * @module onnx-embeddings/embedding-generator
  */
 import { EmbeddingModel, EmbeddingError, EmbeddingErrorType } from './types.js';
-import { secureRandom } from '../../../shared/utils/crypto-random.js';
 /**
  * LRU Cache for embeddings
  */
@@ -84,23 +83,27 @@ export class EmbeddingGenerator {
             return;
         }
         try {
-            // In production, this would call the MCP embeddings_init tool
-            // For now, we create a mock that bridges to the real implementation
+            // Issue #469: the previous mock implementation generated random vectors
+            // per call, which made cosine similarity meaningless. We now route
+            // through the shared @xenova/transformers pipeline (all-MiniLM-L6-v2)
+            // via real-embeddings.computeRealEmbedding, so identical text yields
+            // identical vectors and semantically-related text yields high cosine
+            // similarity.
+            const { computeRealEmbedding } = await import('../../../learning/real-embeddings.js');
             this.onnxRuntime = {
-                generateEmbedding: async (text, model) => {
-                    // Bridge to agentic-flow MCP tool: embeddings_generate
-                    // This would call: mcp__claude-flow__embeddings_generate({ text, normalize: true })
-                    // Mock implementation - in production, this calls ONNX
-                    const dimensions = model === EmbeddingModel.MINI_LM_L6 ? 384 : 768;
-                    const vector = new Array(dimensions).fill(0).map(() => secureRandom() * 2 - 1);
-                    // Normalize if configured
+                generateEmbedding: async (text, _model) => {
+                    // computeRealEmbedding already normalizes (pooling: mean, normalize: true)
+                    // and returns a 384-dimensional vector for MiniLM-L6-v2. We honor the
+                    // generator's `config.normalize` flag for parity with the previous mock.
+                    const vector = await computeRealEmbedding(text);
                     if (this.config.normalize) {
                         const norm = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
-                        return vector.map(val => val / norm);
+                        if (norm > 0)
+                            return vector.map(val => val / norm);
                     }
                     return vector;
                 },
-                isAvailable: () => true
+                isAvailable: () => true,
             };
             this.isInitialized = true;
         }

package/dist/integrations/n8n/agent-factory.js

@@ -7,10 +7,13 @@
  * IMPORTANT: This requires v2 to be built first (`npm run build` in root)
  */
 import { randomUUID } from 'crypto';
-import { resolve } from 'path';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { existsSync } from 'fs';
 import { N8N_TO_V3_DOMAIN_MAP } from './workflow-mapper.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 // ============================================================================
 // Minimal MemoryStore Implementation (for V2 agent compatibility)
 // ============================================================================

package/dist/integrations/n8n/n8n-adapter.js

@@ -5,7 +5,10 @@
  * Provides workflow analysis, domain routing, and agent coordination.
  */
 import { existsSync } from 'fs';
-import { resolve } from 'path';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 import { N8N_TO_V3_DOMAIN_MAP, analyzeWorkflowForDomains, getAllDomains, getPrimaryDomain, } from './workflow-mapper.js';
 // ============================================================================
 // Default Configuration

package/dist/kernel/interfaces.d.ts

@@ -297,6 +297,18 @@ export interface KernelConfig {
      * can set false to skip the plugin-load cost.
      */
     enableExperienceBridge?: boolean;
+    /**
+     * Whether to start the DreamScheduler during initialize() (ADR-094).
+     * When true (default), dream cycles run inside the long-lived kernel
+     * process instead of hook subprocesses. Hook subprocesses keep only
+     * `incrementDreamExperience` — the kernel-side scheduler is the
+     * authoritative trigger.
+     *
+     * Long-lived processes (MCP server, daemon) want this true.
+     * Short-lived CLI commands that complete in <1s can set false to skip
+     * DreamEngine init cost.
+     */
+    enableDreamScheduler?: boolean;
 }
 /**
  * Event middleware interface for anti-drift and other event processing (ADR-060)

package/dist/kernel/kernel.d.ts

@@ -21,6 +21,7 @@ export declare class QEKernelImpl implements QEKernel {
     private _initialized;
     private _loopTracker;
     private _experienceBridge?;
+    private _dreamScheduler?;
     constructor(config?: Partial<KernelConfig>);
     get eventBus(): EventBus;
     get coordinator(): AgentCoordinator;

package/dist/kernel/kernel.js

@@ -19,6 +19,8 @@ import * as fs from 'fs';
 import { PluginLifecycleManager } from '../plugins/lifecycle';
 import { PluginCache } from '../plugins/cache';
 import { CapturedExperienceBridge } from '../bridge/captured-experience-bridge.js';
+import { DreamScheduler } from '../learning/dream/dream-scheduler.js';
+import { createDreamEngine } from '../learning/dream/dream-engine.js';
 // Import domain plugin factories
 import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
 import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
@@ -69,6 +71,10 @@ const DEFAULT_CONFIG = {
     // working out of the box. CLI commands that don't need event-driven
     // domain reactions opt out by passing `enableExperienceBridge: false`.
     enableExperienceBridge: true,
+    // ADR-094: kernel-side dream cycles. Defaults match the bridge — long-lived
+    // processes start the scheduler so dream cycles run in the kernel rather
+    // than inside hook subprocesses. Short-lived CLIs opt out.
+    enableDreamScheduler: true,
 };
 export class QEKernelImpl {
     _eventBus;
@@ -83,6 +89,10 @@ export class QEKernelImpl {
     // Issue #479: drains captured_experiences into the eventBus so hook-driven
     // activity reaches the 13 domain plugins' subscribeToEvents() handlers.
     _experienceBridge;
+    // ADR-094: kernel-side dream cycles. Replaces the in-hook
+    // checkAndTriggerDream path so 10-second SQLite write transactions move
+    // out of short-lived hook subprocesses into the long-lived kernel.
+    _dreamScheduler;
     constructor(config = {}) {
         this._config = { ...DEFAULT_CONFIG, ...config };
         this._startTime = new Date();
@@ -262,9 +272,56 @@ export class QEKernelImpl {
                 this._experienceBridge = undefined;
             }
         }
+        // ADR-094: Start the kernel-side DreamScheduler so dream cycles run in
+        // the long-lived process. Hook subprocesses no longer trigger dreams —
+        // they only bump the experience counter (incrementDreamExperience).
+        // The scheduler subscribes to its own event triggers (quality-gate
+        // failure, domain milestones) and runs time-based dreams on its own
+        // cadence (default 1h). DreamEngine.ensureConceptsLoaded() auto-loads
+        // patterns from qe_patterns, so no separate ReasoningBank is needed here.
+        if (this._config.enableDreamScheduler !== false) {
+            try {
+                const dreamEngine = createDreamEngine({
+                    maxDurationMs: 10_000,
+                    minConceptsRequired: 3,
+                });
+                await dreamEngine.initialize();
+                this._dreamScheduler = new DreamScheduler({
+                    dreamEngine,
+                    eventBus: this._eventBus,
+                    memoryBackend: this._memory,
+                });
+                await this._dreamScheduler.initialize();
+                this._dreamScheduler.start();
+            }
+            catch (err) {
+                console.warn('[QEKernel] DreamScheduler failed to start:', err instanceof Error ? err.message : err);
+                // Tear down anything we partially constructed so we don't leak a
+                // half-initialized scheduler (e.g., engine init succeeded but
+                // scheduler.start threw).
+                if (this._dreamScheduler) {
+                    try {
+                        await this._dreamScheduler.dispose();
+                    }
+                    catch { /* swallow during cleanup */ }
+                }
+                this._dreamScheduler = undefined;
+            }
+        }
         this._initialized = true;
     }
     async dispose() {
+        // ADR-094: Stop the dream scheduler first so a dream-in-progress doesn't
+        // try to write to a disposed memory backend.
+        if (this._dreamScheduler) {
+            try {
+                await this._dreamScheduler.dispose();
+            }
+            catch (err) {
+                console.warn('[QEKernel] DreamScheduler dispose failed:', err instanceof Error ? err.message : err);
+            }
+            this._dreamScheduler = undefined;
+        }
         // Stop the bridge first so it doesn't try to publish to a disposed bus.
         if (this._experienceBridge) {
             await this._experienceBridge.stop();

package/dist/kernel/unified-memory-schemas.d.ts

@@ -17,6 +17,6 @@ export declare const QE_PATTERNS_SCHEMA = "\n  -- QE Patterns table (unified fro
 export declare const MINCUT_SCHEMA = "\n  -- MinCut Graph Snapshots (ADR-047)\n  CREATE TABLE IF NOT EXISTS mincut_snapshots (\n    id TEXT PRIMARY KEY,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    vertex_count INTEGER NOT NULL,\n    edge_count INTEGER NOT NULL,\n    total_weight REAL NOT NULL DEFAULT 0.0,\n    is_connected INTEGER NOT NULL DEFAULT 1,\n    component_count INTEGER NOT NULL DEFAULT 1,\n    vertices_json TEXT NOT NULL,\n    edges_json TEXT NOT NULL,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n\n  -- MinCut History (time-series MinCut values)\n  CREATE TABLE IF NOT EXISTS mincut_history (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    mincut_value REAL NOT NULL,\n    vertex_count INTEGER NOT NULL,\n    edge_count INTEGER NOT NULL,\n    algorithm TEXT NOT NULL DEFAULT 'weighted-degree',\n    duration_ms INTEGER,\n    snapshot_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Weak Vertices (detected bottlenecks)\n  CREATE TABLE IF NOT EXISTS mincut_weak_vertices (\n    id TEXT PRIMARY KEY,\n    vertex_id TEXT NOT NULL,\n    weighted_degree REAL NOT NULL,\n    risk_score REAL NOT NULL,\n    reason TEXT NOT NULL,\n    domain TEXT,\n    vertex_type TEXT NOT NULL,\n    suggestions_json TEXT,\n    detected_at TEXT NOT NULL DEFAULT (datetime('now')),\n    resolved_at TEXT,\n    snapshot_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Alerts\n  CREATE TABLE IF NOT EXISTS mincut_alerts (\n    id TEXT PRIMARY KEY,\n    severity TEXT NOT NULL,\n    message TEXT NOT NULL,\n    mincut_value REAL NOT NULL,\n    threshold REAL NOT NULL,\n    affected_vertices_json TEXT,\n    remediations_json TEXT,\n    acknowledged INTEGER DEFAULT 0,\n    acknowledged_at TEXT,\n    acknowledged_by TEXT,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n\n  -- MinCut Healing Actions (self-healing history)\n  CREATE TABLE IF NOT EXISTS mincut_healing_actions (\n    id TEXT PRIMARY KEY,\n    action_type TEXT NOT NULL,\n    action_params_json TEXT NOT NULL,\n    success INTEGER NOT NULL,\n    mincut_before REAL NOT NULL,\n    mincut_after REAL NOT NULL,\n    improvement REAL NOT NULL DEFAULT 0.0,\n    error_message TEXT,\n    duration_ms INTEGER NOT NULL,\n    triggered_by TEXT,\n    snapshot_before_id TEXT,\n    snapshot_after_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_before_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL,\n    FOREIGN KEY (snapshot_after_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Strange Loop Observations (P1: self-organizing)\n  CREATE TABLE IF NOT EXISTS mincut_observations (\n    id TEXT PRIMARY KEY,\n    iteration INTEGER NOT NULL,\n    mincut_value REAL NOT NULL,\n    weak_vertex_count INTEGER NOT NULL DEFAULT 0,\n    weak_vertices_json TEXT,\n    snapshot_id TEXT,\n    prediction_json TEXT,\n    actual_vs_predicted_diff REAL,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Indexes\n  CREATE INDEX IF NOT EXISTS idx_mincut_history_timestamp ON mincut_history(timestamp DESC);\n  CREATE INDEX IF NOT EXISTS idx_mincut_history_value ON mincut_history(mincut_value);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_vertex ON mincut_weak_vertices(vertex_id);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_risk ON mincut_weak_vertices(risk_score DESC);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_resolved ON mincut_weak_vertices(resolved_at);\n  CREATE INDEX IF NOT EXISTS idx_mincut_alerts_severity ON mincut_alerts(severity);\n  CREATE INDEX IF NOT EXISTS idx_mincut_alerts_ack ON mincut_alerts(acknowledged);\n  CREATE INDEX IF NOT EXISTS idx_mincut_healing_type ON mincut_healing_actions(action_type);\n  CREATE INDEX IF NOT EXISTS idx_mincut_healing_success ON mincut_healing_actions(success);\n  CREATE INDEX IF NOT EXISTS idx_mincut_observations_iter ON mincut_observations(iteration);\n";
 export declare const SONA_PATTERNS_SCHEMA = "\n  -- SONA Patterns table (ADR-046: Pattern Persistence for Neural Backbone)\n  CREATE TABLE IF NOT EXISTS sona_patterns (\n    id TEXT PRIMARY KEY,\n    type TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    state_embedding BLOB,\n    action_embedding BLOB,\n    action_type TEXT NOT NULL,\n    action_value TEXT,\n    outcome_reward REAL NOT NULL DEFAULT 0.0,\n    outcome_success INTEGER NOT NULL DEFAULT 0,\n    outcome_quality REAL NOT NULL DEFAULT 0.0,\n    confidence REAL DEFAULT 0.5,\n    usage_count INTEGER DEFAULT 0,\n    success_count INTEGER DEFAULT 0,\n    failure_count INTEGER DEFAULT 0,\n    metadata TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now')),\n    last_used_at TEXT\n  );\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_type ON sona_patterns(type);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_domain ON sona_patterns(domain);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_confidence ON sona_patterns(confidence DESC);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_updated ON sona_patterns(updated_at DESC);\n";
 export declare const WITNESS_CHAIN_SCHEMA = "\n  -- Witness Chain (ADR-070: Cryptographic audit trail for QE decisions)\n  CREATE TABLE IF NOT EXISTS witness_chain (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    prev_hash TEXT NOT NULL,\n    action_hash TEXT NOT NULL,\n    action_type TEXT NOT NULL,\n    action_data TEXT,\n    timestamp TEXT NOT NULL,\n    actor TEXT NOT NULL\n  );\n  CREATE INDEX IF NOT EXISTS idx_witness_action_type ON witness_chain(action_type);\n  CREATE INDEX IF NOT EXISTS idx_witness_timestamp ON witness_chain(timestamp);\n";
-export declare const FEEDBACK_SCHEMA = "\n  -- Test outcomes (ADR-023: Quality Feedback Loop)\n  CREATE TABLE IF NOT EXISTS test_outcomes (\n    id TEXT PRIMARY KEY,\n    test_id TEXT NOT NULL,\n    test_name TEXT NOT NULL,\n    generated_by TEXT NOT NULL,\n    pattern_id TEXT,\n    framework TEXT NOT NULL,\n    language TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    passed INTEGER NOT NULL,\n    error_message TEXT,\n    coverage_lines REAL DEFAULT 0,\n    coverage_branches REAL DEFAULT 0,\n    coverage_functions REAL DEFAULT 0,\n    mutation_score REAL,\n    execution_time_ms REAL NOT NULL,\n    flaky INTEGER DEFAULT 0,\n    flakiness_score REAL,\n    maintainability_score REAL NOT NULL,\n    complexity REAL,\n    lines_of_code INTEGER,\n    assertion_count INTEGER,\n    file_path TEXT,\n    source_file_path TEXT,\n    metadata_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_pattern ON test_outcomes(pattern_id);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_agent ON test_outcomes(generated_by);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);\n\n  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json)\n  CREATE TABLE IF NOT EXISTS routing_outcomes (\n    id TEXT PRIMARY KEY,\n    task_json TEXT NOT NULL,\n    decision_json TEXT NOT NULL,\n    used_agent TEXT NOT NULL,\n    followed_recommendation INTEGER NOT NULL,\n    success INTEGER NOT NULL,\n    quality_score REAL NOT NULL,\n    duration_ms REAL NOT NULL,\n    error TEXT,\n    model_tier TEXT,\n    advisor_consultation_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);\n\n  -- Coverage sessions (ADR-023: Coverage Learning)\n  CREATE TABLE IF NOT EXISTS coverage_sessions (\n    id TEXT PRIMARY KEY,\n    target_path TEXT NOT NULL,\n    agent_id TEXT NOT NULL,\n    technique TEXT NOT NULL,\n    before_lines REAL DEFAULT 0,\n    before_branches REAL DEFAULT 0,\n    before_functions REAL DEFAULT 0,\n    after_lines REAL DEFAULT 0,\n    after_branches REAL DEFAULT 0,\n    after_functions REAL DEFAULT 0,\n    tests_generated INTEGER DEFAULT 0,\n    tests_passed INTEGER DEFAULT 0,\n    gaps_json TEXT,\n    duration_ms REAL NOT NULL,\n    started_at TEXT NOT NULL,\n    completed_at TEXT NOT NULL,\n    context_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_technique ON coverage_sessions(technique);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_agent ON coverage_sessions(agent_id);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_created ON coverage_sessions(created_at);\n";
+export declare const FEEDBACK_SCHEMA = "\n  -- Test outcomes (ADR-023: Quality Feedback Loop)\n  CREATE TABLE IF NOT EXISTS test_outcomes (\n    id TEXT PRIMARY KEY,\n    test_id TEXT NOT NULL,\n    test_name TEXT NOT NULL,\n    generated_by TEXT NOT NULL,\n    pattern_id TEXT,\n    framework TEXT NOT NULL,\n    language TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    passed INTEGER NOT NULL,\n    error_message TEXT,\n    coverage_lines REAL DEFAULT 0,\n    coverage_branches REAL DEFAULT 0,\n    coverage_functions REAL DEFAULT 0,\n    mutation_score REAL,\n    execution_time_ms REAL NOT NULL,\n    flaky INTEGER DEFAULT 0,\n    flakiness_score REAL,\n    maintainability_score REAL NOT NULL,\n    complexity REAL,\n    lines_of_code INTEGER,\n    assertion_count INTEGER,\n    file_path TEXT,\n    source_file_path TEXT,\n    metadata_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_pattern ON test_outcomes(pattern_id);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_agent ON test_outcomes(generated_by);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);\n\n  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json,\n  -- ADR-095: exploration / criticality / q_weight for \u03B5-greedy routing telemetry)\n  CREATE TABLE IF NOT EXISTS routing_outcomes (\n    id TEXT PRIMARY KEY,\n    task_json TEXT NOT NULL,\n    decision_json TEXT NOT NULL,\n    used_agent TEXT NOT NULL,\n    followed_recommendation INTEGER NOT NULL,\n    success INTEGER NOT NULL,\n    quality_score REAL NOT NULL,\n    duration_ms REAL NOT NULL,\n    error TEXT,\n    model_tier TEXT,\n    advisor_consultation_json TEXT,\n    -- ADR-095: routing exploration telemetry\n    exploration INTEGER NOT NULL DEFAULT 0,\n    criticality REAL,\n    q_weight REAL,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_exploration ON routing_outcomes(exploration);\n\n  -- Coverage sessions (ADR-023: Coverage Learning)\n  CREATE TABLE IF NOT EXISTS coverage_sessions (\n    id TEXT PRIMARY KEY,\n    target_path TEXT NOT NULL,\n    agent_id TEXT NOT NULL,\n    technique TEXT NOT NULL,\n    before_lines REAL DEFAULT 0,\n    before_branches REAL DEFAULT 0,\n    before_functions REAL DEFAULT 0,\n    after_lines REAL DEFAULT 0,\n    after_branches REAL DEFAULT 0,\n    after_functions REAL DEFAULT 0,\n    tests_generated INTEGER DEFAULT 0,\n    tests_passed INTEGER DEFAULT 0,\n    gaps_json TEXT,\n    duration_ms REAL NOT NULL,\n    started_at TEXT NOT NULL,\n    completed_at TEXT NOT NULL,\n    context_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_technique ON coverage_sessions(technique);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_agent ON coverage_sessions(agent_id);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_created ON coverage_sessions(created_at);\n";
 export declare const STATS_TABLES: string[];
 //# sourceMappingURL=unified-memory-schemas.d.ts.map

package/dist/kernel/unified-memory-schemas.js

@@ -540,7 +540,8 @@ export const FEEDBACK_SCHEMA = `
   CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);
   CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);
 
-  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json)
+  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json,
+  -- ADR-095: exploration / criticality / q_weight for ε-greedy routing telemetry)
   CREATE TABLE IF NOT EXISTS routing_outcomes (
     id TEXT PRIMARY KEY,
     task_json TEXT NOT NULL,
@@ -553,11 +554,16 @@ export const FEEDBACK_SCHEMA = `
     error TEXT,
     model_tier TEXT,
     advisor_consultation_json TEXT,
+    -- ADR-095: routing exploration telemetry
+    exploration INTEGER NOT NULL DEFAULT 0,
+    criticality REAL,
+    q_weight REAL,
     created_at TEXT DEFAULT (datetime('now'))
   );
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);
+  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_exploration ON routing_outcomes(exploration);
 
   -- Coverage sessions (ADR-023: Coverage Learning)
   CREATE TABLE IF NOT EXISTS coverage_sessions (

package/dist/learning/agent-routing.d.ts

@@ -1,6 +1,7 @@
 /**
  * Agentic QE v3 - Agent Routing
  * ADR-021: QE ReasoningBank for Pattern Learning
+ * ADR-095: ε-greedy exploration with Q-value blending and mincut safety gate
  *
  * Static agent capability mapping and routing score calculation
  * used by QEReasoningBank.routeTask().
@@ -22,11 +23,28 @@ export interface AgentCapabilityProfile {
 export declare const AGENT_CAPABILITIES: Record<string, AgentCapabilityProfile>;
 /**
  * Scored agent with reasoning trace.
+ *
+ * ADR-095 telemetry fields (all optional, populated only when the
+ * corresponding signal source is wired):
+ *   - `staticScore`: the pre-blend score (domain + capability + perf + …)
+ *   - `qWeight`, `qValue`: when Q-table data was available
+ *   - `exploration`: true if this agent was promoted to position 0 by the
+ *     ε-greedy policy rather than scored to the top deterministically
  */
 export interface ScoredAgent {
     agent: string;
     score: number;
     reasoning: string[];
+    /** ADR-095: pre-blend static score for retrospective explainability */
+    staticScore?: number;
+    /** ADR-095: Q-value influence (0..MAX_Q_WEIGHT) on the final score */
+    qWeight?: number;
+    /** ADR-095: raw q_value from rl_q_values, for telemetry */
+    qValue?: number;
+    /** ADR-095: number of (state_key, action_key) visits behind the Q value */
+    qVisits?: number;
+    /** ADR-095: true when ε-greedy promoted this agent over the greedy winner */
+    exploration?: boolean;
 }
 /**
  * Routing weight configuration.
@@ -38,6 +56,114 @@ export interface RoutingWeights {
     /** Weight for language match boost (default: 1.0) */
     language?: number;
 }
+/**
+ * Maximum Q-value influence on the final score.
+ *
+ * 0.4 means a fully-mature Q-value can move the score by up to ±0.2 (since
+ * normalizedQ ranges over (0, 1) and the static contribution clamps the
+ * upper bound). This is intentionally bounded so Q-values inform rather
+ * than override the static features.
+ *
+ * Tuning: post-deploy telemetry will tell us whether agents are actually
+ * being separated by Q-values. If the avg `q_weight` in routing_outcomes
+ * climbs but quality_score doesn't improve, this constant is too high.
+ */
+export declare const MAX_Q_WEIGHT = 0.4;
+/**
+ * Number of (state_key, action_key) visits at which qWeight saturates at
+ * MAX_Q_WEIGHT. Below this, qWeight ramps linearly from 0.
+ *
+ * 20 visits at the default 30-min worker tick + typical session cadence
+ * implies ~1 week of activity before a (state, agent) pair drives the
+ * decision. Adjust downward if cold-start latency proves problematic.
+ */
+export declare const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * Q-value lookup callback supplied by the caller (QEReasoningBank.routeTask).
+ * Returns undefined when the (stateKey, agentType) pair has no recorded
+ * Q-value yet — caller does not need to handle missing-row vs zero-visits.
+ */
+export type QValueLookup = (agentType: string) => {
+    qValue: number;
+    visits: number;
+} | undefined;
+/**
+ * Blend a static score with a Q-value contribution.
+ *
+ *   effectiveScore = staticScore * (1 - qWeight) + normalizedQ * qWeight
+ *
+ * Returns { score, qWeight, qValue, qVisits } so callers can attach the
+ * telemetry fields to the ScoredAgent record.
+ */
+export declare function blendStaticAndQValue(staticScore: number, qLookup: {
+    qValue: number;
+    visits: number;
+} | undefined): {
+    score: number;
+    qWeight: number;
+    qValue: number;
+    qVisits: number;
+};
+/**
+ * Resolve the per-decision ε for the exploration policy.
+ *
+ * Priority order:
+ *   1. AQE_ROUTER_EXPLORATION_RATE env var (operator override, fixed)
+ *   2. Default base rate (0.05)
+ * The result is then multiplied by the mincut safety gate (caller passes
+ * `topologyCritical` derived from getSharedMinCutMonitor().isCritical()):
+ * critical topology → 0.2x dampening, healthy/unknown → 1.0x.
+ *
+ * Returns a number in [0, 1].
+ */
+export declare function resolveExplorationRate(opts: {
+    envOverride?: string;
+    topologyCritical?: boolean;
+}): {
+    epsilon: number;
+    baseEpsilon: number;
+    safetyMultiplier: number;
+};
+/**
+ * Apply the ε-greedy exploration policy to a sorted score list.
+ *
+ * With probability ε (computed from resolveExplorationRate), swaps the
+ * top-scored agent with a uniformly-random pick from positions 1..3 (or
+ * fewer if the list is shorter). Mutates `agentScores` in place. The
+ * promoted agent gets `exploration = true`.
+ *
+ * Uses `crypto.randomInt` for cryptographically-strong uniform sampling —
+ * matches the codebase convention (randomUUID is imported from 'crypto'
+ * in the same modules). Math.random() would work but breaks consistency.
+ */
+export declare function applyExplorationPolicy(agentScores: ScoredAgent[], epsilon: number): void;
+/**
+ * Derive a structural taskType from a free-form task description. Used to
+ * build the q-learning state_key shared with the post-task Bellman update
+ * (hooks-dream-learning.ts).
+ *
+ * Exported (rather than kept private in task-hooks) so QEReasoningBank can
+ * compute the same state_key at routing time as post-task does at outcome
+ * time — without that, the Q-table writer and reader would address
+ * different keys.
+ */
+export declare function deriveTaskType(description: string): string;
+/**
+ * Build the canonical Q-learning state_key. Must match the format used by
+ * `updateHookRouterQValue` in hooks-dream-learning.ts — the writer and
+ * reader must agree on the key shape.
+ */
+export declare function buildRoutingStateKey(opts: {
+    taskType: string;
+    priority?: string;
+    domain?: string;
+    complexityBucket: number;
+}): string;
+/**
+ * Compute the complexity bucket [0, 10] from a task description length.
+ * Mirrors the formula in task-hooks.ts pre-task bridge.
+ */
+export declare function deriveComplexityBucket(description: string): number;
 /**
  * Calculate agent scores for a routing request.
  *
@@ -49,7 +175,14 @@ export interface RoutingWeights {
  * @param requestLanguage - Optional language to boost agents with matching language expertise
  * @returns Sorted array of scored agents (highest score first)
  */
-export declare function calculateAgentScores(detectedDomains: QEDomain[], requestCapabilities: string[] | undefined, agentDomainPatternCounts: Map<string, number>, routingWeights: RoutingWeights, agentCapabilities?: Record<string, AgentCapabilityProfile>, requestLanguage?: string): ScoredAgent[];
+export declare function calculateAgentScores(detectedDomains: QEDomain[], requestCapabilities: string[] | undefined, agentDomainPatternCounts: Map<string, number>, routingWeights: RoutingWeights, agentCapabilities?: Record<string, AgentCapabilityProfile>, requestLanguage?: string, 
+/**
+ * ADR-095: optional per-agent Q-value lookup. When provided, the static
+ * score is blended with the Q-value contribution via blendStaticAndQValue.
+ * When omitted (or returning undefined for every agent), behavior is
+ * identical to the pre-ADR-095 deterministic scoring.
+ */
+qValueLookup?: QValueLookup): ScoredAgent[];
 /**
  * Domain compatibility matrix for cross-domain pattern transfer.
  * Maps each domain to its related domains (same as TransferSpecialistService).

package/dist/learning/agent-routing.js

@@ -1,10 +1,12 @@
 /**
  * Agentic QE v3 - Agent Routing
  * ADR-021: QE ReasoningBank for Pattern Learning
+ * ADR-095: ε-greedy exploration with Q-value blending and mincut safety gate
  *
  * Static agent capability mapping and routing score calculation
  * used by QEReasoningBank.routeTask().
  */
+import { randomInt } from 'crypto';
 // ============================================================================
 // Agent Capabilities Map
 // ============================================================================
@@ -72,6 +74,159 @@ export const AGENT_CAPABILITIES = {
         performanceScore: 0.75,
     },
 };
+// ============================================================================
+// ADR-095: Q-Value Blending + ε-Greedy Exploration
+// ============================================================================
+/**
+ * Maximum Q-value influence on the final score.
+ *
+ * 0.4 means a fully-mature Q-value can move the score by up to ±0.2 (since
+ * normalizedQ ranges over (0, 1) and the static contribution clamps the
+ * upper bound). This is intentionally bounded so Q-values inform rather
+ * than override the static features.
+ *
+ * Tuning: post-deploy telemetry will tell us whether agents are actually
+ * being separated by Q-values. If the avg `q_weight` in routing_outcomes
+ * climbs but quality_score doesn't improve, this constant is too high.
+ */
+export const MAX_Q_WEIGHT = 0.4;
+/**
+ * Number of (state_key, action_key) visits at which qWeight saturates at
+ * MAX_Q_WEIGHT. Below this, qWeight ramps linearly from 0.
+ *
+ * 20 visits at the default 30-min worker tick + typical session cadence
+ * implies ~1 week of activity before a (state, agent) pair drives the
+ * decision. Adjust downward if cold-start latency proves problematic.
+ */
+export const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * Sigmoid mapping R → (0, 1) for Q-value normalization before blending.
+ * A fresh row with q_value = 0 contributes 0.5 (neutral); negative q_values
+ * (after a failure, given the asymmetric -1.0 penalty from ADR-061) push
+ * the contribution toward 0, positive q_values toward 1.
+ */
+function sigmoid(x) {
+    return 1 / (1 + Math.exp(-x));
+}
+/**
+ * Blend a static score with a Q-value contribution.
+ *
+ *   effectiveScore = staticScore * (1 - qWeight) + normalizedQ * qWeight
+ *
+ * Returns { score, qWeight, qValue, qVisits } so callers can attach the
+ * telemetry fields to the ScoredAgent record.
+ */
+export function blendStaticAndQValue(staticScore, qLookup) {
+    if (!qLookup || qLookup.visits === 0) {
+        return { score: staticScore, qWeight: 0, qValue: 0, qVisits: 0 };
+    }
+    const qWeight = Math.min(qLookup.visits / QWEIGHT_RAMP_VISITS, 1) * MAX_Q_WEIGHT;
+    const normalizedQ = sigmoid(qLookup.qValue);
+    return {
+        score: staticScore * (1 - qWeight) + normalizedQ * qWeight,
+        qWeight,
+        qValue: qLookup.qValue,
+        qVisits: qLookup.visits,
+    };
+}
+/**
+ * Resolve the per-decision ε for the exploration policy.
+ *
+ * Priority order:
+ *   1. AQE_ROUTER_EXPLORATION_RATE env var (operator override, fixed)
+ *   2. Default base rate (0.05)
+ * The result is then multiplied by the mincut safety gate (caller passes
+ * `topologyCritical` derived from getSharedMinCutMonitor().isCritical()):
+ * critical topology → 0.2x dampening, healthy/unknown → 1.0x.
+ *
+ * Returns a number in [0, 1].
+ */
+export function resolveExplorationRate(opts) {
+    const envValue = opts.envOverride;
+    const parsed = envValue !== undefined ? Number.parseFloat(envValue) : NaN;
+    const baseEpsilon = Number.isFinite(parsed) && parsed >= 0 && parsed <= 1
+        ? parsed
+        : 0.05;
+    const safetyMultiplier = opts.topologyCritical ? 0.2 : 1.0;
+    const epsilon = Math.min(Math.max(baseEpsilon * safetyMultiplier, 0), 1);
+    return { epsilon, baseEpsilon, safetyMultiplier };
+}
+/**
+ * Apply the ε-greedy exploration policy to a sorted score list.
+ *
+ * With probability ε (computed from resolveExplorationRate), swaps the
+ * top-scored agent with a uniformly-random pick from positions 1..3 (or
+ * fewer if the list is shorter). Mutates `agentScores` in place. The
+ * promoted agent gets `exploration = true`.
+ *
+ * Uses `crypto.randomInt` for cryptographically-strong uniform sampling —
+ * matches the codebase convention (randomUUID is imported from 'crypto'
+ * in the same modules). Math.random() would work but breaks consistency.
+ */
+export function applyExplorationPolicy(agentScores, epsilon) {
+    if (epsilon <= 0 || agentScores.length < 2)
+        return;
+    // Compare in micro-units so randomInt can do uniform sampling without
+    // float arithmetic. ε = 0.05 → 50_000 micro-units in 1_000_000.
+    const epsilonMicro = Math.round(epsilon * 1_000_000);
+    if (epsilonMicro <= 0)
+        return;
+    if (randomInt(0, 1_000_000) >= epsilonMicro)
+        return;
+    // Pick from top alternatives (positions 1..min(3, length-1)).
+    const ceiling = Math.min(4, agentScores.length);
+    const exploreIdx = randomInt(1, ceiling);
+    const explored = agentScores[exploreIdx];
+    agentScores[exploreIdx] = agentScores[0];
+    agentScores[0] = explored;
+    agentScores[0].exploration = true;
+    agentScores[0].reasoning = [...agentScores[0].reasoning, '(exploration)'];
+}
+/**
+ * Derive a structural taskType from a free-form task description. Used to
+ * build the q-learning state_key shared with the post-task Bellman update
+ * (hooks-dream-learning.ts).
+ *
+ * Exported (rather than kept private in task-hooks) so QEReasoningBank can
+ * compute the same state_key at routing time as post-task does at outcome
+ * time — without that, the Q-table writer and reader would address
+ * different keys.
+ */
+export function deriveTaskType(description) {
+    const d = description.toLowerCase();
+    if (/\bgenerate[- ]?test|\btest[- ]?gen|\bgenerate.+spec/.test(d))
+        return 'test-generation';
+    if (/\bcoverage|\banalyze.+cover/.test(d))
+        return 'coverage-analysis';
+    if (/\bquality|\bassess|\baudit/.test(d))
+        return 'quality-assessment';
+    if (/\bsecurity|\bvulnerab|\bcompliance/.test(d))
+        return 'security-compliance';
+    if (/\bdefect|\bbug|\bdiagnos/.test(d))
+        return 'defect-intelligence';
+    if (/\brequirement|\bspec\b/.test(d))
+        return 'requirements-validation';
+    if (/\brefactor|\brewrite|\boptim/.test(d))
+        return 'refactoring';
+    if (/\btest|\brun.+test/.test(d))
+        return 'test-execution';
+    return 'unknown';
+}
+/**
+ * Build the canonical Q-learning state_key. Must match the format used by
+ * `updateHookRouterQValue` in hooks-dream-learning.ts — the writer and
+ * reader must agree on the key shape.
+ */
+export function buildRoutingStateKey(opts) {
+    return `${opts.taskType}|${opts.priority ?? 'normal'}|${opts.domain ?? 'any'}|${opts.complexityBucket}`;
+}
+/**
+ * Compute the complexity bucket [0, 10] from a task description length.
+ * Mirrors the formula in task-hooks.ts pre-task bridge.
+ */
+export function deriveComplexityBucket(description) {
+    return Math.max(0, Math.min(10, Math.round(Math.min(description.length / 200, 1) * 10)));
+}
 /**
  * Calculate agent scores for a routing request.
  *
@@ -83,7 +238,14 @@ export const AGENT_CAPABILITIES = {
  * @param requestLanguage - Optional language to boost agents with matching language expertise
  * @returns Sorted array of scored agents (highest score first)
  */
-export function calculateAgentScores(detectedDomains, requestCapabilities, agentDomainPatternCounts, routingWeights, agentCapabilities = AGENT_CAPABILITIES, requestLanguage) {
+export function calculateAgentScores(detectedDomains, requestCapabilities, agentDomainPatternCounts, routingWeights, agentCapabilities = AGENT_CAPABILITIES, requestLanguage, 
+/**
+ * ADR-095: optional per-agent Q-value lookup. When provided, the static
+ * score is blended with the Q-value contribution via blendStaticAndQValue.
+ * When omitted (or returning undefined for every agent), behavior is
+ * identical to the pre-ADR-095 deterministic scoring.
+ */
+qValueLookup) {
     const agentScores = [];
     for (const [agentType, profile] of Object.entries(agentCapabilities)) {
         let score = 0;
@@ -128,7 +290,28 @@ export function calculateAgentScores(detectedDomains, requestCapabilities, agent
             score += patternBoost;
             reasoning.push(`Pattern matches: ${patternCount}`);
         }
-        agentScores.push({ agent: agentType, score, reasoning });
+        // ADR-095: blend Q-value if a lookup is provided
+        const staticScore = score;
+        if (qValueLookup) {
+            const q = qValueLookup(agentType);
+            const blended = blendStaticAndQValue(staticScore, q);
+            score = blended.score;
+            if (blended.qWeight > 0) {
+                reasoning.push(`Q-bonus (w=${blended.qWeight.toFixed(2)}, v=${blended.qVisits})`);
+            }
+            agentScores.push({
+                agent: agentType,
+                score,
+                reasoning,
+                staticScore,
+                qWeight: blended.qWeight,
+                qValue: blended.qValue,
+                qVisits: blended.qVisits,
+            });
+        }
+        else {
+            agentScores.push({ agent: agentType, score, reasoning, staticScore });
+        }
     }
     // Sort by score descending
     agentScores.sort((a, b) => b.score - a.score);