@bongos/core 1.20.6 → 1.20.7

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.6",
-  "core_contract": "1.20.6",
-  "source_commit": "7887b42a9147d4ca749389bca6fbff6120c41766",
+  "core_version": "1.20.7",
+  "core_contract": "1.20.7",
+  "source_commit": "9a8e336459336ffc6beebeac8b6496960dec3bdd",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T04:05:09.203Z",
+  "built_at": "2026-09-30T04:20:20.175Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 556,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2619,
+    "functional_verbatim": 2621,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3201,
-  "tree_sha256": "e7197c9a0497ef19bdfcd4085f7d6509536dbd1a85e1e52629d416a46530bce2",
+  "file_count": 3203,
+  "tree_sha256": "dcbd562f300693a4aac156ab9d3d09aa65f2ec33fe5f0b469846f0eaca1a6005",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "4604938cde7776d0076401f0a76aea306838b3498cd6c6834bf2ce34e68d84c9"
+      "sha256": "20bca63270af7e3ccc11037fc0faf76c5d7ed75d8bde9b115c96b1b6f4e985a2"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8852,12 +8852,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d445839a2e943ee2d1f3309b1366f72132d11925c29aa19a46891ce7925ad116"
+      "sha256": "1822db240575bf86013d014572456d1f007004bfdc29209929938288ba43e3b2"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d5d908e1d217603998e494d6c8343087d61dacc1b8fe894983a56cc4d809b819"
+      "sha256": "1b1b7816c342fed258f9eaa453ce64588f26fe28beb4ab3eb1dfc06ec8f4529e"
     },
     {
       "path": "public-docs/index.html",
@@ -8877,7 +8877,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "0836c84d2d1fbda2104f75831bcc05bd10fa3e05d29db763c250d8d4416769b3"
+      "sha256": "59dcfa061d238c013470c67e6a82249f559fdbc4509c0c1d4ba8c29c03cc68ab"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9394,6 +9394,11 @@
       "mode": "0000644",
       "sha256": "b8b1a7ed1d8dd217b24757a3ec9f4b3aa58b26a3e2a7b2cef9de217792e5ea43"
     },
