ruvnet-brain 4.0.1 → 4.0.2

package/scripts/check-indexation.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * check-indexation.mjs — POSITIVE index-status confirmation for RuvNet-Brain's SEO surfaces.
+ *
+ * Why this exists: "indexable" is a passive assumption; "indexed" is a live fact. This probe
+ * replaces the assumption with a check you can run any time. It NEVER infers "indexed" from
+ * HTTP health alone — serving-ready is necessary but NOT sufficient for indexed.
+ *
+ * For each target it reports three independent facts:
+ *   1. SERVING  — does the URL return 200 (or a clean redirect), with a self-canonical and no noindex?
+ *   2. BING     — does a live `site:` query on Bing return the URL? (scrape; may be challenged)
+ *   3. GOOGLE   — best-effort `site:` on Google. Datacenter IPs are often challenged → "inconclusive".
+ *                 AUTHORITATIVE Google status needs Search Console; see GSC note below.
+ *
+ * Ground-truth upgrade path: set GSC_ACCESS_TOKEN (a Search Console OAuth token with the
+ * webmasters.readonly scope) and this probe will call the URL Inspection API for a definitive
+ * Google verdict instead of scraping. Until then Google is best-effort and labeled as such.
+ *
+ * Usage:  node scripts/check-indexation.mjs
+ * Exit:   0 always (it's a report, not a gate). Parse the printed table.
+ */
+
+const TARGETS = [
+  'https://isovision.ai/ruvnet-brain/',
+  'https://github.com/stuinfla/ruvnet-brain',
+  'https://isovision.ai/ruvnet-brain/',
+];
+
+const UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/126.0 Safari/537.36';
+
+const CHALLENGE = /captcha|unusual traffic|verify you are|challenge|are you a robot/i;
+
+async function serving(url) {
+  try {
+    const res = await fetch(url, { redirect: 'manual', headers: { 'User-Agent': UA } });
+    const loc = res.headers.get('location');
+    if (res.status >= 300 && res.status < 400 && loc) return { ok: true, note: `${res.status}→ ${loc}` };
+    if (res.status !== 200) return { ok: false, note: `HTTP ${res.status}` };
+    const html = await res.text();
+    const canonical = (html.match(/<link[^>]+rel=["']canonical["'][^>]*>/i) || [''])[0];
+    const noindex = /content=["'][^"']*noindex/i.test(html) || res.headers.get('x-robots-tag')?.includes('noindex');
+    const selfCanon = canonical.includes(url.replace(/\/$/, '')) || canonical.includes(url);
+    return { ok: !noindex, note: `200${noindex ? ' ⚠NOINDEX' : ''}${selfCanon ? ' canon=self' : canonical ? ' canon=other' : ' no-canon'}` };
+  } catch (e) {
+    return { ok: false, note: `unreachable: ${e.message}` };
+  }
+}
+
+async function siteQuery(engine, url) {
+  const host = new URL(url).host;
+  const path = new URL(url).pathname.replace(/\/$/, '');
+  const q = encodeURIComponent(`site:${host}${path}`);
+  const endpoint =
+    engine === 'bing' ? `https://www.bing.com/search?q=${q}` : `https://www.google.com/search?q=${q}`;
+  try {
+    const res = await fetch(endpoint, { headers: { 'User-Agent': UA } });
+    const body = await res.text();
+    if (CHALLENGE.test(body) || res.status !== 200) return 'inconclusive (bot-challenged)';
+    // Heuristic: an indexed result links back to the host+path somewhere in the results markup.
+    const needle = `${host}${path}`.toLowerCase();
+    const hits = (body.toLowerCase().match(new RegExp(needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) || []).length;
+    const noResults = /did not match any documents|no results found|there are no results/i.test(body);
+    if (noResults) return 'NOT indexed';
+    return hits > 1 ? 'INDEXED' : 'NOT indexed';
+  } catch (e) {
+    return `inconclusive (${e.message})`;
+  }
+}
+
+async function gscInspect(url) {
+  const token = process.env.GSC_ACCESS_TOKEN;
+  if (!token) return null;
+  try {
+    const res = await fetch('https://searchconsole.googleapis.com/v1/urlInspection/index:inspect', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ inspectionUrl: url, siteUrl: `sc-domain:${new URL(url).host}` }),
+    });
+    const j = await res.json();
+    const v = j?.inspectionResult?.indexStatusResult?.verdict;
+    return v ? `GSC(authoritative): ${v}` : `GSC: ${JSON.stringify(j).slice(0, 120)}`;
+  } catch (e) {
+    return `GSC error: ${e.message}`;
+  }
+}
+
+(async () => {
+  const stamp = new Date().toISOString();
+  console.log(`\n  RuvNet-Brain indexation probe — ${stamp}`);
+  console.log('  (SERVING = necessary; INDEXED = the fact that matters)\n');
+  for (const url of TARGETS) {
+    const [srv, bing, google, gsc] = await Promise.all([
+      serving(url),
+      siteQuery('bing', url),
+      siteQuery('google', url),
+      gscInspect(url),
+    ]);
+    console.log(`  ${url}`);
+    console.log(`    SERVING : ${srv.ok ? '✓' : '✗'} ${srv.note}`);
+    console.log(`    BING    : ${bing}`);
+    console.log(`    GOOGLE  : ${gsc || google + '  (best-effort; set GSC_ACCESS_TOKEN for authoritative)'}`);
+    console.log('');
+  }
+  console.log('  Reminder: the fastest way to a definitive Google YES is Search Console →');
+  console.log('  URL Inspection → Request Indexing (needs a Google login). Everything else is latency.\n');
+})();

package/scripts/check-legibility.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// check-legibility.mjs — the gate for the bug that kept shipping.
+//
+// WHY (2026-07-17). Twice in one session a diagram shipped whose labels were PRESENT, unclipped,
+// non-overflowing, xmllint-clean, zero failed requests — and unreadable. The tips hero rendered its
+// labels at 8.1px; the MetaHarness diagram rendered its at 2.9px on a phone. Stuart's words: "I'm
+// not sure what that first animation is." He couldn't read it. Every automated check we owned
+// passed, because none of them measured the one thing that mattered.
+//
+// The cause is always the same: an SVG declares font-size in viewBox units, then gets rendered into
+// a column narrower than its viewBox. Every label silently multiplies by (renderedWidth/viewBoxWidth).
+// A 640-unit viewBox in a 453px column downscales 11.5px type to 8.1px. Nothing errors. It just
+// becomes invisible.
+//
+// This gate exists because of a hard-won distinction (see memory: feedback_never_grade_your_own_work):
+// a wall can only enforce FACTS, never TASTE. "Is this beautiful" is not gateable and any gate that
+// pretends otherwise just launders an opinion into a receipt. "Is this text >= N effective pixels"
+// IS a fact. So we gate exactly that, and nothing more.
+//
+// It measures via getScreenCTM() — the browser's REAL accumulated transform — not a hand-computed
+// ratio, so it survives nested transforms, CSS scaling, and responsive containers.
+//
+// It measures IN THE REAL PAGE, never the asset in isolation. That distinction is load-bearing: the
+// MetaHarness agent tested the asset at 380px and passed, while the real page squeezed it to 261px
+// behind gutters and padding. Testing the asset is not testing the page.
+//
+// Usage:
+//   node scripts/check-legibility.mjs --url http://127.0.0.1:7411/tips.html
+//   node scripts/check-legibility.mjs --url <url> --min 12 --widths 1440,1024,768 --selector '.hero-scene'
+//
+// Exit 0 = every label clears --min at every width. Exit 3 = something is too small to read.
+import { createRequire } from 'node:module';
+
+const args = process.argv.slice(2);
+const get = (k, d = null) => { const i = args.indexOf('--' + k); return i >= 0 ? args[i + 1] : d; };
+
+const url = get('url');
+const MIN = Number(get('min', 12));
+const widths = String(get('widths', '1440,1024,768')).split(',').map(Number);
+const selector = get('selector', 'svg');
+const themes = String(get('themes', 'dark,light')).split(',');
+
+if (!url) {
+  console.error('usage: check-legibility.mjs --url <url> [--min 12] [--widths 1440,1024,768] [--selector svg]');
+  process.exit(1);
+}
+
+// Playwright lives in the global npm prefix; resolve it rather than assuming a local install.
+let chromium;
+try {
+  const require = createRequire(import.meta.url);
+  ({ chromium } = require('playwright'));
+} catch {
+  try {
+    const require = createRequire(import.meta.url);
+    ({ chromium } = require('/Users/stuartkerr/.npm-global/lib/node_modules/playwright/index.js'));
+  } catch {
+    console.error('✗ playwright not resolvable — install it or run this gate where it is available');
+    process.exit(1);
+  }
+}
+
+const browser = await chromium.launch();
+const failures = [];
+const rows = [];
+
+for (const width of widths) {
+  for (const theme of themes) {
+    const page = await browser.newPage({ viewport: { width, height: 900 }, colorScheme: theme });
+    // NOT networkidle: the console holds a live connection open and would time out forever.
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    // The page keys off data-theme, not just the OS hint — stamp both or the "dark" run is a lie.
+    await page.evaluate((t) => { document.documentElement.dataset.theme = t; }, theme);
+    await page.waitForTimeout(900);
+
+    // Assert the viewport is what we asked for. Playwright's option is `viewport`; the plausible-
+    // looking `viewportSize` is SILENTLY IGNORED and renders everything at 1280. That already
+    // produced one false report on this project.
+    const vp = page.viewportSize();
+    if (vp.width !== width) {
+      failures.push(`viewport lied: asked ${width}, got ${vp.width}`);
+      await page.close();
+      continue;
+    }
+
+    // (1) INLINE svg — the DOM can see its text, so use the browser's real transform.
+    const found = await page.evaluate(({ sel, min }) => {
+      const out = [];
+      for (const svg of document.querySelectorAll(sel)) {
+        if (!svg.getScreenCTM) continue;
+        const ctm = svg.getScreenCTM();
+        if (!ctm) continue;                       // not rendered (display:none, detached)
+        const box = svg.getBoundingClientRect();
+        if (box.width === 0) continue;
+        for (const t of svg.querySelectorAll('text')) {
+          const txt = (t.textContent || '').trim();
+          if (!txt) continue;
+          const cs = getComputedStyle(t);
+          // Hidden text is not a legibility problem — skip display:none / visibility:hidden /
+          // opacity:0, and anything a parent hid. A label a responsive breakpoint deliberately
+          // hides (e.g. the hero rings' labels on phones, where a legend carries them instead)
+          // must not be flagged as "3px and unreadable" when it renders zero pixels.
+          if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) continue;
+          let box; try { box = t.getBoundingClientRect(); } catch { box = null; }
+          if (box && (box.width === 0 || box.height === 0)) continue;   // clipped/collapsed → not visible
+          const declared = parseFloat(cs.fontSize);
+          if (!declared) continue;
+          // ctm.a is the real horizontal scale the browser applies, transforms included.
+          const effective = +(declared * ctm.a).toFixed(1);
+          out.push({ text: txt.slice(0, 34), declared, effective, ok: effective >= min,
+                     svgW: Math.round(box.width) });
+        }
+      }
+      return out;
+    }, { sel: selector, min: MIN });
+
+    // (2) <img src="*.svg"> — the whole reason this gate nearly shipped useless. An SVG behind an
+    // <img> is a CLOSED document: the parent page cannot see inside it, so pass (1) reports zero
+    // labels and the file sails through. That is exactly how metaharness.svg rendered its labels at
+    // 2.9px on a phone while every check "passed". So: find the <img>, fetch the SVG's SOURCE,
+    // read its viewBox + declared font-sizes, and scale by the img's REAL rendered width.
+    const imgSvgs = await page.evaluate(() => {
+      const out = [];
+      for (const img of document.querySelectorAll('img[src$=".svg"], object[data$=".svg"]')) {
+        const box = img.getBoundingClientRect();
+        if (box.width === 0) continue;            // not rendered
+        out.push({ src: img.getAttribute('src') || img.getAttribute('data'), renderedW: box.width });
+      }
+      return out;
+    });
+
+    for (const { src, renderedW } of imgSvgs) {
+      const abs = new URL(src, url).href;
+      let text;
+      try {
+        const r = await page.request.get(abs);
+        if (!r.ok()) { failures.push(`${width}px/${theme}: ${src} → HTTP ${r.status()}`); continue; }
+        text = await r.text();
+      } catch (e) { failures.push(`${width}px/${theme}: ${src} unfetchable (${e.message})`); continue; }
+
+      const vb = text.match(/viewBox\s*=\s*["']\s*[-\d.]+\s+[-\d.]+\s+([\d.]+)\s+([\d.]+)/i);
+      if (!vb) { rows.push({ width, theme, n: 0, min: null, note: `${src}: no viewBox — cannot scale` }); continue; }
+      const scale = renderedW / Number(vb[1]);
+
+      // Declared sizes: font-size="N" attributes, plus font-size:Npx in the SVG's own <style>.
+      const sizes = [
+        ...[...text.matchAll(/font-size\s*=\s*["']([\d.]+)/gi)].map((m) => Number(m[1])),
+        ...[...text.matchAll(/font-size\s*:\s*([\d.]+)px/gi)].map((m) => Number(m[1])),
+      ].filter((n) => n > 0);
+      if (!sizes.length) { rows.push({ width, theme, n: 0, min: null, note: `${src}: no font-size found` }); continue; }
+
+      const smallest = Math.min(...sizes);
+      const effective = +(smallest * scale).toFixed(1);
+      rows.push({ width, theme, n: sizes.length, min: effective, svgW: Math.round(renderedW),
+                  note: `${src} (img, viewBox ${vb[1]})` });
+      if (effective < MIN) {
+        failures.push(`${width}px/${theme}: ${src} smallest label → ${effective}px effective ` +
+          `(declared ${smallest} in a ${vb[1]}-unit viewBox rendered at ${Math.round(renderedW)}px) — under ${MIN}px`);
+      }
+    }
+
+    if (!found.length) { rows.push({ width, theme, n: 0, min: null, note: 'no svg <text> found' }); await page.close(); continue; }
+
+    const worst = found.reduce((a, b) => (b.effective < a.effective ? b : a));
+    const bad = found.filter((f) => !f.ok);
+    rows.push({ width, theme, n: found.length, min: worst.effective, svgW: worst.svgW, bad: bad.length });
+    for (const f of bad) {
+      failures.push(`${width}px/${theme}: "${f.text}" → ${f.effective}px effective (declared ${f.declared}, svg rendered ${f.svgW}px) — under ${MIN}px`);
+    }
+    await page.close();
+  }
+}
+await browser.close();
+
+console.log(`legibility · ${url} · min ${MIN}px · selector "${selector}"`);
+for (const r of rows) {
+  const flag = r.min === null ? '—' : r.min >= MIN ? '✓' : '✗';
+  console.log(`  ${flag} ${String(r.width).padStart(4)}px/${r.theme.padEnd(5)}  ${String(r.n).padStart(3)} labels  smallest ${r.min === null ? 'n/a' : r.min + 'px'}${r.note ? '  (' + r.note + ')' : ''}`);
+}
+
+if (failures.length) {
+  console.error(`\n✗ ${failures.length} label(s) below ${MIN}px effective — present, unclipped, and unreadable:`);
+  for (const f of failures.slice(0, 20)) console.error('   ' + f);
+  if (failures.length > 20) console.error(`   … and ${failures.length - 20} more`);
+  console.error('\n  Usually the viewBox is wider than the column it renders into. Size the viewBox to the');
+  console.error('  real render width (≈1:1), or give the figure a min-width + overflow-x:auto container.');
+  process.exit(3);
+}
+console.log(`\n✓ every label ≥ ${MIN}px effective at every width/theme tested`);

package/scripts/ci/build-fixture-kb.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// scripts/ci/build-fixture-kb.mjs — the fixture-staging logic shared by:
+//   • tests/mutation/install-selfcheck-consumption-mutation.test.mjs (M-D8b, local)
+//   • .github/workflows/stranger-matrix.yml (ADR-058 §D8, the stranger's-machine matrix)
+//
+// Stages a MINIMAL but REAL KB-bundle directory: the real forge-mcp-all.mjs (copied from kb/ at the
+// candidate SHA — so `--drop-mcp` deleting it for the seeded-broken scenario is a real, meaningful
+// mutation, not a synthetic one), a fake `.rvf` marker (gatherInstallState() only checks EXISTENCE,
+// never content), and `file:`-referenced reader-dep stubs for @xenova/transformers and @ruvector/rvf
+// (installReader() runs a REAL `npm i` inside the unpacked bundle — verified empirically that it
+// PRUNES any node_modules entry not declared as a dependency, even against an otherwise-empty
+// package.json, so a manually-placed stub does not survive; `file:` deps make npm install them for
+// real, from local paths, with zero network and zero real package weight).
+//
+// Deliberately NEVER ships forge-ask-all.mjs: its absence is what keeps bin/install.mjs's
+// smokeQuery() from trying to warm a real local embedding model, keeping every matrix cell fast,
+// offline, and hermetic — the same convention tests/integration/install-smoke.mjs's own "COMPLETE
+// brain dir" fixture and the M-D8b mutation test both already rely on.
+//
+// This script only STAGES a directory — it deliberately does not zip it (zip/unzip tooling differs
+// per OS: `zip -r` on POSIX, PowerShell's `Compress-Archive` on Windows — that one step stays in the
+// workflow YAML, native per runner).
+//
+//   node scripts/ci/build-fixture-kb.mjs --out <dir> [--drop-mcp] [--no-rvf]
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const argv = process.argv.slice(2);
+const arg = (flag, def = null) => { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : def; };
+const OUT = arg('--out');
+const DROP_MCP = argv.includes('--drop-mcp'); // M-D8a: the seeded-broken scenario
+const NO_RVF = argv.includes('--no-rvf');
+
+if (!OUT) {
+  console.error('usage: node scripts/ci/build-fixture-kb.mjs --out <dir> [--drop-mcp] [--no-rvf]');
+  process.exit(2);
+}
+
+fs.mkdirSync(OUT, { recursive: true });
+
+if (!DROP_MCP) {
+  fs.copyFileSync(path.join(REPO_ROOT, 'kb', 'forge-mcp-all.mjs'), path.join(OUT, 'forge-mcp-all.mjs'));
+}
+
+const xenStub = path.join(OUT, 'vendor', 'xenova-transformers-stub');
+fs.mkdirSync(xenStub, { recursive: true });
+fs.writeFileSync(path.join(xenStub, 'package.json'), '{"name":"@xenova/transformers","version":"0.0.0-fixture"}\n');
+const ruvectorStub = path.join(OUT, 'vendor', 'ruvector-rvf-stub');
+fs.mkdirSync(ruvectorStub, { recursive: true });
+fs.writeFileSync(path.join(ruvectorStub, 'package.json'), '{"name":"@ruvector/rvf","version":"0.0.0-fixture"}\n');
+fs.writeFileSync(path.join(OUT, 'package.json'), JSON.stringify({
+  name: 'ruvnet-brain-kb-fixture',
+  version: '0.0.0',
+  private: true,
+  dependencies: {
+    '@xenova/transformers': 'file:vendor/xenova-transformers-stub',
+    '@ruvector/rvf': 'file:vendor/ruvector-rvf-stub',
+  },
+}, null, 2));
+
+if (!NO_RVF) {
+  fs.writeFileSync(path.join(OUT, 'fixture.rvf'), 'not a real store — presence is what gatherInstallState() counts\n');
+}
+
+console.log(`[build-fixture-kb] staged ${OUT} (mcp: ${!DROP_MCP}, rvf: ${!NO_RVF})`);

package/scripts/ci/learning-replay-codex-adapter.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Fixture-generation adapter used only by scripts/learning-replay.mjs.
+// The installed Codex plugin manifest calls the stable user-level wrapper. RUVNET_BRAIN_HOME makes
+// that wrapper resolve this isolated generation, where this adapter observes the real lesson hook
+// and blocks the first command before the model can learn the CLI syntax from its output.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const raw = fs.readFileSync(0);
+let input = {};
+try { input = JSON.parse(raw.toString('utf8')); } catch { /* fail closed below for tool calls */ }
+
+const hookId = process.argv[2] || '';
+const event = String(input.hook_event_name || '');
+const here = path.dirname(fileURLToPath(import.meta.url));
+const sequenceFile = process.env.RUVNET_REPLAY_SEQUENCE_FILE || '';
+const attemptsFile = process.env.RUVNET_REPLAY_ATTEMPTS_FILE || '';
+const probe = process.env.RUVNET_REPLAY_LESSON_PROBE || '';
+
+if (event === 'PreToolUse') {
+  const recorder = process.env.RUVNET_REPLAY_RECORDER || '';
+  if (!recorder) process.exit(2);
+  const result = spawnSync(process.execPath, [recorder, attemptsFile, sequenceFile], {
+    input: raw,
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exit(result.status ?? 2);
+}
+
+if (event === 'UserPromptSubmit' && hookId === 'unprompted-speech') {
+  const shim = path.join(here, 'hook-shim.mjs');
+  const result = spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
+    input: raw,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CLAUDE_SESSION_ID: String(input.session_id || ''),
+      CLAUDE_PROJECT_DIR: String(input.cwd || process.cwd()),
+      RUVNET_HOOK_HOST: 'codex',
+    },
+  });
+  if (probe && String(result.stdout || '').includes(probe) && sequenceFile) {
+    try {
+      fs.mkdirSync(path.dirname(sequenceFile), { recursive: true });
+      fs.appendFileSync(sequenceFile, JSON.stringify({
+        kind: 'lesson',
+        atNs: process.hrtime.bigint().toString(),
+      }) + '\n');
+    } catch { /* a missing receipt makes the replay fail closed */ }
+  }
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exit(result.status ?? 0);
+}
+
+process.exit(0);

package/scripts/ci/learning-replay-recorder.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// scripts/ci/learning-replay-recorder.mjs — the ARTIFACT TAP for the D4 counterfactual replay.
+//
+// Registered as a PreToolUse(Bash) hook inside a fixture session (never in a user's settings). Its
+// whole job is to capture the command the agent PRODUCED — the artifact the trap's oracle parses —
+// and to stop it from ever executing, because a fixture agent must not run anything on a real
+// machine and must not be allowed to LEARN the answer from a CLI's own output mid-run (a `--help`
+// that reveals the flag would contaminate the control arm and turn a measurable difference into an
+// unmeasurable one).
+//
+// It writes one JSON line per attempt, in order, with a monotonic timestamp. Order is the evidence
+// for PASS-condition (a): the lesson must be in the transcript BEFORE the first of these lines.
+//
+// The payload is parsed by plugin/scripts/hook-input.mjs — the repo's ONE hook-envelope translator
+// (DDD-0013's anti-corruption boundary against Claude Code's hook contract). Never a bash regex,
+// never a hand-rolled JSON.parse of an envelope shape, for the reason that file already records:
+// a JSON-escaped quote silently truncated a command in this exact codebase.
+//
+// Exit 2 + stderr is the documented BLOCK contract. Blocking is the point: the artifact is what the
+// agent WOULD have run, and letting it run would both mutate the machine and feed the agent an
+// answer the trap is trying to measure it for already having.
+//
+// Usage (as a hook):  node scripts/ci/learning-replay-recorder.mjs <attempts.jsonl>
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const HOOK_INPUT = path.resolve(HERE, '..', '..', 'plugin', 'scripts', 'hook-input.mjs');
+const out = process.argv[2];
+const sequenceOut = process.argv[3];
+
+let payload = '';
+try { payload = fs.readFileSync(0, 'utf8'); } catch { payload = ''; }
+
+let command = '';
+const r = spawnSync(process.execPath, [HOOK_INPUT, 'command'], { input: payload, encoding: 'utf8' });
+if (r.status === 0) command = String(r.stdout || '').trim();
+
+const atNs = process.hrtime.bigint().toString();
+if (out) {
+  try {
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.appendFileSync(out, JSON.stringify({ at: Date.now(), atNs, command }) + '\n');
+  } catch { /* a recorder that cannot write must still block; a silent run is worse than a lost line */ }
+}
+if (sequenceOut) {
+  try {
+    fs.mkdirSync(path.dirname(sequenceOut), { recursive: true });
+    fs.appendFileSync(sequenceOut, JSON.stringify({ kind: 'tool', atNs, command }) + '\n');
+  } catch { /* blocking still wins over a missing receipt */ }
+}
+
+// stderr is the channel exit 2 feeds back to the model (stdout is ignored on 2). Terse on purpose:
+// a long refusal is itself context, and this fixture is measuring what the agent brings IN.
+process.stderr.write('Sandbox: commands are not executed here. Your command was recorded. Do not retry; state your answer.\n');
+process.exit(2);

package/scripts/ci/mutate-hook-timeout.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// scripts/ci/mutate-hook-timeout.mjs — M-D8c (ADR-058 §D8): register ONE additional hook in the
+// PACKED, INSTALLED hooks.json whose body sleeps past its declared timeout, then run
+// `--doctor --hooks` again against the SAME installed surface and assert the battery goes RED.
+// Proves the hook-FIRE assertion is real (a genuine watchdog catch), not manifest-present —
+// tests/integration/install-smoke.mjs's own `--doctor --hooks goes RED when a registered hook
+// sleeps past its declared timeout` test is the fast local rehearsal of this exact mechanism
+// against a synthetic surface; this runs it against the REAL packed-and-installed plugin tree a
+// stranger's machine actually has, right after the `healthy` scenario's install.
+//
+//   node scripts/ci/mutate-hook-timeout.mjs --installed <dir> --home <dir>
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const argv = process.argv.slice(2);
+const arg = (flag) => { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : null; };
+const INSTALLED = arg('--installed');
+const HOME_DIR = arg('--home'); // the SAME home the `healthy` scenario already installed into
+
+if (!INSTALLED || !HOME_DIR) {
+  console.error('usage: node mutate-hook-timeout.mjs --installed <dir> --home <dir>');
+  process.exit(2);
+}
+
+const pluginRoot = path.join(HOME_DIR, '.claude', 'plugins', 'marketplaces', 'ruvnet-brain', 'plugin');
+const hooksFile = path.join(pluginRoot, 'hooks', 'hooks.json');
+if (!fs.existsSync(hooksFile)) {
+  console.error(`[mutate-hook-timeout] FAIL: no installed hooks.json at ${hooksFile} — run the healthy scenario first`);
+  process.exit(1);
+}
+
+// The REAL held-open-stdin hang fixture this repo already uses to prove the watchdog
+// (tests/fixtures/selfcheck-hooks/hang.mjs) — a synchronous stdin read freezes the event loop, so
+// only an EXTERNAL watchdog (never an in-process timer) can catch it.
+fs.copyFileSync(
+  path.join(REPO_ROOT, 'tests', 'fixtures', 'selfcheck-hooks', 'hang.mjs'),
+  path.join(pluginRoot, 'scripts', 'ci-hang-fixture.mjs'),
+);
+
+const doc = JSON.parse(fs.readFileSync(hooksFile, 'utf8'));
+doc.hooks ??= {};
+doc.hooks.UserPromptSubmit ??= [];
+doc.hooks.UserPromptSubmit.push({
+  matcher: '*',
+  hooks: [{ type: 'command', command: 'node "${CLAUDE_PLUGIN_ROOT}/scripts/ci-hang-fixture.mjs"', timeout: 1 }],
+});
+fs.writeFileSync(hooksFile, JSON.stringify(doc, null, 2));
+console.log(`[mutate-hook-timeout] registered a 1s-timeout sleeping hook in ${hooksFile}`);
+
+const r = spawnSync(process.execPath, [path.join(INSTALLED, 'bin', 'install.mjs'), '--doctor', '--hooks'], {
+  env: { ...process.env, HOME: HOME_DIR, USERPROFILE: HOME_DIR, RUVNET_BRAIN_TEST: '1' },
+  input: '',
+  encoding: 'utf8',
+  timeout: 120_000,
+});
+console.log(r.stdout);
+if (r.stderr) console.error(r.stderr);
+
+if (r.status === 0) {
+  console.error('[mutate-hook-timeout] FAIL: expected --doctor --hooks to go RED with a sleeping hook registered, got exit 0');
+  process.exit(1);
+}
+if (!/\bhang\b/.test(r.stdout || '')) {
+  console.error('[mutate-hook-timeout] FAIL: exited non-zero, but no "hang" violation was named — some OTHER check may have failed instead');
+  process.exit(1);
+}
+console.log(`[mutate-hook-timeout] PASS — the battery went RED (exit ${r.status}) with a real "hang" violation`);

package/scripts/ci/stranger-fixture-stage.mjs

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Stage one scenario's assembled `--local` bundle into the packed install.
+ *
+ * Scenarios share the installed package directory, so this must replace the
+ * previous scenario's bundle rather than merge into it. A merge can preserve a
+ * healthy scenario's files and silently repair the seeded-broken fixture.
+ */
+export function stageLocalBundle(sourceDir, installedDir) {
+  const targetDir = path.join(installedDir, 'dist', 'ruvnet-brain');
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.cpSync(sourceDir, targetDir, { recursive: true });
+  return targetDir;
+}