@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/turn-end-sound.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// scripts/bongos/turn-end-sound.js — the Stop hook that rings when a turn ends
+// (task 1003272).
+//
+// THE TRIGGER THAT NEVER EXISTED. scripts/bongos/fetch-sound-prefs.js has always
+// described "a LOCAL Stop hook + ship.js via .claude/sounds/play.js", and
+// sound-prefs.js has always labelled `chime` as "When Claude finishes a turn" —
+// but .claude/settings.json had no Stop hook at all. So the single most
+// noticeable sound in the system had nothing to fire it, on top of the player
+// being absent and four of the five WAVs never having been committed. Three
+// independent gaps, one symptom: "all sound seems bugged".
+//
+// WHY A SCRIPT RATHER THAN AN INLINE HOOK COMMAND. The variant resolution below
+// is the same logic ship-io.js's playShipBell() already uses (read the mirrored
+// prefs, take the event's chosen wav, fall back to a base sound). That is a
+// couple of lines too many for a JSON string, and a hook that cannot be read is
+// a hook nobody will fix.
+//
+// IT MUST ALWAYS EXIT 0 AND FAST. This runs at the end of every turn. It resolves
+// a name, hands it to a fire-and-forget player that spawns detached, and returns;
+// every failure path is a silent no-op. A Stop hook that threw, or that blocked
+// on audio, would make a cosmetic feature everyone's problem.
+
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// `user-input` is the event whose meaning matches a turn ending — Claude has
+// paused and it is the builder's move. Falls back to `chime`, which is the base
+// sound sound-prefs.js labels "When Claude finishes a turn".
+const EVENT_ID = 'user-input';
+const FALLBACK_WAV = 'chime';
+
+// Resolve the mirror the SAME way fetch-sound-prefs.js writes it
+// (instance-config.configPath — today ~/.config/cloudbongos/), with the
+// pre-rename ~/.config/otb/ as a fallback for an older box. Hardcoding the
+// legacy path is the bug this task found in two other readers; it is not going
+// to be re-introduced here.
+function prefsPath() {
+  try {
+    const p = require('../../src/instance-config').configPath('sound-prefs.json');
+    if (fs.existsSync(p)) return p;
+  } catch (_) { /* fall through */ }
+  return path.join(os.homedir(), '.config', 'otb', 'sound-prefs.json');
+}
+
+function resolveWav() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(prefsPath(), 'utf8'));
+    const chosen = parsed && parsed.event_sounds && parsed.event_sounds[EVENT_ID];
+    if (typeof chosen === 'string' && chosen) return chosen;
+  } catch (_) { /* no mirror yet — the fallback is the honest default */ }
+  return FALLBACK_WAV;
+}
+
+function main() {
+  try {
+    // Guarded exactly like ship-state.js's: on a checkout without the player
+    // (or mid-re-seed) this is a no-op, never a failed turn.
+    let playSound;
+    try {
+      ({ playSound } = require(path.resolve(__dirname, '..', '..', '.claude', 'sounds', 'play.js')));
+    } catch (_) { return; }
+    if (typeof playSound === 'function') playSound(resolveWav());
+  } catch (_) { /* cosmetic, always */ }
+}
+
+if (require.main === module) {
+  main();
+  process.exit(0); // never let a stray handle hold the turn open
+}
+module.exports = { resolveWav, prefsPath, EVENT_ID, FALLBACK_WAV };

