agentic-qe 3.10.0 → 3.10.2

package/dist/kernel/kernel.js

@@ -21,6 +21,7 @@ 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 { createLLMRouterService, } from '../shared/llm/llm-router-service.js';
 // Import domain plugin factories
 import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
 import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
@@ -44,21 +45,25 @@ import '../domains/security-compliance';
 import '../domains/code-intelligence';
 import '../domains/quality-assessment';
 import { createEnterpriseIntegrationPlugin } from '../domains/enterprise-integration/plugin';
+// NOTE: underlying createXxxPlugin signatures are updated in Phase 2.
+// For Phase 1, the wrappers accept llmRouter but discard it — this
+// keeps the kernel boot path internally consistent without forcing
+// 13 simultaneous domain-level changes.
 const DOMAIN_FACTORIES = {
-    'test-generation': (eb, m, c) => createTestGenerationPlugin(eb, m, c),
-    'test-execution': (eb, m) => createTestExecutionPlugin(eb, m),
-    'coverage-analysis': (eb, m) => createCoverageAnalysisPlugin(eb, m),
-    'quality-assessment': (eb, m, c) => createQualityAssessmentPlugin(eb, m, c),
-    'defect-intelligence': (eb, m, c) => createDefectIntelligencePlugin(eb, m, c),
-    'requirements-validation': (eb, m, c) => createRequirementsValidationPlugin(eb, m, c),
-    'code-intelligence': (eb, m, c) => createCodeIntelligencePlugin(eb, m, c),
-    'security-compliance': (eb, m, c) => createSecurityCompliancePlugin(eb, m, c),
-    'contract-testing': (eb, m, c) => createContractTestingPlugin(eb, m, c),
-    'visual-accessibility': (eb, m, c) => createVisualAccessibilityPlugin(eb, m, c),
-    'chaos-resilience': (eb, m, c) => createChaosResiliencePlugin(eb, m, c),
-    'learning-optimization': (eb, m, c) => createLearningOptimizationPlugin(eb, m, c),
-    'enterprise-integration': (eb, m, c) => createEnterpriseIntegrationPlugin(eb, m, c),
-    'coordination': (eb, m, c) => createCoordinationPlugin(eb, m, c),
+    'test-generation': (eb, m, c, llmRouter) => createTestGenerationPlugin(eb, m, c, undefined, llmRouter),
+    'test-execution': (eb, m, _c, llmRouter) => createTestExecutionPlugin(eb, m, llmRouter),
+    'coverage-analysis': (eb, m, _c, llmRouter) => createCoverageAnalysisPlugin(eb, m, llmRouter),
+    'quality-assessment': (eb, m, c, llmRouter) => createQualityAssessmentPlugin(eb, m, c, undefined, llmRouter),
+    'defect-intelligence': (eb, m, c, llmRouter) => createDefectIntelligencePlugin(eb, m, c, undefined, llmRouter),
+    'requirements-validation': (eb, m, c, llmRouter) => createRequirementsValidationPlugin(eb, m, c, undefined, llmRouter),
+    'code-intelligence': (eb, m, c, llmRouter) => createCodeIntelligencePlugin(eb, m, c, undefined, llmRouter),
+    'security-compliance': (eb, m, c, llmRouter) => createSecurityCompliancePlugin(eb, m, c, undefined, llmRouter),
+    'contract-testing': (eb, m, c, llmRouter) => createContractTestingPlugin(eb, m, c, undefined, llmRouter),
+    'visual-accessibility': (eb, m, c, llmRouter) => createVisualAccessibilityPlugin(eb, m, c, undefined, llmRouter),
+    'chaos-resilience': (eb, m, c, llmRouter) => createChaosResiliencePlugin(eb, m, c, undefined, llmRouter),
+    'learning-optimization': (eb, m, c, llmRouter) => createLearningOptimizationPlugin(eb, m, c, undefined, llmRouter),
+    'enterprise-integration': (eb, m, c, _llmRouter) => createEnterpriseIntegrationPlugin(eb, m, c),
+    'coordination': (eb, m, c, _llmRouter) => createCoordinationPlugin(eb, m, c),
 };
 const DEFAULT_CONFIG = {
     maxConcurrentAgents: AGENT_CONSTANTS.MAX_CONCURRENT_AGENTS,
@@ -93,6 +98,10 @@ export class QEKernelImpl {
     // checkAndTriggerDream path so 10-second SQLite write transactions move
     // out of short-lived hook subprocesses into the long-lived kernel.
     _dreamScheduler;
+    // ADR-043: kernel singleton HybridRouter. Built during initialize() iff
+    // a provider key is in env or the project explicitly enables one.
+    _llmRouter;
+    _llmRouterBuild;
     constructor(config = {}) {
         this._config = { ...DEFAULT_CONFIG, ...config };
         this._startTime = new Date();
@@ -118,6 +127,15 @@ export class QEKernelImpl {
     get memory() {
         return this._memory;
     }
+    /**
+     * ADR-043: Get the LLM router built during initialize(). Returns
+     * undefined when llmRouter.enabled is false or no provider was
+     * available. Domain plugins receive this as their factory's 4th arg
+     * via DOMAIN_FACTORIES.
+     */
+    get llmRouter() {
+        return this._llmRouter;
+    }
     async initialize() {
         if (this._initialized) {
             return;
@@ -156,14 +174,20 @@ export class QEKernelImpl {
             // Re-create plugins with the real memory backend
             this._plugins = new DefaultPluginLoader(this._eventBus, this._memory, this._config.lazyLoading);
         }
+        // ADR-043: Build the kernel-singleton LLM router before plugin
+        // factories are registered, so the closure on the next loop can
+        // capture it. Builds iff configured/auto-detected; null otherwise.
+        await this._initializeLLMRouter(projectRoot);
         // Register domain factories for enabled domains
         for (const domain of this._config.enabledDomains) {
             const factory = DOMAIN_FACTORIES[domain];
             if (factory) {
                 // Wrap factory to match PluginLoader signature (async)
                 this._plugins.registerFactory(domain, async (eventBus, memory) => {
-                    // Create plugin synchronously, return as Promise
-                    return Promise.resolve(factory(eventBus, memory, this._coordinator));
+                    // Create plugin synchronously, return as Promise.
+                    // ADR-043: pass the kernel singleton llmRouter as 4th arg —
+                    // domain factories forward it to coordinators/services.
+                    return Promise.resolve(factory(eventBus, memory, this._coordinator, this._llmRouter));
                 });
             }
         }
@@ -199,7 +223,9 @@ export class QEKernelImpl {
                         if (typeof createPlugin !== 'function') {
                             throw new Error(`Plugin "${manifest.name}" entry point must export a default function or "createPlugin" function`);
                         }
-                        return createPlugin(eventBus, memory, this._coordinator);
+                        // ADR-043: forward llmRouter so external plugins can
+                        // opt into LLM enhancement on the same terms as built-ins.
+                        return createPlugin(eventBus, memory, this._coordinator, this._llmRouter);
                     });
                 }
             }
@@ -310,6 +336,106 @@ export class QEKernelImpl {
         }
         this._initialized = true;
     }
+    /**
+     * ADR-043: Build the kernel-singleton HybridRouter.
+     *
+     * Behavior is gated, in order:
+     *   1. AQE_LLM_ROUTER_DISABLED env var (kill-switch): if set to a truthy
+     *      value, ALWAYS skip — even when config.llmRouter.enabled === true.
+     *      This is the env-only opt-out for users who upgrade with a
+     *      provider key already in env and don't want billing surprises.
+     *   2. config.llmRouter.enabled:
+     *      'auto' (default): build iff at least one provider key is in env,
+     *                        or the project's llm-config.json enables a provider
+     *      true:             attempt to build; emit error event if no provider
+     *      false:            skip entirely (sets _llmRouter to undefined)
+     *
+     * On any error we publish a structured kernel.llm-router.init-failed
+     * event so monitoring catches misconfiguration. We also keep the
+     * console.warn for direct visibility in dev. The kernel still boots —
+     * a kernel that boots without LLMs is strictly better than a kernel
+     * that won't boot — but the failure is now observable.
+     */
+    async _initializeLLMRouter(projectRoot) {
+        // (1) Hard env kill-switch. Truthy values disable; falsy/empty pass.
+        // Same parse rule as src/mcp/tools/base.ts:isRouterKillSwitchSet
+        // so both code paths agree on what "disabled" means.
+        const killSwitch = (process.env.AQE_LLM_ROUTER_DISABLED ?? '').trim().toLowerCase();
+        if (killSwitch &&
+            killSwitch !== 'false' &&
+            killSwitch !== '0' &&
+            killSwitch !== 'no' &&
+            killSwitch !== 'off') {
+            this._llmRouter = undefined;
+            return;
+        }
+        const llmCfg = this._config.llmRouter ?? {};
+        const enabled = llmCfg.enabled ?? 'auto';
+        if (enabled === false) {
+            this._llmRouter = undefined;
+            return;
+        }
+        try {
+            const built = await createLLMRouterService({
+                projectRoot,
+                override: llmCfg.configOverride,
+                providerManager: llmCfg.providerManager,
+            });
+            if (!built) {
+                if (enabled === true) {
+                    console.warn('[QEKernel] llmRouter.enabled=true but no provider available — ' +
+                        'continuing without LLM router (domain services will skip LLM enhancement)');
+                    await this._publishLLMRouterEvent('init-no-provider', {
+                        reason: 'no provider available in env or disk config',
+                    });
+                }
+                this._llmRouter = undefined;
+                return;
+            }
+            this._llmRouterBuild = built;
+            this._llmRouter = built.router;
+            // Phase 5 wiring: register as shared singleton so MCP standalone
+            // tools see the same router instance (one cost tracker, one cache,
+            // one metric collector, one circuit breaker per provider).
+            try {
+                const { setSharedLLMRouter } = await import('../mcp/tools/base.js');
+                setSharedLLMRouter(built.router);
+            }
+            catch {
+                // MCP module not loaded — fine in CLI-only contexts.
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn('[QEKernel] LLM router init failed; continuing without LLM enhancement:', msg);
+            await this._publishLLMRouterEvent('init-failed', {
+                error: msg,
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+            this._llmRouter = undefined;
+        }
+    }
+    /**
+     * ADR-043: emit a structured event on the kernel event bus when the
+     * LLM router can't be built. Observability hook for monitoring and
+     * alerting — a silent warn is not enough for production systems where
+     * "tests run without LLM analysis" is a quality regression worth
+     * paging on.
+     */
+    async _publishLLMRouterEvent(type, payload) {
+        try {
+            await this._eventBus.publish({
+                id: randomUUID(),
+                type: `kernel.llm-router.${type}`,
+                timestamp: new Date(),
+                source: 'qe-kernel',
+                payload,
+            });
+        }
+        catch {
+            // Event bus publish failures during boot must not crash the kernel.
+        }
+    }
     async dispose() {
         // ADR-094: Stop the dream scheduler first so a dream-in-progress doesn't
         // try to write to a disposed memory backend.
@@ -332,6 +458,20 @@ export class QEKernelImpl {
         await this._coordinator.dispose();
         await this._eventBus.dispose();
         await this._memory.dispose();
+        // ADR-043: clear the shared LLM router singleton if we registered
+        // one. Prevents test isolation problems where a stale router from
+        // a previous kernel boot leaks into the next.
+        if (this._llmRouter) {
+            try {
+                const { resetSharedLLMRouter } = await import('../mcp/tools/base.js');
+                resetSharedLLMRouter();
+            }
+            catch {
+                // MCP module not loaded — fine.
+            }
+            this._llmRouter = undefined;
+            this._llmRouterBuild = undefined;
+        }
         this._initialized = false;
     }
     getDomainAPI(domain) {

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

@@ -78,6 +78,25 @@ export declare const MAX_Q_WEIGHT = 0.4;
  * decision. Adjust downward if cold-start latency proves problematic.
  */
 export declare const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * De-dilution cap for the domain-match denominator (#510 item 2).
+ *
+ * Domain score is `(domainMatch / denom) * 0.4`. The original `denom` was the
+ * full count of *detected* domains, but AQE's domain detector routinely emits
+ * 7-12 domains per task, so a perfect single-domain specialist scored
+ * `(1/11)*0.4 ≈ 0.04` — relevance washed out by detector breadth, leaving
+ * confidence dominated by the fixed performance term (measured easy task
+ * 37.3%, hard task 20.5%, with hard tasks mis-routing to high-performance
+ * but domain-irrelevant agents).
+ *
+ * Capping the denominator models the fact that a task has only a few *truly
+ * relevant* domains. With cap=3: a precise detector (1-2 domains) is
+ * unchanged, while a broad detector no longer dilutes a real match below
+ * usefulness. Proportionality across agents is preserved (an agent matching 2
+ * relevant domains still beats one matching 1). Tunable; raise toward the old
+ * behavior, lower to weight domain relevance more heavily.
+ */
+export declare const DOMAIN_DENOM_CAP = 3;
 /**
  * Q-value lookup callback supplied by the caller (QEReasoningBank.routeTask).
  * Returns undefined when the (stateKey, agentType) pair has no recorded

package/dist/learning/agent-routing.js

@@ -99,6 +99,25 @@ export const MAX_Q_WEIGHT = 0.4;
  * decision. Adjust downward if cold-start latency proves problematic.
  */
 export const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * De-dilution cap for the domain-match denominator (#510 item 2).
+ *
+ * Domain score is `(domainMatch / denom) * 0.4`. The original `denom` was the
+ * full count of *detected* domains, but AQE's domain detector routinely emits
+ * 7-12 domains per task, so a perfect single-domain specialist scored
+ * `(1/11)*0.4 ≈ 0.04` — relevance washed out by detector breadth, leaving
+ * confidence dominated by the fixed performance term (measured easy task
+ * 37.3%, hard task 20.5%, with hard tasks mis-routing to high-performance
+ * but domain-irrelevant agents).
+ *
+ * Capping the denominator models the fact that a task has only a few *truly
+ * relevant* domains. With cap=3: a precise detector (1-2 domains) is
+ * unchanged, while a broad detector no longer dilutes a real match below
+ * usefulness. Proportionality across agents is preserved (an agent matching 2
+ * relevant domains still beats one matching 1). Tunable; raise toward the old
+ * behavior, lower to weight domain relevance more heavily.
+ */
+export const DOMAIN_DENOM_CAP = 3;
 /**
  * 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
@@ -265,7 +284,14 @@ qValueLookup) {
         const reasoning = [];
         // Domain match (0-0.4)
         const domainMatch = detectedDomains.filter((d) => profile.domains.includes(d)).length;
-        const domainScore = domainMatch > 0 ? (domainMatch / detectedDomains.length) * 0.4 : 0;
+        // De-dilute by capping the denominator (#510 item 2): dividing by the full
+        // count of *detected* domains (7-12) washed out real matches. Cap models
+        // the few truly-relevant domains a task actually has. Math.min(...,1)
+        // guards the case where domainMatch exceeds the cap.
+        const domainDenom = Math.min(detectedDomains.length, DOMAIN_DENOM_CAP);
+        const domainScore = domainMatch > 0
+            ? Math.min(domainMatch / domainDenom, 1) * 0.4
+            : 0;
         score += domainScore * routingWeights.similarity;
         if (domainScore > 0) {
             reasoning.push(`Domain match: ${(domainScore * 100).toFixed(0)}%`);

package/dist/learning/dream/dream-scheduler.d.ts

@@ -101,42 +101,6 @@ export interface DreamSchedulerDependencies {
     /** Memory backend for persisting scheduler state (optional) */
     memoryBackend?: MemoryBackend;
 }
-/**
- * DreamScheduler manages automatic triggering of dream cycles.
- *
- * It follows the dependency injection pattern - all required dependencies
- * (DreamEngine, EventBus) must be provided via the constructor.
- *
- * @example
- * ```typescript
- * const scheduler = new DreamScheduler({
- *   dreamEngine,
- *   eventBus,
- *   memoryBackend, // optional
- * });
- *
- * await scheduler.initialize();
- * scheduler.start();
- *
- * // Record experiences as they happen
- * scheduler.recordExperience({
- *   id: 'exp-1',
- *   agentType: 'tester',
- *   domain: 'test-execution',
- *   taskType: 'run-tests',
- *   success: true,
- *   duration: 5000,
- *   timestamp: new Date(),
- * });
- *
- * // Manually trigger a dream
- * const result = await scheduler.triggerDream();
- *
- * // Stop and cleanup
- * scheduler.stop();
- * await scheduler.dispose();
- * ```
- */
 export declare class DreamScheduler {
     private readonly config;
     private readonly dreamEngine;
@@ -320,6 +284,17 @@ export declare class DreamScheduler {
      * Publish a dream completed event.
      */
     private publishDreamCompletedEvent;
+    /**
+     * #509: Reconcile the SessionStart-read `dream-scheduler:hook-state` row after
+     * a successful dream cycle. The post-task hook only ever INCREMENTS that row's
+     * experienceCount; this kernel scheduler is the entity that actually dreams
+     * (ADR-094) but historically never wrote it back, so the SessionStart readout
+     * showed lastDreamTime:null and a pendingExperiences counter that only grew.
+     * We stamp { lastDreamTime: now, experienceCount: 0, totalDreamsThisSession++ }
+     * using the SAME key + DEFAULT namespace the hook path uses. Best-effort: a
+     * failure here must never break a dream cycle.
+     */
+    private reconcileHookState;
     /**
      * Save scheduler state to memory backend.
      */

package/dist/learning/dream/dream-scheduler.js

@@ -81,6 +81,17 @@ export const DEFAULT_DREAM_SCHEDULER_CONFIG = {
  * await scheduler.dispose();
  * ```
  */
+/**
+ * kv_store key that the SessionStart hook reads for its dream readout and the
+ * post-task hook increments. Mirrors `DREAM_STATE_KEY` in
+ * cli/commands/hooks-handlers/hooks-dream-learning.ts — kept as a local literal
+ * (not imported) to avoid a learning→cli layering dependency. MUST match that
+ * value and use the DEFAULT namespace (the hook path passes no namespace).
+ * #509: this scheduler is the entity that actually dreams (ADR-094) but never
+ * reset this row, so SessionStart showed lastDreamTime:null + an ever-growing
+ * pendingExperiences. reconcileHookState() below stamps the truth per cycle.
+ */
+const DREAM_HOOK_STATE_KEY = 'dream-scheduler:hook-state';
 export class DreamScheduler {
     config;
     dreamEngine;
@@ -351,6 +362,10 @@ export class DreamScheduler {
             this.totalDreamsCompleted++;
             // Clear experience buffer after successful dream
             this.clearExperienceBuffer();
+            // #509: reconcile the SessionStart-read hook-state row. The post-task hook
+            // only increments its experienceCount and nothing on the active dream path
+            // reset it, so the readout was perpetually stale. Best-effort.
+            await this.reconcileHookState();
             // Auto-apply high-confidence insights if enabled
             if (this.config.autoApplyHighConfidenceInsights) {
                 await this.autoApplyInsights(result);
@@ -698,6 +713,35 @@ export class DreamScheduler {
     // ==========================================================================
     // Private: State Persistence
     // ==========================================================================
+    /**
+     * #509: Reconcile the SessionStart-read `dream-scheduler:hook-state` row after
+     * a successful dream cycle. The post-task hook only ever INCREMENTS that row's
+     * experienceCount; this kernel scheduler is the entity that actually dreams
+     * (ADR-094) but historically never wrote it back, so the SessionStart readout
+     * showed lastDreamTime:null and a pendingExperiences counter that only grew.
+     * We stamp { lastDreamTime: now, experienceCount: 0, totalDreamsThisSession++ }
+     * using the SAME key + DEFAULT namespace the hook path uses. Best-effort: a
+     * failure here must never break a dream cycle.
+     */
+    async reconcileHookState() {
+        if (!this.memoryBackend)
+            return;
+        try {
+            const prev = await this.memoryBackend.get(DREAM_HOOK_STATE_KEY);
+            const next = {
+                lastDreamTime: (this.lastDreamTime ?? new Date()).toISOString(),
+                experienceCount: 0,
+                sessionStartTime: prev?.sessionStartTime,
+                totalDreamsThisSession: (prev?.totalDreamsThisSession ?? 0) + 1,
+            };
+            await this.memoryBackend.set(DREAM_HOOK_STATE_KEY, next);
+        }
+        catch (err) {
+            logger.warn('Dream hook-state reconcile failed (non-critical)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     /**
      * Save scheduler state to memory backend.
      */

package/dist/learning/experience-consolidation.d.ts

@@ -18,6 +18,12 @@ import type { Database as DatabaseType } from 'better-sqlite3';
 export interface ConsolidationResult {
     /** Experiences merged into survivors */
     merged: number;
+    /**
+     * Experiences suppressed from retrieval because they CONTRADICT a
+     * higher-quality near-duplicate (similar context, opposite outcome).
+     * Soft-suppressed (consolidated_into = 'contradicted'), not deleted.
+     */
+    contradicted: number;
     /** Experiences with quality recalculated */
     qualityUpdated: number;
     /** Experiences soft-archived (Phase 3 valueless + Phase 4 safety valve) */
@@ -54,6 +60,16 @@ export interface ConsolidationConfig {
     archiveQualityThreshold: number;
     /** Quality boost per merged experience */
     mergeQualityBoost: number;
+    /**
+     * Contradiction detection (#510 item 7). Two experiences with cosine
+     * similarity >= this threshold but a quality delta >= contradictionQualityDelta
+     * are treated as "same context, opposite outcome" — a conflict, not a
+     * duplicate. The lower-quality loser is suppressed from retrieval instead of
+     * merged, so it can't poison recall.
+     */
+    contradictionSimilarityThreshold: number;
+    /** Min quality gap that turns a near-duplicate into a contradiction (0-1). */
+    contradictionQualityDelta: number;
 }
 export declare class ExperienceConsolidator {
     private readonly config;

package/dist/learning/experience-consolidation.js

@@ -25,6 +25,8 @@ const DEFAULT_CONFIG = {
     archiveMinAgeDays: 30,
     archiveQualityThreshold: 0.15,
     mergeQualityBoost: 0.02,
+    contradictionSimilarityThreshold: 0.85,
+    contradictionQualityDelta: 0.4,
 };
 // ============================================================================
 // ExperienceConsolidator
@@ -59,6 +61,7 @@ export class ExperienceConsolidator {
         this.ensureInitialized();
         const totalResult = {
             merged: 0,
+            contradicted: 0,
             qualityUpdated: 0,
             archived: 0,
             hardDeleted: 0,
@@ -73,6 +76,7 @@ export class ExperienceConsolidator {
         for (const { domain, cnt } of targetDomains) {
             const result = await this.consolidateDomain(domain, cnt);
             totalResult.merged += result.merged;
+            totalResult.contradicted += result.contradicted;
             totalResult.qualityUpdated += result.qualityUpdated;
             totalResult.archived += result.archived;
             totalResult.hardDeleted += result.hardDeleted;
@@ -81,8 +85,9 @@ export class ExperienceConsolidator {
         // Count total active remaining
         const activeCount = this.db.prepare("SELECT COUNT(*) as cnt FROM captured_experiences WHERE consolidated_into IS NULL").get();
         totalResult.activeRemaining = activeCount.cnt;
-        if (totalResult.merged > 0 || totalResult.archived > 0) {
+        if (totalResult.merged > 0 || totalResult.archived > 0 || totalResult.contradicted > 0) {
             console.log(`[ExperienceConsolidator] Consolidated: ${totalResult.merged} merged, ` +
+                `${totalResult.contradicted} contradicted, ` +
                 `${totalResult.archived} archived, ${totalResult.activeRemaining} active`);
         }
         return totalResult;
@@ -94,14 +99,17 @@ export class ExperienceConsolidator {
         this.ensureInitialized();
         const result = {
             merged: 0,
+            contradicted: 0,
             qualityUpdated: 0,
             archived: 0,
             hardDeleted: 0,
             activeRemaining: 0,
             domainsProcessed: [domain],
         };
-        // Phase 1: Cluster & Merge
-        result.merged = await this.clusterAndMerge(domain);
+        // Phase 1: Cluster & Merge (+ contradiction suppression)
+        const clusterResult = await this.clusterAndMerge(domain);
+        result.merged = clusterResult.merged;
+        result.contradicted = clusterResult.contradicted;
         // Phase 2: Quality Reinforcement
         result.qualityUpdated = this.reinforceQuality(domain);
         // Phase 3: Archive Valueless
@@ -129,7 +137,7 @@ export class ExperienceConsolidator {
         if (flag) {
             console.log(`[ExperienceConsolidator] Domain ${domain} already bootstrapped`);
             return {
-                merged: 0, qualityUpdated: 0, archived: 0,
+                merged: 0, contradicted: 0, qualityUpdated: 0, archived: 0,
                 hardDeleted: 0, activeRemaining: 0, domainsProcessed: [domain],
             };
         }
@@ -165,7 +173,7 @@ export class ExperienceConsolidator {
       ORDER BY quality DESC
     `).all(domain);
         if (candidates.length < 2)
-            return 0;
+            return { merged: 0, contradicted: 0 };
         // Build a temporary HNSW index for this domain
         const hnswIndex = new HNSWEmbeddingIndex({
             dimension: 384,
@@ -196,7 +204,9 @@ export class ExperienceConsolidator {
         // Track which IDs have been absorbed
         const absorbed = new Set();
         let mergeCount = 0;
+        let contradictionCount = 0;
         const markConsolidated = this.db.prepare("UPDATE captured_experiences SET consolidated_into = ? WHERE id = ?");
+        const markContradicted = this.db.prepare("UPDATE captured_experiences SET consolidated_into = 'contradicted' WHERE id = ?");
         const boostSurvivor = this.db.prepare(`
       UPDATE captured_experiences
       SET consolidation_count = consolidation_count + ?,
@@ -210,7 +220,7 @@ export class ExperienceConsolidator {
     `);
         // Iterate experiences by quality DESC
         for (const row of candidates) {
-            if (mergeCount >= this.config.maxMergesPerRun)
+            if (mergeCount + contradictionCount >= this.config.maxMergesPerRun)
                 break;
             if (absorbed.has(row.id))
                 continue;
@@ -232,21 +242,42 @@ export class ExperienceConsolidator {
                 namespace: 'experiences',
             });
             const mergedIds = [];
+            const contradictedIds = [];
             for (const { id: hnswId, distance } of neighbors) {
-                if (mergeCount >= this.config.maxMergesPerRun)
+                if (mergeCount + contradictionCount >= this.config.maxMergesPerRun)
                     break;
                 const neighborId = idMap.get(hnswId);
                 if (!neighborId || neighborId === row.id || absorbed.has(neighborId))
                     continue;
                 const similarity = 1 - distance;
-                if (similarity < this.config.mergeSimilarityThreshold)
+                // Gate on the lower of the two thresholds so neither merge nor
+                // contradiction detection is starved if they are configured differently.
+                if (similarity < Math.min(this.config.mergeSimilarityThreshold, this.config.contradictionSimilarityThreshold))
                     continue;
                 // Find the neighbor in candidates
                 const neighbor = candidates.find(c => c.id === neighborId);
                 if (!neighbor)
                     continue;
-                // Only merge lower-quality, unused neighbors into the survivor
-                if (neighbor.quality <= row.quality && neighbor.application_count === 0) {
+                // Contradiction (#510 item 7): same context (high similarity) but
+                // opposite outcome (large quality delta) => a conflict, not a duplicate.
+                // Suppress the lower-quality loser from retrieval even if it was applied
+                // (a used-but-low-quality contradictory experience is exactly the
+                // recall-poisoning case). Candidates are sorted quality DESC and absorbed
+                // ones are skipped, so when a gap exists `neighbor` is the strict loser.
+                const qualityDelta = Math.abs(row.quality - neighbor.quality);
+                if (similarity >= this.config.contradictionSimilarityThreshold
+                    && qualityDelta >= this.config.contradictionQualityDelta) {
+                    if (neighbor.quality < row.quality) {
+                        absorbed.add(neighborId);
+                        contradictedIds.push(neighborId);
+                        contradictionCount++;
+                    }
+                    continue; // never merge a contradictory pair
+                }
+                // Only merge lower-quality, unused neighbors into the survivor (requires
+                // the normal merge similarity threshold).
+                if (similarity >= this.config.mergeSimilarityThreshold
+                    && neighbor.quality <= row.quality && neighbor.application_count === 0) {
                     absorbed.add(neighborId);
                     mergedIds.push(neighborId);
                     mergeCount++;
@@ -264,10 +295,23 @@ export class ExperienceConsolidator {
                 });
                 transaction();
             }
+            // Apply contradiction suppressions in a transaction. The loser is
+            // soft-suppressed (consolidated_into = 'contradicted'), so it is excluded
+            // from retrieval (WHERE consolidated_into IS NULL) but not deleted. The
+            // survivor is NOT boosted — a contradiction is a conflict, not a duplicate.
+            if (contradictedIds.length > 0) {
+                const tx = this.db.transaction(() => {
+                    for (const loserId of contradictedIds) {
+                        markContradicted.run(loserId);
+                    }
+                    logConsolidation.run(uuidv4(), domain, 'contradiction', JSON.stringify(contradictedIds), row.id, JSON.stringify({ count: contradictedIds.length, survivorQuality: row.quality }));
+                });
+                tx();
+            }
         }
         // Clean up HNSW index
         hnswIndex.clearIndex('experiences');
-        return mergeCount;
+        return { merged: mergeCount, contradicted: contradictionCount };
     }
     // ============================================================================
     // Phase 2: Quality Reinforcement

package/dist/learning/pattern-lifecycle.d.ts

@@ -42,6 +42,27 @@ export interface PatternLifecycleConfig {
  * Default lifecycle configuration
  */
 export declare const DEFAULT_LIFECYCLE_CONFIG: PatternLifecycleConfig;
+/** Minimum usage_count before success_rate is trusted as an importance signal. */
+export declare const EWC_MIN_USAGE_FOR_PROTECTION = 5;
+/**
+ * Fraction of the base decay rate a fully-important pattern is shielded from.
+ * 0.9 => a success_rate=1.0 pattern decays at 10% of the base rate.
+ * Low-importance patterns (importance 0) decay EXACTLY as before (no regression).
+ */
+export declare const EWC_DECAY_PROTECTION = 0.9;
+/**
+ * Multiplier extending the stale window by importance.
+ * effectiveStaleDays = staleDaysThreshold * (1 + importance * EWC_STALE_PROTECTION_BONUS).
+ * 2 => a fully-important pattern survives 3x longer unused (e.g. 30d -> 90d)
+ * before stale-deprecation; importance-0 patterns are unchanged.
+ */
+export declare const EWC_STALE_PROTECTION_BONUS = 2;
+/**
+ * Importance proxy in [0,1] for EWC++ forgetting protection.
+ * Returns 0 (no protection) until a pattern has been used enough to trust its
+ * success rate, then equals the clamped success rate.
+ */
+export declare function patternImportance(successRate: number, usageCount: number): number;
 /**
  * Experience aggregation for pattern candidate identification
  */