@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/audit-deps.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// scripts/bongos/audit-deps.js — likely-missing-dependency detector CLI (task 349).
+//
+// WHY: an under-specified dependencies[] lets work start before the task it
+// implicitly builds on has shipped, racing already-built work (the original
+// motivation: task 307 was claimable before the rank system it needed had
+// shipped). This surfaces OPEN tasks whose touches[] overlap an UNSHIPPED task
+// they do NOT already depend on — candidate missing edges for a human to triage.
+//
+// THIS IS ADVISORY. Most touches[] overlaps are PARALLEL work on a shared surface
+// (src/bongos/db.js, migrations/, CLAUDE.md, …), NOT a build-order dependency.
+// Backfilling a wrong edge GATES the dependent (POST /claims → 409
+// DEPS_NOT_SHIPPED) until the named blocker ships. So: act only on `high`
+// confidence, by hand, after reading both task descriptions.
+//
+// PURE CORE MOVED to modules/lifecycle/missing-dep-classify.js (task 1002827),
+// so dependency-advisory.js's live POST /tasks path can reuse the ONE canonical
+// `classify`/`findMissingDeps` — the same one tests/audit_deps.mjs covers —
+// without pulling this file's CLI-only machinery (cliClient's session-token
+// I/O, resolveDefaultVersion) into the running server. This file is now the
+// CLI wrapper only: argv parsing, the corpus fetch, and --stranded's dead-edge
+// report. Every name below is RE-EXPORTED unchanged so no caller of this file
+// (including tests/audit_deps.mjs) needs to know it moved.
+//
+//   node scripts/bongos/audit-deps.js [--version GDS-V3] [--min high|medium|low] [--json]
+//   node scripts/bongos/audit-deps.js --stranded [--json]   # the INVERSE: dead edges (task 1003153),
+//                                                      # plus prose-declared gates naming a dead task (task 1003857, advisory)
+
+const { cliClient } = require('./cli-lib');
+const { resolveDefaultVersion } = require('./version-select.js');
+// task 1003153 — the DEAD-edge detector core, shared with the claim refusal so
+// "abandoned dependency" means one thing across the CLI, the route and this audit.
+const { findStrandedTasks, findProseGatedTasks } = require('../../modules/lifecycle/dead-deps.js');
+// task 1003752 — the route's page bound + the first-page offset rule, declared once.
+const { TASK_LIST_MAX_LIMIT, buildTaskPageQuery } = require('../../modules/lifecycle/task-list-limits.js');
+const { OPEN, isUnshippedBlocker, HOTSPOTS, classify, findMissingDeps } =
+  require('../../modules/lifecycle/missing-dep-classify.js');
+
+// Read the WHOLE task corpus, one allowed page at a time (task 1003752). This
+// was a single `limit: 3000` read, which GET /tasks caps at TASK_LIST_MAX_LIMIT
+// (1000) — so it 400'd on every run and the detector below never saw a single
+// task. Paging is not a nicety here: the corpus passed one page long ago (3610
+// rows on 2026-09-16), so even a legal `limit: 1000` would silently UNDER-read,
+// which in a detector is the same failure wearing a success exit code.
+//
+// `getPage(query)` is injected rather than closed over so the loop is testable
+// with no API; it returns the { ok, status, data } shape cliClient gives back.
+// Dedupes by id: listTasks orders by `priority NULLS LAST, created_at, id`, so
+// pages are stable — but a detector whose whole job is surfacing rows nobody
+// can see must not be the thing that loses one.
+async function fetchAllTasks(getPage, { query = {}, pageSize = TASK_LIST_MAX_LIMIT, maxPages = 100 } = {}) {
+  const byId = new Map();
+  let offset = 0;
+  for (let page = 0; page < maxPages; page++) {
+    const q = buildTaskPageQuery({ ...query, limit: pageSize, offset });
+    const r = await getPage(q);
+    if (!r || !r.ok) throw new Error(`HTTP ${r && r.status}`);
+    const rows = (r.data && r.data.tasks) || [];
+    for (const t of rows) byId.set(String(t.id), t);
+    // A short page is the end of the table. Compare against the CLAMPED size
+    // the route actually honoured, never the size the caller asked for.
+    if (rows.length < q.limit) return [...byId.values()];
+    offset += q.limit;
+  }
+  throw new Error(`more than ${maxPages} pages of tasks — refusing to loop forever`);
+}
+// --stranded (task 1003153): the INVERSE audit. findMissingDeps asks "which edge
+// is MISSING"; this asks "which existing edge is DEAD" — a live task gated by an
+// ABANDONED dependency. That edge can never satisfy (an abandoned task can never
+// ship), so the dependent never auto-promotes and can never be claimed: stranded,
+// not waiting. Per the owner ruling (2026-08-21) the gates stay strict, which
+// makes this detector the remedy — an abandoned dependency must be REPORTED as a
+// top-priority thing to resolve rather than blocking silently and forever.
+// Exits 1 when anything is stranded, so a sweep or CI leg can gate on it.
+async function reportStranded({ asJson }) {
+  const api = await cliClient();
+  let all;
+  try {
+    all = await fetchAllTasks((query) => api.tasks.getTasks({ query }), { query: { include: 'deps' } });
+  } catch (e) {
+    console.error(`audit-deps: could not list tasks (${e.message})`);
+    process.exit(1);
+  }
+  const stranded = findStrandedTasks(all);
+  // task 1003857: the same question asked of PROSE. The structured graph above
+  // reads blocked_by edges; a gate written in a description is unpoliced, and stales
+  // identically — task 1002839 told a builder to coordinate with "existing open task
+  // 1001380", abandoned since 2026-08-18. Reported HERE rather than in a second tool
+  // so there is one answer to "what is stranded".
+  const statusById = (() => {
+    const byId = new Map(all.map((t) => [String(t.id), String(t.status)]));
+    return (id) => byId.get(String(id)) || null;
+  })();
+  const proseGated = findProseGatedTasks(all, statusById);
+
+  // Context worth stating even at zero: abandoned tasks that still CARRY
+  // dependents are the latent trap. They report clean only because every
+  // dependent happens to be terminal too — one promote would light them up.
+  const gatingAbandoned = new Set();
+  for (const t of all) for (const d of (t.blocked_by || [])) {
+    if (String(d.status) === 'abandoned') gatingAbandoned.add(String(d.id));
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ stranded, prose_gated: proseGated, abandoned_deps_with_dependents: [...gatingAbandoned] }, null, 2));
+    // ADVISORY: a prose match never changes the exit code. It is weaker evidence than
+    // an edge — the text may be history, a citation, or simply wrong — so it reports
+    // candidates for a human and must not gate a sweep or a CI leg.
+    return stranded.length ? 1 : 0;
+  }
+  console.log(`audit-deps --stranded: ${all.length} task(s) scanned — ${stranded.length} LIVE task(s) stranded by an abandoned dependency\n`);
+  for (const s of stranded) {
+    console.log(`[STRANDED] #${s.task_id} [${s.status}]  ${(s.title || '').slice(0, 70)}`);
+    for (const d of s.dead_deps) console.log(`           dead edge → #${d.id} [${d.status}]  ${(d.title || '').slice(0, 60)}`);
+    console.log(`           fix: drop the edge (DELETE /dependencies {"from_kind":"task","from_id":${s.task_id},"to_kind":"task","to_id":${s.dead_deps[0].id}})`);
+    console.log(`             or restore the dep (POST /tasks/${s.dead_deps[0].id}/promote)\n`);
+  }
+  if (proseGated.length) {
+    console.log(`Prose-declared gates naming a dead task: ${proseGated.length} (ADVISORY — a human reads these; they never gate a claim)\n`);
+    for (const p of proseGated) {
+      console.log(`[PROSE]    #${p.task_id} [${p.status}]  ${(p.title || '').slice(0, 70)}`);
+      for (const d of p.prose_dead_deps) console.log(`           body names → #${d.id} [${d.status}]`);
+      console.log('           fix: correct the sentence (PATCH /tasks/' + p.task_id + ' {"description":…}), or promote the named task if the gate is real\n');
+    }
+  }
+  if (!stranded.length) {
+    console.log('Nothing stranded — no live task is gated by an abandoned dependency.');
+    console.log(`Latent exposure: ${gatingAbandoned.size} abandoned task(s) still carry dependents; they read clean only`);
+    console.log('because those dependents are themselves terminal. Promoting one would strand it immediately.');
+  }
+  return stranded.length ? 1 : 0;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--stranded')) {
+    process.exitCode = await reportStranded({ asJson: argv.includes('--json') });
+    return;
+  }
+  // task 1003166 (G02): the default was 'GDS-V3', which has shipped — so a bare
+  // `audit-deps` audited a closed version and reported nothing useful.
+  const ver = argv.includes('--version')
+    ? argv[argv.indexOf('--version') + 1]
+    : await resolveDefaultVersion();
+  if (!ver) {
+    console.error('audit-deps: no version is building; pass --version <id>.');
+    process.exitCode = 1;
+    return;
+  }
+  const minRank = argv.includes('--min') ? argv[argv.indexOf('--min') + 1] : 'low';
+  const asJson = argv.includes('--json');
+  const order = { high: 3, medium: 2, low: 1 };
+
+  const api = await cliClient();
+  const r = await api.tasks.getTasks({ query: { version: ver } });
+  if (!r.ok) { console.error(`audit-deps: could not list tasks (${r.status})`); process.exit(1); }
+  const all = r.data.tasks || [];
+  const openTasks = all.filter((t) => OPEN.has(t.status) && Array.isArray(t.touches) && t.touches.length);
+
+  // dependencies[] lives in a join table, not the task row — hydrate per open task.
+  for (const t of openTasks) {
+    const dr = await api.tasks.getTasksIdDependencies({ id: t.id });
+    t.dependencies = dr.ok ? (dr.data.dependencies || []).map((d) => String(d.id)) : [];
+  }
+  const byId = new Map(all.map((t) => [String(t.id), t]));
+  // Feed the FULL task set (open + others) so blockers in any status are visible.
+  const edges = findMissingDeps([...openTasks, ...all.filter((t) => !OPEN.has(t.status))])
+    .filter((e) => order[e.confidence] >= (order[minRank] || 1))
+    .sort((a, b) => order[b.confidence] - order[a.confidence]);
+
+  if (asJson) { console.log(JSON.stringify(edges, null, 2)); return; }
+  console.log(`audit-deps: ${ver} — ${openTasks.length} open task(s) audited, ${edges.length} candidate edge(s) >= ${minRank}\n`);
+  for (const e of edges) {
+    const t = byId.get(String(e.task_id)) || {};
+    const o = byId.get(String(e.dep_id)) || {};
+    console.log(`[${e.confidence.toUpperCase().padEnd(6)}] #${e.task_id} should-maybe-depend-on #${e.dep_id} [${e.dep_status}]`);
+    console.log(`         from: ${(t.title || '').slice(0, 70)}`);
+    console.log(`         dep : ${(o.title || '').slice(0, 70)}`);
+    console.log(`         on  : ${e.paths.join(', ')}\n`);
+  }
+  if (!edges.length) console.log('No candidate missing dependencies at this confidence — the graph is clean here.');
+  console.log('NB: advisory only. Backfill `high` edges by hand (POST /tasks/:id/dependencies) after reading both tasks; a wrong edge gates the dependent.');
+}
+
+module.exports = { findMissingDeps, classify, OPEN, isUnshippedBlocker, HOTSPOTS, reportStranded, fetchAllTasks };
+
+if (require.main === module) {
+  main().catch((e) => { console.error('audit-deps:', e.message); process.exit(1); });
+}