+    {
+      "path": "scripts/gds/find-untested.js",
+      "mode": "0000644",
+      "sha256": "6788cb8ea36250fe84236f1a1f1a216f5627a1772d9dad5399b700cd3f984d74"
+    },
     {
       "path": "scripts/gds/fitness-checks-error-envelope.js",
       "mode": "0000644",
@@ -9727,7 +9732,7 @@
     {
       "path": "scripts/gds/newcomer-floor.templates.json",
       "mode": "0000644",
-      "sha256": "0b5cf03a0c3fd84da5f22064cbf6b6c8d73d30cbeb6a09803da6ef3e9f2809b6"
+      "sha256": "0623cc216ae3d20def01ac6d1aaedb4cf25d25fe9a94201cee86b8ff07673c0a"
     },
     {
       "path": "scripts/gds/newcomer-floor.test.js",
@@ -10982,7 +10987,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b76b3ccf9bc56f911703cf59e4e02652ab73076407ab164ef746f1177b7f72aa"
+      "sha256": "37545c18b037b0de0faaba69a716f67b779a48815d0f5e8937a7202ac7bb8f65"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12324,6 +12329,11 @@
       "mode": "0000644",
       "sha256": "815f2fa2ffd6e7a721507852d43b0490115a0b15393670f6035626bdf000e99c"
     },
+    {
+      "path": "tests/find_untested.mjs",
+      "mode": "0000644",
+      "sha256": "1a4b0eeee9212776a1a1f159053cd48d5af3041dc0a45c3b32cf0e7706600422"
+    },
     {
       "path": "tests/first_admin_bootstrap.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2669,5 +2669,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.4 with no explicit bump. run 36666171516. (task 1002620)
   1.20.6 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.5 with no explicit bump. run 36667238912. (task 1002620)
+  1.20.7 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.6 with no explicit bump. run 36668328505. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.6",
+  "version": "1.20.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.6",
+      "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.6",
+  "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

@@ -8088,5 +8088,11 @@
       "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/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/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/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.6'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.7'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/find_untested.mjs

@@ -0,0 +1,137 @@
+// tests/find_untested.mjs
+//
+// Unit test for scripts/gds/find-untested.js (task 1002458) — the finder the newcomer
+// "add a unit test" chore runs instead of a hardcoded target list. The cases pin the two
+// failures that made the naive scans unusable, measured before it was built:
+//   - BASENAME matching falsely marks a common-word module (settings.js) as tested because
+//     some unrelated test mentions a different settings.js;
+//   - LITERAL-require-only scanning misses tests that reach a module through
+//     path.join(ROOT, …), a `const GOV = path.join(…)` prefix, or a spawned script — which is
+//     how it once flagged the well-tested memory-map.js as untested.
+// Plus the purity heuristic, the ranking, and one pass over the live tree. Run:
+// node tests/find_untested.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const fu = require('../scripts/gds/find-untested.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); } catch (e) { failed++; console.log(`  FAIL ${name}\n       ${e.message}`); }
+}
+
+const MODS = new Set([
+  'modules/builder-settings/settings.js',
+  'modules/hall-ui/settings.js',
+  'modules/government/db.js',
+  'modules/government/board.js',
+  'scripts/gds/memory-map.js',
+  'scripts/gds/grade-smoke.js',
+  'modules/lifecycle/index.js',
+]);
+const hits = (src, file) => [...fu.extractPathRefs(src, file)].map((r) => fu.resolveRef(r, MODS)).filter(Boolean).sort();
+
+test('a basename alone never resolves to a module (the common-word false drop)', () => {
+  assert.deepEqual(hits("const s = require('./settings.js'); // settings.js", 'tests/x.mjs'), []);
+  assert.deepEqual(hits("import x from 'settings.js'", 'tests/x.mjs'), []);
+});
+
+test('a full or relative path resolves to exactly that module, not its namesake', () => {
+  assert.deepEqual(hits("require('../modules/hall-ui/settings.js')", 'tests/x.mjs'), ['modules/hall-ui/settings.js']);
+  assert.deepEqual(hits("require('modules/builder-settings/settings')", 'tests/x.mjs'), ['modules/builder-settings/settings.js']);
+});
+
+test('path.join(ROOT, …) segments, and a const prefix, are evaluated (the memory-map miss)', () => {
+  const src = [
+    "const ROOT = path.resolve(__dirname, '..');",
+    "const GOV = path.join(ROOT, 'modules', 'government');",
+    "const db = require(path.join(GOV, 'db.js'));",
+    "const mm = require(path.join(ROOT, 'scripts', 'gds', 'memory-map.js'));",
+  ].join('\n');
+  assert.deepEqual(hits(src, 'tests/x.mjs'), ['modules/government/db.js', 'scripts/gds/memory-map.js']);
+});
+
+test('an unknown leading identifier stands for the repo root; one in the middle does not', () => {
+  assert.deepEqual(hits("path.join(REPO, 'modules/government/board.js')", 'tests/x.mjs'), ['modules/government/board.js']);
+  assert.deepEqual(hits("path.join('modules', someVar, 'board.js')", 'tests/x.mjs'), []);
+});
+
+test('a spawned script, new URL(…, import.meta.url) and a directory index all count', () => {
+  assert.deepEqual(hits("spawnSync(process.execPath, ['scripts/gds/grade-smoke.js', '--dry'])", 'tests/x.mjs'), ['scripts/gds/grade-smoke.js']);
+  assert.deepEqual(hits("await import(new URL('../scripts/gds/memory-map.js', import.meta.url))", 'tests/x.mjs'), ['scripts/gds/memory-map.js']);
+  assert.deepEqual(hits("require('../modules/lifecycle')", 'tests/x.mjs'), ['modules/lifecycle/index.js']);
+});
+
+test('template literals with interpolation and URLs are ignored, not mis-resolved', () => {
+  assert.deepEqual(hits('require(`../modules/${k}/settings.js`)', 'tests/x.mjs'), []);
+  assert.deepEqual(hits("fetch('https://example.com/scripts/gds/memory-map.js')", 'tests/x.mjs'), []);
+});
+
+test('extractRequires separates packages from local edges and ignores comment mentions', () => {
+  const r = fu.extractRequires("const pg = require('pg');\nconst fs = require('node:fs');\nconst b = require('./board');\n// see ./db.js", 'modules/government/x.js');
+  assert.deepEqual([...r.packages].sort(), ['fs', 'pg']);
+  assert.deepEqual([...r.local], ['modules/government/board']);
+});
+
+test('ownImpurity: pg, a db module, child_process and fetch are hard; fs is soft', () => {
+  const imp = (src, file = 'modules/a/x.js') => fu.ownImpurity(src, fu.extractRequires(src, file));
+  assert.deepEqual([...imp("require('pg')").hard], ['postgres']);
+  assert.deepEqual([...imp("require('./db-claims.js')").hard], ['postgres']);
+  assert.deepEqual([...imp("require('node:child_process')").hard], ['subprocess']);
+  assert.deepEqual([...imp('const r = await fetch(url)').hard], ['network']);
+  const f = imp("require('fs')");
+  assert.equal(f.hard.size, 0);
+  assert.equal(f.fs, true);
+  // A name that merely contains "db" is not a database module.
+  assert.equal(imp("require('./feedback.js')").hard.size, 0);
+});
+
+test('isTestPath covers every test root and *.test.js siblings, and nothing else', () => {
+  assert.equal(fu.isTestPath('tests/a.mjs'), true);
+  assert.equal(fu.isTestPath('modules/lifecycle/tests/a.mjs'), true);
+  assert.equal(fu.isTestPath('scripts/gds/newcomer-floor.test.js'), true);
+  assert.equal(fu.isTestPath('scripts/gds/latest.js'), false);
+});
+
+test('hasExports / countExports read CommonJS and ESM', () => {
+  assert.equal(fu.hasExports('function a(){}'), false);
+  assert.equal(fu.countExports('module.exports = {\n  a,\n  b, // note\n  c: 1,\n};'), 3);
+  assert.equal(fu.countExports('exports.x = 1; module.exports.y = 2;'), 2);
+  assert.equal(fu.countExports('export function f(){}\nexport const g = 1;'), 2);
+});
+
+test('normRel clamps a climb above the root instead of escaping it', () => {
+  assert.equal(fu.normRel('tests/../../../scripts/gds/x.js'), 'scripts/gds/x.js');
+  assert.equal(fu.normRel('./a//b/./c'), 'a/b/c');
+  assert.equal(fu.normRel('..'), '');
+});
+
+test('rankCandidates: unreachable first, then no-fs, then smallest', () => {
+  const rows = [
+    { path: 'c', reach: 'indirect', fs: false, lines: 10 },
+    { path: 'b', reach: 'unreachable', fs: true, lines: 500 },
+    { path: 'a', reach: 'indirect', fs: true, lines: 5 },
+    { path: 'd', reach: 'indirect', fs: false, lines: 90 },
+  ];
+  assert.deepEqual(fu.rankCandidates(rows).map((r) => r.path), ['b', 'c', 'd', 'a']);
+});
+
+test('the live tree: tested modules the naive scans got wrong are NOT candidates', () => {
+  const rows = fu.scanTree();
+  const by = new Map(rows.map((r) => [r.path, r]));
+  // A scan that finds nothing looks exactly like a clean tree, so assert it found a lot.
+  assert.ok(rows.length > 300, `expected hundreds of exported modules, scanned ${rows.length}`);
+  for (const p of ['scripts/gds/memory-map.js', 'modules/grading/grader-workers/worker-verdict.js', 'scripts/gds/find-untested.js']) {
+    assert.ok(by.has(p), `${p} should be scanned`);
+    assert.equal(by.get(p).tested, true, `${p} has a test naming it`);
+  }
+  const untested = rows.filter((r) => !r.tested);
+  assert.ok(untested.length > 0 && untested.length < rows.length / 2,
+    `untested should be a minority, got ${untested.length} of ${rows.length}`);
+});
+
+console.log(`\nfind-untested (task 1002458) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);