agentic-qe 3.10.4 → 3.10.5

package/dist/contracts/verdicts.js

@@ -0,0 +1,178 @@
+/**
+ * Agentic QE v3 - Structured Verdict Contracts (ADR-103)
+ *
+ * Typed, versioned verdict envelopes for agent-to-agent and MCP-boundary
+ * handoffs: RiskDecision (quality gates), FindingVerdict (review findings
+ * with adversarial refutations), CoverageGap (risk-weighted gap reports).
+ *
+ * Validators are dependency-free and are the source of truth; the exported
+ * JSON Schemas (published to schemas/*.schema.json by
+ * scripts/generate-verdict-schemas.mjs) mirror them for external tooling
+ * (ajv, workflow agent() schema option). Envelopes are versioned and
+ * additive-only within a major version: consumers must tolerate unknown
+ * fields, so schemas keep `additionalProperties: true`.
+ */
+export const VERDICT_CONTRACT_VERSION = '1.0';
+// ============================================================================
+// Validators (dependency-free, boundary-grade)
+// ============================================================================
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+function inUnitRange(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+}
+export function validateRiskDecision(value) {
+    const errors = [];
+    if (!isRecord(value))
+        return { valid: false, errors: ['not an object'] };
+    if (value.contract !== 'risk-decision@1')
+        errors.push(`contract must be "risk-decision@1"`);
+    if (!['approve', 'block', 'escalate'].includes(value.decision)) {
+        errors.push('decision must be approve|block|escalate');
+    }
+    if (!isStringArray(value.riskFactors))
+        errors.push('riskFactors must be string[]');
+    if (!inUnitRange(value.confidence))
+        errors.push('confidence must be a number in [0,1]');
+    if (typeof value.rationale !== 'string' || value.rationale.length === 0) {
+        errors.push('rationale must be a non-empty string');
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function validateFindingVerdict(value) {
+    const errors = [];
+    if (!isRecord(value))
+        return { valid: false, errors: ['not an object'] };
+    if (value.contract !== 'finding-verdict@1')
+        errors.push(`contract must be "finding-verdict@1"`);
+    if (typeof value.id !== 'string' || value.id.length === 0)
+        errors.push('id must be a non-empty string');
+    if (typeof value.title !== 'string' || value.title.length === 0)
+        errors.push('title must be a non-empty string');
+    if (value.file !== undefined && typeof value.file !== 'string')
+        errors.push('file must be a string when present');
+    if (!['critical', 'high', 'medium', 'low', 'info'].includes(value.severity)) {
+        errors.push('severity must be critical|high|medium|low|info');
+    }
+    if (!inUnitRange(value.confidence))
+        errors.push('confidence must be a number in [0,1]');
+    if (!isStringArray(value.evidence))
+        errors.push('evidence must be string[]');
+    if (!['upheld', 'refuted', 'uncertain'].includes(value.verdict)) {
+        errors.push('verdict must be upheld|refuted|uncertain');
+    }
+    if (!isStringArray(value.refutations))
+        errors.push('refutations must be string[]');
+    return { valid: errors.length === 0, errors };
+}
+export function validateCoverageGap(value) {
+    const errors = [];
+    if (!isRecord(value))
+        return { valid: false, errors: ['not an object'] };
+    if (value.contract !== 'coverage-gap@1')
+        errors.push(`contract must be "coverage-gap@1"`);
+    if (typeof value.file !== 'string' || value.file.length === 0)
+        errors.push('file must be a non-empty string');
+    for (const k of ['rangeStart', 'rangeEnd']) {
+        const v = value[k];
+        if (v !== undefined && (!Number.isInteger(v) || v < 1)) {
+            errors.push(`${k} must be a positive integer when present`);
+        }
+    }
+    if (Number.isInteger(value.rangeStart) &&
+        Number.isInteger(value.rangeEnd) &&
+        value.rangeEnd < value.rangeStart) {
+        errors.push('rangeEnd must be >= rangeStart');
+    }
+    if (!inUnitRange(value.riskScore))
+        errors.push('riskScore must be a number in [0,1]');
+    if (!isStringArray(value.suggestedTests))
+        errors.push('suggestedTests must be string[]');
+    return { valid: errors.length === 0, errors };
+}
+// ============================================================================
+// Builders — derive contract envelopes at MCP boundaries
+// ============================================================================
+/**
+ * Derive a RiskDecision from a quality-gate outcome (quality_assess boundary).
+ * Indeterminate gates (passed undefined) escalate rather than guess.
+ */
+export function buildRiskDecisionFromQualityGate(input) {
+    const { passed, qualityScore, recommendations = [] } = input;
+    const decision = passed === true ? 'approve' : passed === false ? 'block' : 'escalate';
+    return {
+        contract: 'risk-decision@1',
+        decision,
+        riskFactors: recommendations.slice(0, 10),
+        confidence: decision === 'escalate' ? 0.5 : 0.9,
+        rationale: decision === 'escalate'
+            ? 'Quality gate outcome indeterminate — manual review required'
+            : `Quality gate ${passed ? 'passed' : 'failed'}${typeof qualityScore === 'number' ? ` with score ${qualityScore}` : ''}`,
+    };
+}
+// ============================================================================
+// JSON Schemas (draft-07) — mirrors of the validators above, published to
+// schemas/*.schema.json for ajv / workflow agent({schema}) consumers
+// ============================================================================
+const unit = { type: 'number', minimum: 0, maximum: 1 };
+const stringArray = { type: 'array', items: { type: 'string' } };
+export const RISK_DECISION_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'https://agentic-qe.dev/schemas/risk-decision.schema.json',
+    title: 'RiskDecision',
+    type: 'object',
+    required: ['contract', 'decision', 'riskFactors', 'confidence', 'rationale'],
+    additionalProperties: true,
+    properties: {
+        contract: { const: 'risk-decision@1' },
+        decision: { enum: ['approve', 'block', 'escalate'] },
+        riskFactors: stringArray,
+        confidence: unit,
+        rationale: { type: 'string', minLength: 1 },
+    },
+};
+export const FINDING_VERDICT_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'https://agentic-qe.dev/schemas/finding-verdict.schema.json',
+    title: 'FindingVerdict',
+    type: 'object',
+    required: ['contract', 'id', 'title', 'severity', 'confidence', 'evidence', 'verdict', 'refutations'],
+    additionalProperties: true,
+    properties: {
+        contract: { const: 'finding-verdict@1' },
+        id: { type: 'string', minLength: 1 },
+        title: { type: 'string', minLength: 1 },
+        file: { type: 'string' },
+        severity: { enum: ['critical', 'high', 'medium', 'low', 'info'] },
+        confidence: unit,
+        evidence: stringArray,
+        verdict: { enum: ['upheld', 'refuted', 'uncertain'] },
+        refutations: stringArray,
+    },
+};
+export const COVERAGE_GAP_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'https://agentic-qe.dev/schemas/coverage-gap.schema.json',
+    title: 'CoverageGap',
+    type: 'object',
+    required: ['contract', 'file', 'riskScore', 'suggestedTests'],
+    additionalProperties: true,
+    properties: {
+        contract: { const: 'coverage-gap@1' },
+        file: { type: 'string', minLength: 1 },
+        rangeStart: { type: 'integer', minimum: 1 },
+        rangeEnd: { type: 'integer', minimum: 1 },
+        riskScore: unit,
+        suggestedTests: stringArray,
+    },
+};
+export const VERDICT_SCHEMAS = {
+    'risk-decision': RISK_DECISION_SCHEMA,
+    'finding-verdict': FINDING_VERDICT_SCHEMA,
+    'coverage-gap': COVERAGE_GAP_SCHEMA,
+};
+//# sourceMappingURL=verdicts.js.map

