ruvnet-brain 4.0.1 → 4.0.4

package/scripts/eval-brain.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// eval-brain.mjs — the eval flywheel. Ask the frozen held-out questions, and judge the answers by
+// GROUND TRUTH rather than by a model's opinion of them. (ADR-0011 Phase 0.)
+//
+// FIVE STRATA, because a gate that only asks easy questions cannot fail:
+//   named       — the repo is named in the question           pass = grounded AND routed
+//   described   — capability described, no names              pass = grounded AND routed
+//   scenario    — a real-world situation, no names            pass = grounded AND routed
+//   adversarial — the correct answer is NOT in this corpus    pass = ABSTAINED (top ce < 0, or no hits)
+//   provenance  — gist-shaped content                          pass = grounded AND (if the top hit IS a
+//                 gist chunk, it must carry its GIST STATUS banner — better repo grounding also passes)
+//
+// GATING IS ON THE WILSON LOWER BOUND, never the point estimate. With n=12, routed 10/12 had a 95%
+// CI of [55.2%, 95.3%] and 9/12's upper bound (91.1%) overlapped it completely — the gate could not
+// detect the regression it existed to catch. n=120 gives ≥80% power for a 0.90 -> 0.80 drop (n≈69
+// suffices; computed 2026-07-09).
+//
+// FAIL-CLOSED PROMOTION: `--gate` compares each metric's lower bound against evals/baseline.json and
+// exits 1 on any drop. A missing baseline is a failure too — you cannot promote against nothing.
+// Baselines are only ever written deliberately with `--record`.
+//
+// Why no model judge: an LLM panel scored a ZERO-CITATION answer 98/100 on this repo.
+//
+//   node scripts/eval-brain.mjs                 # run + table
+//   node scripts/eval-brain.mjs --gate          # run + exit 1 on regression (or missing baseline)
+//   node scripts/eval-brain.mjs --record        # run + write evals/baseline.json (deliberate)
+//   node scripts/eval-brain.mjs --json          # machine-readable
+//   node scripts/eval-brain.mjs --strata named,adversarial   # subset (never gate on a subset)
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+const HELD_OUT = path.join(ROOT, 'evals', 'held-out.json');
+const BASELINE = path.join(ROOT, 'evals', 'baseline.json');
+
+// The cross-encoder emits a relevance logit per (query, passage): strongly negative when unrelated.
+// An adversarial question "passes" when the brain effectively found nothing relevant. 0 is the
+// neutral cut; per-question ce values are recorded so this stays inspectable, and the Wilson-gated
+// baseline makes the stratum a regression detector even if the absolute rate is imperfect.
+export const ABSTAIN_CE = 0;
+
+/**
+ * Order-independent, tamper-evident hash of the held-out set — rUv's own frozen-eval pattern
+ * (ruflo harness-frozen-eval: humanEvalHash / FROZEN_HUMAN_EVAL_HASH). The pinned constant lives in
+ * tests/unit/eval-brain-gate.test.mjs; editing ANY question turns that test red, which is what
+ * "frozen" means mechanically. Reordering does not (sorting makes the hash order-independent).
+ */
+export async function heldOutHash(questions) {
+  const { createHash } = await import('node:crypto');
+  const per = questions.map((q) =>
+    createHash('sha256').update(JSON.stringify({ id: q.id, stratum: q.stratum, query: q.query, expectRepo: q.expectRepo ?? null })).digest('hex'));
+  return createHash('sha256').update(per.sort().join('')).digest('hex');
+}
+
+/** Wilson score interval — the same instrument rUv uses on every SWE-bench number. */
+export function wilson(k, n, z = 1.96) {
+  if (!n) return { p: 0, lo: 0, hi: 1 };
+  const p = k / n;
+  const d = 1 + (z * z) / n;
+  const c = (p + (z * z) / (2 * n)) / d;
+  const h = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / d;
+  return { p, lo: Math.max(0, c - h), hi: Math.min(1, c + h) };
+}
+
+/**
+ * Grade one answered question by its stratum's rule. Pure — takes the verifier verdict, the top
+ * citation (with its ce score), and whether the raw output carried the gist provenance banner.
+ */
+export function gradeQuestion(q, { grounded, citations, bannerPresent }) {
+  const top = citations?.[0] ?? null;
+  const routed = !!(grounded && q.expectRepo?.length && top && q.expectRepo.includes(top.repo));
+  const abstained = !top || (typeof top.ce === 'number' && top.ce < ABSTAIN_CE);
+  switch (q.stratum) {
+    case 'adversarial':
+      return { grounded, routed: null, abstained, pass: abstained };
+    case 'provenance':
+      // The mechanism under test: IF a gist chunk wins, it must carry its own status banner.
+      // A better hit from the real repo is not a failure — it is better grounding.
+      return { grounded, routed: null, abstained, pass: !!grounded && (top?.repo !== 'ruv-gists' || bannerPresent) };
+    default:
+      return { grounded, routed, abstained, pass: !!grounded && routed };
+  }
+}
+
+/** Aggregate graded rows into the four gated metrics, each with its Wilson interval. */
+export function aggregate(rows) {
+  const by = (pred) => rows.filter(pred);
+  const routedStrata = (r) => ['named', 'described', 'scenario'].includes(r.stratum);
+  const groundable = by((r) => r.stratum !== 'adversarial');
+  const routed = by(routedStrata);
+  const adversarial = by((r) => r.stratum === 'adversarial');
+  const provenance = by((r) => r.stratum === 'provenance');
+  const metric = (arr, key) => {
+    const k = arr.filter((r) => r[key]).length;
+    return { k, n: arr.length, ...wilson(k, arr.length) };
+  };
+  return {
+    grounded: metric(groundable, 'grounded'),
+    routed: metric(routed, 'pass'),
+    abstain: metric(adversarial, 'pass'),
+    banner: metric(provenance, 'pass'),
+  };
+}
+
+/** The fail-closed comparison: every metric's lower bound must hold the baseline's lower bound. */
+export function gateAgainst(current, baseline) {
+  if (!baseline) return { pass: false, regressions: ['no baseline to promote against — record one deliberately (--record)'] };
+  // An old-schema baseline (pre-strata counts, no {k,n,lo}) must FAIL, not pass vacuously — a gate
+  // that silently compares against nothing is the decorated-green failure this whole phase kills.
+  if (!['grounded', 'routed', 'abstain', 'banner'].some((m) => baseline[m]?.n)) {
+    return { pass: false, regressions: ['baseline is from an older schema — re-record deliberately (--record)'] };
+  }
+  const regressions = [];
+  for (const m of ['grounded', 'routed', 'abstain', 'banner']) {
+    const cur = current[m];
+    const base = baseline[m];
+    if (!base || !base.n) continue; // metric absent from an older baseline — cannot regress against nothing
+    if (!cur.n) { regressions.push(`${m}: stratum is empty but the baseline has n=${base.n}`); continue; }
+    if (cur.lo < base.lo - 1e-9) regressions.push(`${m}: lower bound ${(cur.lo * 100).toFixed(1)}% < baseline ${(base.lo * 100).toFixed(1)}%`);
+  }
+  return { pass: regressions.length === 0, regressions };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const GATE = argv.includes('--gate');
+  const RECORD = argv.includes('--record');
+  const JSON_OUT = argv.includes('--json');
+  const strataArg = argv.includes('--strata') ? argv[argv.indexOf('--strata') + 1]?.split(',') : null;
+  const die = (msg) => { console.error(`eval-brain: ${msg}`); process.exit(2); };
+
+  if (!fs.existsSync(path.join(KB, 'forge-ask-all.mjs'))) die(`no brain at ${KB} — run: npx ruvnet-brain`);
+  const verifierPath = path.join(KB, 'verify-citation.mjs');
+  if (!fs.existsSync(verifierPath)) die('this bundle predates verify-citation.mjs — refusing to score grounding without a way to check it');
+  const { verifyGrounding } = await import(pathToFileURL(verifierPath).href);
+
+  let { questions } = JSON.parse(fs.readFileSync(HELD_OUT, 'utf8'));
+  for (const q of questions) if (!q.stratum) die(`question ${q.id} has no stratum`);
+  if (strataArg) {
+    questions = questions.filter((q) => strataArg.includes(q.stratum));
+    if (GATE || RECORD) die('--strata is for local iteration only; never gate or record on a subset');
+  }
+
+  // Each question is an independent subprocess with its own ONNX thread, so the pool parallelizes
+  // cleanly across cores — spawnSync would serialize the whole run on the event loop. Measured
+  // serial cost was ~13.5s/question ≈ 27 min for 120; at concurrency 6 the wall drops ~6×.
+  const { execFile } = await import('node:child_process');
+  const ask = (query) => new Promise((resolve) => {
+    execFile('node', ['forge-ask-all.mjs', '--dir', KB, '--q', query, '--k', '3'],
+      { cwd: KB, timeout: 240000, env: process.env, maxBuffer: 64 * 1024 * 1024 },
+      (err, stdout) => resolve(err ? '' : String(stdout || '')));
+  });
+
+  const CONC = Math.max(1, Number(process.env.EVAL_CONCURRENCY ?? (argv.includes('--concurrency') ? argv[argv.indexOf('--concurrency') + 1] : 6)) || 6);
+  const rows = new Array(questions.length);
+  let cursor = 0;
+  let done = 0;
+  // An empty answer means the SUBPROCESS failed (contention, timeout, OOM) — an infrastructure
+  // event, not a retrieval verdict. Scoring it as "not grounded" pollutes the quality metric with
+  // ops noise: one dead process under 6-wide load dragged grounded's lower bound below baseline and
+  // failed a gate that retrieval never failed (caught live, 2026-07-10, question ho-04 → "ce=—").
+  // Retry once; if it still returns nothing, the row is an INFRA ERROR and the run is inconclusive.
+  const infraErrors = [];
+  const runOne = async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= questions.length) return;
+      const q = questions[i];
+      let out = await ask(q.query);
+      if (!out) { await new Promise((r) => setTimeout(r, 2000)); out = await ask(q.query); }
+      if (!out) {
+        infraErrors.push(q.id);
+        done++;
+        process.stderr.write(`\r[eval] ${done}/${questions.length} ! ${q.id} (infra)          `);
+        continue;
+      }
+      const v = await verifyGrounding(out, KB);
+      const graded = gradeQuestion(q, { grounded: v.grounded, citations: v.citations, bannerPresent: /GIST STATUS/.test(out) });
+      const top = v.citations?.[0] ?? null;
+      rows[i] = {
+        id: q.id, stratum: q.stratum, query: q.query,
+        citedRepo: top?.repo ?? null, citedPath: top?.fullPath ?? null, ce: top?.ce ?? null,
+        ...graded,
+      };
+      done++;
+      process.stderr.write(`\r[eval] ${done}/${questions.length} ${graded.pass ? '✓' : '✗'} ${q.id}          `);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONC, questions.length) }, runOne));
+  process.stderr.write('\n');
+
+  if (infraErrors.length) {
+    console.error(`[eval-brain] INCONCLUSIVE — ${infraErrors.length} infrastructure failure(s) after retry: ${infraErrors.join(', ')}`);
+    console.error('  A dead subprocess is not a retrieval verdict. Re-run (consider EVAL_CONCURRENCY=3 on a loaded machine).');
+    process.exit(2); // never a quality verdict, never a recorded baseline
+  }
+
+  const score = aggregate(rows.filter(Boolean));
+
+  if (JSON_OUT) {
+    console.log(JSON.stringify({ score, rows }, null, 2));
+  } else {
+    console.log(`\n# eval-brain — frozen held-out set (${rows.length} questions)\n`);
+    console.log('| metric | k/n | rate | 95% Wilson |');
+    console.log('|---|---|---|---|');
+    for (const [m, s] of Object.entries(score)) {
+      if (!s.n) continue;
+      console.log(`| ${m} | ${s.k}/${s.n} | ${(s.p * 100).toFixed(1)}% | [${(s.lo * 100).toFixed(1)}%, ${(s.hi * 100).toFixed(1)}%] |`);
+    }
+    const fails = rows.filter((r) => !r.pass);
+    if (fails.length) {
+      console.log(`\nFailures (${fails.length}):`);
+      for (const f of fails) console.log(`  ✗ ${f.id} [${f.stratum}] → ${f.citedRepo ?? '—'} ce=${f.ce ?? '—'}  ${f.query.slice(0, 64)}`);
+    }
+    console.log('\nGrounded = the cited passage exists on disk. Routed = the owning repo answered.');
+    console.log('Abstain = the brain declined an out-of-corpus question. Banner = a winning gist chunk carried its provenance.');
+    console.log('No model graded anything here.\n');
+  }
+
+  if (RECORD) {
+    fs.mkdirSync(path.dirname(BASELINE), { recursive: true });
+    fs.writeFileSync(BASELINE, JSON.stringify({ recorded: new Date().toISOString(), n: rows.length, score }, null, 2) + '\n');
+    console.error(`[eval-brain] baseline recorded (${rows.length} questions)`);
+  }
+
+  if (GATE) {
+    const baseline = fs.existsSync(BASELINE) ? JSON.parse(fs.readFileSync(BASELINE, 'utf8')).score : null;
+    const g = gateAgainst(score, baseline);
+    if (!g.pass) {
+      console.error(`[eval-brain] FAIL (fail-closed): ${g.regressions.join('; ')}`);
+      process.exit(1);
+    }
+    console.error('[eval-brain] PASS: every metric holds its baseline Wilson lower bound');
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/scripts/fix-metaharness-memretrieve.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// fix-metaharness-memretrieve.mjs — repair (and guard) a real bug in Ruflo's metaharness plugin.
+//
+// THE BUG
+// -------
+// `audit-list.mjs` and `audit-trend.mjs` read a stored audit record with:
+//     npx @claude-flow/cli memory retrieve --namespace <ns> --key <key>
+// ...WITHOUT `--format json`, then greedily `JSON.parse` whatever `{...}` they can scrape from
+// human-formatted stdout. But `memory retrieve --format json` returns an ENVELOPE:
+//     { id, key, namespace, content: "<the audit record, JSON-stringified>", ... }
+// so the record lives in `.content` (a string) and must be unwrapped. Without both changes,
+// memRetrieve() returns null for EVERY key, and `metaharness_audit_list` /
+// `metaharness_drift_from_history` silently report `records: []` while `totalInNamespace > 0`.
+// (Symptom: "0 audit records" even right after a successful oia-audit persisted one.)
+//
+// WHY THIS SCRIPT EXISTS
+// ----------------------
+// Both files live inside the GLOBAL npm package `@claude-flow/cli`, so `npm update -g` (or any
+// reinstall) silently reverts the patch. This has already happened twice. Rather than hand-edit
+// a third time, this script re-applies it idempotently AND can verify it in CI / a doctor check.
+//
+//   node scripts/fix-metaharness-memretrieve.mjs --check   # exit 1 if reverted (guard)
+//   node scripts/fix-metaharness-memretrieve.mjs --apply   # patch in place (idempotent)
+//
+// The durable fix is upstream; this keeps the local install honest until that lands.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+const TARGET_DIR =
+  process.env.METAHARNESS_SCRIPTS_DIR ||
+  path.join(os.homedir(), '.npm-global/lib/node_modules/@claude-flow/cli/plugins/ruflo-metaharness/scripts');
+
+export const FILES = ['audit-list.mjs', 'audit-trend.mjs'];
+const SENTINEL = 'outer.content'; // present only when the fix is applied
+
+const FIXED = `function memRetrieve(key) {
+  const r = spawnSync('npx', [
+    CLI_PKG, 'memory', 'retrieve',
+    '--namespace', NS, '--key', key, '--format', 'json',
+  ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', shell: process.platform === 'win32' });
+  if (r.status !== 0) return null;
+  const m = /\\{[\\s\\S]*\\}/.exec(r.stdout || '');
+  if (!m) return null;
+  try {
+    const outer = JSON.parse(m[0]);
+    // \`memory retrieve --format json\` wraps the record: { id, key, content: "<record JSON>" }.
+    // Unwrap \`content\` — parsing the envelope AS the record is the empty-results bug.
+    const inner = typeof outer.content === 'string' ? outer.content
+                : typeof outer.value === 'string' ? outer.value
+                : null;
+    if (inner) { try { return JSON.parse(inner); } catch { return null; } }
+    return (outer.startedAt || outer.composite) ? outer : null;
+  } catch { return null; }
+}`;
+
+// Match the whole memRetrieve function, up to the first closing brace at column 0.
+const FN_RE = /function memRetrieve\(key\) \{[\s\S]*?\n\}/;
+
+export function statusOf(file, dir = TARGET_DIR) {
+  const p = path.join(dir, file);
+  if (!fs.existsSync(p)) return { file, p, state: 'missing' };
+  const src = fs.readFileSync(p, 'utf-8');
+  if (src.includes(SENTINEL)) return { file, p, state: 'fixed', src };
+  if (FN_RE.test(src)) return { file, p, state: 'reverted', src };
+  return { file, p, state: 'unrecognized', src };
+}
+
+export function apply(dir = TARGET_DIR, log = console.log) {
+  let changed = 0;
+  for (const file of FILES) {
+    const s = statusOf(file, dir);
+    if (s.state === 'missing') { log(`  – ${file}: not installed here — nothing to patch`); continue; }
+    if (s.state === 'fixed') { log(`  ✓ ${file}: already fixed`); continue; }
+    if (s.state === 'unrecognized') { log(`  ⚠ ${file}: memRetrieve() not recognized — upstream changed shape; skipping`); continue; }
+    fs.writeFileSync(s.p, s.src.replace(FN_RE, FIXED), 'utf-8');
+    log(`  ✓ ${file}: PATCHED (envelope unwrap + --format json)`);
+    changed++;
+  }
+  log(changed ? `\napplied to ${changed} file(s).` : '\nnothing to do — already healthy.');
+  return 0;
+}
+
+// A guard that cries wolf gets ignored. `missing` means the metaharness plugin simply isn't
+// installed on this machine (the common case in CI) — that is NOT a failure. Only a file that
+// EXISTS and has lost the fix is a failure, because that is the exact state an `npm update -g`
+// leaves behind, and the symptom is silent (`records: []`, never an error).
+export function check(dir = TARGET_DIR, log = console.log) {
+  let reverted = 0;
+  let present = 0;
+  for (const file of FILES) {
+    const s = statusOf(file, dir);
+    if (s.state === 'missing') { log(`  – ${file}: n/a (metaharness plugin not installed)`); continue; }
+    present++;
+    if (s.state === 'reverted') reverted++;
+    log(`  ${s.state === 'fixed' ? '✓' : '✗'} ${file}: ${s.state}`);
+  }
+  if (!present) {
+    log('\n– metaharness plugin not installed — guard not applicable (pass).');
+    return 0;
+  }
+  if (reverted) {
+    log(`\n✗ ${reverted} file(s) reverted — an npm update wiped the fix.`);
+    log('  Repair: node scripts/fix-metaharness-memretrieve.mjs --apply');
+    return 1;
+  }
+  log('\n✓ metaharness memRetrieve fix intact.');
+  return 0;
+}
+
+// Only act when run directly, so tests can import the pure functions above.
+// Compare in URL space (pathToFileURL), not by decoding a URL into a path: `new URL(...).pathname`
+// yields "/D:/..." on Windows and never matches, so `--apply` would silently no-op there.
+const invokedDirectly = process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+if (invokedDirectly) {
+  const mode = process.argv.includes('--check') ? 'check' : 'apply';
+  console.log(`metaharness memRetrieve ${mode} — ${TARGET_DIR}\n`);
+  process.exit(mode === 'check' ? check() : apply());
+}

package/scripts/fix-workstream.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// Supervised fix lifecycle boundary: create one isolated writer lane, then seal a clean,
+// content-bound handoff. This command intentionally cannot merge, push, publish, promote,
+// delete, reset, or force-remove anything. Immutable release authority remains release-proof.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const FULL_SHA = /^[a-f0-9]{40}$/i;
+const SCOPED_BRANCH = /^(fix|bugfix|hotfix|issue|codex)\/[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+const SAFE_SCOPE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const RELEASE_COMMAND = 'node scripts/release-proof.mjs --candidate <candidate-receipt.json>';
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function command(commandName, args, options = {}) {
+  return spawnSync(commandName, args, {
+    encoding: options.encoding ?? 'utf8',
+    cwd: options.cwd,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+function git(cwd, args, { allowFailure = false, binary = false } = {}) {
+  const result = command('git', ['-C', cwd, ...args], {
+    cwd,
+    encoding: binary ? null : 'utf8',
+  });
+  if (!allowFailure && result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error?.message || 'unknown git failure').trim();
+    fail(`git ${args.join(' ')} failed: ${detail}`);
+  }
+  return result;
+}
+
+function output(cwd, args) {
+  return String(git(cwd, args).stdout || '').trim();
+}
+
+function parseArgs(args) {
+  const parsed = { evidence: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith('--')) fail(`unexpected argument: ${token}`);
+    const key = token.slice(2);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) fail(`missing value for --${key}`);
+    index += 1;
+    if (key === 'evidence') parsed.evidence.push(value);
+    else if (['integration', 'base', 'branch', 'worktree', 'scope', 'out'].includes(key)) parsed[key] = value;
+    else fail(`unknown option: --${key}`);
+  }
+  return parsed;
+}
+
+function requireAbsolute(value, label) {
+  if (!value) fail(`${label} is required`);
+  if (!path.isAbsolute(value)) fail(`${label} must be an absolute path`);
+  return path.resolve(value);
+}
+
+function requireScope(value) {
+  if (!SAFE_SCOPE.test(String(value || ''))) fail('scope must be a bounded identifier using letters, digits, dot, underscore, or dash');
+  return value;
+}
+
+function requireClean(cwd, role) {
+  const dirty = output(cwd, ['status', '--porcelain=v1', '--untracked-files=all']);
+  if (dirty) fail(`${role} worktree is dirty; preserve it and reconcile before continuing`);
+}
+
+function commonDirectory(cwd) {
+  const raw = output(cwd, ['rev-parse', '--git-common-dir']);
+  return fs.realpathSync(path.resolve(cwd, raw));
+}
+
+function currentBranch(cwd) {
+  const branch = output(cwd, ['branch', '--show-current']);
+  if (!branch) fail(`${cwd} is detached; a named branch is required`);
+  return branch;
+}
+
+function validateBase(cwd, base) {
+  if (!FULL_SHA.test(String(base || ''))) fail('base lineage must be an explicit full 40-character commit SHA');
+  const resolved = output(cwd, ['rev-parse', '--verify', `${base}^{commit}`]);
+  if (resolved !== base) fail('base lineage does not resolve to the explicit commit SHA');
+}
+
+function requireScopedBranch(branch, integrationBranch) {
+  if (!SCOPED_BRANCH.test(String(branch || '')) || branch === integrationBranch) {
+    fail('writer must use a scoped non-main branch (fix/, bugfix/, hotfix/, issue/, or codex/) distinct from integration');
+  }
+}
+
+function worktrees(cwd) {
+  const text = output(cwd, ['worktree', 'list', '--porcelain']);
+  return text.split(/\n\n+/).filter(Boolean).map((block) => {
+    const fields = {};
+    for (const line of block.split('\n')) {
+      const space = line.indexOf(' ');
+      fields[space === -1 ? line : line.slice(0, space)] = space === -1 ? true : line.slice(space + 1);
+    }
+    return fields;
+  });
+}
+
+function sameFilesystemEntry(left, right) {
+  try {
+    const leftStat = fs.statSync(left, { bigint: true });
+    const rightStat = fs.statSync(right, { bigint: true });
+    return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+  } catch {
+    return false;
+  }
+}
+
+function assertSingleOwner(cwd, branch, expectedPath, role) {
+  const ref = `refs/heads/${branch}`;
+  const owners = worktrees(cwd).filter((item) => item.branch === ref);
+  if (owners.length !== 1 || !sameFilesystemEntry(owners[0].worktree, expectedPath)) {
+    fail(`${role} branch has a shared writer or is not owned by the declared worktree`);
+  }
+}
+
+function receipt(payload) {
+  const encoded = JSON.stringify(payload);
+  return { ...payload, receiptId: `sha256:${createHash('sha256').update(encoded).digest('hex')}` };
+}
+
+function emit(value, outPath = null) {
+  const rendered = `${JSON.stringify(value, null, 2)}\n`;
+  if (outPath) {
+    const target = requireAbsolute(outPath, 'out');
+    if (fs.existsSync(target)) fail(`refusing to overwrite existing receipt: ${target}`);
+    fs.writeFileSync(target, rendered, { flag: 'wx', mode: 0o600 });
+  }
+  process.stdout.write(rendered);
+}
+
+function pendingRealPath(value, label) {
+  const absolute = requireAbsolute(value, label);
+  const parent = path.dirname(absolute);
+  if (!fs.existsSync(parent) || !fs.statSync(parent).isDirectory()) fail(`${label} parent directory does not exist: ${parent}`);
+  return path.join(fs.realpathSync(parent), path.basename(absolute));
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(fs.realpathSync(root), candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+export function startFixWorkstream(options) {
+  const integration = requireAbsolute(options.integration, 'integration');
+  const writer = requireAbsolute(options.worktree, 'worktree');
+  const scope = requireScope(options.scope);
+  validateBase(integration, options.base);
+  requireClean(integration, 'integration');
+  const integrationSha = output(integration, ['rev-parse', 'HEAD']);
+  if (integrationSha !== options.base) fail('base lineage must equal the current integration HEAD');
+  const integrationBranch = currentBranch(integration);
+  requireScopedBranch(options.branch, integrationBranch);
+  assertSingleOwner(integration, integrationBranch, integration, 'integration');
+
+  if (writer === integration || writer.startsWith(`${integration}${path.sep}`)) fail('writer worktree must be isolated from the integration worktree');
+  if (fs.existsSync(writer)) fail('writer worktree path already exists; it will not be removed or overwritten');
+  const branchRef = git(integration, ['show-ref', '--verify', `refs/heads/${options.branch}`], { allowFailure: true });
+  if (branchRef.status === 0) {
+    const owner = worktrees(integration).find((item) => item.branch === `refs/heads/${options.branch}`);
+    fail(owner ? `branch is already checked out at ${owner.worktree}; shared writers are forbidden` : 'writer branch already exists; branch reuse is forbidden');
+  }
+
+  const created = git(integration, ['worktree', 'add', '-b', options.branch, writer, options.base], { allowFailure: true });
+  if (created.status !== 0) {
+    const detail = String(created.stderr || created.stdout || created.error?.message || 'unknown git failure').trim();
+    fail(`git worktree add failed without cleanup or force removal: ${detail}`);
+  }
+
+  if (commonDirectory(writer) !== commonDirectory(integration)) fail('created writer is not in the integration repository lineage');
+  if (output(writer, ['rev-parse', 'HEAD']) !== options.base) fail('created writer HEAD does not match the explicit integration base');
+  requireClean(writer, 'writer');
+  assertSingleOwner(writer, options.branch, writer, 'writer');
+
+  return receipt({
+    schemaVersion: 1,
+    phase: 'workstream-start',
+    scope,
+    branch: options.branch,
+    worktree: writer,
+    integrationWorktree: integration,
+    integrationBranch,
+    baseSha: options.base,
+    baseTree: output(integration, ['rev-parse', `${options.base}^{tree}`]),
+    repositoryCommonDir: commonDirectory(integration),
+    publishAuthorized: false,
+    promotionAuthorized: false,
+    releaseGate: { authority: 'release-proof', command: RELEASE_COMMAND },
+  });
+}
+
+function requireAncestor(cwd, ancestor, descendant, message) {
+  const result = git(cwd, ['merge-base', '--is-ancestor', ancestor, descendant], { allowFailure: true });
+  if (result.status !== 0) fail(message);
+}
+
+function evidenceFiles(values) {
+  if (!Array.isArray(values) || values.length === 0) fail('at least one focused test or review evidence file is required');
+  return values.map((value) => {
+    const absolute = requireAbsolute(value, 'evidence');
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) fail(`evidence file does not exist or is not a file: ${absolute}`);
+    const bytes = fs.readFileSync(absolute);
+    return { path: absolute, sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
+  });
+}
+
+export function sealFixHandoff(options) {
+  const integration = requireAbsolute(options.integration, 'integration');
+  const writer = requireAbsolute(options.worktree, 'worktree');
+  const scope = requireScope(options.scope);
+  if (options.out) {
+    const out = pendingRealPath(options.out, 'out');
+    if (isWithin(integration, out) || isWithin(writer, out)) fail('handoff receipt must be outside the integration and writer worktrees');
+    if (fs.existsSync(out)) fail(`refusing to overwrite existing receipt: ${out}`);
+  }
+  validateBase(integration, options.base);
+  validateBase(writer, options.base);
+  requireClean(integration, 'integration');
+  requireClean(writer, 'writer');
+  if (commonDirectory(writer) !== commonDirectory(integration)) fail('writer and integration do not share repository lineage');
+
+  const integrationBranch = currentBranch(integration);
+  const writerBranch = currentBranch(writer);
+  requireScopedBranch(writerBranch, integrationBranch);
+  assertSingleOwner(integration, integrationBranch, integration, 'integration');
+  assertSingleOwner(writer, writerBranch, writer, 'writer');
+  const integrationSha = output(integration, ['rev-parse', 'HEAD']);
+  const writerSha = output(writer, ['rev-parse', 'HEAD']);
+  requireAncestor(integration, options.base, integrationSha, 'integration lineage does not descend from the declared base');
+  requireAncestor(writer, options.base, writerSha, 'writer lineage does not descend from the declared base');
+  if (writerSha === options.base) fail('writer contains no committed change to hand off');
+
+  const patchBytes = git(writer, ['diff', '--binary', `${options.base}..${writerSha}`], { binary: true }).stdout;
+  const changedPaths = output(writer, ['diff', '--name-status', `${options.base}..${writerSha}`])
+    .split('\n').filter(Boolean).map((line) => {
+      const [status, ...names] = line.split('\t');
+      return { status, path: names.join(' -> ') };
+    });
+  if (changedPaths.length === 0) fail('writer commit has no content change to hand off');
+
+  return receipt({
+    schemaVersion: 1,
+    phase: 'fix-handoff',
+    scope,
+    branch: writerBranch,
+    worktree: writer,
+    integrationWorktree: integration,
+    baseSha: options.base,
+    integrationSha,
+    writerSha,
+    writerTree: output(writer, ['rev-parse', `${writerSha}^{tree}`]),
+    patchSha256: createHash('sha256').update(patchBytes).digest('hex'),
+    changedPaths,
+    evidence: evidenceFiles(options.evidence),
+    publishAuthorized: false,
+    promotionAuthorized: false,
+    nextAuthority: 'integration-owner',
+    releaseGate: { authority: 'release-proof', command: RELEASE_COMMAND },
+  });
+}
+
+export function main(args = process.argv.slice(2)) {
+  const [operation, ...rest] = args;
+  if (!['start', 'handoff'].includes(operation)) {
+    console.error('fix-workstream: supported commands are start and handoff; this tool cannot merge, publish, promote, or clean up');
+    return 2;
+  }
+  try {
+    const options = parseArgs(rest);
+    const result = operation === 'start' ? startFixWorkstream(options) : sealFixHandoff(options);
+    emit(result, operation === 'handoff' ? options.out : null);
+    return 0;
+  } catch (error) {
+    console.error(`fix-workstream: ${error.message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = main();