@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/repo-metrics.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// repo-metrics.js — the shared measurement substrate for repo cleanliness
+// (V3.R91 / #352, Layer 0 of the code-simplification plan).
+//
+// "You can't manage what you don't measure." This dependency-free CLI shells
+// out to git / wc / knip and emits a JSON snapshot of repo health, then upserts
+// it into repo_health_snapshots (idempotent on calendar date — rerun same day
+// = upsert, not a new row). The latest row feeds /api/bongos/public/repo-health,
+// which renders a trend tile on status.example.com.
+//
+// What the snapshot contains:
+//   - total_loc + loc_by_dir   — tracked JS/MJS line counts, per watched dir
+//   - largest_files            — top-N files by line count
+//   - dead_exports / dead_files — knip unused-export / unused-file counts
+//                                 (NULL when knip is unavailable — graceful)
+//   - stale_branches + max_branch_age_days — unmerged claude/* branch hygiene
+//   - confirmed_unshipped      — tasks verified but not yet on main (the
+//                                merge-mode backlog made visible)
+//
+// Usage:
+//   node scripts/bongos/repo-metrics.js                 # compute + persist + print
+//   node scripts/bongos/repo-metrics.js --json          # print snapshot JSON, persist too
+//   node scripts/bongos/repo-metrics.js --no-write       # compute + print, do NOT touch the DB
+//
+// Exit codes:
+//   0  snapshot computed (and persisted unless --no-write)
+//   1  fatal local error
+//
+// Follow-up (scheduling): the design (plan "Layer 3 — janitor") calls for a
+// WEEKLY scheduled routine (.claude/scheduled-tasks/repo-simplify-sweep/) that
+// runs this script, stores the snapshot, and files findings to idea_inbox.
+// That routine is a separate task; until it lands, run this manually or via
+// any cron that can reach the configured DB. It is safe to run any number of
+// times per day — the upsert collapses to one row per date.
+
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { hasFlag } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TOP_N_LARGEST = 15;
+
+// Directories whose net LOC we track explicitly (matches the plan).
+const WATCHED_DIRS = ['src/', 'public/game/', 'scripts/bongos/', 'modules/art-pipeline/pipeline/'];
+
+
+// Shell helper that never throws — returns trimmed stdout, or null on failure.
+function sh(cmd, opts = {}) {
+  try {
+    return execSync(cmd, {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 32 * 1024 * 1024,
+      ...opts,
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------- per-file size + LOC by directory ----------
+
+// List tracked JS/MJS files via git so untracked scratch + node_modules never
+// leak in. Counts lines with wc-equivalent (read + split) so there is no
+// dependency on `wc` argv-length limits across thousands of files.
+function gatherFileSizes() {
+  const listed = sh("git ls-files '*.js' '*.mjs'");
+  const files = listed ? listed.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  const sizes = [];
+  for (const rel of files) {
+    const abs = path.join(REPO_ROOT, rel);
+    let lines = 0;
+    try {
+      const buf = fs.readFileSync(abs, 'utf8');
+      // Line count = number of newline-separated segments. An empty file is 0;
+      // a file with content but no trailing newline still counts its last line.
+      lines = buf.length === 0 ? 0 : buf.split('\n').length - (buf.endsWith('\n') ? 1 : 0);
+    } catch (_) {
+      continue; // file listed by git but unreadable (deleted mid-run) — skip
+    }
+    sizes.push({ path: rel, lines });
+  }
+  return sizes;
+}
+
+function summarizeSizes(sizes) {
+  const totalLoc = sizes.reduce((acc, f) => acc + f.lines, 0);
+
+  const locByDir = {};
+  for (const dir of WATCHED_DIRS) locByDir[dir] = 0;
+  for (const f of sizes) {
+    for (const dir of WATCHED_DIRS) {
+      if (f.path.startsWith(dir)) {
+        locByDir[dir] += f.lines;
+        break;
+      }
+    }
+  }
+
+  const largest = [...sizes]
+    .sort((a, b) => b.lines - a.lines)
+    .slice(0, TOP_N_LARGEST)
+    .map((f) => ({ path: f.path, lines: f.lines }));
+
+  return { totalLoc, locByDir, largest, fileCount: sizes.length };
+}
+
+// ---------- dead-code / unused-export scan (knip) ----------
+//
+// Depends on R90 having configured knip. We degrade gracefully: if knip is not
+// installed / not configured / errors, dead_exports + dead_files come back
+// NULL and `knip_status` records why, so the rest of the substrate still works.
+function scanDeadCode() {
+  // Is knip even configured? R90 should have added a `knip` block to
+  // package.json and the devDependency. If neither is present, don't even try.
+  let configured = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    configured =
+      !!pkg.knip ||
+      fs.existsSync(path.join(REPO_ROOT, 'knip.json')) ||
+      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc'));
+  } catch (_) {
+    configured = false;
+  }
+  if (!configured) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unconfigured' };
+  }
+
+  // knip --reporter json emits a machine-readable report. Use the locally
+  // installed binary when present; otherwise npx (which may download on first
+  // run). Either way, failures degrade to NULL rather than throwing.
+  const localBin = path.join(REPO_ROOT, 'node_modules', '.bin', 'knip');
+  const runner = fs.existsSync(localBin) ? JSON.stringify(localBin) : 'npx --yes knip';
+  // knip exits non-zero whenever it finds issues, which is the normal case.
+  // Append `|| true` so the shell exit is 0 and sh() returns the JSON stdout;
+  // sh() then only yields null on a genuine spawn failure (knip truly absent).
+  const out = sh(`${runner} --reporter json --no-progress || true`);
+  if (out == null || out === '') {
+    return { dead_exports: null, dead_files: null, knip_status: 'unavailable' };
+  }
+
+  let report;
+  try {
+    report = JSON.parse(out);
+  } catch (_) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unparseable' };
+  }
+
+  // knip v6 JSON shape: { issues: [{ file, files (bool: whole file unused),
+  // exports:[...], types:[...], ... }] }. A top-level `files` array exists in
+  // some reporter modes; handle both. dead_exports sums unused exports+types
+  // across issues; dead_files counts issues whose whole file is unused.
+  let deadFiles = null;
+  let deadExports = null;
+  try {
+    if (Array.isArray(report.issues)) {
+      deadExports = report.issues.reduce((acc, issue) => {
+        const ex = Array.isArray(issue.exports) ? issue.exports.length : 0;
+        const ty = Array.isArray(issue.types) ? issue.types.length : 0;
+        return acc + ex + ty;
+      }, 0);
+      deadFiles = report.issues.reduce(
+        (acc, issue) => acc + (issue.files === true ? 1 : 0),
+        0
+      );
+    }
+    // Some reporter modes additionally surface a flat unused-file list.
+    if (Array.isArray(report.files)) {
+      deadFiles = (deadFiles ?? 0) + report.files.length;
+    }
+    if (deadExports == null && deadFiles == null) {
+      return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+    }
+  } catch (_) {
+    return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  }
+  return { dead_exports: deadExports, dead_files: deadFiles, knip_status: 'ok' };
+}
+
+// ---------- branch hygiene ----------
+//
+// Unmerged claude/* branches (local + remote-tracking), counted distinct by
+// short name, plus the age (in days) of the oldest one's last commit.
+function scanBranchHygiene() {
+  sh('git fetch origin --prune'); // best-effort freshen; null on no network
+
+  // All claude/* refs (local heads + origin remotes), with each ref's last
+  // commit unix timestamp. `for-each-ref` is one cheap call.
+  const raw = sh(
+    "git for-each-ref --format='%(refname:short)|%(committerdate:unix)' refs/heads/claude refs/remotes/origin/claude"
+  );
+  if (raw == null || raw === '') {
+    return { stale_branches: 0, max_branch_age_days: null };
+  }
+
+  // Names already merged into main aren't "unmerged" — compute the merged set
+  // once (two cheap calls) rather than per-branch inside the loop.
+  const mergedSet = new Set();
+  for (const cmd of ['git branch --remotes --merged origin/main', 'git branch --merged origin/main']) {
+    for (const b of (sh(cmd) || '').split('\n')) {
+      const n = b.trim().replace(/^\*?\s*/, '').replace(/^origin\//, '');
+      if (n) mergedSet.add(n);
+    }
+  }
+
+  const now = Date.now() / 1000;
+  const byName = new Map(); // short name (origin/ stripped) → newest commit ts
+  for (const line of raw.split('\n')) {
+    const [ref, tsStr] = line.split('|');
+    if (!ref) continue;
+    const name = ref.replace(/^origin\//, '');
+    if (!name.startsWith('claude/')) continue;
+    const ts = Number(tsStr);
+    if (!Number.isFinite(ts)) continue;
+    if (mergedSet.has(name)) continue; // already on main — not unmerged
+    const prev = byName.get(name);
+    if (prev == null || ts > prev) byName.set(name, ts);
+  }
+
+  if (byName.size === 0) return { stale_branches: 0, max_branch_age_days: null };
+
+  let oldestTs = Infinity;
+  for (const ts of byName.values()) oldestTs = Math.min(oldestTs, ts);
+  const maxAgeDays = Number.isFinite(oldestTs)
+    ? Math.round(((now - oldestTs) / 86400) * 10) / 10
+    : null;
+
+  return { stale_branches: byName.size, max_branch_age_days: maxAgeDays };
+}
+
+// ---------- confirmed-but-unshipped task count ----------
+//
+// Reads directly from the DB (same pool the other scripts/bongos/*.js writers use
+// — peer auth via the local socket on the droplet, PG* env vars elsewhere).
+async function countConfirmedUnshipped(pool) {
+  try {
+    const { rows } = await pool.query(
+      `SELECT COUNT(*)::int AS n FROM tasks WHERE status = 'confirmed'`
+    );
+    return rows[0]?.n ?? 0;
+  } catch (_) {
+    return 0; // DB unreachable (e.g. off-droplet local run without PG*) — 0
+  }
+}
+
+// ---------- persistence ----------
+
+async function upsertSnapshot(pool, snap) {
+  const { rows } = await pool.query(
+    `INSERT INTO repo_health_snapshots
+       (snapshot_date, total_loc, loc_by_dir, largest_files,
+        dead_exports, dead_files, stale_branches, max_branch_age_days,
+        confirmed_unshipped, raw, created_at)
+     VALUES (CURRENT_DATE, $1, $2, $3, $4, $5, $6, $7, $8, $9, now())
+     ON CONFLICT (snapshot_date) DO UPDATE SET
+        total_loc           = EXCLUDED.total_loc,
+        loc_by_dir          = EXCLUDED.loc_by_dir,
+        largest_files       = EXCLUDED.largest_files,
+        dead_exports        = EXCLUDED.dead_exports,
+        dead_files          = EXCLUDED.dead_files,
+        stale_branches      = EXCLUDED.stale_branches,
+        max_branch_age_days = EXCLUDED.max_branch_age_days,
+        confirmed_unshipped = EXCLUDED.confirmed_unshipped,
+        raw                 = EXCLUDED.raw,
+        created_at          = now()
+     RETURNING id, snapshot_date`,
+    [
+      snap.total_loc,
+      JSON.stringify(snap.loc_by_dir),
+      JSON.stringify(snap.largest_files),
+      snap.dead_exports,
+      snap.dead_files,
+      snap.stale_branches,
+      snap.max_branch_age_days,
+      snap.confirmed_unshipped,
+      JSON.stringify(snap),
+    ]
+  );
+  return rows[0];
+}
+
+// ---------- main ----------
+
+(async () => {
+  const args = process.argv.slice(2);
+  const asJson = hasFlag('--json', args);
+  const noWrite = hasFlag('--no-write', args);
+
+  const sizes = gatherFileSizes();
+  const { totalLoc, locByDir, largest, fileCount } = summarizeSizes(sizes);
+  const dead = scanDeadCode();
+  const branches = scanBranchHygiene();
+
+  // Lazy-require the DB so --no-write can run with no Postgres reachable.
+  let confirmedUnshipped = 0;
+  let pool = null;
+  if (!noWrite) {
+    try {
+      ({ pool } = require('../../src/bongos/pool'));
+      confirmedUnshipped = await countConfirmedUnshipped(pool);
+    } catch (_) {
+      pool = null;
+    }
+  }
+
+  const snap = {
+    total_loc: totalLoc,
+    file_count: fileCount,
+    loc_by_dir: locByDir,
+    largest_files: largest,
+    dead_exports: dead.dead_exports,
+    dead_files: dead.dead_files,
+    knip_status: dead.knip_status,
+    stale_branches: branches.stale_branches,
+    max_branch_age_days: branches.max_branch_age_days,
+    confirmed_unshipped: confirmedUnshipped,
+  };
+
+  let written = null;
+  if (!noWrite && pool) {
+    try {
+      written = await upsertSnapshot(pool, snap);
+    } catch (err) {
+      console.error('failed to persist snapshot:', err.message);
+    } finally {
+      await pool.end().catch(() => {});
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ ...snap, persisted: written }, null, 2));
+  } else {
+    console.log('Repo health snapshot');
+    console.log('────────────────────');
+    console.log(`  total tracked JS/MJS LOC : ${totalLoc} across ${fileCount} files`);
+    for (const dir of WATCHED_DIRS) console.log(`    ${dir.padEnd(16)} ${locByDir[dir]} LOC`);
+    console.log(
+      `  dead exports / files     : ${dead.dead_exports ?? '—'} / ${dead.dead_files ?? '—'}  (knip: ${dead.knip_status})`
+    );
+    console.log(
+      `  unmerged claude/* branches: ${branches.stale_branches}` +
+        (branches.max_branch_age_days != null ? ` (oldest ${branches.max_branch_age_days}d)` : '')
+    );
+    console.log(`  confirmed-but-unshipped  : ${confirmedUnshipped}`);
+    console.log(`  top files:`);
+    for (const f of largest.slice(0, 5)) console.log(`    ${String(f.lines).padStart(5)}  ${f.path}`);
+    if (written) {
+      console.log(`\n  ✓ persisted snapshot for ${written.snapshot_date} (row #${written.id})`);
+    } else if (noWrite) {
+      console.log('\n  (--no-write: snapshot not persisted)');
+    } else {
+      console.log('\n  (DB unreachable — snapshot computed but not persisted)');
+    }
+  }
+
+  process.exit(0);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/bongos/review-sheet.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/review-sheet.js — open before/after screenshots for a person to
+// review, as ONE page in their own browser (task 1004202).
+//
+// WHY. Every change to a rendered surface is reviewed by the session's human
+// before it ships — the project default since the owner's 2026-09-23 decision.
+// A terminal shows no images: a screenshot an agent "sends" or reads into its
+// own context never reaches a CLI user's eyes. So the review is a local HTML page
+// of captioned shots, opened with the OS's own opener. Nothing is uploaded.
+//
+// Usage:
+//   node scripts/bongos/review-sheet.js --title "Task 1004200 — graph titles" \
+//     --shot "Before — 1280, light=C:/shots/before.png" \
+//     --shot "After — 1280, light=C:/shots/after.png" \
+//     [--note "One line on what changed."] [--out <dir>] [--no-open]
+//
+// Prints the page's path. Each --shot is "<caption>=<image path>", in order.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { spawn } = require('node:child_process');
+
+function escapeHtml(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+// parseArgs — the flags above; `shots` keep their order. A --shot with no "="
+// is an error, not a guess: the caption and the path cannot be told apart.
+function parseArgs(argv) {
+  const out = { title: 'Visual review', note: '', shots: [], outDir: null, open: true, errors: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-open') { out.open = false; continue; }
+    const v = argv[i + 1];
+    if (a === '--title') { out.title = v; i++; }
+    else if (a === '--note') { out.note = v; i++; }
+    else if (a === '--out') { out.outDir = v; i++; }
+    else if (a === '--shot') {
+      i++;
+      const at = String(v || '').lastIndexOf('=');
+      if (at < 1) out.errors.push(`--shot needs "<caption>=<image path>", got: ${v}`);
+      else out.shots.push({ caption: v.slice(0, at).trim(), file: v.slice(at + 1).trim() });
+    } else out.errors.push(`unknown argument: ${a}`);
+  }
+  if (!out.shots.length) out.errors.push('at least one --shot is required');
+  return out;
+}
+
+// buildReviewPage — the page itself. Images are absolute file:// URLs, so the
+// page works wherever it is written and nothing is copied.
+function buildReviewPage({ title, note, shots }) {
+  const figures = shots.map((s) => `<figure><figcaption>${escapeHtml(s.caption)}</figcaption>`
+    + `<img src="${escapeHtml(pathToFileURL(path.resolve(s.file)).href)}" alt="${escapeHtml(s.caption)}"></figure>`).join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<style>
+  body { margin: 0; padding: 24px; font: 15px/1.5 system-ui, sans-serif; background: #f4f4f5; color: #17181a; }
+  h1 { font-size: 20px; margin: 0 0 6px; }
+  p { margin: 0 0 20px; max-width: 70ch; }
+  figure { margin: 0 0 28px; }
+  figcaption { font-weight: 600; margin-bottom: 6px; }
+  img { display: block; max-width: 100%; border: 1px solid #d4d4d8; border-radius: 8px; }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(title)}</h1>
+${note ? `<p>${escapeHtml(note)}</p>\n` : ''}${figures}
+</body>
+</html>
+`;
+}
+
+function openInBrowser(file) {
+  // `start`'s first quoted argument is a window title, hence the empty "".
+  const [cmd, args] = process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', `"${file}"`]]
+    : process.platform === 'darwin' ? ['open', [file]] : ['xdg-open', [file]];
+  const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsVerbatimArguments: process.platform === 'win32' });
+  child.on('error', () => console.error(`Could not open a browser — open this file yourself: ${file}`));
+  child.unref();
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  const missing = opts.shots.filter((s) => !fs.existsSync(s.file)).map((s) => `no such image: ${s.file}`);
+  const errors = [...opts.errors, ...missing];
+  if (errors.length) {
+    console.error(errors.join('\n'));
+    return 1;
+  }
+  const dir = opts.outDir || fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-review-'));
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'index.html');
+  fs.writeFileSync(file, buildReviewPage(opts));
+  console.log(file);
+  if (opts.open) openInBrowser(file);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { parseArgs, buildReviewPage };

package/scripts/bongos/role-pack-guard.js

@@ -0,0 +1,142 @@
+// scripts/bongos/role-pack-guard.js
+//
+// WHAT. The fitness check behind the kernel/pack split (task 1002990, criterion
+// wa6-kernel-and-packs): every entry in the role registry that names a `pack` must
+// point at a file that exists, and every pack must stay inside a context budget.
+//
+// WHY IT IS A HARD FAIL, when claim.js's own read is fail-open. The registry
+// (scripts/bongos/discipline-modes.json) is read at claim time by code that must never
+// break a granted claim, so a pack path that points at nothing degrades to silence:
+// the builder is told their craft's label and nothing else, and the playbook that
+// was supposed to carry everything the role-neutral kernel dropped never loads. That
+// failure is invisible at runtime by design. CI is therefore the only place it can
+// be caught, which is exactly the split the criterion asks for — "CI budgets each
+// pack" — and why a renamed or deleted pack must red the build rather than quietly
+// hollow out a role.
+//
+// WHY A BUDGET AT ALL. A pack is loaded in full whenever someone works that craft,
+// so it costs the same per-session tokens the root CLAUDE.md does (ADR 0061, the
+// context-rot argument). The kernel got a budget when it was the only always-loaded
+// file; the packs inherit the same discipline now that they carry half its content.
+// The ceilings are advisory-then-hard in the same shape checkClaudeMdBudget uses:
+// a target that WARNS, a ceiling that FAILS, both ratcheted down as detail relocates
+// to ADRs and recipes.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CORE_ROOT } = require('./fitness-lib.js');
+
+// The registry lives beside the CLI that reads it, in the CORE package — the same
+// resolution claim.js uses (path.join(__dirname, 'discipline-modes.json')), so this
+// check and the runtime always read the same file even from a scaffolded instance
+// whose repo root is somewhere else entirely (ADR 0108).
+const REGISTRY_REL = 'scripts/bongos/discipline-modes.json';
+
+// ~4 chars/token for markdown prose, the estimator checkClaudeMdBudget uses.
+const estTokens = (n) => Math.round(n / 4);
+
+// Ratcheted just above the packs as authored by task 1002990 (engineer 12,223,
+// ideator 10,218, artist 6,982 chars). Lower both as pack detail relocates to
+// ADRs and recipes — the same ratchet contract ROOT_CHAR_HARD_MAX carries.
+const PACK_CHAR_HARD_MAX = 16000; // ~4K tokens — a role pack must never balloon past this.
+const PACK_CHAR_TARGET = 13000;   // ~3.25K tokens — aspirational.
+
+function checkRolePacks(fsImpl = fs) {
+  const violations = [];
+  const warnings = [];
+  const abs = path.join(CORE_ROOT, REGISTRY_REL);
+
+  let modes;
+  try {
+    modes = (JSON.parse(fsImpl.readFileSync(abs, 'utf8')) || {}).modes || {};
+  } catch (e) {
+    // Unlike claim.js this does NOT fail open. An unreadable registry is the one
+    // state that makes every other assertion here vacuous, so it is the failure.
+    return {
+      name: 'role registry packs resolve + fit their budget',
+      ok: false,
+      hardFail: true,
+      violations: [`${REGISTRY_REL} could not be read or parsed (${e && e.message}) — claim.js reads this file on every claim and fails open, so a broken registry is silent at runtime and can only be caught here.`],
+      warnings: [],
+      note: 'the role registry could not be read.',
+    };
+  }
+
+  const entries = Object.entries(modes);
+  let packCount = 0;
+  const sizes = [];
+
+  for (const [discipline, mode] of entries) {
+    if (!mode || typeof mode !== 'object') {
+      violations.push(`role registry entry '${discipline}' is not an object — every entry must carry a directive plus a pack or a skill.`);
+      continue;
+    }
+    // An entry with neither pointer routes a claim nowhere: the session is told the
+    // label only and is left to guess its own playbook.
+    if (!mode.pack && !mode.skill) {
+      violations.push(`role registry entry '${discipline}' names neither a 'pack' (docs/packs/<craft>.md) nor a 'skill' — a claim of this discipline would be routed to no playbook at all.`);
+    }
+    if (!mode.pack) continue;
+
+    packCount += 1;
+    const packAbs = path.join(CORE_ROOT, mode.pack);
+    if (!fsImpl.existsSync(packAbs)) {
+      violations.push(`role registry entry '${discipline}' points at '${mode.pack}', which is not in the tree — claim.js would print the path and the session would find nothing there.`);
+      continue;
+    }
+    let text = '';
+    try {
+      text = fsImpl.readFileSync(packAbs, 'utf8');
+    } catch (e) {
+      violations.push(`role registry entry '${discipline}' points at '${mode.pack}', which exists but could not be read (${e && e.message}).`);
+      continue;
+    }
+    const chars = text.length;
+    sizes.push(`${discipline} ${chars}`);
+    if (chars > PACK_CHAR_HARD_MAX) {
+      violations.push(`${mode.pack} is ${chars} chars (~${estTokens(chars)} tokens) — over the ${PACK_CHAR_HARD_MAX}-char (~${estTokens(PACK_CHAR_HARD_MAX)}-token) hard ceiling. A pack loads in full for every session of its craft; relocate detail to an ADR or a recipe (ADR 0061).`);
+    } else if (chars > PACK_CHAR_TARGET) {
+      warnings.push(`${mode.pack} is ${chars} chars (~${estTokens(chars)} tokens) — over the ~${PACK_CHAR_TARGET}-char (~${estTokens(PACK_CHAR_TARGET)}-token) target. Trim prose, then lower PACK_CHAR_TARGET.`);
+    }
+  }
+
+  // Each pack's WRITTEN-RESPONSIBILITY block must match src/role-responsibilities.js
+  // (task 1003732). It lives with the other pack assertions rather than in
+  // checkGeneratedArtifactsFresh so one check owns "the packs are correct" — and the
+  // drift matters for the same reason the missing-pack case does: the profile and
+  // the grader read the source at runtime and cannot drift, but the pack is markdown,
+  // so its copy is the only one that can — and it is the copy a SESSION is instructed
+  // by. A stale block means the project teaches one standard, shows a second on the
+  // profile, and grades against a third. Skipped when the fs is stubbed (the negative
+  // tests inject a registry that names packs this generator would not find).
+  if (fsImpl === fs) {
+    try {
+      const { plan } = require('./gen-role-responsibilities.js');
+      const { writes } = plan();
+      for (const w of writes) {
+        violations.push(`${w.rel}: the written-responsibility block is STALE against src/role-responsibilities.js — run \`node scripts/bongos/gen-role-responsibilities.js\` and commit (task 1003732).`);
+      }
+    } catch (e) {
+      violations.push(`could not check the packs' written-responsibility blocks (${e && e.message}) — run \`node scripts/bongos/gen-role-responsibilities.js --check\`.`);
+    }
+  }
+
+  // The split's own shape, asserted so a later edit cannot quietly drop a craft
+  // back into the kernel: three core packs, and Governor deliberately absent
+  // (criterion wa6-kernel-and-packs — "three packs, not four, until the owner decides").
+  if (packCount < 3) {
+    violations.push(`only ${packCount} craft(s) name a pack — the split is one kernel plus three packs (Engineer, Artist, Ideator). A craft with no pack has nowhere to keep what the role-neutral kernel does not.`);
+  }
+
+  return {
+    name: 'role registry packs resolve + fit their budget',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${entries.length} registry entr(ies), ${packCount} with a pack (${sizes.join(', ') || 'none'} chars) — ≤ ${PACK_CHAR_HARD_MAX} chars each, target ~${PACK_CHAR_TARGET}. A pack path that resolves to nothing is silent at claim time, so CI is the only gate.`,
+  };
+}
+
+module.exports = { checkRolePacks, PACK_CHAR_HARD_MAX, PACK_CHAR_TARGET, REGISTRY_REL };