ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/release.mjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+// scripts/release.mjs — the DEFINITION OF DONE. The only path to the word "shipped."
+//
+// WHY (2026-07-17, Stuart): "You should be able to take the applied knowledge and build it into a set
+// of criteria that you always use, not a bunch of suggestions you choose to ignore." Every failure
+// this session was an ASSUMPTION that survived because the check was a suggestion, not a gate. This
+// script turns the checklist into a gate: it runs the criteria in order, STOPS on the first failure,
+// and only prints "SHIPPED" when every channel a user touches is proven current and working. There is
+// no "I think it's fine" — there is pass or fail.
+//
+// It is idempotent and safe to re-run. Each step verifies the REAL artifact (registry, live URL, the
+// actual command), never the repo state. Repo state != user experience (the whole lesson).
+//
+// Usage:
+//   node scripts/release.mjs --check          # run every gate READ-ONLY (no publish) — the pre-flight
+//   node scripts/release.mjs --publish        # sync version, npm publish, then run every gate
+//   node scripts/release.mjs                   # same as --check
+//
+// The gates, in order (fail fast):
+//   A. version single-source-of-truth agrees (sync-version --check)
+//   B. full test suite green (npm test — the 60/60)
+//   C. narrative + unit gates (vitest) incl. the tag/entity-aware "What's new" check
+//   C+. [--publish only] push to origin/main — ONLY now that A–C are green (a red tree can't reach GitHub)
+//   D. [--publish only] build + sign bundle, create/update the exact-SHA GitHub Release,
+//      then npm publish + force `latest` to the shipping version
+//   E. verify-channels — the LIVE walk of npm / self-update manifest / release bundle+sig / explainer / git
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const PUBLISH = process.argv.includes('--publish');
+const c = { g: (s) => `\x1b[32m${s}\x1b[0m`, r: (s) => `\x1b[31m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, dim: (s) => `\x1b[2m${s}\x1b[0m` };
+const V = () => JSON.parse(fs.readFileSync(path.join(ROOT, 'plugin/.claude-plugin/plugin.json'), 'utf8')).version;
+
+function step(n, label) { process.stdout.write(`\n${c.b('▸ ' + n)} ${label}\n`); }
+function runOrDie(label, cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { cwd: ROOT, stdio: 'inherit', ...opts });
+  if (r.error || r.status !== 0) {
+    console.error(`\n${c.r('✗ GATE FAILED: ' + label)} ${c.dim('(' + cmd + ' ' + args.join(' ') + ' → ' + (r.error ? r.error.message : 'exit ' + r.status) + ')')}`);
+    console.error(`${c.r('  NOT shipped. Fix this, then re-run. No assumptions past a red gate.')}\n`);
+    process.exit(1);
+  }
+}
+
+function remoteTagCommit(tag) {
+  const out = execFileSync('git', [
+    'ls-remote', 'origin', `refs/tags/${tag}`, `refs/tags/${tag}^{}`,
+  ], { cwd: ROOT, encoding: 'utf8' }).trim();
+  if (!out) return '';
+  const rows = out.split('\n').map((line) => line.trim().split(/\s+/));
+  return rows.find(([, ref]) => ref?.endsWith('^{}'))?.[0] || rows[0]?.[0] || '';
+}
+
+function recordReleaseTransaction(state, data) {
+  const file = path.join(ROOT, 'dist', 'release-transaction.json');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const next = {
+    state,
+    updatedAt: new Date().toISOString(),
+    ...data,
+  };
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function readReleaseTransaction() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'dist', 'release-transaction.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+console.log(`\n${c.b('RuvNet Brain — release / definition-of-done')} ${c.dim('· ' + (PUBLISH ? 'PUBLISH' : 'check-only') + ' · shipping ' + V())}\n`);
+
+// A verdict is only about the exact committed candidate. Check-only used to permit a dirty tree
+// while publish checked cleanliness much later, so preflight could certify bytes that would never
+// ship. Both modes now bind to the same committed tree before any expensive gate runs.
+const initialDirty = execFileSync('git', ['-C', ROOT, 'status', '--porcelain'], { encoding: 'utf8' }).trim();
+if (initialDirty) {
+  console.error(`\n${c.r('✗ GATE FAILED: working tree not clean')} ${c.dim('— preflight and publish both certify committed bytes only.')}`);
+  console.error(initialDirty.split('\n').slice(0, 10).map((l) => '    ' + l).join('\n'));
+  process.exit(1);
+}
+
+// A. version single source of truth
+step('A', 'version single-source-of-truth agrees across every surface');
+runOrDie('version sync', process.execPath, ['scripts/sync-version.mjs', '--check']);
+
+// WIRED-CHECK — refuses to ship a module with zero callers.
+//
+// Added 2026-07-22 after this project shipped built-tested-unwired code SEVEN times in one session
+// (capability-registry, capability-audit, lesson-gate's five triggers, anticipate.sh,
+// advocacy-outcomes, lesson-promote's demotion, continuation-gate's global path). Every one had
+// passing tests, because a test imports the module directly — the one caller that proves nothing
+// about whether the product uses it. Every one was found by a human running grep, hours later.
+//
+// Seven repetitions of one mistake is not a discipline problem; discipline is what failed. So it
+// becomes a gate, on the ship path, where this repo's gates run 8/8 against prose's 0/6.
+runOrDie('wired (no orphan modules)', process.execPath, ['scripts/wired-check.mjs', '--check']);
+
+// THE NORTH-STAR VECTOR — a release may not average one broken/unknown invariant into a pass.
+// This is the real ship path, not an npm alias or a test import: every check-only preflight and
+// every publish attempt executes the eight D1-D8 detectors on the candidate SHA.
+runOrDie('release vector (all critical invariants PASS)', process.execPath, ['scripts/release-vector.mjs']);
+
+// The Top-100 corpus spans naive through expert prompts and grades semantic clauses, citations,
+// abstention, and latency. A manual-only benchmark is a report; a release-path benchmark is a
+// guarantee. The benchmark itself fails closed unless all 100 canonical questions run.
+runOrDie('Top-100 source-grounded recall contract', process.execPath, ['scripts/top100-benchmark.mjs', '--no-write']);
+
+// A2. Stable Spine restart classifier (ADR-023, red-team finding 18): diff the boot-frozen SHELL
+// (hooks.json, hook-shim, MCP server, .mcp.json, skills/, commands/) against the previous release
+// tag and SAY OUT LOUD whether this release needs a restart. The classification is computed, never
+// remembered — the same shellDiff logic runs client-side in update-apply.mjs at every flip, so the
+// user-facing nag stays honest even if this print is ignored. Informational at ship time; the
+// releasing human sees exactly which shell files changed.
+step('A2', 'Stable Spine — does this release change the boot-frozen shell? (requiresRestart classifier)');
+{
+  const { execFileSync } = await import('node:child_process');
+  const SHELL = ['plugin/hooks/hooks.json', 'plugin/scripts/hook-shim.mjs', 'plugin/mcp/server.mjs', 'plugin/.mcp.json', 'plugin/skills', 'plugin/commands'];
+  let prevTag = '';
+  try { prevTag = execFileSync('git', ['describe', '--tags', '--abbrev=0'], { encoding: 'utf8' }).trim(); } catch { /* no tags yet */ }
+  if (!prevTag) {
+    console.log(c.dim('  no previous release tag — classifier has no baseline (first spine release: requiresRestart=true by definition)'));
+  } else {
+    let changed = [];
+    try {
+      const out = execFileSync('git', ['diff', '--name-only', `${prevTag}..HEAD`, '--', ...SHELL], { encoding: 'utf8' }).trim();
+      changed = out ? out.split('\n') : [];
+    } catch { /* diff failure = unknown; say so, never guess green */ changed = ['(diff failed — treat as changed)']; }
+    if (changed.length) {
+      console.log(`  ${c.y('requiresRestart: TRUE')} — shell changed vs ${prevTag}:`);
+      for (const f of changed) console.log(`    · ${f}`);
+      console.log(c.dim('  users get ONE honest restart notice (session-start reads active.json.shellChanged); everything else is live.'));
+    } else {
+      console.log(`  ${c.g('requiresRestart: false')} — no shell change vs ${prevTag}; this release goes fully live with zero restarts.`);
+    }
+  }
+}
+
+// B. the full brain test suite (the 60/60)
+step('B', 'full test suite (npm test)');
+runOrDie('npm test', 'npm', ['test']);
+
+// C. unit gates — narrative-version (tag/entity aware), claims, etc.
+step('C', 'unit gates (vitest) — narrative version, claims, guards');
+runOrDie('vitest unit', 'npx', ['vitest', 'run', 'tests/unit']);
+
+// C+. PUSH — only now that A–C are green (publish only). Pushing AFTER the local gates is the fix
+// for the drift that bit on 2026-07-18: a commit was pushed FIRST, then release.mjs's gate B caught a
+// failing plugin-battery test, leaving GitHub at 3.4.10-dev while npm sat at 3.4.9-dev — the exact
+// "pushed but didn't finish" split. The pre-push git hook only checks version/manifest (fast, always),
+// so tests must gate the push HERE. A red tree can no longer reach origin ahead of npm.
+if (PUBLISH) {
+  // C++. REMOTE CI IS A SHIP GATE (ADR-053 §5). Between 2026-07-21 and 07-26 the `ci` workflow was
+  // red for ~70 consecutive runs — six releases shipped right past it, because nothing on the ship
+  // path ever ASKED the remote verdict. Local gates prove this machine; only CI proves ubuntu and
+  // windows. So the latest COMPLETED run on origin/main must be green before we add commits on top
+  // and publish. (The current commit's own run starts after the push — this gate is "never build on
+  // a known-broken main", not "wait for my own run".) Escape hatch for a genuine hotfix:
+  // --ci-override "<reason>" — printed into the release log, never silent.
+  step('C++', 'remote CI on origin/main is green (the ubuntu+windows verdict this machine cannot produce)');
+  {
+    const { fetchLatestCiVerdict, assessCiGate } = await import('./ci-verdict.mjs');
+    const OVERRIDE_IX = process.argv.indexOf('--ci-override');
+    const overrideReason = OVERRIDE_IX >= 0 ? (process.argv[OVERRIDE_IX + 1] || '(no reason given)') : null;
+    const { verdict, sha } = await fetchLatestCiVerdict();
+    const gate = assessCiGate(verdict, overrideReason);
+    if (gate === 'ship') {
+      console.log(c.dim(`  latest completed ci run on origin/main: success (${sha})`));
+    } else if (gate === 'override') {
+      console.log(`  ${c.y('! CI gate OVERRIDDEN')} — verdict was ${verdict ?? 'unknown'} (${sha || 'no run found'}); reason: ${overrideReason}`);
+    } else {
+      console.error(`\n${c.r('✗ GATE FAILED: remote CI on origin/main is ' + (verdict ?? 'unknown'))} ${c.dim('(' + (sha || 'no completed run found') + ')')}`);
+      console.error(`${c.r('  A red or unknown main does not get shipped on top of. Fix CI first (gh run list --workflow ci.yml),')}`);
+      console.error(`${c.r('  or for a genuine hotfix: --ci-override "<reason>" (the reason is printed into the release log).')}\n`);
+      process.exit(1);
+    }
+  }
+
+  step('C+', 'push to origin/main — safe now that A–C passed');
+  let ahead = '0';
+  try { ahead = execFileSync('git', ['-C', ROOT, 'rev-list', '--count', 'origin/main..HEAD'], { encoding: 'utf8' }).trim(); } catch { /* origin/main ref missing — push will resolve */ ahead = '?'; }
+  if (ahead === '0') console.log(c.dim('  nothing to push — HEAD already on origin/main'));
+  else runOrDie('git push', 'git', ['-C', ROOT, 'push', 'origin', 'main']);
+}
+
+// D. Publish BOTH delivery channels. This used to advance npm without creating the GitHub Release
+// that verify-channels immediately required, making the sanctioned manual ship path impossible to
+// complete. Build and sign first, then create/update the exact-SHA Release before npm advances.
+// Re-runs are idempotent: a matching Release gets its three assets replaced; a tag bound to any
+// other commit is a hard provenance failure.
+if (PUBLISH) {
+  const v = V();
+  const tag = `v${v}`;
+  const zip = path.join(ROOT, 'dist', 'ruvnet-brain.zip');
+  const assets = [zip, `${zip}.sig`, `${zip}.sha256`];
+  const head = execFileSync('git', ['-C', ROOT, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  const priorTxn = readReleaseTransaction();
+  const unfinished = priorTxn && priorTxn.state !== 'channels-converged';
+  const samePendingCandidate = unfinished && priorTxn.tag === tag && priorTxn.head === head;
+
+  step('D', 'build + sign bundle and publish matching GitHub/npm channels');
+  if (unfinished && !samePendingCandidate) {
+    console.error(`\n${c.r('✗ GATE FAILED: unfinished release transaction requires reconciliation')}`);
+    console.error(c.dim(`  ${priorTxn.state}: ${priorTxn.tag || '?'} @ ${priorTxn.head || '?'}; refusing to overwrite it with ${tag} @ ${head}`));
+    process.exit(1);
+  }
+  if (samePendingCandidate) {
+    if (!assets.every((asset) => fs.existsSync(asset))) {
+      console.error(`\n${c.r('✗ GATE FAILED: pending release assets are missing; reconcile before retrying')}`);
+      process.exit(1);
+    }
+    const declared = fs.readFileSync(`${zip}.sha256`, 'utf8').trim().split(/\s+/)[0];
+    const actual = crypto.createHash('sha256').update(fs.readFileSync(zip)).digest('hex');
+    const verify = spawnSync(process.execPath, ['scripts/verify-bundle.mjs', zip, `${zip}.sig`], {
+      cwd: ROOT, encoding: 'utf8',
+    });
+    if (declared !== priorTxn.bundleSha256 || actual !== declared || verify.status !== 0) {
+      console.error(`\n${c.r('✗ GATE FAILED: pending release assets do not match their signed transaction')}`);
+      process.exit(1);
+    }
+    console.log(c.dim('  resume existing signed release assets for the pending candidate'));
+  } else {
+    runOrDie('build release bundle', process.execPath, ['scripts/build-bundle.mjs', '--version', tag]);
+    runOrDie('sign release bundle', process.execPath, ['scripts/sign-bundle.mjs', '--bundle', zip]);
+  }
+  for (const asset of assets) {
+    if (!fs.existsSync(asset)) {
+      console.error(`\n${c.r('✗ GATE FAILED: signed release asset missing')} ${c.dim(asset)}`);
+      process.exit(1);
+    }
+  }
+  const bundleSha256 = fs.readFileSync(`${zip}.sha256`, 'utf8').trim().split(/\s+/)[0];
+  if (!/^[a-f0-9]{64}$/i.test(bundleSha256)) {
+    console.error(`\n${c.r('✗ GATE FAILED: release digest is not a SHA-256 value')}`);
+    process.exit(1);
+  }
+
+  let remoteTagSha = '';
+  try {
+    remoteTagSha = remoteTagCommit(tag);
+  } catch (e) {
+    console.error(`\n${c.r('✗ GATE FAILED: could not verify remote release tag')} ${c.dim(String(e.message || e).split('\n')[0])}`);
+    process.exit(1);
+  }
+  if (remoteTagSha && remoteTagSha !== head) {
+    console.error(`\n${c.r('✗ GATE FAILED: release tag already identifies different bytes')}`);
+    console.error(c.dim(`  ${tag} -> ${remoteTagSha}; candidate HEAD -> ${head}`));
+    process.exit(1);
+  }
+
+  // Cross-provider publication cannot be truly atomic. Persist the exact convergence state before
+  // the first remote mutation so a failed npm publish is recoverable and the next run can converge
+  // the SAME tag/HEAD instead of guessing which channel moved.
+  if (priorTxn && !['channels-converged'].includes(priorTxn.state)) {
+    const sameCandidate = priorTxn.tag === tag
+      && priorTxn.head === head
+      && priorTxn.bundleSha256 === bundleSha256;
+    if (!sameCandidate) {
+      console.error(`\n${c.r('✗ GATE FAILED: unfinished release transaction requires reconciliation')}`);
+      if (priorTxn.tag === tag && priorTxn.head === head && priorTxn.bundleSha256 !== bundleSha256) {
+        console.error(c.dim('  release transaction artifact digest changed for the same tag and HEAD'));
+      }
+      console.error(c.dim(`  ${priorTxn.state}: ${priorTxn.tag || '?'} @ ${priorTxn.head || '?'}; refusing to overwrite it with ${tag} @ ${head}`));
+      process.exit(1);
+    }
+  }
+  recordReleaseTransaction('prepared', { version: v, tag, head, bundleSha256 });
+
+  let releaseExists = false;
+  try {
+    execFileSync('gh', ['release', 'view', tag, '--repo', 'stuinfla/ruvnet-brain'], {
+      cwd: ROOT, stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    releaseExists = true;
+  } catch { /* absent is the expected first-publish state */ }
+
+  if (releaseExists) {
+    if (!remoteTagSha) {
+      console.error(`\n${c.r('✗ GATE FAILED: GitHub Release exists without a verifiable matching tag')} ${c.dim(tag)}`);
+      process.exit(1);
+    }
+    runOrDie('replace signed GitHub Release assets', 'gh', [
+      'release', 'upload', tag, ...assets, '--clobber', '--repo', 'stuinfla/ruvnet-brain',
+    ]);
+  } else {
+    runOrDie('create signed GitHub Release', 'gh', [
+      'release', 'create', tag, ...assets,
+      '--repo', 'stuinfla/ruvnet-brain',
+      '--target', head,
+      '--title', `${tag} — verified release`,
+      '--generate-notes',
+      '--latest',
+    ]);
+  }
+
+  // Confirm the tag GitHub created/retained points to the candidate before touching npm.
+  let publishedTagSha = '';
+  try {
+    publishedTagSha = remoteTagCommit(tag);
+  } catch { /* handled by the mismatch below */ }
+  if (publishedTagSha !== head) {
+    console.error(`\n${c.r('✗ GATE FAILED: published GitHub Release tag is not candidate HEAD')}`);
+    console.error(c.dim(`  ${tag} -> ${publishedTagSha || '(missing)'}; candidate HEAD -> ${head}`));
+    process.exit(1);
+  }
+  recordReleaseTransaction('github-published-npm-pending', { version: v, tag, head, bundleSha256 });
+
+  let already = '';
+  try { already = execFileSync('npm', ['view', `ruvnet-brain@${v}`, 'version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { /* not published yet */ }
+  if (already === v) console.log(c.dim(`  ${v} already on npm — skipping publish, just re-asserting the tag`));
+  // npm requires an explicit tag for prerelease versions. This project intentionally serves its
+  // `-dev` release from `latest`, so make that policy explicit on the publish command itself.
+  else runOrDie('npm publish', 'npm', ['publish', '--tag', 'latest']);
+  // npm does NOT auto-move `latest` to a prerelease (x.y.z-dev) — force it, or `@latest` stays stale.
+  runOrDie('npm dist-tag latest', 'npm', ['dist-tag', 'add', `ruvnet-brain@${v}`, 'latest']);
+  recordReleaseTransaction('publish-complete-verification-pending', { version: v, tag, head, bundleSha256 });
+} else {
+  step('D', 'GitHub Release + npm publish — SKIPPED (check-only; pass --publish to publish)');
+}
+
+// D+. THE DEPLOY-SURFACE SWEEP (owner standing order, 2026-07-27): "ALWAYS check GitHub CLI and
+// Vercel CLI for gotchas with anything you're pushing. This needs to be part of the protocol you use
+// whenever you deploy. I don't want to have to tell you this again."
+//
+// Gate C++ already asks whether CI passed. That is one surface. This asks the two CLIs what the
+// PLATFORMS think — failing workflows other than our own ci, security advisories, and whether the
+// production deployment that serves the explainer is actually Ready. Each is a question a human
+// would otherwise have to remember to ask, which is the definition of a check that eventually
+// doesn't happen.
+//
+// ADVISORY BY DESIGN, LOUD BY CONTRACT: this prints findings and does not exit non-zero, because a
+// GitHub-side hiccup must not wedge a correct release — EXCEPT where it overlaps a hard gate that
+// already exists (C++ for ci, E for the live explainer). Anything it finds is printed in full so it
+// cannot be a diagnostic nobody reads.
+step('D+', 'deploy-surface sweep — what GitHub and Vercel think about what we are pushing');
+{
+  const sh = (cmd, args) => { try { return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore','pipe','ignore'], timeout: 45000 }); } catch { return null; } };
+
+  // 1. Failing workflow runs that are NOT our ci (ci is gate C++'s job). issue-watch exits 1 BY
+  //    DESIGN on an SLA breach, so it is reported as an SLA signal, never as a broken pipeline —
+  //    conflating the two is how a permanently-red workflow trains everyone to ignore red.
+  const runs = sh('gh', ['run','list','--repo','stuinfla/ruvnet-brain','--limit','15','--json','name,conclusion,headBranch']);
+  if (runs) {
+    let bad = [];
+    try { bad = JSON.parse(runs).filter((r) => r.conclusion && r.conclusion !== 'success' && r.name !== 'ci'); } catch { /* unparseable — reported below */ }
+    const sla = bad.filter((r) => r.name === 'issue-watch');
+    const real = bad.filter((r) => r.name !== 'issue-watch');
+    if (sla.length) console.log(`  ${c.y('! issue-watch red x' + sla.length)} ${c.dim('— by design: an open issue is past its 4h SLA. Answer the issue, do not fix the workflow.')}`);
+    if (real.length) console.log(`  ${c.y('! non-ci workflows failing:')} ${real.map((r) => r.name).join(', ')}`);
+    if (!sla.length && !real.length) console.log(c.dim('  no failing workflows outside ci'));
+  } else console.log(c.dim('  gh unavailable — workflow sweep SKIPPED (not a pass)'));
+
+  // 2. Security advisories against what we ship.
+  const dep = sh('gh', ['api','repos/stuinfla/ruvnet-brain/dependabot/alerts','--jq','[.[]|select(.state=="open")]|length']);
+  if (dep !== null) {
+    const n = parseInt(dep.trim(), 10);
+    console.log(n > 0 ? `  ${c.r('! ' + n + ' open dependabot alert(s)')}` : c.dim('  0 open dependabot alerts'));
+  } else console.log(c.dim('  dependabot query unavailable — SKIPPED (not a pass)'));
+
+  // 3. Vercel: the explainer is a shipped surface; a Ready production deployment is the precondition
+  //    for gate E's live check meaning anything.
+  const vc = sh('vercel', ['ls','--yes']);
+  if (vc) {
+    const prod = vc.split('\n').find((l) => l.includes('Production'));
+    const ready = prod && /●\s*Ready/.test(prod);
+    console.log(ready ? c.dim('  vercel: latest production deployment Ready') : `  ${c.y('! vercel: latest production deployment is NOT Ready')} ${c.dim((prod||'').trim().slice(0,90))}`);
+  } else console.log(c.dim('  vercel CLI unavailable/not logged in — SKIPPED (not a pass)'));
+}
+
+// E. the live channel walk — THE gate that would have caught the stale-2.9.1 + 404
+step('E', 'verify-channels — the live walk of every user path');
+runOrDie('verify-channels', process.execPath, ['scripts/verify-channels.mjs']);
+if (PUBLISH) {
+  const txn = readReleaseTransaction();
+  recordReleaseTransaction('channels-converged', {
+    version: V(),
+    tag: `v${V()}`,
+    head: execFileSync('git', ['-C', ROOT, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(),
+    bundleSha256: txn?.bundleSha256 ?? null,
+  });
+}
+
+if (PUBLISH) {
+  console.log(`\n${c.g(c.b('✓✓✓ SHIPPED'))} — every gate passed and every live channel is current. ${c.dim('A user on any path (npm, npx, explainer, --update) gets the working, current build.')}\n`);
+} else {
+  console.log(`\n${c.g(c.b('✓✓✓ PREFLIGHT PASS — NOT PUBLISHED'))} — the committed candidate passed every check-only gate.\n`);
+}

package/scripts/remedy-registry.mjs

@@ -0,0 +1,247 @@
+// remedy-registry.mjs — ONE object per recommendation id, owning detector ⇄ executor ⇄ inverse.
+//
+// WHY THIS EXISTS. Before this file, a recommendation's id, the code that ran it, and the code that
+// reversed it lived in three different places that nothing forced to agree. All three drifted, and
+// every drift was invisible until someone clicked the button:
+//
+//   1. `learning:enable-fleet` was constructed, validated, and offered — with NO executor at all.
+//      It fell through apply()'s if/else to `Unknown recommendation id`. The single most important
+//      recommendation in the product (ADR-027's North Star case) was a dead button.
+//   2. `repair:memory-index` journalled `kind:'restore-memory-backup'`, and undo() had no branch for
+//      it. It hit the default arm and reported "nothing to undo (the change reverses itself
+//      automatically)" — while the recommendation had promised "restore the backup taken immediately
+//      before the repair." The undo did not exist. The promise was a lie.
+//   3. `repair:memory-index` also satisfies `startsWith('repair:')`, so ONE reordering of an if/else
+//      chain silently routed a database repair into a global npm sync. That was caught by review,
+//      but only by review — nothing structural prevented it.
+//
+// The common shape: a chain of `if (id.startsWith(...))` cannot be audited, because the set of ids
+// it handles is not a value anything can inspect. So it becomes a value here. Each Remedy owns its
+// id, the executor as DATA (not a spawn), and a DECLARED inverse. `assertRegistryClosure()` then
+// proves, in a test, that every id the builders can construct resolves to exactly one remedy with a
+// real undo handler behind it — so a dead button fails CI instead of failing a user.
+//
+// PURITY: no I/O, no spawn, no fs — same discipline as console-engine.mjs (DDD context 4). A remedy
+// RETURNS a description of what to run; onboarding-console.mjs is the only thing that runs it. That
+// is what lets the closure test check every path without touching the machine.
+
+// ── Undo kinds ───────────────────────────────────────────────────────────────────────────────────
+// The set of inverses the console can actually perform. A remedy may not name a kind outside this
+// set, and every kind here MUST have a live branch in onboarding-console.undo(). Both directions are
+// enforced by test, because a missing branch does not throw — it silently returns "nothing to undo",
+// which is the most dangerous possible answer: it reads like success.
+//
+// NONE is a real, declared value, not an absence. "This genuinely has no inverse" and "nobody wrote
+// one" must never look the same, which is exactly the bug that made #2 above invisible.
+export const UNDO_KINDS = Object.freeze({
+  NONE: 'none',
+  REINSTALL_VERSION: 'reinstall-version',
+  RESTORE_BACKUP: 'restore-backup',
+  RESTORE_MEMORY_BACKUP: 'restore-memory-backup',
+  RESTORE_STORE_BACKUPS: 'restore-store-backups',
+  AUTO_REBUILD: 'auto-rebuild',
+  // distill-project.mjs's OWN `--restore` (see its header: a tested inverse, not a re-implementation
+  // of one). Distinct from RESTORE_MEMORY_BACKUP/RESTORE_STORE_BACKUPS because those restore backups
+  // *this server* located and named; this one hands the restore entirely to the same script that took
+  // the snapshot, which already knows where its own backups live.
+  RESTORE_PROJECT_DISTILL: 'restore-project-distill',
+});
+const K = UNDO_KINDS;
+
+// Ids that are exact, reserved words. A parameterized matcher (`repair:<pkg>`) must never capture
+// one of these — see the ambiguity throw in resolveRemedy().
+const RESERVED = new Set(['repair:memory-index', 'purge:shadows']);
+
+// ── The registry ─────────────────────────────────────────────────────────────────────────────────
+// match(id)   → params object if this remedy owns the id, else null.
+// plan(p)     → { script, args } — the executor, as data.
+// inverse(p)  → { kind, ...params } — journalled BEFORE the change is made.
+export const REMEDIES = [
+  {
+    key: 'memory-index',
+    autoEligible: true,
+    summary: 'REINDEX a corrupt AgentDB store',
+    match: (id) => (id === 'repair:memory-index' ? {} : null),
+    plan: () => ({ script: 'scripts/health-repair.mjs', args: ['--repair-memory'] }),
+    // health-repair.mjs takes an sqlite `.backup` of the store immediately before REINDEX (never a
+    // cp — that silently truncates a live WAL database, a standing lesson proven by experiment).
+    // The inverse is restoring it. This is the branch whose absence made the promise a lie.
+    inverse: () => ({ kind: K.RESTORE_MEMORY_BACKUP }),
+  },
+  {
+    key: 'learning-flush',
+    summary: 'drain the capture queue into the learner',
+    match: (id) => (id === 'learning:flush' ? {} : null),
+    plan: () => ({ script: 'scripts/health-repair.mjs', args: ['--flush-learning'] }),
+    // Genuinely additive: it moves already-captured local events into the learner. Declared NONE on
+    // purpose, and the human string says what a user would actually do instead.
+    inverse: () => ({ kind: K.NONE, human: 'nothing to reverse — this only adds observations the learner already had queued; learned state can be reset separately' }),
+  },
+  {
+    key: 'learning-train',
+    summary: 'run one training cycle',
+    match: (id) => (id === 'learning:train' ? {} : null),
+    plan: () => ({ script: 'scripts/health-repair.mjs', args: ['--train-learning'] }),
+    inverse: () => ({ kind: K.NONE, human: 'nothing to reverse here — learned state is reset with `ruflo hooks intelligence --reset`, which is a separate, deliberate action' }),
+  },
+  {
+    // THE ONE THAT HAD NO EXECUTOR. See ADR-027's North Star case: stores full of memories that
+    // teach nothing. The remedy is not ours to invent — memory-doctor.mjs has printed the exact fix
+    // since the day it was written ("embedded but never distilled — run: ruflo memory distill run"),
+    // and the console simply never said it out loud. This wires that sentence to a button.
+    key: 'distill-fleet',
+    summary: 'distill embedded-but-never-distilled stores into reusable patterns',
+    match: (id) => (id === 'learning:distill-fleet' ? {} : null),
+    // needsReceipt: this remedy touches a SET of stores discovered at run time, so the inverse
+    // cannot be described up front. The executor writes down exactly which stores it snapshotted
+    // and where; the inverse reads that receipt. Without it, "restore the backups" would be a hope
+    // rather than an instruction — and a hope is what made the memory-index undo a lie.
+    plan: () => ({ script: 'scripts/health-repair.mjs', args: ['--distill-fleet'], needsReceipt: true }),
+    // Distillation WRITES (reasoning_patterns, episodes, causal_edges), so it needs a real inverse.
+    // health-repair snapshots each store with `ruflo memory backup` (rUv's own WAL-safe, rotated
+    // snapshotter) before distilling it; the inverse restores those snapshots.
+    inverse: () => ({ kind: K.RESTORE_STORE_BACKUPS }),
+  },
+  {
+    // THE CAPABILITY BRIDGE'S ONLY CURRENT MEMBER. buildCapabilityRecommendations() in
+    // console-engine.mjs offers `enable:memory-distillation` only while the capability is OFF; this
+    // is the executor behind it. See distill-project.mjs's header for why THIS script and not bare
+    // `ruflo memory distill run`: the wrapper snapshots first, fails closed on a receipt-write
+    // failure, and its `--restore` is the tested inverse (proven 644→648→644→648, 2026-07-24).
+    key: 'enable-memory-distillation',
+    autoEligible: true,
+    summary: "mine this project's stored memories into reusable patterns (snapshots first; reversible)",
+    match: (id) => (id === 'enable:memory-distillation' ? {} : null),
+    // This console instance is always scoped to ONE project — the directory it was started in — the
+    // same assumption the memory-index/learning-flush/learning-train remedies above already make.
+    // `usesServerProject` asks onboarding-console.mjs (impure, process-aware) to supply that directory
+    // at call time; this file stays pure and never reads process.cwd() itself (see header).
+    plan: () => ({ script: 'scripts/distill-project.mjs', args: [], usesServerProject: true }),
+    // `--restore` with no path argument uses distill-project.mjs's OWN newestSnapshot() lookup inside
+    // this project's `.swarm/backups` — the exact mechanism its header proves end to end. Re-deriving
+    // which snapshot to restore here, instead of asking the tool that took it, is the kind of
+    // duplicate implementation this project has already been burned by once (ADR-047's rejected
+    // "offered command and promised undo live on different execution paths" bug).
+    inverse: () => ({ kind: K.RESTORE_PROJECT_DISTILL }),
+  },
+  {
+    key: 'stack-sync',
+    summary: 'install/repair a global package to its target version',
+    match: (id) => {
+      if (RESERVED.has(id)) return null; // `repair:memory-index` is NOT a package repair
+      const m = /^(?:sync|repair):(.+)$/.exec(id);
+      return m ? { pkg: m[1] } : null;
+    },
+    plan: () => ({ script: 'scripts/stack-sync.mjs', args: ['--sync'] }),
+    // The inverse of a version bump is the version that was on disk a moment ago — which only the
+    // caller can read, so it is filled in at journal time. Declaring it here is what makes the
+    // closure test able to check that undo() can honour it.
+    inverse: ({ pkg }) => ({ kind: K.REINSTALL_VERSION, pkg }),
+  },
+  {
+    key: 'purge-shadows',
+    summary: 'delete stale duplicate copies from the npx cache',
+    match: (id) => (id === 'purge:shadows' ? {} : null),
+    plan: () => ({ script: 'scripts/stack-sync.mjs', args: ['--sync'] }),
+    inverse: () => ({ kind: K.AUTO_REBUILD, human: 'the temporary cache re-fills itself on next use; no manual step needed' }),
+  },
+  {
+    key: 'reconcile-project',
+    autoEligible: true,
+    summary: 'rewire a project from npx to the global binary',
+    match: (id) => {
+      const m = /^reconcile:(.+)$/.exec(id);
+      return m ? { project: m[1] } : null;
+    },
+    plan: ({ project }) => ({ script: 'scripts/reconcile-project.mjs', args: ['--apply', '--project', project], resolveProject: true }),
+    inverse: ({ project }) => ({ kind: K.RESTORE_BACKUP, project }),
+  },
+];
+
+/**
+ * Resolve an id to EXACTLY ONE remedy.
+ *
+ * Ambiguity throws rather than picking a winner. Silently preferring the first match is precisely
+ * how `repair:memory-index` once routed into a global npm sync while telling the user their database
+ * had been repaired — a wrong action reported as the right one. A throw is a loud developer error;
+ * a silent misroute is a user's data.
+ */
+export function resolveRemedy(id) {
+  const hits = [];
+  for (const r of REMEDIES) {
+    const params = r.match(id);
+    if (params) hits.push({ remedy: r, params });
+  }
+  if (hits.length > 1) {
+    throw new Error(`Remedy id "${id}" is ambiguous — claimed by: ${hits.map((h) => h.remedy.key).join(', ')}. Exactly one remedy must own an id.`);
+  }
+  return hits[0] ?? null;
+}
+
+/** The full plan for an id: what to run, and what reverses it. Null when nothing owns the id. */
+export function planFor(id) {
+  const hit = resolveRemedy(id);
+  if (!hit) return null;
+  const { remedy, params } = hit;
+  return {
+    key: remedy.key,
+    summary: remedy.summary,
+    autoEligible: remedy.autoEligible === true,
+    exec: remedy.plan(params),
+    undo: remedy.inverse(params),
+    params,
+  };
+}
+
+/**
+ * THE CLOSURE PROOF. Every id that can be OFFERED must be runnable and reversible.
+ *
+ * Takes the ids the recommendation builders actually constructed (never a hand-typed list — a
+ * hand-typed list drifts from the builders, which is the whole failure mode) plus the undo kinds
+ * onboarding-console.undo() implements, and returns every gap it finds.
+ *
+ * @param {string[]} offeredIds  ids from buildHealth/Stack/WiringRecommendations
+ * @param {string[]} handledUndoKinds  kinds undo() has a real branch for
+ * @returns {{orphanIds:string[], ambiguousIds:string[], unhandledUndoKinds:string[], deadKinds:string[]}}
+ */
+export function assertRegistryClosure(offeredIds = [], handledUndoKinds = []) {
+  const orphanIds = [];
+  const ambiguousIds = [];
+  const unhandledUndoKinds = [];
+  const handled = new Set(handledUndoKinds);
+  const usedKinds = new Set();
+
+  for (const id of offeredIds) {
+    let plan = null;
+    try { plan = planFor(id); } catch { ambiguousIds.push(id); continue; }
+    if (!plan) { orphanIds.push(id); continue; } // offered with no executor — the dead-button bug
+    usedKinds.add(plan.undo.kind);
+    // NONE is self-handling by definition, but it must still be DECLARED (see UNDO_KINDS).
+    if (plan.undo.kind !== K.NONE && !handled.has(plan.undo.kind)) unhandledUndoKinds.push(`${id} → ${plan.undo.kind}`);
+  }
+
+  // The other direction: a kind the registry declares that undo() cannot perform is a broken promise
+  // waiting to happen, even if no builder currently emits that id.
+  const declared = new Set();
+  for (const r of REMEDIES) {
+    try { declared.add(r.inverse(r.match(sampleIdFor(r)) || {}).kind); } catch { /* sampling is best-effort */ }
+  }
+  const deadKinds = [...declared].filter((k) => k !== K.NONE && !handled.has(k));
+
+  return { orphanIds, ambiguousIds, unhandledUndoKinds, deadKinds };
+}
+
+/** A representative id for each remedy, so closure can sample parameterized matchers too. */
+export function sampleIdFor(remedy) {
+  switch (remedy.key) {
+    case 'memory-index': return 'repair:memory-index';
+    case 'learning-flush': return 'learning:flush';
+    case 'learning-train': return 'learning:train';
+    case 'distill-fleet': return 'learning:distill-fleet';
+    case 'enable-memory-distillation': return 'enable:memory-distillation';
+    case 'stack-sync': return 'sync:ruflo';
+    case 'purge-shadows': return 'purge:shadows';
+    case 'reconcile-project': return 'reconcile:example';
+    default: return `__unknown:${remedy.key}`;
+  }
+}