package/scripts/bongos/tweak-halt.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// scripts/bongos/tweak-halt.js — an unattended /tweak stops, releases its round with a
+// plain note, and exits (task 1004678 / BV2.TW19b, ADR 0371 D8).
+//
+// WHY. `/tweak --page <id> --unattended` runs with nobody to ask. Every halt it can
+// meet must end the same way: the round goes back to the queue with a sentence an
+// artist can read, and the worker exits. Writing that once here means the skill,
+// copy-apply's --unattended path and the runner's lane (TW19c) cannot each word a
+// halt differently, or leave one claimed.
+//
+// Run:  node scripts/bongos/tweak-halt.js <task-id> --code <halt-code>
+//
+// The note is fixed vocabulary per code, never free text from the worker: the
+// worker is a model reading pages an artist wrote, so nothing it says rides out
+// onto the round.
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// The halts ADR 0371 D8 names, plus the copy-apply exits that mean "do not ship".
+const HALT_NOTES = Object.freeze({
+  claim_refused: 'The automatic apply could not take this round (the claim was refused). It waits for a person.',
+  nothing_applied: 'The automatic apply placed none of the lines, so there is nothing to show. Each refused line is recorded on the round.',
+  wrong_page: 'The automatic apply was pointed at a different page than this round. Nothing was changed.',
+  registry_mismatch: 'The automatic apply wrote the files but the copy registry did not read the new words back, so it stopped before shipping.',
+  reread_failed: 'The automatic apply could not re-read the page after applying it, so it stopped before shipping.',
+  ship_check_stale: 'The automatic apply stopped because the pre-ship checks named something stale it may not fix by itself.',
+  grader_unavailable: 'The quality review could not run, so the automatic apply stopped. The round waits for the next try or a person.',
+  grade_failed: 'The quality review did not pass the automatic apply. The round waits for a person.',
+  worker_stopped: 'The automatic apply stopped before it finished, without saying why. The round waits for the next try or a person.',
+  outside_page: 'The automatic apply would have changed a file outside this page, so it stopped.',
+});
+
+function haltNote(code) {
+  return HALT_NOTES[code] || null;
+}
+
+// copy-apply --batch's exit codes, as halts. 0 is not a halt. 2 is "nothing
+// applied" and also every refusal copy-apply names before writing (an unreadable
+// round): in both, nothing reached the page.
+function haltForCopyApplyExit(exit) {
+  if (exit === 0) return null;
+  return { 2: 'nothing_applied', 3: 'registry_mismatch', 4: 'reread_failed', 5: 'wrong_page' }[exit] || 'nothing_applied';
+}
+
+// Release the round with the note. `spawn` is the test seam. Returns the exit.
+function releaseWithNote(taskId, code, { spawn = spawnSync } = {}) {
+  const note = haltNote(code);
+  if (!note) throw new Error(`unknown halt code: ${code}`);
+  const r = spawn(process.execPath, [path.join(__dirname, 'release.js'), String(taskId), '--reason', `[tweak-unattended:${code}] ${note}`], { stdio: 'inherit' });
+  return r && typeof r.status === 'number' ? r.status : 1;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const taskId = argv[0];
+  const i = argv.indexOf('--code');
+  const code = i >= 0 ? argv[i + 1] : null;
+  if (!/^[1-9][0-9]*$/.test(String(taskId || '')) || !haltNote(code)) {
+    console.error(`usage: node scripts/bongos/tweak-halt.js <task-id> --code <${Object.keys(HALT_NOTES).join('|')}>`);
+    return 1;
+  }
+  console.log(`tweak-halt: task ${taskId} — ${haltNote(code)}`);
+  return releaseWithNote(taskId, code);
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { HALT_NOTES, haltNote, haltForCopyApplyExit, releaseWithNote };

package/scripts/bongos/tweak-renders.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/tweak-renders.js — the eight renders of a page tweak, shot and
+// attached (task 1004322 / BV2.TW11; ADR 0341 D7 and its builder pick 9).
+//
+// WHY. The artist approves the APPLIED PAGE, not a diff and not a page built from
+// the batch: the Approval queue (TW12) shows images of the applied branch, which
+// is what keeps ADR 0233's "nothing renders a task description as product copy"
+// true. So /tweak renders the page before it applies the batch and again after,
+// on a desktop (1440) and a phone (390), in light and in dark, and attaches the
+// eight pictures to the round's task under their slot names
+// (task-visuals.TWEAK_RENDER_SLOTS: before-desktop-light … after-phone-dark).
+//
+// HOW IT RENDERS. Exactly the way the page reader reads (scripts/bongos/page-reader.js):
+// the hall through the hall-preview harness with the pinned fixture account, the
+// landing and status surfaces through the ui-design kit's stub, one browser from
+// the kit's launchBrowser (system Edge or Chrome; nothing is downloaded), the
+// clock pinned, the page's first state from its .states.json. A page that pins
+// one colour mode is shot in that mode for both of its "light" and "dark" slots,
+// and the run says so, rather than inventing a mode the page does not have.
+// Full-page JPEG, so a long page still fits under the store's 4 MB cap.
+//
+// Run:  node scripts/bongos/tweak-renders.js shoot --page <id> --phase before|after --out <dir>
+//       node scripts/bongos/tweak-renders.js attach <task-id> --dir <dir>   (every slot file in <dir>)
+//       node scripts/bongos/tweak-renders.js plan --page <id>              (what would be shot; no browser)
+//
+// Exit: 0 done · 1 a render or an upload failed · 2 usage · 3 no browser.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+const { arg, cliClient, cliExit } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const EXT = 'jpg';
+const JPEG_QUALITY = 82;
+
+// ---- pure ------------------------------------------------------------------
+
+function slotName(phase, device, mode) {
+  return `${phase}-${device}-${mode}`;
+}
+
+// The shots for one phase of one page: one per device x mode, each carrying the
+// slot it fills and the mode the page will actually render in. `plan` is the
+// page's first render plan from page-reader.planRenders.
+function shotsFor(phase, plan) {
+  if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase)) throw new Error(`phase must be one of ${taskVisuals.TWEAK_RENDER_PHASES.join(', ')}`);
+  const pinned = plan && plan.pinnedMode ? plan.pinnedMode : null;
+  const out = [];
+  for (const [device, width] of Object.entries(taskVisuals.TWEAK_RENDER_DEVICES)) {
+    for (const mode of taskVisuals.TWEAK_RENDER_MODES) {
+      out.push({ slot: slotName(phase, device, mode), device, width, mode, renderMode: pinned || mode, file: `${slotName(phase, device, mode)}.${EXT}` });
+    }
+  }
+  return out;
+}
+
+// The page's first render plan, and whether its states file pins a mode. Reads
+// the inventory and the states file; no browser.
+function planForPage(pageId, { inventory, planRenders, root = REPO_ROOT }) {
+  const page = (inventory.pages || []).find((p) => p.id === pageId);
+  if (!page) return { ok: false, code: 'unknown_page', detail: { page: pageId } };
+  const plans = planRenders(page, { root });
+  const plan = plans[0];
+  let modes = null;
+  if (page.states_files && page.states_files.length) {
+    try { modes = JSON.parse(fs.readFileSync(path.join(root, page.states_files[0]), 'utf8')).modes || null; } catch { modes = null; }
+  }
+  const pinnedMode = Array.isArray(modes) && modes.length === 1 ? modes[0] : null;
+  return { ok: true, page, plan: { ...plan, pinnedMode } };
+}
+
+// Which slot files a directory holds, in slot order, and which are missing.
+function slotFilesIn(dir, { exists = (p) => fs.existsSync(p) } = {}) {
+  const found = [];
+  const missing = [];
+  for (const slot of taskVisuals.TWEAK_RENDER_SLOTS) {
+    const hit = ['jpg', 'png', 'webp'].map((e) => path.join(dir, `${slot}.${e}`)).find(exists);
+    if (hit) found.push({ slot, file: hit });
+    else missing.push(slot);
+  }
+  return { found, missing };
+}
+
+// ---- the browser half --------------------------------------------------------
+
+async function shoot({ pageId, phase, out }) {
+  const reader = require('./page-reader.js');
+  const kit = require('../../modules/ui-design/kit/lib');
+  const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+  const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+  if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+  const { page, plan } = planned;
+  const shots = shotsFor(phase, plan);
+  if (plan.pinnedMode) console.log(`tweak-renders: ${pageId} pins the ${plan.pinnedMode} mode, so both of its mode slots are shot in ${plan.pinnedMode}.`);
+  fs.mkdirSync(out, { recursive: true });
+
+  let browser;
+  try { browser = await kit.launchBrowser(); } catch (e) {
+    console.error(`tweak-renders: ${e.message}`);
+    return e instanceof kit.NoBrowserError ? 3 : 1;
+  }
+  const stoppers = [];
+  let failed = 0;
+  try {
+    let base;
+    if (page.surface === 'builders') {
+      const h = await reader.startHarness(kit);
+      stoppers.push(h.stop);
+      base = h.base;
+    } else {
+      const s = await kit.startStub({ surface: reader.SURFACE_MODULE[page.surface] || page.surface, auth: plan.auth, prefix: plan.stub.prefix, child: plan.stub.child, fixtures: plan.stub.fixtures });
+      stoppers.push(s.stop);
+      base = s.base;
+    }
+    for (const shot of shots) {
+      const [W, H] = kit.SIZES[shot.width];
+      const ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1, colorScheme: shot.renderMode });
+      try {
+        if (ctx.clock && typeof ctx.clock.setFixedTime === 'function') await ctx.clock.setFixedTime(new Date(reader.PINNED_CLOCK));
+        const p = await ctx.newPage();
+        p.setDefaultTimeout(6000);
+        p.on('dialog', (d) => { d.dismiss().catch(() => {}); });
+        await p.goto(base + kit.withMode(plan.url, shot.renderMode, plan.modeQuery), { waitUntil: 'load', timeout: 45000 });
+        await p.evaluate(() => document.fonts.ready).catch(() => {});
+        await p.waitForTimeout(kit.SETTLE_MS);
+        try { await kit.runActions(p, plan.actions); } catch (e) { console.log(`  ${shot.slot}: an action failed (${String(e.message).split('\n')[0].slice(0, 100)}); shot as it stood`); }
+        await p.screenshot({ path: path.join(out, shot.file), fullPage: true, type: 'jpeg', quality: JPEG_QUALITY });
+        const kb = Math.round(fs.statSync(path.join(out, shot.file)).size / 1024);
+        console.log(`  ${shot.slot}: ${W}px ${shot.renderMode} -> ${shot.file} (${kb} KB)`);
+      } catch (e) {
+        failed += 1;
+        console.error(`  ${shot.slot}: NOT rendered (${String(e.message).split('\n')[0].slice(0, 160)})`);
+      } finally {
+        await ctx.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    for (const stop of stoppers) stop();
+  }
+  console.log(`tweak-renders: ${shots.length - failed} of ${shots.length} ${phase} render(s) of ${pageId} in ${out}`);
+  return failed ? 1 : 0;
+}
+
+// ---- the upload half ---------------------------------------------------------
+
+async function attach({ taskId, dir }, deps = {}) {
+  const { found, missing } = slotFilesIn(dir, deps);
+  if (!found.length) { console.error(`tweak-renders: no slot files in ${dir} (expected ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.${EXT} and the rest).`); return 1; }
+  const client = deps.client || await cliClient();
+  let failed = 0;
+  for (const { slot, file } of found) {
+    const img = taskVisuals.readImageFile(file);
+    if (!img.ok) { failed += 1; console.error(`  ${slot}: ${img.message}`); continue; }
+    const r = await client.tasks.postTasksIdVisualsSlot({ id: taskId, slot, body: { image_b64: img.buf.toString('base64'), content_type: img.contentType, alt: `${slot.replace(/-/g, ' ')} render of the page` } });
+    if (r.ok) console.log(`  ${slot}: attached (${Math.round(img.buf.length / 1024)} KB)`);
+    else { failed += 1; console.error(`  ${slot}: upload failed (${r.status})`); }
+  }
+  if (missing.length) console.error(`tweak-renders: MISSING ${missing.length} slot(s): ${missing.join(', ')}. The Approval queue shows what is attached; shoot the missing phase and attach again.`);
+  console.log(`tweak-renders: ${found.length - failed} of ${taskVisuals.TWEAK_RENDER_SLOTS.length} render(s) attached to task ${taskId}.`);
+  return failed || missing.length ? 1 : 0;
+}
+
+async function main(args) {
+  const cmd = args[0];
+  if (cmd === 'shoot' || cmd === 'plan') {
+    const pageId = arg('--page', args);
+    if (!pageId) { console.error('usage: node scripts/bongos/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    if (cmd === 'plan') {
+      const reader = require('./page-reader.js');
+      const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+      const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+      if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+      for (const phase of taskVisuals.TWEAK_RENDER_PHASES) for (const s of shotsFor(phase, planned.plan)) console.log(`${s.slot}\t${s.width}px\t${s.renderMode}\t${planned.plan.url}`);
+      return 0;
+    }
+    const phase = arg('--phase', args);
+    const out = arg('--out', args);
+    if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase) || !out) { console.error('usage: node scripts/bongos/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    return shoot({ pageId, phase, out: path.resolve(out) });
+  }
+  if (cmd === 'attach') {
+    const taskId = Number(args[1]);
+    const dir = arg('--dir', args);
+    if (!Number.isInteger(taskId) || taskId <= 0 || !dir) { console.error('usage: node scripts/bongos/tweak-renders.js attach <task-id> --dir <dir>'); return 2; }
+    return attach({ taskId, dir: path.resolve(dir) });
+  }
+  console.error('usage: node scripts/bongos/tweak-renders.js shoot|attach|plan … (see the file header)');
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => cliExit(code), (e) => { console.error(`tweak-renders: ${e.stack || e.message}`); cliExit(1); });
+}
+
+module.exports = { shotsFor, planForPage, attach };

