agentic-qe 3.8.4 → 3.8.6

package/dist/cli/commands/hooks-handlers/hooks-dream-learning.js

@@ -0,0 +1,263 @@
+/**
+ * Agentic QE v3 - Hooks Dream Scheduler & Learning Persistence
+ *
+ * Dream cycle scheduling, experience recording, and experience-to-pattern
+ * consolidation. Extracted from hooks-shared.ts to keep files under 500 lines.
+ */
+import { randomUUID } from 'crypto';
+import chalk from 'chalk';
+// ============================================================================
+// Dream Scheduler State (persisted in kv_store between hook invocations)
+// ============================================================================
+export const DREAM_STATE_KEY = 'dream-scheduler:hook-state';
+export const DREAM_INTERVAL_MS = 3600000; // 1 hour between auto-dreams
+export const DREAM_EXPERIENCE_THRESHOLD = 20; // experiences before triggering
+export const DREAM_MIN_GAP_MS = 300000; // 5 minutes minimum between dreams
+/**
+ * Check if a dream cycle should be triggered and run it if so.
+ * Called from post-task hook after recording each experience.
+ *
+ * Trigger conditions (any of):
+ * 1. Time-based: >1hr since last dream
+ * 2. Experience-based: >20 experiences since last dream
+ *
+ * Guard: minimum 5 minutes between dreams
+ */
+export async function checkAndTriggerDream(memoryBackend) {
+    try {
+        // Load persisted dream state
+        const dreamState = await memoryBackend.get(DREAM_STATE_KEY);
+        if (!dreamState) {
+            return { triggered: false, reason: 'no-state' };
+        }
+        const now = Date.now();
+        const lastDreamTime = dreamState.lastDreamTime ? new Date(dreamState.lastDreamTime).getTime() : 0;
+        const timeSinceLastDream = now - lastDreamTime;
+        // Guard: minimum gap
+        if (timeSinceLastDream < DREAM_MIN_GAP_MS) {
+            return { triggered: false, reason: 'too-soon' };
+        }
+        // Check triggers
+        const timeTriggered = timeSinceLastDream >= DREAM_INTERVAL_MS;
+        const experienceTriggered = dreamState.experienceCount >= DREAM_EXPERIENCE_THRESHOLD;
+        if (!timeTriggered && !experienceTriggered) {
+            return { triggered: false, reason: 'conditions-not-met' };
+        }
+        const reason = timeTriggered ? 'time-interval' : 'experience-threshold';
+        console.log(chalk.dim(`[hooks] Dream trigger: ${reason} (${dreamState.experienceCount} experiences, ${Math.round(timeSinceLastDream / 60000)}min since last dream)`));
+        // Run a quick dream cycle
+        const { createDreamEngine } = await import('../../../learning/dream/index.js');
+        const { createQEReasoningBank: createRB } = await import('../../../learning/qe-reasoning-bank.js');
+        const engine = createDreamEngine({
+            maxDurationMs: 10000, // 10s for hook-triggered dreams
+            minConceptsRequired: 3,
+        });
+        await engine.initialize();
+        // Load patterns from ReasoningBank
+        const rb = createRB(memoryBackend, undefined, {
+            enableLearning: true,
+            enableGuidance: false,
+            enableRouting: false,
+            embeddingDimension: 384,
+            useONNXEmbeddings: true,
+        });
+        await rb.initialize();
+        const patternsResult = await rb.searchPatterns('', { limit: 100, minConfidence: 0.3 });
+        if (patternsResult.success && patternsResult.value.length > 0) {
+            const importPatterns = patternsResult.value.map(r => ({
+                id: r.pattern.id,
+                name: r.pattern.name,
+                description: r.pattern.description || `${r.pattern.patternType} pattern`,
+                domain: r.pattern.qeDomain || 'learning-optimization',
+                patternType: r.pattern.patternType,
+                confidence: r.pattern.confidence,
+                successRate: r.pattern.successRate || 0.5,
+            }));
+            await engine.loadPatternsAsConcepts(importPatterns);
+        }
+        const result = await engine.dream(10000);
+        // Update state
+        dreamState.lastDreamTime = new Date().toISOString();
+        dreamState.experienceCount = 0;
+        dreamState.totalDreamsThisSession++;
+        await memoryBackend.set(DREAM_STATE_KEY, dreamState);
+        await engine.close();
+        return {
+            triggered: true,
+            reason,
+            insightsGenerated: result.insights.length,
+        };
+    }
+    catch (error) {
+        console.error(chalk.dim(`[hooks] Dream trigger failed: ${error instanceof Error ? error.message : 'unknown'}`));
+        return { triggered: false, reason: 'error' };
+    }
+}
+/**
+ * Increment the experience counter in dream state.
+ * Called from post-task hook.
+ */
+export async function incrementDreamExperience(memoryBackend) {
+    try {
+        let dreamState = await memoryBackend.get(DREAM_STATE_KEY);
+        if (!dreamState) {
+            dreamState = {
+                lastDreamTime: null,
+                experienceCount: 0,
+                sessionStartTime: new Date().toISOString(),
+                totalDreamsThisSession: 0,
+            };
+        }
+        dreamState.experienceCount++;
+        await memoryBackend.set(DREAM_STATE_KEY, dreamState);
+        return dreamState.experienceCount;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Persist a command/edit experience directly to the captured_experiences table.
+ * CLI hooks cannot use the MCP middleware wrapper, so they write directly.
+ */
+export async function persistCommandExperience(opts) {
+    try {
+        const { getUnifiedMemory } = await import('../../../kernel/unified-memory.js');
+        const um = getUnifiedMemory();
+        if (!um.isInitialized()) {
+            await um.initialize();
+        }
+        const db = um.getDatabase();
+        const id = `cli-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        // Compute quality based on context rather than binary success/fail.
+        // Duration-aware: fast successful ops get higher quality.
+        // Source-aware: post-task and post-edit are higher signal than post-command.
+        const durationMs = opts.durationMs || 0;
+        let quality;
+        if (opts.success) {
+            // Successful: base 0.7, bonus for fast execution (< 5s), bonus for high-signal sources
+            const speedBonus = durationMs > 0 && durationMs < 5000 ? 0.1 : 0;
+            const sourceBonus = opts.source.includes('post-task') ? 0.1 : opts.source.includes('post-edit') ? 0.05 : 0;
+            quality = Math.min(0.95, 0.7 + speedBonus + sourceBonus);
+        }
+        else {
+            // Failed: base 0.3, but higher for post-task (still learned something)
+            const sourceBonus = opts.source.includes('post-task') ? 0.15 : opts.source.includes('post-edit') ? 0.1 : 0;
+            quality = Math.min(0.6, 0.3 + sourceBonus);
+        }
+        db.prepare(`
+      INSERT OR REPLACE INTO captured_experiences
+        (id, task, agent, domain, success, quality, duration_ms,
+         started_at, completed_at, source)
+      VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'), ?)
+    `).run(id, opts.task.slice(0, 500), opts.agent, opts.domain, opts.success ? 1 : 0, quality, durationMs, opts.source);
+    }
+    catch (error) {
+        // Best-effort — don't fail the hook
+        console.error(chalk.dim(`[hooks] persistCommandExperience: ${error instanceof Error ? error.message : 'unknown'}`));
+    }
+}
+/**
+ * Lightweight experience-to-pattern consolidation.
+ * Aggregates captured_experiences by domain+agent, and for clusters that meet
+ * quality thresholds, creates new qe_patterns entries.
+ * Called at session-end so patterns grow with each session.
+ */
+export async function consolidateExperiencesToPatterns() {
+    const { getUnifiedMemory } = await import('../../../kernel/unified-memory.js');
+    const um = getUnifiedMemory();
+    if (!um.isInitialized()) {
+        await um.initialize();
+    }
+    const db = um.getDatabase();
+    // Ensure consolidation columns exist (may be missing on older DBs)
+    const existingCols = new Set(db.prepare('PRAGMA table_info(captured_experiences)').all().map(c => c.name));
+    const migrations = [
+        ['consolidated_into', 'TEXT DEFAULT NULL'],
+        ['consolidation_count', 'INTEGER DEFAULT 1'],
+        ['quality_updated_at', 'TEXT DEFAULT NULL'],
+        ['reuse_success_count', 'INTEGER DEFAULT 0'],
+        ['reuse_failure_count', 'INTEGER DEFAULT 0'],
+    ];
+    for (const [col, def] of migrations) {
+        if (!existingCols.has(col)) {
+            db.exec(`ALTER TABLE captured_experiences ADD COLUMN ${col} ${def}`);
+        }
+    }
+    // Aggregate unprocessed experiences by domain+agent with quality thresholds.
+    // Exclude 'cli-hook' agent — these are low-quality hook telemetry events
+    // (quality ~0.40, success_rate ~0.24) that flood the pipeline and block
+    // real pattern creation. See issue #348.
+    const aggregates = db.prepare(`
+    SELECT
+      domain,
+      agent,
+      COUNT(*) as cnt,
+      AVG(quality) as avg_quality,
+      SUM(success) as successes,
+      CAST(SUM(success) AS REAL) / COUNT(*) as success_rate,
+      AVG(duration_ms) as avg_duration,
+      GROUP_CONCAT(DISTINCT source) as sources
+    FROM captured_experiences
+    WHERE application_count = 0
+      AND agent != 'cli-hook'
+    GROUP BY domain, agent
+    HAVING cnt >= 3 AND avg_quality >= 0.5 AND success_rate >= 0.6
+    ORDER BY avg_quality DESC
+    LIMIT 50
+  `).all();
+    if (aggregates.length === 0)
+        return 0;
+    const { v4: uuidv4 } = await import('uuid');
+    let created = 0;
+    for (const agg of aggregates) {
+        try {
+            // Use date-bucketed names so new patterns emerge as usage evolves,
+            // instead of silently reinforcing one static pattern forever.
+            const dateBucket = new Date().toISOString().slice(0, 7); // YYYY-MM
+            const patternName = `${agg.agent}-${agg.domain}-${dateBucket}`;
+            // Check for existing pattern with same name this month
+            const existing = db.prepare(`
+        SELECT id FROM qe_patterns
+        WHERE qe_domain = ? AND name = ?
+        LIMIT 1
+      `).get(agg.domain, patternName);
+            if (existing) {
+                // Reinforce existing monthly pattern
+                db.prepare(`
+          UPDATE qe_patterns
+          SET usage_count = usage_count + ?,
+              successful_uses = successful_uses + ?,
+              confidence = MIN(0.99, confidence + 0.01),
+              quality_score = MIN(0.99, quality_score + 0.005),
+              updated_at = datetime('now')
+          WHERE id = ?
+        `).run(agg.cnt, agg.successes, existing.id);
+            }
+            else {
+                const patternId = uuidv4();
+                const confidence = Math.min(0.95, agg.avg_quality * 0.8 + agg.success_rate * 0.2);
+                const qualityScore = confidence * 0.3 + (Math.min(agg.cnt, 100) / 100) * 0.2 + agg.success_rate * 0.5;
+                db.prepare(`
+          INSERT INTO qe_patterns (
+            id, pattern_type, qe_domain, domain, name, description,
+            confidence, usage_count, success_rate, quality_score, tier,
+            template_json, context_json, created_at, successful_uses
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?)
+        `).run(patternId, 'workflow', agg.domain, agg.domain, patternName, `Auto-consolidated from ${agg.cnt} experiences. Agent: ${agg.agent}, success rate: ${(agg.success_rate * 100).toFixed(0)}%`, confidence, agg.cnt, agg.success_rate, qualityScore, 'short-term', JSON.stringify({ type: 'workflow', content: `${agg.agent} pattern for ${agg.domain}`, variables: [] }), JSON.stringify({ tags: (agg.sources || '').split(','), sourceType: 'session-consolidation', extractedAt: new Date().toISOString() }), agg.successes);
+                created++;
+            }
+            // Mark experiences as processed
+            db.prepare(`
+        UPDATE captured_experiences
+        SET application_count = application_count + 1
+        WHERE domain = ? AND agent = ? AND application_count = 0
+      `).run(agg.domain, agg.agent);
+        }
+        catch {
+            // Skip on error (e.g. constraint violations)
+        }
+    }
+    return created;
+}
+//# sourceMappingURL=hooks-dream-learning.js.map

package/dist/cli/commands/hooks-handlers/hooks-shared.d.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Agentic QE v3 - Hooks Shared State & Utilities
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * Shared state, initialization, dream scheduler, learning utils, and output helpers
+ * used by all hooks handler modules.
+ */
+import { QEReasoningBank } from '../../../learning/qe-reasoning-bank.js';
+import { QEHookRegistry } from '../../../learning/qe-hooks.js';
+import type { MemoryBackend } from '../../../kernel/interfaces.js';
+import { type ICoherenceService } from '../../../integrations/coherence/index.js';
+/**
+ * Singleton state for hooks system
+ */
+export interface HooksSystemState {
+    reasoningBank: QEReasoningBank | null;
+    hookRegistry: QEHookRegistry | null;
+    coherenceService: ICoherenceService | null;
+    sessionId: string | null;
+    initialized: boolean;
+    initializationPromise: Promise<void> | null;
+}
+export declare const state: HooksSystemState;
+/**
+ * Get or create the hooks system with proper initialization
+ */
+export declare function getHooksSystem(): Promise<{
+    reasoningBank: QEReasoningBank;
+    hookRegistry: QEHookRegistry;
+}>;
+/**
+ * Initialize the hooks system
+ */
+export declare function initializeHooksSystem(): Promise<void>;
+/**
+ * Create hybrid backend with timeout protection
+ *
+ * ADR-046: Uses unified memory.db path for consistency with all other components.
+ * HybridMemoryBackend delegates to UnifiedMemoryManager singleton.
+ */
+export declare function createHybridBackendWithTimeout(dataDir: string): Promise<MemoryBackend>;
+/**
+ * Create in-memory fallback backend
+ */
+export declare function createInMemoryBackend(): MemoryBackend;
+export declare function printJson(data: unknown): void;
+export declare function printSuccess(message: string): void;
+export declare function printError(message: string): void;
+export declare function printGuidance(guidance: string[]): void;
+export { DREAM_STATE_KEY, DREAM_INTERVAL_MS, DREAM_EXPERIENCE_THRESHOLD, DREAM_MIN_GAP_MS, type DreamHookState, checkAndTriggerDream, incrementDreamExperience, persistCommandExperience, consolidateExperiencesToPatterns, } from './hooks-dream-learning.js';
+//# sourceMappingURL=hooks-shared.d.ts.map

package/dist/cli/commands/hooks-handlers/hooks-shared.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Agentic QE v3 - Hooks Shared State & Utilities
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * Shared state, initialization, dream scheduler, learning utils, and output helpers
+ * used by all hooks handler modules.
+ */
+import chalk from 'chalk';
+import path from 'node:path';
+import { createQEReasoningBank, } from '../../../learning/qe-reasoning-bank.js';
+import { QEHookRegistry, setupQEHooks, } from '../../../learning/qe-hooks.js';
+import { HybridMemoryBackend } from '../../../kernel/hybrid-backend.js';
+import { findProjectRoot } from '../../../kernel/unified-memory.js';
+import { wasmLoader, createCoherenceService, } from '../../../integrations/coherence/index.js';
+export const state = {
+    reasoningBank: null,
+    hookRegistry: null,
+    coherenceService: null,
+    sessionId: null,
+    initialized: false,
+    initializationPromise: null,
+};
+/**
+ * Get or create the hooks system with proper initialization
+ */
+export async function getHooksSystem() {
+    // If already initializing, wait for it
+    if (state.initializationPromise) {
+        await state.initializationPromise;
+    }
+    // If already initialized, return
+    if (state.initialized && state.reasoningBank && state.hookRegistry) {
+        return {
+            reasoningBank: state.reasoningBank,
+            hookRegistry: state.hookRegistry,
+        };
+    }
+    // Initialize with timeout protection
+    state.initializationPromise = initializeHooksSystem();
+    await state.initializationPromise;
+    state.initializationPromise = null;
+    if (!state.reasoningBank || !state.hookRegistry) {
+        throw new Error('Failed to initialize hooks system');
+    }
+    return {
+        reasoningBank: state.reasoningBank,
+        hookRegistry: state.hookRegistry,
+    };
+}
+/**
+ * Initialize the hooks system
+ */
+export async function initializeHooksSystem() {
+    if (state.initialized)
+        return;
+    try {
+        // Create memory backend — always resolve to project root DB
+        const projectRoot = findProjectRoot();
+        const dataDir = path.join(projectRoot, '.agentic-qe');
+        // Use hybrid backend with timeout protection
+        const memoryBackend = await createHybridBackendWithTimeout(dataDir);
+        // Initialize CoherenceService (optional - falls back to TypeScript implementation)
+        try {
+            state.coherenceService = await createCoherenceService(wasmLoader);
+            console.log(chalk.dim('[hooks] CoherenceService initialized with WASM engines'));
+        }
+        catch (error) {
+            // WASM not available - will use fallback
+            console.log(chalk.dim(`[hooks] CoherenceService WASM unavailable, using fallback: ${error instanceof Error ? error.message : 'unknown'}`));
+        }
+        // Create reasoning bank with coherence service
+        state.reasoningBank = createQEReasoningBank(memoryBackend, undefined, {
+            enableLearning: true,
+            enableGuidance: true,
+            enableRouting: true,
+            embeddingDimension: 384,
+            useONNXEmbeddings: true, // Use real transformer embeddings (384-dim)
+        }, state.coherenceService ?? undefined);
+        // Initialize with timeout
+        const initTimeout = 10000; // 10 seconds
+        const initPromise = state.reasoningBank.initialize();
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('ReasoningBank init timeout')), initTimeout));
+        await Promise.race([initPromise, timeoutPromise]);
+        // Wire RVF dual-writer for vector replication (optional, best-effort)
+        try {
+            const { getSharedRvfDualWriter } = await import('../../../integrations/ruvector/shared-rvf-dual-writer.js');
+            const dualWriter = await getSharedRvfDualWriter();
+            if (dualWriter)
+                state.reasoningBank.setRvfDualWriter(dualWriter);
+        }
+        catch (e) {
+            if (process.env.DEBUG)
+                console.debug('[hooks] RVF wiring skipped:', e instanceof Error ? e.message : e);
+        }
+        // Setup hook registry
+        state.hookRegistry = setupQEHooks(state.reasoningBank);
+        state.initialized = true;
+        console.log(chalk.dim('[hooks] System initialized'));
+    }
+    catch (error) {
+        // Create minimal fallback state
+        console.warn(chalk.yellow(`[hooks] Using fallback mode: ${error instanceof Error ? error.message : 'unknown error'}`));
+        // Create in-memory fallback backend
+        // NOTE: RVF dual-writer is intentionally NOT wired here — the fallback
+        // uses an in-memory backend with no disk access, so RVF replication
+        // (which requires the unified memory DB) is not meaningful.
+        const fallbackBackend = createInMemoryBackend();
+        state.reasoningBank = createQEReasoningBank(fallbackBackend, undefined, {
+            enableLearning: true,
+            enableGuidance: true,
+            enableRouting: true,
+        });
+        // Skip full initialization for fallback
+        state.hookRegistry = new QEHookRegistry();
+        state.hookRegistry.initialize(state.reasoningBank);
+        state.initialized = true;
+    }
+}
+/**
+ * Create hybrid backend with timeout protection
+ *
+ * ADR-046: Uses unified memory.db path for consistency with all other components.
+ * HybridMemoryBackend delegates to UnifiedMemoryManager singleton.
+ */
+export async function createHybridBackendWithTimeout(dataDir) {
+    const timeoutMs = 5000;
+    // ADR-046: Use unified memory.db path - same as all other components
+    // HybridMemoryBackend is a facade over UnifiedMemoryManager
+    const backend = new HybridMemoryBackend({
+        sqlite: {
+            path: path.join(dataDir, 'memory.db'), // ADR-046: Unified storage
+            walMode: true,
+            poolSize: 3,
+            busyTimeout: 5000,
+        },
+        // agentdb.path is ignored - vectors stored in unified memory.db
+        enableFallback: true,
+        defaultNamespace: 'qe-patterns',
+    });
+    const initPromise = backend.initialize();
+    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Backend init timeout')), timeoutMs));
+    await Promise.race([initPromise, timeoutPromise]);
+    return backend;
+}
+/**
+ * Create in-memory fallback backend
+ */
+export function createInMemoryBackend() {
+    const store = new Map();
+    return {
+        initialize: async () => { },
+        dispose: async () => {
+            store.clear();
+        },
+        get: async (key) => {
+            const entry = store.get(key);
+            return entry ? entry.value : undefined;
+        },
+        set: async (key, value, _options) => {
+            store.set(key, { value });
+        },
+        delete: async (key) => {
+            return store.delete(key);
+        },
+        has: async (key) => store.has(key),
+        search: async (pattern, _limit) => {
+            const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+            return Array.from(store.keys()).filter((k) => regex.test(k));
+        },
+        vectorSearch: async (_embedding, _k) => {
+            return [];
+        },
+        storeVector: async (_key, _embedding, _metadata) => {
+            // No-op for in-memory fallback
+        },
+        count: async (namespace) => {
+            let count = 0;
+            const prefix = `${namespace}:`;
+            for (const key of store.keys()) {
+                if (key.startsWith(prefix)) {
+                    count++;
+                }
+            }
+            return count;
+        },
+        hasCodeIntelligenceIndex: async () => {
+            const prefix = 'code-intelligence:kg:';
+            for (const key of store.keys()) {
+                if (key.startsWith(prefix)) {
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function printSuccess(message) {
+    console.log(chalk.green('✓'), message);
+}
+export function printError(message) {
+    console.error(chalk.red('✗'), message);
+}
+export function printGuidance(guidance) {
+    if (guidance.length === 0) {
+        console.log(chalk.dim('  No specific guidance'));
+        return;
+    }
+    guidance.forEach((g, i) => {
+        console.log(chalk.cyan(`  ${i + 1}.`), g);
+    });
+}
+// ============================================================================
+// Dream Scheduler & Learning — re-exported from hooks-dream-learning.ts
+// ============================================================================
+export { DREAM_STATE_KEY, DREAM_INTERVAL_MS, DREAM_EXPERIENCE_THRESHOLD, DREAM_MIN_GAP_MS, checkAndTriggerDream, incrementDreamExperience, persistCommandExperience, consolidateExperiencesToPatterns, } from './hooks-dream-learning.js';
+//# sourceMappingURL=hooks-shared.js.map

package/dist/cli/commands/hooks-handlers/routing-hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Agentic QE v3 - Routing Hooks (route)
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * Handles task routing to optimal QE agent.
+ */
+import { Command } from 'commander';
+/**
+ * Register route subcommand on the hooks command.
+ */
+export declare function registerRoutingHooks(hooks: Command): void;
+//# sourceMappingURL=routing-hooks.d.ts.map

package/dist/cli/commands/hooks-handlers/routing-hooks.js

@@ -0,0 +1,107 @@
+/**
+ * Agentic QE v3 - Routing Hooks (route)
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * Handles task routing to optimal QE agent.
+ */
+import { randomUUID } from 'crypto';
+import chalk from 'chalk';
+import path from 'node:path';
+import { findProjectRoot } from '../../../kernel/unified-memory.js';
+import { getHooksSystem, createHybridBackendWithTimeout, incrementDreamExperience, printJson, printError, printGuidance, } from './hooks-shared.js';
+/**
+ * Register route subcommand on the hooks command.
+ */
+export function registerRoutingHooks(hooks) {
+    // -------------------------------------------------------------------------
+    // route: Route task to optimal agent
+    // -------------------------------------------------------------------------
+    hooks
+        .command('route')
+        .description('Route a task to the optimal QE agent')
+        .requiredOption('-t, --task <description>', 'Task description')
+        .option('-d, --domain <domain>', 'Target QE domain hint')
+        .option('-c, --capabilities <caps...>', 'Required capabilities')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const { reasoningBank } = await getHooksSystem();
+            const request = {
+                task: options.task,
+                domain: options.domain,
+                capabilities: options.capabilities,
+            };
+            const result = await reasoningBank.routeTask(request);
+            if (!result.success) {
+                throw new Error(result.error.message);
+            }
+            const routing = result.value;
+            if (options.json) {
+                printJson({
+                    recommendedAgent: routing.recommendedAgent,
+                    confidence: routing.confidence,
+                    alternatives: routing.alternatives,
+                    domains: routing.domains,
+                    patternCount: routing.patterns.length,
+                    guidance: routing.guidance,
+                    reasoning: routing.reasoning,
+                });
+            }
+            else {
+                console.log(chalk.bold('\n🎯 Task Routing Result'));
+                console.log(chalk.dim(`  Task: "${options.task}"`));
+                console.log(chalk.bold('\n👤 Recommended Agent:'), chalk.cyan(routing.recommendedAgent));
+                console.log(chalk.dim(`  Confidence: ${(routing.confidence * 100).toFixed(1)}%`));
+                if (routing.alternatives.length > 0) {
+                    console.log(chalk.bold('\n🔄 Alternatives:'));
+                    routing.alternatives.forEach((alt) => {
+                        console.log(chalk.dim(`  - ${alt.agent}: ${(alt.score * 100).toFixed(1)}%`));
+                    });
+                }
+                console.log(chalk.bold('\n📂 Detected Domains:'), routing.domains.join(', '));
+                console.log(chalk.bold('\n💡 Guidance:'));
+                printGuidance(routing.guidance);
+                console.log(chalk.bold('\n📖 Reasoning:'), chalk.dim(routing.reasoning));
+            }
+            // Persist routing decision for learning
+            try {
+                const { getUnifiedMemory } = await import('../../../kernel/unified-memory.js');
+                const um = getUnifiedMemory();
+                if (!um.isInitialized()) {
+                    await um.initialize();
+                }
+                const db = um.getDatabase();
+                const outcomeId = `route-${Date.now()}-${randomUUID().slice(0, 8)}`;
+                db.prepare(`
+            INSERT OR REPLACE INTO routing_outcomes (
+              id, task_json, decision_json, used_agent,
+              followed_recommendation, success, quality_score,
+              duration_ms, error
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(outcomeId, JSON.stringify({ description: options.task, domain: options.domain }), JSON.stringify({
+                    recommended: routing.recommendedAgent,
+                    confidence: routing.confidence,
+                    alternatives: routing.alternatives,
+                }), routing.recommendedAgent, 1, // followed_recommendation = true (recommendation stage)
+                1, // success = true (routing itself succeeded)
+                routing.confidence, 0, // duration not tracked at routing stage
+                null);
+                // Increment dream experience counter
+                const projectRoot = findProjectRoot();
+                const dataDir = path.join(projectRoot, '.agentic-qe');
+                const memoryBackend = await createHybridBackendWithTimeout(dataDir);
+                await incrementDreamExperience(memoryBackend);
+            }
+            catch (persistError) {
+                // Best-effort — don't fail the hook
+                console.error(chalk.dim(`[hooks] route persist: ${persistError instanceof Error ? persistError.message : 'unknown'}`));
+            }
+            return;
+        }
+        catch (error) {
+            printError(`route failed: ${error instanceof Error ? error.message : 'unknown'}`);
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=routing-hooks.js.map

package/dist/cli/commands/hooks-handlers/session-hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Agentic QE v3 - Session Hooks (session-start, session-end)
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * Handles session lifecycle hooks.
+ */
+import { Command } from 'commander';
+/**
+ * Register session-start and session-end subcommands on the hooks command.
+ */
+export declare function registerSessionHooks(hooks: Command): void;
+//# sourceMappingURL=session-hooks.d.ts.map