@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/me.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// scripts/bongos/me.js — "who am I, and what am I holding?" from the terminal
+// (ADR 0095 backfill).
+//
+// WHY. A builder's identity lives on the SERVER (rank is read fresh from the DB on
+// every request — ADR 0016), so a local file can never answer this honestly. This
+// CLI asks the API instead: profile + rank, the leaderboard top 10, and — the part
+// that actually matters mid-session — the ACTIVE CLAIM, so an agent resuming work
+// can confirm what it is allowed to be changing before it changes anything.
+//
+// Read-only. It prints; it never mutates a claim (that is `claim.js`/`ship.js`).
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+(async () => {
+  await requireSession();
+  const api = await cliClient();
+  const me = await api.me.getMe();
+  if (!me.ok) {
+    console.error('me failed:', me.data);
+    process.exit(1);
+  }
+  const lb = await api.leaderboard.getLeaderboard();
+
+  const b = me.data.builder;
+  const rankLabel = b.rank ? b.rank.charAt(0).toUpperCase() + b.rank.slice(1) : 'Thetes';
+  console.log(`${b.display_name} (@${b.github_login})`);
+  console.log(`Builder #${b.id}  ·  ${rankLabel}  ·  ${b.total_credits} credits`);
+  // V3 auth-flow slice 1: the /me call we just made succeeded, which means the
+  // session is valid AND just rolled forward (mig 035 refreshes expires_at to
+  // NOW()+1h on every authenticated request). Surface that so 1h-rolling is
+  // visible to the builder rather than being silent infrastructure.
+  console.log(`Session valid — auto-refreshes on every API call (1h rolling TTL).`);
+
+  // Streak panel — shown only when current streak > 0 (per task spec).
+  const s = me.data.streak;
+  if (s && s.current > 0) {
+    console.log('');
+    console.log(`Streak: ${s.current} day${s.current === 1 ? '' : 's'}  🔥 (longest: ${s.longest})`);
+    if (s.last_ship_day) {
+      console.log(`Last ship-day: ${s.last_ship_day}${s.today === s.last_ship_day ? ' (today)' : ''}`);
+    }
+  }
+
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  if (claims.length === 0) {
+    console.log('');
+    console.log('No active claims.');
+  } else {
+    console.log('');
+    console.log(`Active claim${claims.length > 1 ? 's' : ''} (${claims.length}):`);
+    for (const c of claims) {
+      console.log(`  #${c.task_id} ${c.title}`);
+      console.log(`    Version: ${c.version_id} · P${c.priority ?? '?'} · ${c.credits_reward}c reward`);
+      console.log(`    Claimed: ${new Date(c.claimed_at).toLocaleString()}`);
+      if (c.worktree_name) console.log(`    Worktree: ${c.worktree_name}`);
+      // Streak preview — only when qualifying + extending (skip the noisy
+      // "today-already-counted" + "task-not-found" cases).
+      const sp = c.streak_preview;
+      if (sp && sp.qualifies && sp.projected_streak > sp.current_streak) {
+        console.log(`    🔥 Shipping this would extend streak to ${sp.projected_streak} day${sp.projected_streak === 1 ? '' : 's'}`);
+      }
+    }
+  }
+
+  // Recent quality grades (task 197). Surface only when the builder has at
+  // least one graded task so a fresh builder sees no empty section.
+  const grades = me.data.grades || {};
+  const recent = grades.recent || [];
+  const rolling = grades.rolling || {};
+  if (recent.length > 0) {
+    console.log('');
+    console.log('Recent quality marks (last 5):');
+    for (const g of recent) {
+      const verdict = g.passed ? 'PASS' : 'FAIL';
+      const dateStr = new Date(g.graded_at).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+      console.log(`  ${dateStr}  #${g.task_id}  ${Number(g.score).toFixed(1)}/10  ${verdict}  ${g.title || ''}`);
+    }
+    if (Number(rolling.n) > 0) {
+      const avg = Number(rolling.avg_score).toFixed(1);
+      console.log(`  14-day avg: ${avg}/10 across ${rolling.n} task${rolling.n === 1 ? '' : 's'} (${rolling.n_passed} passed)`);
+    }
+  }
+
+  if (lb.ok) {
+    console.log('\nLeaderboard (top 10):');
+    let i = 1;
+    for (const row of (lb.data.leaderboard || []).slice(0, 10)) {
+      const me = row.id === b.id ? ' ← you' : '';
+      console.log(`  ${i.toString().padStart(2)}. ${row.display_name} (@${row.github_login}) — ${row.total_credits}c${me}`);
+      i++;
+    }
+  }
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/bongos/memory-map.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// memory-map.js — keep the always-loaded memory MAP (MEMORY.md) light.
+//
+// MEMORY.md is the index the Claude Code harness loads IN FULL every session:
+// one line per memory → its topic file (the full fact). The topic files are the
+// "drawer" — they live on disk, sync to the GDS server (builder_memory), and are
+// searchable via /recall (ADR 0060), so they cost nothing until something fetches
+// them. The map is the only part paid for every session, so it must stay small.
+//
+// Nothing kept it small, so it re-bloated until the harness's ~24.4KB truncation
+// fired (too late — by then it was dropping lines). This module is the cure
+// (task 1362): a budget GUARD + an auto-TIDY that demotes the oldest non-rule
+// entries out of the map. **Demote = delete the entry's LINE from MEMORY.md only;
+// the topic file is never touched** — it stays on disk + server + /recall, one
+// query away. Standing rules (feedback_*/user memories) are never demoted.
+//
+// This file holds the PURE, testable logic. The session-start hook
+// (.claude/hooks/pull-memory.js) calls it; the actual file write is done by the
+// caller so it can be parallel-safe (optimistic: skip if the file changed since
+// read — the builder runs many concurrent sessions).
+
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnv } = require('../../src/instance-config');
+
+// Budgets, in bytes of MEMORY.md (~4 chars/token for markdown prose).
+const WARN_BYTES = 16000;   // ~4K tok — drifting up; warn so it gets tidied.
+const TIDY_BYTES = 20000;   // ~5K tok — auto-compact kicks in (still well under the ~24.4KB harness truncation).
+const TARGET_BYTES = 13000; // ~3.25K tok — compact back to about here.
+const MAX_LINE_CHARS = 280; // an index line past this has slipped the "one line" rule.
+const KEEP_NEWEST = 25;     // newest non-rule entries always kept in the map.
+
+const estTokens = (bytes) => Math.round(bytes / 4);
+
+// A map entry is a top-level bullet linking a topic file:
+//   - [Title](some-file.md) — one-line hook
+const ENTRY_RE = /^- \[([^\]]*)\]\(([A-Za-z0-9_-]+\.md)\)/;
+
+// Parse MEMORY.md into ordered entries. Non-entry lines (blank, headers) are
+// preserved positionally as { raw, entry:false } so render() can't drop them.
+function parseLines(text) {
+  return text.split('\n').map((raw) => {
+    const m = raw.match(ENTRY_RE);
+    return m ? { raw, entry: true, title: m[1], file: m[2], len: raw.length } : { raw, entry: false };
+  });
+}
+
+function entries(text) {
+  return parseLines(text).filter((l) => l.entry);
+}
+
+// Measure the map: size, token estimate, count, and any over-long lines.
+function measure(text) {
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const es = entries(text);
+  const longLines = es.filter((e) => e.len > MAX_LINE_CHARS).map((e) => ({ file: e.file, len: e.len }));
+  return {
+    bytes,
+    tokens: estTokens(bytes),
+    count: es.length,
+    longLines,
+    overWarn: bytes > WARN_BYTES,
+    overTidy: bytes > TIDY_BYTES,
+  };
+}
+
+// type/mtime for a topic file. feedback_* and `user`-type memories are STANDING
+// RULES — never demoted. Everything else is demotable by age.
+function metaOf(file, memoryDir, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const stat = deps.stat || ((p) => fs.statSync(p));
+  let type = /^feedback_/.test(file) ? 'feedback' : 'unknown';
+  let mtime = 0;
+  let pin = false;
+  const abs = path.join(memoryDir, file);
+  try {
+    mtime = stat(abs).mtimeMs;
+    const fm = readFile(abs).match(/^---\n([\s\S]*?)\n---/);
+    if (fm) {
+      if (type === 'unknown') {
+        const t = fm[1].match(/(?:^|\n)\s*type:\s*([a-z]+)/);
+        if (t) type = t[1];
+      }
+      // `pin: true` in frontmatter marks an entry the owner always wants on the
+      // home screen — kept regardless of age or budget (e.g. the live-version
+      // pointer, standing security alerts).
+      pin = /(?:^|\n)\s*pin:\s*(?:true|yes)\b/i.test(fm[1]);
+    }
+  } catch { /* missing file → treat as demotable, oldest */ }
+  return { type, mtime, pin };
+}
+
+const isRule = (type) => type === 'feedback' || type === 'user';
+// Never demoted: a standing rule (feedback_*/user) OR an explicitly pinned entry.
+const keepAlways = (meta) => isRule(meta.type) || !!meta.pin;
+
+// Decide what stays in the map and what gets demoted to the drawer.
+// Keep: every standing rule + the newest `keepNewest` of the rest; then, if still
+// over targetBytes, demote more from the oldest kept until under target.
+// Rules are NEVER demoted. Returns { newText, demote:[{file,title}], willChange }.
+function planCompaction(text, opts = {}) {
+  const memoryDir = opts.memoryDir;
+  const targetBytes = opts.targetBytes ?? TARGET_BYTES;
+  const keepNewest = opts.keepNewest ?? KEEP_NEWEST;
+  const meta = opts.metaOf || ((file) => metaOf(file, memoryDir, opts.deps));
+
+  const lines = parseLines(text);
+  const es = lines.filter((l) => l.entry);
+  const enriched = es.map((e) => ({ ...e, ...meta(e.file) }));
+
+  const rules = new Set(enriched.filter((e) => keepAlways(e)).map((e) => e.file));
+  const others = enriched.filter((e) => !keepAlways(e)).sort((a, b) => b.mtime - a.mtime); // newest first
+  const keptOthers = others.slice(0, keepNewest);
+  const demote = new Map(others.slice(keepNewest).map((e) => [e.file, e.title]));
+
+  // Still over target? Demote more from the OLDEST end of the kept others.
+  const sizeIfKept = () => {
+    const drop = new Set(demote.keys());
+    return Buffer.byteLength(lines.filter((l) => !(l.entry && drop.has(l.file))).map((l) => l.raw).join('\n') + '\n', 'utf8');
+  };
+  for (let i = keptOthers.length - 1; i >= 0 && sizeIfKept() > targetBytes; i--) {
+    demote.set(keptOthers[i].file, keptOthers[i].title);
+  }
+
+  const drop = new Set(demote.keys());
+  const keptLines = lines.filter((l) => !(l.entry && drop.has(l.file)));
+  const newText = keptLines.map((l) => l.raw).join('\n').replace(/\n*$/, '') + '\n';
+  return {
+    newText,
+    demote: [...demote.entries()].map(([file, title]) => ({ file, title })),
+    willChange: drop.size > 0,
+    keptCount: keptLines.filter((l) => l.entry).length,
+    ruleCount: rules.size,
+  };
+}
+
+// Parallel-safe apply: only write if the file on disk still matches what we read
+// (another concurrent session may have just rewritten it — don't clobber it).
+function applyCompaction(mapPath, expectedText, newText, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const writeFile = deps.writeFile || ((p, c) => fs.writeFileSync(p, c));
+  let current;
+  try { current = readFile(mapPath); } catch { return { written: false, reason: 'missing' }; }
+  if (current !== expectedText) return { written: false, reason: 'changed-since-read' };
+  writeFile(mapPath, newText);
+  return { written: true };
+}
+
+module.exports = {
+  WARN_BYTES, TIDY_BYTES, TARGET_BYTES, MAX_LINE_CHARS, KEEP_NEWEST,
+  estTokens, parseLines, entries, measure, metaOf, isRule, keepAlways,
+  planCompaction, applyCompaction,
+};
+
+// CLI: `node scripts/bongos/memory-map.js [--dir <memoryDir>] [--apply]`
+// Prints the measurement + the compaction plan; --apply writes it (parallel-safe).
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const dirArg = args.indexOf('--dir');
+  // <PREFIX>_MEMORY_DIR (BONGOS_ on a vanilla instance; the legacy OTB_ still read).
+  const memoryDir = dirArg >= 0 ? args[dirArg + 1] : resolveEnv('MEMORY_DIR');
+  if (!memoryDir) { console.error('usage: memory-map.js --dir <memoryDir> [--apply]'); process.exit(2); }
+  const mapPath = path.join(memoryDir, 'MEMORY.md');
+  let text; try { text = fs.readFileSync(mapPath, 'utf8'); } catch { console.error('no MEMORY.md at', mapPath); process.exit(0); }
+  const m = measure(text);
+  console.log(`map: ${m.bytes} bytes (~${m.tokens} tok), ${m.count} entries · overWarn=${m.overWarn} overTidy=${m.overTidy} · longLines=${m.longLines.length}`);
+  const plan = planCompaction(text, { memoryDir });
+  if (!plan.willChange) { console.log('nothing to demote — map is within target.'); process.exit(0); }
+  console.log(`would demote ${plan.demote.length} entries to the drawer (topic files kept):`);
+  for (const d of plan.demote) console.log(`  - ${d.file}`);
+  if (args.includes('--apply')) {
+    const r = applyCompaction(mapPath, text, plan.newText);
+    console.log(r.written ? `applied — map now ${Buffer.byteLength(plan.newText)} bytes` : `not written (${r.reason})`);
+  }
+}

