ruvnet-brain 4.0.1 → 4.0.4

package/scripts/qe/ux-suite.mjs

@@ -0,0 +1,323 @@
+// ux-suite.mjs — the UX-experience QE suite runner (owner request 2026-07-24).
+//
+// Runs the deterministic UX probes, prints a table of MEASURED numbers, writes a machine-readable
+// receipt when UX_QE_EVIDENCE is set, and exits non-zero on any HARD failure.
+//  1. Environment-sensitive timings (server-ready, console/tips paint, command→explanation,
+//     dead-air) are HARD user-experience budgets. Platform calibration gives slower hosted runners
+//     honest headroom without turning "slow enough for a person to notice" into advisory green.
+//  2. kb/card-lane.mjs's decision lane is MODEL-FREE, ML-FREE keyword overlap with a measured warm
+//     baseline of 0.1158ms. Its budget (kb/card-lane-budget.json, p95 <= 250ms / absolute fail
+//     >1000ms — ~2,159x / ~8,600x the baseline) has so much headroom that a breach cannot be
+//     scheduler jitter — it can only be a correctness regression. THIS is a genuine hard gate: a
+//     breach here fails the suite, not warns it. See scripts/qe/card-lane-gate.mjs for the full
+//     reasoning and the in-process (no subprocess per firing) measurement method.
+//  3. SESSION-START WALL TIME (added 2026-07-28) is the SAME tier as 2, and is here because tier 2
+//     alone was not enough. An independent grader's words: the card-lane gate "measures a
+//     0.03–0.22ms in-process function against a 250ms budget (~1000x headroom — it can only catch
+//     catastrophic regression classes)", while "everything the user actually FEELS — heavy-lane
+//     query seconds, session-start WALL TIME, install minutes, dead air, refusal clarity — is
+//     advisory or unmeasured". Session-start wall time is the first of those promoted out of tier 1:
+//     it is the hook a stranger's Claude Code fires before their first prompt is answered, it is
+//     already measured by scripts/selfcheck.mjs's external process-group watchdog (no second timer
+//     was written), and its budget is set from a measured distribution — p95 1000ms is ~3.1x the
+//     worst measured p95 (323ms over n=110), NOT 1000x. See scripts/qe/session-start-gate.mjs.
+//
+// HONESTY (same rules as the product):
+//  • Every number is measured on THIS run. Nothing is asserted from memory.
+//  • A probe that could not execute is reported "not run" and HARD-fails — silence is not success.
+//  • The probes are MODEL-FREE (render + PTY-style timing, plus the in-process card-lane firings).
+//    They call no LLM, use no API key, touch no account — the cleanest satisfaction of the owner's
+//    "no API keys, run on our account" rule.
+//  • aqe orchestration: we OPTIONALLY register this run as an `aqe task` for visibility in
+//    `aqe status`, but the MEASUREMENT is a plain deterministic probe, NOT aqe-internal. Verified live
+//    2026-07-24: `aqe domain` supports only list/health (not create), so inventing an "onboarding-ux"
+//    domain would be fiction. We do not. If aqe isn't present, the suite runs identically and says so.
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { runCommandProbe } from '../../tests/ux/command-probe.mjs';
+import { runCardLaneGate } from './card-lane-gate.mjs';
+import { runSessionStartGate } from './session-start-gate.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const RENDER_PROBE = path.resolve(HERE, '../../tests/ux/render-probe.mjs');
+// The child now performs seven acceptance assertions, two real settings writes + reload, one real
+// batch remedy and one real undo in addition to paint timings. Its total wall clock is test-runtime,
+// not user-visible latency; each user action has its own hard 4s assertion inside the probe.
+const RENDER_PROBE_TIMEOUT_MS = 60_000;
+
+function stopProcessTree(child) {
+  if (!child?.pid) return;
+  if (process.platform === 'win32') {
+    try { spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }); } catch {}
+    return;
+  }
+  try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+  try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+}
+
+/**
+ * Browser drivers can wedge below JavaScript, so an in-process Promise timeout is not a bound.
+ * Run the render probe in its own process group and kill the whole group at the deadline.
+ */
+export function runRenderProbeIsolated({
+  probeFile = RENDER_PROBE,
+  timeoutMs = RENDER_PROBE_TIMEOUT_MS,
+} = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [probeFile], {
+      cwd: path.resolve(HERE, '../..'),
+      env: process.env,
+      detached: process.platform !== 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      stopProcessTree(child);
+      const trace = stderr.trim().split('\n').filter(Boolean).slice(-4).join(' | ');
+      finish({
+        results: [],
+        notes: [`render probe exceeded ${timeoutMs}ms process deadline${trace ? `; last stages: ${trace}` : ''}`],
+      });
+    }, timeoutMs);
+
+    child.on('error', (error) => finish({ results: [], notes: [`render probe spawn failed: ${error.message}`] }));
+    child.on('close', () => {
+      try {
+        const parsed = JSON.parse(stdout);
+        finish(parsed);
+      } catch {
+        const trace = stderr.trim().split('\n').filter(Boolean).slice(-4).join(' | ');
+        finish({ results: [], notes: [`render probe returned no readable JSON${trace ? `; last stages: ${trace}` : ''}`] });
+      }
+    });
+  });
+}
+
+// Darwin values are frozen from the measured 2026-07-24 baseline in docs/qe/ux-first-run.md.
+// Linux and Windows receive bounded hosted-runner startup headroom; the visible-paint and dead-air
+// product promises stay tight. These are release budgets, not performance claims about GitHub's
+// hardware. CI receipts make future recalibration evidence-based rather than guessed.
+export const PLATFORM_BUDGETS = Object.freeze({
+  darwin: Object.freeze({
+    'server-ready': 2500,
+    'console time-to-visible': 2500,
+    'tips time-to-visible (hero)': 2000,
+    'tips first-section': 2000,
+    commandToExplanationMs: 1500,
+    maxDeadAirMs: 3000,
+  }),
+  linux: Object.freeze({
+    'server-ready': 4000,
+    'console time-to-visible': 3000,
+    'tips time-to-visible (hero)': 2500,
+    'tips first-section': 2500,
+    commandToExplanationMs: 2500,
+    maxDeadAirMs: 3000,
+  }),
+  win32: Object.freeze({
+    'server-ready': 6000,
+    'console time-to-visible': 4000,
+    'tips time-to-visible (hero)': 3500,
+    'tips first-section': 3500,
+    commandToExplanationMs: 3000,
+    maxDeadAirMs: 3000,
+  }),
+});
+
+export function budgetsForPlatform(platform = process.platform) {
+  const budgets = PLATFORM_BUDGETS[platform];
+  if (!budgets) throw new Error(`unsupported UX-QE platform: ${platform}`);
+  return budgets;
+}
+
+export function timingFailure(label, measured, budget) {
+  if (measured == null) return `${label}: could not measure`;
+  if (measured > budget) return `${label}: ${measured}ms exceeds HARD ${budget}ms budget`;
+  return null;
+}
+
+function line(label, measured, unit, hardAt) {
+  const val = measured == null ? 'NOT RUN' : `${measured}${unit}`;
+  let flag = '';
+  if (measured == null) flag = '  ✗ could not measure';
+  else if (hardAt != null && measured > hardAt) flag = `  ✗ HARD FAIL (>${hardAt}${unit})`;
+  else if (hardAt != null) flag = `  ✓ HARD budget ${hardAt}${unit}`;
+  return `  ${label.padEnd(30)} ${String(val).padStart(10)}${flag}`;
+}
+
+function writeEvidence(receipt) {
+  const jsonOutIndex = process.argv.indexOf('--json-out');
+  if (jsonOutIndex >= 0 && !process.argv[jsonOutIndex + 1]) {
+    throw new Error('--json-out requires a file path');
+  }
+  const target = jsonOutIndex >= 0
+    ? process.argv[jsonOutIndex + 1]
+    : process.env.UX_QE_EVIDENCE;
+  if (!target) return;
+  const resolved = path.resolve(target);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, `${JSON.stringify(receipt, null, 2)}\n`);
+};
+
+function tryRegisterAqeTask() {
+  // Best-effort visibility only. Never fails the suite; never bills a model. `submit` enqueues
+  // metadata to the Queen Coordinator; `--no-progress` and no `--wait` keep it fire-and-forget, so no
+  // model is invoked. Flags grounded live 2026-07-24 against `aqe task submit --help` (type positional,
+  // -p/-d/-t/--payload — there is NO --description).
+  const payload = JSON.stringify({ probe: 'ruvnet-brain-ux-time-to-visible', model_free: true });
+  const r = spawnSync('aqe', ['task', 'submit', 'quality-assessment', '-p', 'p3', '--payload', payload, '--no-progress'], { encoding: 'utf8', timeout: 15000 });
+  if (r.error || r.status !== 0) return { registered: false, why: (r.error && r.error.message) || (r.stderr || '').trim().split('\n').filter(Boolean).pop() || `exit ${r.status}` };
+  const id = ((r.stdout || '').match(/task[- ]?id[:\s]+(\S+)/i) || [])[1] || 'submitted';
+  return { registered: true, id };
+}
+
+export async function runUxSuite() {
+  console.log('\n  RuvNet Brain — UX-experience QE suite  (deterministic · model-free · runs on your account)\n');
+  const platform = process.platform;
+  const budgets = budgetsForPlatform(platform);
+  const startedAt = new Date().toISOString();
+
+  const aqe = tryRegisterAqeTask();
+  console.log(aqe.registered
+    ? `  aqe: registered task ${aqe.id} for orchestration visibility (measurement is a plain probe)\n`
+    : `  aqe: not registered (${aqe.why}) — probes run identically; orchestration visibility only\n`);
+
+  const hardFailures = [];
+
+  // ── Probe 1: render time-to-visible ──────────────────────────────────────────────────────────
+  console.log('  ── time-to-visible (console + tips) ──');
+  const render = await runRenderProbeIsolated();
+  for (const r of render.results) {
+    console.log(line(r.label, r.ms, 'ms', budgets[r.label]));
+    const failure = timingFailure(r.label, r.ms, budgets[r.label]);
+    if (failure) hardFailures.push(failure);
+  }
+  for (const n of render.notes) { console.log(`  ! ${n}`); hardFailures.push(`render: ${n}`); }
+  console.log('\n  ── console control acceptance ──');
+  for (const row of render.acceptance || []) {
+    console.log(`  ${row.pass ? '✓' : '✗'} ${row.label}: ${row.detail}`);
+    if (!row.pass) hardFailures.push(`console control acceptance: ${row.label} — ${row.detail}`);
+  }
+  if (!(render.acceptance || []).length) hardFailures.push('console control acceptance: NOT RUN');
+  // Any expected render row missing entirely = not run = hard fail.
+  const gotConsole = render.results.some((r) => r.label === 'console time-to-visible' && r.ms != null);
+  if (!gotConsole) hardFailures.push('console time-to-visible: NOT RUN');
+
+  // ── Probe 2/3: command → explanation → "it's live" ──────────────────────────────────────────
+  console.log('\n  ── command → explanation → completion signal ──');
+  const cmd = await runCommandProbe();
+  console.log(line('command→explanation', cmd.commandToExplanationMs, 'ms', budgets.commandToExplanationMs));
+  console.log(line('command→"it\'s live"', cmd.commandToLiveMs, 'ms', null) + '  (reported, not gated)');
+  console.log(line('max dead-air gap', cmd.maxDeadAirMs, 'ms', budgets.maxDeadAirMs));
+  console.log(`  completion signal present      ${cmd.completionSignalPresent ? '        YES  ✓' : '         NO  ✗ (GAP)'}`);
+  if (cmd.liveSignalText) console.log(`    signal: "${cmd.liveSignalText}"`);
+
+  const explanationFailure = timingFailure('command→explanation', cmd.commandToExplanationMs, budgets.commandToExplanationMs);
+  if (explanationFailure) hardFailures.push(explanationFailure);
+  const deadAirFailure = timingFailure('max dead-air gap', cmd.maxDeadAirMs, budgets.maxDeadAirMs);
+  if (deadAirFailure) hardFailures.push(deadAirFailure);
+  if (!cmd.completionSignalPresent) hardFailures.push('completion signal MISSING — the "it\'s live, take a look at your page" line never printed');
+
+  // ── Probe 4: decision-lane latency — HARD GATE, not advisory (ADR-058 D6) ───────────────────
+  // Deliberately NOT reusing line()'s warnAt/"(proposed)" formatting above: that phrasing is correct
+  // for the advisory timings but would misreport a HARD budget breach as merely "proposed".
+  console.log('\n  ── decision-lane latency (kb/card-lane.mjs) — HARD GATE, deterministic, model-free ──');
+  try {
+    const laneResult = await runCardLaneGate();
+    const b = laneResult.budget;
+    const tag = (ok) => (ok ? '✓' : '✗ HARD FAIL');
+    console.log(`  ${'card-lane p50'.padEnd(30)} ${laneResult.p50.toFixed(4).padStart(10)}ms  (reported, not gated)`);
+    console.log(`  ${'card-lane p95'.padEnd(30)} ${laneResult.p95.toFixed(4).padStart(10)}ms  budget ${b.p95BudgetMs}ms  ${tag(laneResult.p95 <= b.p95BudgetMs)}`);
+    console.log(`  ${'card-lane max'.padEnd(30)} ${laneResult.max.toFixed(4).padStart(10)}ms  absolute-fail ${b.absoluteFailMs}ms  ${tag(laneResult.max <= b.absoluteFailMs)}`);
+    console.log(`  firings: ${laneResult.n} in-process (no subprocess per firing — see card-lane-gate.mjs)`);
+    if (!laneResult.pass) for (const r of laneResult.reasons) hardFailures.push(`card-lane latency: ${r}`);
+  } catch (e) {
+    console.log(`  ! could not run the card-lane latency gate: ${e.message}`);
+    hardFailures.push(`card-lane latency gate: could not run — ${e.message}`);
+  }
+
+  // ── Probe 5: session-start wall time — HARD GATE, the first USER-FELT number (ADR-058 D6) ───
+  // Wired exactly like probe 4 above and for the same reason: same tier, same "could not measure is
+  // never success" handling, same refusal to reuse line()'s "(proposed)" phrasing, which is correct
+  // for an advisory row and would misreport a HARD breach.
+  console.log('\n  ── session-start wall time (plugin/hooks/hooks.json SessionStart) — HARD GATE, user-felt ──');
+  try {
+    const ss = await runSessionStartGate();
+    const b = ss.budget;
+    const tag = (ok) => (ok ? '✓' : '✗ HARD FAIL');
+    console.log(`  ${'session-start cold first fire'.padEnd(30)} ${ss.warmupMs.toFixed(0).padStart(10)}ms  ${ss.warmupTimedOut ? '✗ HARD FAIL (declared timeout exceeded)' : '✓ inside declared timeout'}`);
+    console.log(`  ${'session-start p50'.padEnd(30)} ${ss.p50.toFixed(0).padStart(10)}ms  (reported, not gated)`);
+    console.log(`  ${'session-start p95'.padEnd(30)} ${ss.p95.toFixed(0).padStart(10)}ms  budget ${b.p95BudgetMs}ms  ${tag(ss.p95 <= b.p95BudgetMs)}`);
+    console.log(`  ${'session-start max'.padEnd(30)} ${ss.max.toFixed(0).padStart(10)}ms  absolute-fail ${b.absoluteFailMs}ms  ${tag(ss.max <= b.absoluteFailMs)}`);
+    console.log(`  firings: ${ss.n} sequential fires of the REAL registered command via selfcheck.mjs's watchdog, from ${ss.surface.source}`);
+    if (ss.warmupStderr) {
+      console.log(`  cold trace: ${ss.warmupStderr.trim().split('\n').join(' | ')}`);
+    }
+    if (!ss.pass) for (const r of ss.reasons) hardFailures.push(`session-start wall time: ${r}`);
+  } catch (e) {
+    console.log(`  ! could not run the session-start wall-time gate: ${e.message}`);
+    hardFailures.push(`session-start wall-time gate: could not run — ${e.message}`);
+  }
+
+  // ── Not run on this host (stated, never faked) ──────────────────────────────────────────────
+  console.log('\n  ── execution scope ──');
+  console.log(`    Platform          — ${platform} ${os.arch()} (this process; other OSes execute as separate CI jobs)`);
+  console.log('    Codex host        — NOT RUN: GitHub-hosted runners do not provide a configured Codex host; this probes the shipped console process directly');
+
+  // ── Verdict ─────────────────────────────────────────────────────────────────────────────────
+  const receipt = {
+    schemaVersion: 1,
+    suite: 'ruvnet-brain-ux-qe',
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    gitSha: process.env.GITHUB_SHA || null,
+    platform,
+    arch: os.arch(),
+    node: process.version,
+    budgetsMs: budgets,
+    render,
+    command: cmd,
+    hardFailures,
+    pass: hardFailures.length === 0,
+    scope: {
+      browser: 'Playwright Chromium, real local console HTTP server',
+      command: 'direct shipped console process',
+      codexHost: 'not-run',
+    },
+  };
+  writeEvidence(receipt);
+
+  console.log('\n  ── verdict ──');
+  if (hardFailures.length === 0) {
+    console.log('  PASS — every probe ran and every render, explanation, dead-air, decision-lane, and session-start HARD budget passed.\n');
+    return receipt;
+  }
+  console.log('  FAIL (hard):');
+  for (const f of hardFailures) console.log(`    ✗ ${f}`);
+  console.log('');
+  const error = new Error(`UX QE failed with ${hardFailures.length} hard failure(s)`);
+  error.receipt = receipt;
+  throw error;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runUxSuite().catch((e) => {
+    if (!e.receipt) console.error('  ux-suite crashed:', e.message);
+    process.exit(e.receipt ? 1 : 2);
+  });
+}

