@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/gen-repo-map.js

@@ -0,0 +1,540 @@
+#!/usr/bin/env node
+'use strict';
+// gen-repo-map.js — Path B (ADR 0062 §9 / ADR 0063, task 1224).
+//
+// A committed, CI-regenerated SYMBOL SKELETON for this instance's codebase:
+//   (1) docs/repo-map.md — an "altitude map" so an agent can navigate without reading every
+//       file: top symbols ranked by reference frequency (à la Aider's repo map) + per-directory
+//       exported signatures.
+//   (2) refreshes the FACTUAL half of the nested per-module CLAUDE.md docs (ADR 0061) — a
+//       generated, delimited block of the directory's exported signatures, so the hand-written
+//       interpretive prose stays put while the file list / signatures can't silently drift.
+//
+// Zero-dependency on purpose: the codebase is CommonJS JS, and a portable-core capability must
+// regenerate in CI and on any checkout with no native build / no node-gyp / no WASM grammar to
+// fetch (the whole point of Paths B+C is keeping every instance navigable cheaply). A line+regex
+// extractor is accurate enough for an *advisory* navigation aid (it is not a compiler input). A
+// richer tree-sitter/WASM backend can slot in behind extractFile() later for polyglot instances
+// (ADR 0063 Alternatives).
+//
+// Deterministic: no timestamps, stable sort — so `--check` is a clean idempotent CI gate.
+//
+// Usage:
+//   node scripts/bongos/gen-repo-map.js            # regenerate docs/repo-map.md + nested-doc blocks
+//   node scripts/bongos/gen-repo-map.js --check       # write nothing; exit 2 if EITHER bucket would change
+//   node scripts/bongos/gen-repo-map.js --check-block # exit 2 only if a TRACKED nested block would change (the CI gate)
+//   node scripts/bongos/gen-repo-map.js --check-whole # exit 2 only if docs/repo-map.md would change
+//   node scripts/bongos/gen-repo-map.js --whole-only  # WRITE docs/repo-map.md only; never touch the
+//                                                  # tracked nested blocks (what a SPARSE
+//                                                  # checkout must use — task 1002962)
+// docs/repo-map.md is GITIGNORED + regenerated at deploy since ADR 0110 (task 1926);
+// only the nested-doc symbol blocks stay tracked, so CI gates the block bucket, not the whole file.
+//   node scripts/bongos/gen-repo-map.js --json       # print the extracted model as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+// task 2013: reuse docs-entropy's link/staleness detectors (single source) to
+// build the doc link-graph + staleness flags. Requiring it is side-effect-free
+// (its CLI body is require.main-guarded).
+const docsEntropy = require('./docs-entropy');
+const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
+
+// ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the generator scans TWO trees.
+// CORE code + the core-owned nested docs live under the core PACKAGE (resolveCoreRoot); the
+// instance's .claude/hooks are materialized under the host REPO (resolveInstanceRoot); modules
+// ship from BOTH. Today both resolve to the same checkout, so the scan is byte-identical; once the
+// core installs from node_modules they diverge and the map covers the right trees. A NEW hardcoded
+// `path.resolve(__dirname,'..','..')` reintroduces the bug.
+const CORE_ROOT = resolveCoreRoot();
+const INSTANCE_ROOT = resolveInstanceRoot();
+const REPO_ROOT = CORE_ROOT; // alias for the purely-core scan/write sites; instance/module sites route explicitly
+const MODULE_ROOTS = [...new Set([CORE_ROOT, INSTANCE_ROOT])];
+
+// Source roots scanned for both symbol extraction AND reference counting, grouped by which root
+// each resolves against. The build-system core (server-side JS) — the Cloud Bongos decoupling
+// target. Extend here to map more of an instance.
+const CORE_SCAN_ROOTS = ['server.js', 'src', 'scripts'];
+const INSTANCE_SCAN_ROOTS = ['.claude/hooks'];
+const MODULE_SCAN_ROOT = 'modules';
+const SCAN_ROOTS = [...CORE_SCAN_ROOTS, ...INSTANCE_SCAN_ROOTS, MODULE_SCAN_ROOT]; // combined list, for the scope header
+
+// Directories whose nested CLAUDE.md gets a generated symbol-skeleton block (must already exist —
+// they are authored in Path A / ADR 0061; this only refreshes the factual half). All CORE dirs.
+// scripts/bongos dropped (task 1003548): its block had grown to ~40k chars — 76% of a file every builder
+// session loads when it touches claim/ship. docs/repo-map.md still carries the full index.
+const NESTED_DIRS = ['src/bongos', 'src/bongos/routes'];
+
+const EXCLUDE_DIR = new Set(['node_modules', '.git', 'tests', 'test', 'vendor']);
+const TOP_GLOBAL = 50;      // global "most-referenced" table cap
+const PER_FILE = 10;        // exported symbols listed per file
+const SIG_MAX = 90;         // signature truncation
+
+const BEGIN = '<!-- BEGIN GENERATED REPO-MAP (scripts/bongos/gen-repo-map.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED REPO-MAP -->';
+
+// Generic per-file local-helper / boilerplate names. They dominate a raw token tally (every script
+// has a `main`, a `log`, an `err`) but say nothing about cross-file centrality, so they are noise
+// for an altitude map. CommonJS reachability means real cross-file centrality ⟺ being exported, so
+// the global ranking is exported-only; this list trims the few generic names that still leak in.
+const NOISE = new Set([
+  'main', 'run', 'log', 'err', 'warn', 'fail', 'ok', 'info', 'debug', 'usage', 'help', 'sleep',
+  'noop', 'status', 'client', 'pool', 'res', 'req', 'next', 'data', 'result', 'val', 'value',
+  'fn', 'cb', 'msg', 'out', 'ret', 'args', 'opts', 'options', 'ctx', 'app', 'router', 'init',
+]);
+const isNoise = (name) => NOISE.has(name) || name.length <= 2;
+
+// macOS Finder / iCloud Drive sync-conflict copies are named "<base> 2.js",
+// "<base> 3.js", … (a space + digits before the extension). They are untracked,
+// stale duplicates that must NEVER enter the symbol skeleton: left in, they
+// double-count a module's symbols and bump file/symbol totals, so a ship from an
+// iCloud-synced checkout bakes phantom entries into the committed repo-map — and
+// CI's `repo_map --check` (run on a clean checkout that has no such copies) then
+// flags it STALE and fails the required `unit` gate. Skip them at the walk so the
+// generator is deterministic regardless of the working tree's sync artifacts
+// (task 1236; first hit on PR #165, the task 1233 ship).
+const CONFLICT_COPY_RE = / \d+\.js$/;
+const isConflictCopy = (name) => CONFLICT_COPY_RE.test(name);
+
+// Choose the symbols to surface for one file: exported public surface (ranked by reference
+// frequency); for an entry-point script with no exports, its declared fns/classes in source order.
+function pickForFile(f) {
+  const exAll = f.symbols.filter((s) => s.exported);
+  const ex = exAll.filter((s) => !isNoise(s.name));
+  if (ex.length) {
+    const list = [...ex].sort((a, b) => b.refs - a.refs || a.name.localeCompare(b.name));
+    return { list: list.slice(0, PER_FILE), pool: exAll.length };
+  }
+  const decl = f.symbols.filter((s) => (s.kind === 'fn' || s.kind === 'class') && !isNoise(s.name));
+  return { list: decl.slice(0, PER_FILE), pool: decl.length };
+}
+
+// ---- file walk -------------------------------------------------------------
+
+function walk(absRoot, out) {
+  let st;
+  try { st = fs.statSync(absRoot); } catch { return; }
+  if (st.isFile()) {
+    const base = path.basename(absRoot);
+    if (absRoot.endsWith('.js') && !isConflictCopy(base)) out.push(absRoot);
+    return;
+  }
+  if (!st.isDirectory()) return;
+  for (const ent of fs.readdirSync(absRoot, { withFileTypes: true })) {
+    if (ent.isDirectory()) {
+      if (EXCLUDE_DIR.has(ent.name)) continue;
+      walk(path.join(absRoot, ent.name), out);
+    } else if (ent.isFile() && ent.name.endsWith('.js') && !isConflictCopy(ent.name)) {
+      out.push(path.join(absRoot, ent.name));
+    }
+  }
+}
+
+// repo-relative POSIX path for an abs file under EITHER root (core package or instance repo).
+const relOf = (abs) => {
+  for (const base of [CORE_ROOT, INSTANCE_ROOT]) {
+    const r = path.relative(base, abs);
+    if (r && !r.startsWith('..') && !path.isAbsolute(r)) return r.split(path.sep).join('/');
+  }
+  return path.relative(CORE_ROOT, abs).split(path.sep).join('/');
+};
+
+function collectFiles() {
+  const files = [];
+  for (const root of CORE_SCAN_ROOTS) walk(path.join(CORE_ROOT, root), files);
+  for (const root of INSTANCE_SCAN_ROOTS) walk(path.join(INSTANCE_ROOT, root), files);
+  for (const r of MODULE_ROOTS) walk(path.join(r, MODULE_SCAN_ROOT), files); // modules ship from both roots
+  // stable, de-duped BY repo-relative path (a shared checkout would otherwise list a module twice)
+  const seen = new Set();
+  const uniq = [];
+  for (const abs of [...new Set(files)].sort()) {
+    const r = relOf(abs);
+    if (seen.has(r)) continue;
+    seen.add(r);
+    uniq.push(abs);
+  }
+  return uniq;
+}
+
+// ---- symbol extraction (col-0 declarations + exports) ----------------------
+
+const RE_FUNC = /^(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)?/;
+const RE_CLASS = /^class\s+([A-Za-z_$][\w$]*)/;
+// const NAME = (a,b) => | function(a,b) | async (a,b) => | require(...) | value | {…}
+const RE_DECL = /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(.*)$/;
+
+function rhsKindAndSig(rhs) {
+  let m;
+  if ((m = rhs.match(/^async\s+function\s*\(([^)]*)\)?/)) || (m = rhs.match(/^function\s*\(([^)]*)\)?/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if ((m = rhs.match(/^async\s*\(([^)]*)\)?\s*=>/)) || (m = rhs.match(/^\(([^)]*)\)?\s*=>/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if ((m = rhs.match(/^async\s+([A-Za-z_$][\w$]*)\s*=>/)) || (m = rhs.match(/^([A-Za-z_$][\w$]*)\s*=>/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if (/^require\(/.test(rhs)) return { kind: 'import', sig: '' };
+  if (/^\{/.test(rhs)) return { kind: 'obj', sig: '' };
+  if (/^(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/.test(rhs)) return { kind: 'val', sig: '' };
+  return { kind: 'const', sig: '' };
+}
+
+function parseExports(src) {
+  const exported = new Set();
+  let m;
+  // module.exports.NAME = / exports.NAME =
+  const reDot = /(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g;
+  while ((m = reDot.exec(src))) exported.add(m[1]);
+  // module.exports = { a, b: x, c }   (also handles multi-line object)
+  const reObj = /module\.exports\s*=\s*\{([\s\S]*?)\}/g;
+  while ((m = reObj.exec(src))) {
+    for (const part of m[1].split(',')) {
+      const key = part.split(':')[0].trim().replace(/^\.\.\./, '').trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(key)) exported.add(key);
+    }
+  }
+  // module.exports = NAME
+  const reSingle = /module\.exports\s*=\s*([A-Za-z_$][\w$]*)\s*;/g;
+  while ((m = reSingle.exec(src))) exported.add(m[1]);
+  return exported;
+}
+
+function extractFile(abs) {
+  const src = fs.readFileSync(abs, 'utf8');
+  const lines = src.split('\n');
+  const exported = parseExports(src);
+  const symbols = [];
+  for (const raw of lines) {
+    // col-0 declarations only — commented-out / nested code is indented or comment-led
+    if (/^[\s/*]/.test(raw)) continue;
+    let m;
+    if ((m = raw.match(RE_FUNC))) {
+      symbols.push({ name: m[1], kind: 'fn', sig: (m[2] || '').trim() });
+    } else if ((m = raw.match(RE_CLASS))) {
+      symbols.push({ name: m[1], kind: 'class', sig: '' });
+    } else if ((m = raw.match(RE_DECL))) {
+      const { kind, sig } = rhsKindAndSig(m[2].trim());
+      if (kind === 'import') continue; // requires aren't navigation symbols
+      symbols.push({ name: m[1], kind, sig: (sig || '').trim() });
+    }
+  }
+  // de-dupe by name (keep first), tag exported
+  const seen = new Set();
+  const uniq = [];
+  for (const s of symbols) {
+    if (seen.has(s.name)) continue;
+    seen.add(s.name);
+    uniq.push({ ...s, exported: exported.has(s.name) });
+  }
+  return uniq;
+}
+
+// ---- reference frequency (token tally across the whole corpus) -------------
+
+function buildRefCounts(files) {
+  const counts = new Map();
+  const reId = /[A-Za-z_$][\w$]*/g;
+  for (const abs of files) {
+    const src = fs.readFileSync(abs, 'utf8');
+    let m;
+    while ((m = reId.exec(src))) {
+      const id = m[0];
+      counts.set(id, (counts.get(id) || 0) + 1);
+    }
+  }
+  return counts;
+}
+
+// ---- model -----------------------------------------------------------------
+
+function buildModel() {
+  const files = collectFiles();
+  const refs = buildRefCounts(files);
+  const byFile = []; // {rel, symbols:[{name,kind,sig,exported,refs}]}
+  const allSyms = [];
+  for (const abs of files) {
+    const rel = relOf(abs); // root-aware: a module file may live under the instance repo post-split
+    const syms = extractFile(abs).map((s) => ({ ...s, refs: refs.get(s.name) || 0, file: rel }));
+    byFile.push({ rel, symbols: syms });
+    allSyms.push(...syms);
+  }
+  return { files, byFile, allSyms };
+}
+
+function fmtSig(s) {
+  if (s.kind === 'fn') {
+    let sig = s.sig || '';
+    if (sig.length > SIG_MAX) sig = sig.slice(0, SIG_MAX) + '…';
+    return `${s.name}(${sig})`;
+  }
+  if (s.kind === 'class') return `class ${s.name}`;
+  return s.name;
+}
+
+// ---- rendering: docs/repo-map.md -------------------------------------------
+
+function renderRepoMap(model) {
+  const L = [];
+  L.push('# Repo map — generated symbol skeleton');
+  L.push('');
+  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/bongos/gen-repo-map.js` (runs on deploy, like `gen-diagrams.js`). Path B of the 2026-06-18 context-cliff plan — a portable-core altitude map ([ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §9 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md)). Complements the lexical recall layer ([ADR 0060](adr/0060-gds-retrieval-layer.md)), which indexes *prose*; this indexes *code*.');
+  L.push('>');
+  L.push(`> **Scope:** \`${SCAN_ROOTS.join('`, `')}\` — ${model.files.length} JS files, ${model.allSyms.length} top-level symbols. (Tests + \`node_modules\` + vendored libs excluded.) Symbols ranked by reference frequency across the scanned corpus.`);
+  L.push('');
+
+  // Global top-N: exported surface (cross-file reachable in CommonJS), minus generic noise.
+  const top = model.allSyms
+    .filter((s) => s.exported && !isNoise(s.name))
+    .sort((a, b) => b.refs - a.refs || a.name.localeCompare(b.name) || a.file.localeCompare(b.file))
+    .slice(0, TOP_GLOBAL);
+  L.push(`## Top ${TOP_GLOBAL} exported symbols by reference frequency`);
+  L.push('');
+  L.push('| symbol | kind | file | refs |');
+  L.push('|---|---|---|---|');
+  for (const s of top) L.push(`| \`${fmtSig(s)}\` | ${s.kind} | \`${s.file}\` | ${s.refs} |`);
+  L.push('');
+
+  // Per-directory exported signatures
+  L.push('## By directory — exported signatures');
+  L.push('');
+  const dirs = new Map();
+  for (const f of model.byFile) {
+    const dir = f.rel.includes('/') ? f.rel.slice(0, f.rel.lastIndexOf('/')) : '.';
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push(f);
+  }
+  for (const dir of [...dirs.keys()].sort()) {
+    const fileEntries = dirs.get(dir).sort((a, b) => a.rel.localeCompare(b.rel));
+    const rendered = [];
+    for (const f of fileEntries) {
+      const { list, pool } = pickForFile(f);
+      if (!list.length) continue;
+      const base = f.rel.slice(f.rel.lastIndexOf('/') + 1);
+      const more = pool - list.length;
+      rendered.push(`- \`${base}\` — ${list.map((s) => '`' + fmtSig(s) + '`').join(', ')}${more > 0 ? ` _(+${more} more)_` : ''}`);
+    }
+    if (!rendered.length) continue;
+    L.push(`### \`${dir}/\``);
+    L.push('');
+    L.push(...rendered);
+    L.push('');
+  }
+
+  // task 2013 — the DOCUMENTATION map: a link-graph for the key navigational docs
+  // (bullet 193: "click architecture.md → see the docs it links to") + STALENESS
+  // FLAGS (docs whose internal links/anchors docs-entropy can't resolve). This is
+  // the anti-drift mechanism that replaces the manual "remember to update the
+  // detail files" session-end chores (bullets 223/224/226): the flag surfaces
+  // mechanically what needs a touch-up, so it isn't left to memory.
+  L.push(...renderDocMapLines());
+
+  return L.join('\n').replace(/\n+$/, '') + '\n';
+}
+
+// The curated set of top navigational docs whose outbound doc-links are worth
+// graphing (the whole 399-file graph would be noise). An agent lands on one of
+// these and can see, without opening it, which docs it points at.
+const KEY_DOCS = [
+  'CLAUDE.md',
+  'docs/architecture.md',
+  'docs/project-context.md',
+  'docs/file-map.md',
+  'docs/branding-contract.md',
+  'docs/api-reference.md',
+  'docs/adr/README.md',
+  'docs/canonical-permissions.md',
+];
+
+// Resolve a markdown link href (relative to the doc it appears in) to a
+// repo-relative .md path, or null if it isn't an internal .md target.
+function resolveDocLink(fromRel, href) {
+  const noAnchor = String(href).split('#')[0];
+  if (!noAnchor || !/\.md$/i.test(noAnchor)) return null;
+  const fromDir = fromRel.includes('/') ? fromRel.slice(0, fromRel.lastIndexOf('/')) : '.';
+  const resolved = path.posix.normalize(path.posix.join(fromDir, noAnchor));
+  return resolved.startsWith('..') ? null : resolved;
+}
+
+function renderDocMapLines() {
+  const L = [];
+  let files;
+  try { files = docsEntropy.collectMarkdownFiles(); } catch { return L; }
+  const fileSet = new Set(files);
+
+  L.push('');
+  L.push('## Documentation map — link-graph + staleness (task 2013)');
+  L.push('');
+  L.push('> Generated from the same detectors as `docs-entropy.js`. The link-graph lets an agent see a key doc\'s outbound doc-links without opening it; the staleness flags surface docs whose internal links/anchors no longer resolve — the anti-drift signal that replaces the manual "remember to update the detail files" chore.');
+  L.push('');
+
+  // Link-graph for the curated key docs.
+  L.push('### Key-doc link-graph');
+  L.push('');
+  L.push('| doc | links to |');
+  L.push('|---|---|');
+  for (const doc of KEY_DOCS) {
+    if (!fileSet.has(doc)) continue;
+    let parsed;
+    try { parsed = docsEntropy.parseFile(path.join(INSTANCE_ROOT, doc)); } catch { parsed = null; }
+    if (!parsed) { try { parsed = docsEntropy.parseFile(path.join(CORE_ROOT, doc)); } catch { parsed = null; } }
+    const targets = new Set();
+    for (const lk of (parsed && parsed.links) || []) {
+      const t = resolveDocLink(doc, lk.href);
+      if (t && t !== doc && fileSet.has(t)) targets.add(t);
+    }
+    const list = [...targets].sort();
+    const shown = list.slice(0, 12).map((t) => `\`${t}\``).join(', ');
+    const more = list.length > 12 ? ` _(+${list.length - 12} more)_` : '';
+    L.push(`| \`${doc}\` | ${list.length ? shown + more : '—'} |`);
+  }
+  L.push('');
+
+  // Staleness flags: docs with unresolved internal links/anchors.
+  let findings = [];
+  try { findings = docsEntropy.scanStaleLinks(files) || []; } catch { findings = []; }
+  const byFile = new Map();
+  for (const f of findings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+  L.push('### Docs needing a touch-up (staleness flags)');
+  L.push('');
+  if (byFile.size === 0) {
+    L.push('_None — every tracked doc\'s internal links + anchors resolve._');
+  } else {
+    L.push(`${byFile.size} doc(s) carry an unresolved internal link or anchor (top 25 by count):`);
+    L.push('');
+    L.push('| doc | unresolved links |');
+    L.push('|---|---|');
+    const rows = [...byFile.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, 25);
+    for (const [file, fs2] of rows) L.push(`| \`${file}\` | ${fs2.length} |`);
+  }
+  L.push('');
+  return L;
+}
+
+// ---- rendering: nested-doc generated block ---------------------------------
+
+function renderNestedBlock(model, dir) {
+  const prefix = dir.endsWith('/') ? dir : dir + '/';
+  const here = model.byFile
+    .filter((f) => {
+      const d = f.rel.includes('/') ? f.rel.slice(0, f.rel.lastIndexOf('/')) : '.';
+      return d === dir; // non-recursive: files directly in this dir
+    })
+    .sort((a, b) => a.rel.localeCompare(b.rel));
+  const L = [];
+  L.push(BEGIN);
+  L.push(`**Symbol skeleton (generated from the code — do not hand-edit; refresh: \`node scripts/bongos/gen-repo-map.js\`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](${path.relative(path.join(REPO_ROOT, dir), path.join(REPO_ROOT, 'docs/adr/0063-generated-repo-map-symbol-skeleton.md')).split(path.sep).join('/')})).`);
+  L.push('');
+  for (const f of here) {
+    const { list, pool } = pickForFile(f);
+    if (!list.length) continue;
+    const base = f.rel.slice(prefix.length);
+    const more = pool - list.length;
+    L.push(`- \`${base}\` — ${list.map((s) => '`' + fmtSig(s) + '`').join(', ')}${more > 0 ? ` _(+${more} more)_` : ''}`);
+  }
+  L.push(END);
+  return L.join('\n');
+}
+
+function injectBlock(existing, block) {
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + block + existing.slice(e + END.length);
+  }
+  // insert before "**See also.**" if present, else append
+  const anchor = existing.indexOf('**See also.**');
+  if (anchor !== -1) {
+    return existing.slice(0, anchor) + block + '\n\n' + existing.slice(anchor);
+  }
+  return existing.replace(/\n*$/, '') + '\n\n' + block + '\n';
+}
+
+// ---- main ------------------------------------------------------------------
+
+function main() {
+  // Two artifact BUCKETS, gated separately since ADR 0110 (task 1926):
+  //   • 'whole' — docs/repo-map.md, which is now GITIGNORED and regenerated at
+  //     deploy (the gen-atlas.js model), so it carries no
+  //     committed copy and two parallel branches can never collide on it.
+  //   • 'block' — the generated symbol BLOCK inside each nested CLAUDE.md, which
+  //     stays hand-written prose + a tracked block, so it MUST stay fresh in git.
+  // `--check`       → both buckets (back-compat; a full local sanity check).
+  // `--check-block` → block bucket only (the HARD per-PR CI gate in fitness.js).
+  // `--check-whole` → whole-file bucket only (used by nothing hard; deploy owns it).
+  const checkAll = process.argv.includes('--check');
+  const checkWhole = process.argv.includes('--check-whole');
+  const checkBlock = process.argv.includes('--check-block');
+  // WRITE-side bucket selection, the sibling of the --check-* flags above (task
+  // 1002962). --whole-only regenerates the GITIGNORED docs/repo-map.md and leaves
+  // the TRACKED nested blocks alone.
+  //
+  // WHY a caller ever needs this: a SPARSE checkout materializes only part of the
+  // tree. The block ordering is `b.refs - a.refs || name`, and `refs` counts
+  // references across the VISIBLE corpus — so a checkout with 7 of 20 modules
+  // computes different counts and emits a legitimately different block. Written
+  // into a tracked file that dirties the working tree, and the NEXT `git pull`
+  // aborts with "local changes would be overwritten" — a silent, permanent sync
+  // deadlock (one checkout sat 257 commits behind for three days). A sparse
+  // checkout CONSUMES these blocks; they arrive correct with the pull, generated
+  // by CI from the whole tree. Only a full checkout may produce them.
+  const wholeOnly = process.argv.includes('--whole-only');
+  const model = buildModel();
+
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(model, null, 2) + '\n');
+    return;
+  }
+
+  const writes = [];
+  // 1) docs/repo-map.md (whole-file; gitignored since ADR 0110 — a `write` here on a
+  //    fresh checkout just means "absent, would be created", which is expected)
+  const mapPath = path.join(REPO_ROOT, 'docs', 'repo-map.md');
+  const mapNext = renderRepoMap(model);
+  const mapCur = fs.existsSync(mapPath) ? fs.readFileSync(mapPath, 'utf8') : '';
+  if (!sameContent(mapCur, mapNext)) writes.push({ full: mapPath, content: mapNext, rel: 'docs/repo-map.md', bucket: 'whole' });
+
+  // 2) nested CLAUDE.md generated blocks (tracked; the HARD-gated bucket).
+  //     Skipped entirely under --whole-only — see the flag's rationale above.
+  for (const dir of (wholeOnly ? [] : NESTED_DIRS)) {
+    const docPath = path.join(REPO_ROOT, dir, 'CLAUDE.md');
+    if (!fs.existsSync(docPath)) {
+      console.error(`gen-repo-map: WARN nested doc missing, skipping: ${dir}/CLAUDE.md`);
+      continue;
+    }
+    const cur = fs.readFileSync(docPath, 'utf8');
+    const next = injectBlock(cur, renderNestedBlock(model, dir));
+    if (!sameContent(cur, next)) writes.push({ full: docPath, content: next, rel: `${dir}/CLAUDE.md`, bucket: 'block' });
+  }
+
+  if (checkAll || checkWhole || checkBlock) {
+    const wantBlock = checkAll || checkBlock;
+    const wantWhole = checkAll || checkWhole;
+    const stale = writes.filter((w) => (w.bucket === 'block' && wantBlock) || (w.bucket === 'whole' && wantWhole));
+    if (stale.length) {
+      console.error(`gen-repo-map ${checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check'}: STALE — would update ${stale.map((w) => w.rel).join(', ')}`);
+      console.error('  run: node scripts/bongos/gen-repo-map.js  (and commit any TRACKED files it changes)');
+      process.exit(2);
+    }
+    console.log(`gen-repo-map ${checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check'}: up to date.`);
+    return;
+  }
+
+  if (!writes.length) {
+    console.log('gen-repo-map: repo map already current — no changes.');
+    return;
+  }
+  for (const w of writes) fs.writeFileSync(w.full, w.content);
+  console.log(`gen-repo-map: wrote ${writes.length} file(s): ${writes.map((w) => w.rel).join(', ')}`);
+}
+
+if (require.main === module) main();
+
+// Exported so the git merge driver / ship self-heal (scripts/bongos/git-merge-regen.js,
+// task 1243) can regenerate a generated file's content from the MERGED working-tree
+// code WITHOUT shelling out or re-parsing stdout. The require.main guard above keeps
+// `require('./gen-repo-map')` side-effect-free (it no longer runs main()).
+module.exports = { BEGIN, END, NESTED_DIRS, buildModel, renderRepoMap, renderNestedBlock, injectBlock };

package/scripts/bongos/gen-role-responsibilities.js

@@ -0,0 +1,134 @@
+// scripts/bongos/gen-role-responsibilities.js
+//
+// WHAT. Writes each craft's written responsibility into its role pack under
+// docs/packs/, between markers, from the ONE source at src/role-responsibilities.js.
+//
+// WHY A GENERATOR AND NOT A PARAGRAPH SOMEONE TYPES. Criterion
+// wa6-written-responsibilities (goal 1000095) says there is one source "shown on
+// the profile, injected into the pack, referenced by grading". The profile and the
+// grader read the source at runtime, so they cannot drift. A markdown pack cannot
+// require a JS module, so its copy is the only one that CAN drift — and the drift
+// would be invisible and consequential: the pack is what a session is actually
+// instructed by, so a stale sentence there means the project teaches one standard,
+// shows a second on the profile, and grades against a third. This is the
+// gen-diagrams / gen-session-index pattern (ADR 0062 §8): generate the block, gate
+// its freshness in CI, never hand-edit it.
+//
+// USAGE
+//   node scripts/bongos/gen-role-responsibilities.js            # write the blocks
+//   node scripts/bongos/gen-role-responsibilities.js --check    # exit 2 if any block drifted (the CI gate)
+//
+// A pack with no markers is a WARNING, not a failure — a host instance may carry a
+// pack this core does not know about. A pack whose marker block is STALE is the
+// hard failure, because that is the drift the whole file exists to prevent.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ROLE_RESPONSIBILITIES, RESPONSIBILITIES_SOURCE } = require('../../src/role-responsibilities');
+const { resolveCoreRoot } = require('../../src/instance-config');
+
+// The packs are CORE content (they ship in the package alongside the registry that
+// names them), so resolve them against the core root the same way the role-pack
+// guard does — never the instance root.
+const CORE_ROOT = resolveCoreRoot();
+const REGISTRY_REL = 'scripts/bongos/discipline-modes.json';
+
+const BEGIN = '<!-- BEGIN GENERATED ROLE RESPONSIBILITY (scripts/bongos/gen-role-responsibilities.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED ROLE RESPONSIBILITY -->';
+
+// The block a pack carries. Deliberately short: the pack teaches the craft, this
+// states the standard, and the provenance line is there so a reader knows the
+// sentence is the owner's and not the platform's opinion.
+function blockFor(discipline) {
+  const text = ROLE_RESPONSIBILITIES[discipline];
+  if (!text) return null;
+  const s = RESPONSIBILITIES_SOURCE;
+  return [
+    BEGIN,
+    '## What this craft is answerable for',
+    '',
+    `> ${text}`,
+    '',
+    `*The ${discipline}'s written responsibility — one source (\`src/role-responsibilities.js\`), shown on the hall profile, taught here, and referenced by the grader. Fixed by ${s.authoredBy} on ${s.authoredOn}, criterion \`${s.criterion}\`. Generated: do not hand-edit, and do not paraphrase it elsewhere.*`,
+    END,
+  ].join('\n');
+}
+
+// Replace the marked region, or report that the pack has no markers. Mirrors
+// gen-session-index.injectBlock: bounded by the two literal markers, so a pack may
+// put the block anywhere and move it later without touching this file.
+//
+// THE BLOCK TAKES THE FILE'S OWN LINE ENDING. These packs are `.md` and check out
+// CRLF on Windows while CI checks out LF. A generator that always wrote '\n' would
+// splice LF lines into a CRLF file, so the committed bytes and the bytes `--check`
+// recomputes would differ by platform — the check would be red on one checkout and
+// green on the other, for a file nobody touched. Detecting the file's ending makes
+// the generator idempotent on both.
+function inject(text, block) {
+  const i = text.indexOf(BEGIN);
+  const j = text.indexOf(END);
+  if (i === -1 || j === -1 || j < i) return null;
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  return text.slice(0, i) + block.replace(/\n/g, eol) + text.slice(j + END.length);
+}
+
+// Every discipline the role registry binds to a pack. Reading the registry rather
+// than hardcoding three filenames means a pack that is renamed, or a fourth craft
+// that is added later (Governor, when the owner decides), is picked up here with no
+// edit — the same single-declaration rule the registry already enforces for claim.js.
+function packTargets() {
+  const abs = path.join(CORE_ROOT, REGISTRY_REL);
+  const modes = (JSON.parse(fs.readFileSync(abs, 'utf8')) || {}).modes || {};
+  const out = [];
+  for (const [discipline, mode] of Object.entries(modes)) {
+    if (!mode || !mode.pack) continue;
+    out.push({ discipline, rel: mode.pack, abs: path.join(CORE_ROOT, mode.pack) });
+  }
+  return out;
+}
+
+function plan() {
+  const writes = [];
+  const warnings = [];
+  for (const t of packTargets()) {
+    const block = blockFor(t.discipline);
+    if (!block) {
+      // A pack whose craft has no statement is legitimate (a module-contributed
+      // craft that grew a pack). Say so; never write an empty quote into it.
+      warnings.push(`${t.rel}: no written responsibility for '${t.discipline}' — leaving the pack alone.`);
+      continue;
+    }
+    let cur;
+    try { cur = fs.readFileSync(t.abs, 'utf8'); } catch {
+      warnings.push(`${t.rel}: named by the role registry but not readable — the role-pack guard is the check that fails on this.`);
+      continue;
+    }
+    const next = inject(cur, block);
+    if (next === null) { warnings.push(`${t.rel}: no marker block — add the BEGIN/END pair to carry the statement.`); continue; }
+    if (next !== cur) writes.push({ abs: t.abs, rel: t.rel, content: next });
+  }
+  return { writes, warnings };
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const { writes, warnings } = plan();
+  for (const w of warnings) console.error(`gen-role-responsibilities: WARN ${w}`);
+  if (check) {
+    if (writes.length) {
+      for (const w of writes) console.error(`gen-role-responsibilities: STALE ${w.rel}`);
+      console.error('Run `node scripts/bongos/gen-role-responsibilities.js` and commit.');
+      process.exit(2);
+    }
+    console.log('gen-role-responsibilities --check: up to date.');
+    return;
+  }
+  for (const w of writes) fs.writeFileSync(w.abs, w.content);
+  console.log(writes.length ? `gen-role-responsibilities: wrote ${writes.length} pack(s): ${writes.map((w) => w.rel).join(', ')}` : 'gen-role-responsibilities: already up to date.');
+}
+
+if (require.main === module) main();
+
+module.exports = { BEGIN, END, blockFor, inject, packTargets, plan };