@bongos/core 1.20.6 → 1.20.8

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/scripts/gds/role-pack-guard.js

@@ -72,8 +72,8 @@ function checkRolePacks(fsImpl = fs) {
       violations.push(`role registry entry '${discipline}' is not an object — every entry must carry a directive plus a pack or a skill.`);
       continue;
     }
-    // An entry with neither pointer routes a claim nowhere: claim.js prints the
-    // label and the session is left to guess its own playbook.
+    // An entry with neither pointer routes a claim nowhere: the session is told the
+    // label only and is left to guess its own playbook.
     if (!mode.pack && !mode.skill) {
       violations.push(`role registry entry '${discipline}' names neither a 'pack' (docs/packs/<craft>.md) nor a 'skill' — a claim of this discipline would be routed to no playbook at all.`);
     }

package/src/bongos/craft-mode.js

@@ -0,0 +1,87 @@
+// src/bongos/craft-mode.js — a claimed task's craft, as the pointer a session
+// follows to its playbook (task 1002992).
+//
+// WHY. The role registry (scripts/gds/discipline-modes.json) says which role
+// pack or skill each craft works from. claim.js used to PRINT that as a directive
+// block, which reaches the session only if someone reads the claim scroll by —
+// and a role pack skipped that way is invisible. This turns an entry into the same
+// { inject, contract } shape the interaction profile and the speciality contract
+// use, so GET /me can carry it on each active claim and the Conductor can relay it
+// on the next prompt, exactly as it relays those.
+//
+// ONE REGISTRY. This reads the file claim.js and fitness.js (role-pack-guard.js)
+// read — never a server-side copy of the map — so CI's hard-fail on a pack that is
+// not in the tree covers what the session is told, too.
+//
+// Fail-open throughout: an unreadable or invalid registry, or a craft with no
+// entry, yields nothing, never an error, so /me and a claim behave as before.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveCoreRoot } = require('../instance-config');
+
+function registryPath() {
+  return path.join(resolveCoreRoot(), 'scripts', 'gds', 'discipline-modes.json');
+}
+
+// The `modes` map, or {} for a missing / unparsable file.
+//
+// The DEFAULT registry is read once per process and memoised: GET /me calls this
+// on every request, and the file ships with the core, so it changes only on a
+// deploy, which restarts the process. A failed read is NOT memoised, so a
+// transient error does not pin {} for the life of the server. An explicit `file`
+// (claim.js, tests) is always read fresh.
+let memo = null;
+function readModes(file) {
+  if (file === undefined) {
+    if (!memo) {
+      const modes = readModesFile(registryPath());
+      if (Object.keys(modes).length) memo = modes;
+      return modes;
+    }
+    return memo;
+  }
+  return readModesFile(file);
+}
+
+function readModesFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const modes = parsed && parsed.modes;
+    return modes && typeof modes === 'object' ? modes : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+// The opener a session acts on. A pack is a file to READ (no slash command sits
+// behind it); a skill is one to INVOKE. The wrong verb sends a session hunting for
+// a command that does not exist, so the two shapes stay distinct.
+function opener(mode) {
+  if (!mode) return null;
+  if (mode.pack) return `read ${mode.pack}`;
+  if (mode.skill) return `/${mode.skill}`;
+  return null;
+}
+
+// The one-line role indicator claim.js prints, or null.
+function roleLine(mode) {
+  if (!mode) return null;
+  const o = opener(mode);
+  return `▶ ${mode.label || 'Working mode'}${o ? ` — ${o}` : ''}`;
+}
+
+// The injected fragment for one craft, or null when the registry has no entry
+// for it. Static registry text only — no task or builder text is interpolated —
+// so this adds no prompt-injection surface to the session.
+function describeCraftMode(discipline, modes) {
+  if (!discipline || !modes) return null;
+  const mode = modes[discipline];
+  if (!mode || typeof mode !== 'object' || !mode.directive) return null;
+  const parts = [`${roleLine(mode)} (the craft of the task claimed in this worktree).`, String(mode.directive).trim()];
+  if (mode.pack) parts.push(`Your pack: ${mode.pack} (the kernel is CLAUDE.md; this is the half that is only true for your craft).`);
+  return { discipline, inject: true, contract: parts.join('\n') };
+}
+
+module.exports = { readModes, roleLine, describeCraftMode };

package/src/bongos/routes/me.js

@@ -33,6 +33,7 @@ const db = require('../db');
 // provider is default-on (present in prod); resolveOptional degrades on a
 // prefs-module-less instance so the slices simply render their unset/default shape.
 const { validateOrRespond } = require('./_helpers');
+const { readModes: readCraftModes, describeCraftMode } = require('../craft-mode'); // task 1002992
 const { branding } = require('../../branding'); // task 2011: instance model-allocation default
 // The onboarding state machine carved into modules/onboarding/ (BV1.R81 / ADR
 // 0093 §1): the GET /me aggregator + PATCH /me/disciplines resolve the
