@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/gen-diagrams.js

@@ -1,608 +1,7 @@
 #!/usr/bin/env node
-// Onboarding-diagram generator (task #357; conceptual diagrams added #436).
-//
-// Regenerates the data-driven onboarding diagrams from LIVE facts so they stay
-// an accurate snapshot of the architecture with no human in the loop:
-//   01-task-lifecycle      ← task-status set (+ structural transitions)
-//   02-rank-ladder         ← rank enum + wired ranks + default
-//   05-versioning          ← live versions (id/status)
-//   03-drachmae-karma      ← per-piece backing-task status + seeded-achievement count
-//   04-architecture        ← per-piece backing-task status: the ADR 0024 memory
-//                            chain + the machine → prod ship flow, in one
-//                            "complete architecture" map (consolidated under
-//                            task 1059)
-//
-// It writes each .mmd from a template, renders the SVG (crisp, pannable) + PNG
-// (fallback) via scripts/render-diagrams.sh, and rewrites the data-driven slices
-// of assertions.json so the drift checker agrees. As of ADR 0110 pt.3 (task 2027)
-// the .svg/.png renders are GITIGNORED and regenerated at DEPLOY (deploy-prod.sh
-// runs render-diagrams.sh against the tracked .mmd, using the host's installed
-// Chrome); only the .mmd + assertions.json are tracked. So ship.js runs this with
-// --no-render (sources only) — pass --no-render anywhere a headless browser is
-// absent or the renders aren't wanted in the working tree.
-//
-// The 2 CONCEPTUAL diagrams (03-drachmae-karma, 04-architecture) used to be
-// hand-authored and only flagged on drift. As of #436 they are auto-generated
-// too: each feature-piece is LIVE iff its backing Bongos task is 'shipped', so their
-// LIVE/PLANNED labels + edge styles are driven by live data and never need a
-// hand-fix. CAVEAT — they reduce to the AUTHENTICATED /tasks/:id status, so when
-// no Bongos session is available (headless run, no creds) facts.gatherFacts returns
-// conceptual=null and this generator SKIPS 03/04 (leaving the files untouched)
-// rather than emit wrong data. The 3 mechanical diagrams have no such dependency
-// and always regenerate. The drift checker remains as a belt-and-braces backstop.
-//
-// Idempotent: if the regenerated content matches what's on disk, nothing
-// changes. Run on every deploy (ship.js / merge-mode call it before deploying).
-//
-// Usage:
-//   node scripts/gds/gen-diagrams.js            # regenerate + render
-//   node scripts/gds/gen-diagrams.js --check     # report if anything WOULD change, write nothing (exit 2 if so)
-//   node scripts/gds/gen-diagrams.js --no-render  # write .mmd + assertions only
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const { apiCall } = require('./cli-lib.js');
-const facts = require('./diagram-facts.js');
-
-const REPO = path.join(__dirname, '..', '..');
-const DIR = path.join(REPO, 'docs/onboarding/diagrams');
-const ASSERT_PATH = path.join(DIR, 'assertions.json');
-
-// --- instance branding (R58, task 1197) ------------------------------------
-// The conceptual diagrams (03/04) carry instance identity:
-// the currency name, the public host, the world/product name. Read them from
-// the branding contract so a neutral instance renders neutral diagrams and an
-// owner's instance renders its own — no hard-coded OTB/Example tokens, no
-// prod IP. Fail-safe to the neutral defaults (the generator must run headless,
-// and a branding validation error must not break diagram regeneration).
-// NOTE: the diagram FILE ids (e.g. 03-drachmae-karma) are structural — the hall
-// UI, drift checker, and onboarding docs key off them — and are intentionally
-// NOT rebranded here; this task parameterizes the rendered CONTENT.
-function brand() {
-  let b = {};
-  try { b = require('../../src/branding').branding(); } catch { /* fail-to-neutral */ }
-  const currency = (b.currency && b.currency.label) || 'credits';
-  const worldName = (b.identity && b.identity.worldName) || 'Cloud Bongos';
-  const productName = (b.identity && b.identity.productName) || worldName;
-  let host = 'localhost:3000';
-  try { host = new URL((b.domains && b.domains.publicOrigin) || 'http://localhost:3000').host; } catch { /* keep default */ }
-  return { currency, worldName, productName, host };
-}
-const cap = (s) => (s ? s.charAt(0).toUpperCase() + s.slice(1) : s);
-
-// --- structural knowledge the DB doesn't carry -----------------------------
-
-// Which Greek band each rank sits in (the enum order encodes it, but name it
-// explicitly so a reordered enum still groups correctly). Unknown ranks fall
-// into an "unclassified" band so a newly-added enum value still renders.
-// Arrays are in intended top-to-bottom (highest→lowest) order; within-band
-// render order follows these arrays (NOT enum order), so a live rank lands in
-// the right vertical slot. `thetes` is the graduated-newcomer rank (#692 / ADR
-// 0034) — a sub-citizen sitting between metic and xenos, so it lives in the
-// outsider band, not among the (reserved) citizen wealth-classes.
-const RANK_BANDS = {
-  divine: ['olympian', 'hermes', 'oracle', 'demigod'],
-  citizen: ['archon', 'strategos', 'boule', 'aristoi', 'hippeis', 'zeugitai'],
-  outsider: ['metic', 'thetes', 'xenos', 'periokoi', 'doulos', 'helot'],
-};
-const BAND_LABEL = {
-  divine: 'Divine — above the system',
-  citizen: 'Citizen — the working ladder',
-  outsider: 'Outsider / sub-citizen — sandboxed',
-  unclassified: 'Unclassified — new enum value, place me',
-};
-
-// Standard task-lifecycle transitions. Edges render only when BOTH endpoints
-// are in the live status set; a live status not mentioned here renders as a
-// flagged standalone node.
-const LIFECYCLE_EDGES = [
-  ['[*]', 'backlog', 'task created'],
-  ['backlog', 'ready', 'deps shipped / promote'],
-  ['ready', 'active', '/builder-claim'],
-  ['active', 'blocked', 'blocker filed'],
-  ['blocked', 'active', 'blocker resolved'],
-  ['active', 'ready', '/builder-release (no credits)'],
-  ['active', 'completed', '/builder-ship: declared done + smoke tests'],
-  ['completed', 'confirmed', 'grader passes  (verified — not yet paid)'],
-  ['confirmed', 'shipped', 'CI + gate-review → auto-merge + deploy  ◀ CREDITS AWARDED HERE'],
-  ['backlog', 'abandoned', 'dropped'],
-];
-
-// --- templates (pure functions of facts) -----------------------------------
-
-function lifecycleMmd(f) {
-  const statuses = new Set(f.task_statuses);
-  const known = new Set(LIFECYCLE_EDGES.flatMap(([a, b]) => [a, b]).filter((s) => s !== '[*]'));
-  const lines = [
-    '---',
-    'title: Task lifecycle — from backlog to shipped  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)',
-    '---',
-    'stateDiagram-v2',
-  ];
-  for (const [a, b, label] of LIFECYCLE_EDGES) {
-    const aok = a === '[*]' || statuses.has(a);
-    const bok = b === '[*]' || statuses.has(b);
-    if (aok && bok) lines.push(`    ${a} --> ${b}: ${label}`);
-  }
-  lines.push('    shipped --> [*]: live in production');
-  // Landing (confirmed→shipped) + the rank/surface auto-merge gate. Static policy
-  // text (ADR 0058/0042/0043), mirrored in docs/onboarding/primer.md "How work
-  // lands". Only rendered when both confirmed and shipped are live statuses, so the
-  // note never references a status the diagram doesn't show.
-  if (statuses.has('confirmed') && statuses.has('shipped')) {
-    lines.push('    note right of confirmed');
-    lines.push('        Landing (confirmed→shipped): the PR must pass CI');
-    lines.push('        (tests + secret scan + gate-review), then the server');
-    lines.push('        auto-merges and main deploys — nobody pushes main by');
-    lines.push('        hand. A stalled green PR is swept in ~5 min; /merge-mode');
-    lines.push('        is the manual fallback.');
-    lines.push('        --');
-    lines.push('        What may AUTO-merge, by what the change touches:');
-    lines.push('        - normal work (game / art / docs / tests): any rank');
-    lines.push('        - a protected gate surface: Metic+ only;');
-    lines.push('          Xenos / Thetes wait for an Archon');
-    lines.push('        - the safety core (hard floor): always an Archon');
-    lines.push('    end note');
-  }
-  // Any live status with no structural transitions yet — surface it, don't hide it.
-  const orphans = [...statuses].filter((s) => !known.has(s));
-  for (const o of orphans) {
-    lines.push(`    ${o} : ${o} (new status — wire its transitions in gen-diagrams.js)`);
-  }
-  return lines.join('\n') + '\n';
-}
-
-function rankLadderMmd(f) {
-  const wired = new Set(f.wired_ranks);
-  const bandOf = (r) => {
-    for (const [band, members] of Object.entries(RANK_BANDS)) if (members.includes(r)) return band;
-    return 'unclassified';
-  };
-  const marker = (r) => (wired.has(r) ? '●' : '○');
-  const note = (r) => {
-    const bits = [];
-    if (r === f.default_rank) bits.push('default for new builders');
-    if (wired.has(r)) bits.push('LIVE'); else bits.push('reserved');
-    return bits.join(', ');
-  };
-
-  const lines = [
-    '---',
-    'title: Builder rank ladder — live vs reserved  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)',
-    '---',
-    'flowchart TB',
-    '    LEGEND["● LIVE (enforced by builders.rank)   ○ reserved (enum value, no wiring yet)"]',
-  ];
-  // Bands in fixed top-to-bottom order, only those with members present.
-  // Within a band, render in the curated RANK_BANDS array order (highest→lowest)
-  // intersected with the live enum — so e.g. metic→thetes→xenos reads correctly
-  // regardless of the enum's historical column order.
-  const order = ['divine', 'citizen', 'outsider', 'unclassified'];
-  const byBand = {};
-  for (const band of order) {
-    const members = (RANK_BANDS[band] || []).filter((r) => f.rank_enum.includes(r));
-    if (members.length) byBand[band] = members;
-  }
-  // Any enum rank not classified into a named band still renders (don't hide it).
-  const classified = new Set(Object.values(RANK_BANDS).flat());
-  const extras = f.rank_enum.filter((r) => !classified.has(r));
-  if (extras.length) byBand.unclassified = [...(byBand.unclassified || []), ...extras];
-  const presentBands = order.filter((b) => byBand[b] && byBand[b].length);
-  presentBands.forEach((band, bi) => {
-    const safe = `B_${band}`;
-    lines.push(`    subgraph ${safe}["${BAND_LABEL[band]}"]`);
-    lines.push('        direction TB');
-    const members = byBand[band];
-    members.forEach((r, i) => {
-      const id = `r_${r}`;
-      lines.push(`        ${id}["${marker(r)} ${r} — ${note(r)}"]`);
-      if (i > 0) lines.push(`        r_${members[i - 1]} --> ${id}`);
-    });
-    lines.push('    end');
-    if (bi > 0) lines.push(`    B_${presentBands[bi - 1]} --> ${safe}`);
-  });
-  // Permissions block (the live citizen ranks). Static text, but keyed on which
-  // ranks are actually wired so it doesn't claim authority that isn't enforced.
-  lines.push('    subgraph PERMS["Permissions — server-enforced (auth.requireRank, no caching; ADR 0016)"]');
-  lines.push('        direction TB');
-  if (wired.has('archon')) lines.push('        P_archon["archon: create/promote/PATCH tasks · version close · grant ranks · override claims"]');
-  if (wired.has('metic')) lines.push('        P_metic["metic: claim any task · idea triage · blocker review · planning/priority · file red-team; CANNOT create tasks or grant ranks"]');
-  if (wired.has('thetes')) lines.push('        P_thetes["thetes (auto-graduated after 3 ships): claim the whole general queue; NO scope-shaping — cannot triage, file red-team, resolve blockers, or create/edit tasks"]');
-  if (wired.has(f.default_rank)) lines.push(`        P_default["${f.default_rank} (default): claim ONLY newcomer_friendly tasks + ship/release OWN work · log cost · capture learnings · file blockers+ideas; CANNOT create/edit tasks or touch others' claims"]`);
-  lines.push('    end');
-  if (wired.has('archon')) lines.push('    r_archon -.-> P_archon');
-  if (wired.has('metic')) lines.push('    r_metic -.-> P_metic');
-  if (wired.has('thetes')) lines.push('    r_thetes -.-> P_thetes');
-  if (wired.has(f.default_rank)) lines.push(`    r_${f.default_rank} -.-> P_default`);
-  return lines.join('\n') + '\n';
-}
-
-function versioningMmd(f) {
-  // Chronological order: by started_at (nulls last), then id.
-  const ord = (arr) =>
-    [...arr].sort((a, b) => {
-      const ta = a.started_at ? Date.parse(a.started_at) : Infinity;
-      const tb = b.started_at ? Date.parse(b.started_at) : Infinity;
-      return ta - tb || a.id.localeCompare(b.id);
-    });
-  const lines = [
-    '---',
-    'title: Versioning + planning sessions  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)',
-    '---',
-    'flowchart TB',
-    '    PS["/planning-session → done_when_criteria + tasks (with dependencies) + rank → seed the work pool"]',
-    '    PS --> POOL["Version task pool (backlog/ready)"]',
-    '    POOL --> VERSIONS',
-    '    subgraph VERSIONS["Every task inherits its version; role/discipline is the work-type axis"]',
-    '        direction TB',
-  ];
-  const vs = ord(f.versions);
-  vs.forEach((v, i) => {
-    const id = `v_${v.id.replace(/[^A-Za-z0-9]/g, '_')}`;
-    lines.push(`        ${id}["${v.id} — ${v.status}"]`);
-    if (i > 0) {
-      const prev = `v_${vs[i - 1].id.replace(/[^A-Za-z0-9]/g, '_')}`;
-      lines.push(`        ${prev} --> ${id}`);
-    }
-  });
-  lines.push('    end');
-  lines.push('    VERSIONS --> CLOSE["Version close — all done_when_criteria satisfied"]');
-  lines.push('    CLOSE --> ARCHIVE["Archive scope to limitations/*.md; status=shipped"]');
-  lines.push('    ARCHIVE --> REVIEW["Guided review before next version becomes king"]');
-  lines.push('    REVIEW --> PS');
-  return lines.join('\n') + '\n';
-}
-
-// --- conceptual templates (pure functions of f.conceptual) ------------------
-//
-// Both port the previously hand-authored .mmd VERBATIM (same nodes, layout,
-// prose) and change ONLY: the title line (now AUTO-GENERATED) and the
-// LIVE/PLANNED label fragments + edge solid-vs-dotted, derived from the backing
-// task statuses in f.conceptual.taskStatus. Callers MUST guard on f.conceptual
-// being present (TARGETS does).
-
-// 03-drachmae-karma. Pieces → backing task ids (live ids, verified 2026-05-30):
-//   D_TOKEN — no task gate (cost-plus per-session reward, ADR 0054 / task 1005;
-//             live in prod via migration 090). Always LIVE, like D_SHIP/D_ACH.
-//             This is now the PRIMARY drachmae source — round(true_cost × 1.20).
-//   D_SHIP  — no task gate (foundational per-task credit trigger), always LIVE;
-//             label carries the ADR 0023 kind multiplier + idea-promotion bonus.
-//   D_ACH   — always LIVE; N = seeded-achievement count (+ net-negative bonus).
-//   D_BOUNTY rate card — #284 (R65); awarding — #286 (R67, auto-confirm/award)
-//             + #282 (R63 vuln_reports). Awarding LIVE iff BOTH shipped.
-//   KARMA   — K_VOTE #245 (R25), K_PROP #248 (R32), K_SURF #246 (R26); each
-//             LIVE iff shipped. Subgraph title flips once karma is partially live.
-function drachmaeKarmaMmd(f) {
-  const c = f.conceptual;
-  const { currency } = brand();
-  const CUR = currency.toUpperCase();
-  const shipped = (id) => c.taskStatus[id] === 'shipped';
-  const tag = (id) => (shipped(id) ? 'LIVE' : 'PLANNED');
-  const edge = (id) => (shipped(id) ? '-->' : '-.PLANNED.->');
-
-  const nAch = c.achievementsSeeded;
-  const rateCard = shipped(284);
-  const awarding = shipped(286) && shipped(282);
-  const karmaAnyLive = shipped(245) || shipped(248) || shipped(246);
-  const karmaTitle = karmaAnyLive
-    ? 'KARMA  (separate signal — partially live)'
-    : 'KARMA  (separate signal — PLANNED, not yet built)';
-
-  const lines = [
-    '---',
-    `title: ${cap(currency)} & karma — where each comes from, where each goes  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)`,
-    '---',
-    'flowchart LR',
-    `    subgraph CURRENCY["${CUR}  (the builder reward — equity / reputation, a stake, not a spendable currency)"]`,
-    '        direction TB',
-    '        D_TOKEN["Ship a SESSION — the main reward\\nround(true_cost_usd × 1.20) cents — cost-plus on real token spend\\n(LIVE: priced server-side from token counts; ADR 0054, idempotent per session)"]',
-    '        D_SHIP["SHIP a TASK — books when the code lands on main, not at confirm\\ncredits_reward × kind multiplier (0.8–1.5×)\\n+ 25% idea-promotion bonus to the capturer\\n(LIVE: ADR 0023; pay-on-land ADR 0120; withheld entirely on a cost-plus-only instance, ADR 0146)"]',
-    `        D_ACH["Unlock an achievement\\nachievements.credit_bonus (LIVE: ${nAch} seeded)\\n+ small net-negative-ship bonus"]`,
-    `        D_BOUNTY["Red-team / security bounty\\n${currency} payout by severity\\n(rate card ${rateCard ? 'LIVE' : 'PLANNED'}: R65 #284 — src/bongos/security.js + shown on /builders;\\nawarding still ${awarding ? 'LIVE' : 'PLANNED'}: R67 #286 + vulnerability_reports R63 #282)"]`,
-    '',
-    '        D_BAL["builders.total_credits\\n(running balance per builder)"]',
-    '',
-    '        D_TOKEN --> D_BAL',
-    '        D_SHIP --> D_BAL',
-    '        D_ACH --> D_BAL',
-    `        D_BOUNTY ${awarding ? '-->' : '-.PLANNED.->'} D_BAL`,
-    '',
-    `        D_SPEND["Spent on: nothing yet.\\n${cap(currency)} are EQUITY / reputation — a stake, not a\\nspendable currency. They persist losslessly across exit (migration 025)."]`,
-    '        D_BAL --> D_SPEND',
-    '    end',
-    '',
-    `    subgraph KARMA["${karmaTitle}"]`,
-    '        direction TB',
-    `        K_VOTE["Builder-on-builder upvote / downvote\\non CONFIRMED work\\n(${tag(245)}: R25 #245, anti-self-vote)"]`,
-    `        K_PROP["Boost on criterion-proposal ratification\\n(${tag(248)}: R32 #248, cross-link C5→C2)"]`,
-    '        K_BAL["Per-builder karma score"]',
-    `        K_SURF["Surfaced on profile + sortable\\non leaderboard (${tag(246)}: R26 #246)"]`,
-    '',
-    `        K_VOTE ${edge(245)} K_BAL`,
-    `        K_PROP ${edge(248)} K_BAL`,
-    `        K_BAL ${edge(246)} K_SURF`,
-    '    end',
-    '',
-    `    note1["${cap(currency)} measure OUTPUT (work shipped) — most of it now a cost-plus reward on real token spend.\\nKarma measures PEER TRUST (how others rate your work); it does NOT gate rank promotions.\\nBoth are reputation; neither is a spendable currency today.\\nSeparately, an Archon can set a per-builder monthly budget cap to limit SPEND — but builders are uncapped by default (src/bongos/cost.js)."]`,
-    '    CURRENCY --- note1',
-    '    KARMA --- note1',
-  ];
-  return lines.join('\n') + '\n';
-}
-
-// 04-architecture. The complete picture: where a builder's work runs and how it
-// reaches production, with the per-builder memory layer (ADR 0024) folded in
-// (task 1059). Conceptual like 03: every feature-piece + flow edge is LIVE/solid
-// iff its backing Bongos task is 'shipped', dotted/PLANNED otherwise — so the map
-// is an honest snapshot that flips itself as pieces ship (or regresses if one is
-// reopened). Pieces → live task ids:
-//   memory layer  : 273 schema · 274 sync-on-ship · 275 pull-on-start · 276 isolation
-//   ship flow     : 1025 publish-via-server · 1028 GitHub App push credential
-// Work runs on the builder's own machine, in a clone of the instance repo. It
-// reaches main one of two ways (ship-deploy-target.js `pushVia`): a machine
-// signed in to GitHub pushes its branch and opens the PR itself; a checkout with
-// no push credential uploads the branch as a git bundle and the SERVER pushes it
-// with its own credential (ADR 0055).
-function architectureMmd(f) {
-  const c = f.conceptual;
-  const { host } = brand();
-  const shipped = (id) => c.taskStatus[id] === 'shipped';
-  const tag = (id) => (shipped(id) ? 'LIVE' : 'PLANNED');
-  // Labeled flow edge: solid when its backing piece is shipped, dotted (and
-  // PLANNED-labelled) otherwise. e.g. `WORKER -->|"..."| API`.
-  const flow = (a, id, label, b) =>
-    `    ${a} ${shipped(id) ? '-->' : '-.->'}|"${label}"| ${b}`;
-
-  // --- MEMORY layer (ADR 0024 chain) ---
-  const MEM_IDS = [273, 274, 275, 276];
-  const memAllLive = MEM_IDS.every(shipped);
-  const memLead = memAllLive ? 'LIVE' : 'PARTIAL';
-  const refOf = { 273: 'R54', 274: 'R55', 275: 'R56', 276: 'R57' };
-  const liveRefs = MEM_IDS.filter(shipped).map((id) => refOf[id]);
-  const pendRefs = MEM_IDS.filter((id) => !shipped(id)).map((id) => refOf[id]);
-  const memStatus = memAllLive
-    ? `${MEM_IDS.map((id) => refOf[id]).join(' / ')} — all shipped`
-    : `${liveRefs.length ? liveRefs.join('/') + ' shipped' : 'none shipped yet'}${pendRefs.length ? '; ' + pendRefs.join('/') + ' pending' : ''}`;
-  const pushEdge = shipped(274)
-    ? 'LOCAL -->|"sync on ship (push)"| SRVMEM'
-    : 'LOCAL -.->|"sync on ship (push) — PLANNED"| SRVMEM';
-  const pullEdge = shipped(275)
-    ? 'SRVMEM -->|"pull on session start"| LOCAL'
-    : 'SRVMEM -.->|"pull on session start — PLANNED"| LOCAL';
-
-  // --- ship flow: the server's push credential + closing note ---
-  const pushCred = shipped(1028)
-    ? 'GitHub App, short-lived tokens'
-    : 'standing push PAT (GitHub App pending — 1028)';
-  // Both ways onto main LIVE? NB the deploy leg is the standalone AUTO-PULL
-  // (ADR 0108/0129), not a task-gated GitHub-Actions CI job — so 859 (CI deploy)
-  // is intentionally NOT in this set.
-  const chainLive = [1025, 1028].every(shipped);
-  const closingNote = chainLive
-    ? 'Both ways onto main work today: a machine signed in to GitHub pushes its own branch, and a checkout without a push credential uploads it for the server to push. Either way the instance auto-pulls and redeploys.'
-    : `Still landing (PLANNED): the server-mediated publish (${tag(1025)} · 1025) and the GitHub App push credential (${tag(1028)} · 1028).`;
-
-  // Product-neutral runtime label: the instance's own product name (branding),
-  // NOT a hard-coded "game" (this core powers any app, not only the reference
-  // game instance). Falls back to a generic phrase when branding carries none.
-  const productName = brand().productName;
-  const appLabel = productName && productName !== 'Cloud Bongos' ? productName : 'app';
-
-  // Layout: ELK engine, top-down (task 1066). ELK minimizes edge crossings far
-  // better than the default renderer. Two declutter moves: (1) the INTRA-cluster
-  // wiring (worker→its files, api→db/rank, db→memory-store) is dropped —
-  // co-location inside a labelled subgraph already says "these belong together";
-  // only the CROSS-cluster flow (the numbered ship steps, memory sync,
-  // claim/ship) is drawn. (2) Low-signal annotation edges (DB-is-king,
-  // memory-follows-you) are folded into node labels. WATERFALL ordering (task
-  // 1073, off Lars's "put the GitHub box last"): subgraphs are declared in flow
-  // order MACHINE→SERVER→GH, and the live app (the instance's product runtime)
-  // is pulled OUT of the SERVER cluster into its own terminal node at the very
-  // bottom (annotated "same server · same Node process" so it stays honest), so
-  // the deploy is the LAST forward step instead of an edge looping back UP into
-  // the server. The deploy is the STANDALONE auto-pull (ADR 0108/0129): merge to
-  // the instance's own main → the server pulls its own repo →
-  // migrate/regenerate/restart → the live app — NOT a GitHub-Actions push-deploy
-  // (that was the reference monorepo's model). NOTE on direction: we keep TB,
-  // not LR — a sideways layout stretches the chain into an unreadable strip.
-  const lines = [
-    '---',
-    'title: The complete architecture — where your work runs and how it reaches production  (AUTO-GENERATED from live facts — do not hand-edit; see scripts/gds/gen-diagrams.js)',
-    'config:',
-    '  layout: elk',
-    '---',
-    'flowchart TB',
-    '    subgraph MACHINE["YOUR MACHINE — a clone of the instance repo"]',
-    '        WORKER["Claude Code — the desktop app or the terminal\\n(opens files · runs commands · runs the /builder-* skills)"]',
-    '        CODE["the code — git clone + per-task worktrees (.claude/worktrees/*)\\nCLAUDE.md is DESCRIPTIVE only"]',
-    '        LOCAL["local ~/.claude memory\\nMAP = MEMORY.md — a one-line index loaded EVERY session\\n(a guard + auto-tidy keep it light; ADR 0074)\\n+ drawer of full notes, loaded only on demand"]',
-    '    end',
-    '',
-    `    subgraph SERVER["THE INSTANCE SERVER — ${host} (the authority AND production)"]`,
-    '        API["/api/bongos/* (same Node process as the app)"]',
-    '        CORE["@bongos/core — the build platform, VENDORED as a pinned dependency\\n(ADR 0108: central updates are a version-pin bump via `bongos upgrade`, not a merge)"]',
-    '        DB["Postgres — tasks · claims · versions · builders.rank\\ncredit_log · grades · idea_inbox · builder_memory\\n(KING for work-state + permissions; CLAUDE.md only describes it)"]',
-    '        RANK["auth.requireRank — checked per request, NO caching\\n(ADR 0016: a demotion takes effect on the next request)"]',
-    `        SRVMEM["server-side builder_memory store\\n${memLead}: per-builder · isolated · forensic read at Metic+ (ADR 0157)\\nyour memory follows you across machines & worktrees\\n/recall fetches only the relevant subset (ADR 0060)\\n(${memStatus})"]`,
-    `        PUSHTOK["server-held push credential\\n(${pushCred} — for a checkout that has none of its own)"]`,
-    '        DEPLOY["auto-pull deploy (ADR 0129)\\na timer pulls THIS instance repo every ~2 min →\\nnpm ci if the pin changed → migrate → regenerate docs → restart → healthz"]',
-    '    end',
-    '',
-    `    subgraph GH["GITHUB — the instance's own repo${c.repoSlug ? ` (${c.repoSlug})` : ''}"]`,
-    '        MAIN["branch-protected main\\n(no direct push; PR + required checks only)\\nholds config + the pinned @bongos/core — NOT the platform source"]',
-    '    end',
-    '',
-    `    LIVEAPP["the live ${appLabel} — ${host}\\n(same server · same Node process as /api/bongos/*)"]`,
-    '',
-    '    WORKER -->|"1 · edit + commit"| CODE',
-    '    WORKER -->|"2 · push the branch + open a PR (a machine signed in to GitHub)"| MAIN',
-    flow('WORKER', 1025, '2 · or upload the branch as a git bundle (no push credential here)', 'API'),
-    flow('API', 1025, `3 · the server pushes it + opens the PR (${tag(1025)})`, 'MAIN'),
-    '    MAIN -->|"4 · the instance auto-pulls its own main"| DEPLOY',
-    '    DEPLOY -->|"5 · migrate · regenerate docs · restart"| LIVEAPP',
-    '    CORE --- API',
-    '    PUSHTOK -.-> API',
-    '    API -. "claim / ship / cost" .-> WORKER',
-    `    ${pushEdge}`,
-    `    ${pullEdge}`,
-    '',
-    `    NEXT["${closingNote}"]`,
-    '    LIVEAPP --- NEXT',
-  ];
-  return lines.join('\n') + '\n';
-}
-
-// --- assertions.json (data-driven slices kept in sync) ----------------------
-
-function rebuildAssertions(prev, f) {
-  const next = JSON.parse(JSON.stringify(prev));
-  next.rank_ladder.rank_enum = f.rank_enum;
-  next.rank_ladder.default_rank = f.default_rank;
-  next.rank_ladder.wired_ranks = f.wired_ranks;
-  next.task_lifecycle.task_statuses = f.task_statuses;
-  // Derived from LIFECYCLE_EDGES so this assertion can never drift from the
-  // rendered diagram again (it silently outlived ADR 0120's move of the award
-  // from completed→confirmed to confirmed→shipped).
-  const creditEdge = LIFECYCLE_EDGES.find(([, , label]) => label.includes('CREDITS AWARDED HERE'));
-  if (creditEdge) next.task_lifecycle.credits_awarded_at = `${creditEdge[0]}->${creditEdge[1]}`;
-  // Persist only the stable identity fields (drop started_at ordering helper).
-  next.versioning.diagram = '05-versioning';
-  next.versioning.versions = f.versions.map((v) => ({ id: v.id, status: v.status }));
-
-  // Conceptual slices (03 + 04) — only rebuilt when live conceptual facts are
-  // present. When degraded (f.conceptual == null) leave the existing slices
-  // untouched so a headless run can't blank them out.
-  if (f.conceptual) {
-    const c = f.conceptual;
-    const shipped = (id) => c.taskStatus[id] === 'shipped';
-    const entry = (id) => ({ id, label: c.taskLabels[id] });
-    const split = (ids) => ({
-      live_tasks: ids.filter(shipped).map(entry),
-      pending_tasks: ids.filter((id) => !shipped(id)).map(entry),
-    });
-
-    // 04-architecture — the ADR 0024 memory chain + the machine → prod ship
-    // flow (task 1059). A piece is LIVE iff its backing task is shipped.
-    const arch = split([273, 274, 275, 276, 1025, 1028]);
-    next.architecture = {
-      diagram: '04-architecture',
-      _comment:
-        "Pieces of 04-architecture gated on a backing Bongos task. A piece is LIVE iff its task is 'shipped'; live_tasks must ALL be shipped, pending_tasks must NOT yet be. Rebuilt by scripts/gds/gen-diagrams.js in lockstep with the diagram, so this is the drift checker's backstop. The machine/server/GitHub topology is structural (not task-gated); these are the LIVE/PLANNED markers. MEMORY layer (ADR 0024): 273 schema / 274 sync-on-ship / 275 pull-on-start / 276 isolation. Ship flow: 1025 (server-mediated publish, for a checkout with no push credential), 1028 (GitHub App push credential). The deploy leg is the standalone AUTO-PULL (ADR 0108/0129), not a task-gated GitHub-Actions CI job, so 859 is intentionally absent.",
-      live_tasks: arch.live_tasks,
-      pending_tasks: arch.pending_tasks,
-    };
-
-    // 03-drachmae-karma — bounty + karma pieces (D_SHIP/D_ACH have no task gate).
-    const dk = split([284, 286, 282, 245, 248, 246]);
-    next.drachmae_karma = {
-      ...next.drachmae_karma,
-      diagram: '03-drachmae-karma',
-      _comment:
-        "Pieces of 03-drachmae-karma that are gated on a backing Bongos task. A piece is LIVE iff its task is 'shipped'. live_tasks must ALL be shipped live; pending_tasks must NOT yet be shipped. Rebuilt automatically by scripts/gds/gen-diagrams.js from the authenticated /tasks/:id status; the diagram is regenerated in lockstep, so this slice is a redundant backstop the drift checker verifies. D_SHIP (credit_log trigger) and D_ACH (achievement bonuses) have no task gate and are always LIVE. achievements_seeded mirrors 03's 'N seeded' label, counted from the achievements seed INSERTs in migrations/.",
-    };
-    next.drachmae_karma.live_tasks = dk.live_tasks;
-    next.drachmae_karma.pending_tasks = dk.pending_tasks;
-    next.drachmae_karma.achievements_seeded = c.achievementsSeeded;
-  }
-  return next;
-}
-
-// --- main -------------------------------------------------------------------
-
-// The 3 mechanical diagrams always regenerate (no auth dependency). The 2
-// conceptual ones are appended only when live conceptual facts are present;
-// when degraded they're left untouched and a skip line is logged.
-const MECHANICAL_TARGETS = [
-  ['01-task-lifecycle.mmd', lifecycleMmd],
-  ['02-rank-ladder.mmd', rankLadderMmd],
-  ['05-versioning.mmd', versioningMmd],
-];
-const CONCEPTUAL_TARGETS = [
-  ['03-drachmae-karma.mmd', drachmaeKarmaMmd],
-  ['04-architecture.mmd', architectureMmd],
-];
-
-(async () => {
-  const checkOnly = process.argv.includes('--check');
-  const noRender = process.argv.includes('--no-render');
-
-  const f = await facts.gatherFacts({ repo: REPO });
-
-  const TARGETS = [...MECHANICAL_TARGETS];
-  if (f.conceptual) {
-    TARGETS.push(...CONCEPTUAL_TARGETS);
-  } else {
-    console.log(
-      'gen-diagrams: conceptual facts unavailable (no Bongos session / API unreachable) — SKIPPING 03-drachmae-karma + 04-architecture; the 3 mechanical diagrams still regenerate.'
-    );
-  }
-
-  const changed = [];
-  const writes = []; // {file, content}
-
-  for (const [file, tmpl] of TARGETS) {
-    const full = path.join(DIR, file);
-    const next = tmpl(f);
-    const cur = fs.existsSync(full) ? fs.readFileSync(full, 'utf8') : '';
-    if (cur !== next) {
-      changed.push(file);
-      writes.push({ full, content: next });
-    }
-  }
-
-  // assertions.json
-  const prevAssert = JSON.parse(fs.readFileSync(ASSERT_PATH, 'utf8'));
-  const nextAssert = rebuildAssertions(prevAssert, f);
-  const nextAssertStr = JSON.stringify(nextAssert, null, 2) + '\n';
-  const curAssertStr = fs.readFileSync(ASSERT_PATH, 'utf8');
-  const assertChanged = curAssertStr !== nextAssertStr;
-
-  if (checkOnly) {
-    if (changed.length === 0 && !assertChanged) {
-      console.log('gen-diagrams --check: up to date.');
-      process.exit(0);
-    }
-    console.log(`gen-diagrams --check: would update ${[...changed, assertChanged ? 'assertions.json' : null].filter(Boolean).join(', ')}`);
-    process.exit(2);
-  }
-
-  if (changed.length === 0 && !assertChanged) {
-    // task 1002674: say WHICH set was checked. The old wording claimed only
-    // "mechanical", which reads as "the conceptual pair was skipped" — the
-    // degraded case — even on a fully successful run. Verifying that 03 + 04
-    // actually regenerated then meant reading the source.
-    console.log(`gen-diagrams: all ${TARGETS.length} diagram(s) already current — no changes${f.conceptual ? '' : ' (conceptual pair SKIPPED — see above)'}.`);
-    process.exit(0);
-  }
-
-  for (const w of writes) fs.writeFileSync(w.full, w.content);
-  if (assertChanged) fs.writeFileSync(ASSERT_PATH, nextAssertStr);
-  console.log(`gen-diagrams: wrote ${changed.length} .mmd${assertChanged ? ' + assertions.json' : ''}: ${changed.join(', ') || '(none)'}`);
-
-  if (changed.length && !noRender) {
-    const args = changed.map((f2) => path.join(DIR, f2));
-    const r = spawnSync('bash', [path.join(REPO, 'scripts/render-diagrams.sh'), ...args], { stdio: 'inherit' });
-    if (r.error) {
-      // The render step is a bash script (mermaid-cli). On a platform without
-      // bash on PATH — e.g. a Windows builder lacking Git Bash — spawnSync sets
-      // r.error (ENOENT) and r.status is null. The .mmd sources are already
-      // written above and the caller (ship.js regenerateDiagrams) will commit
-      // them; PNGs get re-rendered on the Linux droplet at deploy time, and the
-      // diagram-drift routine backstops any staleness. So skip the render
-      // NON-FATALLY rather than hard-failing the whole ship on a missing bash.
-      console.warn(
-        `gen-diagrams: could not run the render step (${r.error.code || r.error.message}). ` +
-        '.mmd written; PNG render skipped (droplet re-renders on deploy).'
-      );
-    } else if (r.status !== 0) {
-      // bash ran but the render genuinely failed — surface it.
-      console.error('gen-diagrams: render failed — .mmd written but PNG not refreshed.');
-      process.exit(1);
-    }
-  }
-  console.log('gen-diagrams: done.');
-})().catch((e) => {
-  console.error('gen-diagrams: error:', e.message);
-  process.exit(1);
-});
+// scripts/gds/gen-diagrams.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/gen-diagrams.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'gen-diagrams.js');