@bongos/core 1.17.0

package/scripts/gds/audit-authorship.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# scripts/gds/audit-authorship.sh — V3.R12 (#236).
+#
+# Audits the repo for hardcoded references to the original Archon's identity
+# in IMPLEMENTATION code. The point: a second builder's commits, scripts,
+# error messages, and skill outputs must NOT silently impersonate or
+# hardcode-credit the founding builder.
+#
+# What counts as a violation here:
+#   * `/Users/larskristensen/...` paths in code or skill instructions.
+#     (Use `$HOME` / `os.path.expanduser('~')` instead.)
+#   * `builder_id = 1` / `shipped_by = 1` hardcodes in code paths that run
+#     during a builder's session. (Use `req.builder.id` / the active claim.)
+#   * `lars589` / `larskristensen` literals in setup-path code or test data
+#     that would mis-attribute a second builder's work.
+#
+# What is INTENTIONAL and allow-listed (NOT a violation):
+#   * Archived shipping docs in `limitations/*-shipped.md` — historical record.
+#   * ADRs, session logs, and the chat-broadcast plan — historical / decision
+#     records that name the founder by intent.
+#   * `CLAUDE.md` — §2 is explicitly about working with Lars as the prompter
+#     and project owner; that framing IS the point.
+#   * Droplet operational identity (`User=lars`, `lars@104.236.254.243`,
+#     `/home/lars/amazonprimea`, `lars@hermeslines.com`) — that's the actual
+#     unix user / SSH target / ACME contact on the production server. It's
+#     infra config, not impersonation of a builder identity.
+#   * The seed script that ORIGINALLY created the V3 tasks
+#     (`scripts/gds/seed-v3-tasks.js`) — a frozen migration-style snapshot.
+#     Names appear in task descriptions by historical necessity.
+#     (The earlier `seed-v2-tasks.js` + `import-backlog.js` seeds were
+#     deleted as dead code in task 1079.)
+#   * Self-references in this audit script and in the V3.R09 / V3.R12 task
+#     descriptions captured in `seed-v3-tasks.js`.
+#   * GitHub remote `lars589/amazonprimea` — actual repo owner; cloning
+#     anything else would clone a different project.
+#   * Comments that document who decided something or who originally ran a
+#     one-time backfill — historical decision-attribution.
+#
+# Usage:
+#   bash scripts/gds/audit-authorship.sh           # check, exit 1 on new hits
+#   bash scripts/gds/audit-authorship.sh --verbose # print every hit (incl.
+#                                                  # allowlisted) for review
+#
+# Hookable from CI / pre-commit. No writes, no network.
+
+set -uo pipefail
+
+# Anchor to repo root regardless of where the script was invoked from.
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+VERBOSE=0
+for arg in "$@"; do
+  case "$arg" in
+    --verbose|-v) VERBOSE=1 ;;
+    -h|--help)
+      sed -n '2,50p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+  esac
+done
+
+# Uses plain `grep -RE` so the script runs on any machine — including CI
+# images that don't bundle ripgrep — and on the bare droplet. Exclude paths
+# are passed via the standard --exclude / --exclude-dir flags.
+
+# ----------------------------------------------------------------------------
+# 1. Path-exclusion args — paths where hits NEVER count (frozen archives,
+#    generated content, dot-git, third-party deps). Filtered at the grep
+#    level so they never even enter the candidate set.
+# ----------------------------------------------------------------------------
+EXCLUDE_DIRS=(
+  --exclude-dir=node_modules
+  --exclude-dir=.git
+  --exclude-dir=iterations         # under art/, historical cost ledger
+  --exclude-dir=generated          # under art/, generated PNGs / metadata
+  --exclude-dir=docs               # human prose: ADRs, recipes, plans,
+                                   # session logs, architecture notes —
+                                   # naming the founder by intent
+  --exclude-dir=blockers           # blockers ARE the things stuck on Lars
+  --exclude-dir=limitations        # archives + scope-truth docs
+  --exclude-dir=worktrees          # .claude/worktrees/ holds N full repo
+                                   # copies (one per builder worktree); from
+                                   # the main checkout, recursing them is slow
+                                   # AND produces 100s of duplicate self-hits
+                                   # (#558). Each worktree audits its own tree.
+)
+EXCLUDE_FILES=(
+  --exclude=session-log-archive.md
+  --exclude='*-shipped.md'         # frozen version archives in limitations/
+  --exclude='*.sql'                # migrations ran AS lars at migration time
+  --exclude=CLAUDE.md              # §2 is about the prompter by intent
+  --exclude=README.md              # README credits / examples
+  --exclude=chat-inbox.md          # framing references
+  --exclude=generative-ideas.md    # historical idea capture
+  --exclude=.git                   # in a worktree, .git is a file (gitdir
+                                   # pointer to main repo) — skip it
+)
+
+# ----------------------------------------------------------------------------
+# 2. The regex — what we're scanning for.
+#    Three families:
+#      a) /Users/larskristensen/... — runtime hardcoded home-dir paths
+#      b) builder_id = 1 / shipped_by = 1 — hardcoded primary key references
+#      c) literal lars589 / larskristensen identifiers in code surface
+# ----------------------------------------------------------------------------
+PATTERN='(/Users/larskristensen)|(\bbuilder_id\s*=\s*1\b)|(\bshipped_by\s*=\s*1\b)|(\blars589\b)|(\blarskristensen\b)'
+
+# ----------------------------------------------------------------------------
+# 3. The allowlist — file:line tokens where the regex IS expected to match.
+#    Each entry is a substring match against "file:line: <captured-text>"
+#    style records. Add a new allowlist entry only with a justification
+#    comment.
+# ----------------------------------------------------------------------------
+ALLOWLIST=(
+  # Frozen seed scripts — the V3 plan literally contains the strings being
+  # audited because the task DESCRIPTION (#234/V3.R09 and #236/V3.R12) names
+  # them. Stripping them would lose the task history.
+  'scripts/gds/seed-v3-tasks.js'
+
+  # Audit-replay docs the builders table example "1 for lars589" — that's
+  # the actual row in the prod DB; renaming the example breaks the doc.
+  'scripts/gds/audit-replay.sh'
+
+  # provision-staging.sh clones the actual GitHub repo owned by lars589.
+  # That's the GitHub org/user that owns the repo; not a builder identity.
+  'scripts/deploy/provision-staging.sh'
+
+  # Dev Box app distribution (#904, ADR 0044): the PUBLIC releases repo lives
+  # under the same GitHub account that owns the main repo — repo-hosting
+  # identity (same nature as provision-staging.sh above), not a builder
+  # identity. The test pins the committed config's repo string.
+  'config/devbox-app.json'
+  'tests/devbox_downloads.mjs'
+
+  # This audit script's own self-reference (it documents what it's looking for).
+  'scripts/gds/audit-authorship.sh'
+
+  # skill-usage-review explains how Claude Code encodes cwd into the
+  # transcripts directory name — explanatory text describing why the glob
+  # is now builder-agnostic. Not a runtime hardcode.
+  '.claude/scheduled-tasks/skill-usage-review/SKILL.md'
+
+  # setup_smoke explicitly asserts the ABSENCE of /Users/larskristensen
+  # leaks in setup.js — the string appearing in the comment IS the
+  # specification of what's forbidden in implementation code.
+  'tests/setup_smoke.mjs'
+)
+
+# ----------------------------------------------------------------------------
+# 4. Operational-identity allowlist — these patterns reference the droplet's
+#    unix user / SSH target / ACME contact / cron user / DB role. They are
+#    legitimate operational configuration, not impersonation of a builder.
+# ----------------------------------------------------------------------------
+OPS_ALLOWLIST_PATTERN='(^User=lars$|/home/lars/|lars@104\.236\.254\.243|lars@hermeslines\.com|^DROPLET=.*lars@|sudo -u postgres .*-O lars\b|PGUSER=lars\b|createdb -O lars\b|"-U" "?lars"?|-U lars\b|runs as user .lars.|service .* lars\b|cron .*lars\b)'
+
+# ----------------------------------------------------------------------------
+# 4b. Spec-string allowlist — content patterns where the literal "lars589"
+#    (etc.) appears precisely because it is the THING THE AUDIT FORBIDS,
+#    quoted inside a prompt/comment that instructs a reader (human or the LLM
+#    grader) to hunt for it. The grader workers' prompts say `Look for literal
+#    "lars", "lars589", absolute /Users paths ...` — that's the audit's own
+#    specification embedded in a prompt, not a runtime hardcode that
+#    mis-attributes a builder. Matched on line content (not file path) so the
+#    rest of grader.js stays auditable for a genuine hardcode.
+#
+#    The pattern is the FULL exact prompt phrase, not just `Look for literal`,
+#    so the suppression can't double as a smuggling channel: a contributor
+#    can't sneak a real hardcode past the audit by appending a short comment,
+#    because escaping requires reproducing this whole sentence verbatim — at
+#    which point the line is self-evidently a prompt-spec, not plausible cover
+#    for `builder_id = "lars589"`.
+# ----------------------------------------------------------------------------
+SPEC_ALLOWLIST_PATTERN='[Ll]ook for literal "lars", "lars589", absolute /Users paths'
+
+# ----------------------------------------------------------------------------
+# 5. Scan, filter, report.
+# ----------------------------------------------------------------------------
+TMP_RAW="$(mktemp)"
+TMP_HITS="$(mktemp)"
+TMP_FILTERED="$(mktemp)"
+trap 'rm -f "$TMP_RAW" "$TMP_HITS" "$TMP_FILTERED"' EXIT
+
+# Walk every file under repo root (excluding the path-level exclusions above).
+# grep -R recurses into hidden subdirs by default (including .claude/, which
+# absolutely DOES need auditing since skill prompts live there). The
+# --exclude-dir entries below cull the dirs we don't care about.
+grep -RIn -E "${EXCLUDE_DIRS[@]}" "${EXCLUDE_FILES[@]}" -e "$PATTERN" . 2>/dev/null \
+  | sed 's|^\./||' \
+  | sort -u \
+  > "$TMP_RAW" || true
+
+# Apply file-level allowlist (entry is a path prefix match against "file:" portion).
+ALLOWLIST_RE=''
+for e in "${ALLOWLIST[@]}"; do
+  # Escape regex metachars conservatively (just dots — paths only have those).
+  esc="${e//./\\.}"
+  ALLOWLIST_RE+="^${esc}:|"
+done
+ALLOWLIST_RE="${ALLOWLIST_RE%|}"
+
+if [ -n "$ALLOWLIST_RE" ]; then
+  grep -vE "$ALLOWLIST_RE" "$TMP_RAW" > "$TMP_HITS" || true
+else
+  cp "$TMP_RAW" "$TMP_HITS"
+fi
+
+# Apply operational-identity + spec-string pattern allowlists (both match on
+# line content, not file path).
+grep -vE "$OPS_ALLOWLIST_PATTERN" "$TMP_HITS" \
+  | grep -vE "$SPEC_ALLOWLIST_PATTERN" > "$TMP_FILTERED" || true
+
+HIT_COUNT=$(wc -l < "$TMP_FILTERED" | tr -d ' ')
+
+if [ "$VERBOSE" = "1" ]; then
+  TOTAL=$(wc -l < "$TMP_RAW" | tr -d ' ')
+  AFTER_FILE=$(wc -l < "$TMP_HITS" | tr -d ' ')
+  echo "audit-authorship: scan summary"
+  echo "  raw hits (post path-exclude): $TOTAL"
+  echo "  after file allowlist:          $AFTER_FILE"
+  echo "  after ops + spec allowlists:   $HIT_COUNT"
+  echo ""
+fi
+
+if [ "$HIT_COUNT" -eq 0 ]; then
+  echo "audit-authorship: PASS — no hardcoded Archon-identity references in implementation code."
+  exit 0
+fi
+
+echo "audit-authorship: FAIL — found $HIT_COUNT hardcoded reference(s) to the original Archon in implementation code."
+echo ""
+echo "Hits:"
+cat "$TMP_FILTERED"
+echo ""
+echo "Remediation:"
+echo "  * Paths like /Users/larskristensen/...  ->  use \$HOME or os.path.expanduser('~')"
+echo "  * builder_id = 1 / shipped_by = 1       ->  use req.builder.id / the active claim"
+echo "  * lars589 / larskristensen literals     ->  use the current builder's github_login"
+echo ""
+echo "If a hit IS intentional (historical doc, droplet operational identity,"
+echo "or a frozen seed/import script), add it to the ALLOWLIST or"
+echo "OPS_ALLOWLIST_PATTERN in this script with a one-line justification."
+exit 1

package/scripts/gds/audit-deps.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// scripts/gds/audit-deps.js — likely-missing-dependency detector (task 349).
+//
+// WHY: an under-specified dependencies[] lets work start before the task it
+// implicitly builds on has shipped, racing already-built work (the original
+// motivation: task 307 was claimable before the rank system it needed had
+// shipped). This surfaces OPEN tasks whose touches[] overlap an UNSHIPPED task
+// they do NOT already depend on — candidate missing edges for a human to triage.
+//
+// THIS IS ADVISORY. Most touches[] overlaps are PARALLEL work on a shared surface
+// (src/bongos/db.js, migrations/, CLAUDE.md, …), NOT a build-order dependency.
+// Backfilling a wrong edge GATES the dependent (POST /claims → 409
+// DEPS_NOT_SHIPPED) until the named blocker ships. So: act only on `high`
+// confidence, by hand, after reading both task descriptions. The detector reuses
+// the ONE canonical overlap matcher (src/bongos/path-match.touchesOverlap) — the
+// same one tests/touches_overlap.mjs covers — so it can't drift from the claim
+// gate's notion of "overlap".
+//
+//   node scripts/gds/audit-deps.js [--version GDS-V3] [--min high|medium|low] [--json]
+
+const { touchesOverlap } = require('../../src/bongos/path-match.js');
+const { cliClient } = require('./cli-lib');
+
+// Lifecycle statuses that count as "open" (auditable) vs "an unshipped blocker".
+const OPEN = new Set(['ready', 'backlog', 'active', 'blocked']);
+const isUnshippedBlocker = (s) => s !== 'shipped' && s !== 'abandoned';
+
+// Shared collaboration surfaces: an overlap here is a parallel-safety (touches[])
+// signal, not a dependency. A candidate whose ONLY overlap is one of these (or a
+// bare directory) is demoted to `low`. Deliberately broad; tune as the repo moves.
+const HOTSPOTS = [
+  'src/bongos/db.js', 'src/bongos/routes.js', 'server.js', 'migrations/', 'CLAUDE.md',
+  'modules/hall-ui/', 'tests/', 'scripts/gds/', 'src/bongos/', 'src/bongos/routes/',
+  'scripts/gds/ship.js', 'scripts/gds/api.js', 'scripts/gds/cli-lib.js',
+  'modules/grading/grader.js', 'docs/', 'docs/adr/', 'docs/adr/README.md', 'docs/recipes/',
+  'docs/architecture.md', 'docs/file-map.md', '.claude/skills/', '.claude/hooks/',
+  'infra/', 'public/assets/tiles/',
+];
+const isHotspot = (p) => HOTSPOTS.includes(p);
+
+// Confidence heuristic (advisory; a human decides):
+//   high   — an exact SAME non-hotspot, non-bare-dir FILE both tasks name.
+//   medium — a narrow (non-hotspot, non-bare-dir) overlap exists.
+//   low    — overlap only on a shared hotspot / bare directory.
+function classify(tTouches, oTouches) {
+  const pairs = [];
+  for (const a of tTouches) for (const b of oTouches) {
+    if (touchesOverlap([a], [b])) pairs.push({ a, b, exact: a === b });
+  }
+  if (!pairs.length) return null;
+  const narrow = pairs.filter((p) => !isHotspot(p.a) && !isHotspot(p.b) && !p.a.endsWith('/') && !p.b.endsWith('/'));
+  const confidence = narrow.some((p) => p.exact) ? 'high' : narrow.length ? 'medium' : 'low';
+  const paths = [...new Set(pairs.map((p) => (p.exact ? p.a : `${p.a} ~ ${p.b}`)))];
+  return { confidence, paths };
+}
+
+// Pure core — unit-tested with fixtures (no API). `tasks` is an array of
+// { id, status, touches:[], dependencies:[ids] }. Returns candidate edges
+// { task_id, dep_id, dep_status, confidence, paths }.
+function findMissingDeps(tasks, { open = OPEN, isBlocker = isUnshippedBlocker } = {}) {
+  const out = [];
+  for (const t of tasks) {
+    if (!open.has(t.status)) continue;
+    if (!Array.isArray(t.touches) || !t.touches.length) continue;
+    const declared = new Set((t.dependencies || []).map(String));
+    for (const o of tasks) {
+      if (String(o.id) === String(t.id)) continue;
+      if (!isBlocker(o.status)) continue;
+      if (!Array.isArray(o.touches) || !o.touches.length) continue;
+      if (declared.has(String(o.id))) continue;
+      if (!touchesOverlap(t.touches, o.touches)) continue;
+      const c = classify(t.touches, o.touches);
+      if (c) out.push({ task_id: t.id, dep_id: o.id, dep_status: o.status, ...c });
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const ver = argv.includes('--version') ? argv[argv.indexOf('--version') + 1] : 'GDS-V3';
+  const minRank = argv.includes('--min') ? argv[argv.indexOf('--min') + 1] : 'low';
+  const asJson = argv.includes('--json');
+  const order = { high: 3, medium: 2, low: 1 };
+
+  const api = await cliClient();
+  const r = await api.tasks.getTasks({ query: { version: ver } });
+  if (!r.ok) { console.error(`audit-deps: could not list tasks (${r.status})`); process.exit(1); }
+  const all = r.data.tasks || [];
+  const openTasks = all.filter((t) => OPEN.has(t.status) && Array.isArray(t.touches) && t.touches.length);
+
+  // dependencies[] lives in a join table, not the task row — hydrate per open task.
+  for (const t of openTasks) {
+    const dr = await api.tasks.getTasksIdDependencies({ id: t.id });
+    t.dependencies = dr.ok ? (dr.data.dependencies || []).map((d) => String(d.id)) : [];
+  }
+  const byId = new Map(all.map((t) => [String(t.id), t]));
+  // Feed the FULL task set (open + others) so blockers in any status are visible.
+  const edges = findMissingDeps([...openTasks, ...all.filter((t) => !OPEN.has(t.status))])
+    .filter((e) => order[e.confidence] >= (order[minRank] || 1))
+    .sort((a, b) => order[b.confidence] - order[a.confidence]);
+
+  if (asJson) { console.log(JSON.stringify(edges, null, 2)); return; }
+  console.log(`audit-deps: ${ver} — ${openTasks.length} open task(s) audited, ${edges.length} candidate edge(s) >= ${minRank}\n`);
+  for (const e of edges) {
+    const t = byId.get(String(e.task_id)) || {};
+    const o = byId.get(String(e.dep_id)) || {};
+    console.log(`[${e.confidence.toUpperCase().padEnd(6)}] #${e.task_id} should-maybe-depend-on #${e.dep_id} [${e.dep_status}]`);
+    console.log(`         from: ${(t.title || '').slice(0, 70)}`);
+    console.log(`         dep : ${(o.title || '').slice(0, 70)}`);
+    console.log(`         on  : ${e.paths.join(', ')}\n`);
+  }
+  if (!edges.length) console.log('No candidate missing dependencies at this confidence — the graph is clean here.');
+  console.log('NB: advisory only. Backfill `high` edges by hand (POST /tasks/:id/dependencies) after reading both tasks; a wrong edge gates the dependent.');
+}
+
+module.exports = { findMissingDeps, classify, OPEN, isUnshippedBlocker, HOTSPOTS };
+
+if (require.main === module) {
+  main().catch((e) => { console.error('audit-deps:', e.message); process.exit(1); });
+}

package/scripts/gds/audit-exports.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// audit-exports.js — V3.R?? (#467). Dead-export checker for the grader modules.
+//
+// The MAS grader accreted v1/v2/v3 code; some exported symbols outlived their
+// only consumer (the dead exports #466 deletes). This script is the cheap,
+// greppable, CI-hookable guard that catches that class — same spirit as
+// audit-authorship.sh (V3.R12): require the target modules, read their actual
+// export keys, then scan the repo for a real consumer of each.
+//
+// Classification per exported symbol:
+//   consumed   — referenced in src/ or scripts/ outside the defining file
+//   test-only  — referenced ONLY under tests/ (a warning: exported for tests)
+//   DEAD       — no word-boundary reference anywhere outside the defining file
+//
+// Exit 1 if any DEAD export (nothing imports it). test-only is reported but
+// does not fail. --json prints the raw classification.
+//
+// Usage: node scripts/gds/audit-exports.js [--json]
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+
+// Modules whose export surface we police. Add more as the grader grows.
+const TARGETS = [
+  'modules/grading/grader.js',
+  'modules/grading/grader-workers/index.js',
+];
+
+// Dirs scanned for consumers.
+const SCAN_DIRS = ['src', 'scripts', 'tests'];
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs']);
+
+// Walk a dir collecting code files (skip node_modules / .git).
+function collectFiles(dir, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (e.name === 'node_modules' || e.name === '.git') continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) collectFiles(full, out);
+    else if (CODE_EXT.has(path.extname(e.name))) out.push(full);
+  }
+  return out;
+}
+
+// Build { absPath: content } for the whole scan corpus.
+function buildCorpus() {
+  const files = [];
+  for (const d of SCAN_DIRS) collectFiles(path.join(REPO_ROOT, d), files);
+  const corpus = {};
+  for (const f of files) {
+    try { corpus[f] = fs.readFileSync(f, 'utf8'); } catch { /* skip unreadable */ }
+  }
+  return corpus;
+}
+
+// Pure core: given a target's absolute path + its exported symbol names + the
+// corpus ({absPath: content}), classify each export. A reference is a
+// word-boundary match of the symbol in any corpus file OTHER than the defining
+// file. Exported under tests/ only → test-only; nowhere → DEAD.
+function classifyExports(targetAbsPath, exportNames, corpus) {
+  const results = [];
+  for (const name of exportNames) {
+    const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+    let inSrcOrScripts = false;
+    let inTests = false;
+    for (const [file, content] of Object.entries(corpus)) {
+      if (file === targetAbsPath) continue; // self-references don't count
+      if (!re.test(content)) continue;
+      // A file is a test by virtue of living under a tests/ segment — checked
+      // on the raw path (not REPO_ROOT-relative) so the core stays pure +
+      // unit-testable with synthetic paths.
+      const isTest = /(^|[\\/])tests[\\/]/.test(file);
+      if (isTest) inTests = true;
+      else inSrcOrScripts = true;
+    }
+    const status = inSrcOrScripts ? 'consumed' : inTests ? 'test-only' : 'DEAD';
+    results.push({ name, status });
+  }
+  return results;
+}
+
+function run({ json = false } = {}) {
+  const corpus = buildCorpus();
+  const all = [];
+  for (const rel of TARGETS) {
+    const abs = path.join(REPO_ROOT, rel);
+    let mod;
+    try { mod = require(abs); } catch (err) {
+      console.error(`audit-exports: could not require ${rel}: ${err.message}`);
+      process.exitCode = 1;
+      continue;
+    }
+    const names = Object.keys(mod);
+    for (const r of classifyExports(abs, names, corpus)) {
+      all.push({ module: rel, ...r });
+    }
+  }
+
+  const dead = all.filter((r) => r.status === 'DEAD');
+  const testOnly = all.filter((r) => r.status === 'test-only');
+
+  if (json) {
+    console.log(JSON.stringify({ dead, test_only: testOnly, all }, null, 2));
+  } else {
+    console.log(`audit-exports: ${all.length} exported symbol(s) across ${TARGETS.length} module(s)`);
+    if (dead.length) {
+      console.log(`\n  DEAD (no consumer anywhere — un-export or delete):`);
+      for (const r of dead) console.log(`    ✗ ${r.module} → ${r.name}`);
+    }
+    if (testOnly.length) {
+      console.log(`\n  test-only (exported but used only by tests):`);
+      for (const r of testOnly) console.log(`    • ${r.module} → ${r.name}`);
+    }
+    if (!dead.length) console.log('  no dead exports — every exported symbol has a consumer ✓');
+  }
+
+  if (dead.length) process.exitCode = 1;
+  return { dead, testOnly, all };
+}
+
+if (require.main === module) {
+  run({ json: process.argv.includes('--json') });
+}
+
+module.exports = { classifyExports, buildCorpus, run, TARGETS };

package/scripts/gds/audit-replay.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# scripts/gds/audit-replay.sh — V3.R52 (#271).
+#
+# Given a builder_id and a date range, reconstruct chronologically EVERY
+# trace of what that builder did against the city. The point is the
+# forensic question: "If someone went rogue, can we tell?"
+#
+# Tables walked (each contributes timestamped rows):
+#   - claims          (CLAIM + CLAIM_END events per task; outcome carries
+#                     the disposition: shipped / abandoned / partial / expired)
+#   - credit_log      (drachmae awards / debits)
+#   - cost_log        (API + infra spend they logged)
+#   - session_logs    (claim-scoped session boundaries + outcome)
+#   - audit_log       (HTTP writes — V3.R35 #256)
+#
+# Two modes:
+#   1. ON THE DROPLET (psql against the local Unix socket — fast, no auth).
+#   2. FROM A LAPTOP via SSH (the script self-hops; you need lars@<droplet>).
+#      Triggered if the local PG socket isn't reachable.
+#
+# Usage:
+#   bash scripts/gds/audit-replay.sh <builder_id> <start_iso> <end_iso>
+#
+# Example:
+#   bash scripts/gds/audit-replay.sh 1 2026-05-20T00:00:00Z 2026-05-28T23:59:59Z
+#
+# Output: TSV columns: when_utc, kind, detail. Sorted chronologically.
+# See docs/recipes/audit-replay.md for the recipe + how to extend.
+
+set -euo pipefail
+
+BUILDER_ID="${1:-}"
+START="${2:-}"
+END="${3:-}"
+
+if [ -z "$BUILDER_ID" ] || [ -z "$START" ] || [ -z "$END" ]; then
+  cat <<USAGE >&2
+usage: $0 <builder_id> <start_iso> <end_iso>
+
+  builder_id   the id from the builders table (e.g. 1 for lars589)
+  start_iso    inclusive lower bound, RFC3339/ISO 8601 (e.g. 2026-05-20T00:00:00Z)
+  end_iso      inclusive upper bound, same shape
+
+example:
+  $0 1 2026-05-20T00:00:00Z 2026-05-28T23:59:59Z
+
+see docs/recipes/audit-replay.md
+USAGE
+  exit 2
+fi
+
+# Decide local vs remote. The droplet's Postgres listens on a Unix socket
+# under /var/run/postgresql; if we can stat it, we're already on the droplet.
+DROPLET="lars@104.236.254.243"
+PG_SOCKET="/var/run/postgresql"
+
+if [ ! -S "$PG_SOCKET/.s.PGSQL.5432" ]; then
+  # Re-invoke ourselves on the droplet. The script doesn't depend on any
+  # repo file at runtime, so we ship the script body over stdin to avoid a
+  # rsync step. Quoting on the SSH side preserves the timestamp args.
+  exec ssh -o ConnectTimeout=10 "$DROPLET" \
+    "bash -s -- '$BUILDER_ID' '$START' '$END'" < "$0"
+fi
+
+# From here down: running where Postgres is reachable on the Unix socket.
+
+PSQL_ARGS=(-h "$PG_SOCKET" -d amazonprimea -U lars -t -A -F $'\t' --no-psqlrc)
+
+q() {
+  PGOPTIONS='--client-min-messages=warning' psql "${PSQL_ARGS[@]}" -c "$1"
+}
+
+# Single UNION ALL so the chronological sort is one operation. The leading
+# timestamp column normalises to ISO-8601 UTC so the textual sort is the
+# chronological sort.
+SQL=$(cat <<SQL
+WITH range AS (
+  SELECT '${START}'::timestamptz AS lo, '${END}'::timestamptz AS hi
+),
+all_events AS (
+  -- CLAIM (claim row born)
+  SELECT to_char(c.claimed_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CLAIM' AS kind,
+         ('task=' || c.task_id || ' claim_id=' || c.id ||
+          ' worktree=' || COALESCE(c.worktree_name, '-')) AS detail
+    FROM claims c, range
+   WHERE c.builder_id = ${BUILDER_ID}
+     AND c.claimed_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- CLAIM_END (released — outcome distinguishes shipped vs abandoned, etc.)
+  SELECT to_char(c.released_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CLAIM_END' AS kind,
+         ('task=' || c.task_id || ' claim_id=' || c.id ||
+          ' outcome=' || COALESCE(c.outcome, '-')) AS detail
+    FROM claims c, range
+   WHERE c.builder_id = ${BUILDER_ID}
+     AND c.released_at IS NOT NULL
+     AND c.released_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- CREDIT (drachmae movement)
+  SELECT to_char(cl.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'CREDIT' AS kind,
+         ('delta=' || cl.delta || ' reason=' || cl.reason ||
+          ' task=' || COALESCE(cl.task_id::text, '-')) AS detail
+    FROM credit_log cl, range
+   WHERE cl.builder_id = ${BUILDER_ID}
+     AND cl.recorded_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- COST (spend they logged; co.task_id may be NULL for infra-level entries)
+  SELECT to_char(co.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'COST' AS kind,
+         ('category=' || co.category || ' usd=' || co.amount_usd ||
+          ' source=' || COALESCE(co.source, '-') ||
+          ' task=' || COALESCE(co.task_id::text, '-')) AS detail
+    FROM cost_log co
+    JOIN claims c2 ON c2.task_id = co.task_id AND c2.builder_id = ${BUILDER_ID}
+    , range
+   WHERE co.recorded_at BETWEEN range.lo AND range.hi
+   GROUP BY co.id, co.recorded_at, co.category, co.amount_usd, co.source, co.task_id
+
+  UNION ALL
+  -- SESSION_START
+  SELECT to_char(sl.started_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'SESSION_START' AS kind,
+         ('claim_id=' || COALESCE(sl.claim_id::text, '-') ||
+          ' task=' || COALESCE(sl.task_id::text, '-')) AS detail
+    FROM session_logs sl, range
+   WHERE sl.builder_id = ${BUILDER_ID}
+     AND sl.started_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- SESSION_END
+  SELECT to_char(sl.ended_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'SESSION_END' AS kind,
+         ('claim_id=' || COALESCE(sl.claim_id::text, '-') ||
+          ' outcome=' || COALESCE(sl.outcome, '-')) AS detail
+    FROM session_logs sl, range
+   WHERE sl.builder_id = ${BUILDER_ID}
+     AND sl.ended_at BETWEEN range.lo AND range.hi
+
+  UNION ALL
+  -- HTTP write
+  SELECT to_char(al.recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS when_utc,
+         'HTTP_' || al.method AS kind,
+         ('route=' || al.route ||
+          ' status=' || al.response_status ||
+          ' ip=' || COALESCE(al.ip, '-')) AS detail
+    FROM audit_log al, range
+   WHERE al.builder_id = ${BUILDER_ID}
+     AND al.recorded_at BETWEEN range.lo AND range.hi
+)
+SELECT when_utc, kind, detail
+  FROM all_events
+ ORDER BY when_utc, kind;
+SQL
+)
+
+q "$SQL"