@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/device-flow-help.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/device-flow-help.js — the one explanation of a Device-Flow refusal, shared
+// by `bongos setup` and `bongos login` (task 1003881).
+//
+// WHY IT EXISTS AT ALL. GitHub creates an App from a manifest with Device Flow OFF and
+// exposes no API to switch it on — only a checkbox in the App's settings. So on every
+// wizard-born instance the documented terminal sign-in is hard-broken from birth, for
+// every builder, until the owner ticks that box. Nothing in the product can do it for
+// them; the least we can do is say so precisely, and name a route that works meanwhile.
+//
+// WHY IT IS ITS OWN FILE. setup.js grew the detector + the guidance first; login.js threw
+// a bare "could not start sign-in (HTTP 424)" — a dead end sitting directly downstream of
+// the CLI's OWN wrong-instance advice to run `bongos login`. setup.js already requires
+// login.js for runDeviceFlow, so having login.js require setup.js back would close a
+// require cycle. Both now depend on this leaf instead: one source of truth, no cycle.
+//
+// PURE — no fs, no network, no process state; both functions unit-test standalone.
+
+// Does this /auth/device/start response carry GitHub's device_flow_disabled refusal?
+//
+// Matches on TEXT, not status, deliberately: the CLI talks to many core versions, and the
+// server envelope moved from 502 to 424 (a 502 body was being eaten by the CDN). Both
+// register. Must NOT match auth_not_configured or any other upstream failure — those have
+// different cures, and a wrong cure is worse than a generic error.
+function isDeviceFlowDisabled(start) {
+  if (!start || start.ok) return false;
+  const err = start.data && start.data.error;
+  const text = [
+    typeof err === 'string' ? err : '',
+    err && typeof err === 'object' ? `${err.code || ''} ${err.message || ''}` : '',
+    start.data && start.data.message ? String(start.data.message) : '',
+  ].join(' ');
+  return /device_flow_disabled/i.test(text);
+}
+
+// The plain-language guidance: what happened, the web route that works RIGHT NOW, and the
+// owner's one-checkbox repair. Returns an array of lines (the callers join them).
+//
+// `finish` names the caller, because only the closing move differs: setup prompts for the
+// token inline ("paste it below"), login has no such prompt and must tell you to run the
+// one-liner instead. Everything above that step is genuinely shared and stays shared.
+function deviceFlowFallbackLines(base, { finish = 'setup' } = {}) {
+  const settings = `${base}/builders/settings`;
+  const close = finish === 'login'
+    ? [
+      '  3. Copy the one-liner it shows and run it in this shell — that writes',
+      '     the same session `bongos login` would have.',
+    ]
+    : [
+      '  3. Copy the token it shows and paste it below (or run the printed',
+      '     one-liner in another shell, then re-run setup).',
+    ];
+  return [
+    '',
+    "This project's GitHub App has Device Flow switched off, so terminal sign-in",
+    'cannot start. Apps created by the one-click setup begin this way — GitHub',
+    'only offers the switch as a checkbox in the App settings; no setup flow can',
+    'tick it automatically.',
+    '',
+    'Sign in through the web instead (works right now):',
+    `  1. Open ${settings} and sign in with GitHub.`,
+    '  2. Under "CLI Access", click "Re-issue CLI token".',
+    ...close,
+    '',
+    'To repair terminal sign-in for everyone (the project owner, once):',
+    '  GitHub → Settings → Developer settings → GitHub Apps → your app →',
+    '  check "Enable Device Flow" → Save. Web sign-in is unaffected either way.',
+  ];
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines };

package/scripts/bongos/diagnose-achievements.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict';
+
+// diagnose-achievements.js — for each builder, evaluate every achievement
+// against CURRENT state and compare to what's actually unlocked. A row where the
+// builder is eligible but the achievement is locked is a bug (a missed unlock).
+//
+// The eligibility predicates are NOT redefined here. They live ONCE in
+// modules/economy/achievements.js (STATE_EVALUATORS) and are imported below, so
+// this diagnostic, the backfill (--apply), and the live reconcile-at-ship can
+// never drift apart — the exact failure that silently broke gds-shipper when the
+// rename left stale `src/pms/` copies in three places (idea 44 / idea 50).
+//
+// Must run on the droplet (uses local Postgres via peer auth) — or with PG*
+// env vars set to point at a remote host. A CLI may require a module directly
+// (the memory/grading-carve precedent).
+//
+// Usage:
+//   # report only (exit 1 if any builder has a missed unlock — a smoke check):
+//   ssh <user>@<db-host> 'cd ~/<instance> && node scripts/bongos/diagnose-achievements.js'
+//   # backfill: actually unlock every missed achievement (idempotent), then report:
+//   ssh <user>@<db-host> 'cd ~/<instance> && node scripts/bongos/diagnose-achievements.js --apply'
+
+const { pool } = require('../../src/bongos/pool');
+const {
+  STATE_EVALUATORS,
+  reconcileBuilderAchievements,
+} = require('../../modules/economy/achievements');
+
+const APPLY = process.argv.includes('--apply');
+
+// --apply: backfill missed unlocks for every builder, reusing the SAME
+// reconcile the ship path runs. Each builder in its own txn so one odd builder
+// can't roll back the rest. Idempotent — re-running unlocks nothing new.
+async function backfill() {
+  const builders = await pool.query('SELECT id, github_login FROM builders ORDER BY id');
+  let totalUnlocked = 0;
+  for (const builder of builders.rows) {
+    const builderId = Number(builder.id);
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const unlocked = await reconcileBuilderAchievements(client, builderId, {});
+      await client.query('COMMIT');
+      if (unlocked.length > 0) {
+        totalUnlocked += unlocked.length;
+        console.log(
+          `#${builderId} ${builder.github_login}: unlocked ${unlocked.map((u) => u.id).join(', ')}`
+        );
+      }
+    } catch (err) {
+      await client.query('ROLLBACK').catch(() => {});
+      console.error(`#${builderId} ${builder.github_login}: reconcile failed — ${err.message}`);
+    } finally {
+      client.release();
+    }
+  }
+  console.log('');
+  console.log(`Backfill complete. Newly unlocked: ${totalUnlocked}`);
+}
+
+async function main() {
+  if (APPLY) {
+    await backfill();
+  }
+
+  const builders = await pool.query('SELECT id, github_login FROM builders ORDER BY id');
+  let mismatchCount = 0;
+  const rows = [];
+
+  for (const builder of builders.rows) {
+    const builderId = Number(builder.id);
+    const unlocked = await pool.query(
+      'SELECT achievement_id FROM builder_achievements WHERE builder_id = $1',
+      [builderId]
+    );
+    const unlockedSet = new Set(unlocked.rows.map((r) => r.achievement_id));
+
+    for (const ev of STATE_EVALUATORS) {
+      const wouldFire = await ev.fn(pool, builderId);
+      const currentlyUnlocked = unlockedSet.has(ev.id);
+      const mismatch = wouldFire && !currentlyUnlocked;
+      if (mismatch) mismatchCount++;
+      rows.push({
+        builder_id: builderId,
+        github_login: builder.github_login,
+        achievement_id: ev.id,
+        would_fire: wouldFire,
+        currently_unlocked: currentlyUnlocked,
+        mismatch,
+      });
+    }
+  }
+
+  // Tabular output
+  const w = (s, n) => String(s).padEnd(n);
+  console.log(w('builder', 12), w('achievement', 24), w('would_fire', 11), w('unlocked', 9), 'mismatch');
+  console.log('-'.repeat(72));
+  for (const r of rows) {
+    console.log(
+      w(`#${r.builder_id} ${r.github_login}`, 12),
+      w(r.achievement_id, 24),
+      w(r.would_fire ? 'yes' : 'no', 11),
+      w(r.currently_unlocked ? 'yes' : 'no', 9),
+      r.mismatch ? 'BUG' : '-',
+    );
+  }
+  console.log('');
+  console.log(`Mismatch count: ${mismatchCount}`);
+
+  await pool.end();
+  process.exit(mismatchCount === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error('diagnose-achievements failed:', err);
+  process.exit(2);
+});

package/scripts/bongos/diagram-facts.js