package/scripts/bongos/uat.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// scripts/bongos/uat.js — see, and sign off, a criterion's UAT from a session
+// (task 1004392, goal 1000089; ADR 0351). The CLI half of /goal-uat.
+//
+// WHY. A criterion no longer closes because its linked tasks shipped. It reads
+// "Awaiting UAT" until someone who did not ship the work performs it on the live
+// site and signs it off with a recording (or, for a criterion marked
+// backend-only, a recording-free sign-off). This is how a session does that
+// before the hall has buttons for it (task 1004402), and what /goal-uat drives.
+//
+// Usage:
+//   node scripts/bongos/uat.js --queue [--version V]            every criterion awaiting UAT
+//   node scripts/bongos/uat.js <criterion-id>                    its three checks + sign-offs
+//   node scripts/bongos/uat.js <criterion-id> --recording <file.mp4|.webm> [--live-attested] [--note "..."]
+//   node scripts/bongos/uat.js <criterion-id> --backend-signoff [--live-attested] [--note "..."]
+//   node scripts/bongos/uat.js <criterion-id> --backend-only on|off
+//
+// <criterion-id> is the criterion's numeric id (the `id` /status and the queue
+// print), not its slug. --live-attested is only needed where this site cannot
+// tell on its own whether the work is live; the server says so when it is.
+
+const { apiCall, arg, argText, hasFlag, cliExit } = require('./cli-lib');
+const uat = require('../../modules/lifecycle/criterion-uat');
+
+const API = '/api/bongos';
+
+function refusalText(data) {
+  const e = data && data.error;
+  if (!e) return 'the server refused it.';
+  const msg = typeof e === 'string' ? e : (e.message || e.code);
+  const extra = [];
+  const details = (typeof e === 'object' && e.details) || data;
+  if (details && Array.isArray(details.remaining) && details.remaining.length) {
+    extra.push(`still open: ${details.remaining.map((t) => `task ${t.id} (${t.status})`).join(', ')}`);
+  }
+  if (details && Array.isArray(details.not_live) && details.not_live.length) {
+    extra.push(`not live yet: ${details.not_live.map((t) => `task ${t.task_id}${t.stage ? ` (${t.stage})` : ''}`).join(', ')}`);
+  }
+  return [msg, ...extra].join('\n  ');
+}
+
+async function showQueue() {
+  const version = arg('--version');
+  const q = version ? `?version=${encodeURIComponent(version)}` : '';
+  const r = await apiCall('GET', `${API}/done-when/pending-review${q}`);
+  if (!r.ok) { console.error(`Could not read the queue: ${refusalText(r.data)}`); return 1; }
+  const rows = (r.data.criteria || []).filter((c) => c.awaiting_uat);
+  if (!rows.length) { console.log('Nothing is awaiting UAT.'); return 0; }
+  console.log(`${rows.length} criteri${rows.length === 1 ? 'on' : 'a'} awaiting UAT:\n`);
+  for (const c of rows) {
+    const tag = c.backend_only ? '  [backend-only]' : '';
+    console.log(`  criterion ${c.id}  ${c.criterion_id}${tag}`);
+    console.log(`    goal ${c.goal_id ?? '-'}${c.goal_title ? ` "${c.goal_title}"` : ''}${c.is_last_in_goal ? '  (last open criterion: signing it off can achieve the goal)' : ''}`);
+  }
+  return 0;
+}
+
+async function showOne(id) {
+  const r = await apiCall('GET', `${API}/done-when/${id}/uat`);
+  if (!r.ok) { console.error(`Could not read criterion ${id}: ${refusalText(r.data)}`); return 1; }
+  const v = r.data;
+  console.log(`criterion ${v.criterion.id}  ${v.criterion.criterion_id}  — ${v.uat_label}${v.backend_only ? '  [backend-only]' : ''}\n`);
+  console.log(String(v.criterion.criterion_md || '').trim());
+  console.log('');
+  console.log(`  Code  ${v.checks.code ? 'passed' : 'not yet'}  (${v.linked_tasks.length} linked: ${v.linked_tasks.map((t) => `${t.id} ${t.status}`).join(', ') || 'none'})`);
+  const live = v.checks.live;
+  console.log(`  Live  ${live == null ? '-' : !live.available ? 'this site cannot tell; the signer confirms it' : live.live ? 'running on the site' : `not yet: ${(live.not_live || []).map((t) => t.task_id).join(', ')}`}`);
+  const s = v.checks.uat;
+  console.log(`  UAT   ${s ? `${s.kind === 'uat' ? 'recorded' : 'backend sign-off'} by ${s.signed_off_by_login || s.signed_off_by} on ${String(s.created_at).slice(0, 10)}` : 'not yet'}`);
+  return 0;
+}
+
+async function signOff(id, kind) {
+  let recording = null;
+  if (kind === 'uat') {
+    const file = arg('--recording');
+    const read = uat.readRecordingFile(file);
+    if (!read.ok) { console.error(`Recording refused: ${read.message}`); return 1; }
+    const up = await apiCall('POST', `${API}/done-when/${id}/uat/recording`, null, { rawBody: read.buf, contentType: read.contentType });
+    if (!up.ok) { console.error(`Upload refused: ${refusalText(up.data)}`); return 1; }
+    recording = up.data.recording;
+    console.log(`Uploaded the recording (${Math.round(up.data.bytes / 1024 / 1024 * 10) / 10} MB).`);
+  }
+  const body = { kind };
+  if (recording) body.recording = recording;
+  if (hasFlag('--live-attested')) body.live_attested = true;
+  const note = argText('--note');
+  if (note) body.note = note;
+  const r = await apiCall('POST', `${API}/done-when/${id}/uat`, body);
+  if (!r.ok) { console.error(`Sign-off refused: ${refusalText(r.data)}`); return 1; }
+  console.log(r.data.criterion_closed ? `Signed off. Criterion ${id} is now closed.` : `Signed off, but criterion ${id} did not close yet.`);
+  for (const g of r.data.achieved_goals || []) console.log(`  That was the goal's last criterion: goal ${g} is achieved.`);
+  return 0;
+}
+
+async function setBackendOnly(id, value) {
+  if (value !== 'on' && value !== 'off') { console.error('--backend-only takes on or off.'); return 1; }
+  const r = await apiCall('PUT', `${API}/done-when/${id}/backend-only`, { backend_only: value === 'on' });
+  if (!r.ok) { console.error(`Refused: ${refusalText(r.data)}`); return 1; }
+  console.log(`Criterion ${id} is ${r.data.backend_only ? 'now marked backend-only' : 'no longer backend-only'}.`);
+  return 0;
+}
+
+async function main() {
+  if (hasFlag('--queue')) return showQueue();
+  const id = process.argv[2];
+  if (!id || !/^\d{1,12}$/.test(id)) {
+    console.error('usage: node scripts/bongos/uat.js <criterion-id> [--recording f | --backend-signoff | --backend-only on|off]  |  --queue');
+    return 2;
+  }
+  if (arg('--backend-only')) return setBackendOnly(id, arg('--backend-only'));
+  if (hasFlag('--backend-signoff')) return signOff(id, 'backend_signoff');
+  if (arg('--recording')) return signOff(id, 'uat');
+  return showOne(id);
+}
+
+main().then((code) => cliExit(code), (err) => {
+  console.error(`uat: ${err && err.message}`);
+  cliExit(1);
+});