package/scripts/bongos/audit-gate.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// scripts/bongos/audit-gate.js — the dependency vulnerability gate (task 1003127,
+// goal 1000076; ADR 0180, docs/audits/ai-dev-redteam-baseline.md §3).
+//
+// Ratchet semantics, matching the goal's other budgets: a committed BASELINE
+// (config/audit-baseline.json) records the advisories that predate the gate.
+// A HIGH or CRITICAL advisory NOT in the baseline fails CI; anything below
+// high warns; a baseline entry that no longer reproduces prints a shrink nudge
+// (removing it is an ordinary PR). Fixes are explicit tasks — a blanket
+// `npm audit fix` does not even run against this tree (workspace: protocol).
+//
+// Fail contract: CLOSED on findings, OPEN on infrastructure — a registry
+// outage or unparseable audit output warns and exits 0 rather than bricking
+// every PR (the gate's job is catching new advisories, not proving uptime).
+//
+// Run:            node scripts/bongos/audit-gate.js
+// Refresh floor:  node scripts/bongos/audit-gate.js --update-baseline
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASELINE_PATH = path.join(ROOT, 'config', 'audit-baseline.json');
+const GATE_SEVERITIES = new Set(['high', 'critical']);
+
+// npm audit JSON → flat advisory findings, one per (advisory, vulnerable pkg).
+// Identity is the advisory's numeric `source` id + the package it hits — stable
+// across runs, unlike the parent-package rollups npm prints.
+function extractFindings(auditJson) {
+  const out = new Map();
+  const vulns = (auditJson && auditJson.vulnerabilities) || {};
+  for (const entry of Object.values(vulns)) {
+    for (const via of entry.via || []) {
+      if (typeof via !== 'object' || via === null || via.source == null) continue;
+      const key = `${via.source}:${via.name}`;
+      if (!out.has(key)) {
+        out.set(key, {
+          id: String(via.source),
+          name: via.name,
+          severity: String(via.severity || entry.severity || 'unknown').toLowerCase(),
+          title: via.title || '',
+        });
+      }
+    }
+  }
+  return [...out.values()].sort((a, b) => (a.name + a.id).localeCompare(b.name + b.id));
+}
+
+// Pure gate decision — exported for the hermetic test.
+function compare(currentFindings, baselineFindings) {
+  const baseKeys = new Set((baselineFindings || []).map((f) => `${f.id}:${f.name}`));
+  const curKeys = new Set(currentFindings.map((f) => `${f.id}:${f.name}`));
+  const fresh = currentFindings.filter((f) => !baseKeys.has(`${f.id}:${f.name}`));
+  return {
+    newGating: fresh.filter((f) => GATE_SEVERITIES.has(f.severity)),
+    newAdvisory: fresh.filter((f) => !GATE_SEVERITIES.has(f.severity)),
+    resolved: (baselineFindings || []).filter((f) => !curKeys.has(`${f.id}:${f.name}`)),
+  };
+}
+
+function readBaseline() {
+  try {
+    return JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8')).findings || [];
+  } catch {
+    return [];
+  }
+}
+
+function runAudit() {
+  try {
+    return execSync('npm audit --omit=dev --json', { cwd: ROOT, maxBuffer: 32 * 1024 * 1024 }).toString();
+  } catch (e) {
+    // npm audit exits 1 when advisories exist — that IS the payload.
+    if (e && e.stdout) return e.stdout.toString();
+    throw e;
+  }
+}
+
+function main() {
+  const update = process.argv.includes('--update-baseline');
+  let findings;
+  try {
+    findings = extractFindings(JSON.parse(runAudit()));
+  } catch (e) {
+    console.warn(`audit-gate: WARN — npm audit did not produce parseable JSON (${e.message}); failing OPEN (infra, not findings).`);
+    process.exit(0);
+  }
+
+  if (update) {
+    fs.writeFileSync(
+      BASELINE_PATH,
+      JSON.stringify({ _comment: 'audit-gate baseline (ADR 0180): pre-existing advisories the gate tolerates. Shrink-only — remove entries as fix tasks land; never add by hand to silence a NEW advisory.', updated: null, findings }, null, 2) + '\n',
+    );
+    console.log(`audit-gate: baseline updated — ${findings.length} finding(s) recorded at ${path.relative(ROOT, BASELINE_PATH)}.`);
+    return;
+  }
+
+  const verdict = compare(findings, readBaseline());
+  for (const f of verdict.resolved) {
+    console.log(`audit-gate: ratchet-down available — baseline entry no longer reproduces: [${f.severity}] ${f.name} (${f.id}) ${f.title}`);
+  }
+  for (const f of verdict.newAdvisory) {
+    console.warn(`audit-gate: WARN new ${f.severity} advisory (below the gate): ${f.name} (${f.id}) ${f.title}`);
+  }
+  if (verdict.newGating.length) {
+    console.error('audit-gate: FAIL — new high/critical advisories not in the baseline:');
+    for (const f of verdict.newGating) {
+      console.error(`  [${f.severity}] ${f.name} (advisory ${f.id}) ${f.title}`);
+    }
+    console.error('Fix or pin the dependency. The baseline only records PRE-GATE debt; do not add new entries to silence this.');
+    process.exit(1);
+  }
+  console.log(`audit-gate: PASS — ${findings.length} known finding(s), 0 new at high/critical.`);
+}
+
+if (require.main === module) main();
+
+module.exports = { extractFindings, compare, GATE_SEVERITIES, BASELINE_PATH };

