proffesor-for-testing__agentic-qe/docs/rvf-integration-plan.md

RVF Cognitive Container Integration Plan for AQE

Date: 2026-02-22 Status: Proposed Depends on: ADR-065 Bridge Layer (Phase 0.5), ADR-047 (MinCut Self-Organizing) Complements: docs/plans/rvf-integration-implementation-plan.md (VectorBackend bridge)

---

Executive Summary

This plan integrates RVF (RuVector Format) cognitive container capabilities into the AQE platform across three phases: Shadow Mode (validation), Progressive Integration (unification), and Native RVF (production). It targets capabilities orthogonal to the existing VectorBackend bridge plan: mincut-based routing, RVCOW dream cycle branching, witness chain quality attestation, HNSW unification, Stoer-Wagner health monitoring, and RVF container portability.

Key Constraint: SDK Reality

Per the Phase 0 Gate Report (docs/plans/rvf-phase0-gate-report.md):

• Working NOW: @ruvector/gnn (HNSW, differentiable search), @ruvector/sona (pattern learning), @ruvector/attention (Flash Attention), @ruvector/core (VectorDb)
• Rust-complete, npm-stub: @ruvector/rvf-node (no binaries), @ruvector/mincut-node (unverified -- must validate before relying on it)
• Strategy: Phase 1 uses only verified npm packages + TypeScript implementations. Phases 2-3 gate on @ruvector/rvf-node and @ruvector/mincut-node binary availability.

Relationship to Existing Plans

• The VectorBackend bridge plan (rvf-integration-implementation-plan.md) handles VectorBackend interface, @ruvector/core integration, and lazy persistence. Tasks RVF-0.5.1 through RVF-0.5.8.
• This plan handles complementary concerns: mincut routing, dream cycle branching, witness chains, HNSW unification, health monitoring, and container portability.
• No file conflicts between plans. This plan creates new files and extends (does not replace) existing ones.

---

Workstream Architecture

Tasks are organized into 4 independent workstreams that can run in parallel within each phase. Cross-workstream dependencies are explicitly called out.

Workstream	Focus	Lead Agent Type
WS-A	MinCut Routing	coder
WS-B	Dream Cycle + RVCOW Branching	coder
WS-C	Witness Chain + Quality Gates	coder
WS-D	HNSW Unification + Health Monitoring	coder

---

Phase 1: Shadow Mode (Weeks 1-4)

All Phase 1 tasks run in shadow/observability-only mode. No production behavior changes. All decisions are logged but not acted upon. This validates the new systems against real workloads before any cutover.

Workstream A: MinCut Routing

Task 1.1: Validate @ruvector/mincut-node Availability

Description: Probe whether @ruvector/mincut-node has functional N-API binaries on the target platform (linux-x64-gnu). If not, the existing TypeScript MinCutCalculator in v3/src/coordination/mincut/mincut-calculator.ts becomes the reference implementation and we skip the native dependency.

Field	Value
Files to modify	None (validation only)
Files to create	scripts/validate-mincut-node.ts
Agent	researcher
Dependencies	None
Parallel Group	Phase1-Immediate
Risk Level	Low
Est. Hours	2

Validation steps:

1. npm info @ruvector/mincut-node -- check published versions and binary artifacts
2. npm install @ruvector/mincut-node in a temp directory -- check for prebuild download
3. Attempt require('@ruvector/mincut-node') and call subpolynomialDynamic() with test graph
4. If functional: record latency benchmarks vs TypeScript MinCutCalculator
5. If stub: document in gate report, proceed with TypeScript implementation only

Test Strategy: Script outputs a JSON gate report at reports/mincut-node-validation.json.

Rollback: No changes to codebase. Script is standalone.

---

Task 1.2: Create mincut-wrapper.ts

Description: Create a wrapper that provides a unified interface over either @ruvector/mincut-node (native) or the existing TypeScript MinCutCalculator, selected at initialization time. This follows the same pattern as gnn-wrapper.ts and sona-wrapper.ts.

Field	Value
Files to create	v3/src/integrations/ruvector/mincut-wrapper.ts
Files to modify	v3/src/integrations/ruvector/index.ts (add export)
Agent	coder
Dependencies	Task 1.1 (gate result determines native availability)
Parallel Group	WS-A
Risk Level	Low
Est. Hours	4

Interface:

/**
 * Unified MinCut wrapper -- native or TypeScript backend
 * Follows the same pattern as gnn-wrapper.ts and sona-wrapper.ts
 */

/** MinCut algorithm selection */
export type MinCutAlgorithm =
  | 'subpolynomial-dynamic'  // Fastest: 128.7ns query (native), O(V) approx (TS)
  | 'stoer-wagner'           // Exact undirected: O(V^3)
  | 'karger'                 // Randomized: O(E), high probability
  | 'dinic';                 // Max-flow/min-cut: for attention gating

/** Graph input for mincut computation */
export interface MinCutGraph {
  readonly vertices: ReadonlyArray<{
    readonly id: string;
    readonly weight: number;
    readonly metadata?: Record<string, unknown>;
  }>;
  readonly edges: ReadonlyArray<{
    readonly source: string;
    readonly target: string;
    readonly capacity: number;
  }>;
}

/** MinCut computation result */
export interface MinCutComputeResult {
  readonly value: number;
  readonly sourceSide: readonly string[];
  readonly targetSide: readonly string[];
  readonly cutEdges: ReadonlyArray<{ source: string; target: string; capacity: number }>;
  readonly algorithm: MinCutAlgorithm;
  readonly backend: 'native' | 'typescript';
  readonly durationNs: number;
}

/** Lambda (connectivity) for a single vertex */
export interface VertexLambda {
  readonly vertexId: string;
  readonly lambda: number;
  readonly isBottleneck: boolean;
}

export interface QEMinCutWrapper {
  /** Compute minimum cut of the graph */
  computeMinCut(graph: MinCutGraph, algorithm?: MinCutAlgorithm): MinCutComputeResult;

  /** Compute vertex connectivity (lambda) for all vertices */
  computeLambdas(graph: MinCutGraph): VertexLambda[];

  /** Compute edge connectivity for a specific source-target pair */
  edgeConnectivity(graph: MinCutGraph, source: string, target: string): number;

  /** Get the backend being used */
  getBackend(): 'native' | 'typescript';

  /** Health check */
  isHealthy(): boolean;

  /** Dispose resources */
  dispose(): void;
}

/** Factory function */
export function createQEMinCutWrapper(options?: {
  preferNative?: boolean;
}): QEMinCutWrapper;

Implementation notes:

• Try require('@ruvector/mincut-node') at module load time (same pattern as unified-memory-hnsw.ts lines 16-28)
• If native unavailable, wrap MinCutCalculator from v3/src/coordination/mincut/mincut-calculator.ts
• The existing MinCutCalculator already implements approxMinCut (weighted degree), stoerWagnerMinCut, and kargersMinCut
• For dinic algorithm: implement in TypeScript (Dinic's max-flow is ~100 LOC) or defer to native
• durationNs measured via process.hrtime.bigint()

Test Strategy: Unit tests with mocked native module. Integration tests with real graph from SwarmGraph.

Rollback: Remove export from index.ts. No production code depends on this wrapper yet.

---

Task 1.3: MinCutRoutingService -- Lambda-Based Task Complexity

Description: Implement a service that models the AQE task routing problem as a graph and uses mincut lambda (vertex connectivity) to determine task complexity for the 3-tier model router. This runs in shadow mode alongside the existing TaskRouter in v3/src/mcp/services/task-router.ts.

Field	Value
Files to create	v3/src/mcp/services/mincut-routing-service.ts
Files to modify	None (shadow mode -- no wiring yet)
Agent	coder
Dependencies	Task 1.2
Parallel Group	WS-A
Risk Level	Low (shadow only)
Est. Hours	6

Interface:

import type { RoutingInput, RoutingDecision, ModelTier } from '../../integrations/agentic-flow';

/** MinCut routing context -- models task as graph problem */
export interface MinCutRoutingContext {
  /** Task description */
  readonly task: string;
  /** Domain context */
  readonly domain?: string;
  /** File paths involved */
  readonly filePaths?: readonly string[];
  /** Code complexity metrics (if available) */
  readonly codeContext?: string;
  /** Whether task is critical */
  readonly isCritical?: boolean;
}

/** Shadow routing result -- for comparison with production router */
export interface ShadowRoutingResult {
  /** MinCut-derived tier recommendation */
  readonly mincutTier: ModelTier;
  /** Lambda (connectivity) score used for the decision */
  readonly lambda: number;
  /** Production router's actual decision (for A/B comparison) */
  readonly productionTier: ModelTier;
  /** Whether mincut and production agree */
  readonly agrees: boolean;
  /** Graph structure used for the computation */
  readonly graphStats: {
    readonly vertices: number;
    readonly edges: number;
    readonly mincutValue: number;
  };
  /** Computation time */
  readonly durationMs: number;
  /** Timestamp */
  readonly timestamp: string;
}

export interface MinCutRoutingService {
  /** Compute shadow routing decision (does NOT affect production) */
  shadowRoute(context: MinCutRoutingContext): ShadowRoutingResult;

  /** Get accumulated shadow comparison metrics */
  getMetrics(): {
    readonly totalDecisions: number;
    readonly agreementRate: number;
    readonly mincutFasterTier: number;
    readonly mincutSlowerTier: number;
    readonly avgLambda: number;
    readonly avgDurationMs: number;
  };

  /** Reset metrics */
  resetMetrics(): void;

  /** Dispose resources */
  dispose(): void;
}

Complexity-to-tier mapping:

The service models the task as a dependency graph:

• Vertices: code modules mentioned in filePaths, domain agents, test suites
• Edges: import relationships, agent communication channels, test coverage links
• Lambda: minimum vertex connectivity of the task subgraph

Mapping lambda to ModelTier:

• lambda >= 5.0 (highly connected, complex): Tier 3 (Sonnet/Opus)
• lambda >= 2.0 (moderate connectivity): Tier 2 (Haiku)
• lambda >= 1.0 (simple, isolated): Tier 1 (Booster)
• lambda < 1.0 (disconnected): Tier 0 (Booster, trivial)

Thresholds are configurable and will be tuned based on shadow comparison data.

Test Strategy: Unit tests with synthetic graphs at known lambda values. Verify tier mapping. Mock the mincut wrapper.

Rollback: Delete file. No production wiring.

---

Task 1.4: A/B Shadow Comparison Framework

Description: Create a lightweight A/B comparison framework that logs every routing decision from both the production 3-tier router and the shadow MinCut router, enabling data-driven evaluation.

Field	Value
Files to create	v3/src/mcp/services/routing-ab-comparator.ts
Files to modify	v3/src/mcp/services/task-router.ts (add shadow hook, ~10 LOC)
Agent	coder
Dependencies	Task 1.3
Parallel Group	WS-A
Risk Level	Low (logging only)
Est. Hours	4

Interface:

export interface RoutingComparison {
  readonly taskId: string;
  readonly timestamp: string;
  readonly productionTier: number;
  readonly mincutTier: number;
  readonly productionLatencyMs: number;
  readonly mincutLatencyMs: number;
  readonly agrees: boolean;
  readonly lambda: number;
  readonly taskDescription: string;
}

export interface ABComparator {
  /** Record a routing comparison */
  record(comparison: RoutingComparison): void;

  /** Get summary statistics */
  getSummary(): {
    readonly total: number;
    readonly agreementRate: number;
    readonly mincutWouldUpgrade: number;
    readonly mincutWouldDowngrade: number;
    readonly avgLambda: number;
    readonly tierDistribution: Record<number, number>;
  };

  /** Export all comparisons (for offline analysis) */
  export(): readonly RoutingComparison[];

  /** Persist to SQLite kv_store namespace 'routing-ab' */
  flush(): void;
}

Modification to task-router.ts: Add an optional shadow hook that is called after every routing decision. The hook is injected via constructor or setABComparator(). When absent, zero overhead.

// In TaskRouterService.routeTask():
if (this.abComparator) {
  const shadowResult = this.mincutService.shadowRoute(context);
  this.abComparator.record({
    taskId,
    timestamp: new Date().toISOString(),
    productionTier: decision.tier,
    mincutTier: shadowResult.mincutTier,
    productionLatencyMs: decision.latencyMs,
    mincutLatencyMs: shadowResult.durationMs,
    agrees: shadowResult.agrees,
    lambda: shadowResult.lambda,
    taskDescription: input.task,
  });
}

Test Strategy: Unit tests verify recording, summary computation, and persistence. Integration test with real TaskRouterService.

Rollback: Remove the optional hook from task-router.ts (revert ~10 LOC). Delete new files.

---

Workstream B: Dream Cycle + RVCOW Branching

Task 1.5: RVCOW Branching Adapter for Dream Cycles

Description: Create an adapter that provides copy-on-write branching semantics for dream cycle experimentation. Since @ruvector/rvf-node COW is not yet available, implement branching over SQLite using transaction savepoints and in-memory overlays.

Field	Value
Files to create	v3/src/learning/dream/dream-branch-manager.ts
Files to modify	v3/src/learning/dream/dream-engine.ts (optional injection point, ~15 LOC)
Agent	coder
Dependencies	None (uses existing SQLite)
Parallel Group	WS-B
Risk Level	Medium (touches dream engine)
Est. Hours	8

Interface:

/**
 * Copy-on-Write branching for dream cycle experimentation.
 *
 * Allows the DreamEngine to create isolated "branches" where speculative
 * pattern associations can be tested without affecting the main pattern store.
 * Successful branches are merged; failed branches are discarded.
 *
 * Implementation: SQLite savepoints + in-memory overlay (now).
 * Future: @ruvector/rvf-node RVCOW derive() when binaries ship.
 */

export interface DreamBranch {
  readonly branchId: string;
  readonly parentId: string | null;
  readonly createdAt: string;
  readonly status: 'active' | 'merged' | 'discarded';
  readonly insightCount: number;
}

export interface DreamBranchManager {
  /** Create a new branch for a dream cycle */
  createBranch(dreamCycleId: string): DreamBranch;

  /** Write a speculative insight to the branch */
  writeInsight(branchId: string, insight: DreamInsightData): void;

  /** Read all insights from a branch */
  readInsights(branchId: string): DreamInsightData[];

  /** Merge successful branch insights into the main store */
  mergeBranch(branchId: string, filter?: (insight: DreamInsightData) => boolean): MergeResult;

  /** Discard a branch (no side effects on main store) */
  discardBranch(branchId: string): void;

  /** List active branches */
  listBranches(): DreamBranch[];

  /** Dispose resources */
  dispose(): void;
}

export interface DreamInsightData {
  readonly insightId: string;
  readonly type: string;
  readonly confidence: number;
  readonly sourcePatterns: readonly string[];
  readonly description: string;
  readonly metadata?: Record<string, unknown>;
}

export interface MergeResult {
  readonly merged: number;
  readonly filtered: number;
  readonly conflicts: number;
}

Implementation approach (SQLite savepoints):

1. createBranch(): Records branch metadata in kv_store namespace dream-branches. Creates an in-memory map for branch-local writes.
2. writeInsight(): Stores insight in the in-memory overlay keyed by branchId.
3. mergeBranch(): Writes surviving insights to dream_insights table inside a single SQLite transaction. If the DreamEngine later supports RVF COW, this delegates to RvfDatabase.derive() and RvfDatabase.merge().
4. discardBranch(): Drops the in-memory overlay. Zero SQLite cost.

Modification to dream-engine.ts: Add optional branchManager?: DreamBranchManager to DreamConfig. When present, each dream cycle:

1. Creates a branch before spreading activation
2. Writes speculative insights to the branch
3. Merges insights that pass confidence threshold
4. Discards the rest

When absent, behavior is identical to current (direct writes).

Test Strategy: Unit tests with in-memory SQLite. Test branch isolation (writes in branch A invisible in branch B). Test merge/discard lifecycle. Test that dream engine works identically with and without branch manager.

Rollback: Remove injection point from DreamConfig (~15 LOC revert). Delete dream-branch-manager.ts.

---

Workstream C: Witness Chain + Quality Gates

Task 1.6: Shadow Witness Chain Logger

Description: Create a witness chain logger that records cryptographic hashes of quality gate decisions (test pass/fail, coverage thresholds, pattern promotions) in an append-only SQLite table. This shadows the production quality gate flow without affecting it.

Field	Value
Files to create	v3/src/domains/quality-assessment/services/witness-chain-logger.ts
Files to modify	None (shadow mode)
Agent	coder
Dependencies	None
Parallel Group	WS-C
Risk Level	Low
Est. Hours	5

Interface:

/**
 * Shadow Witness Chain Logger
 *
 * Records an append-only, hash-chained log of quality gate decisions.
 * Each entry links to its predecessor via SHA-256 hash, forming a
 * tamper-evident audit trail.
 *
 * Phase 1: SQLite table `witness_chain` in memory.db
 * Future: WITNESS_SEG in RVF container when rvf-node ships
 */

export interface WitnessEntry {
  readonly entryId: string;
  readonly previousHash: string | null;
  readonly contentHash: string;
  readonly timestamp: string;
  readonly eventType: WitnessEventType;
  readonly agentId?: string;
  readonly domain?: string;
  readonly payload: Record<string, unknown>;
}

export type WitnessEventType =
  | 'quality-gate-pass'
  | 'quality-gate-fail'
  | 'coverage-threshold'
  | 'pattern-promotion'
  | 'pattern-demotion'
  | 'test-suite-complete'
  | 'dream-cycle-merge'
  | 'routing-decision';

export interface WitnessChainLogger {
  /** Append a new entry to the witness chain */
  append(event: Omit<WitnessEntry, 'entryId' | 'previousHash' | 'contentHash' | 'timestamp'>): WitnessEntry;

  /** Verify the integrity of the entire chain */
  verifyChain(): { valid: boolean; brokenAt?: string; chainLength: number };

  /** Get the chain from a specific entry to the tip */
  getChainFrom(entryId: string): WitnessEntry[];

  /** Get the latest N entries */
  getRecent(n: number): WitnessEntry[];

  /** Get chain statistics */
  getStats(): {
    readonly chainLength: number;
    readonly firstEntry: string;
    readonly lastEntry: string;
    readonly eventTypeCounts: Record<WitnessEventType, number>;
  };

  /** Export chain for RVF WITNESS_SEG (future) */
  exportForRVF(): Buffer;

  /** Dispose */
  dispose(): void;
}

export function createWitnessChainLogger(db: DatabaseType): WitnessChainLogger;

SQLite Schema (new table in memory.db, additive only):

CREATE TABLE IF NOT EXISTS witness_chain (
  entry_id TEXT PRIMARY KEY,
  previous_hash TEXT,
  content_hash TEXT NOT NULL,
  timestamp TEXT NOT NULL,
  event_type TEXT NOT NULL,
  agent_id TEXT,
  domain TEXT,
  payload_json TEXT NOT NULL,
  FOREIGN KEY (previous_hash) REFERENCES witness_chain(content_hash)
);

CREATE INDEX IF NOT EXISTS idx_witness_chain_timestamp ON witness_chain(timestamp);
CREATE INDEX IF NOT EXISTS idx_witness_chain_event_type ON witness_chain(event_type);

Hashing: SHA-256 via Node.js crypto.createHash('sha256'). Content hash = SHA-256 of JSON.stringify({ eventType, agentId, domain, payload, timestamp }). Chain link = previousHash references the contentHash of the prior entry.

Test Strategy: Unit tests verify chain integrity, tamper detection (modify one entry, verify chain breaks), empty chain handling, and concurrent appends.

Rollback: Drop table witness_chain (or leave it -- it is harmless). Delete file.

---

Workstream D: HNSW Audit (Phase 1 Preparation)

Task 1.7: HNSW Implementation Audit and Unification Proposal

Description: Audit all 5 HNSW-like implementations in the codebase, document their interfaces, usage patterns, dimensions, and performance characteristics. Produce a unification proposal for Phase 2.

Field	Value
Files to create	docs/analysis/hnsw-unification-audit.md
Files to modify	None
Agent	researcher
Dependencies	None
Parallel Group	WS-D
Risk Level	None (documentation only)
Est. Hours	4

Known HNSW implementations (from codebase grep):

#	Class	Location	Type
1	InMemoryHNSWIndex	v3/src/kernel/unified-memory-hnsw.ts:123	Pure TypeScript HNSW
2	RuvectorFlatIndex	v3/src/kernel/unified-memory-hnsw.ts:539	Rust brute-force via @ruvector/gnn
3	QEGNNEmbeddingIndex	v3/src/integrations/ruvector/gnn-wrapper.ts:110	Rust differentiable search
4	HNSWIndex	v3/src/domains/coverage-analysis/services/hnsw-index.ts:224	Domain-specific HNSW
5	HNSWEmbeddingIndex	v3/src/integrations/embeddings/index/HNSWIndex.ts:28	Embedding-specific HNSW

Audit deliverables:

• Interface comparison table (methods, parameters, return types)
• Dimension usage per implementation (384? 768? variable?)
• Caller analysis: who uses which implementation and why
• Performance comparison at common workload (1K vectors, 384-dim, top-10 search)
• Unification feasibility: can all 5 be replaced by VectorBackend + backend selection?
• Risks of unification: domain-specific tuning that would be lost

Test Strategy: N/A (documentation). Audit verified by code review agent.

Rollback: N/A.

---

Phase 1 Parallel Execution Strategy

Phase1-Immediate (parallel):
  Task 1.1 (validate mincut-node)  |  Task 1.7 (HNSW audit)

WS-A (sequential after 1.1):
  Task 1.1 -> Task 1.2 -> Task 1.3 -> Task 1.4

WS-B (independent):
  Task 1.5 (dream branch manager)

WS-C (independent):
  Task 1.6 (witness chain logger)

WS-D (independent):
  Task 1.7 (HNSW audit)

All of WS-B, WS-C, and WS-D can run in parallel with each other and with WS-A.

Task	Workstream	Agent Type	Est. Hours	Depends On
1.1	WS-A	researcher	2	--
1.2	WS-A	coder	4	1.1
1.3	WS-A	coder	6	1.2
1.4	WS-A	coder	4	1.3
1.5	WS-B	coder	8	--
1.6	WS-C	coder	5	--
1.7	WS-D	researcher	4	--
Phase 1 Total		4 agents	33 hours

Wall-clock with 4 agents: ~16 hours (WS-A is the critical path at 16h sequential).

Phase 1 Tests

Task	Test File	Test Type	Key Assertions
1.2	v3/tests/unit/integrations/ruvector/mincut-wrapper.test.ts	Unit (London School)	Factory creates TS backend when native unavailable; computeMinCut returns valid partitions; computeLambdas returns per-vertex connectivity; backend selection matches availability
1.3	v3/tests/unit/mcp/services/mincut-routing-service.test.ts	Unit (London School)	Shadow route returns tier based on lambda thresholds; metrics accumulate correctly; high-lambda tasks get Tier 3; isolated tasks get Tier 0
1.4	v3/tests/unit/mcp/services/routing-ab-comparator.test.ts	Unit	Comparisons recorded and summarized; agreement rate computed; flush persists to kv_store
1.5	v3/tests/unit/learning/dream/dream-branch-manager.test.ts	Unit	Branch isolation (writes invisible cross-branch); merge applies insights; discard removes overlay; DreamEngine works with and without branch manager
1.6	v3/tests/unit/domains/quality-assessment/witness-chain-logger.test.ts	Unit	Chain integrity verified; tamper detected; concurrent appends preserve ordering; export produces valid buffer

---

Phase 2: Progressive Integration (Weeks 5-10)

Phase 2 promotes shadow systems to production-optional (feature-flagged) and begins unifying the fragmented HNSW landscape.

Workstream D (continued): HNSW Unification

Task 2.1: Unified Progressive HNSW Index

Description: Implement a progressive HNSW index that replaces the 3+ in-kernel implementations with a single VectorBackend-compatible implementation. Uses the VectorBackend interface from the bridge plan (RVF-0.5.1) so it plugs into UnifiedMemoryManager.

Field	Value
Files to create	v3/src/kernel/progressive-hnsw-backend.ts
Files to modify	v3/src/kernel/unified-memory-hnsw.ts (deprecation markers), v3/src/integrations/ruvector/feature-flags.ts (add flag)
Agent	coder
Dependencies	Bridge plan RVF-0.5.1 (VectorBackend interface), Task 1.7 (audit results)
Parallel Group	WS-D
Risk Level	Medium
Est. Hours	12

Interface (extends VectorBackend from bridge plan):

import type { VectorBackend } from './vector-backend';

/**
 * Progressive HNSW with 3-layer recall:
 * - Layer A: 70% recall, <1ms latency (coarse graph, few connections)
 * - Layer B: 85% recall, ~2ms latency (medium graph)
 * - Layer C: 95%+ recall, ~5ms latency (full HNSW)
 *
 * Queries can specify desired recall tier for latency/accuracy tradeoff.
 */
export interface ProgressiveHNSWBackend extends VectorBackend {
  /** Search with progressive recall control */
  searchProgressive(
    query: number[],
    k: number,
    options?: {
      /** Minimum recall tier: 'A' (fast), 'B' (balanced), 'C' (precise) */
      recallTier?: 'A' | 'B' | 'C';
      /** Timeout in ms -- falls back to best available results */
      timeoutMs?: number;
    }
  ): Array<{ id: string; score: number; recallTier: 'A' | 'B' | 'C' }>;

  /** Get build status of each layer */
  getLayerStats(): {
    layerA: { built: boolean; nodeCount: number; avgConnections: number };
    layerB: { built: boolean; nodeCount: number; avgConnections: number };
    layerC: { built: boolean; nodeCount: number; avgConnections: number };
  };

  /** Trigger async build of higher layers (non-blocking) */
  buildLayersAsync(): Promise<void>;
}

Implementation approach:

• Layer A: efConstruction=40, M=8 (fast build, coarse)
• Layer B: efConstruction=100, M=16 (standard HNSW)
• Layer C: efConstruction=200, M=32 (high-recall)
• All three share the same node data; only connection graphs differ
• Layer A is always built synchronously on insert
• Layers B and C are built asynchronously in background
• Search starts at the requested layer (default A), optionally refines with B/C if timeout allows

Feature flag: useProgressiveHNSW: boolean in RuVectorFeatureFlags, default false.

Test Strategy: Unit tests verify progressive recall (Layer A < Layer C recall). Benchmark at 1K/5K/10K vectors.

Rollback: Set useProgressiveHNSW=false. Falls back to existing InMemoryHNSWIndex or RuvectorCoreBackend.

---

Task 2.2: RVF Container Shadow Export from memory.db

Description: Create a read-only export utility that snapshots the current learning state (patterns, Q-values, dream insights) into a portable format. Since @ruvector/rvf-node is not yet available, export as a structured JSON+binary bundle that is forward-compatible with RVF when it ships.

Field	Value
Files to create	v3/src/integrations/ruvector/rvf-container-export.ts
Agent	coder
Dependencies	None
Parallel Group	WS-B
Risk Level	Low (read-only)
Est. Hours	6

Interface:

/**
 * Export QE brain state as a portable container.
 *
 * Phase 2: Exports as JSON manifest + binary vector blobs (.aqe-brain)
 * Phase 3: Exports as .rvf file when rvf-node ships
 */

export interface BrainExportManifest {
  readonly version: '1.0';
  readonly exportedAt: string;
  readonly sourceDb: string;
  readonly stats: {
    readonly patternCount: number;
    readonly vectorCount: number;
    readonly qValueCount: number;
    readonly dreamInsightCount: number;
    readonly witnessChainLength: number;
  };
  readonly domains: readonly string[];
  readonly checksum: string;
}

export interface BrainExportOptions {
  /** Which domains to include (default: all) */
  readonly domains?: readonly string[];
  /** Include vector embeddings (large) */
  readonly includeVectors?: boolean;
  /** Include Q-values */
  readonly includeQValues?: boolean;
  /** Include dream insights */
  readonly includeDreamInsights?: boolean;
  /** Include witness chain */
  readonly includeWitnessChain?: boolean;
  /** Output path */
  readonly outputPath: string;
}

export interface ContainerExporter {
  /** Export brain state to a portable container */
  export(options: BrainExportOptions): Promise<BrainExportManifest>;

  /** Get estimated export size (bytes) without exporting */
  estimateSize(options: Omit<BrainExportOptions, 'outputPath'>): Promise<number>;
}

export function createContainerExporter(dbPath: string): ContainerExporter;

Export format (.aqe-brain directory):

brain-export-2026-02-22/
  manifest.json          # BrainExportManifest
  patterns.jsonl         # One QE pattern per line
  vectors.bin            # Float32Array binary blob (id-indexed)
  vector-index.json      # Map<id, byte-offset> into vectors.bin
  q-values.jsonl         # Q-learning state-action values
  dream-insights.jsonl   # Dream cycle discoveries
  witness-chain.jsonl    # Witness chain entries

Safety: Read-only operation on memory.db. Uses PRAGMA journal_mode=wal read connection. Does NOT acquire write lock. Does NOT modify any data.

Test Strategy: Unit test with test database. Verify manifest checksums match content. Verify round-trip (export then re-import counts match).

Rollback: Delete file. No production wiring.

---

Task 2.3: MinCut-Based Test Suite Optimization

Description: Use mincut analysis to identify the minimum set of tests that, if they pass, provide maximum coverage assurance. Models the test suite as a graph (tests as vertices, shared code coverage as edges) and computes the minimum cut to find the critical test boundary.

Field	Value
Files to create	v3/src/domains/test-execution/services/mincut-test-optimizer.ts
Files to modify	None (opt-in service)
Agent	coder
Dependencies	Task 1.2 (mincut-wrapper)
Parallel Group	WS-A
Risk Level	Low (advisory only)
Est. Hours	8

Interface:

/**
 * MinCut-based test suite optimization.
 *
 * Given a test suite and coverage data, identifies:
 * 1. The critical test boundary (minimum tests for maximum coverage assurance)
 * 2. Redundant tests (removable without reducing coverage)
 * 3. Isolated tests (no shared coverage with other tests)
 * 4. Optimal test execution order (based on coverage graph topology)
 */

export interface TestNode {
  readonly testId: string;
  readonly testFile: string;
  readonly coveredFiles: readonly string[];
  readonly estimatedDurationMs: number;
}

export interface TestOptimizationResult {
  /** Critical tests -- must run for coverage assurance */
  readonly criticalTests: readonly string[];
  /** Tests that can be skipped without reducing coverage below threshold */
  readonly skippableTests: readonly string[];
  /** Optimal execution order (critical first, then diminishing returns) */
  readonly executionOrder: readonly string[];
  /** Estimated time savings if skippable tests are skipped */
  readonly estimatedTimeSavingsMs: number;
  /** Coverage graph statistics */
  readonly graphStats: {
    readonly testCount: number;
    readonly coverageEdges: number;
    readonly mincutValue: number;
    readonly connectedComponents: number;
  };
}

export interface MinCutTestOptimizer {
  /** Analyze test suite and produce optimization recommendations */
  optimize(tests: readonly TestNode[], coverageThreshold?: number): TestOptimizationResult;

  /** Get the coverage graph for visualization */
  getCoverageGraph(tests: readonly TestNode[]): MinCutGraph;
}

export function createMinCutTestOptimizer(wrapper: QEMinCutWrapper): MinCutTestOptimizer;

Test Strategy: Unit tests with synthetic test suites. Verify critical tests cover all files. Verify skippable tests are truly redundant.

Rollback: Delete file. Advisory service with no production wiring.

---

Task 2.4: Stoer-Wagner Integrity Monitoring

Description: Implement a health monitoring service that periodically computes the Stoer-Wagner exact mincut of the active agent swarm graph and the codebase dependency graph. Reports health as a "connectivity score" and alerts when the mincut drops below a threshold (indicating fragile topology).

Field	Value
Files to create	v3/src/coordination/mincut/stoer-wagner-monitor.ts
Files to modify	v3/src/coordination/mincut/index.ts (add export)
Agent	coder
Dependencies	Task 1.2 (mincut-wrapper)
Parallel Group	WS-D
Risk Level	Low
Est. Hours	6

Interface:

/**
 * Stoer-Wagner integrity monitor for swarm and codebase health.
 *
 * Periodically computes the exact minimum cut of:
 * 1. The active agent communication graph (from SwarmGraph)
 * 2. The codebase module dependency graph (from HypergraphEngine)
 *
 * Reports health as a normalized "connectivity score" and alerts when
 * topology becomes fragile (low mincut = easy to partition).
 */

export interface IntegritySnapshot {
  readonly timestamp: string;
  readonly swarmHealth: {
    readonly mincutValue: number;
    readonly vertexCount: number;
    readonly edgeCount: number;
    readonly weakVertices: ReadonlyArray<{ id: string; lambda: number }>;
    readonly score: number; // 0-1, higher = healthier
  };
  readonly codebaseHealth: {
    readonly mincutValue: number;
    readonly moduleCount: number;
    readonly dependencyCount: number;
    readonly fragileModules: ReadonlyArray<{ module: string; lambda: number }>;
    readonly score: number;
  };
  readonly overallScore: number;
  readonly alerts: readonly string[];
}

export interface StoerWagnerMonitorConfig {
  /** Polling interval in ms (default: 60000 = 1 minute) */
  readonly intervalMs?: number;
  /** Alert threshold for swarm mincut (default: 2.0) */
  readonly swarmAlertThreshold?: number;
  /** Alert threshold for codebase mincut (default: 1.0) */
  readonly codebaseAlertThreshold?: number;
  /** Callback for alerts */
  readonly onAlert?: (snapshot: IntegritySnapshot) => void;
}

export interface StoerWagnerMonitor {
  /** Start periodic monitoring */
  start(): void;

  /** Stop monitoring */
  stop(): void;

  /** Take a single snapshot now */
  snapshot(): IntegritySnapshot;

  /** Get historical snapshots */
  getHistory(limit?: number): IntegritySnapshot[];

  /** Dispose */
  dispose(): void;
}

export function createStoerWagnerMonitor(
  config: StoerWagnerMonitorConfig,
  swarmGraph: SwarmGraph,
  mincutWrapper: QEMinCutWrapper
): StoerWagnerMonitor;

Test Strategy: Unit tests with known graph topologies. Verify alert triggers at threshold. Verify scores are normalized 0-1.

Rollback: Delete file. Remove export from index.ts.

---

Task 2.5: QE Brain Export as Portable Container (CLI)

Description: Wire the container exporter (Task 2.2) into the AQE CLI as aqe brain export and aqe brain import commands.

Field	Value
Files to create	v3/src/cli/commands/brain.ts
Files to modify	v3/src/cli/index.ts (register command)
Agent	coder
Dependencies	Task 2.2
Parallel Group	WS-B
Risk Level	Low
Est. Hours	4

CLI interface:

aqe brain export [--output <path>] [--domains <list>] [--include-vectors] [--include-q-values]
aqe brain import <path> [--dry-run] [--merge-strategy <latest|highest-confidence|union>]
aqe brain info <path>

Test Strategy: Integration tests calling CLI commands against test database.

Rollback: Remove command registration. Delete file.

---

Phase 2 Parallel Execution Strategy

WS-A:  Task 2.3 (test optimizer)          -- depends on 1.2
WS-B:  Task 2.2 (container export) -> Task 2.5 (CLI)
WS-C:  (no Phase 2 tasks -- witness chain continues running from Phase 1)
WS-D:  Task 2.1 (progressive HNSW) | Task 2.4 (Stoer-Wagner monitor)

All workstreams run in parallel.

Task	Workstream	Agent Type	Est. Hours	Depends On
2.1	WS-D	coder	12	Bridge RVF-0.5.1, Task 1.7
2.2	WS-B	coder	6	--
2.3	WS-A	coder	8	Task 1.2
2.4	WS-D	coder	6	Task 1.2
2.5	WS-B	coder	4	Task 2.2
Phase 2 Total		4 agents	36 hours

Wall-clock with 4 agents: ~16 hours (WS-D at 12+6=18h is critical path, but 2.1 and 2.4 are parallel so ~12h).

Phase 2 Tests

Task	Test File	Test Type	Key Assertions
2.1	v3/tests/unit/kernel/progressive-hnsw-backend.test.ts	Unit + Benchmark	Layer A recall < Layer C recall; progressive search returns tier labels; all VectorBackend methods work; benchmark at 1K/5K/10K
2.2	v3/tests/unit/integrations/ruvector/rvf-container-export.test.ts	Unit	Export produces valid manifest; checksums match; counts match source DB; read-only (no DB modifications)
2.3	v3/tests/unit/domains/test-execution/mincut-test-optimizer.test.ts	Unit	Critical tests cover all files; skippable tests are redundant; execution order starts with critical
2.4	v3/tests/unit/coordination/mincut/stoer-wagner-monitor.test.ts	Unit	Alerts fire at threshold; scores normalized; history recorded
2.5	v3/tests/integration/cli/brain-command.test.ts	Integration	CLI export/import round-trip preserves data; --dry-run makes no changes

---

Phase 3: Native RVF (Weeks 11-16)

GATE: Phase 3 requires @ruvector/rvf-node to publish functional N-API binaries. Check weekly:

npm view @ruvector/rvf-node version
node -e "const rvf = require('@ruvector/rvf-node'); console.log(rvf.RvfDatabase.create('/tmp/test.rvf'))"

If the gate does not pass by Week 11, Phase 3 defers indefinitely. The Phase 1-2 implementations are production-viable without native RVF.

Task 3.1: Dual-Write -- Learning to Both SQLite and RVF

Description: When useRVFBackend=true, all learning writes (pattern store, Q-values, dream insights) go to both SQLite and the RVF container. SQLite remains the source of truth; RVF is validated against it.

Field	Value
Files to create	v3/src/integrations/ruvector/rvf-dual-writer.ts
Files to modify	v3/src/learning/pattern-store.ts (add dual-write hook), v3/src/integrations/ruvector/feature-flags.ts (add useRVFDualWrite flag)
Agent	coder
Dependencies	Bridge plan RVF-1.1+, Phase 2 complete
Parallel Group	WS-B
Risk Level	Medium
Est. Hours	10

Interface:

/**
 * Dual-writer that sends learning data to both SQLite and RVF.
 * SQLite is source of truth. RVF is validated against it.
 */

export interface DualWriteResult {
  readonly sqliteSuccess: boolean;
  readonly rvfSuccess: boolean;
  readonly divergence?: string;
}

export interface RVFDualWriter {
  /** Write a pattern to both stores */
  writePattern(pattern: QEPattern, embedding?: number[]): Promise<DualWriteResult>;

  /** Write a Q-value update to both stores */
  writeQValue(state: string, action: string, value: number): Promise<DualWriteResult>;

  /** Write a dream insight to both stores */
  writeDreamInsight(insight: DreamInsightData): Promise<DualWriteResult>;

  /** Get divergence report (RVF reads that differ from SQLite) */
  getDivergenceReport(): Promise<{
    readonly totalChecked: number;
    readonly divergences: number;
    readonly details: ReadonlyArray<{
      readonly key: string;
      readonly sqliteValue: unknown;
      readonly rvfValue: unknown;
    }>;
  }>;

  /** Dispose */
  dispose(): void;
}

Feature flag: useRVFDualWrite: boolean in RuVectorFeatureFlags, default false.

Test Strategy: Unit tests with mocked RVF backend. Verify both stores receive writes. Verify divergence detection.

Rollback: Set useRVFDualWrite=false. SQLite continues as sole destination.

---

Task 3.2: RVF Read Validation (100% Record Comparison)

Description: A validation service that reads every record from both SQLite and RVF and compares them. Runs as a background task and reports divergences. Must pass 100% agreement before RVF can be promoted to primary.

Field	Value
Files to create	v3/src/integrations/ruvector/rvf-validation-service.ts
Agent	coder
Dependencies	Task 3.1
Parallel Group	WS-B
Risk Level	Low (read-only comparison)
Est. Hours	6

Interface:

export interface ValidationResult {
  readonly timestamp: string;
  readonly totalRecords: number;
  readonly matched: number;
  readonly diverged: number;
  readonly missingInRVF: number;
  readonly missingInSQLite: number;
  readonly validationDurationMs: number;
  readonly passRate: number; // 0-1
  readonly details: ReadonlyArray<{
    readonly recordId: string;
    readonly type: 'pattern' | 'q-value' | 'insight';
    readonly issue: 'diverged' | 'missing-rvf' | 'missing-sqlite';
    readonly sqliteValue?: string;
    readonly rvfValue?: string;
  }>;
}

export interface RVFValidationService {
  /** Run full validation */
  validate(): Promise<ValidationResult>;

  /** Run incremental validation (only records changed since last run) */
  validateIncremental(): Promise<ValidationResult>;

  /** Get last validation result */
  getLastResult(): ValidationResult | null;

  /** Check if promotion is safe (100% pass rate) */
  isPromotionSafe(): boolean;
}

Test Strategy: Unit tests with intentionally diverged test data. Verify all divergence types detected.

Rollback: Delete file. Read-only service.

---

Task 3.3: Promote RVF to Primary, SQLite to Backup

Description: When validation passes at 100%, add a feature flag to make RVF the primary read path and SQLite the backup. Writes continue to both (dual-write). Reads prefer RVF with SQLite fallback.

Field	Value
Files to modify	v3/src/integrations/ruvector/feature-flags.ts (add rvfPrimary flag), v3/src/learning/pattern-store.ts (read path routing)
Agent	coder
Dependencies	Task 3.2 (must pass 100% validation)
Parallel Group	WS-B
Risk Level	High
Est. Hours	8

Feature flag: rvfPrimary: boolean in RuVectorFeatureFlags, default false.

Promotion criteria (enforced in code):

1. RVFValidationService.isPromotionSafe() === true
2. useRVFDualWrite has been true for at least 24 hours
3. No divergences in last 3 validation runs

Read path change:

// In PatternStore.search():
if (flags.rvfPrimary) {
  try {
    return await this.rvfStore.search(query, opts);
  } catch (error) {
    logger.warn('RVF read failed, falling back to SQLite', { error });
    return await this.sqliteSearch(query, opts);
  }
} else {
  return await this.sqliteSearch(query, opts);
}

Test Strategy: Integration tests verifying read path routing, fallback on RVF failure, promotion criteria enforcement.

Rollback: Set rvfPrimary=false. Reads revert to SQLite immediately. No data loss (dual-write ensures both stores are current).

---

Task 3.4: RVF Container Marketplace (Import/Export Domain Brains)

Description: Extend the brain export/import (Tasks 2.2, 2.5) to support domain-specific brain sharing. An AQE instance can export its "test-generation" brain and another instance can import it.

Field	Value
Files to create	v3/src/integrations/ruvector/rvf-marketplace.ts
Files to modify	v3/src/cli/commands/brain.ts (add marketplace subcommands)
Agent	coder
Dependencies	Task 2.5, Task 3.1
Parallel Group	WS-B
Risk Level	Medium
Est. Hours	8

Interface:

/**
 * RVF Container Marketplace -- share domain-specific brains between AQE instances.
 *
 * Export: Extract a single domain's patterns, Q-values, and insights into a
 *         portable .aqe-brain container.
 * Import: Merge a foreign domain brain into the local instance with conflict
 *         resolution and provenance tracking.
 */

export interface MarketplaceListing {
  readonly brainId: string;
  readonly domain: string;
  readonly version: string;
  readonly exportedAt: string;
  readonly patternCount: number;
  readonly vectorCount: number;
  readonly sourceInstance: string;
  readonly checksum: string;
  readonly description?: string;
}

export interface ImportOptions {
  /** Merge strategy for conflicting patterns */
  readonly mergeStrategy: 'latest-wins' | 'highest-confidence' | 'union' | 'skip-conflicts';
  /** Dry run (report what would change without changing) */
  readonly dryRun?: boolean;
  /** Namespace prefix for imported patterns (to avoid ID collisions) */
  readonly namespacePrefix?: string;
  /** Trust level for imported patterns (affects initial confidence) */
  readonly trustLevel?: 'full' | 'verified' | 'untrusted';
}

export interface ImportResult {
  readonly imported: number;
  readonly skipped: number;
  readonly conflicts: number;
  readonly conflictResolutions: ReadonlyArray<{
    readonly patternId: string;
    readonly resolution: string;
  }>;
}

export interface RVFMarketplace {
  /** Export a domain brain */
  exportDomain(domain: string, outputPath: string, description?: string): Promise<MarketplaceListing>;

  /** Import a domain brain */
  importDomain(containerPath: string, options: ImportOptions): Promise<ImportResult>;

  /** List available local brain exports */
  listLocal(): Promise<MarketplaceListing[]>;

  /** Validate a container before import */
  validate(containerPath: string): Promise<{ valid: boolean; errors: string[] }>;
}

CLI commands:

aqe brain marketplace export <domain> [--output <path>] [--description <text>]
aqe brain marketplace import <path> [--strategy <strategy>] [--dry-run] [--trust <level>]
aqe brain marketplace list
aqe brain marketplace validate <path>

Test Strategy: Integration tests with two test databases. Export from one, import to other. Verify pattern counts, conflict handling, provenance tracking.

Rollback: Remove marketplace commands. Delete file. Existing brain export/import unaffected.

---

Phase 3 Parallel Execution Strategy

WS-B (sequential):
  Task 3.1 (dual-write) -> Task 3.2 (validation) -> Task 3.3 (promotion)
  Task 3.4 (marketplace) -- parallel with 3.1/3.2, depends on 2.5 and 3.1

Task	Workstream	Agent Type	Est. Hours	Depends On
3.1	WS-B	coder	10	Bridge RVF-1.1+, Phase 2
3.2	WS-B	coder	6	3.1
3.3	WS-B	coder	8	3.2
3.4	WS-B	coder	8	2.5, 3.1
Phase 3 Total		2 agents	32 hours

Wall-clock with 2 agents: ~24 hours (3.1 -> 3.2 -> 3.3 is the critical path at 24h; 3.4 runs parallel with 3.2+3.3).

Phase 3 Tests

Task	Test File	Test Type	Key Assertions
3.1	v3/tests/unit/integrations/ruvector/rvf-dual-writer.test.ts	Unit	Both stores receive writes; divergence detected when stores differ; feature flag controls dual-write
3.2	v3/tests/unit/integrations/ruvector/rvf-validation-service.test.ts	Unit	100% match detected; divergences reported; missing records detected; promotion safety check
3.3	v3/tests/integration/learning/rvf-promotion.test.ts	Integration	RVF reads used when promoted; fallback to SQLite on RVF failure; promotion criteria enforced
3.4	v3/tests/integration/ruvector/rvf-marketplace.test.ts	Integration	Export/import round-trip; conflict resolution; dry-run; provenance tracking; validation

---

Complete File Inventory

New Files (22 files)

File	Phase	Workstream	Purpose
scripts/validate-mincut-node.ts	1	WS-A	Validate @ruvector/mincut-node availability
v3/src/integrations/ruvector/mincut-wrapper.ts	1	WS-A	Unified MinCut interface
v3/src/mcp/services/mincut-routing-service.ts	1	WS-A	Lambda-based shadow routing
v3/src/mcp/services/routing-ab-comparator.ts	1	WS-A	A/B shadow comparison
v3/src/learning/dream/dream-branch-manager.ts	1	WS-B	RVCOW branching for dreams
v3/src/domains/quality-assessment/services/witness-chain-logger.ts	1	WS-C	Append-only witness chain
docs/analysis/hnsw-unification-audit.md	1	WS-D	HNSW audit document
v3/src/kernel/progressive-hnsw-backend.ts	2	WS-D	Progressive 3-layer HNSW
v3/src/integrations/ruvector/rvf-container-export.ts	2	WS-B	Brain state export
v3/src/domains/test-execution/services/mincut-test-optimizer.ts	2	WS-A	Test suite optimization
v3/src/coordination/mincut/stoer-wagner-monitor.ts	2	WS-D	Health monitoring
v3/src/cli/commands/brain.ts	2	WS-B	CLI brain commands
v3/src/integrations/ruvector/rvf-dual-writer.ts	3	WS-B	Dual-write to SQLite+RVF
v3/src/integrations/ruvector/rvf-validation-service.ts	3	WS-B	RVF vs SQLite validation
v3/src/integrations/ruvector/rvf-marketplace.ts	3	WS-B	Container marketplace
v3/tests/unit/integrations/ruvector/mincut-wrapper.test.ts	1	WS-A	MinCut wrapper tests
v3/tests/unit/mcp/services/mincut-routing-service.test.ts	1	WS-A	Routing service tests
v3/tests/unit/mcp/services/routing-ab-comparator.test.ts	1	WS-A	A/B comparator tests
v3/tests/unit/learning/dream/dream-branch-manager.test.ts	1	WS-B	Dream branch tests
v3/tests/unit/domains/quality-assessment/witness-chain-logger.test.ts	1	WS-C	Witness chain tests
v3/tests/unit/kernel/progressive-hnsw-backend.test.ts	2	WS-D	Progressive HNSW tests
v3/tests/unit/coordination/mincut/stoer-wagner-monitor.test.ts	2	WS-D	Monitor tests

Modified Files (7 files, minimal changes)

File	Phase	Change	LOC Delta
v3/src/integrations/ruvector/index.ts	1	Add mincut-wrapper export	~3
v3/src/mcp/services/task-router.ts	1	Add optional shadow hook	~10
v3/src/learning/dream/dream-engine.ts	1	Add optional branchManager to DreamConfig	~15
v3/src/integrations/ruvector/feature-flags.ts	2	Add useProgressiveHNSW, useRVFDualWrite, rvfPrimary flags	~20
v3/src/kernel/unified-memory-hnsw.ts	2	Add deprecation markers on old classes	~5
v3/src/coordination/mincut/index.ts	2	Add Stoer-Wagner monitor export	~3
v3/src/learning/pattern-store.ts	3	Add dual-write hook and RVF read path	~30

---

Agent Roster and Swarm Configuration

Recommended Swarm Init

npx @claude-flow/cli@latest swarm init \
  --topology hierarchical \
  --max-agents 8 \
  --strategy specialized

Agent Assignments

Agent ID	Type	Workstream	Phase 1 Tasks	Phase 2 Tasks	Phase 3 Tasks
rvf-researcher-1	researcher	WS-A, WS-D	1.1, 1.7	--	--
rvf-coder-a	coder	WS-A	1.2, 1.3, 1.4	2.3	--
rvf-coder-b	coder	WS-B	1.5	2.2, 2.5	3.1, 3.2, 3.3, 3.4
rvf-coder-c	coder	WS-C	1.6	--	--
rvf-coder-d	coder	WS-D	--	2.1, 2.4	--
rvf-tester-1	tester	All	Phase 1 tests	Phase 2 tests	Phase 3 tests
rvf-reviewer-1	reviewer	All	Code review	Code review	Code review

Phase 1: 5 agents active (researcher + 3 coders + tester) Phase 2: 4 agents active (3 coders + tester) Phase 3: 3 agents active (1 coder + tester + reviewer)

---

Critical Path

Task 1.1 -> 1.2 -> 1.3 -> 1.4 -> [Phase 1 complete]
                                        |
                                        v
                                   Task 2.3 (test optimizer)
                                   Task 2.1 (progressive HNSW)  -- parallel
                                   Task 2.2 -> 2.5 (brain export + CLI)  -- parallel
                                   Task 2.4 (Stoer-Wagner)  -- parallel
                                        |
                                   [Phase 2 complete]
                                        |
                                        v
                              [GATE: rvf-node binaries ship]
                                        |
                                        v
                                   Task 3.1 -> 3.2 -> 3.3
                                   Task 3.4 (marketplace)  -- parallel
                                        |
                                   [Phase 3 complete]

Critical path duration: 1.1 (2h) + 1.2 (4h) + 1.3 (6h) + 1.4 (4h) + 2.1 (12h) + 3.1 (10h) + 3.2 (6h) + 3.3 (8h) = 52 hours sequential

With parallelism: ~32 hours of wall-clock time across 4 agents for Phases 1-2. Phase 3 adds ~24 hours.

---

Risk Register

Risk	Phase	Likelihood	Impact	Mitigation	Rollback
@ruvector/mincut-node is a stub	1	High	Low	TypeScript MinCutCalculator is the proven fallback	Use existing TS implementation
MinCut lambda thresholds poorly calibrated	1	Medium	Low	Shadow mode collects real data; thresholds tuned in Phase 2	Shadow mode has zero production impact
Dream branch manager corrupts insights	1	Low	Medium	In-memory overlay only; no SQLite writes until merge	Remove injection from DreamConfig
Witness chain grows unbounded	1-3	Medium	Low	Add TTL-based pruning; index on timestamp	Drop table (append-only, no dependencies)
Progressive HNSW slower than InMemoryHNSWIndex at small scale	2	Medium	Low	Feature-flagged; both paths available	Set useProgressiveHNSW=false
Dual-write introduces latency	3	Medium	Medium	Async RVF write (fire-and-forget with retry)	Set useRVFDualWrite=false
RVF promotion causes read errors	3	Low	High	Fallback to SQLite on any RVF read error; 3 validation passes required	Set rvfPrimary=false (instant revert)
memory.db modified during export	2	Low	Low	WAL read connection; no write lock acquired	Export is read-only
Marketplace import introduces bad patterns	3	Medium	Medium	Trust levels; imported patterns start at reduced confidence; dry-run	Delete imported patterns by namespace prefix

---

Success Metrics

Phase 1 Exit Criteria

• MinCut wrapper passes all unit tests with TypeScript backend
• Shadow routing service produces tier recommendations for 100+ real routing decisions
• A/B comparator has logged agreement rate data
• Dream branch manager passes isolation tests
• Witness chain logger produces valid hash chains
• HNSW audit document reviewed and approved

Phase 2 Exit Criteria

• Progressive HNSW passes recall benchmarks (Layer A=70%, B=85%, C=95%+)
• Brain export produces valid containers from real memory.db
• MinCut test optimizer identifies critical/skippable tests on real test suite
• Stoer-Wagner monitor detects artificially weakened topologies
• CLI aqe brain export/import round-trip works

Phase 3 Exit Criteria

• Dual-write to SQLite and RVF for 24+ hours with zero divergences
• Validation service reports 100% match on 3 consecutive runs
• RVF promoted to primary; 100 reads complete without fallback
• Marketplace export/import between two test instances
• All existing tests pass with both rvfPrimary=false and rvfPrimary=true

---

Summary

Phase	Duration	Tasks	New Files	Agent Hours	Key Deliverable
1: Shadow	Weeks 1-4	7	7	33	Shadow mincut routing, dream branching, witness chain
2: Progressive	Weeks 5-10	5	5	36	Progressive HNSW, brain export, test optimization, health monitoring
3: Native RVF	Weeks 11-16	4	3	32	Dual-write, validation, promotion, marketplace
Total	16 weeks	16	15 src + 7 test	101 hours	Production RVF integration with full rollback safety

All phases are feature-flagged with instant rollback. Phase 3 is gated on external dependency availability. Phases 1-2 deliver standalone value regardless of Phase 3 outcome.