package/scripts/bongos/ui-kit-transform.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// ui-kit-transform.js — the instance's serving transforms as a command (task
+// 1003320, ADR 0197). Reads one surface page and prints it transformed exactly as
+// serve-internal.js / platform-server.js serve it: the apex-only strip, the
+// brand-token stamp, the pack's theme injection — with the instance's own
+// branding pack.
+//
+// WHY a script: the ui-design kit's stub (modules/ui-design/kit/serve.js) must
+// serve a page through the REAL code path, and a module may not require core
+// (ADR 0083), while the doorway may not import the serving domain (fitness Check
+// 12, ADR 0091 §1). A command under scripts/bongos/ is outside both walls — the
+// memory / ideas / sessions precedent: a command travels with its domain but
+// stays under scripts/. The stub spawns this per page and memoises the answer.
+//
+//   node scripts/bongos/ui-kit-transform.js <page.html> [--child] [--json]
+//     --child   the child-instance shape (apex-only regions removed)
+//     --json    { html, brand, publicOrigin, hallOrigin } instead of the bare HTML
+//
+// Exit 2 on usage; the transformed page on stdout, nothing else.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+if (!file) { process.stderr.write('usage: node scripts/bongos/ui-kit-transform.js <page.html> [--child] [--json]\n'); process.exit(2); }
+const child = args.includes('--child');
+
+const { injectBrandingGlobal, applyBrandTokens } = require('../../src/bongos/serve-internal');
+const { stripApexOnly } = require('../../src/platform-server');
+const branding = require('../../src/branding');
+
+const brand = branding.clientBranding();
+let domains = {};
+try { domains = (typeof branding.branding === 'function' ? branding.branding() : {}).domains || {}; } catch { domains = {}; }
+const publicOrigin = domains.publicOrigin || '';
+const hallOrigin = child ? '' : (domains.buildersOrigin || '');
+
+const raw = fs.readFileSync(path.resolve(file), 'utf8');
+// platform-server's order for the landing: strip, then inject; the token stamp is
+// what the hall/status surfaces get on the way through serve-internal.
+const html = injectBrandingGlobal(applyBrandTokens(stripApexOnly(raw, !child), brand, publicOrigin, hallOrigin, '', ''), brand);
+process.stdout.write(args.includes('--json') ? JSON.stringify({ html, brand, publicOrigin, hallOrigin }) : html);