@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/gen-diagrams.js

@@ -0,0 +1,608 @@
+#!/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/bongos/gen-diagrams.js            # regenerate + render
+//   node scripts/bongos/gen-diagrams.js --check     # report if anything WOULD change, write nothing (exit 2 if so)
+//   node scripts/bongos/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/bongos/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/bongos/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/bongos/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/bongos/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/bongos/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/bongos/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/bongos/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);
+});