ruvnet-brain 4.0.36 → 4.0.90-dev

package/scripts/org-repo-count.mjs

@@ -0,0 +1,119 @@
+/**
+ * org-repo-count.mjs — how many repos rUv actually has, DERIVED, with the source recorded.
+ *
+ * THE DEFECT THIS REPLACES. `orgTotalApprox: 248` was a literal, written twice:
+ *
+ *     scripts/build-bundle.mjs:402   coverage: { …, orgTotalApprox: 248, … }
+ *     scripts/brain-stamp.mjs:77     coverage: { …, orgTotalApprox: 248, … }
+ *
+ * Measured 2026-08-12, two independent ways: `users/ruvnet.public_repos` = 200, and a paginated
+ * `users/ruvnet/repos` fetch = 200 distinct names. So the denominator every coverage percentage in
+ * this product is computed against was wrong by 48 — and wrong in BOTH copies, which is what a
+ * restated fact always does.
+ *
+ * Replacing 248 with 200 would repeat the mistake with a fresher number. The count changes whenever
+ * rUv pushes a new repo, so it is not a constant and must not be stored as one.
+ *
+ * HONESTY OVER AVAILABILITY. A build with no network must not silently invent a total. `source` is
+ * carried alongside the number so every consumer can see whether it is live:
+ *
+ *     { count: 200, source: 'live',     at: '2026-08-12T…' }   ← queried just now
+ *     { count: 200, source: 'recorded', at: '2026-08-12T…' }   ← last live reading, reused offline
+ *     { count: null, source: 'unknown', at: null }             ← never say a number we cannot source
+ *
+ * A consumer that receives `unknown` must omit the claim rather than print a guess — the same rule
+ * sync-census follows when it refuses to write a non-positive census.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+/** The last LIVE reading, so an offline build reuses a real measurement instead of a literal. */
+export const RECORD_PATH = process.env.RUVNET_ORG_COUNT_RECORD
+  || path.join(ROOT, 'data', 'org-repo-count.json');
+
+export const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
+
+/** Ask GitHub. Returns a positive integer or null — never a guess, never a partial page. */
+export function fetchLiveCount(owner = OWNER, { run = spawnSync } = {}) {
+  // `public_repos` is the account's own count: one request, no pagination to get wrong.
+  const r = run('gh', ['api', `users/${owner}`, '--jq', '.public_repos'], { encoding: 'utf8', timeout: 30_000 });
+  if (r.error || r.status !== 0) return null;
+  const n = Number(String(r.stdout || '').trim());
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+const readRecord = (file) => {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Number.isInteger(j?.count) && j.count > 0 ? j : null;
+  } catch { return null; }
+};
+
+/**
+ * The count, its provenance, and when it was taken.
+ * A successful live read updates the record, so the offline fallback is always a real past reading.
+ */
+/**
+ * READING A NUMBER MUST NOT MUTATE A TRACKED FILE.
+ *
+ * `persist` defaults to FALSE, and that default is the fix for a release that could not ship.
+ * Every call used to write `data/org-repo-count.json` — a TRACKED file — with a fresh `at`
+ * timestamp. Both production callers (`brain-stamp.mjs`, `build-bundle.mjs`) are BUILD scripts, so
+ * building the release candidate dirtied the working tree, and `release-qe`'s stabilization seal
+ * requires `dirty === false`. Measured 2026-08-19, once the seal was made to name its cause:
+ *
+ *     stabilization seal failed: INVALID_LINEAGE
+ *       working tree is dirty (1 path(s)):
+ *         M data/org-repo-count.json
+ *
+ * That single line had blocked EVERY release since 2026-08-08 (issue #141: nothing published in
+ * eleven days while main advanced 46 commits), because the seal previously reported only the code
+ * `INVALID_LINEAGE` and named nothing.
+ *
+ * The committed record still matters — it is the honest offline fallback, so an air-gapped or
+ * rate-limited build reuses the last REAL reading instead of inventing one. It just may not be
+ * written as a side effect of being read. Refreshing it is now a deliberate act (`--record`), the
+ * same separation `refresh-model-catalog.mjs` already uses for the model snapshot.
+ */
+export function orgRepoCount({ owner = OWNER, file = RECORD_PATH, now = new Date(), fetch = fetchLiveCount, persist = false } = {}) {
+  const live = fetch(owner);
+  if (live) {
+    const at = now.toISOString();
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      if (persist) fs.writeFileSync(file, `${JSON.stringify({ owner, count: live, at }, null, 2)}\n`);
+    } catch { /* recording is best-effort; the live number still stands */ }
+    return { count: live, source: 'live', at };
+  }
+  const rec = readRecord(file);
+  if (rec) return { count: rec.count, source: 'recorded', at: rec.at || null };
+  return { count: null, source: 'unknown', at: null };
+}
+
+/**
+ * Refreshing the committed record is a DELIBERATE ACT, never a side effect of a build.
+ *
+ *     node scripts/org-repo-count.mjs --record
+ *
+ * Same separation `refresh-model-catalog.mjs` uses for the model snapshot: a build READS, a human
+ * (or a scheduled refresh that commits its own result) WRITES. That boundary is what keeps the
+ * working tree clean for `release-qe`'s stabilization seal.
+ */
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const record = process.argv.includes('--record');
+  const r = orgRepoCount({ persist: record });
+  process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  if (record && r.source !== 'live') {
+    process.stderr.write('NOT recorded: the live read failed, and a remembered number may not be '
+      + 'rewritten as if it were fresh.\n');
+    process.exit(1);
+  }
+}