package/dist/coordination/queen-types.d.ts

@@ -45,6 +45,10 @@ export interface TaskExecution {
     readonly result?: unknown;
     readonly error?: string;
     readonly retryCount: number;
+    /** ADR-101: agent that spawned this task (nested-subagent provenance) */
+    readonly parentAgentId?: string;
+    /** ADR-101: nesting depth, 0 = top-level (Anthropic cap is 5; bound is 32) */
+    readonly depth?: number;
 }
 /**
  * Domain group for coordination

package/dist/integrations/agentic-flow/reasoning-bank/experience-replay.js

@@ -18,6 +18,7 @@ import { computeRealEmbedding, } from '../../../learning/real-embeddings.js';
 import { CircularBuffer } from '../../../shared/utils/circular-buffer.js';
 import { HNSWEmbeddingIndex } from '../../embeddings/index/HNSWIndex.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { scrubReasoningBlocks } from '../../../shared/reasoning-scrub.js';
 import { ExperienceConsolidator } from '../../../learning/experience-consolidation.js';
 import { getRuVectorFeatureFlags } from '../../ruvector/feature-flags.js';
 import { ReservoirReplayBuffer } from '../../ruvector/reservoir-replay.js';
@@ -126,7 +127,8 @@ export class ExperienceReplay {
         `);
                 let written = 0;
                 for (const row of ghosts) {
-                    const text = `${row.domain ?? ''}: ${row.task}`.slice(0, 512);
+                    // ADR-099: legacy rows may predate ingestion-time scrubbing
+                    const text = scrubReasoningBlocks(`${row.domain ?? ''}: ${row.task}`).slice(0, 512);
                     const embedding = await computeRealEmbedding(text);
                     const buf = Buffer.from(new Float32Array(embedding).buffer);
                     updateStmt.run(buf, embedding.length, row.id);
@@ -174,7 +176,8 @@ export class ExperienceReplay {
                 const updateStmt = this.db.prepare(`UPDATE qe_trajectories SET embedding = ? WHERE id = ?`);
                 let written = 0;
                 for (const row of rows) {
-                    const text = `${row.domain ?? ''}: ${row.task}`.slice(0, 512);
+                    // ADR-099: legacy rows may predate ingestion-time scrubbing
+                    const text = scrubReasoningBlocks(`${row.domain ?? ''}: ${row.task}`).slice(0, 512);
                     const embedding = await computeRealEmbedding(text);
                     updateStmt.run(Buffer.from(new Float32Array(embedding).buffer), row.id);
                     written++;
@@ -373,18 +376,22 @@ export class ExperienceReplay {
             return null;
         }
         // Extract key actions
+        // ADR-099: scrub reasoning scratchpad blocks so neither the stored
+        // experience nor its embedding carries extended-thinking text
+        const task = scrubReasoningBlocks(trajectory.task);
+        strategy = scrubReasoningBlocks(strategy);
         const keyActions = trajectory.steps
             .filter(s => s.result.outcome === 'success')
-            .map(s => s.action);
+            .map(s => scrubReasoningBlocks(s.action));
         // Generate embedding for similarity search
-        const embeddingText = `${trajectory.task} ${strategy} ${keyActions.join(' ')}`;
+        const embeddingText = `${task} ${strategy} ${keyActions.join(' ')}`;
         const embedding = await computeRealEmbedding(embeddingText, this.config.embedding);
         const id = uuidv4();
         const domain = trajectory.domain || 'test-generation';
         const experience = {
             id,
             trajectoryId: trajectory.id,
-            task: trajectory.task,
+            task,
             domain,
             strategy,
             keyActions,
@@ -401,7 +408,7 @@ export class ExperienceReplay {
         const insertStmt = this.prepared.get('insertExperience');
         if (insertStmt) {
             const embeddingBuffer = embedding ? this.floatArrayToBuffer(embedding) : null;
-            insertStmt.run(id, trajectory.task, strategy, // agent column stores strategy
+            insertStmt.run(id, task, strategy, // agent column stores strategy
             domain, trajectory.metrics.efficiencyScore, JSON.stringify(keyActions), // steps_json stores key actions
             JSON.stringify(trajectory.metrics), // routing_json stores original metrics
             embeddingBuffer, embedding?.length ?? null, JSON.stringify(tags));
@@ -523,6 +530,8 @@ export class ExperienceReplay {
             return [];
         }
         // Generate embedding for the task
+        // ADR-099: scrub so query embeddings match the scrubbed stored embeddings
+        task = scrubReasoningBlocks(task);
         const taskEmbedding = await computeRealEmbedding(task, this.config.embedding);
         // Create query embedding for HNSW search
         const queryEmbedding = {

package/dist/integrations/agentic-flow/reasoning-bank/trajectory-tracker.js

@@ -11,6 +11,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { getUnifiedMemory } from '../../../kernel/unified-memory.js';
 import { CircularBuffer } from '../../../shared/utils/circular-buffer.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { scrubReasoningBlocks, scrubReasoningDeep } from '../../../shared/reasoning-scrub.js';
 const DEFAULT_CONFIG = {
     maxStepsPerTrajectory: 100,
     autoEndTimeoutMs: 30 * 60 * 1000, // 30 minutes
@@ -222,6 +223,9 @@ export class TrajectoryTracker {
      */
     async startTrajectory(task, options = {}) {
         this.ensureInitialized();
+        // ADR-099: strip reasoning scratchpad blocks before the task text enters
+        // persistence and (later) embedding generation
+        task = scrubReasoningBlocks(task);
         const id = uuidv4();
         const startedAt = new Date();
         // Store in memory for active tracking
@@ -270,6 +274,14 @@ export class TrajectoryTracker {
         }
         const stepId = uuidv4();
         const quality = options.quality ?? this.calculateStepQuality(result);
+        // ADR-099: scrub reasoning blocks from step content before it is held
+        // in memory (distilled into experiences at endTrajectory) and persisted
+        action = scrubReasoningBlocks(action);
+        result = {
+            ...result,
+            data: result.data ? scrubReasoningDeep(result.data) : result.data,
+            error: result.error ? scrubReasoningBlocks(result.error) : result.error,
+        };
         const step = {
             id: stepId,
             action,