@bongos/core 1.20.5 → 1.20.7

package/modules/specialities/specialities.js

@@ -204,7 +204,23 @@ function canAdopt(speciality, viewer) {
 // characters and a session cannot carry that; what the contract carries is the
 // speciality's terms plus an inventory of what it knows, so the agent knows to
 // GO AND SEARCH rather than believing the subject is undocumented.
-function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuthored = true, authorLabel = null } = {}) {
+// The one sentence naming the enabled skills, or null — SILENT when nothing is on
+// (the common state after part 2), never an empty list. Only a skill still both
+// OFFERED and (when `installed` is known) INSTALLED is named: the PUT checked
+// both, but an author can shrink the offer and a deploy can drop a skill later,
+// and advising a session to reach for a skill it cannot find is noise.
+function enabledSkillsLine(active, installed = null) {
+  const enabled = Array.isArray(active && active.enabled_skills) ? active.enabled_skills : [];
+  const offered = new Set(Array.isArray(active && active.skills) ? active.skills : []);
+  const names = [...new Set(enabled)].filter((n) => typeof n === 'string' && SKILL_NAME_RE.test(n)
+    && offered.has(n) && (!installed || installed.has(n)));
+  if (!names.length) return null;
+  return `In this speciality the builder chose to lean on these skills: ${names.map((n) => `/${n}`).join(', ')}. `
+    + 'Reach for them when the work calls for one. This is advice, not permission — '
+    + 'each still runs only if the builder\'s rank allows it.';
+}
+
+function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuthored = true, authorLabel = null, installed = null } = {}) {
   if (!active) return null;
   const parts = [];
   // Conditional, not unconditional: an unnamed speciality has nothing to announce,
@@ -243,6 +259,15 @@ function describeForApi(active, { documentCount = 0, learningCount = 0, selfAuth
     );
   }
 
+  // THE ENABLED SKILLS (task 1004074, ADR 0310 part 3). What THIS builder turned
+  // on in the walkthrough, so the speciality changes what the session reaches for.
+  // After the provenance fence on purpose: the list is the adopter's own choice,
+  // not the author's prose. Advice only — naming a skill grants nothing, and the
+  // line says so, because a session told "use X" by a builder who cannot run X
+  // should hit the rank gate, not believe the speciality opened it.
+  const skillsLine = enabledSkillsLine(active, installed);
+  if (skillsLine) parts.push(skillsLine);
+
   const contract = parts.filter(Boolean).join('\n');
   // inject:false for an empty contract, matching how the wandering knob stays
   // silent on its permissive levels rather than spending context saying nothing.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.5",
+  "version": "1.20.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.5",
+      "version": "1.20.7",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.5",
+  "version": "1.20.7",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8066,9 +8066,33 @@
     }
   ],
   "1.20.5": [
+    {
+      "id": "1002456",
+      "text": "The list of decision records now says plainly which 20 numbers are shared by two documents, and tells everyone to cite a record by its file name so nobody opens the wrong one."
+    },
+    {
+      "id": "1004394",
+      "text": "Code tidy-up in the tweak editor: an out-of-date comment fixed. Nothing changes for artists."
+    },
+    {
+      "id": "1004074",
+      "text": "The skills you switch on for a speciality now follow you into your work sessions. Your assistant is told which ones you chose to lean on, and only in sessions for that craft. Switch nothing on and nothing extra is said. It is"
+    },
     {
       "id": "1004391",
       "text": "Wrote down a rule: when several linked tasks are claimed together, whoever claims them must finish them in order. Nothing enforces it yet, by the owner's choice."
     }
+  ],
+  "1.20.6": [
+    {
+      "id": "1004392",
+      "text": "A goal's checklist item no longer ticks itself off just because some linked work shipped. Once the work is done it now shows \"Awaiting UAT\", and it closes only when someone who did not build it tries it on the live site and up"
+    }
+  ],
+  "1.20.7": [
+    {
+      "id": "1002458",
+      "text": "The starter task that asks a new builder to add a test now finds its own targets from the current code, so it no longer goes out of date every time someone completes it."
+    }
   ]
 }