package/scripts/record-lesson.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * record-lesson.mjs — the durable "capture a lesson the RIGHT way" habit.
+ *
+ * WHY: AgentDB auto-capture records session transcripts (logging), not lessons
+ * (learning), and that telemetry drowns real lessons in recall. This records a
+ * lesson *structured* (task / tried / worked / critique / outcome) into a dedicated
+ * `lessons` signal namespace, refines it via native distill, and proves recall.
+ *
+ * NATIVE ONLY — shells to `ruflo memory` (store + distill + search). It does NOT
+ * reimplement any rUv capability; it enforces the structured-capture discipline
+ * that rUv's own `/remember` command recommends (agentdb-memory/commands/remember.md).
+ *
+ * Usage:
+ *   node scripts/record-lesson.mjs \
+ *     --task "..." --tried "..." --worked "..." --critique "..." --outcome success \
+ *     [--slug short-name] [--dir <projectDir>] [--namespace lessons]
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const arg = (name, def = '') => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+};
+
+const task = arg('task');
+if (!task) {
+  console.error('ERROR: --task is required (what were you trying to do?)');
+  process.exit(2);
+}
+const tried = arg('tried');
+const worked = arg('worked');
+const critique = arg('critique');
+const outcome = arg('outcome', 'success');
+const dir = path.resolve(arg('dir', process.cwd()));
+const ns = arg('namespace', 'lessons');
+const slug =
+  arg('slug') ||
+  task.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+
+const db = path.join(dir, '.swarm', 'memory.db');
+if (!fs.existsSync(db)) {
+  console.error(`ERROR: no AgentDB at ${db}\n  -> run \`ruflo memory init\` in that project first.`);
+  process.exit(2);
+}
+
+const key = `lesson-${slug}`;
+const value = [
+  `TASK: ${task}`,
+  tried ? `TRIED(failed): ${tried}` : null,
+  worked ? `WORKED: ${worked}` : null,
+  critique ? `CRITIQUE: ${critique}` : null,
+  `OUTCOME: ${outcome}`,
+].filter(Boolean).join(' ');
+
+const ruflo = (args) =>
+  execFileSync('ruflo', args, { cwd: dir, encoding: 'utf8', timeout: 60000 });
+
+console.log(`\nRecording lesson into ${path.basename(dir)}/.swarm/memory.db  (namespace: ${ns})`);
+console.log(`  key: ${key}`);
+
+// 1. STORE (native, signal namespace) — L1 content + L2 embedding
+let stored = false;
+try {
+  const out = ruflo(['memory', 'store', '-k', key, '-n', ns, '--value', value]);
+  stored = /OK|stored/i.test(out);
+} catch (e) {
+  console.error('  store FAILED:', String(e.stdout || e.message).split('\n')[0]);
+  process.exit(1);
+}
+console.log(`  1. store   -> ${stored ? 'OK' : '?'}`);
+
+// 2. REFINE (native) — L3 patterns + L4 episodes
+let batchEpisodes = '?';
+let distillOk = false;
+try {
+  const dist = ruflo(['memory', 'distill', 'run']);
+  const m = dist.match(/Episodes\s*\|\s*(\d+)/i);
+  if (m) batchEpisodes = m[1];
+  distillOk = true;
+} catch (e) {
+  /* distill is best-effort; the store already succeeded */
+}
+// DERIVED, not asserted (F15): say what actually happened — the old line printed "refined into
+// episodes+patterns" even when distill threw.
+console.log(distillOk
+  ? `  2. distill -> refined into episodes+patterns (batch: ${batchEpisodes})`
+  : '  2. distill -> FAILED (best-effort; the raw lesson is stored, refinement will catch up on a later distill)');
+
+// 3. VERIFY recall by the task text (paraphrase-ish), filtered to the namespace
+let recalled = false;
+try {
+  const search = ruflo(['memory', 'search', '-q', task, '-n', ns]);
+  recalled = search.includes(key.slice(0, 16));
+} catch (e) {
+  /* search failure shouldn't fail the record */
+}
+console.log(
+  `  3. recall  -> ${
+    recalled
+      ? `✅ "${task.slice(0, 44)}…" returns ${key}`
+      : '⚠️  not the top in-namespace hit (stored fine; ranking improves as signal grows)'
+  }`,
+);
+
+// DERIVED, not asserted (F15): the closing line reports exactly what was verified, never more. The
+// old line claimed "captured, refined, and recall-verified" even when distill failed and recall
+// didn't return the key — asserted prose over an honest exit code.
+const parts = ['captured', distillOk ? 'refined' : 'NOT refined (distill failed)', recalled ? 'recall-verified' : 'recall NOT verified'];
+console.log(`\nDone. Lesson is ${parts.join(', ')}.\n`);
+process.exit(stored ? 0 : 1);

