@bongos/core 1.23.22 → 1.24.1

package/scripts/bongos/run-unit-tests.js

@@ -25,7 +25,8 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
+const os = require('node:os');
+const { execFile, execFileSync } = require('node:child_process');
 const { isModuleEnabled } = require('../../src/modules');
 
 const TESTS_DIR = path.resolve(__dirname, '..', '..', 'tests');
@@ -79,10 +80,19 @@ const INTEGRATION = new Set([
   // keeps the week's baseline rule, the year counts from a row's first snapshot inside
   // it, the pin under a hide and two racing writers. The DB-free sibling is community_crowns.
   'community_crowns_db',
+  // task 1004992: the ways a person signs in against real SQL — the UNIQUE constraints,
+  // the minted-key sequence, the GitHub-born trigger, the backfill and a real sign-up
+  // race. The DB-free sibling is account_logins.
+  'account_logins_db',
   // task 1002983: the rising builder and the projects on the move against real SQL — the
   // year's baseline over 30 days, a quiet row's live total, hidden and private left out.
   // The DB-free sibling is community_movers.
   'community_movers_db',
+  // task 1004936: the Market Watch tables, hub seed and read queries against real SQL. The
+  // CHECKs, partial unique indexes and ON CONFLICT targets are what make the seed
+  // idempotent and a resumed run unable to record an item twice. DB-free sibling:
+  // market_watch_data.
+  'market_watch_data_db',
   // bfg, bfg_write, memory_isolation, memory_pull and setup_smoke LEFT this set under task
   // 1004865: none of them ever needed a database. Each failed on a stale test harness (a fake
   // server without res.fail, a stub on the wrong module, an old error shape, a renamed session
@@ -98,9 +108,16 @@ const INTEGRATION = new Set([
   // never was a dedicated consumer-layout-boot workflow, whatever older notes say.
   'consumer_layout_boot',
   'claim_gate_open_blocker', 'claim_gate_rebase',
+  // task 1004950: what a task needs — the real feed + all three claim surfaces, per capability.
+  'task_needs_db',
+  // task 1004947: an artist's page claim never hides or refuses engineering work (real feed + claim).
+  'page_tweak_no_block',
   // task 1004585: a hall-made goal's spec task gates its other work — the edge, the
   // claim gate's unsatisfiedDeps read, and the ship-time auto-promotion, on real Postgres.
   'goal_spec_task_db',
+  // task 1004984: unlinking an open task from a criterion, then the reconciler's
+  // close — the delivery guard and the sign-off recency clause are one SQL statement.
+  'task_criteria_unlink_db',
   // task 1003457: proves the blocker-resolve auto-promotion trigger (migration
   // 009, tightened by core_223) fires on the HALL'S OWN write path — the real
   // buildGdsRouter() HTTP routes, not a static SQL-text pin (blocker_resolve_guard.mjs,
@@ -231,6 +248,13 @@ const INTEGRATION = new Set([
   // task 1004750 (ADR 0382 D6): passkey tables from the real migration — single-use
   // challenges, TTL sweep, unique credential id, sign-count regression.
   'passkey_foundation_db',
+  // task 1004913 (ADR 0385 D4, ADR 0387 D2): the payout approval log from the real
+  // migration — the DATABASE refuses edits, deletes, truncation, a non-web or machine
+  // signature, a widening narrowing and anything after a revocation.
+  'payout_approvals_db',
+  // task 1004914 (ADR 0385 D8): the payout gate tables from the real migration —
+  // append-only, no silent hold, who may appeal, decide and co-sign, the gate end to end.
+  'payout_gates_db',
   // task 1004408: migration platform_identity_028 deletes the old hub invite's
   // pending rows before a cutoff it reads from the core_upgrades ledger. Only a real
   // engine runs the DO block, the numeric version compare and the one-shot guard.
@@ -383,6 +407,216 @@ function reportToWorkflow(failures) {
   fs.appendFileSync(process.env.GITHUB_OUTPUT, `failures=${describeFailures(failures)}\n`);
 }
 
+// ── Parallel lane + serial lane (task 1004926) ─────────────────────────────────────────
+// The unit gate used to run every file one at a time (task 1001435 pinned that). Each test
+// already runs in its OWN node process, so nothing in-process can race; what CAN collide is
+// state OUTSIDE the processes. So the runner now runs several files at once, sized to the
+// machine, and keeps every file that touches shared outside state in a SERIAL lane that runs
+// alone, with nothing else running beside it.
+//
+// What sends a file to the serial lane: its name in SERIAL below, or one of SERIAL_MARKERS
+// in its source — a browser launch, a fixed listen port, a fixed temp path, a write inside
+// the repo tree. A NEW test that
+// grows one of those lands in the serial lane on its own; no list to remember.
+//
+// Forcing serial: UNIT_TESTS_SERIAL=1 runs everything one at a time, as before. UNIT_TEST_JOBS=N
+// sets the pool size. --integration and --integration-parked are always serial: their tests
+// share one database.
+//
+// Output does not change shape: each file's lines print in sorted file order (a result that
+// finishes early waits for the ones before it), and the roll-up — teardown aborts, skips,
+// failures, the workflow report, the exit code — is built in that same order.
+const UNIT_TESTS_SERIAL_ENV = 'UNIT_TESTS_SERIAL';
+const UNIT_TEST_JOBS_ENV = 'UNIT_TEST_JOBS';
+
+// Files that share state outside their own process in a way the source scan cannot see.
+// Each entry says what it shares. Keep it short: a test that can own its state (mkdtemp,
+// listen(0)) should be fixed to, not listed here.
+//
+// Found by running the pool and diffing against a serial run (task 1004926):
+const SERIAL = new Set([
+  // asserts a handler returns in under 50 ms of wall clock; a busy pool makes that a coin toss
+  'agents_event_router',
+]);
+
+// Writes INSIDE the repo: a write call whose path is built from the repo root (ROOT, REPO,
+// REPO_ROOT, repoRoot, REPO_DIR, or `new URL('../…', import.meta.url)`), inline or through a
+// variable assigned from one. Every other test reads that tree. Found by watching the
+// worktree during a pooled run (task 1004926): prelaunch_gate plants a line into
+// src/bongos/prelaunch-gate.js and platform_boot, booting the real server beside it, crashed;
+// file_map drops a probe module into modules/ and fitness_scope_roster saw it; figma_adapter
+// writes src/ui/ and config/design-sources.json and find_untested tripped on it; repo_map
+// dirties scripts/bongos/CLAUDE.md. A temp dir is not caught here, which is the point.
+const REPO_ROOT_IDS = '(?:ROOT|REPO|REPO_ROOT|repoRoot|REPO_DIR)';
+const REPO_PATH = `(?:(?:path\\.)?(?:join|resolve)\\(\\s*${REPO_ROOT_IDS}\\b|new URL\\(\\s*['"\`]\\.\\.\\/)`;
+const FS_WRITE = '(?:writeFileSync|appendFileSync|mkdirSync|rmSync|rmdirSync|unlinkSync|renameSync|mkdtempSync|symlinkSync|fsp\\.rm|fsp\\.writeFile|fs\\.promises\\.writeFile)';
+const WRITE_INLINE_RE = new RegExp(`${FS_WRITE}\\(\\s*${REPO_PATH}`);
+const REPO_PATH_VAR_RE = new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*${REPO_PATH}`, 'g');
+function writesInsideRepo(src) {
+  if (WRITE_INLINE_RE.test(src)) return true;
+  for (const m of src.matchAll(REPO_PATH_VAR_RE)) {
+    if (new RegExp(`${FS_WRITE}\\(\\s*${m[1]}\\b`).test(src)) return true;
+  }
+  return false;
+}
+
+// A fixed name under the shared temp dir: path.join(os.tmpdir(), 'name') NOT wrapped in
+// mkdtemp. Every process on the machine sees the same path. A mkdtemp prefix is unique per call.
+const TMP_JOIN_LITERAL = /\bjoin\(\s*os\.tmpdir\(\)\s*,\s*(['"])[^'"$]*\1\s*[,)]/g;
+function usesFixedTempPath(src) {
+  for (const m of src.matchAll(TMP_JOIN_LITERAL)) {
+    const before = src.slice(Math.max(0, m.index - 40), m.index);
+    if (!/mkdtemp(?:Sync)?\(\s*(?:path\.)?$/.test(before)) return true;
+  }
+  return false;
+}
+
+const SERIAL_MARKERS = [
+  // One Chrome per test is heavy, and the launch flake (exit 7 with only "TAP version 13")
+  // is a resource-starvation symptom; running them beside a full pool invites it.
+  { why: 'launches a browser', test: (src) => /\b(?:puppeteer|playwright|chromium)\b|headless/i.test(src) },
+  // A literal port is shared by every process on the machine. listen(0) is not.
+  { why: 'listens on a fixed port', test: (src) => /\.listen\(\s*[1-9]\d{1,4}\s*[,)]/.test(src) },
+  { why: 'uses a fixed temp path', test: usesFixedTempPath },
+  { why: 'writes inside the repo', test: writesInsideRepo },
+];
+
+function serialReason(name, src) {
+  if (SERIAL.has(name)) return 'listed in SERIAL';
+  for (const m of SERIAL_MARKERS) if (m.test(src)) return m.why;
+  return null;
+}
+
+function resolveJobs(env = process.env, cpus = defaultCpus()) {
+  if (/^(1|true|yes|on)$/i.test(String(env[UNIT_TESTS_SERIAL_ENV] || '').trim())) return 1;
+  const raw = String(env[UNIT_TEST_JOBS_ENV] || '').trim();
+  if (/^[1-9]\d*$/.test(raw)) return Number(raw);
+  return Math.max(1, cpus);
+}
+
+function defaultCpus() {
+  return typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
+}
+
+// Run one test file in its own process. Resolves (never rejects) with a normalised result,
+// so the verdict logic below reads the same shape whatever ended the child.
+function runFile(filePath, timeout) {
+  return new Promise((resolve) => {
+    const child = execFile(process.execPath, [filePath], {
+      maxBuffer: 16 * 1024 * 1024,
+      timeout,
+      env: { ...process.env, NODE_ENV: 'test' },
+      windowsHide: true,
+    }, (err, stdout, stderr) => {
+      resolve({
+        ok: !err,
+        status: err ? (typeof err.code === 'number' ? err.code : null) : 0,
+        signal: err ? err.signal || null : null,
+        killed: !!(err && (err.killed || err.code === 'ETIMEDOUT')),
+        stdout: String(stdout || ''),
+        stderr: String(stderr || ''),
+      });
+    });
+    // stdin was 'ignore' (EOF at once) under execFileSync; a pipe nobody closes would leave a
+    // suite that reads stdin waiting for the whole budget.
+    if (child.stdin) child.stdin.end();
+  });
+}
+
+// Run `items` through `worker` with at most `jobs` in flight. Plain index hand-out: each
+// slot takes the next index when its last one finishes.
+async function runPool(items, jobs, worker) {
+  let next = 0;
+  const slot = async () => {
+    while (next < items.length) {
+      const i = next++;
+      await worker(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, jobs), items.length) }, slot));
+}
+
+// One file's verdict as printable lines plus its outcome. Pure: the same result always renders
+// the same lines, whichever lane ran it.
+function renderResult(displayName, r, perTestTimeout) {
+  const lines = [];
+  if (r.ok) {
+    const n = countSkips(r.stdout);
+    lines.push(`  ok    ${displayName}${n ? ` (${n} SKIPPED — not run here)` : ''}`);
+    return { lines, outcome: 'ok', skips: n };
+  }
+  // `exit null` on its own is unreadable, and it is what a HANG looks like here: the
+  // signal that ended the process is the whole diagnosis, so say it (task 1004052 —
+  // a test that hung for the full budget reported `exit null` and nothing else).
+  const why = r.killed
+    ? `TIMEOUT after ${perTestTimeout / 1000}s${r.signal ? `, ${r.signal}` : ''}`
+    : `exit ${r.status}${r.signal ? ` (${r.signal})` : ''}`;
+  const stdoutText = r.stdout.trim();
+  if (!r.killed && isCleanTeardownAbort(stdoutText, r.stderr)) {
+    lines.push(`  ok    ${displayName} (clean verdict, then libuv teardown abort, ${why})`);
+    return { lines, outcome: 'teardown', skips: 0 };
+  }
+  lines.push(`  FAIL  ${displayName} (${why})`);
+  // task 1002644: stdout used to be IGNORED, so the failing assertion (test files print
+  // their FAIL lines to stdout) was discarded. The actual failures first: the file's own
+  // FAIL lines, then its stdout tail (the last failure's assertion detail + summary).
+  // EMPTY STDOUT IS ITSELF THE CLUE: node:test buffers a file's whole report until the file
+  // finishes, so a suite that hangs mid-run emits NOTHING.
+  if (!stdoutText) {
+    lines.push('        (no output at all — node:test buffers a file\'s report until it finishes,');
+    lines.push('         so this suite did not reach the end. To find which case: run it on the same');
+    lines.push('         platform with each case writing its name to STDERR before it runs; stderr is');
+    lines.push('         unbuffered, so the last name with no completion is the one that hung.)');
+  }
+  const failLines = stdoutText ? stdoutText.split('\n').filter((l) => /\bFAIL\b/.test(l)).slice(0, 5) : [];
+  for (const l of failLines) lines.push(`      ${l.trim()}`);
+  if (stdoutText) {
+    for (const l of stdoutText.split('\n').slice(-5)) lines.push(`      ${l}`);
+  }
+  const stderr = r.stderr.trim().split('\n').slice(-3).join('\n      ');
+  if (stderr) lines.push(`      stderr: ${stderr}`);
+  return { lines, outcome: 'fail', skips: 0 };
+}
+
+// Run every entry — the serial lane first, alone, one at a time; then the rest `jobs` at a
+// time — print each entry's lines in entry order, and return the results in entry order.
+async function runEntries(entries, { jobs, perTestTimeout, run = runFile, print = (l) => console.log(l) }) {
+  const results = new Array(entries.length);
+  let printed = 0;
+  const flush = () => {
+    while (printed < entries.length && results[printed]) {
+      for (const l of results[printed].lines) print(l);
+      printed++;
+    }
+  };
+  // A TIMEOUT inside the pool can be the pool's fault: a heavy suite that spawns its own
+  // children can starve beside `jobs - 1` others. So a pooled file that times out is not
+  // judged there — it is re-run ALONE at the end, with the same budget, and that run is its
+  // verdict. A file that hangs alone still fails exactly as before. Only a timeout earns the
+  // re-run: an assertion failure in the pool is a failure.
+  const rerunAlone = [];
+  const reran = new Set();
+  const work = async (idx, { pooled }) => {
+    const e = entries[idx];
+    const r = await run(e.file, perTestTimeout);
+    if (pooled && r.killed) { rerunAlone.push(idx); return; }
+    const out = renderResult(e.displayName, r, perTestTimeout);
+    if (!pooled && reran.has(idx)) out.lines.splice(1, 0, `        (timed out beside ${jobs - 1} other file(s) in the pool; this verdict is from a re-run alone)`);
+    results[idx] = out;
+    flush();
+  };
+  const all = entries.map((_, i) => i);
+  const serialIdx = jobs > 1 ? all.filter((i) => entries[i].serial) : all;
+  const poolIdx = jobs > 1 ? all.filter((i) => !entries[i].serial) : [];
+  await runPool(serialIdx, 1, (idx) => work(idx, { pooled: false }));
+  await runPool(poolIdx, jobs, (idx) => work(idx, { pooled: true }));
+  rerunAlone.sort((a, b) => a - b);
+  for (const idx of rerunAlone) reran.add(idx);
+  await runPool(rerunAlone, 1, (idx) => work(idx, { pooled: false }));
+  flush();
+  return results;
+}
+
 // Discover modules/<key>/tests/*.mjs. Pure-ish (reads disk; `isEnabled` is
 // injected so this is unit-testable with zero real modules/ or DB config —
 // mirrors the injected-dependency pattern the module loader itself uses).
@@ -495,7 +729,7 @@ function discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEna
 const INTEGRATION_PARKED = new Set([
 ]);
 
-function main() {
+async function main() {
   // Two gates from one runner (task 1002221 / audit H1):
   //   default        — the DB-free UNIT gate: every test file MINUS the integration set (+ known-
   //                     failing / support / disabled-module). Fast, runs in a clean checkout / per PR.
@@ -571,88 +805,35 @@ function main() {
   }
   const total = files.length + moduleTests.length;
 
-  const failures = [];
-  const teardownAborts = [];
   // A GREEN suite that skipped cases is the shape this roll-up used to hide: the suite said so
   // on its own stdout, which was discarded on success, so the only visible line was `ok` and a
   // session reading the roll-up could not tell exercised coverage from absent coverage.
-  const skipped = [];
-  const runOne = (displayName, filePath) => {
-    try {
-      const out = execFileSync(process.execPath, [filePath], {
-        // task 1002644: stdout used to be IGNORED, so the failing assertion (test
-        // files print their FAIL lines to stdout) was discarded and the only
-        // context shown was the last 3 STDERR lines — often stale diagnostic
-        // noise from an EARLIER, PASSING test. The live example: gate_approvals'
-        // route-catch console.error dump made every failure in that file read as
-        // a GraphQL/network outage, and the real flaky assertion was invisible.
-        stdio: ['ignore', 'pipe', 'pipe'],
-        maxBuffer: 16 * 1024 * 1024,
-        timeout: perTestTimeout,
-        env: { ...process.env, NODE_ENV: 'test' },
-      });
-      const n = countSkips(out ? out.toString() : '');
-      if (n) skipped.push({ name: displayName, n });
-      console.log(`  ok    ${displayName}${n ? ` (${n} SKIPPED — not run here)` : ''}`);
-    } catch (err) {
-      // `exit null` on its own is unreadable, and it is what a HANG looks like here: the
-      // signal that ended the process is the whole diagnosis, so say it (task 1004052 —
-      // a test that hung for the full budget reported `exit null` and nothing else).
-      const why = err.killed
-        ? `TIMEOUT after ${perTestTimeout / 1000}s${err.signal ? `, ${err.signal}` : ''}`
-        : `exit ${err.status}${err.signal ? ` (${err.signal})` : ''}`;
-      const stdoutText = (err.stdout ? err.stdout.toString() : '').trim();
-      if (!err.killed && isCleanTeardownAbort(stdoutText, err.stderr ? err.stderr.toString() : '')) {
-        console.log(`  ok    ${displayName} (clean verdict, then libuv teardown abort, ${why})`);
-        teardownAborts.push(displayName);
-        return;
-      }
-      console.log(`  FAIL  ${displayName} (${why})`);
-      // The actual failures first: the file's own FAIL lines, then its stdout
-      // tail (the last failure's assertion detail + summary), both bounded.
-      // EMPTY STDOUT IS ITSELF THE CLUE, and it used to print as a blank gap. node:test
-      // buffers a file's whole report until the file finishes, so a suite that hangs
-      // mid-run emits NOTHING — which reads as "no detail available" when it actually
-      // means "it never got to the end". Name that, and name how to find the case.
-      if (!stdoutText) {
-        console.log('        (no output at all — node:test buffers a file\'s report until it finishes,');
-        console.log('         so this suite did not reach the end. To find which case: run it on the same');
-        console.log('         platform with each case writing its name to STDERR before it runs; stderr is');
-        console.log('         unbuffered, so the last name with no completion is the one that hung.)');
-      }
-      const failLines = stdoutText ? stdoutText.split('\n').filter((l) => /\bFAIL\b/.test(l)).slice(0, 5) : [];
-      for (const l of failLines) console.log(`      ${l.trim()}`);
-      if (stdoutText) {
-        for (const l of stdoutText.split('\n').slice(-5)) console.log(`      ${l}`);
-      }
-      const stderr = (err.stderr ? err.stderr.toString() : '').trim().split('\n').slice(-3).join('\n      ');
-      if (stderr) console.log(`      stderr: ${stderr}`);
-      failures.push(displayName);
-    }
-  };
-
-  // EXECUTION IS SERIAL, ONE PROCESS PER TEST — and that is load-bearing, not
-  // incidental (task 1001435). runOne uses execFileSync, which blocks, and these
-  // are plain sequential loops: no Promise.all, no worker pool, no concurrency
-  // anywhere in this file. Pinned by tests/unit_runner_serial.mjs.
   //
-  // Why it is written down. A flaky-`unit` report (this task, from idea #353)
-  // diagnosed "parallel execution racing on shared global state" and asked whether
-  // the runner fans tests out concurrently in one process. It does not, and never
-  // has — so an in-process race is ruled out as a cause by construction, and any
-  // future flake investigation should start somewhere else. The three suites that
-  // report named were audited then:
-  //   - fitness.mjs      — writes only under mkdtempSync(os.tmpdir()); no repo
-  //                        writes, no env mutation. Clean.
-  //   - session_index.mjs — mutates no global state at all. Clean.
-  //   - secret_box.mjs   — DID have a real hole, but not this one: it redirected
-  //                        only HOME, which os.homedir() ignores on Windows, so
-  //                        its sandbox was a no-op there. Fixed under this task.
-  // Collisions between separate processes remain possible through state OUTSIDE
-  // them — the real home directory, generated files in the repo, a second run on
-  // the same machine — which is where to look next, not here.
-  for (const name of files) runOne(name, path.join(TESTS_DIR, `${name}.mjs`));
-  for (const { key, name, file } of moduleTests) runOne(`${key}/${name}`, file);
+  // Execution: see "Parallel lane + serial lane" above (task 1004926). Every file still runs in
+  // its own node process with the same budget and the same verdict rules; up to `jobs` of them
+  // run at once, and the files that share state outside their process run alone first. The
+  // integration gate is always serial — its tests share one database.
+  const entries = [
+    ...files.map((name) => ({ displayName: name, file: path.join(TESTS_DIR, `${name}.mjs`) })),
+    ...moduleTests.map(({ key, name, file }) => ({ displayName: `${key}/${name}`, file })),
+  ];
+  const jobs = integrationMode ? 1 : resolveJobs();
+  if (jobs > 1) {
+    for (const e of entries) e.serial = serialReason(path.basename(e.file, '.mjs'), fs.readFileSync(e.file, 'utf8'));
+    const serialCount = entries.filter((e) => e.serial).length;
+    console.log(`run-unit-tests: ${jobs} at a time; ${serialCount} file(s) in the serial lane run alone first (set ${UNIT_TESTS_SERIAL_ENV}=1 to run everything one at a time)`);
+  }
+  const results = await runEntries(entries, { jobs, perTestTimeout });
+
+  const failures = [];
+  const teardownAborts = [];
+  const skipped = [];
+  results.forEach((r, i) => {
+    const name = entries[i].displayName;
+    if (r.outcome === 'fail') failures.push(name);
+    else if (r.outcome === 'teardown') teardownAborts.push(name);
+    else if (r.skips) skipped.push({ name, n: r.skips });
+  });
 
   const label = integrationMode ? 'run-unit-tests --integration' : 'run-unit-tests';
   console.log('');
@@ -673,6 +854,11 @@ function main() {
   process.exit(1);
 }
 
-if (require.main === module) main();
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+  });
+}
 
-module.exports = { discoverModuleTests, isCleanTeardownAbort, countSkips, describeFailures, STATUS_DESCRIPTION_MAX, INTEGRATION, INTEGRATION_PARKED, KNOWN_FAILING };
+module.exports = { resolveJobs, serialReason, runFile, renderResult, runEntries, SERIAL, UNIT_TESTS_SERIAL_ENV, UNIT_TEST_JOBS_ENV, discoverModuleTests, isCleanTeardownAbort, countSkips, describeFailures, STATUS_DESCRIPTION_MAX, INTEGRATION, INTEGRATION_PARKED, KNOWN_FAILING };

package/scripts/bongos/seed-tasks.example.json

@@ -0,0 +1,56 @@
+{
+  "_comment": "Example spec for scripts/bongos/seed-tasks.js (task 1004979). Copy it, fill in your goal, and run with --dry-run first. criterion_ids are the goal's criterion SLUGS, never positional Cn refs (learning 1000188). A links[] body value {\"$task\": \"R03\"} becomes that task's id.",
+  "version_id": "EXAMPLE-V1",
+  "goal_id": 1000001,
+  "source": "planning-session",
+  "source_ref_prefix": "example-v1-onboarding",
+  "tasks": [
+    {
+      "ref": "R01",
+      "title": "Spike: where the welcome checklist is stored",
+      "description": "Output an ADR naming the table and who writes it.",
+      "kind": "spike",
+      "discipline": "engineer",
+      "priority": 4,
+      "est_minutes": 90,
+      "criterion_ids": ["newcomer-knows-what-to-do-next"]
+    },
+    {
+      "ref": "R02",
+      "title": "The welcome checklist API",
+      "description": "Build to R01's ADR. Done-when: a new builder's checklist is returned by one GET.",
+      "kind": "feature",
+      "discipline": "engineer",
+      "priority": 4,
+      "est_minutes": 180,
+      "criterion_ids": ["newcomer-knows-what-to-do-next"],
+      "deps": ["R01"]
+    },
+    {
+      "ref": "R03",
+      "title": "The welcome checklist on the home page",
+      "description": "Render the checklist from R02 on the newcomer's home page.",
+      "kind": "feature",
+      "discipline": "ui",
+      "priority": 3,
+      "est_minutes": 150,
+      "criterion_ids": ["newcomer-knows-what-to-do-next"],
+      "deps": ["R02"]
+    },
+    {
+      "ref": "R04",
+      "title": "Proof: a newcomer finds their next step without asking",
+      "description": "A brand-new builder signs in and finds what to do next unaided.",
+      "kind": "verify",
+      "discipline": "engineer",
+      "priority": 3,
+      "est_minutes": 60,
+      "criterion_ids": ["newcomer-knows-what-to-do-next"],
+      "deps": ["R03"]
+    }
+  ],
+  "promote": ["R01"],
+  "links": [
+    { "method": "PATCH", "path": "/inbox/1000002", "body": { "status": "promoted", "promoted_to_task_id": { "$task": "R03" } } }
+  ]
+}