package/scripts/bongos/audit-rank-roles.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// scripts/bongos/audit-rank-roles.js — does the live builder roster hold ONLY the
+// four live ranks? (task 1002873)
+//
+// WHY. `migrations/023`'s CHECK on `builders.rank` still admits twelve legacy
+// values beyond the four live ranks. `governance_002_seed_and_backfill.sql`
+// backfills roles with an INNER JOIN from `builders.rank` to the four seeded
+// `governance_roles`, so a builder sitting on a legacy rank gets NO role row and
+// resolves to ZERO permissions: admitted by threshold under `requireRank`, locked
+// out of everything under the resolver. They are not told why, and nothing about
+// their account looks wrong.
+//
+// That divergence is deliberate — ADR 0151 chose fail-closed, and
+// `tests/governance_parity.mjs` asserts it is strictly a tightening. What was
+// missing is the VERIFICATION. governance_002's comment says "none exist today —
+// verified", a point-in-time manual check that nothing re-runs; the parity test
+// is DB-free by necessity (the unit gate has no Postgres) and says so in the
+// repo; and R114's live proof ran on a scratch DB holding only the four seeded
+// rank-roles, so the production roster was never queried.
+//
+// THIS IS THE RE-RUNNABLE HALF, and it is deliberately NOT fatal at boot. Idea
+// 1000622 records that trap: an assertion that throws on startup turns a data
+// problem on one instance into an outage. This is a standalone read-only script
+// for a nightly/deploy-time caller — it exits 1 so a caller can act, and nothing
+// in the server's boot path requires it.
+//
+// It reports rather than repairs, and that is a decision, not an omission:
+// rewriting somebody's rank is an authority change, and it belongs to an operator
+// who can see who the account is — not to a sweep.
+//
+//   node scripts/bongos/audit-rank-roles.js [--json] [--file-idea]
+//
+// Exit codes:
+//   0  every builder holds a live rank
+//   1  at least one builder holds a rank the governance backfill cannot match
+//   2  could not read the roster (no session / network / route absent)
+//
+// `--file-idea` is what makes this a SURFACE rather than another thing nobody
+// runs — the same shape diagram-drift/check.js uses, spawning capture.js so idea
+// filing has one implementation. Without it a nightly deterministic run that exits
+// 1 reports into a log nobody reads, which is the exact criticism this task makes
+// of the status quo.
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const { cliClient, requireSession, cliExit } = require('./cli-lib');
+const { LIVE_RANK_LADDER } = require('../../src/bongos/db-kernel.js');
+
+// findRanksWithoutRoles — the PURE half. Given roster rows and the live ladder,
+// which builders hold a rank that `governance_002`'s INNER JOIN cannot match?
+//
+// Pure + exported because this is the only altitude the repo can test: the unit
+// gate has no Postgres, which is exactly why the gap this script closes went
+// unverified for so long. A DB-free test of the decision is not a consolation
+// prize here — it is the thing that can actually run in CI.
+//
+// A row with NO rank at all counts: NULL fails the INNER JOIN the same way a
+// legacy value does, and reads as "fine" in every UI that renders a blank.
+function findRanksWithoutRoles(rows, liveRanks = LIVE_RANK_LADDER) {
+  const live = new Set(liveRanks);
+  return (Array.isArray(rows) ? rows : [])
+    .filter((b) => b && !live.has(b.rank))
+    .map((b) => ({
+      id: b.id != null ? String(b.id) : null,
+      // The login is what an operator needs to act; it is already visible to any
+      // caller authorised to read the roster, so this adds no exposure.
+      github_login: b.github_login || null,
+      rank: b.rank === undefined ? null : b.rank,
+      status: b.status || null,
+    }));
+}
+
+// summarize — the rank histogram, so a CLEAN run still says what it looked at.
+// A green check that prints nothing is indistinguishable from one that read
+// nothing, which is the failure mode this whole task is about.
+function summarize(rows) {
+  const counts = new Map();
+  for (const b of Array.isArray(rows) ? rows : []) {
+    const key = b && b.rank ? b.rank : '(none)';
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+
+// Spawn capture.js rather than POSTing here, so idea filing keeps one
+// implementation (the diagram-drift/check.js precedent). Best-effort: a failure to
+// file must not turn a successful audit into a crash — the exit code and stdout
+// still carry the finding.
+function fileIdea(offenders) {
+  const body = [
+    `${offenders.length} builder(s) hold a rank with no matching governance_roles row.`,
+    '',
+    'They resolve to ZERO permissions — admitted by rank threshold under requireRank,',
+    'refused by the permission resolver, and given no reason (ADR 0151 fail-closed).',
+    '',
+    ...offenders.map((o) => `- builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`),
+    '',
+    'Fix: move each to a live rank through the normal rank-change path, which rotates',
+    'the governance role in the same transaction. Not auto-repaired: changing a rank is',
+    'an authority decision, and a sweep is the wrong actor for it.',
+    '',
+    'Filed by scripts/bongos/audit-rank-roles.js (task 1002873).',
+  ].join('\n');
+  const tmp = path.join(os.tmpdir(), `rank-roles-audit-${process.pid}.md`);
+  try {
+    fs.writeFileSync(tmp, body, 'utf8');
+    const r = spawnSync(
+      process.execPath,
+      [path.join(__dirname, 'capture.js'),
+        `[rank-roles] ${offenders.length} builder(s) on a rank with no governance role`,
+        '--kind', 'bug', '--body-file', tmp],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 }
+    );
+    if (r.status !== 0) console.error('audit-rank-roles: capture.js failed to file the idea — the exit code above still carries the finding.');
+  } catch (e) {
+    console.error(`audit-rank-roles: could not file the idea (${(e && e.message) || e}) — the exit code above still carries the finding.`);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* best-effort */ }
+  }
+}
+
+async function main() {
+  const json = process.argv.includes('--json');
+  await requireSession();
+  const api = await cliClient();
+  const r = await api.request('GET', '/builders/roster');
+  if (!r.ok) {
+    console.error(`audit-rank-roles: could not read the roster (HTTP ${r.status}).`);
+    console.error('  Needs a session with builder.roster.read. Nothing was checked — do NOT read this as a pass.');
+    return cliExit(2);
+  }
+  // The roster query has no WHERE on `builders`, so this covers every row,
+  // INACTIVE ONES INCLUDED. That matters: a deactivated builder on a legacy rank
+  // is exactly the row a future CHECK-narrowing migration would fail to apply over.
+  const rows = (r.data && (r.data.builders || r.data.roster || r.data)) || [];
+  const offenders = findRanksWithoutRoles(rows);
+  const histogram = summarize(rows);
+
+  if (json) {
+    console.log(JSON.stringify({ checked: rows.length, live_ranks: LIVE_RANK_LADDER, histogram, offenders }, null, 2));
+    return cliExit(offenders.length ? 1 : 0);
+  }
+
+  console.log(`audit-rank-roles: ${rows.length} builder row(s) checked against the live ladder [${LIVE_RANK_LADDER.join(', ')}]`);
+  for (const [rank, n] of histogram) console.log(`  ${String(rank).padEnd(12)} ${n}`);
+  if (!offenders.length) {
+    console.log('\n✓ every builder holds a live rank — the governance backfill can match all of them.');
+    return cliExit(0);
+  }
+  console.log(`\n✗ ${offenders.length} builder(s) hold a rank with no matching governance role.`);
+  console.log('  They resolve to ZERO permissions: admitted by rank threshold, refused by the resolver,');
+  console.log('  and nothing tells them why (ADR 0151 fail-closed).');
+  for (const o of offenders) {
+    console.log(`  - builder ${o.id}${o.github_login ? ` (${o.github_login})` : ''} rank=${o.rank === null ? '(none)' : o.rank} status=${o.status || '?'}`);
+  }
+  console.log('\n  This is a BUILDER NEED, not an outage: move each to a live rank with the normal');
+  console.log('  rank-change path so the governance role rotates in the same transaction.');
+  console.log('  Deliberately not repaired here — changing a rank is an authority decision.');
+  if (process.argv.includes('--file-idea')) fileIdea(offenders);
+  return cliExit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('audit-rank-roles:', (err && err.message) || err);
+    cliExit(2);
+  });
+}
+
+module.exports = { findRanksWithoutRoles, summarize };