agentic-qe 3.11.5 → 3.12.0

package/dist/mcp/tools/quality-assessment/gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agentic QE v3 - Quality Gate MCP Tool (ADR-119)
+ *
+ * qe/quality/gate - two-gate, three-valued quality verdict against a pinned
+ * ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
+ * `aqe quality-gate` CLI subcommand so CLI and MCP stay in exact parity.
+ *
+ * The frontier judge is built from the forwarded HybridRouter
+ * (context.llmRouter). When no provider is configured the judge's preflight
+ * fails ⇒ the verdict is `inconclusive` — never a silent pass.
+ */
+import { MCPToolBase, MCPToolConfig, MCPToolContext } from '../base';
+import { ToolResult } from '../../types';
+import type { QualityVerdictResult } from '../../../validation/quality-verdict.js';
+export interface QualityGateParams {
+    /** Pinned anchor checklist id (e.g. "A1-inRange"). */
+    checklistId: string;
+    /** The artifact under judgement (produced test source / spec output). */
+    artifact: string;
+    /**
+     * Mechanical-gate result from the ADR-113 oracle. Omit/null ⇒ oracle did not
+     * run ⇒ mechanical fail (a non-executed test can never be a silent pass).
+     */
+    oracle?: {
+        passed: boolean;
+        baselinePassed: boolean;
+    } | null;
+    /** Override the frozen anchor path (ADR-117). */
+    anchorPath?: string;
+    /** Frontier judge model id (ADR-111: always frontier-tier). */
+    model?: string;
+    [key: string]: unknown;
+}
+export declare class QualityGateTool extends MCPToolBase<QualityGateParams, QualityVerdictResult> {
+    readonly config: MCPToolConfig;
+    execute(params: QualityGateParams, context: MCPToolContext): Promise<ToolResult<QualityVerdictResult>>;
+}
+//# sourceMappingURL=gate.d.ts.map

package/dist/mcp/tools/quality-assessment/gate.js

@@ -0,0 +1,86 @@
+/**
+ * Agentic QE v3 - Quality Gate MCP Tool (ADR-119)
+ *
+ * qe/quality/gate - two-gate, three-valued quality verdict against a pinned
+ * ADR-117 checklist. Calls the SAME `runQualityGate` orchestrator as the
+ * `aqe quality-gate` CLI subcommand so CLI and MCP stay in exact parity.
+ *
+ * The frontier judge is built from the forwarded HybridRouter
+ * (context.llmRouter). When no provider is configured the judge's preflight
+ * fails ⇒ the verdict is `inconclusive` — never a silent pass.
+ */
+import { MCPToolBase } from '../base';
+import { toErrorMessage } from '../../../shared/error-utils.js';
+import { getLLMRouter } from '../base.js';
+import { runQualityGate } from '../../../validation/quality-gate-runner.js';
+import { createRouterFrontierJudge, createUnavailableJudge, } from '../../../validation/frontier-judge.js';
+export class QualityGateTool extends MCPToolBase {
+    config = {
+        name: 'qe/quality/gate',
+        description: 'Two-gate, three-valued quality verdict (ADR-119): mechanical oracle gate plus a frontier '
+            + 'judge grading the artifact against a pinned ADR-117 checklist. Returns pass|fail|inconclusive.',
+        domain: 'quality-assessment',
+        schema: QUALITY_GATE_SCHEMA,
+        streaming: false,
+        timeout: 120000,
+    };
+    async execute(params, context) {
+        try {
+            if (!params.checklistId) {
+                return { success: false, error: 'checklistId is required' };
+            }
+            if (typeof params.artifact !== 'string' || params.artifact.length === 0) {
+                return { success: false, error: 'artifact (non-empty string) is required' };
+            }
+            const router = await getLLMRouter(context);
+            const judge = router
+                ? createRouterFrontierJudge(router, params.model ? { model: params.model } : {})
+                : createUnavailableJudge('no LLM provider configured — set a frontier provider API key');
+            if (!router) {
+                this.markAsDemoData(context, 'no LLM router — frontier judge unavailable, verdict will be inconclusive');
+            }
+            const result = await runQualityGate({
+                oracleResult: params.oracle ?? null,
+                artifact: params.artifact,
+                checklistId: params.checklistId,
+                judge,
+                anchorPath: params.anchorPath,
+            });
+            return { success: true, data: result };
+        }
+        catch (error) {
+            return { success: false, error: `Quality gate failed: ${toErrorMessage(error)}` };
+        }
+    }
+}
+const QUALITY_GATE_SCHEMA = {
+    type: 'object',
+    properties: {
+        checklistId: {
+            type: 'string',
+            description: 'Pinned ADR-117 anchor checklist id (e.g. "A1-inRange")',
+        },
+        artifact: {
+            type: 'string',
+            description: 'The artifact under judgement (produced test source / spec output)',
+        },
+        oracle: {
+            type: 'object',
+            description: 'ADR-113 mechanical oracle result. Omit ⇒ mechanical fail (test did not execute).',
+            properties: {
+                passed: { type: 'boolean', description: 'Mutation score met threshold' },
+                baselinePassed: { type: 'boolean', description: 'Tests executed against the reference impl' },
+            },
+        },
+        anchorPath: {
+            type: 'string',
+            description: 'Override the frozen anchor path (ADR-117)',
+        },
+        model: {
+            type: 'string',
+            description: 'Frontier judge model id (ADR-111: always frontier-tier)',
+        },
+    },
+    required: ['checklistId', 'artifact'],
+};
+//# sourceMappingURL=gate.js.map

package/dist/mcp/tools/registry.d.ts

@@ -29,6 +29,7 @@ export declare const QE_TOOL_NAMES: {
     readonly COVERAGE_ANALYZE: "qe/coverage/analyze";
     readonly COVERAGE_GAPS: "qe/coverage/gaps";
     readonly QUALITY_EVALUATE: "qe/quality/evaluate";
+    readonly QUALITY_GATE: "qe/quality/gate";
     readonly DEFECT_PREDICT: "qe/defects/predict";
     readonly REQUIREMENTS_VALIDATE: "qe/requirements/validate";
     readonly QUALITY_CRITERIA: "qe/requirements/quality-criteria";

package/dist/mcp/tools/registry.js

@@ -9,6 +9,7 @@ import { TestGenerateTool } from './test-generation/generate';
 import { TestExecuteTool } from './test-execution/execute';
 import { CoverageAnalyzeTool, CoverageGapsTool } from './coverage-analysis';
 import { QualityEvaluateTool } from './quality-assessment/evaluate';
+import { QualityGateTool } from './quality-assessment/gate';
 import { DefectPredictTool } from './defect-intelligence/predict';
 import { RequirementsValidateTool } from './requirements-validation/validate';
 import { QualityCriteriaTool } from './requirements-validation/quality-criteria';
@@ -42,6 +43,7 @@ export const QE_TOOL_NAMES = {
     COVERAGE_GAPS: 'qe/coverage/gaps',
     // Quality Assessment
     QUALITY_EVALUATE: 'qe/quality/evaluate',
+    QUALITY_GATE: 'qe/quality/gate',
     // Defect Intelligence
     DEFECT_PREDICT: 'qe/defects/predict',
     // Requirements Validation
@@ -105,6 +107,7 @@ export const QE_TOOLS = [
     new CoverageGapsTool(),
     // Quality Assessment Domain
     new QualityEvaluateTool(),
+    new QualityGateTool(),
     // Defect Intelligence Domain
     new DefectPredictTool(),
     // Requirements Validation Domain

package/dist/shared/safe-db.js

@@ -23,6 +23,18 @@ export function openDatabase(dbPath, opts) {
     const fileMustExist = opts?.fileMustExist ?? false;
     const busyTimeout = opts?.busyTimeout ?? 5000;
     const walMode = opts?.walMode ?? !readonly;
+    // Environment override for filesystems where WAL is UNSAFE. WAL prevents
+    // concurrent-writer corruption on a normal filesystem, but on a macOS
+    // Docker/virtiofs bind mount the `-shm` mmap coherence across the
+    // host/container boundary is broken, so WAL checkpoints can zero pages and
+    // corrupt the DB (observed 2026-06-08 and again 2026-07-07). On such a mount,
+    // set AQE_DISABLE_WAL=1 (or AQE_JOURNAL_MODE=DELETE|TRUNCATE) so this process
+    // opens the DB in a rollback-journal mode instead. Default behavior is
+    // unchanged: without the env var, writable connections still use WAL.
+    const journalOverride = (process.env.AQE_JOURNAL_MODE ?? '').trim().toUpperCase();
+    const disableWal = process.env.AQE_DISABLE_WAL === '1' ||
+        journalOverride === 'DELETE' ||
+        journalOverride === 'TRUNCATE';
     const db = new Database(dbPath, {
         readonly,
         fileMustExist,
@@ -30,10 +42,17 @@ export function openDatabase(dbPath, opts) {
     // Always set busy_timeout — even for readonly connections.
     // Without this, concurrent access gets SQLITE_BUSY immediately.
     db.pragma(`busy_timeout = ${busyTimeout}`);
-    // WAL mode for writable connections prevents corruption from concurrent writers.
-    // Readonly connections inherit WAL from the DB file but we set it explicitly
-    // to be safe in case the DB was created without WAL.
-    if (walMode) {
+    if (disableWal) {
+        // Explicit opt-out of WAL for this environment. Readonly connections cannot
+        // change journal_mode, so only apply to writable opens.
+        if (!readonly) {
+            db.pragma(`journal_mode = ${journalOverride || 'DELETE'}`);
+        }
+    }
+    else if (walMode) {
+        // WAL mode for writable connections prevents corruption from concurrent
+        // writers. Readonly connections inherit WAL from the DB file but we set it
+        // explicitly to be safe in case the DB was created without WAL.
         db.pragma('journal_mode = WAL');
     }
     return db;

package/dist/validation/anchor-set.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Frozen oracle-grade QE anchor set (ADR-117).
+ *
+ * A small, human-labeled, content-hash-pinned, constant-denominator eval set
+ * that promotion gates (ADR-118 accept(), ADR-120 re-executed gates) must
+ * evaluate and never regress against. The loader recomputes the content hash on
+ * load and THROWS on drift — a frozen anchor the optimizer can silently edit is
+ * not frozen. Mirrors ruflo `harness-frozen-eval` + retort's constant-denominator
+ * `REQUIREMENTS.json`.
+ *
+ * Each item is a test-generation task graded by the ADR-113 oracle
+ * (`evaluateOracle`): the policy produces a test for `referenceImpl`, and the
+ * mutation kill rate is the score. `requirements` is the pinned checklist (the
+ * constant denominator) the ADR-119 judge grades against.
+ */
+export interface AnchorItem {
+    /** Stable item id (e.g. "A1-inRange"). */
+    id: string;
+    /** Human-readable spec the test-gen policy is asked to produce a test for. */
+    inputUnderTest: string;
+    /** Base module name (no extension) for the reference impl. */
+    moduleName: string;
+    /** ESM source of the correct implementation. */
+    referenceImpl: string;
+    /** Pinned checklist of requirements — the CONSTANT denominator (frozen count). */
+    requirements: string[];
+    /** Ground-truth mutant count a correct test must kill (measured via the oracle at freeze time). */
+    expectedMutants: number;
+}
+export interface AnchorPassBar {
+    /** Minimum mutation kill rate for an item to pass (ADR-117 "High" bar = 0.8). */
+    mutationThreshold: number;
+    /** Required checklist coverage for the ADR-119 judge (pass only at 1.0). */
+    checklistCoverage: number;
+}
+export interface AnchorSet {
+    schemaVersion: number;
+    /** The frozen quality bar. */
+    passBar: AnchorPassBar;
+    /** No-regression tolerance: a promotion may not drop the anchor mean by more than this. */
+    anchorTol: number;
+    /** SHA-256 over the canonicalized items — recomputed and checked on load. */
+    contentHash: string;
+    items: AnchorItem[];
+}
+/**
+ * Deterministic canonical form of the items for hashing: items sorted by id,
+ * object keys sorted, no incidental whitespace. Independent of file formatting
+ * and key order so a semantically-identical file hashes identically.
+ */
+export declare function canonicalizeItems(items: AnchorItem[]): string;
+/** SHA-256 content hash over the canonicalized items. */
+export declare function computeContentHash(items: AnchorItem[]): string;
+/**
+ * Load a frozen anchor set, refusing to return if the recorded hash does not
+ * match the recomputed one (ADR-117 §2). No promotion path may read the anchor
+ * except through this loader.
+ */
+export declare function loadAnchorSet(path: string): AnchorSet;
+/** The score of one anchor item = its oracle mutation kill rate. */
+export declare function anchorItemScore(oracleResult: {
+    mutationScore: number;
+}): number;
+/**
+ * The anchor mean: Σ score / N with N constant (the constant-denominator
+ * property — comparable across runs and generations).
+ */
+export declare function anchorMean(scores: number[]): number;
+/**
+ * No-regression contract (ADR-117 §4, ADR-118 accept(), ADR-120 re-exec).
+ * A candidate policy may not drop the anchor mean below baseline − tol.
+ */
+export declare function meetsNoRegression(candidateMean: number, baselineMean: number, tol: number): boolean;
+//# sourceMappingURL=anchor-set.d.ts.map

package/dist/validation/anchor-set.js

@@ -0,0 +1,78 @@
+/**
+ * Frozen oracle-grade QE anchor set (ADR-117).
+ *
+ * A small, human-labeled, content-hash-pinned, constant-denominator eval set
+ * that promotion gates (ADR-118 accept(), ADR-120 re-executed gates) must
+ * evaluate and never regress against. The loader recomputes the content hash on
+ * load and THROWS on drift — a frozen anchor the optimizer can silently edit is
+ * not frozen. Mirrors ruflo `harness-frozen-eval` + retort's constant-denominator
+ * `REQUIREMENTS.json`.
+ *
+ * Each item is a test-generation task graded by the ADR-113 oracle
+ * (`evaluateOracle`): the policy produces a test for `referenceImpl`, and the
+ * mutation kill rate is the score. `requirements` is the pinned checklist (the
+ * constant denominator) the ADR-119 judge grades against.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+/**
+ * Deterministic canonical form of the items for hashing: items sorted by id,
+ * object keys sorted, no incidental whitespace. Independent of file formatting
+ * and key order so a semantically-identical file hashes identically.
+ */
+export function canonicalizeItems(items) {
+    const norm = [...items]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((it) => ({
+        id: it.id,
+        inputUnderTest: it.inputUnderTest,
+        moduleName: it.moduleName,
+        referenceImpl: it.referenceImpl,
+        requirements: it.requirements,
+        expectedMutants: it.expectedMutants,
+    }));
+    return JSON.stringify(norm);
+}
+/** SHA-256 content hash over the canonicalized items. */
+export function computeContentHash(items) {
+    return createHash('sha256').update(canonicalizeItems(items)).digest('hex');
+}
+/**
+ * Load a frozen anchor set, refusing to return if the recorded hash does not
+ * match the recomputed one (ADR-117 §2). No promotion path may read the anchor
+ * except through this loader.
+ */
+export function loadAnchorSet(path) {
+    const raw = JSON.parse(fs.readFileSync(path, 'utf8'));
+    const recomputed = computeContentHash(raw.items);
+    if (recomputed !== raw.contentHash) {
+        throw new Error(`Anchor set hash drift at ${path}: recorded ${raw.contentHash}, `
+            + `recomputed ${recomputed}. Refusing to load a mutated frozen anchor (ADR-117). `
+            + `A legitimate change must be a versioned re-freeze (qe-anchor-v2), never an in-place edit.`);
+    }
+    if (raw.items.length === 0) {
+        throw new Error(`Anchor set at ${path} has no items — a frozen anchor must be non-empty.`);
+    }
+    return raw;
+}
+/** The score of one anchor item = its oracle mutation kill rate. */
+export function anchorItemScore(oracleResult) {
+    return oracleResult.mutationScore;
+}
+/**
+ * The anchor mean: Σ score / N with N constant (the constant-denominator
+ * property — comparable across runs and generations).
+ */
+export function anchorMean(scores) {
+    if (scores.length === 0)
+        return 0;
+    return scores.reduce((a, b) => a + b, 0) / scores.length;
+}
+/**
+ * No-regression contract (ADR-117 §4, ADR-118 accept(), ADR-120 re-exec).
+ * A candidate policy may not drop the anchor mean below baseline − tol.
+ */
+export function meetsNoRegression(candidateMean, baselineMean, tol) {
+    return candidateMean >= baselineMean - tol;
+}
+//# sourceMappingURL=anchor-set.js.map

package/dist/validation/frontier-judge.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Frontier-tier spec judge for the ADR-119 two-gate quality verdict.
+ *
+ * This is the real spec-gate `Judge` consumed by `computeQualityVerdict`
+ * (quality-verdict.ts). It grades an artifact against a pinned,
+ * constant-denominator ADR-117 checklist using a FRONTIER model — never the
+ * cheap local writer lane (ADR-111: the oracle is the one place you never
+ * economize). Two design guarantees flow from the verdict logic:
+ *
+ *   - `preflight()` does a cheap live round-trip to prove the provider and
+ *     credentials actually respond. On any failure it returns `false`, which the
+ *     verdict maps to `inconclusive` — a dead provider can never masquerade as a
+ *     silent pass.
+ *   - `grade()` returns `ran: false` on ANY tooling failure (timeout,
+ *     usage-limit, unparseable response). A non-real opinion can never
+ *     contribute to a `fail`; too few real opinions ⇒ `inconclusive`.
+ *
+ * The single provider call is isolated behind an injectable `complete(prompt)`
+ * seam so the judge is unit-testable with a fake and zero network. Wire the real
+ * frontier model with `routerComplete()` / `createRouterFrontierJudge()`.
+ */
+import type { Judge, RequirementChecklist } from './quality-verdict.js';
+import type { HybridRouter } from '../shared/llm/router/hybrid-router.js';
+import type { ExtendedProviderType } from '../shared/llm/router/types.js';
+/** The model call seam. Returns the raw model text for one prompt. */
+export type CompleteFn = (prompt: string) => Promise<string>;
+export interface FrontierJudgeOptions {
+    /**
+     * Injectable frontier-model call. In production this is `routerComplete()`
+     * bound to a frontier model; in tests it is a fake — NO network either way.
+     */
+    complete: CompleteFn;
+    /**
+     * Cheap liveness ping used by `preflight()`. Defaults to a minimal
+     * `complete()` round-trip. Should resolve truthy only when the provider and
+     * credentials actually respond.
+     */
+    ping?: () => Promise<boolean>;
+    /** Frontier model id, for reporting/telemetry only (the seam owns the call). */
+    model?: string;
+    /** Per-call timeout in ms (grade + default ping). Default 60s. */
+    timeoutMs?: number;
+    /** Optional diagnostic logger. */
+    logger?: (message: string) => void;
+}
+/**
+ * Create the ADR-119 frontier spec judge.
+ *
+ * The returned object satisfies the `Judge` contract consumed by
+ * `computeQualityVerdict`. All provider interaction is behind `opts.complete`.
+ */
+export declare function createFrontierJudge(opts: FrontierJudgeOptions): Judge;
+/**
+ * Build a `complete()` seam backed by the shared HybridRouter, pinned to a
+ * frontier model. This is where the ADR-111 "never economize the oracle" rule is
+ * enforced: `model` defaults to a frontier Opus and `preferredProvider` lets the
+ * caller route to a frontier provider explicitly.
+ */
+export declare function routerComplete(router: HybridRouter, opts?: {
+    model?: string;
+    preferredProvider?: ExtendedProviderType;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+}): CompleteFn;
+/**
+ * Convenience: a frontier judge wired to the shared HybridRouter. The judge is
+ * ALWAYS frontier-tier — `model` defaults to a frontier Opus.
+ */
+export declare function createRouterFrontierJudge(router: HybridRouter, opts?: {
+    model?: string;
+    preferredProvider?: ExtendedProviderType;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    logger?: (message: string) => void;
+}): Judge;
+/**
+ * A judge for when no frontier provider is available (no LLM router / no
+ * credentials). `preflight()` returns false so the verdict is `inconclusive` —
+ * NEVER a silent pass. Both CLI and MCP use this fallback so they stay in parity.
+ */
+export declare function createUnavailableJudge(_reason: string): Judge;
+/**
+ * Build the grading prompt. Requirements are numbered 1..N and the model is
+ * asked for the numbers of the UNMET ones as strict JSON. Reporting unmet (not
+ * satisfied) keeps the denominator constant and the contract unambiguous.
+ */
+export declare function buildGradePrompt(artifact: string, checklist: RequirementChecklist): string;
+/**
+ * Parse the model response into a set of 0-based unmet requirement indices.
+ * Returns `null` when the response cannot be parsed into the strict contract
+ * (so the caller treats it as a non-real opinion). Out-of-range and duplicate
+ * numbers are ignored — a garbled index list never inflates the unmet count.
+ */
+export declare function parseUnmetIndices(raw: string, total: number): Set<number> | null;
+/** Reject with a timeout error if `p` does not settle within `ms`. */
+export declare function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T>;
+//# sourceMappingURL=frontier-judge.d.ts.map