agentic-qe 3.10.3 → 3.10.5

package/dist/contracts/verdicts.d.ts

@@ -0,0 +1,297 @@
+/**
+ * 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 declare const VERDICT_CONTRACT_VERSION: "1.0";
+export type RiskDecisionOutcome = 'approve' | 'block' | 'escalate';
+export interface RiskDecision {
+    /** Envelope discriminator + version */
+    contract: 'risk-decision@1';
+    decision: RiskDecisionOutcome;
+    riskFactors: string[];
+    /** 0..1 */
+    confidence: number;
+    rationale: string;
+}
+export type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export type FindingOutcome = 'upheld' | 'refuted' | 'uncertain';
+export interface FindingVerdict {
+    contract: 'finding-verdict@1';
+    id: string;
+    title: string;
+    file?: string;
+    severity: FindingSeverity;
+    /** 0..1 */
+    confidence: number;
+    evidence: string[];
+    verdict: FindingOutcome;
+    /** One entry per refuter that voted to refute (empty when none) */
+    refutations: string[];
+}
+export interface CoverageGap {
+    contract: 'coverage-gap@1';
+    file: string;
+    /** 1-based inclusive line range; omit for whole-file gaps */
+    rangeStart?: number;
+    rangeEnd?: number;
+    /** 0..1 risk weighting */
+    riskScore: number;
+    suggestedTests: string[];
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateRiskDecision(value: unknown): ValidationResult;
+export declare function validateFindingVerdict(value: unknown): ValidationResult;
+export declare function validateCoverageGap(value: unknown): ValidationResult;
+/**
+ * Derive a RiskDecision from a quality-gate outcome (quality_assess boundary).
+ * Indeterminate gates (passed undefined) escalate rather than guess.
+ */
+export declare function buildRiskDecisionFromQualityGate(input: {
+    passed?: boolean;
+    qualityScore?: number;
+    recommendations?: string[];
+}): RiskDecision;
+export declare const RISK_DECISION_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://agentic-qe.dev/schemas/risk-decision.schema.json";
+    readonly title: "RiskDecision";
+    readonly type: "object";
+    readonly required: readonly ["contract", "decision", "riskFactors", "confidence", "rationale"];
+    readonly additionalProperties: true;
+    readonly properties: {
+        readonly contract: {
+            readonly const: "risk-decision@1";
+        };
+        readonly decision: {
+            readonly enum: readonly ["approve", "block", "escalate"];
+        };
+        readonly riskFactors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly confidence: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly rationale: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+};
+export declare const FINDING_VERDICT_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://agentic-qe.dev/schemas/finding-verdict.schema.json";
+    readonly title: "FindingVerdict";
+    readonly type: "object";
+    readonly required: readonly ["contract", "id", "title", "severity", "confidence", "evidence", "verdict", "refutations"];
+    readonly additionalProperties: true;
+    readonly properties: {
+        readonly contract: {
+            readonly const: "finding-verdict@1";
+        };
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly file: {
+            readonly type: "string";
+        };
+        readonly severity: {
+            readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+        };
+        readonly confidence: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly evidence: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly verdict: {
+            readonly enum: readonly ["upheld", "refuted", "uncertain"];
+        };
+        readonly refutations: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+};
+export declare const COVERAGE_GAP_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "https://agentic-qe.dev/schemas/coverage-gap.schema.json";
+    readonly title: "CoverageGap";
+    readonly type: "object";
+    readonly required: readonly ["contract", "file", "riskScore", "suggestedTests"];
+    readonly additionalProperties: true;
+    readonly properties: {
+        readonly contract: {
+            readonly const: "coverage-gap@1";
+        };
+        readonly file: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly rangeStart: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+        readonly rangeEnd: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+        readonly riskScore: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly suggestedTests: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+};
+export declare const VERDICT_SCHEMAS: {
+    readonly 'risk-decision': {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly $id: "https://agentic-qe.dev/schemas/risk-decision.schema.json";
+        readonly title: "RiskDecision";
+        readonly type: "object";
+        readonly required: readonly ["contract", "decision", "riskFactors", "confidence", "rationale"];
+        readonly additionalProperties: true;
+        readonly properties: {
+            readonly contract: {
+                readonly const: "risk-decision@1";
+            };
+            readonly decision: {
+                readonly enum: readonly ["approve", "block", "escalate"];
+            };
+            readonly riskFactors: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 1;
+            };
+            readonly rationale: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+    };
+    readonly 'finding-verdict': {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly $id: "https://agentic-qe.dev/schemas/finding-verdict.schema.json";
+        readonly title: "FindingVerdict";
+        readonly type: "object";
+        readonly required: readonly ["contract", "id", "title", "severity", "confidence", "evidence", "verdict", "refutations"];
+        readonly additionalProperties: true;
+        readonly properties: {
+            readonly contract: {
+                readonly const: "finding-verdict@1";
+            };
+            readonly id: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly file: {
+                readonly type: "string";
+            };
+            readonly severity: {
+                readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 1;
+            };
+            readonly evidence: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly verdict: {
+                readonly enum: readonly ["upheld", "refuted", "uncertain"];
+            };
+            readonly refutations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+    readonly 'coverage-gap': {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly $id: "https://agentic-qe.dev/schemas/coverage-gap.schema.json";
+        readonly title: "CoverageGap";
+        readonly type: "object";
+        readonly required: readonly ["contract", "file", "riskScore", "suggestedTests"];
+        readonly additionalProperties: true;
+        readonly properties: {
+            readonly contract: {
+                readonly const: "coverage-gap@1";
+            };
+            readonly file: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly rangeStart: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+            readonly rangeEnd: {
+                readonly type: "integer";
+                readonly minimum: 1;
+            };
+            readonly riskScore: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 1;
+            };
+            readonly suggestedTests: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=verdicts.d.ts.map

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,

package/dist/integrations/ruvector/shared-rvf-adapter.js

@@ -10,6 +10,9 @@
  *
  * @module integrations/ruvector/shared-rvf-adapter
  */
+// Issue #516: lightweight, sqlite-free project-root resolver (static import so it
+// resolves under the test runner; avoids pulling unified-memory's sqlite graph).
+import { findProjectRoot } from '../../kernel/project-root.js';
 let sharedAdapter = null;
 let initAttempted = false;
 // ---------------------------------------------------------------------------
@@ -62,7 +65,15 @@ export function getSharedRvfAdapter(dataDir = '.agentic-qe', dimensions = 384) {
         }
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const path = require('path');
-        const rvfPath = path.join(dataDir, 'patterns.rvf');
+        // Issue #516: resolve a relative dataDir against the project root so the
+        // store lands in the project's own .agentic-qe/, not a cwd-relative one.
+        // A subfolder cwd (vendored builds, background workers, `aqe code index
+        // docs/`) otherwise scatters stray patterns.rvf-only stores. Explicit
+        // absolute dataDir args are honored as-is.
+        const baseDir = path.isAbsolute(dataDir)
+            ? dataDir
+            : path.join(process.env.AQE_PROJECT_ROOT ?? findProjectRoot(), dataDir);
+        const rvfPath = path.join(baseDir, 'patterns.rvf');
         // Open-or-create with a try-ladder rather than `existsSync` gate.
         // Reasons:
         //  1. RVF native's `RvfDatabase.create()` throws `0x0303 FsyncFailed`

package/dist/integrations/ruvector/shared-rvf-dual-writer.js

@@ -56,16 +56,20 @@ export async function getSharedRvfDualWriter() {
                 return null;
             }
             // Get DB handle from unified memory
-            const { getUnifiedMemory } = await import('../../kernel/unified-memory.js');
+            const { getUnifiedMemory, findProjectRoot } = await import('../../kernel/unified-memory.js');
             const unifiedMemory = getUnifiedMemory();
             const db = unifiedMemory.getDatabase();
             if (!db) {
                 return null;
             }
+            // Issue #516: anchor brain.rvf to the project root rather than a
+            // cwd-relative path, so a subfolder cwd doesn't scatter a stray store.
+            const { join: joinPath } = await import('node:path');
+            const rvfPath = joinPath(process.env.AQE_PROJECT_ROOT ?? findProjectRoot(), '.agentic-qe', 'brain.rvf');
             // Create dual-writer (dynamic import to avoid bundling .node files)
             const { RvfDualWriter: DualWriterClass } = await import('./rvf-dual-writer.js');
             const writer = new DualWriterClass(db, {
-                rvfPath: '.agentic-qe/brain.rvf',
+                rvfPath,
                 mode: 'dual-write',
                 dimensions: 384,
             });

package/dist/kernel/project-root.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Project Root Detection
+ *
+ * Lightweight, dependency-free resolution of the AQE project root. Kept in its
+ * own module (no SQLite / kernel imports) so hot paths — e.g. the RVF pattern
+ * store factory — can import it statically without dragging in the sqlite-heavy
+ * unified-memory graph, and so it resolves cleanly under the test runner.
+ *
+ * `unified-memory` re-exports `findProjectRoot` / `clearProjectRootCache` for
+ * backward compatibility, so existing import sites keep working.
+ *
+ * @module kernel/project-root
+ */
+/**
+ * Clear the cached project root. Useful for testing or when the
+ * environment changes at runtime.
+ */
+export declare function clearProjectRootCache(): void;
+/**
+ * Find the project root by walking up the directory tree.
+ *
+ * Priority order:
+ * 1. AQE_PROJECT_ROOT environment variable (set by MCP config or init)
+ * 2. Walk up looking for the NEAREST .agentic-qe directory (existing AQE project)
+ * 3. Walk up looking for .git directory (git repo root)
+ * 4. Walk up looking for package.json WITHOUT node_modules sibling (monorepo root)
+ * 5. Fallback to current working directory
+ *
+ * Optimized: single upward walk checks all markers in one pass,
+ * and the result is cached at module level for subsequent calls.
+ */
+export declare function findProjectRoot(startDir?: string): string;
+//# sourceMappingURL=project-root.d.ts.map