package/scripts/repo-count-detector.mjs

@@ -0,0 +1,62 @@
+// repo-count-detector.mjs — THE ONE detector for corpus-size claims in public surfaces.
+//
+// Extracted from tests/unit/repo-count.test.mjs on 2026-08-10 so the WRITER (sync-census.mjs)
+// and the GATE (repo-count.test.mjs) consult the same code. They had drifted by construction:
+// the gate found every phrasing, while the writer enumerated a handful by hand and missed
+// "71 of rUv's repos", "71 RuvNet building-block repos", "71 built today", and the
+// HTML-entity variant. A checker and a fixer that disagree guarantee recurring red builds.
+
+export const MIN_CORPUS_MAGNITUDE = 20;
+
+// Deliberate, documented exceptions: the literal is correct AS WRITTEN because it describes a
+// PAST state (a "before" baseline in a receipts table), not a current claim — not stale data.
+// Anything else that disagrees with ALLOWED fails. Keyed `${file}::${matched text}` so a typo'd
+// exemption can't silently swallow an unrelated real regression.
+export const EXEMPT = new Set([
+  'README.md::24 repos', // v1 (pre-2.0) baseline column in the "what 2.0 proved" before/after table
+  'README.md::24→69 verified repos', // same v1-baseline row, "24→<current>" delta phrasing
+  // 2026-08-06: the corpus grew 69 → 71 (tonight's rebuild). The CURRENT claims were updated to 71
+  // in README.md and SKILL.md, but these two are HISTORICAL — they describe what release 2.0
+  // proved, inside a collapsed "Earlier — what 2.0 proved" section and its before/after table.
+  // Rewriting them to 71 would be the easy way to make this gate green and would falsify the record:
+  // 2.0 shipped with 69, not 71. A gate that pressures you into editing history is worse than the
+  // stale number it caught, so historical mentions are exempted by name and current ones are not.
+  'README.md::69 verified repos', // "what 2.0 proved" summary line — a claim about 2.0, not today
+  'README.md::69 repos', // the 2.0 column of the same v1→v2.0 before/after table
+]);
+
+/** @param {string} src @returns {{text: string, n: number}[]} */
+export function findRepoCountLiterals(src) {
+  const found = [];
+  // Covers "repo(s)" and the spelled-out "repositor(y|ies)" (SKILL.md line 8's own phrasing:
+  // "32 RuvNet (rUv / Reuven Cohen) repositories" — real prose puts several filler words/
+  // parentheticals between the number and the noun, so this can't be a fixed word count).
+  const REPO_WORD = '(?:repos?|repositor(?:y|ies))';
+  // Digit NOT immediately followed by "+": an open lower-bound like "20+ repos" is a true,
+  // deliberately-vague qualifier, not a precise count claim — exempt from matching at all rather
+  // than needing a per-mention exemption. Filler between the digit and the repo-word is capped at
+  // 50 chars and may not cross a sentence end / table-cell boundary (".", "|", newline), so this
+  // can't accidentally bridge two unrelated numbers separated by prose.
+  // `(?<!\d\.)` — never treat a SEMVER COMPONENT as a repo count. Real false positive: the primer's
+  // header line "…v3.4.21-dev · Built: 2026-07-20 · Covers: 69/192 repos" made the detector read the
+  // patch number `21` (the `-` after it is a word boundary) and then walk 40-odd filler chars to
+  // "repos", reporting a stale count on a line whose actual claim — 69/192 — was correct. The
+  // published number was right and the gate cried wolf, which is how a gate loses its authority.
+  // Two guards, both added after REAL false positives on the primer's own header line
+  // "…<version> · Built: <date> · Covers: 69/192 repos", whose actual claim (69/192) is correct:
+  //   (?<!\d\.)  — a SEMVER COMPONENT is never a repo count. The patch number was being read as
+  //                one, because the `-` before a prerelease suffix is a word boundary.
+  //   `·` in the filler exclusion — a middle dot separates INDEPENDENT facts. Without it the walk
+  //                crossed from the build DATE into the count and reported `2026` as a repo count
+  //                (found by this file's own detector tests, after the semver fix unmasked it).
+  const reSpaced = new RegExp(`(?<!\\d\\.)\\b(\\d{1,4})(?!\\+)\\b(?:(?![.|·\\n])[\\s\\S]){0,50}?\\b${REPO_WORD}\\b`, 'gi');
+  const reHyphen = new RegExp(`(?<!\\d\\.)\\b(\\d{1,4})(?!\\+)-repos?\\b`, 'gi');
+  for (const re of [reSpaced, reHyphen]) {
+    for (const m of src.matchAll(re)) {
+      const n = Number(m[1]);
+      if (n >= MIN_CORPUS_MAGNITUDE) found.push({ text: m[0], n });
+    }
+  }
+  return found;
+}
+

