ruvnet-brain 4.0.1 → 4.0.2

package/scripts/gates.mjs

@@ -0,0 +1,146 @@
+// gates.mjs — what stands between the model and your machine, and what it has caught.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY (2026-07-17). Stuart, looking at the console's wiring card: "I have no idea what message it's
+// supposed to tell me… it seems to be facts without purpose." The card counted launch sites. Nobody
+// wants a census. The question worth answering is the one the harness exists for: WHAT STOPS CLAUDE
+// FROM BEING WRONG, AND HAS IT EVER ACTUALLY STOPPED IT?
+//
+// Two things had to be true before that card could be honest, and neither was:
+//
+//   1. The console never read the gates. wiringSurvey() walks ~/Code project settings only, so the
+//      12 machine-wide hooks in ~/.claude/settings.json and the 9 in the plugin's own hooks.json —
+//      including the design wall that blocks commits — were invisible to the page bragging about them.
+//
+//   2. The gates never recorded a block. Only successes were logged, so "the harness caught Claude"
+//      had no receipt. gate-receipt.sh now writes one at the moment of refusal.
+//
+// THE HONEST DISTINCTION this module exists to draw: a hook wired with `|| true` CANNOT block —
+// it injects context and the tool call proceeds regardless. Only a gate that can exit non-zero
+// stops anything. Counting all hooks as "protection" would be the same inflation as counting
+// cloned upstream repos as your own wiring. Advisory and blocking are different claims.
+//
+// Reads only. Never asserts a count it cannot source from a file on this machine.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+const BLOCKS = path.join(HOME, '.cache/ruvnet-brain/gate-blocks.jsonl');
+
+function readJSON(f) { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } }
+
+// Two independent things must BOTH be true for a hook to stop anything, and conflating them is how
+// a census gets sold as protection:
+//   1. The EVENT must be one that runs before the thing it would stop. PreToolUse gates a tool call;
+//      UserPromptSubmit gates a prompt. SessionStart has nothing to refuse yet, and PostToolUse /
+//      PreCompact / SessionEnd arrive after the fact — those inject or record, they never block.
+//   2. The COMMAND must not end in `|| true`, which swallows the exit code the gate would refuse with.
+const BLOCKING_EVENTS = new Set(['PreToolUse', 'UserPromptSubmit']);
+const swallowsExit = (cmd) => /\|\|\s*true\s*$/.test(String(cmd || '').trim());
+const canBlock = (event, cmd) => BLOCKING_EVENTS.has(event) && !swallowsExit(cmd);
+
+const NAME = (cmd) => {
+  const m = String(cmd || '').match(/([\w-]+)\.(sh|mjs|js)/);
+  return m ? m[1] : String(cmd || '').split(/\s+/).filter((t) => !t.startsWith('-')).pop()?.slice(0, 28) || 'hook';
+};
+
+function collect(hooksObj, source) {
+  const out = [];
+  for (const [event, groups] of Object.entries(hooksObj || {})) {
+    const list = Array.isArray(groups) ? groups : [groups];
+    for (const g of list) {
+      const hooks = Array.isArray(g?.hooks) ? g.hooks : (g?.command ? [g] : []);
+      for (const h of hooks) {
+        if (!h?.command) continue;
+        out.push({ event, matcher: g?.matcher ?? '*', name: NAME(h.command), blocking: canBlock(event, h.command), source });
+      }
+    }
+  }
+  return out;
+}
+
+// Every catch the gates have recorded. This file only exists once a gate has actually refused
+// something — an empty ledger is an honest "nothing caught yet", never a failure.
+export function gateBlocks() {
+  try {
+    return fs.readFileSync(BLOCKS, 'utf8').trim().split('\n')
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+export function gatesSurvey({ repo } = {}) {
+  const machine = collect(readJSON(path.join(HOME, '.claude/settings.json'))?.hooks, 'machine');
+  const pluginCfg = repo ? readJSON(path.join(repo, 'plugin/hooks/hooks.json')) : null;
+  const plugin = collect(pluginCfg?.hooks || pluginCfg, 'plugin');
+
+  const all = [...machine, ...plugin];
+  const blocking = all.filter((g) => g.blocking);
+
+  // THE LEDGER IS MACHINE-WIDE; THIS SURVEY IS ABOUT ONE PROJECT. Every catch ever recorded on the
+  // machine used to be counted here, so standing in an empty folder produced "203 refusals have been
+  // recorded" — this repo's history, attributed to a project that has never run a gate. Each record
+  // carries the `cwd` it was caught in, so when a project is named, only its own catches count.
+  //
+  // KNOWN LIMIT, stated rather than hidden: `cwd` is a basename, so two projects sharing a folder
+  // name share a count. That is a real ambiguity and it is narrow; attributing the whole machine's
+  // history to whichever directory you happen to be standing in was neither.
+  const here = repo ? path.basename(path.resolve(repo)) : null;
+  const allBlocks = gateBlocks();
+  const blocks = here ? allBlocks.filter((b) => b.cwd === here) : allBlocks;
+
+  // Same gate, same event, wired both machine-wide AND by the plugin — it runs twice on every
+  // matching call. Harmless to correctness (these gates are idempotent) but it is real duplicated
+  // work, and counting it as two protections would inflate the only number on the card that matters.
+  const seen = new Map();
+  const duplicated = [];
+  for (const g of all) {
+    const k = `${g.event}:${g.name}`;
+    if (seen.has(k) && seen.get(k) !== g.source) { if (!duplicated.includes(g.name)) duplicated.push(g.name); }
+    seen.set(k, g.source);
+  }
+  const uniqueBlocking = new Set(blocking.map((g) => `${g.event}:${g.name}`)).size;
+
+  // Group the catches by gate so the card can say WHAT was caught, not just how many times.
+  const byGate = {};
+  for (const b of blocks) (byGate[b.gate] ||= []).push(b);
+
+  const weekAgo = Date.now() - 7 * 864e5;
+  const recent = blocks.filter((b) => Date.parse(b.at || 0) >= weekAgo);
+
+  // THREE NUMBERS, ONE UNIT. This block used to mix two: `blocking` was DEDUPLICATED
+  // (distinct event:name) while `advisory` was `all.length - blocking.length`, computed from the
+  // RAW array. So `blocking + advisory` fell short of `armed` by exactly the number of duplicated
+  // blocking wirings, and the console printed "N gates armed — B can stop a call. The other A add
+  // context" where B + A ≠ N. On a machine with 4 duplicate blocking gates the sentence silently
+  // lost four of them — in the one sentence whose entire job is to account for all of them.
+  //
+  // It summed correctly on any machine with no duplicates, which is why it survived: the defect was
+  // invisible exactly where it was most often looked at. Found by Fable 5, 2026-07-24, by adding up
+  // the numbers on the owner's own console.
+  //
+  // Fixed by reporting all three in WIRED-ENTRY units, so armed = blocking + advisory holds by
+  // construction. The distinct-gate count is still exported — it is genuinely the more meaningful
+  // number for "how many different things can refuse" — but under its own name, where it cannot be
+  // mistaken for a term in that sum.
+  const blockingWired = blocking.length;
+  return {
+    summary: {
+      armed: all.length,
+      blocking: blockingWired,           // wired entries that can refuse — same unit as `armed`
+      advisory: all.length - blockingWired,
+      blockingDistinct: uniqueBlocking,  // distinct gates that can refuse; ≤ blocking when wired twice
+      duplicated,                        // wired twice; runs twice
+      caughtTotal: blocks.length,
+      caughtThisWeek: recent.length,
+      everRecorded: blocks.length > 0,
+    },
+    gates: all.sort((a, b) => Number(b.blocking) - Number(a.blocking)),
+    // Newest first — the most recent catch is the one worth reading.
+    catches: blocks.slice(-12).reverse(),
+    byGate: Object.fromEntries(Object.entries(byGate).map(([k, v]) => [k, v.length])),
+  };
+}

package/scripts/gen-console-images.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// gen-console-images.mjs — imagery for the Onboarding Console. Same proven path as gen-images.mjs
+// (OpenAI gpt-image-1, fallback dall-e-3), same brand style, output into console/assets/.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const OUT = path.join(ROOT, 'console/assets');
+fs.mkdirSync(OUT, { recursive: true });
+
+// Load the key the same way gen-images.mjs does, but tolerate a few env-file locations.
+function loadKey() {
+  if (process.env.OPENAI_API_KEY) return process.env.OPENAI_API_KEY;
+  const candidates = [process.env.RUVNET_ENV_FILE, path.join(ROOT, '.env'), path.join(process.env.HOME, 'Code/Ask-Ruvnet/.env')].filter(Boolean);
+  for (const f of candidates) { try { const m = fs.readFileSync(f, 'utf8').match(/^OPENAI_API_KEY=(.+)$/m); if (m) return m[1]; } catch { /* next */ } }
+  return '';
+}
+const KEY = (loadKey().match(/sk-[A-Za-z0-9_\-]+/) || [''])[0];
+if (!KEY) { console.error('no OPENAI_API_KEY (env or .env)'); process.exit(2); }
+const redact = (s) => String(s).replace(/sk-[A-Za-z0-9_\-]+/g, 'sk-***');
+
+const STYLE = ' — Style: deep near-black background (#0a0c10), sophisticated premium editorial-tech aesthetic, restrained warm amber (#f0a830) and warm gold (#ffce6a) glow with cool cyan (#5ad6ff) and calm green (#5fd38a) accents only, cinematic soft volumetric light, generous negative space, refined, calming, screenshot-worthy, high craft. Absolutely NO text, NO words, NO letters, NO numbers, NO UI chrome, NO logos, NO circuit-board cliché.';
+
+const IMAGES = [
+  { slug: 'hero', size: '1536x1024', p: 'A warm amber intelligence gently understanding a computer: soft glowing amber and gold neural filaments and threads of light weaving and resolving out of a faint tangle on the left into an elegant, orderly, translucent crystalline lattice of floating glass panels and cards on the right — the feeling of messy machine settings being calmly brought into clear, beautiful order. Lots of soft dark negative space on the right for text.' },
+  { slug: 'memory', size: '1024x1024', p: 'A single luminous softly-glowing sphere of warm amber and cyan light, made of countless fine interwoven filaments, holding its shape calmly in dark space — an abstract emblem of a mind that remembers; serene, alive, precise.' },
+];
+
+async function gen(model, prompt, size) {
+  const body = model === 'gpt-image-1'
+    ? { model, prompt, size, quality: 'high', n: 1 }
+    : { model, prompt, size: size === '1536x1024' ? '1792x1024' : '1024x1024', response_format: 'b64_json', n: 1 };
+  const r = await fetch('https://api.openai.com/v1/images/generations', {
+    method: 'POST', headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error(`${model} HTTP ${r.status}: ${(await r.text()).slice(0, 160)}`);
+  return (await r.json()).data[0].b64_json;
+}
+
+const only = process.argv.slice(2).filter((a) => !a.startsWith('-'));
+for (const im of IMAGES) {
+  if (only.length && !only.includes(im.slug)) continue;
+  const prompt = im.p + STYLE;
+  let b64;
+  try { b64 = await gen('gpt-image-1', prompt, im.size); console.log(`✓ ${im.slug} (gpt-image-1)`); }
+  catch (e) {
+    console.log(`  gpt-image-1 failed for ${im.slug}: ${redact(e.message)} — trying dall-e-3`);
+    try { b64 = await gen('dall-e-3', prompt, im.size); console.log(`✓ ${im.slug} (dall-e-3)`); }
+    catch (e2) { console.error(`✗ ${im.slug}: ${redact(e2.message)}`); continue; }
+  }
+  fs.writeFileSync(path.join(OUT, `${im.slug}.png`), Buffer.from(b64, 'base64'));
+}
+console.log('done →', OUT);

package/scripts/gen-images.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// gen-images.mjs — generate a cohesive set of explainer images (OpenAI gpt-image-1, fallback dall-e-3).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const OUT = path.join(ROOT, 'explainer/assets/img');
+fs.mkdirSync(OUT, { recursive: true });
+const RAWKEY = process.env.OPENAI_API_KEY || (fs.readFileSync((process.env.RUVNET_ENV_FILE || '.env'), 'utf8').match(/^OPENAI_API_KEY=(.+)$/m) || [])[1] || '';
+const KEY = (RAWKEY.match(/sk-[A-Za-z0-9_\-]+/) || [''])[0];   // first valid token only — handles dup lines / whitespace
+if (!KEY) { console.error('no OPENAI_API_KEY'); process.exit(2); }
+const redact = (s) => String(s).replace(/sk-[A-Za-z0-9_\-]+/g, 'sk-***');   // never let a key reach logs
+
+const STYLE = ' — Style: dark near-black background (#0b0d0f) with a faint blueprint grid, sophisticated premium editorial-tech aesthetic, restrained warm amber (#f0a830) and cool cyan (#5ad6ff) accent light only, cinematic volumetric glow, fine detail, high craft, elegant and confident. Absolutely NO text, NO words, NO letters, NO numbers, NO UI chrome, NO logos.';
+
+const IMAGES = [
+  { slug: 'hero', size: '1536x1024', p: 'A luminous intricate three-dimensional structure resembling a brain fused with a vast interconnected codebase: thousands of glowing amber and cyan filaments forming one elegant organized sphere of intelligence, floating in dark space, a sense of all knowledge made orderly and alive.' },
+  { slug: 'problem-skim', size: '1536x1024', p: 'A vast deep canyon made of densely stacked layers of code and documents descending far into darkness; a single small fragile light hovers at the very top only grazing the surface, never reaching the immense depth below. The feeling of skimming and missing everything underneath.' },
+  { slug: 'point-deeper', size: '1536x1024', p: 'One precise clean beam of warm amber light cutting straight down through many deep translucent strata of a vast structure to perfectly illuminate a single exact point far below; surgical precision locating the one true answer in the depths.' },
+  { slug: 'architecture', size: '1536x1024', p: 'An elegant isometric exploded view of five translucent glass layers floating one above another in dark space, each a slightly different luminous tone, joined by thin vertical conduits of light; a refined premium product render of a clean layered system.' },
+  { slug: 'proof', size: '1536x1024', p: 'Three distinct elegant luminous measuring instruments aim converging beams of light onto a single crystalline object at center that glows confident green, while one beam exposes a hidden flaw glowing warning red; independent rigorous verification against a single source of truth.' },
+];
+
+async function gen(model, prompt, size) {
+  const body = model === 'gpt-image-1'
+    ? { model, prompt, size, quality: 'high', n: 1 }
+    : { model, prompt, size: size === '1536x1024' ? '1792x1024' : '1024x1024', response_format: 'b64_json', n: 1 };
+  const r = await fetch('https://api.openai.com/v1/images/generations', {
+    method: 'POST', headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error(`${model} HTTP ${r.status}: ${(await r.text()).slice(0, 160)}`);
+  const j = await r.json();
+  return j.data[0].b64_json;
+}
+
+for (const im of IMAGES) {
+  const prompt = im.p + STYLE;
+  let b64;
+  try { b64 = await gen('gpt-image-1', prompt, im.size); console.log(`✓ ${im.slug} (gpt-image-1)`); }
+  catch (e) {
+    console.log(`  gpt-image-1 failed for ${im.slug}: ${redact(e.message)} — trying dall-e-3`);
+    try { b64 = await gen('dall-e-3', prompt, im.size); console.log(`✓ ${im.slug} (dall-e-3)`); }
+    catch (e2) { console.error(`✗ ${im.slug}: ${redact(e2.message)}`); continue; }
+  }
+  fs.writeFileSync(path.join(OUT, `${im.slug}.png`), Buffer.from(b64, 'base64'));
+}
+console.log('done →', OUT);

package/scripts/git-clone-refresh.mjs

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function submodulePaths(repoDir) {
+  const gitmodules = path.join(repoDir, '.gitmodules');
+  if (!fs.existsSync(gitmodules)) return [];
+  let output = '';
+  try {
+    output = execFileSync(
+      'git',
+      ['config', '-f', gitmodules, '--get-regexp', '^submodule\\..*\\.path$'],
+      { encoding: 'utf8' },
+    );
+  } catch (error) {
+    if (error.status !== 1) throw error;
+  }
+  return output.trim().split('\n').filter(Boolean).map((line) => line.replace(/^\S+\s+/, ''));
+}
+
+export function withSubmoduleSymlinksDetached(repoDir, operation) {
+  const detached = [];
+  for (const relativePath of submodulePaths(repoDir)) {
+    const absolutePath = path.join(repoDir, relativePath);
+    let stat;
+    try {
+      stat = fs.lstatSync(absolutePath);
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
+    if (!stat.isSymbolicLink()) continue;
+    detached.push({ absolutePath, target: fs.readlinkSync(absolutePath) });
+    fs.unlinkSync(absolutePath);
+  }
+
+  try {
+    return operation();
+  } finally {
+    for (const { absolutePath, target } of detached) {
+      if (fs.existsSync(absolutePath)) {
+        const stat = fs.lstatSync(absolutePath);
+        if (!stat.isDirectory() || fs.readdirSync(absolutePath).length > 0) {
+          throw new Error(`cannot restore submodule symlink over non-empty path: ${absolutePath}`);
+        }
+        fs.rmdirSync(absolutePath);
+      }
+      fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+      fs.symlinkSync(target, absolutePath);
+    }
+  }
+}

package/scripts/git-hooks/pre-push

@@ -0,0 +1,126 @@
+#!/bin/sh
+# RuvNet Brain — pre-push gate. NON-OPTIONAL. Runs on every `git push`.
+#
+# WHY (2026-07-17): a real client (Jan) hit npx ruvnet-brain@latest with a stale package whose
+# self-update manifest 404'd. The root cause wasn't the bug — it was that the CHECK was optional
+# and I skipped it. This hook removes the discretion: it refuses the push if the version surfaces
+# disagree or the self-update manifest 404s. It does not care whether I remembered, or was in a
+# hurry, or "was pretty sure it was fine." Pass or the push does not happen.
+#
+# It blocks ONLY on what is knowable before a push. npm-latest and the live explainer are verified
+# post-publish by `node scripts/release.mjs --publish` (the only sanctioned ship path).
+#
+# Escape hatch is `git push --no-verify` — but if you use it, you are consciously overriding a gate
+# that exists because of a specific failure that cost real user trust. Own that out loud.
+#
+# SECRET SCAN (2026-07-21): a buggy diagnostic echoed live OPENAI and OPENROUTER keys into a
+# terminal, and AgentDB's session autocapture wrote them to .swarm/. Nothing reached git — but the
+# only thing that stopped it was a GLOBAL gitignore that does not travel to a clone or another
+# machine. Relying on "the file happened to be ignored" is not a control. This is: a real key
+# pattern in anything being pushed refuses the push. Placeholders (your-key, abc123, xxxx,
+# deadbeef, example) are excluded, because rUv's own docs are full of them and a gate that cries
+# wolf on documentation is a gate people learn to bypass.
+#
+# SCOPE FIX (2026-07-22): this scanned `git diff --cached HEAD` — the STAGED INDEX. But a push ships
+# COMMITS, and at push time the index is normally clean, so the scan read nothing. Proven both ways
+# in a scratch repo: a key COMMITTED then pushed sailed through, while the same key merely STAGED was
+# blocked. The gate could only catch the one case that never happens. It is the same defect class the
+# 7e715bb commit fixed in the *test* — a check that cannot fail in the situation it was written for —
+# which survived here in the *scan*. Now it reads the actual push range from the hook's stdin.
+RANGE_DIFF=""
+CURRENCY_BASE=""
+while read -r _local_ref local_sha _remote_ref remote_sha; do
+  [ -z "$local_sha" ] && continue
+  case "$local_sha" in *[!0]*) ;; *) continue ;; esac        # all-zeros = branch deletion, nothing to scan
+  case "$remote_sha" in
+    ""|*[!0-9a-f]*|0000000000000000000000000000000000000000)  # new branch: scan its whole history vs other refs
+      RANGE_DIFF="$RANGE_DIFF$(git diff --no-color -U0 "$(git merge-base HEAD origin/main 2>/dev/null || echo '')" "$local_sha" 2>/dev/null)"
+      # ADR-056 §5: a new branch has no remote counterpart, so the merge-base with main is the only
+      # honest base. If even that cannot resolve, CURRENCY_BASE stays empty and the currency check is
+      # SKIPPED rather than run against a guess — never a scope invented from nothing.
+      [ -z "$CURRENCY_BASE" ] && CURRENCY_BASE="$(git merge-base HEAD origin/main 2>/dev/null || true)" ;;
+    *)
+      RANGE_DIFF="$RANGE_DIFF$(git diff --no-color -U0 "$remote_sha" "$local_sha" 2>/dev/null)"
+      # ADR-056: the remote tip is only a valid "what did I change" base when it is an ANCESTOR of
+      # what we are pushing. After a rebase or squash it is NOT — the range then spans the entire
+      # rewrite and drags in every document the upstream branch already carried, red ones included.
+      # Measured 2026-07-27: a force-push after rebasing onto main was refused for ADR-054 and
+      # ADR-055 — two documents on main that this branch never touched. GPT-5.6 predicted exactly
+      # this in the ADR-056 duel ("rebase or squash changes the touched-file set without changing
+      # whether a violation is genuinely new"). So: ancestor => use it; otherwise fall back to the
+      # merge-base with main, which is the honest answer to "what is mine".
+      if [ -z "$CURRENCY_BASE" ]; then
+        if git merge-base --is-ancestor "$remote_sha" "$local_sha" 2>/dev/null; then
+          CURRENCY_BASE="$remote_sha"
+        else
+          CURRENCY_BASE="$(git merge-base "$local_sha" origin/main 2>/dev/null || true)"
+        fi
+      fi ;;
+  esac
+done
+# Fall back to the staged index too, so a pre-commit-style invocation still gets covered.
+RANGE_DIFF="$RANGE_DIFF
+$(git diff --cached --no-color -U0 HEAD 2>/dev/null)"
+
+SECRET_HITS=$(printf '%s' "$RANGE_DIFF" | grep -E "^\+" \
+  | grep -oE "sk-(proj|ant|or-v1)-[A-Za-z0-9_-]{20,}" \
+  | grep -vEi "your-key|abc123|xxxx+|deadbeef|example|placeholder|REDACTED" | head -3)
+if [ -n "$SECRET_HITS" ]; then
+  echo ""
+  echo "  ⛔ PUSH BLOCKED — what looks like a REAL API key is in this push."
+  echo "     matched (prefix only): $(echo "$SECRET_HITS" | cut -c1-14 | tr '\n' ' ')"
+  echo "     Remove it, rotate the key, and push again. Never --no-verify past this one:"
+  echo "     a key that reaches a remote is compromised the moment it lands."
+  echo ""
+  exit 1
+fi
+
+# Hooks may be shared by several git worktrees. Resolving from this script's own path is wrong when
+# core.hooksPath names another checkout: the hook then validates that checkout while pushing the
+# current one (measured 2026-07-28: announced 3.9.128, pushed 3.9.129). Git already knows the
+# worktree whose refs are being pushed, so derive the shipping root from that live repository.
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$ROOT" ] || [ ! -f "$ROOT/scripts/verify-channels.mjs" ]; then
+  echo "  ⛔ pre-push gate cannot resolve the worktree being pushed."
+  exit 1
+fi
+node "$ROOT/scripts/verify-channels.mjs" --pre-push
+status=$?
+if [ "$status" -ne 0 ]; then
+  echo ""
+  echo "  ⛔ pre-push gate refused this push. A user on some path would get a broken build."
+  echo "     Fix the channel(s) above, then push again. Do not route around this."
+  exit 1
+fi
+
+# ── DOCUMENT CURRENCY (ADR-056 §5) ─────────────────────────────────────────────────────────────────
+# The tool was written and tested on 2026-07-22 and then invoked by NOTHING for five days — absent
+# from this hook, gate.sh, gates.mjs and every workflow, while `wired-check` reported it "wired"
+# because package.json DEFINED an npm alias for it. This line is the whole fix.
+#
+# NO RATCHET, DELIBERATELY. The first draft of ADR-056 proposed a stateful new-vs-pre-existing
+# violation tracker so this gate could coexist with 32 pre-existing BLOCKs forever. Two independent
+# adversarial reviews killed it: a committed baseline is gamed by the same commit that adds the
+# violation, re-deriving at the remote SHA needs a second worktree, and "report the rest forever"
+# is the wolf-cry doc-currency.mjs's own header names as its designed failure mode. The debt was
+# PAID instead (32 BLOCKs -> 4, all four genuine re-reads), which makes the plain gate safe.
+#
+# SCOPED to what this push touches. A pre-existing red document must not block someone who merely
+# walked past it — that teaches people never to touch the red documents, preserving exactly the drift
+# this exists to end. Scope is empty => nothing to check => pass; never a scope invented from nothing.
+if [ -n "$CURRENCY_BASE" ]; then
+  node "$ROOT/scripts/doc-currency.mjs" --check --changed "$CURRENCY_BASE"
+  dc_status=$?
+  if [ "$dc_status" -ne 0 ]; then
+    echo ""
+    echo "  ⛔ pre-push gate refused this push — a document you touched disagrees with its code."
+    echo "     An ADR that describes a world the code left is worse than no ADR."
+    echo "     \`node scripts/doc-currency.mjs --fix\` backfills every date git can prove;"
+    echo "     everything else is a claim only you can make."
+    exit 1
+  fi
+fi
+echo ""
+echo "  ✓ pre-push gate passed — version, channels, secrets, and document currency are clean."
+echo ""
+exit 0