agentic-qe 3.11.0 → 3.11.1

package/dist/cli/chunks/{wrappers-M5C7DONW.js → wrappers-3STST7QW.js}

@@ -1,2 +1,2 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.11.0");process.exit(0)}
-import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-MTSMFEWK.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-QZQGYSDG.js";import"./chunk-QYXTESM3.js";import"./chunk-L7GQKJLV.js";import"./chunk-C4OYHUJV.js";import"./chunk-F62ZQZQQ.js";import"./chunk-T6KT63NC.js";import"./chunk-Y7TBCHW4.js";import"./chunk-RVQW6CBF.js";import"./chunk-BA4WZIAQ.js";import"./chunk-ZT4NPTML.js";import"./chunk-FGOVDO3R.js";import"./chunk-RKDNLPZM.js";import"./chunk-G5VE3HQW.js";import"./chunk-LCDRRAES.js";import"./chunk-XVQUVCFR.js";import"./chunk-J425SQFE.js";import"./chunk-73EWPVBJ.js";import"./chunk-YQIMO7VJ.js";import"./chunk-ACV2WVMX.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.11.1");process.exit(0)}
+import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-SZPTUV3B.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-ZKPOKMJZ.js";import"./chunk-437XL5VZ.js";import"./chunk-W6RS5S4Q.js";import"./chunk-57WGS6BI.js";import"./chunk-S7IHSELP.js";import"./chunk-IUVAWWQG.js";import"./chunk-N6NSZG7Z.js";import"./chunk-S456W64P.js";import"./chunk-QEDS3MOJ.js";import"./chunk-X2OVUBF6.js";import"./chunk-FBOPSWF6.js";import"./chunk-FOD6JEEU.js";import"./chunk-NKCL6RAF.js";import"./chunk-VRHLHGKR.js";import"./chunk-44HXRFOP.js";import"./chunk-O75SVMMB.js";import"./chunk-D6MPGK7R.js";import"./chunk-N4OWZLH5.js";import"./chunk-7SRSOZMP.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};

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