package/scripts/restore-local-ingests.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * restore-local-ingests.mjs — replay every ingest a bundle apply silently removed.
+ *
+ * WHAT HAPPENED, overnight 2026-08-13 → 08-14. A scheduled bundle apply extracted an Aug-8 bundle
+ * over the live brain cache. The outcome for each piece of the previous evening's work was decided
+ * entirely by whether it had been committed:
+ *
+ *   SURVIVED  capability-cards.md — 5 hand-written cards, committed and pushed that night. The live
+ *             brain was restored from the repo copy in one command.
+ *   DIED      helix, rvQR, RuCelium, wifi-veil — ingested and VERIFIED ROUTING hours earlier, gone
+ *             without a trace. Their cards became orphans pointing at stores that no longer existed,
+ *             which is worse than absence: the router offers an answer whose source is missing.
+ *
+ * The owner, correctly and for the second time: "you can't ever let work go overnight — you must
+ * always push latest changes or things get overwritten."
+ *
+ * A `.rvf` is a 32MB gitignored build artifact and CANNOT be committed. So the rule's second half
+ * applies: when the artifact cannot be pushed, commit the RECIPE. `ingest-repo.mjs` now records each
+ * ingest into `kb/local-ingests.json`, and this replays anything the cache is missing.
+ *
+ * The wipe was not on either adversarial audit's list, because both read code and this only shows
+ * up if you watch the machine overnight. A defect that needs a night to appear needs a ledger to be
+ * seen at all.
+ *
+ * MEASURED 2026-08-19, Dream Cycle memory-durability night: this script cannot tell "the store root
+ * was wiped" from "the store root never existed on this host" — a fresh checkout, a CI runner, or
+ * this very nightly agent's own ephemeral container all read exactly one recorded ingest away from
+ * every other, i.e. IDENTICALLY to a real overnight wipe, because `missingIngests()` only diffs the
+ * ledger against `storesAt(root)`, and `storesAt()` silently returns `[]` on ENOENT (kb/store-root.mjs).
+ * `restore-local-ingests.mjs` had zero test coverage before tonight, and the repo's own dream-cycle
+ * operating notes told this very automation to read ANY non-zero exit as "the nightly bundle wiped
+ * local work" — so a routine fresh-checkout run would have logged a false wipe every single night.
+ *
+ * The fix follows the pattern this repo already uses correctly in `nightly-watchdog.mjs`
+ * (MISSING / NEVER-RAN / STALE, three states never collapsed into one alarm) and the general
+ * pattern for reconciling a durable recipe against a rebuildable cache (npm's `.package-lock.json`
+ * witness co-located with `node_modules`, Dynamo-style tombstones): check whether the root was ever
+ * initialized BEFORE treating its contents as evidence of loss.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { storeRoot, storesAt } from '../kb/store-root.mjs';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const LEDGER = path.join(ROOT, 'kb', 'local-ingests.json');
+
+export const OK = 'OK';
+export const NEVER_MATERIALIZED = 'NEVER-MATERIALIZED';
+export const WIPED = 'WIPED';
+
+/** Which recorded ingests are absent from the store root retrieval actually reads. */
+export function missingIngests({ ledgerFile = LEDGER, root = storeRoot() } = {}) {
+  let recorded = [];
+  try { recorded = JSON.parse(fs.readFileSync(ledgerFile, 'utf8')).ingests ?? []; } catch { return []; }
+  const present = new Set(storesAt(root));
+  return recorded.filter((e) => !present.has(e.store ?? e.name.toLowerCase()));
+}
+
+/**
+ * Classify a diff between the recipe ledger and the live store root into three states, never one:
+ *   OK                 every recorded ingest is present.
+ *   NEVER-MATERIALIZED root does not exist on this host at all — nothing was ever ingested here.
+ *                       Not evidence of loss: a fresh checkout, CI runner, or this agent's own
+ *                       ephemeral container all look like this on a routine first run.
+ *   WIPED               root exists (so this host DID ingest before) but recorded entries are gone —
+ *                       the actual signal `restore-local-ingests.mjs` exists to catch.
+ */
+export function classify({ ledgerFile = LEDGER, root = storeRoot() } = {}) {
+  const missing = missingIngests({ ledgerFile, root });
+  if (!missing.length) return { state: OK, missing };
+  if (!fs.existsSync(root)) return { state: NEVER_MATERIALIZED, missing };
+  return { state: WIPED, missing };
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const apply = process.argv.includes('--apply');
+  const { state, missing: gone } = classify();
+  if (state === OK) {
+    console.log(`[restore] every recorded local ingest is present in ${storeRoot()}`);
+    process.exit(0);
+  }
+  // NAMED, never counted. "4 stores missing" is the truncation that reads as completeness.
+  if (state === NEVER_MATERIALIZED) {
+    console.log(`\n[restore] ${storeRoot()} does not exist on this host — ${gone.length} recorded `
+      + `ingest(s) were never materialized here. This is NOT evidence of a wipe (fresh checkout, CI `
+      + `runner, or an ephemeral agent container all look like this):`);
+  } else {
+    console.log(`\n[restore] ${gone.length} recorded ingest(s) are NOT in ${storeRoot()}:`);
+  }
+  for (const e of gone) console.log(`    ${e.name.padEnd(16)} ingested ${String(e.at).slice(0, 10)}`);
+  if (!apply) {
+    console.log('\n  read-only. Re-run with --apply to re-ingest them.\n');
+    // NEVER-MATERIALIZED exits 2 (informational: nothing to restore FROM, just re-ingest) so a
+    // caller checking the exit code cannot mistake "never synced here" for "the nightly bundle
+    // wiped local work" — WIPED keeps exit 1, the real alarm.
+    process.exit(state === NEVER_MATERIALIZED ? 2 : 1);
+  }
+  let failed = 0;
+  for (const e of gone) {
+    console.log(`\n[restore] re-ingesting ${e.name}`);
+    try {
+      execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'ingest-repo.mjs'), '--name', e.name],
+        { cwd: ROOT, stdio: 'inherit', env: process.env });
+    } catch { failed += 1; console.log(`[restore] ${e.name} FAILED — left recorded so the next run retries it`); }
+  }
+  console.log(`\n[restore] ${gone.length - failed}/${gone.length} restored.\n`);
+  process.exit(failed ? 1 : 0);
+}