package/scripts/gds/cli-lib.js

@@ -680,10 +680,13 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
   // account billing, so identity is not an auth boundary. anthropic_user_id is
   // still kept in the session as cosmetic attribution; it is simply not
   // transmitted as a header.
+  // opts.rawBody (a Buffer) + opts.contentType send bytes instead of JSON — a
+  // UAT recording upload (task 1004392), whose route reads a raw video body.
+  if (opts.rawBody) headers['Content-Type'] = opts.contentType || 'application/octet-stream';
   const res = await dispatchedFetch(`${base}${urlPath}`, {
     method,
     headers,
-    body: body ? JSON.stringify(body) : null,
+    body: opts.rawBody ? opts.rawBody : (body ? JSON.stringify(body) : null),
     dispatcher: noKeepAliveDispatcher(),
   });
   const text = await res.text();

package/scripts/gds/find-untested.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/find-untested.js — list source modules that no test names, for the
+// newcomer "add a unit test" chore (task 1002458, from idea 1000574).
+//
+// WHY. The evergreen newcomer task `unit-test-pass` (scripts/gds/newcomer-floor.templates.json)
+// used to carry a HARDCODED list of "untested" helpers. Every newcomer who completed it made
+// the list a little more wrong, and a blanket rename broke three of its five paths outright.
+// This script is the METHOD instead of the list: run it and it names candidates from the live
+// tree, so the task cannot decay.
+//
+// THE DEFINITION (decided at claim time; recorded on the task). A module is a candidate when
+// NO TEST FILE NAMES IT — no test requires/imports it, builds its path with path.join, or
+// spawns it. That is the "no dedicated test" definition. The stricter one, "unreachable from
+// any test at all", is reported alongside as the `reach` column rather than used as the
+// filter: measured in this repo it leaves only a handful of modules, most of them DB pollers,
+// so filtering on it would hand newcomers an empty list. `--unreachable` applies it anyway.
+//
+// THE TWO NAIVE SCANS THIS AVOIDS (both measured before building):
+//   - Matching on BASENAME ("does settings.js appear in any test?") falsely drops common-word
+//     modules — quality.js, settings.js, hierarchy.js match dozens of unrelated tests. So a
+//     reference only counts when it resolves to the module's full repo-relative path.
+//   - Scanning only literal `require('…')` misses the ~65 tests that reach their module
+//     through `require(path.join(ROOT, 'scripts', 'gds', 'x.js'))`, a `const GOV = path.join(…)`
+//     prefix, or a spawned `node scripts/gds/x.js`; that scan wrongly flagged the well-tested
+//     memory-map.js. So every path.join/resolve call is evaluated (through the file's own
+//     path constants) and every path-shaped string literal counts.
+//
+// PURITY IS A HEURISTIC, and the output says so. A module is marked impure when it, or a
+// module it statically requires, reaches Postgres (`pg` or a db*.js module), a subprocess or
+// the network — the propagation is what catches a helper that reaches the database through a
+// module doorway rather than a literal `pg` require. Filesystem use is shown but does not
+// exclude: a module may read files in its CLI half and still export pure helpers. A newcomer
+// still checks the helper they pick.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// Where candidate modules live, and the directories never scanned for them.
+const SOURCE_ROOTS = ['scripts', 'src', 'modules'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'migrations', 'fixtures', 'vendor', 'public']);
+const CODE_EXT = /\.(?:c|m)?js$/;
+
+// ---- pure helpers ----------------------------------------------------------
+
+/** Is this repo-relative path a test file? A file under any `tests/` directory, or a
+ *  `*.test.js` beside its module (scripts/gds/newcomer-floor.test.js is one). */
+function isTestPath(rel) {
+  const p = String(rel).split(path.sep).join('/');
+  return /(^|\/)tests\//.test(p) || /\.test\.(?:c|m)?js$/.test(p);
+}
+
+/** Normalize a path to repo-relative posix form, clamping any climb above the root to the
+ *  root itself. Returns '' for the root. */
+function normRel(p) {
+  const out = [];
+  for (const seg of String(p).split(/[\\/]+/)) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') out.pop();
+    else out.push(seg);
+  }
+  return out.join('/');
+}
+
+/** Directory of a repo-relative file path ('' at the root). */
+function dirOf(rel) {
+  const i = rel.lastIndexOf('/');
+  return i < 0 ? '' : rel.slice(0, i);
+}
+
+// A single argument of a path.join/resolve call, evaluated to a repo-relative string, or
+// null when it cannot be known. `first` lets an unknown leading identifier stand for the
+// repo root — a `ROOT`/`REPO` constant imported from a helper is the overwhelming case.
+function evalArg(arg, env, fileDir, first) {
+  const a = arg.trim();
+  const lit = /^(['"`])((?:\\.|(?!\1)[^\\])*)\1$/.exec(a);
+  if (lit) return lit[2].includes('${') ? null : lit[2];
+  if (a === '__dirname' || a === 'HERE' || a === '__here') return '/' + fileDir;
+  if (Object.prototype.hasOwnProperty.call(env, a)) return env[a] == null ? null : '/' + env[a];
+  if (first && /^[A-Za-z_$][\w$]*$/.test(a)) return '/';
+  return null;
+}
+
+// Evaluate the argument text of one path.join/resolve call to a repo-relative path.
+function evalJoin(argText, env, fileDir) {
+  const args = argText.split(',');
+  let acc = null;
+  for (let i = 0; i < args.length; i++) {
+    const v = evalArg(args[i], env, fileDir, i === 0);
+    if (v == null) return null;
+    if (v.startsWith('/')) acc = v.slice(1);
+    else acc = acc == null ? v : acc + '/' + v;
+  }
+  return acc == null ? null : normRel(acc);
+}
+
+const JOIN_RE = /path\.(?:join|resolve)\s*\(([^()]*)\)/g;
+const CONST_JOIN_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*path\.(?:join|resolve)\s*\(([^()]*)\)/g;
+const CONST_URL_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:path\.dirname\s*\(\s*)?fileURLToPath\s*\(\s*(?:new URL\s*\(\s*(['"])([^'"]*)\2\s*,\s*)?import\.meta\.url/g;
+const URL_RE = /new URL\s*\(\s*(['"])([^'"]+)\1\s*,\s*import\.meta\.url\s*\)/g;
+const STRING_RE = /(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+
+/** Every repo-relative path a source text names: evaluated path.join/resolve calls (through
+ *  the file's own path constants), `new URL(…, import.meta.url)`, and path-shaped string
+ *  literals (relative ones resolved from the file's directory). Pure — it reads no files.
+ *  This is deliberately BROAD: it is how a test's reach is measured, and a test reaches its
+ *  module through any of these shapes. */
+function extractPathRefs(src, fileRel) {
+  const text = String(src);
+  const fileDir = dirOf(normRel(fileRel));
+  const env = {};
+  const refs = new Set();
+  let m;
+  CONST_URL_RE.lastIndex = 0;
+  while ((m = CONST_URL_RE.exec(text))) {
+    // fileURLToPath(import.meta.url) is the file itself; with dirname or a relative URL it
+    // is a directory. Either way the directory is the useful prefix.
+    env[m[1]] = m[3] ? normRel(fileDir + '/' + m[3]) : fileDir;
+  }
+  CONST_JOIN_RE.lastIndex = 0;
+  while ((m = CONST_JOIN_RE.exec(text))) env[m[1]] = evalJoin(m[2], env, fileDir);
+  JOIN_RE.lastIndex = 0;
+  while ((m = JOIN_RE.exec(text))) {
+    const v = evalJoin(m[1], env, fileDir);
+    if (v) refs.add(v);
+  }
+  URL_RE.lastIndex = 0;
+  while ((m = URL_RE.exec(text))) refs.add(normRel(fileDir + '/' + m[2]));
+  STRING_RE.lastIndex = 0;
+  while ((m = STRING_RE.exec(text))) {
+    const s = m[2];
+    if (!s || s.includes('${') || !/\.(?:c|m)?js$|\//.test(s) || /\s/.test(s) || /^[a-z]+:/i.test(s)) continue;
+    refs.add(s.startsWith('.') ? normRel(fileDir + '/' + s) : normRel(s));
+  }
+  return refs;
+}
+
+const REQUIRE_RE = /(?:require|import)\s*\(\s*(['"])([^'"]+)\1\s*\)|\bfrom\s+(['"])([^'"]+)\3/g;
+const REQUIRE_JOIN_RE = /require\s*\(\s*path\.(?:join|resolve)\s*\(([^()]*)\)\s*\)/g;
+
+/** The module specifiers a SOURCE file statically loads: bare package names as-is, and
+ *  in-repo paths (relative, or built with path.join from __dirname) as repo-relative paths
+ *  WITHOUT extension resolution. Narrower than extractPathRefs on purpose — this is the
+ *  require graph, and a path merely mentioned in a comment is not an edge. */
+function extractRequires(src, fileRel) {
+  const text = String(src);
+  const fileDir = dirOf(normRel(fileRel));
+  const env = {};
+  const out = { local: new Set(), packages: new Set() };
+  let m;
+  CONST_JOIN_RE.lastIndex = 0;
+  while ((m = CONST_JOIN_RE.exec(text))) env[m[1]] = evalJoin(m[2], env, fileDir);
+  REQUIRE_RE.lastIndex = 0;
+  while ((m = REQUIRE_RE.exec(text))) {
+    const spec = m[2] || m[4];
+    if (spec.startsWith('.')) out.local.add(normRel(fileDir + '/' + spec));
+    else out.packages.add(spec.replace(/^node:/, '').split('/')[0]);
+  }
+  REQUIRE_JOIN_RE.lastIndex = 0;
+  while ((m = REQUIRE_JOIN_RE.exec(text))) {
+    const v = evalJoin(m[1], env, fileDir);
+    if (v) out.local.add(v);
+  }
+  return out;
+}
+
+/** Resolve a reference against the set of known module paths the way Node would for a
+ *  local specifier: exact, then with .js/.mjs/.cjs, then as a directory's index.js.
+ *  Returns the module path or null. Full-path matching is what keeps a common-word
+ *  basename like settings.js from matching an unrelated module. */
+function resolveRef(ref, modules) {
+  if (!ref) return null;
+  for (const c of [ref, ref + '.js', ref + '.mjs', ref + '.cjs', ref + '/index.js']) {
+    if (modules.has(c)) return c;
+  }
+  return null;
+}
+
+/** Does this source export anything a test could call? CommonJS or ESM. */
+function hasExports(src) {
+  return /\bmodule\.exports\b|\bexports\.[A-Za-z_$]|^\s*export\s/m.test(String(src));
+}
+
+/** Rough count of exported names — a size hint for picking a newcomer-sized module. */
+function countExports(src) {
+  const text = String(src);
+  const names = new Set();
+  let m;
+  const objRe = /module\.exports\s*=\s*\{([\s\S]*?)\};?/g;
+  while ((m = objRe.exec(text))) {
+    for (const part of m[1].split(',')) {
+      const k = /^\s*(?:\.\.\.)?([A-Za-z_$][\w$]*)/.exec(part.replace(/\/\/.*$/gm, ''));
+      if (k) names.add(k[1]);
+    }
+  }
+  const dotRe = /\b(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g;
+  while ((m = dotRe.exec(text))) names.add(m[1]);
+  const esmRe = /^\s*export\s+(?:async\s+)?(?:function\*?|const|let|class)\s+([A-Za-z_$][\w$]*)/gm;
+  while ((m = esmRe.exec(text))) names.add(m[1]);
+  return names.size;
+}
+
+const NETWORK_PKGS = new Set(['http', 'https', 'net', 'tls', 'undici', 'ws', 'dgram']);
+
+/** The impurity markers a single source shows on its own: 'postgres', 'subprocess',
+ *  'network' (hard — the module cannot be tested DB-free and offline) and 'filesystem'
+ *  (soft). `requires` is extractRequires' output for the same text. */
+function ownImpurity(src, requires) {
+  const text = String(src);
+  const hard = new Set();
+  const pk = requires.packages;
+  if (pk.has('pg')) hard.add('postgres');
+  if (pk.has('child_process')) hard.add('subprocess');
+  for (const p of pk) if (NETWORK_PKGS.has(p)) hard.add('network');
+  if (/(?:^|[^\w.])fetch\s*\(/.test(text)) hard.add('network');
+  for (const r of requires.local) if (/(?:^|\/|-)db(?:-[\w-]+)?(?:\.js)?$/.test(r)) hard.add('postgres');
+  return { hard, fs: pk.has('fs') || pk.has('fs/promises') };
+}
+
+/** Rank candidates for a newcomer: unreachable before indirectly-covered, pure before
+ *  filesystem-touching, then smallest first (a newcomer-sized module). */
+function rankCandidates(rows) {
+  return rows.slice().sort((a, b) =>
+    (a.reach === 'unreachable' ? 0 : 1) - (b.reach === 'unreachable' ? 0 : 1)
+    || (a.fs ? 1 : 0) - (b.fs ? 1 : 0)
+    || a.lines - b.lines
+    || a.path.localeCompare(b.path));
+}
+
+// ---- tree scan -------------------------------------------------------------
+
+function walk(relDir, out) {
+  let entries;
+  try { entries = fs.readdirSync(path.join(ROOT, relDir), { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const rel = relDir ? relDir + '/' + e.name : e.name;
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('public-') && !e.name.startsWith('.')) walk(rel, out);
+    } else if (CODE_EXT.test(e.name)) out.push(rel);
+  }
+}
+
+/** Scan the live tree and return every exported source module with its coverage, reach and
+ *  purity: [{ path, lines, exports, tested, reach, impure: [..], fs }]. `tested` is true
+ *  when some test file names the module directly; `reach` is 'direct' | 'indirect' |
+ *  'unreachable' (indirect = only loaded through another module a test names). */
+function scanTree() {
+  const files = [];
+  for (const r of SOURCE_ROOTS) walk(r, files);
+  walk('tests', files);
+  const tests = files.filter((f) => isTestPath(f) && !f.includes('/fixtures/'));
+  const sources = files.filter((f) => !isTestPath(f) && !f.includes('/fixtures/'));
+  const text = new Map();
+  for (const f of files) text.set(f, fs.readFileSync(path.join(ROOT, f), 'utf8'));
+  const modules = new Set(sources);
+
+  // The require graph and each module's own impurity.
+  const edges = new Map();
+  const own = new Map();
+  for (const f of sources) {
+    const req = extractRequires(text.get(f), f);
+    const local = new Set();
+    for (const r of req.local) { const t = resolveRef(r, modules); if (t) local.add(t); }
+    edges.set(f, local);
+    own.set(f, ownImpurity(text.get(f), req));
+  }
+
+  // Hard impurity propagates along the require graph (the "module doorway" case).
+  const impure = new Map();
+  function impurityOf(f, seen) {
+    if (impure.has(f)) return impure.get(f);
+    if (seen.has(f)) return own.get(f).hard;
+    seen.add(f);
+    const acc = new Set(own.get(f).hard);
+    for (const d of edges.get(f)) for (const x of impurityOf(d, seen)) acc.add(x);
+    seen.delete(f);
+    impure.set(f, acc);
+    return acc;
+  }
+
+  // Direct test references, then everything reachable from them.
+  const direct = new Set();
+  for (const t of tests) {
+    for (const r of extractPathRefs(text.get(t), t)) {
+      const hit = resolveRef(r, modules);
+      if (hit) direct.add(hit);
+    }
+    const req = extractRequires(text.get(t), t);
+    for (const r of req.local) { const hit = resolveRef(r, modules); if (hit) direct.add(hit); }
+  }
+  const reached = new Set(direct);
+  const queue = [...direct];
+  while (queue.length) {
+    for (const d of edges.get(queue.pop()) || []) if (!reached.has(d)) { reached.add(d); queue.push(d); }
+  }
+
+  const rows = [];
+  for (const f of sources) {
+    const src = text.get(f);
+    if (!hasExports(src)) continue;
+    rows.push({
+      path: f,
+      lines: src.split('\n').length,
+      exports: countExports(src),
+      tested: direct.has(f),
+      reach: direct.has(f) ? 'direct' : reached.has(f) ? 'indirect' : 'unreachable',
+      impure: [...impurityOf(f, new Set())].sort(),
+      fs: own.get(f).fs,
+    });
+  }
+  return rows;
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+const USAGE = `usage: node scripts/gds/find-untested.js [--unreachable] [--all] [--limit N] [--json]
+
+Lists source modules (scripts/, src/, modules/) that NO test file names, for the newcomer
+"add a unit test" task. Candidates come first when no test reaches them at all, then when
+they look pure, then smallest first.
+
+  --unreachable  only modules no test reaches even indirectly (the strict definition)
+  --all          include modules that look impure (Postgres, subprocess, network)
+  --limit N      how many to print (default 25; 0 = all)
+  --json         machine-readable rows
+
+Purity is a heuristic: check the helper you pick really is DB-free before testing it.`;
+
+function main(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); return 0; }
+  const li = argv.indexOf('--limit');
+  const limit = li >= 0 ? parseInt(argv[li + 1], 10) : 25;
+  if (li >= 0 && !(limit >= 0)) { console.error('find-untested: --limit needs a number'); return 2; }
+  const all = scanTree();
+  let rows = all.filter((r) => !r.tested);
+  if (argv.includes('--unreachable')) rows = rows.filter((r) => r.reach === 'unreachable');
+  if (!argv.includes('--all')) rows = rows.filter((r) => r.impure.length === 0);
+  rows = rankCandidates(rows);
+  const shown = limit ? rows.slice(0, limit) : rows;
+  if (argv.includes('--json')) { console.log(JSON.stringify(shown, null, 2)); return 0; }
+  const untested = all.filter((r) => !r.tested).length;
+  console.log(`find-untested: ${all.length} exported modules scanned; ${untested} have no test naming them; `
+    + `${rows.length} match the filters.`);
+  if (!shown.length) { console.log('  (none — try --all, or strengthen a thin existing test instead)'); return 0; }
+  const w = Math.max(...shown.map((r) => r.path.length));
+  console.log(`  ${'module'.padEnd(w)}  lines  exports  reach        notes`);
+  for (const r of shown) {
+    const notes = [r.impure.length ? 'impure: ' + r.impure.join('+') : 'looks pure', r.fs ? 'uses fs' : ''].filter(Boolean).join(', ');
+    console.log(`  ${r.path.padEnd(w)}  ${String(r.lines).padStart(5)}  ${String(r.exports).padStart(7)}  ${r.reach.padEnd(11)}  ${notes}`);
+  }
+  if (rows.length > shown.length) console.log(`  … ${rows.length - shown.length} more (--limit 0 for all)`);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = {
+  isTestPath,
+  normRel,
+  extractPathRefs,
+  extractRequires,
+  resolveRef,
+  hasExports,
+  countExports,
+  ownImpurity,
+  rankCandidates,
+  scanTree,
+  main,
+};

package/scripts/gds/fitness-checks-write-validation.js

@@ -50,6 +50,10 @@ const WRITE_VALIDATION_EXEMPT = new Set([
   // the route's express.raw parser and read by module-artifact.verifyModuleArtifact, which
   // recomputes every hash and refuses anything that is not a well-formed module version.
   'POST /store/modules/:key/versions',
+  // Not a JSON body: the raw UAT recording (task 1004392, ADR 0351), capped by the
+  // route's express.raw parser and read by criterion-uat.screenRecording, which
+  // refuses anything that is not a bounded mp4/webm whose bytes match its type.
+  'POST /done-when/:criterionId/uat/recording',
 ]);
 
 // KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).

package/scripts/gds/newcomer-floor.templates.json

@@ -10,7 +10,7 @@
       "credits_reward": 15,
       "floor": 2,
       "title": "Add a unit test for an untested pure exported helper (assert its real behaviour)",
-      "description": "## What you're doing\n\nThe repo's safety net is its **unit suite** — every `tests/*.mjs` file, run by `scripts/gds/run-unit-tests.js` in CI on every PR. New pure tests are **auto-discovered** (there is no allowlist to edit), so the moment you add one it joins the gate. Your first ship as an engineer: pick ONE exported helper that has thin or no test coverage and add a focused, DB-free unit test for it.\n\nIt is identical for every newcomer and **always valuable** — coverage is never \"done\", the codebase has hundreds of small pure helpers, and a good test both guards behaviour and teaches you how a corner of the system works. It is also **safe to auto-ship**: you add ONE file under `tests/`, which is not a protected surface, so a clean test merges on green with no owner approval.\n\n## How to pick a target (a PURE helper)\n\nPick a **pure** function — deterministic, with no database, network, filesystem, or live-server dependency — so the test runs standalone. Good hunting grounds (look for an exported function with little or no matching `tests/` coverage):\n- `src/bongos/path-match.js` (`touchesOverlap`, `matchOne`), `src/bongos/llm-pricing.js` (`familyFor`, `canonicalizeModelId`), `modules/lifecycle/task-classifier.js`, `modules/builder-settings/render-prefs.js`, `modules/builder-settings/wandering-prefs.js`.\n- pure parsing/format helpers exported from `scripts/gds/*.js`.\n\nCheck `tests/` first: if a helper already has a thorough test file, add a missing case to a DIFFERENT helper, or pick another module — don't duplicate existing coverage.\n\n## How to write it (mirror an existing test — there is no framework)\n\nThese tests are plain Node scripts using `node:assert`; there is no test runner. Open a small existing one as your model — for example `tests/criterion_ref_parse.mjs` or `tests/task_classifier_vocab.mjs` — and copy the shape:\n1. `import` / `require` the helper from its module.\n2. Assert **several** cases, including at least one **edge / boundary** case (empty input, null, a tricky value).\n3. Print a one-line success message at the end (an assert that throws exits non-zero, which is how the gate sees a failure).\n\nName the file `tests/<helper-or-module>.mjs`.\n\n## Verify + ship\n\nRun BOTH and confirm both are green:\n- `node tests/<your-file>.mjs` — your test alone, exits 0.\n- `node scripts/gds/run-unit-tests.js` — the whole gate, with your test auto-included.\n\nThen `/builder-ship`. The ship notes must name the helper and file you tested.\n\n## Stay safe (off-limits)\n\nAdd exactly ONE new file under `tests/`. Do NOT edit `scripts/gds/run-unit-tests.js` (it auto-discovers your test, and it is a protected file you may not touch), and do NOT change the helper you are testing. Your test must be **DB-free**: anything needing Postgres, the network, or a live server belongs in the integration gate and will fail standalone here. Touch no permission, pipeline, migration, or infra file.",
+      "description": "## What you're doing\n\nThe repo's safety net is its **unit suite** — every `tests/*.mjs` file, run by `scripts/gds/run-unit-tests.js` in CI on every PR. New pure tests are **auto-discovered** (there is no allowlist to edit), so the moment you add one it joins the gate. Your first ship as an engineer: pick ONE exported helper that has thin or no test coverage and add a focused, DB-free unit test for it.\n\nIt is identical for every newcomer and **always valuable** — coverage is never \"done\", the codebase has hundreds of small pure helpers, and a good test both guards behaviour and teaches you how a corner of the system works. It is also **safe to auto-ship**: you add ONE file under `tests/`, which is not a protected surface, so a clean test merges on green with no owner approval.\n\n## How to pick a target (a PURE helper)\n\nPick a **pure** function — deterministic, with no database, network, filesystem, or live-server dependency — so the test runs standalone. Do not hunt by hand: run the finder, which reads the live tree every time (so this task never goes stale the way a written list does):\n\n```\nnode scripts/gds/find-untested.js\n```\n\nIt lists modules that **no test file names**, best candidates first — ones no test reaches at all, then ones that look pure, then the smallest. Its purity column is a heuristic: open the module and confirm the helper you pick really needs no database, network or files. If the list is empty, run it with `--all` and pick a module that still exports a helper you can test DB-free.\n\n## How to write it (mirror an existing test — there is no framework)\n\nThese tests are plain Node scripts using `node:assert`; there is no test runner. Open a small existing one as your model — for example `tests/criterion_ref_parse.mjs` or `tests/task_classifier_vocab.mjs` — and copy the shape:\n1. `import` / `require` the helper from its module.\n2. Assert **several** cases, including at least one **edge / boundary** case (empty input, null, a tricky value).\n3. Print a one-line success message at the end (an assert that throws exits non-zero, which is how the gate sees a failure).\n\nName the file `tests/<helper-or-module>.mjs`.\n\n## Verify + ship\n\nRun BOTH and confirm both are green:\n- `node tests/<your-file>.mjs` — your test alone, exits 0.\n- `node scripts/gds/run-unit-tests.js` — the whole gate, with your test auto-included.\n\nThen `/builder-ship`. The ship notes must name the helper and file you tested.\n\n## Stay safe (off-limits)\n\nAdd exactly ONE new file under `tests/`. Do NOT edit `scripts/gds/run-unit-tests.js` (it auto-discovers your test, and it is a protected file you may not touch), and do NOT change the helper you are testing. Your test must be **DB-free**: anything needing Postgres, the network, or a live server belongs in the integration gate and will fail standalone here. Touch no permission, pipeline, migration, or infra file.",
       "done_when": [
         "A NEW tests/<name>.mjs file was added (it did not exist before) that unit-tests a PURE exported helper — no Postgres, network, filesystem, or live server.",
         "`node tests/<name>.mjs` exits 0 and the test makes real assertions about the helper's behaviour — at least two cases including one edge/boundary case — not a trivial always-true assertion.",

package/scripts/gds/status.js

@@ -37,6 +37,17 @@
 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,
@@ -270,7 +281,7 @@ function renderStatusWidget(data, criterion) {
     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">satisfied</span>' : 'not satisfied'} · ${c.counts.shipped}/${c.counts.total} shipped</span></div>
+  <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>
@@ -314,7 +325,7 @@ function renderStatusMarkdown(data, criterion) {
   const lines = [];
   if (criterion) {
     const c = criterion;
-    lines.push(`**/status · ${data.version_id} · ${criterionLabel(c)}** — ${c.satisfied ? 'satisfied ✓' : 'not satisfied'}`);
+    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) {
@@ -405,7 +416,7 @@ function printAll(data) {
 }
 
 function printOne(data, c) {
-  console.log(`\n${data.version_id} · ${c.criterion_id}  (C${c.cnum})   [${c.satisfied ? 'satisfied ✓' : 'not satisfied'}]`);
+  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');