@@ -333,10 +334,15 @@ module.exports = function buildMeRouter() {
     };
     // For each active claim, compute the streak preview (cheap; pool query).
     // Lets the CLI render "shipping this would extend streak to N days" hints.
+    // task 1002992: each claim also carries its craft's pack pointer
+    // (craft_mode: { discipline, inject, contract } or null), read from the one
+    // role registry, so the Conductor can tell the session which playbook to open
+    // for the claim in ITS worktree. Read once per request; fail-open to null.
+    const craftModes = readCraftModes();
     const activeClaimsWithPreview = await Promise.all(
       activeClaims.map(async (c) => {
         const preview = await reward.wouldExtendStreak(req.builder.id, c.task_id);
-        return { ...c, streak_preview: preview };
+        return { ...c, streak_preview: preview, craft_mode: describeCraftMode(c.discipline, craftModes) };
       })
     );
     const payload = {

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.8'; // 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/conductor_main_e2e.mjs

@@ -14,7 +14,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
-import { spawn } from 'node:child_process';
+import { spawn, execFileSync } from 'node:child_process';
 import http from 'node:http';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -47,7 +47,9 @@ function mePayload({ discipline = 'engineer' } = {}) {
 }
 
 // Run the hook once in a throwaway HOME whose session points at `base`.
-async function runHook(me) {
+// `worktree` names a git repo created under the fake home for the hook to stand
+// in — its basename is what binds a claim to "this" tree (task 1002992).
+async function runHook(me, { worktree = null } = {}) {
   const server = http.createServer((req, res) => {
     if (req.url.startsWith('/api/bongos/me')) { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(me)); return; }
     res.writeHead(404); res.end('{}');
@@ -62,12 +64,18 @@ async function runHook(me) {
   fs.writeFileSync(sessionPath, JSON.stringify({ token: 'test-token', api_base: base, builder: { id: 4242 } }));
   const env = { ...process.env, HOME: home, USERPROFILE: home };
   for (const k of Object.keys(env)) if (/_API_BASE$/.test(k) || k === 'OTB_CONDUCTOR_OFF' || k === 'OTB_SUBAGENT') delete env[k];
+  let cwd = home;
+  if (worktree) {
+    cwd = path.join(home, worktree);
+    fs.mkdirSync(cwd, { recursive: true });
+    execFileSync('git', ['init', '-q'], { cwd, stdio: 'ignore' });
+  }
   try {
-    const child = spawn(process.execPath, [HOOK], { env, cwd: home, stdio: ['pipe', 'pipe', 'pipe'] });
+    const child = spawn(process.execPath, [HOOK], { env, cwd, stdio: ['pipe', 'pipe', 'pipe'] });
     let out = ''; let err = '';
     child.stdout.on('data', (d) => { out += d; });
     child.stderr.on('data', (d) => { err += d; });
-    child.stdin.end(JSON.stringify({ session_id: 'e2e-' + Date.now(), prompt: 'hello', cwd: home }));
+    child.stdin.end(JSON.stringify({ session_id: 'e2e-' + Date.now(), prompt: 'hello', cwd }));
     const code = await new Promise((r) => child.on('close', r));
     return { out, err, code };
   } finally {
@@ -94,4 +102,30 @@ await test('with an artist claim, the artist contract is the one injected', asyn
   assert.ok(!r.out.includes(SPECIALITY));
 });
 
+// task 1002992: the craft's pack pointer, built by the SERVER's own helper from
+// the real registry (what GET /me puts on each claim), run through the real hook.
+const craftMode = require('../src/bongos/craft-mode.js');
+const MODES = craftMode.readModes();
+function twoTreePayload() {
+  const claim = (id, discipline) => ({ task_id: id, title: 't', touches: [], worktree_name: `task-${id}`, discipline, craft_mode: craftMode.describeCraftMode(discipline, MODES) });
+  return { ...mePayload(), specialities: [], active_claims: [claim(77, 'engineer'), claim(88, 'ideator')] };
+}
+
+await test('a session in a claimed worktree is told its craft\'s pack on the first prompt, and not the other tree\'s', async () => {
+  const r = await runHook(twoTreePayload(), { worktree: 'task-77' });
+  assert.equal(r.code, 0);
+  assert.ok(r.out.includes('docs/packs/engineer.md'), `the engineer pack pointer reaches the session; stdout was: ${JSON.stringify(r.out.slice(0, 400))}`);
+  assert.ok(!r.out.includes('docs/packs/ideator.md'), 'worktree task-88\'s ideator craft does not');
+  const other = await runHook(twoTreePayload(), { worktree: 'task-88' });
+  assert.ok(other.out.includes('docs/packs/ideator.md'));
+  assert.ok(!other.out.includes('docs/packs/engineer.md'));
+});
+
+await test('outside any claimed worktree no craft is guessed', async () => {
+  const r = await runHook(twoTreePayload());
+  assert.equal(r.code, 0);
+  assert.ok(!r.out.includes('docs/packs/'), 'no tree, no craft — silent rather than pooled');
+  assert.ok(r.out.includes(INTERACTION), 'and the rest of the hook still runs');
+});
+
 summary();