package/scripts/selfcheck.mjs

@@ -532,7 +532,15 @@ export async function runBattery({ home = os.homedir(), repo = null, cwd = os.tm
 export async function checkCoexistence({ home = os.homedir(), repo = null } = {}) {
   const reg = await loadRegistry();
   const registry = reg.buildRegistry({ repo: repo ?? reg.REPO, home, includeMachine: true });
-  const ours = registry.records.filter((r) => r.layer === 'plugin' || r.layer === 'plugin-installed' || r.layer === 'marketplace-clone');
+  // 'codex' joined hook-registry.mjs's mesh 2026-08-20 (Dream Cycle cross-host-conformance) — it is
+  // OURS (plugin/hooks/codex-hooks.json, shipped in package.json's "files" tree same as plugin/),
+  // never a foreign registration. Omitting it here silently undercounted `ourCount` and dropped all
+  // 16 Codex registrations from both buckets — caught by an independent critique before this shipped.
+  // 'codex' joined hook-registry.mjs's mesh 2026-08-20 (Dream Cycle cross-host-conformance) — it is
+  // OURS (plugin/hooks/codex-hooks.json, shipped in package.json's "files" tree same as plugin/),
+  // never a foreign registration. Omitting it here silently undercounted `ourCount` and dropped all
+  // 16 Codex registrations from both buckets — caught by an independent critique before this shipped.
+  const ours = registry.records.filter((r) => r.layer === 'plugin' || r.layer === 'codex' || r.layer === 'plugin-installed' || r.layer === 'marketplace-clone');
   const foreign = registry.records.filter((r) => r.layer === 'user' || r.layer.startsWith('third-party:') || r.layer === 'project');
 
   // DOUBLE REGISTRATION — reused wholesale from hook-registry (ADR-055 M1): one handler, an

package/scripts/stabilization-receipt.mjs

@@ -52,7 +52,12 @@ export function createStabilizationReceipt({ root, artifactPath, qe, audit }) {
     scoreClaimed: false,
     sha,
     tree: git('rev-parse', 'HEAD^{tree}'),
+    // NAME WHAT IS DIRTY, or the failure is unactionable. `release-qe` has failed on EVERY main run
+    // with a bare `INVALID_LINEAGE`, which says a clean tree is required and not one word about what
+    // made it unclean — so the release chain has been blocked with no way to see why from the log.
+    // The receipt now carries the offending paths; the seal is unchanged, only its evidence is.
     dirty: Boolean(git('status', '--porcelain')),
+    dirtyPaths: String(git('status', '--porcelain') || '').split('\n').filter(Boolean).slice(0, 40),
     version: manifest.version,
     tag: `v${manifest.version}`,
     sourceVersions: { package: manifest.version, claudePlugin: claude.version, codexPlugin: codex.version },
@@ -75,7 +80,12 @@ export function createStabilizationReceipt({ root, artifactPath, qe, audit }) {
     ],
   };
   const result = evaluateStabilizationCandidateReceipt(receipt);
-  if (result.verdict !== 'PASS') throw new Error(`stabilization seal failed: ${result.failures.map(({ code }) => code).join(',')}`);
+  if (result.verdict !== 'PASS') {
+    const detail = receipt.dirty && receipt.dirtyPaths?.length
+      ? `\n  working tree is dirty (${receipt.dirtyPaths.length} path(s)):\n    ${receipt.dirtyPaths.join('\n    ')}`
+      : '';
+    throw new Error(`stabilization seal failed: ${result.failures.map(({ code }) => code).join(',')}${detail}`);
+  }
   return receipt;
 }
 

package/scripts/sync-commands.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * sync-commands.mjs — four spellings of one command share ONE body, generated, never hand-copied.
+ *
+ * ISSUE #135. `/rvbc`, `/rvcb`, `/brain-console` and `/ruvnet-brain:configure` each declare, in their
+ * own words, that every spelling is equally valid and the user must never be corrected. Their BODIES
+ * had drifted into four independent hand-written specs, measured on 4.0.36:
+ *
+ *     rvbc.md  4116 B      rvcb.md  976 B      brain-console.md  985 B      configure.md  1680 B
+ *
+ * Four rules lived only in `rvbc.md`: speak first before any tool call; the "Things NOT to do before
+ * the page is open" list; the emphatic `run_in_background: true, ALWAYS` *with its reason*; and
+ * "already running is success, not an error." So which spelling a user happened to type changed how
+ * the assistant behaved — on the one command whose entire promise is that spelling does not matter.
+ *
+ * Two of those cost real silence. Without the "no knowledge search first" prohibition, grounding
+ * before opening the page is a legal move and a cold embedding-model load is allowed up to 180
+ * seconds. And `rvcb.md` kept the `run_in_background` RULE but dropped the REASON — that a foreground
+ * run hangs the call until the 120-second timeout — and a rule whose reason is missing is a rule that
+ * gets traded away.
+ *
+ * THE FIX IS NOT "COPY THE FOUR RULES ACROSS." That is what produced this: four copies of one fact,
+ * drifting the moment anyone edits one. It is ADR-065's rule applied to prompts instead of values —
+ * a fact that appears in more than one place gets exactly ONE producer, and every other occurrence is
+ * written from it. `rvbc.md` is the producer; the other three are generated.
+ *
+ * WHAT EACH ALIAS KEEPS: its own `description:`. That is not duplicated knowledge — it is what the
+ * user reads in the command picker, and each spelling legitimately introduces itself differently.
+ * Everything below the frontmatter is byte-identical by construction.
+ *
+ *   node scripts/sync-commands.mjs           # rewrite the aliases from the canonical body
+ *   node scripts/sync-commands.mjs --check   # fail if any alias has drifted (CI / pre-push)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const DIR = path.join(ROOT, 'plugin', 'commands');
+const CANONICAL = 'rvbc.md';
+const ALIASES = ['rvcb.md', 'brain-console.md', 'configure.md'];
+const CHECK = process.argv.includes('--check');
+
+/** Split `---\n…\n---\n` frontmatter from the body. Both are returned verbatim. */
+export function splitFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  if (!m) return { frontmatter: null, body: text };
+  return { frontmatter: m[1], body: text.slice(m[0].length) };
+}
+
+/** The alias's own description line, kept; everything else in the frontmatter comes from canonical. */
+function rebuild(aliasText, canonicalFrontmatter, canonicalBody) {
+  const { frontmatter } = splitFrontmatter(aliasText);
+  const desc = /^description:.*(?:\n[ \t]+.*)*$/m.exec(frontmatter || '');
+  const rest = canonicalFrontmatter
+    .split('\n')
+    .filter((l) => !/^description:/.test(l))
+    .join('\n');
+  const head = [desc ? desc[0] : null, rest].filter(Boolean).join('\n');
+  return `---\n${head}\n---\n${canonicalBody}`;
+}
+
+// RUN THE CLI ONLY WHEN INVOKED AS ONE. Without this guard, `import { splitFrontmatter }` from a test
+// executed the whole generator — measured: importing this file printed "[commands] synced 0 alias(es)"
+// inside the test runner, and had vitest's argv contained `--check` it would have called process.exit
+// and taken the runner down with it. The identical defect was fixed in tests/unit/nightly-convergence
+// one commit earlier (importing bin/install.mjs ran the installer main); it recurred here because that
+// fix was applied to the CALLER instead of to the module. Fixing it at the module is what makes it
+// stop recurring — same reasoning as ADR-066: one producer, not a rule every caller must remember.
+// realpathSync THROWS on a path that does not resolve, and under vitest on Windows `process.argv[1]`
+// is not a real file — measured in CI as `ENOENT: lstat 'D:\D:'`, which failed the whole SUITE at
+// import time rather than any assertion. A guard that decides "am I the entrypoint" must never be
+// able to crash the caller that merely imported this module: not-resolvable means not-main.
+function resolvedIsMain() {
+  try {
+    return Boolean(process.argv[1])
+      && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch { return false; }
+}
+if (!resolvedIsMain()) { /* imported for its exports — do nothing else */ } else {
+
+const canonicalText = fs.readFileSync(path.join(DIR, CANONICAL), 'utf8');
+const { frontmatter: canonicalFrontmatter, body: canonicalBody } = splitFrontmatter(canonicalText);
+if (!canonicalFrontmatter) {
+  process.stderr.write(`[commands] ${CANONICAL} has no frontmatter — refusing to generate from it\n`);
+  process.exit(2);
+}
+
+const drift = [];
+let wrote = 0;
+for (const alias of ALIASES) {
+  const file = path.join(DIR, alias);
+  if (!fs.existsSync(file)) { drift.push(`${alias} (missing)`); continue; }
+  const before = fs.readFileSync(file, 'utf8');
+  const after = rebuild(before, canonicalFrontmatter, canonicalBody);
+  if (after === before) continue;
+  if (CHECK) { drift.push(alias); continue; }
+  fs.writeFileSync(file, after);
+  process.stdout.write(`[commands] ${alias}: body regenerated from ${CANONICAL}\n`);
+  wrote += 1;
+}
+
+if (CHECK) {
+  if (drift.length) {
+    process.stderr.write(
+      `[commands] DRIFT: ${drift.length} alias(es) disagree with ${CANONICAL}. A user who types one\n`
+      + '           spelling would get different behaviour from one who types another, on the command\n'
+      + '           that promises spelling does not matter. Run: node scripts/sync-commands.mjs\n',
+    );
+    for (const d of drift) process.stderr.write(`    ${d}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`[commands] all ${ALIASES.length} alias(es) share ${CANONICAL}'s body\n`);
+  process.exit(0);
+}
+process.stdout.write(`[commands] synced ${wrote} alias(es) to ${CANONICAL}\n`);
+}