package/scripts/bongos/merge-lock.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// CLI wrapper so the /merge-mode skill shares the SAME merge mutex as ship.js's
+// auto-merge (V3.R50 / #269, criterion C6). Before #269 the lock lived inside
+// ship.js, so a manual /merge-mode run could collide with a concurrent ship on
+// the shared main worktree. /merge-mode now acquires this lock before it
+// checks out main + merges, and releases it after deploy.
+//
+// Usage:
+//   node scripts/bongos/merge-lock.js acquire   # blocks up to 30s; exit 0 acquired, 3 if held
+//   node scripts/bongos/merge-lock.js release   # remove a manual hold
+//   node scripts/bongos/merge-lock.js status    # report holder + age
+//
+// The hold is recorded as mode='manual' (pid=0) because the acquiring CLI
+// process exits immediately — there's no long-lived owner. Manual holds are
+// reclaimed by time only (merge-lock.MANUAL_STALE_MS), so an operator who
+// walks away mid-merge doesn't deadlock the queue forever.
+
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+// the merge-lock lib carved to modules/lifecycle/ (BV1.R86); a CLI may require a
+// module directly (outside the kernel boundary — the grading/economy precedent).
+const lock = require('../../modules/lifecycle/merge-lock');
+
+// Resolve the main checkout root regardless of which worktree we're invoked
+// from: dirname of the shared common .git directory. Rename-proof — matches
+// the /merge-mode SKILL.md REPO_ROOT derivation and ship.js's findMainWorktree.
+function mainWorktreeRoot() {
+  const common = execSync('git rev-parse --git-common-dir', {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  const abs = path.isAbsolute(common) ? common : path.resolve(process.cwd(), common);
+  return path.dirname(abs);
+}
+
+const cmd = process.argv[2];
+let root;
+try {
+  root = mainWorktreeRoot();
+} catch (e) {
+  console.error('merge-lock: not a git repo (cannot resolve main worktree):', e.message);
+  process.exit(2);
+}
+
+if (cmd === 'acquire') {
+  // Manual hold: pid=0 (no long-lived owner), reclaimed by time only.
+  const ok = lock.acquire(root, { mode: 'manual', pid: 0, waitMs: 30000 });
+  if (ok) {
+    console.log('merge-lock: acquired (manual hold). Release with `node scripts/bongos/merge-lock.js release` when the merge run is done.');
+    process.exit(0);
+  }
+  console.error('merge-lock: held by another ship or merge run — wait and retry, or run `merge-lock status` to inspect the holder.');
+  process.exit(3);
+} else if (cmd === 'release') {
+  lock.release(root);
+  console.log('merge-lock: released.');
+  process.exit(0);
+} else if (cmd === 'status') {
+  const rec = lock.readLock(root);
+  if (!rec) {
+    console.log('merge-lock: free.');
+    process.exit(0);
+  }
+  const ageS = Math.round((Date.now() - rec.ts) / 1000);
+  const stale = lock.isStale(rec) ? ' (STALE — reclaimable)' : '';
+  console.log(`merge-lock: HELD  mode=${rec.mode}  pid=${rec.pid}  age=${ageS}s${stale}`);
+  process.exit(0);
+} else {
+  console.error('usage: node scripts/bongos/merge-lock.js acquire|release|status');
+  process.exit(2);
+}

package/scripts/bongos/migration-namespace.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+'use strict';
+// migration-namespace.js — cross-repo migration numbering discipline (ADR 0108 §5,
+// configurable-root W5 / task 1885). Pure helpers, no fs/git — trivially testable.
+//
+// PROBLEM. Once the Cloud Bongos core is a pinned npm dependency (ADR 0108), the core
+// repo and the instance repo version INDEPENDENTLY. Each allocates its next migration
+// number by scanning its OWN migrations/ dir (next-number.js: max+1). With a single
+// shared bare `NNN_` namespace they would both pick the SAME "next" (e.g. both 188).
+// migrate.sh keys schema_migrations by the filename STEM (basename minus .sql), so two
+// same-stemmed migrations from different repos are seen as ONE — the second is silently
+// skipped and NEVER applied. That silent-skip is the collision this module prevents.
+//
+// DISCIPLINE. Every migration SOURCE owns a distinct filename namespace, so stems can
+// never collide across sources and each source's allocator counts only its own numbers:
+//   • CORE      (the @bongos/core package's  migrations/*.sql)        → core_NNN_slug.sql
+//   • MODULE    (modules/<key>/migrations/*.sql)                           → <key>_NNN_slug.sql   (key: art-pipeline → art_pipeline_)
+//   • INSTANCE  (the host repo's                   migrations/instance/*.sql) → NNN_slug.sql        (BARE — the instance owns the bare namespace)
+//
+// The core prefix ALONE is enough to break stem-equality with a bare instance file
+// (`core_188_x` ≠ `188_x`), so the instance keeps the zero-ceremony bare form its seeds
+// already use. Modules were already `<key>_`-prefixed by convention (economy_001_,
+// lifecycle_001_); this makes it a rule for NEW module migrations.
+//
+// GRANDFATHER. Every migration that existed when this discipline landed (task 1885) is
+// bare and already recorded in schema_migrations by its bare stem — renaming one would
+// make migrate.sh re-run it (a from-scratch replay must still match history). So existing
+// bare files are grandfathered and the rule applies only to NEW migrations: a bare CORE
+// file numbered above LEGACY_BARE_CORE_MAX, or a bare migration in a non-legacy MODULE.
+// New prefixed files sort AFTER the legacy block (a letter sorts after a digit in the
+// basename merge-sort), which is the correct "newer applies later" order.
+//
+// ORDER OF APPLICATION (migrate.sh). Core + instance are merge-sorted by basename, so all
+// `core_*` files apply before all bare instance files (and before instance's own new
+// files). That matches the only real dependency direction — instance seeds read core
+// schema, never the reverse. Modules apply in their own later pass, keyed by stem.
+
+// ---- namespaces ------------------------------------------------------------
+
+const CORE_NS = 'core';
+const INSTANCE_NS = 'instance';
+// Reserved namespace words a module key may not be (they name the core/instance sources).
+const RESERVED_NS = new Set([CORE_NS, INSTANCE_NS]);
+
+// SQL/filename-safe namespace prefix for a module key: art-pipeline → art_pipeline (matches
+// fitness.js moduleNamespace + the existing economy_/lifecycle_ files).
+function sqlNamespace(moduleKey) {
+  return String(moduleKey == null ? '' : moduleKey).replace(/-/g, '_');
+}
+
+// Highest bare-numbered CORE migration when the discipline landed (W5 / task 1885). New
+// core migrations are `core_`-prefixed, so no bare core file can ever exceed this — the
+// cutoff never advances. Bare core files ≤ this are legacy (already applied) and allowed.
+const LEGACY_BARE_CORE_MAX = 187;
+
+// Modules whose migrations predate the `<key>_` filename convention (bare NNN_). New
+// module migrations must be `<key>_`-prefixed; these stay bare (already applied on prod).
+const LEGACY_BARE_MODULES = new Set(['game', 'demo']);
+
+// RENAMED_MODULE_PREFIXES: a module whose KEY was renamed keeps its historical
+// migration-filename prefix for files that were already applied. schema_migrations
+// is keyed by filename STEM, so renaming an applied migration makes it look
+// unapplied and RE-RUNS it — and a re-run seed/backfill is a data event, not a
+// no-op. The already-applied files therefore keep the old prefix forever; only
+// NEW migrations must carry the module's current namespace.
+//   government <- governance (ADR 0174, goal 1000068)
+const RENAMED_MODULE_PREFIXES = { government: new Set(['governance']) };
+
+// ---- parsing ---------------------------------------------------------------
+
+const BARE_RE = /^(\d{3,})_(.+)\.sql$/;
+// A prefix is a lowercase word (letters/digits/underscores) starting with a letter,
+// then `_NNN_`. Lazy so `art_pipeline_003_x` splits as prefix=art_pipeline, num=003 (not art/pipeline).
+const PREFIXED_RE = /^([a-z][a-z0-9_]*?)_(\d{3,})_(.+)\.sql$/;
+
+// Parse a migration basename into { prefix, number, slug, bare, ok }. A non-migration
+// name (README, .keep, a .txt) returns { ok: false }. Bare files (leading digit) parse
+// with prefix=null; prefixed files carry their namespace prefix.
+function parseMigrationName(basename) {
+  const s = String(basename == null ? '' : basename);
+  let m = BARE_RE.exec(s);
+  if (m) return { prefix: null, number: parseInt(m[1], 10), slug: m[2], bare: true, ok: true };
+  m = PREFIXED_RE.exec(s);
+  if (m) return { prefix: m[1], number: parseInt(m[2], 10), slug: m[3], bare: false, ok: true };
+  return { prefix: null, number: null, slug: null, bare: false, ok: false };
+}
+
+// The migration number in a basename (bare or prefixed), or null if not a migration.
+function migrationNumberOf(basename) {
+  const p = parseMigrationName(basename);
+  return p.ok ? p.number : null;
+}
+
+// ---- filename discipline ---------------------------------------------------
+
+const pad3 = (n) => String(n).padStart(3, '0');
+
+// For ONE migration file, return a violation string or null. `source` is one of
+// 'core' | 'instance' | 'module'; for 'module' pass { moduleKey }.
+function filenameViolation(source, basename, { moduleKey } = {}) {
+  const p = parseMigrationName(basename);
+  if (!p.ok) return null; // not a migration file — ignore (a .keep, a README)
+
+  if (source === CORE_NS) {
+    if (p.bare) {
+      return p.number > LEGACY_BARE_CORE_MAX
+        ? `core migration "${basename}" is bare — a NEW core migration must be ${CORE_NS}_-prefixed so its stem can't collide with an instance/module migration across repos (ADR 0108 §5): use ${CORE_NS}_${pad3(p.number)}_${p.slug}.sql`
+        : null; // legacy bare core ≤ cutoff — grandfathered (already applied)
+    }
+    return p.prefix === CORE_NS
+      ? null
+      : `core migration "${basename}" carries the "${p.prefix}_" prefix — core migrations must be ${CORE_NS}_-prefixed (ADR 0108 §5).`;
+  }
+
+  if (source === INSTANCE_NS) {
+    // The instance owns the BARE namespace; an explicit instance_ prefix is also fine.
+    if (p.bare || p.prefix === INSTANCE_NS) return null;
+    return `instance migration "${basename}" carries the "${p.prefix}_" prefix — instance migrations stay bare (NNN_) or use the ${INSTANCE_NS}_ prefix; "${p.prefix}_" is another source's namespace (ADR 0108 §5).`;
+  }
+
+  // module
+  const ns = sqlNamespace(moduleKey);
+  if (p.bare) {
+    return LEGACY_BARE_MODULES.has(moduleKey)
+      ? null // legacy bare module — grandfathered
+      : `module "${moduleKey}" migration "${basename}" is bare — a NEW module migration must be ${ns}_-prefixed (ADR 0083 §Decision #5 / ADR 0108 §5): use ${ns}_${pad3(p.number)}_${p.slug}.sql`;
+  }
+  if (p.prefix === ns) return null;
+  // A renamed module's already-applied files keep their historical prefix (see
+  // RENAMED_MODULE_PREFIXES) — the stem is the schema_migrations key, so it cannot move.
+  if ((RENAMED_MODULE_PREFIXES[moduleKey] || new Set()).has(p.prefix)) return null;
+  return `module "${moduleKey}" migration "${basename}" carries the "${p.prefix}_" prefix — it must be ${ns}_-prefixed to its own module (ADR 0083 §Decision #5).`;
+}
+
+// ---- cross-root stem-collision detector ------------------------------------
+
+// A stem shared by migrations from ≥2 sources is the silent-skip hazard: migrate.sh
+// applies the first and skips the rest (schema_migrations is stem-keyed). Given a flat
+// list of { source, moduleKey?, basename }, return [{ stem, files:[label/basename,…] }]
+// for every stem produced by more than one distinct source-file.
+function stemCollisions(files) {
+  const byStem = new Map();
+  for (const f of files || []) {
+    if (!parseMigrationName(f.basename).ok) continue;
+    const stem = f.basename.replace(/\.sql$/, '');
+    const label = f.source === 'module' ? `module:${f.moduleKey}` : f.source;
+    if (!byStem.has(stem)) byStem.set(stem, new Set());
+    byStem.get(stem).add(`${label}/${f.basename}`);
+  }
+  const out = [];
+  for (const [stem, set] of byStem) {
+    if (set.size > 1) out.push({ stem, files: [...set].sort() });
+  }
+  return out.sort((a, b) => a.stem.localeCompare(b.stem));
+}
+
+// ---- same-series number-collision detector ---------------------------------
+
+// The stem detector above catches the CROSS-source hazard (one stem, two sources →
+// migrate.sh applies one and silently skips the rest). It deliberately does not care
+// that `core_012_x` and `platform_identity_012_y` share a number: they are separate
+// allocators with separate namespaces, and the comment on lineageReport says so.
+//
+// THE GAP (task 1003646). Two DIFFERENT stems sharing a number inside ONE series is a
+// different bug, and nothing watched it. next-number.js allocates max+1 by scanning the
+// series as it stands at the caller's BRANCH POINT, so two claim sessions that branch
+// before either lands both compute the same "next". On 2026-08-28 that put three files
+// at platform_identity_012 on main. stemCollisions() returns [] for them — the stems
+// differ — so CI was green.
+//
+// WHY IT MATTERS, given nothing is skipped. migrate.sh applies in BASENAME order
+// (scripts/migrate.sh: core+instance merge-sorted by basename; modules by shell glob),
+// so a colliding pair's relative order is decided by the alphabetical accident of its
+// SLUG. On prod they applied in the order the branches merged. On a from-scratch replay
+// — a restore, a fresh instance, the CI replay guard — they apply alphabetically. When
+// those two orders differ, a rebuilt database is not the database that was built, which
+// is the exact hazard migrations/README.md names as "the one rule that has actually
+// bitten us". Nothing detects the divergence, because both databases report every
+// migration applied.
+//
+// The fix is a guard, not a renumber: renaming an applied migration changes its stem,
+// which is the schema_migrations key, so migrate.sh would see it as unapplied and RE-RUN
+// it — the same reason LEGACY_BARE_MODULES and RENAMED_MODULE_PREFIXES exist above.
+// The one pre-existing collision is therefore grandfathered by name, and the guard binds
+// on everything new.
+// Keyed series/number → the exact STEMS that are exempt. Deliberately not a bare
+// series/number exemption: that would also wave through a FOURTH file landing at 012,
+// which is the very bug this detects. Only the already-applied files are forgiven, so
+// the number stays closed to anything new.
+// Seven races that already landed. Every one of these files is applied on prod, and
+// renaming an applied migration changes its schema_migrations stem, so migrate.sh would
+// see it as unapplied and RE-RUN it — the same constraint that produced
+// LEGACY_BARE_MODULES and RENAMED_MODULE_PREFIXES above. They are recorded rather than
+// fixed, and the guard binds on everything new.
+//
+// These are history, not a pattern to copy: the number is the SECOND-oldest of these
+// (067) through to 2026-08-28 (platform_identity 012), i.e. the race has been happening
+// for as long as parallel claims have, which is why a keyword-free structural check is
+// worth having at all.
+const GRANDFATHERED_NUMBER_COLLISIONS = new Map([
+  ['core/(bare)/067', new Set(['067_builder_boxes', '067_discord_bot_foundation'])],
+  ['core/(bare)/176', new Set(['176_promotion_respects_open_blockers', '176_ui_discipline'])],
+  ['core/(bare)/187', new Set(['187_goal_sort_order', '187_tasks_kind_check_add_verify'])],
+  ['core/core/189', new Set(['core_189_core_upgrades_ledger', 'core_189_credit_log_task_id_index'])],
+  ['core/core/223', new Set(['core_223_blocker_resolve_respects_other_open_blockers', 'core_223_task_visual'])],
+  ['core/core/240', new Set(['core_240_artist_gate_indexes', 'core_240_goal_members_drop_legacy_role'])],
+  ['module:platform-identity/platform_identity/012', new Set([
+    // 2026-08-28, the collision task 1003646 was filed for: three parallel sessions each
+    // allocated 012 from its own branch point. Order between them does not matter — they
+    // alter three different tables (platform_identity_accounts, _projects,
+    // _builder_project_activity), so the basename-order vs merge-order divergence has
+    // nothing to bite on here.
+    'platform_identity_012_account_privacy',
+    'platform_identity_012_project_template',
+    'platform_identity_012_recent_ships',
+  ])],
+]);
+
+// Given the same flat { source, moduleKey?, basename } list stemCollisions() takes,
+// return [{ series, number, files:[…] }] for every number carrying >1 distinct stem
+// within ONE series. Grandfathered entries are omitted.
+function numberCollisions(files) {
+  const bySeriesNumber = new Map();
+  for (const f of files || []) {
+    const p = parseMigrationName(f.basename);
+    if (!p.ok) continue;
+    // A SERIES is one allocator's number space, and that is identified by the filename
+    // PREFIX, not by the directory. A renamed module keeps its historical prefix for
+    // already-applied files (RENAMED_MODULE_PREFIXES) and restarts the new prefix at 001,
+    // so modules/government/ holds governance_001…007 beside government_001…007. Those are
+    // two namespaces sharing a directory, not a race: the prefixes sort into separate
+    // contiguous blocks, so their order is fixed and identical on prod and on replay.
+    // Keying by directory would report all seven as collisions and the check would be
+    // wrong seven times before it was right once. moduleKey still participates so that two
+    // LEGACY BARE modules (game, demo) each numbering from 001 do not collide with each other.
+    const owner = f.source === 'module' ? `module:${f.moduleKey}` : f.source;
+    const series = `${owner}/${p.bare ? '(bare)' : p.prefix}`;
+    const key = `${series}/${pad3(p.number)}`;
+    if (!bySeriesNumber.has(key)) bySeriesNumber.set(key, { series, number: p.number, stems: new Map() });
+    // Keyed by STEM, so the same file counted twice is not a collision — only two
+    // genuinely different migrations at one number are.
+    bySeriesNumber.get(key).stems.set(f.basename.replace(/\.sql$/, ''), f.basename);
+  }
+  const out = [];
+  for (const [key, v] of bySeriesNumber) {
+    if (v.stems.size < 2) continue;
+    // Exempt only when EVERY stem at this number is one of the already-applied files.
+    // One unrecognised stem re-opens the whole group, because that new file is exactly
+    // what must not be allowed to sit on a taken number.
+    const allowed = GRANDFATHERED_NUMBER_COLLISIONS.get(key);
+    if (allowed && [...v.stems.keys()].every((stem) => allowed.has(stem))) continue;
+    out.push({ series: v.series, number: v.number, files: [...v.stems.values()].sort() });
+  }
+  return out.sort((a, b) => (a.series === b.series ? a.number - b.number : a.series.localeCompare(b.series)));
+}
+
+// ---- numbering / lineage (mirrors the public-mirror pattern) ---------------
+
+// next free = max + 1; empty starts at `start` (same shape as next-number.js nextFree,
+// re-implemented here so this module stays dependency-free — it is imported by fitness.js
+// on every CI run and by next-number.js, so a require cycle must not form).
+function _nextFree(numbers, start = 1) {
+  let max = -Infinity;
+  for (const n of numbers) if (n > max) max = n;
+  return max === -Infinity ? start : max + 1;
+}
+
+// The next free migration number WITHIN a namespace, from that namespace's basenames.
+function nextInNamespace(basenames) {
+  return _nextFree((basenames || []).map(migrationNumberOf).filter((n) => n != null));
+}
+
+// A lineage report over the three sources: the next free number each source would
+// allocate, plus any cross-root stem collision. Reuses the public-mirror numbering
+// approach (mirror-lineage-check.js) — independent allocators are safe iff the sources
+// are namespaced (so stems can't collide) even when their NUMBERS overlap.
+function lineageReport({ core = [], instance = [], modulesByKey = {} } = {}) {
+  const files = [
+    ...core.map((basename) => ({ source: CORE_NS, basename })),
+    ...instance.map((basename) => ({ source: INSTANCE_NS, basename })),
+    ...Object.entries(modulesByKey).flatMap(([moduleKey, names]) =>
+      (names || []).map((basename) => ({ source: 'module', moduleKey, basename }))),
+  ];
+  const violations = files
+    .map((f) => filenameViolation(f.source, f.basename, { moduleKey: f.moduleKey }))
+    .filter(Boolean);
+  return {
+    nextCore: nextInNamespace(core),
+    nextInstance: nextInNamespace(instance),
+    nextByModule: Object.fromEntries(
+      Object.entries(modulesByKey).map(([k, names]) => [k, nextInNamespace(names)])),
+    collisions: stemCollisions(files),
+    violations,
+    consistent: violations.length === 0 && stemCollisions(files).length === 0,
+  };
+}
+
+module.exports = {
+  CORE_NS,
+  RENAMED_MODULE_PREFIXES,
+  INSTANCE_NS,
+  RESERVED_NS,
+  LEGACY_BARE_CORE_MAX,
+  LEGACY_BARE_MODULES,
+  sqlNamespace,
+  parseMigrationName,
+  migrationNumberOf,
+  filenameViolation,
+  stemCollisions,
+  numberCollisions,
+  nextInNamespace,
+  lineageReport,
+};