@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/architect-audit.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// MAS Phase 5 (#459) — the Architect.
+//
+// A bounded, first-principles audit of a DEFINED SCOPE. Unlike the Grader
+// (per-ship gate) and the Conductor (per-prompt hook), the Architect runs
+// INFREQUENTLY on an explicit scope — "bounded ferocity, not constant churn."
+// It applies Musk's engineering algorithm (deletion emphasized), thinks in
+// first principles, and is not afraid to delete things. It produces:
+//   1. a written audit at docs/audits/<scope-slug>-<date>.md, and
+//   2. seed ideas filed to idea_inbox (tagged 'architect') that feed the next
+//      version's planning session.
+//
+// Model: OPUS. The one MAS agent that is NOT cross-family Sonnet — this is
+// judgment + design, not adversarial verification, and it runs rarely, so the
+// cost is bounded (CLAUDE.md §2: audits + planning + design = Opus).
+//
+// The subagent stays READ-ONLY (it returns structured JSON); this CLI does the
+// side effects (write doc, file ideas) — deterministic + auditable, mirroring
+// the grader pattern. The subagent inherits OTB_SUBAGENT=1 via grader.run-
+// Subagent, so the Conductor never fires inside it.
+//
+// Usage:
+//   node scripts/bongos/architect-audit.js --scope "<name>" --paths "glob1,glob2,..." \
+//        [--version GDS-V3] [--dry-run]
+//
+//   --dry-run  do everything EXCEPT writing the doc + filing ideas (prints the
+//              audit + what it would file). NOTE: the Opus subagent call still
+//              runs (~1-5 min, real API cost) — dry-run only skips the side
+//              effects (doc write + inbox filing), not the expensive audit.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { apiCall, cliClient, arg } = require('./cli-lib');
+const { resolveDefaultVersion } = require('./version-select.js');
+const grader = require('../../modules/grading/grader');
+const llmCache = require('../../src/bongos/llm-cache'); // System 5 (task 1360): cache identical audits over an unchanged tree
+const { branding } = require('../../src/branding');
+
+// The instance's project name for the Architect's identity line, so a non-OTB
+// Cloud Bongos instance audits ITS OWN project instead of a hardcoded "Off the
+// Boats" (ADR 0062 §3/§5; the branding contract's llmProjectName field). Resolved
+// once; falls back to a neutral phrase if branding fails so the audit never crashes.
+const LLM_PROJECT = (() => {
+  try { return branding().llmProjectName || 'this project'; }
+  catch { return 'this project'; }
+})();
+llmCache.setApiFallback(apiCall); // task 1381: this runs on a builder machine (no DB pool) → reach the cache via the GDS API
+
+// The Architect's deliberate model choice: Opus (judgment + design + planning,
+// per CLAUDE.md §2). Kept as its OWN literal, NOT coupled to the grader's
+// ASSUMED_BUILDER_MODEL — those are two distinct decisions (the grader constant
+// means "what the builder-under-review is assumed to use", to pick a
+// cross-family grader; this is "what the Architect thinks with"). They happen
+// to coincide today; they should be free to diverge.
+const ARCHITECT_MODEL = 'claude-opus-4-7';
+const CONTEXT_CHAR_CAP = 400_000;
+const TIMEOUT_MS = 600_000; // 10 min — a deep audit over a lot of context
+const VALID_KINDS = new Set([
+  'feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture',
+  'cleanup', 'decision', 'blocker-resolution', 'unclassified',
+]);
+
+// ---------- pure helpers (exported for tests) ----------
+
+function slug(scope) {
+  return String(scope || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'audit';
+}
+
+function pickValidKind(kind) {
+  return VALID_KINDS.has(kind) ? kind : 'unclassified';
+}
+
+// Normalize + validate the subagent's seed_ideas into filable rows. Drops
+// anything without a usable title; coerces kind into the valid set.
+function validateSeedIdeas(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const it of raw) {
+    if (!it || typeof it !== 'object') continue;
+    const title = typeof it.title === 'string' ? it.title.trim() : '';
+    if (!title) continue;
+    out.push({
+      title: title.slice(0, 200),
+      kind: pickValidKind(it.kind),
+      body_md: typeof it.body_md === 'string' ? it.body_md : '',
+    });
+  }
+  return out;
+}
+
+const PROMPT_HEADER = `You are the **Architect** — the first-principles design auditor for the ${LLM_PROJECT} project. You are not a code reviewer (the Grader panel does that per-ship) and not a watcher (the Conductor does that per-prompt). You run rarely, on a bounded scope, and your job is to make the system SIMPLER and more correct at the level of structure and requirements — then hand the next version's planning a concrete set of seed ideas.
+
+Apply **Musk's engineering algorithm, IN ORDER, with deletion emphasized**:
+
+1. **Make the requirements less dumb.** Question every requirement and assumption in this scope — especially ones that came from smart people, including past-you. Whose requirement is each? Is it still true? What would you NOT build if starting today?
+2. **DELETE.** The most important step. What code / files / abstractions / config / process in this scope can be removed outright? Be aggressive: "if you're not adding ~10% of it back later, you didn't delete enough." Name specific files, functions, exports, options, layers. Estimate the LOC each deletion removes.
+3. **Simplify** what survives deletion — and ONLY what survives. Never polish a thing that should not exist. Collapse duplication (note: this codebase has had repeated copy-paste-drift findings; hunt for it), flatten needless indirection, unify near-identical code paths into one.
+4. **Accelerate** the build/ship/feedback cycle for this scope. What's slow, manual, or repeated that shouldn't be?
+5. **Automate** — LAST. Only automate things that have proven they should exist and won't keep changing.
+
+Think in first principles: reason from what the system must DO, not from what it currently IS. Be specific and unsentimental — "not afraid to delete things." Vague advice ("improve modularity") is useless; name the file, the function, the deletion, the consolidation.
+
+Your output has two parts:
+- **audit_md**: a thorough markdown audit. Required sections: "## Summary" (3-6 lines, the headline calls), "## 1. Requirements questioned", "## 2. Delete" (the heart — specific removals + LOC estimates), "## 3. Simplify", "## 4. Accelerate", "## 5. Automate", and "## The 10% honesty check" (what, if anything, you'd expect to add back — if nothing, you didn't cut deep enough; say so). Cite real file paths and symbols throughout.
+- **seed_ideas**: 3-8 CONCRETE, task-able proposals for the next version, each derived from the audit. Each: { "title": "<imperative, task-sized>", "kind": "<feature|refactor|cleanup|infra|decision|spike>", "body_md": "<what + why + rough scope + which files>" }. These get filed to the planning inbox — make them actionable, not aspirational.
+
+You have a Read tool — use it to pull any file in the scope (or adjacent to it) that you need to judge a deletion or consolidation safely. Do NOT edit files, do NOT run tests, do NOT call the network.
+
+Return ONLY JSON — no prose before/after, no markdown fences:
+{
+  "audit_md": "<the full markdown audit>",
+  "seed_ideas": [ { "title": "...", "kind": "...", "body_md": "..." }, ... ]
+}`;
+
+function buildPrompt({ scope, fileList, fileBlocks, version }) {
+  const lines = [PROMPT_HEADER, '', '---', `## Audit scope: ${scope}`, ''];
+  if (version) lines.push(`Seed ideas will be filed for planning under: ${version}`, '');
+  lines.push(`### Files in scope (${fileList.length})`, '');
+  for (const f of fileList) lines.push(`- ${f.path}  (${f.loc} lines)`);
+  lines.push('', '---', '## File contents', '');
+  lines.push(fileBlocks);
+  lines.push('', '---', 'Now audit. Lead with deletion. Be specific. Output ONLY the JSON object.');
+  return lines.join('\n');
+}
+
+// ---------- plumbing ----------
+
+function git(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (_) {
+    return '';
+  }
+}
+
+function repoRoot() {
+  return git(['rev-parse', '--show-toplevel']).trim() || process.cwd();
+}
+
+// Resolve comma-separated globs/paths to a deduped file list via git, honoring
+// .gitignore. Includes BOTH tracked files and untracked-but-not-ignored ones
+// (--others --exclude-standard), so a brand-new file in the scope — e.g. the
+// Architect auditing its own freshly-written, not-yet-committed code — isn't
+// invisible to the audit.
+function resolvePaths(spec, root) {
+  const globs = String(spec || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const set = new Set();
+  for (const g of globs) {
+    const tracked = git(['-C', root, 'ls-files', '--', g]);
+    const untracked = git(['-C', root, 'ls-files', '--others', '--exclude-standard', '--', g]);
+    for (const f of (tracked + '\n' + untracked).split('\n').map((s) => s.trim()).filter(Boolean)) set.add(f);
+  }
+  return [...set];
+}
+
+// Read files up to the context cap; past it, list the path without contents
+// (the subagent can Read it on demand).
+function gatherContext(files, root) {
+  const fileList = [];
+  const blocks = [];
+  let used = 0;
+  for (const rel of files) {
+    let content = '';
+    try { content = fs.readFileSync(path.join(root, rel), 'utf8'); } catch (_) { continue; }
+    const loc = content.split('\n').length;
+    fileList.push({ path: rel, loc });
+    if (used + content.length > CONTEXT_CHAR_CAP) {
+      blocks.push(`### ${rel}\n[not inlined — over the context cap; Read it on demand]\n`);
+      continue;
+    }
+    used += content.length;
+    blocks.push(`### ${rel}\n\`\`\`\n${content}\n\`\`\`\n`);
+  }
+  return { fileList, fileBlocks: blocks.join('\n') };
+}
+
+
+async function main() {
+  const args = process.argv.slice(2);
+  const scope = arg('--scope', args);
+  const paths = arg('--paths', args);
+  // task 1003166 (G02): was 'GDS-V3', long since shipped.
+  const version = arg('--version', args) || await resolveDefaultVersion();
+  if (!version) {
+    console.error('architect-audit: no version is building; pass --version <id>.');
+    process.exit(1);
+  }
+  const dryRun = args.includes('--dry-run');
+
+  if (!scope || !paths) {
+    console.error('Usage: architect-audit.js --scope "<name>" --paths "glob1,glob2,..." [--version GDS-V3] [--dry-run]');
+    process.exit(2);
+  }
+
+  const root = repoRoot();
+  const files = resolvePaths(paths, root);
+  if (files.length === 0) {
+    console.error(`No files matched --paths "${paths}". Use git-tracked paths/globs.`);
+    process.exit(2);
+  }
+
+  const { fileList, fileBlocks } = gatherContext(files, root);
+  const prompt = buildPrompt({ scope, fileList, fileBlocks, version });
+
+  console.log(`🏛  Architect audit — scope "${scope}"`);
+  console.log(`   ${fileList.length} files (${fileList.reduce((a, f) => a + f.loc, 0)} lines), model=${ARCHITECT_MODEL}, version=${version}${dryRun ? '  [DRY RUN]' : ''}`);
+  console.log('   thinking (first-principles audit — this is one big Opus call, ~1-5 min)...');
+
+  let parsed;
+  try {
+    // System 5 (task 1360): cache scoped to the git tree-hash of the in-scope
+    // files — the highest-rerun-value model call (nightly audits re-process an
+    // unchanged main). An unchanged tree → a $0 replay of the prior audit.
+    const scopeSha = llmCache.scopeShaFor(fileList.map((f) => f.path), { cwd: root });
+    const cache = llmCache.makeCacheSpec({ prompt, model: ARCHITECT_MODEL, task_type: 'architect-audit', scope_sha: scopeSha });
+    const { stdout, cached } = await grader.runSubagentCached({ prompt, opts: { model: ARCHITECT_MODEL, timeoutMs: TIMEOUT_MS, cwd: root }, cache });
+    if (cached) console.log('   ⚡ cache hit — replayed a prior identical audit at $0 (tree unchanged since).');
+    const result = grader.extractAssistantResult(stdout);
+    parsed = grader.extractJson(typeof result === 'string' ? result : JSON.stringify(result));
+  } catch (err) {
+    console.error('Architect subagent failed:', err && err.message ? err.message : err);
+    process.exit(1);
+  }
+  if (!parsed || typeof parsed.audit_md !== 'string') {
+    console.error('Architect returned no usable audit_md.');
+    process.exit(1);
+  }
+
+  const seeds = validateSeedIdeas(parsed.seed_ideas);
+  const date = new Date().toISOString().slice(0, 10);
+  const auditSlug = slug(scope);
+  const relDoc = path.join('docs', 'audits', `${auditSlug}-${date}.md`);
+
+  // Assemble the doc (header + the subagent's audit_md).
+  const header = [
+    `# Architecture Audit — ${scope}`,
+    '',
+    `- **Date:** ${date}`,
+    `- **Auditor:** the Architect (MAS Phase 5 — ADR 0024)`,
+    `- **Model:** ${ARCHITECT_MODEL}`,
+    `- **Scope (${fileList.length} files):** ${fileList.map((f) => f.path).join(', ')}`,
+    `- **Seed ideas filed:** see idea_inbox (source=architect-audit), tagged for ${version}`,
+    '',
+    '> Generated by `scripts/bongos/architect-audit.js`. The Architect applies Musk\'s algorithm (delete → simplify → accelerate → automate) from first principles. Seed ideas below feed the next version\'s planning session.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+  const docBody = header + parsed.audit_md.trim() + '\n';
+
+  if (dryRun) {
+    console.log(`\n[DRY RUN] would write ${relDoc} (${docBody.length} chars)`);
+    console.log(`[DRY RUN] would file ${seeds.length} seed idea(s):`);
+    for (const s of seeds) console.log(`   - [${s.kind}] ${s.title}`);
+    console.log('\n--- audit_md preview (first 1600 chars) ---\n');
+    console.log(parsed.audit_md.slice(0, 1600));
+    process.exit(0);
+  }
+
+  // Write the audit doc.
+  fs.mkdirSync(path.join(root, 'docs', 'audits'), { recursive: true });
+  fs.writeFileSync(path.join(root, relDoc), docBody);
+  console.log(`\n📜 wrote ${relDoc}`);
+
+  // File the seed ideas to the planning inbox. Payload mirrors capture.js
+  // (POST /api/bongos/inbox): { title, body_md, kind, suggested_version }.
+  // Provenance (which audit produced it) is folded into body_md.
+  let filed = 0;
+  const api = await cliClient();
+  for (const s of seeds) {
+    const r = await api.inbox.postInbox({
+      body: {
+        title: s.title,
+        kind: s.kind,
+        body_md: `${s.body_md}\n\n— filed by the Architect from audit \`${relDoc}\` (scope: ${scope}).`,
+        suggested_version: version,
+      },
+    });
+    if (r.ok) { filed++; console.log(`   📥 #${r.data?.idea?.id ?? '?'} [${s.kind}] ${s.title}`); }
+    else console.error(`   ✗ failed to file "${s.title}" (${r.status})`);
+  }
+  console.log(`\n🏛  Architect audit complete — ${relDoc} + ${filed}/${seeds.length} seed idea(s) filed for ${version}.`);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error('Architect error:', err && err.message ? err.message : err); process.exit(1); });
+}
+
+module.exports = { slug, pickValidKind, validateSeedIdeas, buildPrompt, PROMPT_HEADER };

package/scripts/bongos/artifact-audit.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/artifact-audit.js — does the work a task CLAIMS actually exist? (task 1003200)
+//
+// THE GAP. `confirmed` means verified and credited, awaiting land. A task can therefore be
+// paid for and reported as done while its artifact exists nowhere reachable. On 2026-08-23
+// three such tasks were found BY ACCIDENT, one at a time: 1003158 (body said "BUILT, tested,
+// 33 tests green"; branch absent from origin), 1002459 (`confirmed` — verified and credited;
+// no branch anywhere), 1002792 (`completed`; the validator it claimed to change was
+// untouched). Nothing compared "the task claims an artifact" against "an artifact exists".
+//
+// WHY THE RECONCILER IS NOT THIS. publish-reconciler.js already proves a land — but only for
+// tasks it is sweeping at `confirmed`, and it writes its misses to a log line. It says nothing
+// about `shipped`, which is where a false "done" is most dangerous: the credit is booked, the
+// ledger reads finished, and no sweep will ever look again.
+//
+// SHAPE COPIED FROM deploy-divergence.js / strand-watch.js, deliberately: cheap, bounded,
+// fail-open, and SILENT when the board is clean. A check that cries wolf gets ignored, and an
+// ignored check is worse than none — which is why the narrowing below is documented step by
+// step rather than tuned until the number looked nice.
+//
+// THE NARROWING (measured 2026-09-16, and every step exists because the previous one lied):
+//
+//   2617  tasks at shipped/confirmed/completed
+//    650  shipped on or after the ship-assurance gate (2026-08-19, task 1002483 / ADR 0184).
+//         Before that gate a DB-only ship recorded no declaration at all, so "no artifact"
+//         is unprovable rather than suspicious — 1469 older ships would be pure noise.
+//     33  with no COMMIT MESSAGE on main naming the task
+//     25  …and no FILE CONTENT on main naming it either. This second source is not optional:
+//         task 1003212's fix is on main and cited in a code comment, but the commit that
+//         carried it never named the task, so a message-only index calls it stranded. That
+//         is the "landed under another branch" case, and it is why this check reads both.
+//      3  …and which actually DECLARE a code artifact (non-empty touches[]). The other 22
+//         declare none — goal edits, claim releases, triage, deploys — and are codeless by
+//         shape, reported quietly instead of as alarms.
+//
+// WHAT THIS CHECK CANNOT DO, stated so nobody trusts it further than it earns. The assurance
+// ledger (`no_artifact` + reason, ship-assurance.js) is written into the audit log, and NO API
+// route exposes it. So "declares no artifact" here is inferred from an EMPTY touches[], not
+// read from the declaration the ship actually made. Exposing the assurance would make the
+// codeless bucket exact; until then it is a shape, and a deploy/ops task whose touches[]
+// describes what a RELEASE carried (rather than what it committed) can land in `stranded`.
+//
+// Usage:
+//   node scripts/bongos/artifact-audit.js              # human-readable report
+//   node scripts/bongos/artifact-audit.js --line       # ONE line, or nothing; always exit 0
+//   node scripts/bongos/artifact-audit.js --json       # machine shape
+//   node scripts/bongos/artifact-audit.js --all        # include the pre-gate ships too
+//   node scripts/bongos/artifact-audit.js --since YYYY-MM-DD   # override the gate date
+//   node scripts/bongos/artifact-audit.js --file-blocker       # ALSO file findings as a blocker
+//
+// Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
+
+const { execFileSync } = require('node:child_process');
+const { apiCall, arg, hasFlag } = require('./cli-lib');
+const { TASK_LIST_MAX_LIMIT, buildTaskPageQuery } = require('../../modules/lifecycle/task-list-limits.js');
+const { postWithAsk } = require('./ask.js');
+
+// The statuses where a claimed artifact is supposed to already exist. `shipped` is the one the
+// reconciler never revisits, and the reason this file exists.
+const AUDITED_STATUSES = Object.freeze(['shipped', 'confirmed', 'completed']);
+
+// task 1002483 / ADR 0184 landed the ship-assurance gate on this date. It is the earliest point
+// at which a no-artifact ship had to say so, and therefore the earliest point at which silence
+// means anything at all.
+const ASSURANCE_GATE_DATE = '2026-08-19';
+
+// How a task id is written when something references it: `task 1003200`, `task-1003200`,
+// `task #1003200`. Ids are 6–7 digits; anything shorter is a PR or an issue, not ours.
+const TASK_REF = /task[ _-]#?(\d{6,7})/gi;
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+
+// ---- pure core --------------------------------------------------------------------------
+// Everything below this comment is IO. Everything above the next one is a pure function of
+// (tasks, two evidence sets), which is what tests/artifact_audit.mjs drives with the three
+// real 2026-08-23 cases as fixtures.
+
+function taskIdsIn(text) {
+  const out = new Set();
+  for (const m of String(text || '').matchAll(TASK_REF)) out.add(m[1]);
+  return out;
+}
+
+// Does this task DECLARE a code artifact? touches[] is the task's own statement about which
+// files its work lands in, so a non-empty one is a promise that something reached the tree.
+function declaresArtifact(task) {
+  return Array.isArray(task.touches) && task.touches.some((p) => String(p || '').trim().length > 0);
+}
+
+// The audit. `messageIds` / `contentIds` are sets of task ids evidenced on main by a commit
+// message and by file content respectively; keeping them separate is what lets the report say
+// HOW a task was proven, which is the difference between a finding and an accusation.
+function auditArtifacts(tasks, { messageIds, contentIds, gateDate = ASSURANCE_GATE_DATE } = {}) {
+  const msg = messageIds instanceof Set ? messageIds : new Set(messageIds || []);
+  const content = contentIds instanceof Set ? contentIds : new Set(contentIds || []);
+  const out = { evidenced: [], preGate: [], codeless: [], stranded: [] };
+
+  for (const t of Array.isArray(tasks) ? tasks : []) {
+    if (!t || !AUDITED_STATUSES.includes(String(t.status))) continue;
+    const id = String(t.id);
+    const row = {
+      id,
+      status: String(t.status),
+      shipped_at: t.shipped_at ? String(t.shipped_at).slice(0, 10) : null,
+      title: String(t.title || ''),
+      touches: Array.isArray(t.touches) ? t.touches : [],
+    };
+
+    // Evidence first, and cheapest first. A task named by a commit message landed under its
+    // own branch; one named only in file content landed under someone else's.
+    if (msg.has(id)) { out.evidenced.push({ ...row, how: 'commit-message' }); continue; }
+    if (content.has(id)) { out.evidenced.push({ ...row, how: 'file-content' }); continue; }
+
+    // Unevidenced. Before the assurance gate, silence is not a signal — see the header.
+    if (!row.shipped_at || row.shipped_at < gateDate) { out.preGate.push(row); continue; }
+
+    (declaresArtifact(t) ? out.stranded : out.codeless).push(row);
+  }
+  return out;
+}
+
+// ---- IO ---------------------------------------------------------------------------------
+
+function gitLines(args) {
+  // `git grep` exits 1 when it matches nothing, which is a legitimate empty result, not a
+  // failure. Anything else is genuinely broken and must not read as "no strands".
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+  } catch (e) {
+    if (e && e.status === 1 && typeof e.stdout === 'string') return e.stdout;
+    throw e;
+  }
+}
+
+// Evidence A — every task id named by a commit message reachable from origin/main.
+function messageEvidence(ref) {
+  return taskIdsIn(gitLines(['log', ref, '--format=%s%n%b']));
+}
+
+// Evidence B — every task id named by the CONTENT of a tracked file on origin/main. The repo's
+// doc-comment convention (ADR 0095) cites the task that made a change, so the tree itself is a
+// second, independent record of what landed. -I skips binaries; without it a matching byte run
+// in an image would be counted as a citation.
+function contentEvidence(ref) {
+  return taskIdsIn(gitLines(['grep', '-hoIE', 'task[ _-]#?[0-9]{6,7}', ref]));
+}
+
+// Every task in an audited status, paged — the corpus is well past one page, and asking for
+// more than the cap is a 400 (task 1003752, which is why buildTaskPageQuery exists).
+// `call` is injected (the strand-watch.js pattern) so tests can drive the paging loop with
+// no session and no network.
+async function fetchAuditedTasks({ call = apiCall } = {}) {
+  const rows = [];
+  for (const status of AUDITED_STATUSES) {
+    let offset = 0;
+    for (let page = 0; page < 100; page++) {
+      const q = buildTaskPageQuery({ status, limit: TASK_LIST_MAX_LIMIT, offset });
+      const qs = new URLSearchParams(q).toString();
+      const r = await call('GET', `/api/bongos/tasks?${qs}`);
+      if (!r || !r.ok) throw new Error(`GET /tasks?status=${status} → ${r && r.status}`);
+      const page_rows = (r.data && r.data.tasks) || [];
+      rows.push(...page_rows);
+      if (page_rows.length < q.limit) break;
+      offset += q.limit;
+    }
+  }
+  return rows;
+}
+
+module.exports = {
+  auditArtifacts, declaresArtifact, taskIdsIn,
+  AUDITED_STATUSES, ASSURANCE_GATE_DATE, TASK_REF,
+  messageEvidence, contentEvidence, fetchAuditedTasks,
+  blockerSourceRef, blockerBody, blockerAsk, fileBlocker,
+};
+
+// ---- the human surface ------------------------------------------------------------------
+// A journal line is where the previous three strands went to die: the reconciler DID diagnose
+// 1002459 and wrote 'land_not_proven' down, and nobody ever read the field. So a finding goes
+// to the Archon blocker surface, where a person actually looks.
+//
+// IDEMPOTENT BY THE FINDING SET, not by the run. POST /blockers dedupes on
+// (source, source_ref), so re-running with the same findings returns 200 {skipped} instead of
+// filing a second copy — but a CHANGED set (a new unproven task) has a different source_ref
+// and files a fresh blocker. A check that spams is a check that gets muted.
+function blockerSourceRef(stranded) {
+  return `unproven:${stranded.map((s) => s.id).sort().join(',')}`;
+}
+
+function blockerBody(stranded) {
+  const lines = [
+    `${stranded.length} task(s) at shipped/confirmed/completed declare a code artifact that nothing on \`main\` names — neither a commit message nor any file's content.`,
+    '',
+    'A task in these statuses has already been credited. If the work is genuinely absent, the ledger is reporting finished work that does not exist (task 1003200).',
+    '',
+  ];
+  for (const s of stranded) {
+    lines.push(`- **task ${s.id}** (${s.status}, shipped ${s.shipped_at}) — ${s.title.slice(0, 90)}`);
+    lines.push(`  - declares: ${s.touches.join(', ')}`);
+  }
+  lines.push('');
+  lines.push('**Confirm each by hand before acting.** A deploy/ops task often lists what a RELEASE carried rather than what it committed, and this check cannot tell those apart: the ship-assurance ledger (a no_artifact declaration and its reason) is written to the audit log and no API route exposes it, so "declares no artifact" is inferred from an empty touches[]. Exposing that declaration would make this exact.');
+  lines.push('');
+  lines.push('Re-run: node scripts/bongos/artifact-audit.js');
+  return lines.join('\n');
+}
+
+// The card a person answers (task 1004704): the finding as an ask, short enough
+// to decide at a glance; the body above carries the list.
+function blockerAsk(stranded) {
+  const n = stranded.length;
+  return {
+    question: `Check by hand the ${n} shipped task${n === 1 ? '' : 's'} nothing on main names?`,
+    options: [
+      { key: 'check', label: 'Check each', result: 'Someone reads each by hand before anything is reopened.', act: 'go ahead' },
+      { key: 'accept', label: 'Accept them', result: 'They stay shipped and credited as they are.', act: 'not now' },
+    ],
+    recommend: { key: 'check', why: 'A credited task with no code may be paid work that does not exist.' },
+    waits_on: 'lead:review',
+    if_nobody_answers: 'They stay shipped and credited, unchecked.',
+  };
+}
+
+async function fileBlocker(stranded, { call = apiCall } = {}) {
+  if (!stranded.length) return { filed: false, reason: 'nothing to report' };
+  const r = await postWithAsk((body) => call('POST', '/api/bongos/blockers', body), {
+    title: `${stranded.length} shipped task(s) claim an artifact nothing on main names`,
+    body_md: blockerBody(stranded),
+    source: 'artifact-audit',
+    source_ref: blockerSourceRef(stranded),
+  }, blockerAsk(stranded));
+  if (!r || !r.ok) return { filed: false, reason: `POST /blockers → ${r && r.status}` };
+  if (r.data && r.data.skipped) return { filed: false, reason: 'already filed for this exact finding set' };
+  return { filed: true, id: r.data && r.data.blocker && r.data.blocker.id };
+}
+
+// ---- CLI --------------------------------------------------------------------------------
+
+function strandLine(s) {
+  return `Unproven artifact: task ${s.id} (${s.status}, shipped ${s.shipped_at}) claims `
+    + `${s.touches.length} path(s) but nothing on main names it — ${s.touches.slice(0, 2).join(', ')}`;
+}
+
+async function main() {
+  const asJson = hasFlag('--json');
+  const asLine = hasFlag('--line');
+  const includeAll = hasFlag('--all');
+  const gateDate = arg('--since') || ASSURANCE_GATE_DATE;
+  const wantBlocker = hasFlag('--file-blocker');
+  const ref = arg('--ref') || 'origin/main';
+
+  let result;
+  try {
+    const [tasks, messageIds, contentIds] = await Promise.all([
+      fetchAuditedTasks(),
+      Promise.resolve(messageEvidence(ref)),
+      Promise.resolve(contentEvidence(ref)),
+    ]);
+    result = auditArtifacts(tasks, { messageIds, contentIds, gateDate });
+    result.scanned = tasks.length;
+  } catch (e) {
+    // Fail-open, loudly on the full report and silently on --line. A check that cannot run
+    // must never be mistaken for a check that found nothing (task 1003752's whole lesson).
+    if (asLine) return 0;
+    console.error(`artifact-audit: could not complete (${e.message})`);
+    return 2;
+  }
+
+  const { stranded, codeless, preGate, evidenced, scanned } = result;
+
+  if (asLine) {
+    if (stranded.length) {
+      console.log(
+        `${stranded.length} task(s) claim an artifact nothing on main names: `
+        + `${stranded.slice(0, 3).map((s) => s.id).join(', ')}${stranded.length > 3 ? '…' : ''}. `
+        + 'Run `node scripts/bongos/artifact-audit.js` — a shipped task whose work never landed is credited work that does not exist.'
+      );
+    }
+    return 0;
+  }
+
+  if (asJson) {
+    // preGate collapses to a COUNT unless --all: it is ~1456 rows that are
+    // unprovable by construction, and emitting them by default would bury the
+    // handful of rows a consumer actually has to act on.
+    console.log(JSON.stringify(includeAll ? result : { ...result, preGate: preGate.length }, null, 2));
+    return stranded.length ? 1 : 0;
+  }
+
+  console.log(
+    `artifact-audit: ${scanned} task(s) at ${AUDITED_STATUSES.join('/')} — `
+    + `${evidenced.length} proven on ${ref}, ${preGate.length} predate the assurance gate (${gateDate}), `
+    + `${codeless.length} declare no artifact, ${stranded.length} UNPROVEN\n`
+  );
+
+  for (const s of stranded) {
+    console.log(`[UNPROVEN] ${strandLine(s)}`);
+    console.log(`           all paths: ${s.touches.join(', ')}`);
+    console.log(`           ${s.title.slice(0, 78)}`);
+    console.log('           → confirm by hand before acting: a deploy/ops task may list what a RELEASE');
+    console.log('             carried rather than what it committed. If the work is genuinely absent, it');
+    console.log('             must be redone or the ship corrected — it was credited.\n');
+  }
+
+  if (wantBlocker && stranded.length) {
+    const filed = await fileBlocker(stranded);
+    console.log(filed.filed
+      ? `Filed blocker ${filed.id} on the Archon surface.`
+      : `Blocker not filed: ${filed.reason}.`);
+  }
+
+  if (!stranded.length) {
+    console.log('Nothing unproven — every post-gate task that claims a code artifact is named on main.');
+  }
+  if (includeAll && preGate.length) {
+    console.log(`\nPre-gate (unprovable by design, ${preGate.length}): ${preGate.slice(0, 20).map((p) => p.id).join(', ')}${preGate.length > 20 ? '…' : ''}`);
+  }
+  return stranded.length ? 1 : 0;
+}
+
+if (require.main === module) {
+  main().then((c) => { process.exitCode = c; })
+    .catch((e) => { console.error('artifact-audit:', e.message); process.exit(2); });
+}