ruvnet-brain 4.0.4 → 4.0.6

package/scripts/learning-replay-cli.mjs

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadLessons, saveLessons } from './lesson-store.mjs';
+import {
+  EXIT,
+  INVARIANT,
+  MUTANTS,
+  MUTANT_RESULT_FILES,
+  PORTFOLIO_RESULT_FILES,
+  TRAP,
+  VERDICT,
+  WRONG_SUBCOMMAND_COMMAND,
+  aggregate,
+  trapSpec,
+  verdictForRun,
+} from './learning-replay-contract.mjs';
+import { verifyPostTaskContract, verifyRufloFlag } from './learning-replay-execution.mjs';
+import {
+  allocateRunBase,
+  buildFixtures,
+  nightlyRefresh,
+  recordInProjectA,
+  removeFixture,
+  runArm,
+  seedProjectBMemory,
+} from './learning-replay-fixture.mjs';
+import {
+  checkArtifact,
+  checkMutantArtifacts,
+  checkPortfolio,
+  checkSourceIdentity,
+  cleanupFixtureDaemons,
+  pruneArchive,
+  writeArtifact,
+} from './learning-replay-proof.mjs';
+import { ROOT } from './learning-replay-contract.mjs';
+
+const usage = () => `Usage:
+  node scripts/learning-replay.mjs [--trap ${TRAP.MEMORY_SEARCH}|${TRAP.POST_TASK}] [--n N] [--host codex|claude-code] [--model MODEL]
+  node scripts/learning-replay.mjs --check
+  node scripts/learning-replay.mjs --check-portfolio
+  node scripts/learning-replay.mjs --check-mutants
+  node scripts/learning-replay.mjs --dry-run
+  node scripts/learning-replay.mjs --mutant <${Object.keys(MUTANTS).join('|')}>
+
+Exit: 0=PASS, 1=FAIL, 3=INCONCLUSIVE, 4=UNKNOWN.`;
+
+function parse(argv) {
+  const has = (flag) => argv.includes(flag);
+  const arg = (flag, fallback) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+  };
+  return { has, arg };
+}
+
+function wireProbe(dirs, spec, stateDir) {
+  const result = spawnSync(process.execPath, [
+    path.join(ROOT, 'plugin', 'scripts', 'hook-shim.mjs'),
+    'unprompted-speech', 'UserPromptSubmit',
+  ], {
+    input: JSON.stringify({
+      prompt: spec.prompt,
+      session_id: `dry-${Date.now()}`,
+      cwd: dirs.projectB,
+    }),
+    encoding: 'utf8',
+    cwd: dirs.projectB,
+    env: {
+      ...process.env,
+      RUVNET_BRAIN_HOME: dirs.brainHome,
+      RUVNET_BRAIN_STATE_DIR: stateDir,
+      RUVNET_CONFIG_ROOT: path.join(dirs.base, 'config'),
+      RUVNET_LESSON_STORE: dirs.lessons,
+      RUVNET_LESSON_GATE_STATE: dirs.gateState,
+      CLAUDE_PLUGIN_ROOT: path.join(ROOT, 'plugin'),
+    },
+  });
+  return (result.stdout || '').length;
+}
+
+function printed(label, result) {
+  console.log(`\n  ${label}: ${result.status}\n  ${result.why}\n`);
+  return EXIT[result.status] ?? EXIT.UNKNOWN;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { has, arg } = parse(argv);
+  if (has('--help') || has('-h')) {
+    console.log(usage());
+    return EXIT.PASS;
+  }
+  const mutant = arg('--mutant', null);
+  const trap = arg('--trap', TRAP.MEMORY_SEARCH);
+  const host = arg('--host', 'codex');
+  const model = arg('--model', host === 'codex' ? 'gpt-5.6-sol' : 'haiku');
+  const n = Math.max(1, parseInt(arg('--n', mutant ? '1' : '3'), 10) || 1);
+  const outFile = arg('--out', mutant
+    ? MUTANT_RESULT_FILES[trap]?.[mutant]
+    : PORTFOLIO_RESULT_FILES[trap]);
+  if (mutant && !MUTANTS[mutant]) {
+    console.error(`unknown mutant "${mutant}"`);
+    return EXIT.UNKNOWN;
+  }
+  if (![TRAP.MEMORY_SEARCH, TRAP.POST_TASK].includes(trap) || !outFile) {
+    console.error(`unsupported trap/mutant: ${trap}/${mutant || 'normal'}`);
+    return EXIT.UNKNOWN;
+  }
+  if (has('--check')) {
+    return printed(INVARIANT, checkArtifact({ file: PORTFOLIO_RESULT_FILES[trap] }));
+  }
+  if (has('--check-portfolio')) return printed(`${INVARIANT}-PORTFOLIO`, checkPortfolio());
+  if (has('--check-mutants')) return printed(`${INVARIANT}-MUTANTS`, checkMutantArtifacts());
+
+  const source = checkSourceIdentity();
+  if (!source.clean) {
+    console.error(`  ${INVARIANT}: UNKNOWN — ${source.why}`);
+    return EXIT.UNKNOWN;
+  }
+
+  const spec = trapSpec(trap);
+  const premise = trap === TRAP.POST_TASK ? verifyPostTaskContract() : verifyRufloFlag();
+  console.log(`\n=== ${INVARIANT} — ${trap} ===`);
+  console.log(`  premise: ${premise.ok ? `VERIFIED: ${premise.evidence}` : `NOT VERIFIED: ${premise.why}`}`);
+  if (!premise.ok) {
+    writeArtifact(outFile, aggregate([]), { host, model, mutant, trap, task: spec.prompt });
+    return EXIT.UNKNOWN;
+  }
+
+  const base = allocateRunBase();
+  const dirs = buildFixtures(base);
+  process.once('exit', () => cleanupFixtureDaemons(dirs));
+  const record = recordInProjectA(dirs, { trap });
+  const seed = trap === TRAP.MEMORY_SEARCH
+    ? seedProjectBMemory(dirs)
+    : { key: null, storeExit: null, ok: true, skipped: 'not required' };
+  const refresh = nightlyRefresh(dirs);
+  console.log(`  record: ${record.projectCount} sources; promoted=${record.promoted}; ok=${record.ok}`);
+  console.log(`  seed: ${seed.skipped || `ok=${seed.ok}`}`);
+  console.log(`  refresh: ${refresh.generation}; lessonSurvived=${refresh.lessonSurvived}`);
+
+  if (mutant === 'delete-lesson') {
+    saveLessons([], dirs.lessons);
+    removeFixture(path.join(dirs.projectA, '.swarm', 'memory.db'));
+    console.log(`  mutant delete-lesson: ${loadLessons(dirs.lessons).length} lessons remain`);
+  }
+  if (mutant === 'empty-store') {
+    removeFixture(path.join(dirs.projectB, '.swarm', 'memory.db'));
+    console.log('  mutant empty-store: target memory removed');
+  }
+  if (has('--dry-run')) {
+    const treatedBytes = wireProbe(dirs, spec, dirs.stateOn);
+    const controlBytes = wireProbe(dirs, spec, dirs.stateOff);
+    const dry = aggregate([]);
+    dry.why = `--dry-run: no model called; treated ${treatedBytes}B, control ${controlBytes}B`;
+    writeArtifact(outFile, dry, {
+      host, model, mutant, trap, task: spec.prompt, record, seed, refresh, flag: premise,
+    });
+    if (!has('--keep-fixtures')) {
+      cleanupFixtureDaemons(dirs);
+      removeFixture(base);
+    }
+    return EXIT.UNKNOWN;
+  }
+
+  const runs = [];
+  for (let i = 1; i <= n; i++) {
+    const treated = runArm({
+      dirs,
+      arm: 'treated',
+      stateDir: mutant === 'brain-off-treated' ? dirs.stateOff : dirs.stateOn,
+      model,
+      host,
+      tag: `run${i}-treated`,
+      trap,
+      forceCommand: mutant === 'wrong-subcommand' ? WRONG_SUBCOMMAND_COMMAND : null,
+    });
+    const control = runArm({
+      dirs,
+      arm: 'control',
+      stateDir: dirs.stateOff,
+      model,
+      host,
+      tag: `run${i}-control`,
+      trap,
+      appendSystemPrompt: mutant === 'seed-control' ? spec.lesson : null,
+    });
+    const run = {
+      i,
+      treatedClass: treated.class,
+      controlClass: control.class,
+      lessonBeforeFirstToolCall: treated.lessonBeforeFirstToolCall,
+      controlLessonDelivered: control.lessonDelivered,
+      treatedSubcommandCorrect: treated.subcommandCorrect,
+      treatedExecOk: treated.exec?.exitOk === true,
+      treatedRetrieved: treated.exec?.retrieved === true,
+      treatedExecWhy: treated.exec?.why || null,
+      controlWorked: control.exec?.exitOk === true && control.exec?.retrieved === true,
+      treated,
+      control,
+      error: treated.spawnError || control.spawnError || null,
+    };
+    const verdict = verdictForRun(run);
+    console.log(`  run ${i}: ${verdict.verdict} — ${verdict.why}`);
+    runs.push(run);
+  }
+  const result = aggregate(runs);
+  const costUsd = runs.reduce((sum, run) =>
+    sum + (run.treated.costUsd || 0) + (run.control.costUsd || 0), 0);
+  const wallMs = runs.reduce((sum, run) =>
+    sum + (run.treated.wallMs || 0) + (run.control.wallMs || 0), 0);
+  const artifact = writeArtifact(outFile, result, {
+    host,
+    model,
+    mutant,
+    trap,
+    task: spec.prompt,
+    record,
+    seed,
+    refresh,
+    flag: premise,
+    costUsd,
+    wallMs,
+  });
+  if (!has('--keep-fixtures')) {
+    const preservePaths = artifact.runs.flatMap((run) => [
+      path.resolve(ROOT, run.treated.transcript.path),
+      path.resolve(ROOT, run.control.transcript.path),
+    ]);
+    pruneArchive(dirs, { preservePaths });
+  }
+  console.log(`  ${INVARIANT}: ${result.verdict} — ${result.why}`);
+  console.log(`  artifact: ${path.relative(ROOT, outFile)}`);
+  return EXIT[result.verdict] ?? EXIT.UNKNOWN;
+}

package/scripts/learning-replay-contract.mjs

@@ -0,0 +1,255 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findInvocations } from '../plugin/scripts/hook-input.mjs';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const INVARIANT = 'LEARNING-REPLAY';
+export const VERDICT = Object.freeze({
+  PASS: 'PASS',
+  FAIL: 'FAIL',
+  UNKNOWN: 'UNKNOWN',
+  INCONCLUSIVE: 'INCONCLUSIVE',
+});
+export const EXIT = Object.freeze({ PASS: 0, FAIL: 1, INCONCLUSIVE: 3, UNKNOWN: 4 });
+export const RESULT_FILE = path.join(ROOT, 'data', 'learning-replay-result.json');
+export const POST_TASK_RESULT_FILE = path.join(ROOT, 'data', 'learning-replay-post-task-result.json');
+export const TRAP = Object.freeze({
+  MEMORY_SEARCH: 'memory-search-query',
+  POST_TASK: 'hooks-post-task-persistence',
+});
+
+export const REPLAY_PROMPT =
+  'Earlier in this project someone recorded a note about the caching strategy. '
+  + "Recall it from this project's agent memory with the ruflo CLI. "
+  + 'Run the recall command now, then tell me what you ran.';
+export const LESSON_STATEMENT =
+  'When you look something up in agent memory with the ruflo CLI, run exactly '
+  + '`ruflo memory search -q "<query>" --path .swarm/memory.db` as the first and only Ruflo invocation; '
+  + 'a bare quoted phrase placed after the subcommand is rejected.';
+export const POST_TASK_PROMPT =
+  'Record successful completion of the release retry-budget investigation in ruflo hooks learning, '
+  + 'assign it to the tester agent, and persist the routing decision for later sessions. '
+  + 'Use the terminal CLI, not an MCP tool. Do not inspect help or run any setup command. '
+  + 'Run exactly one post-task command now, then tell me what you ran.';
+export const POST_TASK_LESSON =
+  'A ruflo hooks post-task call persists a reusable routing outcome only when it includes all three: '
+  + '--task with the task description, --agent with the executor, and --store-results; a success/task-id alone '
+  + 'may print success but does not create the routing decision that later learning reads.';
+
+export function trapSpec(id = TRAP.MEMORY_SEARCH) {
+  if (id === TRAP.POST_TASK) {
+    return {
+      id,
+      lessonId: 'FX-D4-ruflo-hooks-post-task-persistence',
+      prompt: POST_TASK_PROMPT,
+      lesson: POST_TASK_LESSON,
+      memoryKey: 'lesson-ruflo-hooks-post-task-persistence',
+      recordQuery: 'ruflo hooks post task routing persistence',
+      check: 'the produced ruflo hooks post-task command includes --task, --agent, and --store-results',
+    };
+  }
+  return {
+    id: TRAP.MEMORY_SEARCH,
+    lessonId: 'FX-D4-ruflo-memory-search-flag',
+    prompt: REPLAY_PROMPT,
+    lesson: LESSON_STATEMENT,
+    memoryKey: 'lesson-ruflo-memory-search-flag',
+    recordQuery: 'ruflo CLI memory query flag',
+    check: 'the produced ruflo memory search command delivers its query through -q/--query',
+  };
+}
+
+export const LOAD_BEARING = Object.freeze([
+  'scripts/learning-replay.mjs',
+  'scripts/learning-replay-contract.mjs',
+  'scripts/learning-replay-execution.mjs',
+  'scripts/learning-replay-fixture.mjs',
+  'scripts/learning-replay-proof.mjs',
+  'scripts/learning-replay-cli.mjs',
+  'scripts/ci/learning-replay-recorder.mjs',
+  'scripts/ci/learning-replay-codex-adapter.mjs',
+  'scripts/lesson-store.mjs',
+  'plugin/scripts/lesson-store.mjs',
+  'plugin/scripts/lesson-gate.mjs',
+  'plugin/scripts/lesson-command-scope.mjs',
+  'plugin/scripts/lesson-presentation.mjs',
+  'plugin/scripts/lesson-hooks.sh',
+  'plugin/scripts/unprompted-runtime.mjs',
+  'plugin/scripts/hook-shim.mjs',
+  'plugin/scripts/hook-input.mjs',
+]);
+
+export function classifyCommand(cmd) {
+  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  if (!invocations.length) return 'none';
+  let sawPositional = false;
+  for (const inv of invocations) {
+    const args = inv.args.filter((a) => a !== '');
+    if (args.some((a) => a === '-q' || a === '--query' || a.startsWith('--query='))) return 'flagged';
+    const bare = [];
+    for (let i = 0; i < args.length; i++) {
+      const value = args[i];
+      if (value.startsWith('-')) {
+        if (!value.includes('=') && args[i + 1] && !args[i + 1].startsWith('-')) i++;
+        continue;
+      }
+      bare.push(value);
+    }
+    const queryish = (value) => /\s/.test(value) || value.length > 24;
+    if (bare.length >= 3 || bare.slice(1).some(queryish)) sawPositional = true;
+  }
+  return sawPositional ? 'positional' : 'other';
+}
+
+export function subcommandCorrect(cmd) {
+  for (const inv of findInvocations(String(cmd || ''), ['ruflo', 'claude-flow'])) {
+    const words = inv.args.filter((a) => a !== '' && !a.startsWith('-'));
+    const memory = words.indexOf('memory');
+    if (memory !== -1 && words[memory + 1] === 'search') return true;
+  }
+  return false;
+}
+
+export const carriesToken = (classification) => classification === 'flagged';
+
+export function optionValue(args, short, long) {
+  for (let i = 0; i < args.length; i++) {
+    const value = args[i];
+    if (value === short || value === long) {
+      return args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null;
+    }
+    if (value.startsWith(`${long}=`)) return value.slice(long.length + 1);
+  }
+  return null;
+}
+
+export function classifyPostTaskCommand(cmd) {
+  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  if (!invocations.length) return 'none';
+  let sawPostTask = false;
+  for (const inv of invocations) {
+    const args = inv.args.filter(Boolean);
+    const hooks = args.indexOf('hooks');
+    if (hooks === -1 || args[hooks + 1] !== 'post-task') continue;
+    sawPostTask = true;
+    const task = optionValue(args, '-t', '--task');
+    const agent = optionValue(args, '-a', '--agent');
+    const store = args.includes('--store-results')
+      || args.some((a) => a.startsWith('--store-results=') && !/=false$/i.test(a));
+    if (task && agent && store) return 'flagged';
+  }
+  return sawPostTask ? 'partial' : 'other';
+}
+
+export function postTaskSubcommandCorrect(cmd) {
+  return findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']).some((inv) => {
+    const words = inv.args.filter((a) => a !== '' && !a.startsWith('-'));
+    const hooks = words.indexOf('hooks');
+    return hooks !== -1 && words[hooks + 1] === 'post-task';
+  });
+}
+
+export function verdictForRun(run) {
+  const {
+    treatedClass, controlClass, lessonBeforeFirstToolCall, error,
+    treatedSubcommandCorrect, treatedExecOk, treatedRetrieved, treatedExecWhy, controlWorked,
+  } = run;
+  if (error) return { verdict: VERDICT.UNKNOWN, why: `harness could not measure this run: ${error}` };
+  if (controlClass === 'none') {
+    return { verdict: VERDICT.UNKNOWN, why: 'the control arm produced no ruflo invocation at all — there is no comparable artifact to difference against' };
+  }
+  if (treatedClass === 'none') return { verdict: VERDICT.FAIL, why: 'the treated arm produced no ruflo invocation at all' };
+  if (carriesToken(controlClass) || controlWorked === true) {
+    return {
+      verdict: VERDICT.INCONCLUSIVE,
+      why: carriesToken(controlClass)
+        ? `the CONTROL arm produced the token (${controlClass}) — the model would have got it right without the lesson, so this trap measured nothing`
+        : `the CONTROL arm's command EXECUTED AND RETRIEVED (class "${controlClass}") — the model would have got it right without the lesson, so this trap measured nothing`,
+    };
+  }
+  if (!carriesToken(treatedClass)) return { verdict: VERDICT.FAIL, why: `treated arm produced "${treatedClass}", not the token` };
+  if (treatedSubcommandCorrect !== true) {
+    return { verdict: VERDICT.FAIL, why: 'treated arm carried the token on the WRONG SUBCOMMAND — the corrective action is unusable' };
+  }
+  if (treatedExecOk !== true) {
+    return { verdict: VERDICT.FAIL, why: `treated arm's produced command did not execute successfully: ${treatedExecWhy || 'not executed'}` };
+  }
+  if (treatedRetrieved !== true) {
+    return { verdict: VERDICT.FAIL, why: `treated arm's command exited 0 but RETRIEVED NOTHING: ${treatedExecWhy || 'no retrieval evidence'}` };
+  }
+  if (lessonBeforeFirstToolCall !== true) {
+    return { verdict: VERDICT.FAIL, why: 'treated arm carried the token but the lesson was NOT observed before the first tool call' };
+  }
+  return { verdict: VERDICT.PASS, why: `treated "${treatedClass}" vs control "${controlClass}"; the produced command executed and returned the required outcome` };
+}
+
+export function aggregate(runs, { threshold = 2 / 3 } = {}) {
+  const perRun = runs.map((run) => ({ ...run, ...verdictForRun(run) }));
+  const n = perRun.length;
+  const passes = perRun.filter((run) => run.verdict === VERDICT.PASS).length;
+  const fails = perRun.filter((run) => run.verdict === VERDICT.FAIL).length;
+  const unknowns = perRun.filter((run) => run.verdict === VERDICT.UNKNOWN).length;
+  const controlTokenRuns = perRun.filter((run) => carriesToken(run.controlClass)).length;
+  const controlWorkedRuns = perRun.filter((run) => run.controlWorked === true).length;
+  const treatedTokenRuns = perRun.filter((run) => carriesToken(run.treatedClass)).length;
+  const treatedSubcommandRuns = perRun.filter((run) => run.treatedSubcommandCorrect === true).length;
+  const treatedExecutedRuns = perRun.filter((run) => run.treatedExecOk === true).length;
+  const treatedRetrievedRuns = perRun.filter((run) => run.treatedRetrieved === true).length;
+  let verdict;
+  let why;
+  if (n === 0) {
+    verdict = VERDICT.UNKNOWN;
+    why = 'zero runs executed — an empty run is not a pass';
+  } else if (controlTokenRuns > 0 || controlWorkedRuns > 0) {
+    verdict = VERDICT.INCONCLUSIVE;
+    why = `${controlTokenRuns}/${n} CONTROL run(s) produced the token and ${controlWorkedRuns}/${n} executed+retrieved — the trap is invalid`;
+  } else if (passes / n >= threshold) {
+    verdict = VERDICT.PASS;
+    why = `${passes}/${n} runs passed (bar ${Math.ceil(threshold * n)}/${n})`;
+  } else if (unknowns > 0) {
+    verdict = VERDICT.UNKNOWN;
+    const error = perRun.map((run) => run.error).find(Boolean);
+    why = error
+      ? `${unknowns}/${n} run(s) could not be measured; executor error: ${error}`
+      : `${unknowns}/${n} run(s) could not be measured; ${passes}/${n} passed`;
+  } else {
+    verdict = VERDICT.FAIL;
+    why = `${passes}/${n} runs passed — below the ${Math.ceil(threshold * n)}/${n} bar`;
+  }
+  if (verdict === VERDICT.PASS && (controlTokenRuns > 0 || controlWorkedRuns > 0)) {
+    throw new Error('LEARNING-REPLAY: refusing PASS while a control succeeded');
+  }
+  const brokenPass = perRun.find((run) => run.verdict === VERDICT.PASS
+    && (run.treatedSubcommandCorrect !== true || run.treatedExecOk !== true || run.treatedRetrieved !== true));
+  if (brokenPass) throw new Error(`LEARNING-REPLAY: unusable PASS run ${brokenPass.i}`);
+  return {
+    verdict, why, n, passes, fails, unknowns,
+    controlTokenRuns, controlWorkedRuns, treatedTokenRuns,
+    treatedSubcommandRuns, treatedExecutedRuns, treatedRetrievedRuns,
+    rate: n ? +(passes / n).toFixed(4) : 0,
+    runs: perRun,
+  };
+}
+
+export const WRONG_SUBCOMMAND_COMMAND = 'ruflo recall -q "caching strategy"';
+export const MUTANTS = Object.freeze({
+  'delete-lesson': 'delete the recorded lesson after refresh',
+  'brain-off-treated': 'run the treated arm with the brain disabled',
+  'seed-control': 'pre-seed the control arm with the lesson',
+  'wrong-subcommand': 'substitute the treated artifact with a right flag on a wrong verb',
+  'empty-store': 'remove the seeded target memory before the gate runs',
+});
+export const MUTANT_RESULT_FILES = Object.freeze({
+  [TRAP.MEMORY_SEARCH]: Object.freeze({
+    'delete-lesson': path.join(ROOT, 'data', 'learning-replay-delete-lesson-result.json'),
+    'brain-off-treated': path.join(ROOT, 'data', 'learning-replay-brain-off-result.json'),
+  }),
+  [TRAP.POST_TASK]: Object.freeze({
+    'delete-lesson': path.join(ROOT, 'data', 'learning-replay-post-task-delete-lesson-result.json'),
+    'brain-off-treated': path.join(ROOT, 'data', 'learning-replay-post-task-brain-off-result.json'),
+  }),
+});
+export const PORTFOLIO_RESULT_FILES = Object.freeze({
+  [TRAP.MEMORY_SEARCH]: RESULT_FILE,
+  [TRAP.POST_TASK]: POST_TASK_RESULT_FILE,
+});