@@ -0,0 +1,355 @@
+// Shared fact-extractor for the onboarding diagrams (task #357).
+//
+// Single source of truth for "what the live system actually is", used by BOTH:
+//   - (formerly) the drift checker .claude/scheduled-tasks/diagram-drift/check.js, retired in task 1004878, which
+//     compares these facts against assertions.json and nudges on divergence; and
+//   - the generator (scripts/bongos/gen-diagrams.js), which regenerates the
+//     mechanical diagrams (.mmd) FROM these facts on every deploy.
+//
+// Keeping both on one extractor guarantees the checker and the generator can
+// never disagree about what "live" means.
+//
+// Facts:
+//   - rank enum + default + WIRED ranks  ← migrations/ + src/bongos/ (this repo)
+//   - task-status set                    ← migrations/ (tasks_status_check)
+//   - live versions                      ← production API (/public/versions)
+//   - conceptual (03 + 04) piece states  ← authenticated /tasks/:id status per
+//                                           backing task + seeded-achievement
+//                                           count from migrations/. Degrades to
+//                                           null when no session is available.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// --- comment stripping (so rank/status literals in prose don't read as wiring) ---
+// Line-based on purpose: a regex block-comment strip over concatenated files can
+// swallow real code across an unbalanced /* ... */, causing false-negatives.
+const dropComments = (s, prefixes) =>
+  s
+    .split('\n')
+    .filter((line) => {
+      const t = line.trim();
+      return !prefixes.some((p) => t.startsWith(p));
+    })
+    .join('\n');
+const stripJs = (s) => dropComments(s, ['//', '*', '/*']);
+const stripSql = (s) => dropComments(s, ['--']);
+
+// --- repo readers ---
+function readMigrations(repo) {
+  const dir = path.join(repo, 'migrations');
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+    .map((f) => ({ name: f, text: fs.readFileSync(path.join(dir, f), 'utf8') }));
+}
+
+function readGdsSource(repo) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.js')) out.push(fs.readFileSync(p, 'utf8'));
+    }
+  };
+  walk(path.join(repo, 'src/bongos'));
+  return out.join('\n');
+}
+
+// --- extractors ---
+function rankEnum(migs) {
+  // Last migration that defines `rank ... CHECK (rank IN (...))` wins.
+  for (const m of [...migs].reverse()) {
+    const block = m.text.match(/rank\s+text[\s\S]*?CHECK\s*\(\s*rank\s+IN\s*\(([\s\S]*?)\)\s*\)/i);
+    if (block) return [...block[1].matchAll(/'([a-z_]+)'/gi)].map((x) => x[1]);
+  }
+  return [];
+}
+
+function defaultRank(migs) {
+  for (const m of [...migs].reverse()) {
+    // A later migration can change the column default with ALTER COLUMN SET
+    // DEFAULT (migration 029 flipped 'thetes' -> 'xenos'). Check that first so a
+    // post-CREATE change wins over the original column definition; then fall back
+    // to the CREATE/ADD COLUMN form. Reverse iteration makes the newest win.
+    const alt = m.text.match(/ALTER\s+COLUMN\s+rank\s+SET\s+DEFAULT\s+'([a-z_]+)'/i);
+    if (alt) return alt[1];
+    const d = m.text.match(/rank\s+text\s+NOT NULL\s+DEFAULT\s+'([a-z_]+)'/i);
+    if (d) return d[1];
+  }
+  return null;
+}
+
+function wiredRanks(migs, src, enum_) {
+  const wired = new Set();
+  const code = stripJs(src);
+  const inEnum = (r) => enum_.includes(r);
+  // 1. ranks named in a requireRank(...) call (gating)
+  for (const call of code.matchAll(/requireRank\(([^)]*)\)/g)) {
+    for (const lit of call[1].matchAll(/'([a-z_]+)'/g)) if (inEnum(lit[1])) wired.add(lit[1]);
+  }
+  // 2. column default
+  const def = defaultRank(migs);
+  if (def) wired.add(def);
+  // 3. rank assigned in src code, e.g. `rank = 'xenos'` (\brank avoids XENOS_RANK)
+  for (const a of code.matchAll(/\brank\s*[:=]\s*'([a-z_]+)'/gi)) if (inEnum(a[1])) wired.add(a[1]);
+  // 4. ranks SET by a migration
+  for (const m of migs) {
+    for (const s of stripSql(m.text).matchAll(/SET\s+rank\s*=\s*'([a-z_]+)'/gi)) {
+      if (inEnum(s[1])) wired.add(s[1]);
+    }
+  }
+  // 5. ranks that appear as keys in the live tier table REQUIRES_RANK_TIER
+  //    (db.js) — that map enumerates exactly the ranks the claim-gate can
+  //    compare, so membership there IS wiring. Catches ranks promoted to via a
+  //    parameterized `SET rank = $n` (e.g. thetes auto-graduation, #692) that
+  //    the literal-assignment rule above can't see.
+  const tierMap = code.match(/REQUIRES_RANK_TIER\s*=\s*\{([^}]*)\}/);
+  if (tierMap) {
+    for (const k of tierMap[1].matchAll(/([a-z_]+)\s*:/gi)) if (inEnum(k[1])) wired.add(k[1]);
+  }
+  return [...wired];
+}
+
+function taskStatuses(migs) {
+  for (const m of [...migs].reverse()) {
+    if (/tasks_status_check/i.test(m.text)) {
+      const block = m.text.match(/tasks_status_check[\s\S]*?status\s+IN\s*\(([\s\S]*?)\)/i);
+      if (block) return [...block[1].matchAll(/'([a-z_]+)'/g)].map((x) => x[1]);
+    }
+  }
+  for (const m of migs) {
+    const block = m.text.match(/status\s+text[\s\S]*?CHECK\s*\(\s*status\s+IN\s*\(([\s\S]*?)\)/i);
+    if (block) return [...block[1].matchAll(/'([a-z_]+)'/g)].map((x) => x[1]);
+  }
+  return [];
+}
+
+async function liveVersions() {
+  const { cliClient } = require('./cli-lib');
+  const api = await cliClient();
+  const r = await api.public.getPublicVersions();
+  if (!r.ok) throw new Error(`public/versions failed: ${r.status}`);
+  // started_at is carried for chronological ordering in the generator; the drift
+  // checker compares only id/status, so the extra field is harmless there.
+  return (r.data.versions || []).map((v) => ({
+    id: v.id,
+    status: v.status,
+    started_at: v.started_at || null,
+  }));
+}
+
+// --- conceptual-diagram facts (03-drachmae-karma, 04-architecture) ----------
+//
+// Both conceptual diagrams reduce to the same shape: a feature-piece is LIVE iff
+// its backing GDS task is 'shipped'. We fetch the live status of every task id
+// the two diagrams reference (authenticated, since /tasks/:id is not public) and
+// the count of seeded achievements (for 03's "N seeded" label).
+//
+// The task ids below are the ORIGIN instance's live GDS ids (verified
+// 2026-05-30), NOT the seed refs — the V3 renumber (migration 021) made
+// seed-ref R##s diverge from live ids in a couple of places (so a source_ref
+// lookup would be unreliable). On an instance that imported the origin backlog
+// under new ids they resolve through the IMPORT_ID_OFFSETS probe below.
+//
+// In particular the bounty-AWARDING gate is the "auto-confirmation flow that
+// awards drachmae" task (#286 / live ref R67), not the security-ADR-stub task
+// that the old hand-authored .mmd loosely called "R68" (#287). Each entry
+// documents the piece it drives.
+const CONCEPTUAL_TASK_IDS = {
+  // 04-architecture (the MEMORY layer) — ADR 0024 cloneable-memory chain.
+  273: 'R54 — builder_memory store schema',
+  274: 'R55 — sync-on-ship (push)',
+  275: 'R56 — pull-on-session-start',
+  276: 'R57 — per-builder isolation + forensic read at Metic+ (ADR 0157)',
+  // 03-drachmae-karma — bounty.
+  284: 'R65 — bounty payout rate card (src/bongos/security.js + /builders)',
+  286: 'R67 — auto-confirmation flow that awards drachmae (the awarding gate)',
+  282: 'R63 — vulnerability_reports table + schema',
+  // 03-drachmae-karma — karma.
+  245: 'R25 — builder-on-builder upvote/downvote on confirmed work',
+  248: 'R32 — karma boost on proposal ratification',
+  246: 'R26 — karma surfaced on profile + sortable on leaderboard',
+};
+
+// 04-architecture (the ship flow) — how code on a builder's machine reaches
+// prod. Same "LIVE iff its backing GDS task is 'shipped'" contract as the memory
+// chain above. Each entry documents the piece it drives in
+// scripts/bongos/gen-diagrams.js `architectureMmd`:
+//   1025 — server-mediated branch publish (a checkout with no GitHub push
+//          credential uploads a bundle, the server pushes it)
+//   1028 — replaced the standing push PAT with a GitHub App (now SHIPPED)
+//
+// Every id here MUST drive a piece of the diagram. An id no consumer reads is
+// not merely dead weight: conceptualFacts() below degrades the WHOLE bundle to
+// null the moment any single id is unreachable, so an unused id can silently
+// stop 03 + 04 from regenerating at all (the failure shape task 1002667 fixed
+// for the offset case). Do NOT re-add 859 (CI self-deploy): the deploy leg is
+// the standalone AUTO-PULL of ADR 0108/0129, not a task-gated Actions job, so
+// gen-diagrams.js deliberately excludes it — see its comment at `ship flow`.
+// Removed in task 1002674.
+const SHIP_FLOW_TASK_IDS = {
+  1025: 'server-mediated branch publish (a checkout with no push credential uploads a bundle, the server pushes)',
+  1028: 'GitHub App hardening (replace the standing push PAT)',
+};
+
+// Count of distinct achievement ids seeded across all migrations. There is no
+// public achievements endpoint, so we read the seed INSERTs directly — the
+// cheapest reliable source. Distinct on id so a later migration that UPSERTs an
+// existing achievement (e.g. 031 corrects streak-3/streak-7) doesn't double-count.
+function seededAchievementCount(migs) {
+  const ids = new Set();
+  for (const m of migs) {
+    // Only scan the achievements seed blocks; an INSERT row looks like
+    //   ('first-ship', 'First Ship', ...
+    // We key off the INSERT INTO achievements header so we don't pick up
+    // id-shaped literals elsewhere in the file, and terminate the block at the
+    // trailing ON CONFLICT / statement-end. We deliberately do NOT terminate on
+    // the first ';' — a description string can legitimately contain one (e.g.
+    // "Hold two simultaneous claims; ship both successfully."), which would
+    // truncate the VALUES block and undercount.
+    const re = /INSERT\s+INTO\s+achievements\s*\([^)]*\)\s*VALUES([\s\S]*?)(?:\bON\s+CONFLICT\b|;\s*(?:--|$|\n\s*(?:INSERT|UPDATE|ALTER|CREATE)))/gi;
+    let block;
+    while ((block = re.exec(m.text)) !== null) {
+      // Each row's id is the first quoted literal after the row's opening paren.
+      for (const row of block[1].matchAll(/\(\s*'([a-z0-9-]+)'\s*,/gi)) ids.add(row[1]);
+    }
+  }
+  return ids.size;
+}
+
+// Repo slug ("github.com/owner/repo") for 04's REPO node.
+//
+// Sourced from the BRANDING CONTRACT (`repo: { owner, name }`), never from the
+// git `origin` remote. Reading git was the original design (task #357) and it
+// did satisfy the rule it was written for — keep builder identity out of
+// implementation code (audit-authorship.sh) — but it only moved the identity
+// from the source into the GENERATED file, which is committed AND published.
+// The portable core carries no branding.json, so `origin` there is always some
+// real person's fork and every regeneration wrote that login into
+// docs/onboarding/diagrams/04-architecture.mmd and shipped it in the core
+// package. That is task 1003911: the one leak the task 1003869 sweep could not
+// hold, because a generator puts it back the moment anyone regenerates.
+//
+// Branding fails to neutral by construction, which is the whole point: an unset
+// `repo` yields the placeholder, so the portable core renders a placeholder and
+// a host instance that declares its own repo renders its own. Every other
+// identity string in these diagrams already follows exactly this rule — see
+// `brand()` in gen-diagrams.js, whose header states it for the currency, the
+// world/product name and the public host.
+function repoSlug() {
+  let b = {};
+  try { b = require('../../src/branding').branding() || {}; } catch (_) { /* fail-to-neutral */ }
+  const r = (b && b.repo) || {};
+  const owner = typeof r.owner === 'string' ? r.owner.trim() : '';
+  const name = typeof r.name === 'string' ? r.name.trim() : '';
+  // Both halves or neither — a half-filled pack must not render "owner/".
+  // null, not a placeholder string: the CALLER owns the prose, so a neutral
+  // instance can drop the clause entirely instead of rendering a parenthetical
+  // that restates the label it sits inside.
+  return owner && name ? `github.com/${owner}/${name}` : null;
+}
+
+// An instance that IMPORTED the origin backlog renumbers the origin tasks by a
+// uniform offset (the reference import renumbered +1000000: origin 276 → live
+// 1000276), so the origin ids above 404 there and every conceptual regen
+// silently degraded to the null sentinel (task 1002667). Probe each id at these
+// offsets, origin-first; the first offset that resolves LOCKS for the rest of
+// the bundle — a uniform renumber can't mix offsets, and locking means a
+// coincidental id collision on a foreign instance degrades to the sentinel
+// instead of blending statuses from two different task sets.
+const IMPORT_ID_OFFSETS = [0, 1_000_000];
+
+// Fetch live status for each conceptual task id. Authenticated (allow-unauth so
+// a 401 returns a sentinel instead of exiting the whole process via cli-lib's
+// guidance path). Ids resolve through the IMPORT_ID_OFFSETS probe but the
+// returned map stays keyed by the ORIGIN ids, so the templates, assertions.json,
+// and the drift checker all keep one stable key set. Returns null on ANY failure
+// (no session, network, non-200) so the generator can SKIP regenerating 03/04
+// rather than emit wrong data.
+async function conceptualFacts({ repo, migs, api }) {
+  // Reuse the caller's migrations read when provided (gatherFacts already reads
+  // them once); only fall back to a fresh read for standalone callers.
+  migs = migs || readMigrations(repo);
+  if (!api) {
+    const { cliClient } = require('./cli-lib');
+    // allow-unauth so a 401 returns a sentinel instead of exiting the whole
+    // process via cli-lib's guidance path (see the loop's degrade-to-null below).
+    api = await cliClient({ allowUnauthenticated: true });
+  }
+  // 03's pieces + 04-architecture's memory chain + its ship-flow pieces
+  // share one fetch + one taskStatus map; any unreachable id degrades the WHOLE
+  // conceptual bundle (so 03 + 04 skip together rather than emit partial data).
+  const ALL_TASK_IDS = { ...CONCEPTUAL_TASK_IDS, ...SHIP_FLOW_TASK_IDS };
+  const ids = Object.keys(ALL_TASK_IDS).map(Number);
+  const status = {};
+  let lockedOffset = null;
+  for (const id of ids) {
+    let s = null;
+    const offsets = lockedOffset === null ? IMPORT_ID_OFFSETS : [lockedOffset];
+    for (const off of offsets) {
+      try {
+        const r = await api.tasks.getTasksId({ id: id + off });
+        if (r.ok) {
+          // A 200 means this id exists at this offset — accept it and stop
+          // probing (a missing status field still degrades below).
+          s = (r.data.task || r.data).status || null;
+          if (s !== null) lockedOffset = off;
+          break;
+        }
+      } catch (_) {
+        s = null;
+      }
+    }
+    if (s === null) {
+      // Any unreachable id degrades the whole conceptual bundle — partial data
+      // could flip a piece to the wrong state. Bail to the sentinel.
+      return null;
+    }
+    status[id] = s;
+  }
+  return {
+    taskStatus: status,
+    taskLabels: { ...ALL_TASK_IDS },
+    achievementsSeeded: seededAchievementCount(migs),
+    repoSlug: repoSlug(),
+  };
+}
+
+// --- convenience: gather everything ---
+async function gatherFacts({ repo }) {
+  const migs = readMigrations(repo);
+  const src = readGdsSource(repo);
+  const enum_ = rankEnum(migs);
+  return {
+    rank_enum: enum_,
+    default_rank: defaultRank(migs),
+    wired_ranks: wiredRanks(migs, src, enum_),
+    task_statuses: taskStatuses(migs),
+    versions: await liveVersions(),
+    // Conceptual-diagram facts (03 + 04). null = degraded (no session / API
+    // unreachable) → the generator SKIPS regenerating the conceptual diagrams.
+    conceptual: await conceptualFacts({ repo, migs }),
+  };
+}
+
+module.exports = {
+  stripJs,
+  stripSql,
+  readMigrations,
+  readGdsSource,
+  rankEnum,
+  defaultRank,
+  wiredRanks,
+  taskStatuses,
+  liveVersions,
+  seededAchievementCount,
+  repoSlug,
+  conceptualFacts,
+  CONCEPTUAL_TASK_IDS,
+  SHIP_FLOW_TASK_IDS,
+  IMPORT_ID_OFFSETS,
+  gatherFacts,
+};

package/scripts/bongos/discord-channels.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+
+// Archon CLI for bot-managed Discord channels (ADR 0037, task #727).
+//
+// Thin wrapper over the HTTP API so the rank gate stays SERVER-SIDE: the
+// /discord/channels/* routes re-check the caller's live builders.rank with
+// requireRank('archon'). A non-Archon session gets a 403 here, exactly as it
+// would from any other privileged command. This script never talks to Discord
+// directly — it asks the deployed bot (via the API) to do the work.
+//
+// Usage:
+//   node scripts/bongos/discord-channels.js plan      # dry run: what WOULD change
+//   node scripts/bongos/discord-channels.js apply     # apply docs/discord/channels.json to Discord
+//   node scripts/bongos/discord-channels.js snapshot  # print the guild AS channels.json (seed the file)
+//
+// The channel layout itself is edited in docs/discord/channels.json and merged
+// (rank-gated) — this command just triggers the reconcile.
+
+const { cliClient } = require('./cli-lib');
+
+async function main() {
+  const cmd = (process.argv[2] || '').toLowerCase();
+  if (cmd !== 'plan' && cmd !== 'apply' && cmd !== 'snapshot') {
+    console.error('usage: node scripts/bongos/discord-channels.js <plan|apply|snapshot>');
+    process.exit(2);
+  }
+
+  const api = await cliClient();
+  let res;
+  if (cmd === 'plan') {
+    res = await api.discord.getDiscordChannelsPlan();
+  } else if (cmd === 'snapshot') {
+    res = await api.discord.getDiscordChannelsSnapshot();
+  } else {
+    res = await api.discord.postDiscordChannelsReconcile({ body: {} });
+  }
+
+  const body = res.data || {};
+  if (res.status === 403) {
+    console.error('Refused: channel commands are Archon-only (your live rank is not archon).');
+    process.exit(1);
+  }
+  if (res.status === 503) {
+    console.error(`Bot unavailable (${body.reason}). The bot must be enabled (DISCORD_BOT_ENABLED) and connected to the guild.`);
+    process.exit(1);
+  }
+  if (res.status < 200 || res.status >= 300) {
+    console.error(`API error ${res.status}:`, JSON.stringify(body));
+    process.exit(1);
+  }
+
+  // Warnings go to STDERR so `snapshot > channels.json` writes clean JSON.
+  for (const w of body.warnings || []) console.warn(`warning: ${w}`);
+  if (cmd === 'snapshot') {
+    // STDOUT is the file body and nothing else — this command exists to be
+    // redirected. Review the diff before committing: it is the guild's real
+    // state, which is not necessarily the state anyone intended.
+    console.log(JSON.stringify(body.config, null, 2));
+    return;
+  }
+  if (cmd === 'plan') {
+    const ops = body.ops || [];
+    if (!ops.length) { console.log('In sync — no channel changes needed.'); return; }
+    console.log(`${ops.length} change(s) the bot would apply:`);
+    for (const op of ops) {
+      const bits = [op.op, op.name];
+      if (op.topic !== undefined) bits.push('(topic)');
+      if (op.overwrites !== undefined) bits.push('(perms)');
+      console.log('  - ' + bits.join(' '));
+    }
+  } else {
+    console.log(`Applied ${body.applied}/${body.total} change(s); ${body.failed} failed.`);
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });