@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/status.js

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+// /status — one-call project status rollup (#435, ADR 0025).
+//
+// Answers "what's left for criterion C8?" in a single call, replacing the
+// ~10-step prose archaeology (grep seed file → eyeball "Gates R55–R63" →
+// re-query each task) that motivated the task. Reads the structured
+// criterion↔task link (task_criteria, migration 055) via the public endpoint
+// GET /api/bongos/versions/:id/progress.
+//
+// Usage:
+//   node scripts/bongos/status.js                          # all criteria, default version
+//   node scripts/bongos/status.js wa6-kernel-and-packs     # drill in by SLUG (the identity)
+//   node scripts/bongos/status.js C8                       # …or by position (an affordance)
+//   node scripts/bongos/status.js --criterion C8           # exact form, no guessing
+//   node scripts/bongos/status.js --version V1             # another version
+//   node scripts/bongos/status.js --version GDS-V3 C8
+//   node scripts/bongos/status.js --json                   # machine-readable
+//
+// WHICH NAME IS THE IDENTITY (task 1004069). The SLUG. `Cn` is a presentation
+// ordinal recomputed live from a reorderable sort_order, so inserting one
+// criterion renumbers every criterion after it, version-wide, silently — and
+// the write path (`resolveCriterionIds`) already REFUSES a positional ref on any
+// multi-goal version for exactly that reason. This CLI used to print `Cn` as
+// each row's identity and accept nothing else, so the one documented way to
+// drill in was the one form the rest of the system calls unsafe. Now the slug
+// leads in every output mode and BOTH forms resolve on input; a positional ref
+// answers with the slug it landed on, so the reader can quote the stable name.
+// The ref vocabulary itself is ../../modules/lifecycle/criterion-ref.js — one
+// definition, shared with the write path, which is what stops the two drifting
+// apart again.
+//
+// Read-only and UNAUTHENTICATED (the endpoint is public, same posture as
+// /versions/:id/done-when), so it works before /builder-setup too.
+//
+// Exit codes: 0 ok · 1 network/api error · 2 bad invocation · 3 not found.
+
+const { API_BASE, cliClient, assertInstanceMatch, cliExit } = require('./cli-lib');
+const { resolveEnv } = require('../../src/instance-config');
+const { resolveDefaultVersion } = require('./version-select.js');
+// task 1004392 (ADR 0351): the criterion's UAT state, in the same words the
+// server and /goal-uat use. Dependency-free, so this public CLI pays nothing.
+const { stateLabel } = require('../../modules/lifecycle/criterion-uat.js');
+
+// One criterion's state as a short phrase. A server older than the UAT rule
+// sends no uat_state, and then the old satisfied/not answer is the truth.
+function criterionStateText(c) {
+  if (!c.uat_state) return c.satisfied ? 'satisfied ✓' : 'not satisfied';
+  const label = stateLabel(c.uat_state);
+  return c.satisfied ? `${label} ✓` : label;
+}
+const {
+  looksLikeVersionId,
+  resolveCriterionIn,
+  criterionLabel,
+} = require('../../modules/lifecycle/criterion-ref.js');
+
+// The active internal version is RESOLVED, never named here. Override with
+// <PREFIX>_STATUS_DEFAULT_VERSION or --version.
+//
+// WHY THERE IS NO LITERAL (task 1004071). This line used to read
+//   const DEFAULT_VERSION = resolveEnv('STATUS_DEFAULT_VERSION') || 'BONGOS-V1';
+// under a comment promising "the bare /status card should default to the live
+// version, not a sealed one" — the same fix task 1709 had already applied once,
+// for GDS-V4 → BONGOS-V1. BONGOS-V1 then sealed, nobody bumped the literal, and
+// /status served a shipped version's closing scoreboard (140/203 satisfied) as
+// the project's current status. It reads as a healthy project, which is why it
+// sat: nothing in the output says `shipped`, and /status is what a session runs
+// precisely when it does NOT already know. Bumping the literal again would only
+// re-arm the same bomb for whoever seals BONGOS-V2, so the rule is derived from
+// `versions.status` instead — the selection capture.js has always used.
+
+// Compact, status-first ordering for the "remaining: …" summaries.
+const STATUS_ORDER = ['shipped', 'confirmed', 'completed', 'claimed', 'ready', 'blocked', 'backlog'];
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let version = null;
+  let criterion = null;
+  let json = false;
+  let widget = false;
+  let hook = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--version' || a === '-v') {
+      version = args[++i];
+      if (version == null) return { error: '--version requires a value' };
+    } else if (a === '--criterion' || a === '-c') {
+      criterion = args[++i];
+      if (criterion == null) return { error: '--criterion requires a value' };
+    } else if (a === '--json') json = true;
+    else if (a === '--widget') widget = true;
+    else if (a === '--hook') hook = true;
+    else if (a === '--help' || a === '-h') return { help: true };
+    else if (a.startsWith('-')) return { error: `unknown flag: ${a}` };
+    // A bare token is a VERSION only if it is shaped like one (V1, GDS-V4,
+    // BONGOS-V2); everything else is a criterion ref, so a slug can be typed
+    // where only `Cn` used to fit. Shape, not order: `status.js
+    // wa6-kernel-and-packs` used to be swallowed as a version id and 404 the
+    // progress fetch. `--version` / `--criterion` are the exact forms that skip
+    // this test entirely, for a caller who will not be guessed at.
+    else if (!version && looksLikeVersionId(a)) version = a;
+    else if (!criterion) criterion = a;
+    else if (!version) version = a;
+    else return { error: `unexpected argument: ${a}` };
+  }
+  // No `versionExplicit` companion flag: `version !== null` already IS that
+  // fact, and resolveVersion returns `defaulted`/`source` for anyone who needs
+  // to act on it. A second field carrying the same truth is one that can drift.
+  // `criterion` is kept VERBATIM — never uppercased, which is what made a slug
+  // unrepresentable here. Case-folding belongs to the resolver, which matches
+  // slugs case-insensitively and `Cn` case-insensitively too.
+  return { version: version || null, criterion: criterion || null, json, widget, hook };
+}
+
+// Resolve which version this invocation is about. Precedence: an explicit
+// --version (or bare token) > the env override > the live BUILDING version.
+// Returns { version, defaulted, source }; version is NULL when nothing is
+// building, which the caller must treat as "stop and say so", never as a guess.
+// Deps are injectable so the precedence is unit-tested without a session.
+async function resolveVersion(opts, deps = {}) {
+  if (opts.version) return { version: opts.version, defaulted: false, source: 'flag' };
+  const env = (deps.resolveEnv || resolveEnv)('STATUS_DEFAULT_VERSION');
+  if (env) return { version: env, defaulted: true, source: 'env' };
+  const resolve = deps.resolveDefaultVersion || resolveDefaultVersion;
+  const building = await resolve();
+  if (building) return { version: building, defaulted: true, source: 'building' };
+  return { version: null, defaulted: true, source: 'none' };
+}
+
+// One line naming a version the USER did not, so a cross-version answer cannot
+// pass unnoticed. `Cn` is version-scoped and the versions number independently
+// — BONGOS-V1 C8 is `money-one-unit`, BONGOS-V2 C8 is `wa6-kernel-and-packs` —
+// so a silently-defaulted version answers a different question than the one
+// asked. Empty when the user named the version: they already know.
+function defaultedVersionNote(r) {
+  if (!r || !r.defaulted || !r.version) return '';
+  const why = r.source === 'env' ? 'from STATUS_DEFAULT_VERSION' : 'the version currently building';
+  return `(no version given — showing ${r.version}, ${why}. Pass --version to pick another.)`;
+}
+
+// One line naming the STABLE name a positional ref landed on, so whatever the
+// reader quotes next survives the next criterion anyone inserts. `Cn` is
+// recomputed from sort_order on every read: creating `wa6-noise-limited` moved
+// `wa10-execution-integrity` from C11 to C13, and every note, doc and click
+// handler still saying C11 now points at a different criterion. Empty when the
+// user already named the slug — they are holding the durable form.
+function positionalRefNote(c, kind) {
+  if (!c || kind !== 'cnum') return '';
+  return `(C${c.cnum} is a position, recomputed whenever a criterion is added or reordered.`
+    + ` The stable name is \`${c.criterion_id}\` — quote that.)`;
+}
+
+async function fetchProgress(version) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/bongos/versions/${encodeURIComponent(version)}/progress`, {
+      headers: { 'User-Agent': require('../../src/branding').userAgent() },
+    });
+  } catch (err) {
+    console.error(`status: could not reach ${API_BASE} (${err.message})`);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    console.error(`status: GET /versions/${version}/progress → ${res.status}`);
+    process.exit(1);
+  }
+  return res.json();
+}
+
+// "R54" if the title is a "V3.R54 — …" rank-prefixed title, else "".
+function rankTag(title) {
+  const m = /\bR\d+\b/.exec(title || '');
+  return m ? m[0] : '';
+}
+
+function shortTitle(title, max = 52) {
+  const t = (title || '').replace(/^V\d+\.R\d+\s*[—-]\s*/, ''); // drop the "V3.R54 — " prefix
+  return t.length > max ? t.slice(0, max - 1) + '…' : t;
+}
+
+// "area 6" for a working-area goal, else nothing (task 1004057). Read from the
+// goal's working_area FIELD, never parsed from its title and never taken from
+// sort_order or the id, which both look like it and are not.
+function areaTag(g) {
+  const n = g && g.working_area;
+  return Number.isInteger(n) && n > 0 ? 'area ' + n : '';
+}
+
+// "1 confirmed, 2 backlog" — non-shipped tasks grouped by status, ordered.
+function remainingSummary(remaining) {
+  if (remaining.length === 0) return 'none — all shipped ✓';
+  const byStatus = {};
+  for (const t of remaining) byStatus[t.status] = (byStatus[t.status] || 0) + 1;
+  // Unknown statuses sort last (rank 999), known ones by STATUS_ORDER position.
+  const rank = (s) => {
+    const i = STATUS_ORDER.indexOf(s);
+    return i < 0 ? 999 : i;
+  };
+  const parts = Object.keys(byStatus)
+    .sort((a, b) => rank(a) - rank(b))
+    .map((s) => `${byStatus[s]} ${s}`);
+  return parts.join(', ');
+}
+
+function bar(shipped, total, width = 10) {
+  if (total === 0) return '─'.repeat(width);
+  const filled = Math.round((shipped / total) * width);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+// The POSITION column only. It is deliberately narrow and deliberately not the
+// row's name: the criterion_id beside it is what a reader should carry away.
+function clabel(c) {
+  return `C${c.cnum}`.padEnd(3);
+}
+
+// ---------- card renderers (task 1288: deterministic /status card) ----------
+// Status had no card — it printed freeform text the skill was told to
+// "interpret + relay", the exact per-session non-determinism the card
+// methodology removes. These render the SAME rollup as a self-contained widget
+// (--widget, and the --hook HTML form) and as a markdown card (the --hook
+// markdown form / widgets-off / no-renderer fallback). Design mirrors the
+// builder-start card (flat, 0.5px borders, CSS theme vars, Tabler icons, no
+// emoji); classes are `.st-*` so they can't collide with builder-start's `.bs-*`
+// or the ship card's `.cc-*`.
+const sesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+// A value going inside a single-quoted JS string inside an HTML attribute needs
+// BOTH escapes, in that order. Task ids are digits so the existing handlers get
+// away with `sesc` alone; a criterion_id is free text from the DB, and an
+// apostrophe in one would close the sendPrompt argument early and break every
+// row's click. Escape for JS first, then for the attribute.
+const jsq = (s) => sesc(String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/'/g, "\\'"));
+
+const STATUS_WIDGET_STYLE = `<style>
+.st-sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;}
+.st-card{background:var(--color-background-primary);border:0.5px solid var(--color-border-tertiary);border-radius:var(--border-radius-lg);padding:1rem 1.25rem;font-family:var(--font-sans);}
+.st-head{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;}
+.st-title{font-size:16px;font-weight:500;}
+.st-title i{font-size:16px;vertical-align:-2px;margin-right:6px;color:#378ADD;}
+.st-meta{font-size:13px;color:var(--color-text-secondary);}
+.st-crit{font-size:13px;color:var(--color-text-secondary);margin-top:8px;}
+.st-bar{display:inline-block;width:48px;height:5px;border-radius:3px;background:var(--color-border-tertiary);overflow:hidden;vertical-align:middle;margin-right:6px;}
+.st-barfill{display:block;height:100%;background:#1D9E75;}
+.st-table{width:100%;border-collapse:collapse;table-layout:fixed;font-size:13px;margin-top:10px;}
+.st-thead{text-align:left;color:var(--color-text-tertiary);font-size:12px;}
+.st-th{padding:0 6px 4px;font-weight:400;}
+.st-tr{cursor:pointer;}
+.st-td{padding:7px 6px;border-top:0.5px solid var(--color-border-tertiary);vertical-align:top;}
+.st-id{color:var(--color-text-secondary);font-family:var(--font-mono);font-size:12px;}
+.st-ok{color:var(--color-text-success);}
+.st-ellip{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+.st-sub{color:var(--color-text-secondary);}
+.st-nowrap{white-space:nowrap;}
+.st-foot{font-size:13px;color:var(--color-text-tertiary);margin-top:12px;}
+</style>`;
+
+function widgetBar(shipped, total) {
+  const pct = total > 0 ? Math.round((shipped / total) * 100) : 0;
+  return `<span class="st-bar"><span class="st-barfill" style="width:${pct}%;"></span></span>`;
+}
+
+// Self-contained HTML for the app's widget renderer (show_widget). `criterion`
+// null → version overview (rows drill into a criterion); set → one criterion's
+// gating tasks (ready rows claim).
+function renderStatusWidget(data, criterion) {
+  if (criterion) {
+    const c = criterion;
+    const rows = c.tasks.map((t) => {
+      const tag = rankTag(t.title);
+      const claimable = t.status === 'ready';
+      const click = claimable
+        ? ` role="button" tabindex="0" onclick="sendPrompt('Claim task ${t.id}')" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();sendPrompt('Claim task ${t.id}')}"`
+        : '';
+      return `<tr class="st-tr"${click}><td class="st-td st-sub st-nowrap">${sesc(t.status)}</td><td class="st-td st-id">#${t.id}${tag ? ' ' + sesc(tag) : ''}</td><td class="st-td st-ellip" title="${sesc(t.title)}">${sesc(shortTitle(t.title, 80))}</td></tr>`;
+    }).join('');
+    const body = c.tasks.length
+      ? `<table class="st-table"><colgroup><col style="width:84px;"><col style="width:92px;"><col></colgroup><thead><tr class="st-thead"><th class="st-th">Status</th><th class="st-th">#</th><th class="st-th">Task</th></tr></thead><tbody>${rows}</tbody></table>`
+      : `<div class="st-crit">No tasks linked to this criterion yet.</div>`;
+    const claimHint = c.tasks.some((t) => t.status === 'ready') ? ' · click a ready task to claim it' : '';
+    return `${STATUS_WIDGET_STYLE}
+<h2 class="st-sr">${sesc(data.version_id)} criterion ${sesc(criterionLabel(c))} ${c.satisfied ? 'is satisfied' : 'is not yet satisfied'}: ${c.counts.shipped} of ${c.counts.total} gating tasks shipped.</h2>
+<div class="st-card">
+  <div class="st-head"><span class="st-title"><i class="ti ti-checklist" aria-hidden="true"></i>${sesc(data.version_id)} · ${sesc(criterionLabel(c))}</span><span class="st-meta">${c.satisfied ? `<span class="st-ok">${sesc(criterionStateText(c))}</span>` : sesc(criterionStateText(c))} · ${c.counts.shipped}/${c.counts.total} shipped</span></div>
+  <div class="st-crit">${sesc(c.criterion_md.replace(/\*\*/g, '').slice(0, 160))}</div>
+  ${body}
+  <div class="st-foot">remaining: ${sesc(remainingSummary(c.remaining))}${claimHint}</div>
+</div>`;
+  }
+  const satisfied = data.criteria.filter((x) => x.satisfied).length;
+  // Version → Goals → Criteria (ADR 0086 §2 / BV1.R58). Render each criterion
+  // row under its goal's header. Fall back to a flat list if the rollup carries
+  // no goals (older payload).
+  // The click sends the SLUG, never the position. A rendered card outlives the
+  // ordering it was rendered from: every handler here used to carry `/status
+  // C11`, so one criterion inserted anywhere above turned every drill-in on a
+  // card already in someone's transcript into a different criterion, silently.
+  // The slug survives an insert, a reorder, and a card read tomorrow.
+  const critRow = (c) =>
+    `<tr class="st-tr" role="button" tabindex="0" title="Drill into ${sesc(c.criterion_id)} (C${c.cnum})" onclick="sendPrompt('/status ${jsq(c.criterion_id)}')" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();sendPrompt('/status ${jsq(c.criterion_id)}')}"><td class="st-td st-ok st-nowrap">${c.satisfied ? '✓' : ''}</td><td class="st-td st-ellip" title="${sesc(c.criterion_id)}">${sesc(c.criterion_id)}</td><td class="st-td st-id">C${c.cnum}</td><td class="st-td st-nowrap">${widgetBar(c.counts.shipped, c.counts.total)}${c.counts.shipped}/${c.counts.total}</td><td class="st-td st-ellip st-sub">${c.remaining.length ? sesc(remainingSummary(c.remaining)) : '—'}</td></tr>`;
+  const goals = (data.goals && data.goals.length) ? data.goals : null;
+  const rows = goals
+    ? goals.map((g) => {
+        const ach = g.status === 'achieved';
+        const head = `<tr><td class="st-td" colspan="5" style="background:var(--color-background-secondary);font-weight:500;"><i class="ti ti-target" aria-hidden="true"></i> ${sesc(g.title)} <span class="st-sub">· ${areaTag(g) ? sesc(areaTag(g)) + ' · ' : ''}${ach ? '<span class="st-ok">achieved</span>' : sesc(g.status)}${g.criteria.length ? '' : ' · no criteria yet'}</span></td></tr>`;
+        return head + g.criteria.map(critRow).join('');
+      }).join('')
+    : data.criteria.map(critRow).join('');
+  const goalMeta = goals ? ` · ${data.goals_achieved}/${data.goals_total} goals${data.version_done ? ' ✓' : ''}` : '';
+  const foot = data.unattributed_tasks > 0
+    ? `<div class="st-foot">${data.unattributed_tasks} task(s) not linked to any criterion · click a row to drill in</div>`
+    : `<div class="st-foot">Click a criterion to see its gating tasks</div>`;
+  return `${STATUS_WIDGET_STYLE}
+<h2 class="st-sr">${sesc(data.version_id)} status: ${satisfied} of ${data.criteria.length} done-when criteria satisfied across ${goals ? data.goals_total : 0} goal(s). Click a criterion to drill in.</h2>
+<div class="st-card">
+  <div class="st-head"><span class="st-title"><i class="ti ti-checklist" aria-hidden="true"></i>${sesc(data.version_id)} status</span><span class="st-meta">${satisfied}/${data.criteria.length} criteria${goalMeta}</span></div>
+  <table class="st-table"><colgroup><col style="width:24px;"><col><col style="width:44px;"><col style="width:96px;"><col style="width:120px;"></colgroup><thead><tr class="st-thead"><th class="st-th"></th><th class="st-th">Criterion</th><th class="st-th">Pos</th><th class="st-th">Shipped</th><th class="st-th">Remaining</th></tr></thead><tbody>${rows}</tbody></table>
+  ${foot}
+</div>`;
+}
+
+// The markdown form — the --hook fallback / widgets-off / no-renderer surface.
+// Same rollup, rendered verbatim everywhere.
+function renderStatusMarkdown(data, criterion) {
+  const lines = [];
+  if (criterion) {
+    const c = criterion;
+    lines.push(`**/status · ${data.version_id} · ${criterionLabel(c)}** — ${criterionStateText(c)}`);
+    lines.push(`_${c.criterion_md.replace(/\*\*/g, '').slice(0, 160)}_`);
+    lines.push('');
+    if (c.tasks.length) {
+      lines.push('| Status | # | Task |');
+      lines.push('|---|---|---|');
+      for (const t of c.tasks) {
+        const tag = rankTag(t.title);
+        lines.push(`| ${t.status} | #${t.id}${tag ? ' ' + tag : ''} | ${shortTitle(t.title, 60)} |`);
+      }
+    } else {
+      lines.push('_No tasks linked to this criterion yet._');
+    }
+    lines.push('');
+    lines.push(`${c.counts.shipped}/${c.counts.total} shipped · remaining: ${remainingSummary(c.remaining)}`);
+    return lines.join('\n');
+  }
+  const satisfied = data.criteria.filter((x) => x.satisfied).length;
+  const goals = (data.goals && data.goals.length) ? data.goals : null;
+  const goalMeta = goals ? ` · ${data.goals_achieved}/${data.goals_total} goals achieved${data.version_done ? ' ✓ (version done)' : ''}` : '';
+  lines.push(`**/status · ${data.version_id}** — ${satisfied}/${data.criteria.length} criteria satisfied${goalMeta}`);
+  lines.push('');
+  // Version → Goals → Criteria (ADR 0086 §2): a subheading per goal, its criteria
+  // beneath. Falls back to a single flat table if the payload carries no goals.
+  // Slug first, position second — the column a reader copies out of a card is
+  // the one that still means the same thing next week.
+  const critRow = (c) => `| ${c.satisfied ? '✓' : ''} | ${c.criterion_id} | C${c.cnum} | ${bar(c.counts.shipped, c.counts.total)} ${c.counts.shipped}/${c.counts.total} | ${c.remaining.length ? remainingSummary(c.remaining) : '—'} |`;
+  const tableHeader = () => { lines.push('| | Criterion | Pos | Shipped | Remaining |'); lines.push('|---|---|---|---|---|'); };
+  if (goals) {
+    for (const g of goals) {
+      lines.push(`**🎯 ${g.title}** — ${areaTag(g) ? areaTag(g) + ' · ' : ''}${g.status === 'achieved' ? 'achieved ✓' : g.status}${g.criteria.length ? '' : ' · no criteria yet'}`);
+      if (g.criteria.length) { tableHeader(); for (const c of g.criteria) lines.push(critRow(c)); }
+      lines.push('');
+    }
+  } else {
+    tableHeader();
+    for (const c of data.criteria) lines.push(critRow(c));
+  }
+  if (data.unattributed_tasks > 0) {
+    lines.push('');
+    lines.push(`_${data.unattributed_tasks} task(s) not linked to any criterion._`);
+  }
+  lines.push('');
+  // The hint quotes a REAL slug off this payload rather than a frozen `C8`,
+  // which is both an example of the stable form and immune to going stale.
+  const example = data.criteria.length ? data.criteria[0].criterion_id : 'wa6-kernel-and-packs';
+  lines.push(`→ Drill into one: \`/status ${example}\``);
+  return lines.join('\n');
+}
+
+// Best-effort widgets pref (task 1279). Status is public/pre-setup, so this is
+// non-fatal: apiCall adds auth only when a session exists and never exits, so an
+// unauthenticated /me just 401s → default ON (emit the widget).
+async function resolveWidgetsPref() {
+  try {
+    const api = await cliClient();
+    const me = await api.me.getMe();
+    if (me && me.ok && me.data && me.data.render) return me.data.render.widgets_enabled !== false;
+  } catch (_) { /* unauth / offline → default ON */ }
+  return true;
+}
+
+function printAll(data) {
+  const satisfied = data.criteria.filter((c) => c.satisfied).length;
+  const goals = (data.goals && data.goals.length) ? data.goals : null;
+  const goalMeta = goals ? `, ${data.goals_achieved}/${data.goals_total} goals achieved${data.version_done ? ' ✓' : ''}` : '';
+  console.log(`\n${data.version_id} — done-when progress  (${satisfied}/${data.criteria.length} criteria satisfied${goalMeta})\n`);
+  // Version → Goals → Criteria (ADR 0086 §2): a heading per goal, criteria beneath.
+  const printCrit = (c) => {
+    const flag = c.satisfied ? '✓' : ' ';
+    const line = `${flag} ${c.criterion_id.padEnd(34)} ${clabel(c)} ${bar(c.counts.shipped, c.counts.total)} `
+      + `${c.counts.shipped}/${c.counts.total} shipped`;
+    const rem = c.remaining.length ? `   remaining: ${remainingSummary(c.remaining)}` : '';
+    console.log(line + rem);
+  };
+  if (goals) {
+    for (const g of goals) {
+      console.log(`  🎯 ${g.title}  [${areaTag(g) ? areaTag(g) + ' · ' : ''}${g.status === 'achieved' ? 'achieved ✓' : g.status}]${g.criteria.length ? '' : '  (no criteria yet)'}`);
+      for (const c of g.criteria) printCrit(c);
+      if (g.criteria.length) console.log('');
+    }
+  } else {
+    for (const c of data.criteria) printCrit(c);
+  }
+  if (data.unattributed_tasks > 0) {
+    console.log(`\n${data.unattributed_tasks} task(s) in ${data.version_id} not linked to any criterion (run /status <criterion> to drill in).`);
+  }
+  console.log('');
+}
+
+function printOne(data, c) {
+  console.log(`\n${data.version_id} · ${c.criterion_id}  (C${c.cnum})   [${criterionStateText(c)}]`);
+  console.log(`"${c.criterion_md.replace(/\*\*/g, '').slice(0, 120)}"\n`);
+  if (c.tasks.length === 0) {
+    console.log('  (no tasks linked — this criterion has no structured gating tasks yet)\n');
+    return;
+  }
+  for (const t of c.tasks) {
+    const tag = rankTag(t.title);
+    const left = `${t.status}`.padEnd(10);
+    console.log(`  ${left} #${t.id}${tag ? ' ' + tag : ''}  ${shortTitle(t.title)}`);
+  }
+  console.log(`\n  ${c.counts.shipped}/${c.counts.total} shipped · remaining: ${remainingSummary(c.remaining)}\n`);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.error) {
+    console.error(`status: ${opts.error}`);
+    console.error('Usage: node scripts/bongos/status.js [--version ID] [<criterion-slug>|Cn] [--json]');
+    process.exit(2);
+  }
+  if (opts.help) {
+    console.log('Usage: node scripts/bongos/status.js [--version ID] [<criterion-slug>|Cn] [--json]');
+    process.exit(0);
+  }
+  // Fail closed if this repo's configured instance != the signed-in session's (task
+  // 2124 / demo-audit C2): fetchProgress uses a raw fetch(API_BASE/…) that bypasses the
+  // apiCall/cliClient guard, so without this `bongos status` would silently print another
+  // instance's progress. Skip only in --hook mode (the automated card path stays fail-open).
+  if (!opts.hook) await assertInstanceMatch();
+
+  // Resolve the version before anything fetches. --hook stays FAIL-OPEN like the
+  // instance check above: the automated card path must degrade, not throw, so a
+  // lookup that cannot answer emits an empty envelope rather than killing the hook.
+  //
+  // COST: one extra sequential GET /versions before the progress fetch, and it
+  // cannot be parallelised — the id IS the second call's path. It is paid only
+  // when no version was named: --version and STATUS_DEFAULT_VERSION both
+  // short-circuit it, so an instance that minds the round trip on the
+  // session-start card path sets the env var once and pays nothing. That is the
+  // deliberate trade against the alternative, which is the literal that spent
+  // months reporting a sealed version as current.
+  const picked = await resolveVersion(opts).catch(() => ({ version: null, defaulted: true, source: 'none' }));
+  if (!picked.version) {
+    if (opts.hook) {
+      process.stdout.write(JSON.stringify({
+        widgets_enabled: false, html: '', markdown: '',
+        warnings: ['status: no version is currently `building` — nothing to report.'],
+      }) + '\n');
+      return;
+    }
+    console.error('status: no version is currently `building` — cannot resolve a default.');
+    console.error('  Open one, or pass --version explicitly (e.g. --version BONGOS-V2).');
+    // cliExit, NOT process.exit: resolveVersion above just made a network round
+    // trip, and a hard exit while the request machinery is tearing down aborts
+    // natively on Windows + Node 24 (UV_HANDLE_CLOSING) — exit 127 AFTER the
+    // message prints, so a caller reads "tooling broken" instead of "no building
+    // version". The other exits in this file are pre-request or have substantial
+    // rendering between; this branch has neither. See scripts/bongos/CLAUDE.md.
+    return cliExit(3);
+  }
+  const data = await fetchProgress(picked.version);
+
+  // Resolve the requested criterion (if any) once — every output mode needs it.
+  // Slug, positional `Cn`, or numeric id, through the SAME vocabulary the write
+  // path uses. The rows come from ONE version's payload, which is what makes the
+  // version scoping structural rather than remembered: a bare `Cn` can only ever
+  // rank inside the version we just fetched, and the versions number
+  // independently (BONGOS-V1 C8 ≠ BONGOS-V2 C8).
+  let c = null;
+  let refKind = null;
+  if (opts.criterion) {
+    const hit = resolveCriterionIn(data.criteria, opts.criterion);
+    c = hit.criterion;
+    refKind = hit.kind;
+    if (!c) {
+      // Name the version, not just the criterion: on a DEFAULTED version this is
+      // the reader's only clue that C13 was looked up somewhere they didn't pick.
+      console.error(`status: ${picked.version} has no criterion "${opts.criterion}".`);
+      if (refKind === 'cnum') {
+        console.error(`  It has C1–C${data.criteria.length}. Positions shift when a criterion is added — prefer the slug.`);
+      } else {
+        // A miss on a slug is usually a typo or the wrong version, and the cure
+        // is the list of legal names, not a count.
+        const names = data.criteria.map((x) => x.criterion_id);
+        console.error(`  Known criteria: ${names.join(', ')}`);
+      }
+      if (picked.defaulted) console.error(`  ${defaultedVersionNote(picked)}`);
+      return cliExit(3);
+    }
+  }
+
+  // --hook (task 1288): the machine envelope the card-delivery hook consumes —
+  // both card forms from this single fetch. stdout carries the JSON only.
+  if (opts.hook) {
+    const widgets = await resolveWidgetsPref();
+    process.stdout.write(JSON.stringify({
+      widgets_enabled: widgets,
+      html: renderStatusWidget(data, c),
+      markdown: renderStatusMarkdown(data, c),
+      warnings: [],
+    }) + '\n');
+    return;
+  }
+  // --widget: pure HTML for a direct show_widget render (the skill's fallback).
+  if (opts.widget) { process.stdout.write(renderStatusWidget(data, c) + '\n'); return; }
+  // --json: unchanged machine interface (the criterion object when drilling in,
+  // else the whole version rollup).
+  if (opts.json) { console.log(JSON.stringify(c || data, null, 2)); return; }
+
+  // Default human output — the existing plain-text rollup, plus one line when
+  // the version was resolved rather than chosen (--json/--widget/--hook are
+  // machine interfaces and stay byte-identical).
+  if (c) printOne(data, c); else printAll(data);
+  const notes = [positionalRefNote(c, refKind), defaultedVersionNote(picked)].filter(Boolean);
+  for (const note of notes) console.log(`  ${note}`);
+  if (notes.length) console.log('');
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('status: unexpected error:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { parseArgs, resolveVersion, defaultedVersionNote, positionalRefNote, renderStatusWidget, renderStatusMarkdown, areaTag };