package/scripts/learning-replay-execution.mjs

@@ -0,0 +1,193 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { commandNodes, findInvocations } from '../plugin/scripts/hook-input.mjs';
+import { optionValue, TRAP } from './learning-replay-contract.mjs';
+
+export const PROJECT_B_MEMORY_KEY = 'note-caching-strategy';
+export const PROJECT_B_MEMORY_VALUE =
+  'The caching strategy for this project: responses are memoized in a two-tier LRU, '
+  + 'warm tier in memory and cold tier on disk, invalidated by content hash.';
+export const RETRIEVAL_EVIDENCE = Object.freeze({
+  positive: Object.freeze([PROJECT_B_MEMORY_KEY.slice(0, 12), PROJECT_B_MEMORY_VALUE.slice(0, 20)]),
+  negative: Object.freeze([
+    /No results found/i,
+    /Unknown command/i,
+    /Required option missing/i,
+    /Usage:\s*claude-flow memory/i,
+    /\[ERROR\]/,
+  ]),
+});
+
+export const RUFLO_BIN = process.env.RUVNET_RUFLO_BIN
+  || path.join(os.homedir(), '.npm-global', 'bin', 'ruflo');
+const MUTATING_SUBCOMMANDS = new Set([
+  'store', 'delete', 'rm', 'purge', 'cleanup', 'compress', 'import', 'export',
+  'backup', 'init', 'configure',
+]);
+
+function spawnRuflo(bin, args, options) {
+  return /\.[cm]?js$/i.test(bin)
+    ? spawnSync(process.execPath, [bin, ...args], options)
+    : spawnSync(bin, args, options);
+}
+
+export function assertRetrieved(out) {
+  const text = String(out || '');
+  for (const pattern of RETRIEVAL_EVIDENCE.negative) {
+    if (pattern.test(text)) return { retrieved: false, why: `output matched failure shape ${pattern}` };
+  }
+  const hit = RETRIEVAL_EVIDENCE.positive.find((value) => text.includes(value));
+  if (!hit) return { retrieved: false, why: 'output names neither the seeded key nor its text' };
+  return { retrieved: true, why: `output carries the seeded memory (matched "${hit}")` };
+}
+
+export function assertPostTaskPersisted({ args, output, cwd }) {
+  const task = optionValue(args, '-t', '--task');
+  const agent = optionValue(args, '-a', '--agent');
+  const taskId = optionValue(args, '-i', '--task-id')
+    || String(output || '').match(/Recording outcome for task:\s*([a-zA-Z0-9_-]+)/)?.[1]
+    || null;
+  if (!task || !agent || !taskId || !args.includes('--store-results')) {
+    return { retrieved: false, why: 'command lacked --task, --agent, --store-results, or a task id' };
+  }
+  let outcomes;
+  let memory;
+  try {
+    outcomes = JSON.parse(fs.readFileSync(path.join(cwd, '.claude-flow', 'routing-outcomes.json'), 'utf8'));
+    memory = JSON.parse(fs.readFileSync(path.join(cwd, '.claude-flow', 'memory', 'store.json'), 'utf8'));
+  } catch (error) {
+    return { retrieved: false, why: `persistence stores were not readable: ${error.message}` };
+  }
+  const outcome = (outcomes.outcomes || []).find((row) =>
+    row.task === task && row.agent === agent && row.success === true);
+  const decision = memory.entries?.[`routing-decision:${taskId}`];
+  let value = null;
+  try { value = decision ? JSON.parse(decision.value) : null; } catch { /* invalid evidence */ }
+  if (!outcome || !decision || value?.task !== task || value?.agent !== agent) {
+    return { retrieved: false, why: 'no matching routing outcome and routing-decision row persisted' };
+  }
+  if (!/\[OK\]\s*Task outcome recorded:\s*SUCCESS/i.test(String(output || ''))) {
+    return { retrieved: false, why: 'rows exist but invocation did not report successful recording' };
+  }
+  return { retrieved: true, why: `routing outcome and routing-decision:${taskId} persisted` };
+}
+
+export function executeProducedCommand(cmd, {
+  cwd,
+  ruflo = RUFLO_BIN,
+  base = null,
+  trap = TRAP.MEMORY_SEARCH,
+} = {}) {
+  const reject = (why, extra = {}) => ({
+    ran: false,
+    argv: null,
+    exit: null,
+    exitOk: false,
+    retrieved: false,
+    why,
+    output: '',
+    ...extra,
+  });
+  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  if (!invocations.length) return reject('no Ruflo invocation to execute');
+  const firstExecutable = path.basename(commandNodes(String(cmd || ''))[0]?.exe || '').split('@')[0];
+  if (invocations.length !== 1 || firstExecutable !== 'ruflo') {
+    return reject('corrective command was not the first and only Ruflo invocation');
+  }
+  const args = invocations[0].args.filter((value) => value !== '');
+  if (args.some((value) => ['--help', '-h', '--version', 'version', 'status'].includes(value))) {
+    return reject('discovery cannot replace the requested corrective action');
+  }
+  for (let i = 0; i < args.length; i++) {
+    const value = args[i];
+    if (!['--path', '--db'].includes(value) && !/^--(?:path|db)=/.test(value)) continue;
+    const raw = value.includes('=') ? value.slice(value.indexOf('=') + 1) : args[i + 1];
+    const absolute = path.resolve(cwd, String(raw || ''));
+    const root = base && path.resolve(base);
+    if (!root || !(absolute === root || absolute.startsWith(`${root}${path.sep}`))) {
+      return reject(`store path ${absolute} is outside the fixture world`, { argv: ['ruflo', ...args] });
+    }
+  }
+  const mutating = args.filter((value) => !value.startsWith('-')).slice(0, 2)
+    .find((value) => MUTATING_SUBCOMMANDS.has(value));
+  if (mutating) return reject(`refused mutating subcommand "${mutating}"`, { argv: ['ruflo', ...args] });
+
+  const env = { ...process.env };
+  delete env.CLAUDE_FLOW_DB_PATH;
+  delete env.CLAUDE_FLOW_MEMORY_PATH;
+  const result = spawnRuflo(ruflo, args, {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000,
+    env,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.error) return reject(`spawn failed: ${result.error.message}`, { argv: ['ruflo', ...args] });
+  const output = `${result.stdout || ''}${result.stderr || ''}`;
+  const evidence = trap === TRAP.POST_TASK
+    ? assertPostTaskPersisted({ args, output, cwd })
+    : assertRetrieved(output);
+  return {
+    ran: true,
+    argv: ['ruflo', ...args],
+    exit: result.status,
+    exitOk: result.status === 0,
+    retrieved: evidence.retrieved,
+    why: `exit ${result.status}; ${evidence.why}`,
+    output: output.slice(0, 1200),
+  };
+}
+
+export function verifyRufloFlag(bin = RUFLO_BIN) {
+  if (!fs.existsSync(bin)) return { ok: false, why: `Ruflo binary not found at ${bin}` };
+  const result = spawnSync(bin, ['memory', 'search', '--help'], {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  const output = `${result.stdout || ''}${result.stderr || ''}`;
+  if (result.status !== 0 && !output) return { ok: false, why: `help exited ${result.status} empty` };
+  if (!/-q,\s*--query/.test(output)) return { ok: false, why: 'live help lacks -q, --query', help: output };
+  if (/\bmemory search\s+"[^"]+"\s*$/m.test(output)) {
+    return { ok: false, why: 'live help documents a positional query', help: output };
+  }
+  return {
+    ok: true,
+    flag: '-q, --query',
+    required: /--query[^\n]*required/i.test(output),
+    evidence: output.split('\n').find((line) => /-q,\s*--query/.test(line))?.trim() || '',
+  };
+}
+
+export function verifyPostTaskContract(bin = RUFLO_BIN) {
+  if (!fs.existsSync(bin)) return { ok: false, why: `Ruflo binary not found at ${bin}` };
+  const help = spawnRuflo(bin, ['hooks', 'post-task', '--help'], {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  const output = `${help.stdout || ''}${help.stderr || ''}`;
+  if (!/--task\b/.test(output) || !/--agent\b/.test(output) || !/--store-results\b/.test(output)
+    || !/Without this \+ --agent, no routing outcome is recorded/.test(output)) {
+    return { ok: false, why: 'live help lacks the three-part persistence contract', help: output };
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'd4-post-task-premise-'));
+  const missing = spawnRuflo(bin, ['hooks', 'post-task', '-i', 'd4-premise-missing', '--success', 'true'], {
+    cwd: dir,
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  const persisted = fs.existsSync(path.join(dir, '.claude-flow', 'routing-outcomes.json'))
+    || fs.existsSync(path.join(dir, '.claude-flow', 'memory', 'store.json'));
+  fs.rmSync(dir, { recursive: true, force: true });
+  if (missing.status !== 0 || persisted) {
+    return { ok: false, why: 'missing-contract probe did not remain successful and non-persistent' };
+  }
+  return {
+    ok: true,
+    flag: '--task + --agent + --store-results',
+    required: true,
+    evidence: 'live help names all flags; success/task-id-only persisted nothing',
+    missingExit: missing.status,
+  };
+}