package/scripts/refresh-model-catalog.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// scripts/refresh-model-catalog.mjs — pulls the LIVE OpenRouter model catalog and writes the committed
+// snapshot data/openrouter-catalog-snapshot.json (with a pulledAt stamp). verify-model-catalog.mjs then
+// enforces, offline in CI, that every model in data/model-catalog.json exists and is priced correctly
+// against this snapshot — and that the snapshot is fresh. Run nightly (the anti-rot mechanism) + on demand.
+// ADR-0016.
+//
+// It ALSO flags drift so a new flagship (e.g. a GPT-5.6-class release) surfaces instead of rotting:
+// any catalog model that has VANISHED from the live catalog. OpenRouter /models is a free metadata
+// endpoint (no generation, no spend).
+//
+// Usage: node scripts/refresh-model-catalog.mjs [--check]   (--check: fail if the pull would change the snapshot)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const SNAPSHOT = path.join(ROOT, 'data/openrouter-catalog-snapshot.json');
+const CATALOG = path.join(ROOT, 'data/model-catalog.json');
+
+/** Turn OpenRouter's /models `data` array into a compact {id: {in,out}} price map ($/Mtok). */
+export function priceMap(orData) {
+  const models = {};
+  for (const m of orData || []) {
+    const p = m.pricing || {};
+    models[m.id] = { in: +(+p.prompt * 1e6).toFixed(4), out: +(+p.completion * 1e6).toFixed(4) };
+  }
+  return models;
+}
+
+/** Which catalog models are no longer present in the live map (tolerating bare Claude ids)? */
+export function detectDrift(catalog, models) {
+  const missing = [];
+  for (const [pid, p] of Object.entries(catalog.providers || {})) {
+    if (p.aliasOf) continue;
+    for (const tier of ['frontier', 'mid', 'cheap']) {
+      const id = p[tier]?.model;
+      if (!id) continue;
+      const found = models[id] || (!id.includes('/') && models['anthropic/' + id]);
+      if (!found) missing.push(`${pid}.${tier} "${id}"`);
+    }
+  }
+  return missing;
+}
+
+export function shapeSnapshot(models, pulledAt) {
+  return { _meta: { source: 'OpenRouter /api/v1/models (live metadata)', pulledAt, modelCount: Object.keys(models).length }, models };
+}
+
+function loadKey() {
+  if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+  try {
+    const env = fs.readFileSync(path.join(ROOT, '.env'), 'utf8');
+    const m = env.match(/^OPENROUTER_API_KEY=(.+)$/m);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, '');
+  } catch { /* no .env */ }
+  return null;
+}
+
+async function pullLive() {
+  const key = loadKey();
+  const res = await fetch('https://openrouter.ai/api/v1/models', { headers: key ? { Authorization: `Bearer ${key}` } : {} });
+  if (!res.ok) throw new Error(`OpenRouter /models HTTP ${res.status}`);
+  return priceMap((await res.json()).data || []);
+}
+
+async function main() {
+  const check = process.argv.includes('--check');
+  const models = await pullLive();
+  if (Object.keys(models).length < 50) throw new Error(`live catalog returned only ${Object.keys(models).length} models — refusing to overwrite the snapshot with a suspiciously thin pull`);
+
+  const catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf8'));
+  const missing = detectDrift(catalog, models);
+  const snapshot = shapeSnapshot(models, new Date().toISOString());
+  const next = JSON.stringify(snapshot, null, 2) + '\n';
+
+  if (check) {
+    const cur = fs.existsSync(SNAPSHOT) ? JSON.parse(fs.readFileSync(SNAPSHOT, 'utf8')).models : null;
+    if (JSON.stringify(cur) !== JSON.stringify(models)) {
+      console.error('✗ snapshot is out of date vs the live OpenRouter catalog — run: node scripts/refresh-model-catalog.mjs');
+      process.exit(1);
+    }
+    console.log(`✓ snapshot matches live (${Object.keys(models).length} models).`);
+    return;
+  }
+
+  fs.writeFileSync(SNAPSHOT, next);
+  console.log(`✓ wrote ${SNAPSHOT.replace(ROOT + '/', '')} — ${Object.keys(models).length} live models, pulledAt ${snapshot._meta.pulledAt}`);
+  if (missing.length) {
+    console.log(`\n⚠ DRIFT: ${missing.length} catalog model(s) no longer in the live catalog — update data/model-catalog.json:`);
+    for (const m of missing) console.log('  - ' + m);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((e) => { console.error('refresh-model-catalog FAILED:', e.message); process.exit(1); });
+}

package/scripts/release-authority.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// One-publisher source gate for issue #77. Rebuild and maintenance jobs may prepare bytes, but
+// only scripts/release.mjs may contain operations that create a GitHub Release, publish npm, or
+// move an npm dist-tag. CI and the canonical release path both execute this check.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CANONICAL_PUBLISHER = 'scripts/release.mjs';
+const SOURCE_EXTENSIONS = new Set(['.mjs', '.js', '.cjs', '.sh']);
+
+function executableSource(source) {
+  const withoutBlocks = source.replace(/\/\*[\s\S]*?\*\//g, '');
+  return withoutBlocks
+    .split('\n')
+    .filter((line) => !line.trimStart().startsWith('#'))
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n');
+}
+
+const ACTIONS = [
+  {
+    action: 'github-release-create',
+    jsPatterns: [
+      /\[\s*['"]release['"]\s*,\s*['"]create['"]/,
+    ],
+    shellPatterns: [/^\s*gh\s+release\s+create\b/m],
+  },
+  {
+    action: 'npm-publish',
+    jsPatterns: [
+      /(?:execFileSync|spawnSync)\(\s*['"]npm['"]\s*,\s*\[\s*['"]publish['"]/,
+      /runOrDie\(\s*['"]npm publish['"]/,
+    ],
+    shellPatterns: [/^\s*npm\s+publish\b/m],
+  },
+  {
+    action: 'npm-dist-tag',
+    jsPatterns: [
+      /(?:execFileSync|spawnSync)\(\s*['"]npm['"]\s*,\s*\[\s*['"]dist-tag['"]\s*,\s*['"]add['"]/,
+      /runOrDie\(\s*['"]npm dist-tag[^'"]*['"]/,
+    ],
+    shellPatterns: [/^\s*npm\s+dist-tag\s+add\b/m],
+  },
+];
+
+export function detectPublisherActions(file, source) {
+  const relative = file.split(path.sep).join('/');
+  if (relative === CANONICAL_PUBLISHER) return [];
+  const executable = executableSource(source);
+  const kind = path.extname(relative) === '.sh' ? 'shellPatterns' : 'jsPatterns';
+  return ACTIONS
+    .filter((action) => action[kind].some((pattern) => pattern.test(executable)))
+    .map(({ action }) => ({ file: relative, action }));
+}
+
+function sourceFiles(root) {
+  const files = [];
+  const visit = (absolute) => {
+    if (!fs.existsSync(absolute)) return;
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      const child = path.join(absolute, entry.name);
+      if (entry.isDirectory()) visit(child);
+      else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) files.push(child);
+    }
+  };
+  visit(path.join(root, 'scripts'));
+  visit(path.join(root, 'deploy'));
+  return files;
+}
+
+export function findUnauthorizedPublishers(root = ROOT) {
+  return sourceFiles(root).flatMap((absolute) => {
+    const relative = path.relative(root, absolute).split(path.sep).join('/');
+    return detectPublisherActions(relative, fs.readFileSync(absolute, 'utf8'));
+  });
+}
+
+export function main(root = ROOT) {
+  const findings = findUnauthorizedPublishers(root);
+  if (findings.length === 0) {
+    console.log('[release-authority] PASS: scripts/release.mjs is the only publisher');
+    return 0;
+  }
+  console.error('[release-authority] FAIL: publication action found outside scripts/release.mjs');
+  for (const finding of findings) console.error(`  ${finding.file}: ${finding.action}`);
+  return 1;
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  process.exitCode = main();
+}

package/scripts/release-proof.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export * from '../plugin/skills/release-proof/scripts/release-proof.mjs';
+import { main } from '../plugin/skills/release-proof/scripts/release-proof.mjs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  process.exitCode = main(process.argv.slice(2));
+}