agentic-qe 3.11.0 → 3.11.2

package/dist/domains/code-intelligence/services/product-factors-bridge.js

@@ -18,8 +18,10 @@ import * as fs from 'fs/promises';
 import { ok, err } from '../../../shared/types';
 import { CodeIntelligenceEvents, createEvent, } from '../../../shared/events/domain-events';
 import { toError } from '../../../shared/error-utils.js';
-import { isCacheValid, sanitizeId, inferComponentType, } from '../../../shared/c4-model';
+import { isCacheValid, sanitizeId, inferComponentType, assessC4Confidence, } from '../../../shared/c4-model';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { C4ModelService } from './c4-model';
+import { toContextRequest, toContainerRequest, toComponentRequest, } from './c4-model/from-detected';
 const DEFAULT_CONFIG = {
     cacheTtlMs: 3600000, // 1 hour
     publishEvents: true,
@@ -96,11 +98,26 @@ export class ProductFactorsBridgeService {
     config;
     initialized = false;
     eventSubscriptions = [];
+    /** ADR-112: the consolidated render+analyze+store engine (lazily built). */
+    c4Service;
     constructor(eventBus, memory, config = {}) {
         this.eventBus = eventBus;
         this.memory = memory;
         this.config = { ...DEFAULT_CONFIG, ...config };
     }
+    /**
+     * ADR-112: lazily construct the shared C4ModelService.
+     * Embeddings are OFF on this internal product-factors path (keeps it offline +
+     * fast); the CLI/MCP surfaces opt embeddings in when semantic search is wanted.
+     */
+    getC4Service() {
+        if (!this.c4Service) {
+            this.c4Service = new C4ModelService(this.memory, {
+                enableEmbeddings: this.config.enableC4Embeddings ?? false,
+            });
+        }
+        return this.c4Service;
+    }
     // ==========================================================================
     // Lifecycle
     // ==========================================================================
@@ -130,7 +147,7 @@ export class ProductFactorsBridgeService {
         const sub2 = this.eventBus.subscribe(CodeIntelligenceEvents.ImpactAnalysisCompleted, this.handleImpactAnalysisCompleted.bind(this));
         this.eventSubscriptions.push(sub2);
     }
-    async handleKnowledgeGraphUpdated(event) {
+    async handleKnowledgeGraphUpdated(_event) {
         // Invalidate relevant caches when knowledge graph is updated
         logger.info('[ProductFactorsBridge] Knowledge graph updated, considering cache invalidation');
         // Note: We don't have project path in this event, so we rely on hash-based invalidation
@@ -198,30 +215,40 @@ export class ProductFactorsBridgeService {
             if (request.analyzeCoupling && components.length > 1) {
                 couplingAnalysis = this.analyzeCoupling(components, relationships);
             }
-            // Generate diagrams
+            // Generate diagrams. ADR-112: the three C4 levels render through the
+            // consolidated C4ModelService (richer + stored + searchable); the bridge
+            // keeps only detection. Inline generators remain as a safety fallback.
             const diagrams = {};
             if (request.includeContext !== false) {
-                diagrams.context = this.generateContextDiagram(projectInfo, externalSystems);
+                diagrams.context = await this.renderContext(projectInfo, externalSystems);
             }
             if (request.includeContainer !== false) {
-                diagrams.container = this.generateContainerDiagram(projectInfo, externalSystems);
+                diagrams.container = await this.renderContainer(projectInfo, externalSystems);
             }
             if (request.includeComponent !== false && components.length > 0) {
-                diagrams.component = this.generateComponentDiagram(projectInfo.name, components, relationships);
+                diagrams.component = await this.renderComponent(projectInfo, components, relationships);
             }
             if (request.includeDependency && components.length > 0) {
                 diagrams.dependency = this.generateDependencyGraph(components, relationships);
             }
+            const filesAnalyzed = components.reduce((sum, c) => sum + c.files.length, 0);
             const metadata = {
                 projectName: projectInfo.name,
                 projectDescription: projectInfo.description,
                 generatedAt: new Date(),
                 source: 'codebase-analysis',
                 analysisMetadata: {
-                    filesAnalyzed: components.reduce((sum, c) => sum + c.files.length, 0),
+                    filesAnalyzed,
                     componentsDetected: components.length,
                     externalSystemsDetected: externalSystems.length,
                     analysisTimeMs: Date.now() - startTime,
+                    // ADR-112: deterministic confidence gate — never present a wrong diagram as truth.
+                    confidence: assessC4Confidence({
+                        componentsDetected: components.length,
+                        relationshipsDetected: relationships.length,
+                        externalSystemsDetected: externalSystems.length,
+                        filesAnalyzed,
+                    }),
                 },
             };
             return ok({
@@ -239,70 +266,37 @@ export class ProductFactorsBridgeService {
         }
     }
     // ==========================================================================
-    // IC4DiagramGenerator Implementation
+    // ADR-112: render via the consolidated C4ModelService (the single engine).
+    // On failure we FAIL LOUD — propagate the error so the caller surfaces it —
+    // rather than silently degrading to a weaker inline diagram. A masked render
+    // failure is worse than a surfaced one (ADR-050: no silent degradation).
     // ==========================================================================
-    generateContextDiagram(project, externalSystems) {
-        let mermaid = `C4Context
-  title System Context diagram for ${project.name}
-
-  Person(user, "User", "A user of the system")
-  System(system, "${project.name}", "${project.description}")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  System_Ext(${sys.id}, "${sys.name}", "${sys.type}")
-`;
-        }
-        mermaid += `
-  Rel(user, system, "Uses")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  Rel(system, ${sys.id}, "${sys.relationship}")
-`;
+    async renderContext(projectInfo, externalSystems) {
+        const res = await this.getC4Service().buildContext(toContextRequest(projectInfo, externalSystems));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 context render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
-    generateContainerDiagram(project, externalSystems) {
-        let mermaid = `C4Container
-  title Container diagram for ${project.name}
-
-  Person(user, "User", "A user of the system")
-
-  Container_Boundary(c1, "${project.name}") {
-    Container(app, "Application", "TypeScript", "Main application")
-  }
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  System_Ext(${sys.id}, "${sys.name}", "${sys.type}")
-`;
-        }
-        mermaid += `
-  Rel(user, app, "Uses")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  Rel(app, ${sys.id}, "${sys.relationship}")
-`;
+    async renderContainer(projectInfo, externalSystems) {
+        const res = await this.getC4Service().buildContainer(toContainerRequest(projectInfo, externalSystems));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 container render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
-    generateComponentDiagram(projectName, components, relationships) {
-        let mermaid = `C4Component
-  title Component diagram for ${projectName}
-
-  Container_Boundary(app, "Application") {
-`;
-        for (const comp of components) {
-            const responsibility = comp.responsibilities?.[0] || '';
-            mermaid += `    Component(${comp.id}, "${comp.name}", "${comp.technology || 'TypeScript'}", "${responsibility}")
-`;
-        }
-        mermaid += `  }
-`;
-        for (const rel of relationships) {
-            mermaid += `  Rel(${rel.sourceId}, ${rel.targetId}, "${rel.type}")
-`;
+    async renderComponent(projectInfo, components, relationships) {
+        const res = await this.getC4Service().buildComponent(toComponentRequest(components, relationships));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 component render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
+    // The dependency graph is NOT a C4 level and C4ModelService does not render
+    // it, so this stays as the bridge's own renderer.
     generateDependencyGraph(components, relationships) {
         let mermaid = `graph TD
 `;
@@ -439,6 +433,19 @@ export class ProductFactorsBridgeService {
         catch (error) {
             logger.error('Component analysis failed:', error instanceof Error ? error : undefined);
         }
+        // ADR-112 C2: prefer REAL KG-derived edges (AST import/call graph) over the
+        // naming heuristic. The resolver returns null on any miss → heuristic stands.
+        if (this.config.relationshipResolver && components.length > 0) {
+            try {
+                const resolved = await this.config.relationshipResolver(components, projectPath);
+                if (resolved && resolved.length > 0) {
+                    return { components, relationships: resolved };
+                }
+            }
+            catch (error) {
+                logger.debug(`KG relationship resolver failed; using heuristic: ${toError(error).message}`);
+            }
+        }
         return { components, relationships };
     }
     shouldExclude(name) {
@@ -473,7 +480,7 @@ export class ProductFactorsBridgeService {
                     }
                 }
             }
-            catch (error) {
+            catch {
                 // Non-critical: permission errors when scanning directories
                 logger.debug('Directory scan error:');
             }

package/dist/domains/requirements-validation/coordinator.d.ts

@@ -9,6 +9,7 @@
 import { Result } from '../../shared/types/index.js';
 import { EventBus, MemoryBackend, AgentCoordinator } from '../../kernel/interfaces.js';
 import type { HybridRouter } from '../../shared/llm/router/hybrid-router.js';
+import { type FreeTierCoordinatorConfig, type RoutingFeedbackLike } from '../../routing/free-tier/index.js';
 import { IRequirementsValidationCoordinator, RequirementAnalysis, TestArtifacts, SprintValidation } from './interfaces.js';
 import { BaseDomainCoordinator, type BaseDomainCoordinatorConfig } from '../base-domain-coordinator.js';
 import { type DomainFinding } from '../../coordination/consensus/domain-findings.js';
@@ -22,7 +23,7 @@ export declare const RequirementsValidationEvents: {
 /**
  * CQ-002: Extends BaseDomainCoordinatorConfig — removes duplicate fields
  */
-export interface CoordinatorConfig extends BaseDomainCoordinatorConfig {
+export interface CoordinatorConfig extends BaseDomainCoordinatorConfig, FreeTierCoordinatorConfig {
     minTestabilityThreshold: number;
     enablePPO: boolean;
     enableSONA: boolean;
@@ -45,10 +46,14 @@ export declare class RequirementsValidationCoordinator extends BaseDomainCoordin
     private readonly bddWriter;
     private readonly testabilityScorer;
     private readonly repository;
+    /** Opt-in cheap-first BDD scenario generation (plan 06, ADR-111). Null = off. */
+    private readonly freeTierExecutor;
     private ppoAlgorithm?;
     private sonaEngine?;
     private rlInitialized;
-    constructor(eventBus: EventBus, memory: MemoryBackend, agentCoordinator: AgentCoordinator, config?: Partial<CoordinatorConfig>, llmRouter?: HybridRouter);
+    constructor(eventBus: EventBus, memory: MemoryBackend, agentCoordinator: AgentCoordinator, config?: Partial<CoordinatorConfig>, llmRouter?: HybridRouter, 
+    /** Optional D9 sink — when provided, free-tier outcomes feed routing-feedback. */
+    routingFeedback?: RoutingFeedbackLike | null);
     /**
      * Initialize the coordinator
      * CQ-002: Domain-specific initialization
@@ -74,6 +79,15 @@ export declare class RequirementsValidationCoordinator extends BaseDomainCoordin
     /**
      * Generate test artifacts from requirement
      */
+    /**
+     * Cheap-first BDD generation (plan 06 broadening; ADR-111 escalation lane).
+     * Generates raw Gherkin on the free local tier (best-effort), verifies Gherkin
+     * STRUCTURE as the objective oracle (§10 — never the model's own judgement),
+     * parses it back into structured scenarios, and escalates the hard tail via the
+     * router. Returns null when off or nothing usable → caller falls back to the
+     * normal structured path. Off by default.
+     */
+    private tryFreeTierScenarios;
     generateTestArtifacts(requirementId: string): Promise<Result<TestArtifacts>>;
     /**
      * Validate sprint requirements

package/dist/domains/requirements-validation/coordinator.js

@@ -10,6 +10,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { LoggerFactory } from '../../logging/index.js';
 import { ok, err } from '../../shared/types/index.js';
 import { toError } from '../../shared/error-utils.js';
+import { buildFreeTierExecutor, } from '../../routing/free-tier/index.js';
 import { createEvent } from '../../shared/events/domain-events.js';
 import { RequirementsValidatorService } from './services/requirements-validator.js';
 import { BDDScenarioWriterService } from './services/bdd-scenario-writer.js';
@@ -93,6 +94,25 @@ class InMemoryRequirementRepository {
  * CQ-002: Extends BaseDomainCoordinator
  */
 const logger = LoggerFactory.create('requirements-validation');
+/** Strip a ```gherkin fence (truncation-robust); else return the text as-is. */
+function stripGherkinFence(s) {
+    s = (s ?? '').trim();
+    const full = /```(?:gherkin|feature)?\s*([\s\S]*?)```/.exec(s);
+    if (full)
+        return full[1].trim();
+    const open = /```(?:gherkin|feature)?[^\n]*\n([\s\S]*)$/.exec(s);
+    return open ? open[1].trim() : s;
+}
+const GHERKIN_STOPWORDS = new Set([
+    'given', 'when', 'then', 'scenario', 'feature', 'with', 'that', 'this', 'from', 'into',
+    'should', 'must', 'have', 'will', 'shall', 'able', 'user', 'users', 'system', 'value',
+    'valid', 'invalid', 'returns', 'return', 'apply', 'using', 'based', 'their', 'they',
+]);
+/** Significant lowercased terms (>3 chars, non-stopword) from a requirement. */
+function significantTerms(requirement) {
+    const src = `${requirement.title} ${(requirement.acceptanceCriteria ?? []).join(' ')}`.toLowerCase();
+    return Array.from(new Set(src.match(/[a-z][a-z0-9]{3,}/g) ?? [])).filter((w) => !GHERKIN_STOPWORDS.has(w));
+}
 export class RequirementsValidationCoordinator extends BaseDomainCoordinator {
     memory;
     agentCoordinator;
@@ -100,11 +120,15 @@ export class RequirementsValidationCoordinator extends BaseDomainCoordinator {
     bddWriter;
     testabilityScorer;
     repository;
+    /** Opt-in cheap-first BDD scenario generation (plan 06, ADR-111). Null = off. */
+    freeTierExecutor;
     // V3: RL and SONA integrations
     ppoAlgorithm;
     sonaEngine;
     rlInitialized = false;
-    constructor(eventBus, memory, agentCoordinator, config = {}, llmRouter) {
+    constructor(eventBus, memory, agentCoordinator, config = {}, llmRouter, 
+    /** Optional D9 sink — when provided, free-tier outcomes feed routing-feedback. */
+    routingFeedback) {
         const fullConfig = { ...DEFAULT_CONFIG, ...config };
         super(eventBus, 'requirements-validation', fullConfig, {
             verifyFindingTypes: ['requirement-conflict', 'testability-assessment', 'ambiguous-requirement'],
@@ -116,6 +140,16 @@ export class RequirementsValidationCoordinator extends BaseDomainCoordinator {
         this.bddWriter = new BDDScenarioWriterService(memory);
         this.testabilityScorer = new TestabilityScorerService(memory);
         this.repository = new InMemoryRequirementRepository(memory);
+        // Opt-in cheap-first BDD generation (plan 06 broadening; ADR-111 escalation
+        // lane). OFF by default; BDD/Gherkin is a bounded-gen + objective-oracle fit.
+        this.freeTierExecutor = buildFreeTierExecutor({
+            config: this.config,
+            agentType: 'qe-requirements-validator',
+            taskKind: 'requirements-validation',
+            llmRouter,
+            routingFeedback, // D9 sink (undefined unless wired by the plugin)
+            logger,
+        });
     }
     // ==========================================================================
     // BaseDomainCoordinator Template Methods
@@ -294,6 +328,72 @@ export class RequirementsValidationCoordinator extends BaseDomainCoordinator {
     /**
      * Generate test artifacts from requirement
      */
+    /**
+     * Cheap-first BDD generation (plan 06 broadening; ADR-111 escalation lane).
+     * Generates raw Gherkin on the free local tier (best-effort), verifies Gherkin
+     * STRUCTURE as the objective oracle (§10 — never the model's own judgement),
+     * parses it back into structured scenarios, and escalates the hard tail via the
+     * router. Returns null when off or nothing usable → caller falls back to the
+     * normal structured path. Off by default.
+     */
+    async tryFreeTierScenarios(requirement, scenarioCount) {
+        if (!this.freeTierExecutor)
+            return null;
+        const ac = (requirement.acceptanceCriteria ?? []).map((c, i) => `${i + 1}. ${c}`).join('\n');
+        const system = 'You write Gherkin .feature files. Output ONLY a single fenced ```gherkin code block — no prose.';
+        const user = `Write a Gherkin feature with ~${scenarioCount} scenarios for this requirement. ` +
+            'Use Feature/Scenario/Given/When/Then; cover the acceptance criteria and edge cases.\n\n' +
+            `Title: ${requirement.title}\nDescription: ${requirement.description}\n` +
+            (ac ? `Acceptance criteria:\n${ac}\n` : '');
+        // Objective oracle (structural proxy — does NOT execute the scenarios). Beyond
+        // bare structure it requires: parses to >=1 scenario, EVERY scenario has a
+        // non-empty Given/When/Then, AND the feature is RELEVANT to the requirement
+        // (token overlap) — so generic off-topic boilerplate is rejected, not rewarded
+        // (resists the §10 Goodhart trap). Still a proxy, not semantic ground truth.
+        const sigTerms = significantTerms(requirement);
+        const verify = (out) => {
+            const text = stripGherkinFence(out);
+            const structural = /\bFeature:/i.test(text) && /\bScenario:/i.test(text) &&
+                /\bGiven\b/i.test(text) && /\bWhen\b/i.test(text) && /\bThen\b/i.test(text);
+            if (!structural) {
+                return { passed: false, feedback: 'must be valid Gherkin: Feature:, Scenario:, and Given/When/Then steps' };
+            }
+            const parsed = this.bddWriter.parseGherkin(text);
+            if (!parsed.success || parsed.value.length === 0) {
+                return { passed: false, feedback: 'Gherkin did not parse into any scenario' };
+            }
+            const wellFormed = parsed.value.every((s) => s.given.length > 0 && s.when.length > 0 && s.then.length > 0);
+            if (!wellFormed) {
+                return { passed: false, feedback: 'every scenario needs at least one Given, one When, and one Then step' };
+            }
+            if (sigTerms.length > 0) {
+                const lower = text.toLowerCase();
+                const hits = sigTerms.filter((t) => lower.includes(t)).length;
+                if (hits < Math.min(2, sigTerms.length)) {
+                    return { passed: false, feedback: `scenarios must address THIS requirement — reference its terms (e.g. ${sigTerms.slice(0, 6).join(', ')})` };
+                }
+            }
+            return { passed: true };
+        };
+        const r = await this.freeTierExecutor.execute({
+            agentId: `requirements:${requirement.id}`,
+            messages: [
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ],
+            verify,
+            escalate: true,
+            bestOfK: this.config.freeTierBestOfK ?? 2, // §12, matches the D3-validated config
+            repairAttempts: this.config.freeTierRepairAttempts ?? 1,
+        });
+        if (!r.ok)
+            return null;
+        const parsed = this.bddWriter.parseGherkin(stripGherkinFence(r.content));
+        if (!parsed.success || parsed.value.length === 0)
+            return null;
+        logger.info(`Free-tier BDD scenarios for ${requirement.id} via tier=${r.tierUsed} (${parsed.value.length} scenarios)`);
+        return parsed.value;
+    }
     async generateTestArtifacts(requirementId) {
         const workflowId = uuidv4();
         try {
@@ -320,15 +420,20 @@ export class RequirementsValidationCoordinator extends BaseDomainCoordinator {
                     logger.info(`[PPO] Optimized scenario count to ${optimizedScenarioCount}`);
                 }
             }
-            // Generate BDD scenarios with optimized count
-            const scenariosResult = await this.bddWriter.generateScenariosWithExamples(requirement, optimizedScenarioCount);
-            if (!scenariosResult.success) {
-                this.failWorkflow(workflowId, scenariosResult.error.message);
-                return err(scenariosResult.error);
+            // Cheap-first (opt-in, ADR-111): generate Gherkin on the free local tier,
+            // verify its structure (objective oracle), parse back to scenarios. Falls
+            // through to the normal structured path on any miss (off by default).
+            let scenarios = await this.tryFreeTierScenarios(requirement, optimizedScenarioCount);
+            if (!scenarios) {
+                const scenariosResult = await this.bddWriter.generateScenariosWithExamples(requirement, optimizedScenarioCount);
+                if (!scenariosResult.success) {
+                    this.failWorkflow(workflowId, scenariosResult.error.message);
+                    return err(scenariosResult.error);
+                }
+                scenarios = scenariosResult.value;
             }
             this.updateWorkflowProgress(workflowId, 50);
             // V3: Use PPO to optimize scenario ordering
-            let scenarios = scenariosResult.value;
             if (this.config.enablePPO && this.ppoAlgorithm) {
                 scenarios = await this.optimizeScenarioOrdering(requirement, scenarios);
             }

package/dist/domains/requirements-validation/plugin.js

@@ -9,6 +9,7 @@ import { RequirementsValidatorService, } from './services/requirements-validator
 import { BDDScenarioWriterService, } from './services/bdd-scenario-writer.js';
 import { TestabilityScorerService, } from './services/testability-scorer.js';
 import { createQCSDIdeationPlugin, } from './qcsd-ideation-plugin.js';
+import { RoutingFeedbackCollector } from '../../routing/routing-feedback.js';
 import { toError } from '../../shared/error-utils.js';
 // ============================================================================
 // Plugin Implementation
@@ -171,8 +172,26 @@ export class RequirementsValidationPlugin extends BaseDomainPlugin {
         this.validator = new RequirementsValidatorService({ memory: this.memory, llmRouter: this.llmRouter }, this.pluginConfig.validator);
         this.bddWriter = new BDDScenarioWriterService(this.memory, this.pluginConfig.bddWriter);
         this.testabilityScorer = new TestabilityScorerService(this.memory, this.pluginConfig.testabilityScorer);
+        // D9: when the free tier is opted in, stand up a live RoutingFeedbackCollector
+        // (calibrator + auto-escalation) so each cheap-vs-escalated BDD outcome feeds
+        // routing confidence. Memory-only fallback if the DB is unavailable.
+        let routingFeedback;
+        const freeTierOn = this.pluginConfig.coordinator?.enableFreeTier === true || process.env.AQE_FREE_TIER === '1';
+        if (freeTierOn) {
+            routingFeedback = new RoutingFeedbackCollector(10000, {
+                enableEMACalibration: true,
+                enableAutoEscalation: true,
+            });
+            try {
+                await routingFeedback.initialize();
+            }
+            catch {
+                // memory-only is fine — recording still drives calibration/escalation
+            }
+        }
         // Create and initialize coordinator
-        this.coordinator = new RequirementsValidationCoordinator(this.eventBus, this.memory, this.agentCoordinator, this.pluginConfig.coordinator, this.llmRouter);
+        this.coordinator = new RequirementsValidationCoordinator(this.eventBus, this.memory, this.agentCoordinator, this.pluginConfig.coordinator, this.llmRouter, routingFeedback // D9 sink (undefined unless free tier is on)
+        );
         await this.coordinator.initialize();
         // Create and initialize QCSD Ideation Plugin
         this.qcsdIdeationPlugin = createQCSDIdeationPlugin(this.memory);

package/dist/domains/test-generation/coordinator.d.ts

@@ -68,10 +68,12 @@ export interface CoordinatorConfig extends BaseDomainCoordinatorConfig {
      * — also enables via env `AQE_FREE_TIER=1`. Local-only / no paid escalation yet.
      */
     enableFreeTier?: boolean;
-    /** Local model id for the free tier (default 'qwen3:8b' or env AQE_FREE_TIER_MODEL). */
+    /** Local model id for the free tier (default qwen3:30b-a3b or env AQE_FREE_TIER_MODEL). */
     freeTierModel?: string;
     /** Same-tier repair retries on a failed free-tier generation (D8). Default 1. */
     freeTierRepairAttempts?: number;
+    /** Best-of-k diverse local attempts per tier (§12; D3-validated k=2). Default 2. */
+    freeTierBestOfK?: number;
 }
 type TestGenWorkflowType = 'generate' | 'tdd' | 'property' | 'data' | 'learn';
 export declare class TestGenerationCoordinator extends BaseDomainCoordinator<CoordinatorConfig, TestGenWorkflowType> implements ITestGenerationCoordinator {

package/dist/domains/test-generation/coordinator.js

@@ -13,7 +13,7 @@ import { readFile } from 'node:fs/promises';
 import { ok, err, } from '../../shared/types';
 import { toError } from '../../shared/error-utils.js';
 // Opt-in free-tier local test generation (cross-pollination plan 06, D7-wire/D8/D9).
-import { FreeTierEscalatingExecutor, defaultFreeTierLadder, createRoutingFeedbackSink, } from '../../routing/free-tier/index.js';
+import { buildFreeTierExecutor, } from '../../routing/free-tier/index.js';
 import { TestGenerationEvents, LearningOptimizationEvents, createEvent, } from '../../shared/events/domain-events';
 import { createTestGeneratorServiceWithDependencies, } from './services/test-generator';
 import { PatternMatcherService, } from './services/pattern-matcher';
@@ -123,36 +123,16 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
         // ADR-043 wiring: dependencies factory accepts llmRouter.
         this.testGenerator = createTestGeneratorServiceWithDependencies({ memory, llmRouter });
         this.patternMatcher = new PatternMatcherService(memory);
-        // Opt-in free-tier local generation (plan 06, D7-wire/D8/D9). OFF by default;
-        // local-only with a same-tier repair loop and NO paid escalation yet.
-        const freeTierOn = this.config.enableFreeTier === true || process.env.AQE_FREE_TIER === '1';
-        if (freeTierOn) {
-            const model = this.config.freeTierModel || process.env.AQE_FREE_TIER_MODEL || 'qwen3:8b';
-            // Paid escalation: delegate Claude tiers to the existing HybridRouter, mapping
-            // the ladder tier to a complexity hint so the router selects that tier. When no
-            // router is wired, the executor stays local-only (Claude tiers report unavailable).
-            const claudeRunner = llmRouter
-                ? async (tier, msgs) => {
-                    const complexity = tier === 'opus' ? 'high' : tier === 'sonnet' ? 'medium' : 'low';
-                    const resp = await llmRouter.chat({
-                        messages: msgs.map((m) => ({ role: m.role, content: m.content })),
-                        agentType: 'qe-test-architect',
-                        complexity,
-                    });
-                    return { content: resp.content };
-                }
-                : undefined;
-            this.freeTierExecutor = new FreeTierEscalatingExecutor({
-                ladder: defaultFreeTierLadder(model),
-                claudeRunner,
-                defaultRepairAttempts: this.config.freeTierRepairAttempts ?? 1,
-                onOutcome: routingFeedback
-                    ? createRoutingFeedbackSink(routingFeedback, { taskKind: 'test-generation' }) // D9
-                    : undefined,
-            });
-            logger.info(`Free-tier local test generation enabled (model=${model}, repair, ` +
-                `${claudeRunner ? 'escalation→HybridRouter' : 'local-only'})`);
-        }
+        // Opt-in free-tier local generation (plan 06, D7-wire/D8/D9; ADR-111).
+        // OFF by default. Generic wiring lives in the shared factory now.
+        this.freeTierExecutor = buildFreeTierExecutor({
+            config: this.config,
+            agentType: 'qe-test-architect',
+            taskKind: 'test-generation',
+            llmRouter,
+            routingFeedback,
+            logger,
+        });
         // Initialize coherence gate if service is provided (ADR-052)
         if (this.config.enableCoherenceGate && coherenceService) {
             this.coherenceGate = createTestGenerationCoherenceGate(coherenceService, undefined, // Use default embedding service
@@ -472,9 +452,11 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
             agentId: `test-gen:${src}`,
             messages,
             verify,
-            // Cheap-first: try local + repair, then escalate the hard tail up the
-            // ladder via the HybridRouter (when wired). Local-only if no router.
+            // Cheap-first: best-of-k (§12) + repair on the local tier, then escalate the
+            // hard tail up the ladder via the HybridRouter (when wired). Matches the D3
+            // config that was validated (k=2). Local-only if no router.
             escalate: true,
+            bestOfK: this.config.freeTierBestOfK ?? 2,
             repairAttempts: this.config.freeTierRepairAttempts ?? 1,
         });
         if (!r.ok)

package/dist/integrations/darwin/types.d.ts

@@ -5,10 +5,17 @@
  * `packages/darwin-mode/src/types.ts` (ADR-072 ScoreCard) so AQE can produce
  * Darwin-compatible scores WITHOUT a build-time dependency on the pre-1.0
  * MetaHarness package (per cross-pollination plan 05: Phase-0 actions stay
- * decoupled). If/when a version contract lands (plan A8), replace this with a
- * real import.
+ * decoupled).
  *
- * Source of truth at time of writing: @metaharness/darwin@0.2.1.
+ * VERSION CONTRACT (plan A8, verified 2026-06-25): `DarwinScoreCard` is byte-for-
+ * byte structurally identical to upstream `ScoreCard` from @metaharness/darwin@0.2.1
+ * THROUGH @0.7.0 (no drift across 5 minors). The mirror is INTENTIONALLY KEPT, not
+ * replaced by a real import: the upstream is a fast-moving pre-1.0 package whose
+ * tarball pulls napi/wasm transitive deps, so the zero-coupling mirror is the lower-
+ * risk substrate (see plan 05 "A8 — status"). `tests/.../darwin-version-contract.test.ts`
+ * pins the mirror's field set so any divergence is caught.
+ *
+ * Pinned upstream contract: @metaharness/darwin ScoreCard @ 0.2.1–0.7.0.
  */
 /** The seven mutation surfaces (mirror of Darwin's MutationSurface). */
 export type MutationSurface = 'planner' | 'contextBuilder' | 'reviewer' | 'retryPolicy' | 'toolPolicy' | 'memoryPolicy' | 'scorePolicy';

package/dist/integrations/darwin/types.js

@@ -5,10 +5,17 @@
  * `packages/darwin-mode/src/types.ts` (ADR-072 ScoreCard) so AQE can produce
  * Darwin-compatible scores WITHOUT a build-time dependency on the pre-1.0
  * MetaHarness package (per cross-pollination plan 05: Phase-0 actions stay
- * decoupled). If/when a version contract lands (plan A8), replace this with a
- * real import.
+ * decoupled).
  *
- * Source of truth at time of writing: @metaharness/darwin@0.2.1.
+ * VERSION CONTRACT (plan A8, verified 2026-06-25): `DarwinScoreCard` is byte-for-
+ * byte structurally identical to upstream `ScoreCard` from @metaharness/darwin@0.2.1
+ * THROUGH @0.7.0 (no drift across 5 minors). The mirror is INTENTIONALLY KEPT, not
+ * replaced by a real import: the upstream is a fast-moving pre-1.0 package whose
+ * tarball pulls napi/wasm transitive deps, so the zero-coupling mirror is the lower-
+ * risk substrate (see plan 05 "A8 — status"). `tests/.../darwin-version-contract.test.ts`
+ * pins the mirror's field set so any divergence is caught.
+ *
+ * Pinned upstream contract: @metaharness/darwin ScoreCard @ 0.2.1–0.7.0.
  */
 export {};
 //# sourceMappingURL=types.js.map