@bongos/core 1.19.616 → 1.19.618

package/scripts/gds/backlog-review.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// /backlog-review — walk the tasks sitting at status='backlog' and give each one
+// the nod, the axe, or a reset clock (task 1003746).
+//
+// WHY THIS EXISTS. `backlog` is the PRE-WORKABLE state: a task lands there when
+// the system will not put it in the claimable queue without a human saying go
+// (`modules/ideas/routing.js` — "'backlog' means a human still says go"), and
+// ADR 0234 §2 records why: a feature/cleanup/refactor filing "reshape[s] what
+// gets built and a filer should not be able to set the queue's agenda alone".
+// Every OTHER queue in the methodology has a walkable cadence — /idea-triage for
+// idea_inbox, /blocker-review for blockers, /bug-triage for kind=bug,
+// /goal-review for criteria. The backlog had none. Its only pull surfaces were
+// the nod queue (`GET /inbox/awaiting-nod`, scoped `WHERE origin='route'`, so it
+// sees only filings that came through the idea inbox) and the 30-day rot timer.
+// This is the missing walk.
+//
+// Usage:
+//   node scripts/gds/backlog-review.js [--limit N] [--goal ID] [--all]
+//
+// THE FOUR BUCKETS, AND WHY ONLY TWO GET WALKED. One read
+// (`GET /tasks?status=backlog&include=deps`) partitions into four populations,
+// and conflating them is the whole trap this script exists to avoid — a row
+// waiting on a TRIGGER is not a row waiting on a PERSON, and asking a human to
+// verdict the former wastes the cadence on rows it cannot move:
+//
+//   stranded   — dep-gated, but at least one dependency is ABANDONED. That edge
+//                can never satisfy, so the migration-163 auto-promote trigger
+//                will NEVER fire: the row is stuck, not waiting. WALKED FIRST,
+//                because it is the only bucket that gets worse by being left.
+//   nod        — no unsatisfied dependency: nothing is gating it but a human.
+//                THE REVIEW SUBJECT. This is what "review the backlog" means.
+//   dep-gated  — an unsatisfied dependency that is still alive. COUNTED, NEVER
+//                WALKED: shipping the dependency auto-promotes it (migration
+//                163), so a human verdict here is noise at best and, if it
+//                promotes, races the trigger.
+//   spikes     — kind='spike' rows live at backlog BY CONVENTION (migration 020:
+//                "Spikes stay in backlog by convention"), so they are not
+//                un-nodded work. COUNTED, NEVER WALKED.
+//
+// THE VERBS ARE STATUS-DERIVED, NOT A FIXED LIST. The rot card publishes four
+// task verbs (prioritise/prune/kill/water — `modules/lifecycle/rot.js`), but two
+// of them are status-conditional at the route: `POST /tasks/:id/promote` accepts
+// only backlog|blocked|abandoned, and `POST /tasks/:id/demote` accepts only
+// 'ready' (`modules/lifecycle/routes/tasks.js`). So on a BACKLOG row "prune" is
+// a guaranteed 409 `cannot_demote` — it is already at the bottom. `verbsFor`
+// below derives the offer from the row's actual status instead of hardcoding a
+// list, so this walk can never offer a button the server will refuse.
+//
+// Prompts per row:
+//   [p]romote   → POST /tasks/:id/promote  (backlog → ready; the nod. Also the
+//                 point the reward gate auto-assigns credits_reward if it is
+//                 0/NULL — ADR 0096 — so the assigned price is echoed back)
+//   [k]ill      → POST /tasks/:id/abandon {reason} (it is not going to happen)
+//   [w]ater     → POST /tasks/:id/water (leave it; reset the rot clock. The one
+//                 verb that changes no status and destroys nothing)
+//   [s]kip      → no write; the row surfaces again next review
+//   [q]uit      → exit early, print the partial summary
+//
+// Exit codes:
+//   0  walked cleanly (incl. an empty queue)
+//   1  api / network error
+//   2  no session
+
+const readline = require('node:readline');
+const { cliClient, requireSession, cliExit, hasFlag, arg } = require('./cli-lib');
+
+// The API caps ?limit at 1000 (`routes/tasks.js` — "limit must be a positive
+// integer up to 1000"). Spelled here rather than passed larger-and-hoped:
+// scripts/gds/audit-deps.js asks for 3000 and every run of it dies on a 400,
+// which is exactly how the stranded rows below went unnoticed.
+const MAX_API_LIMIT = 1000;
+
+// How many rows one sitting offers by default. The queue is routinely in the
+// hundreds; a walk that demands all of them gets abandoned halfway, which is
+// worse than a walk that reliably clears twenty. --all overrides.
+const DEFAULT_WALK_LIMIT = 20;
+
+// A dependency in one of these statuses can never satisfy, so anything gated on
+// it is stranded rather than waiting. Mirrors modules/lifecycle/dead-deps.js
+// DEAD_DEP_STATUSES — kept as its own constant because this script must run from
+// a plain checkout without loading the server's module tree.
+const DEAD_DEP_STATUSES = new Set(['abandoned']);
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function trim(s, n) {
+  const str = String(s || '');
+  return str.length > n ? `${str.slice(0, n - 1)}…` : str;
+}
+
+// unsatisfiedDeps(task) — the dependency edges still holding this row down.
+// `include=deps` returns blocked_by[] with a per-edge `satisfied` flag already
+// computed server-side (modules/lifecycle/db-deps-criteria.js), so this trusts
+// that flag rather than re-deriving "shipped" from a status string here.
+function unsatisfiedDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && !d.satisfied);
+}
+
+function deadDeps(task) {
+  return (task.blocked_by || []).filter((d) => d && DEAD_DEP_STATUSES.has(String(d.status)));
+}
+
+// partitionBacklog(tasks) — the four buckets, from one list of backlog rows.
+// Pure and exported: tests/backlog_review.mjs pins the bucket rules without
+// standing up Postgres, and the ordering below IS the review's priority claim.
+//
+// Order of tests matters and is deliberate: a stranded row is reported as
+// stranded even though it is also dep-gated, because "your gate is dead" is the
+// actionable fact and "you have a gate" is not.
+function partitionBacklog(tasks) {
+  const out = { stranded: [], nod: [], depGated: [], spikes: [] };
+  for (const t of Array.isArray(tasks) ? tasks : []) {
+    if (!t || String(t.status) !== 'backlog') continue;
+    const dead = deadDeps(t);
+    if (dead.length) { out.stranded.push({ ...t, dead_deps: dead }); continue; }
+    if (String(t.kind) === 'spike') { out.spikes.push(t); continue; }
+    if (unsatisfiedDeps(t).length) { out.depGated.push(t); continue; }
+    out.nod.push(t);
+  }
+  // Oldest first in both walked buckets: the row that has waited longest for a
+  // human is the one the cadence exists to catch, and a stable order means an
+  // interrupted walk resumes roughly where it stopped.
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  out.stranded.sort(byAge);
+  out.nod.sort(byAge);
+  return out;
+}
+
+// groupByGoal(rows) — cluster rows into goal groups so the walk is presented
+// goal-by-goal instead of as one flat list.
+//
+// WHY GROUP AT ALL. The nod decision is mostly a SCOPE judgment — "does this goal
+// want this work next" — and that judgment is made once per goal, not once per
+// row. Walking a flat age-ordered list makes the reviewer rebuild the same goal
+// context every few rows and re-decide the same question; clustering lets one
+// context answer five rows in a row.
+//
+// The ORDER still honours oldest-first, one level up: goals are ordered by their
+// own oldest waiting row, and rows inside a goal by age. So the goal that has
+// been ignored longest comes first, and nothing is buried by a chatty neighbour.
+// Returns [{ goal_id, rows }] — pure, exported, and the shape the walk iterates.
+function groupByGoal(rows) {
+  const byAge = (a, b) => String(a.created_at || '').localeCompare(String(b.created_at || '')) || Number(a.id) - Number(b.id);
+  const groups = new Map();
+  for (const t of Array.isArray(rows) ? rows : []) {
+    if (!t) continue;
+    // A goal-less row is its own group rather than being dropped or merged into
+    // some other goal's context. ADR 0250 D4 makes goal_id required on new tasks,
+    // so this is the legacy/system-created tail — small, but it must still be
+    // walkable or the queue would quietly retain rows the walk never offers.
+    const key = t.goal_id == null ? '(no goal)' : String(t.goal_id);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  const out = [];
+  for (const [goal_id, groupRows] of groups) {
+    groupRows.sort(byAge);
+    out.push({ goal_id, rows: groupRows });
+  }
+  // Goals ordered by their oldest row — the age rule, lifted one level.
+  out.sort((a, b) => byAge(a.rows[0], b.rows[0]));
+  return out;
+}
+
+// verbsFor(task) — what the server will ACTUALLY accept on this row, derived
+// from its status. See the header note: promote and demote are each valid for
+// disjoint status sets, so a fixed four-verb list is wrong for every row.
+function verbsFor(task) {
+  const status = String(task && task.status);
+  const verbs = [];
+  if (status === 'backlog' || status === 'blocked' || status === 'abandoned') verbs.push('promote');
+  if (status === 'ready') verbs.push('demote');
+  if (status !== 'shipped' && status !== 'abandoned') verbs.push('kill');
+  verbs.push('water');
+  return verbs;
+}
+
+async function listBacklog({ goalId } = {}) {
+  const api = await cliClient();
+  const query = { status: 'backlog', include: 'deps', limit: MAX_API_LIMIT };
+  if (goalId) query.goal_id = goalId;
+  const r = await api.tasks.getTasks({ query });
+  if (!r.ok) throw new Error(`GET /tasks?status=backlog failed (${r.status}): ${JSON.stringify(r.data)}`);
+  // GET /tasks responds { tasks: [...] }, not a bare array — the same shape trap
+  // that made bug-triage.js throw before listing anything (see its listOpenBugTasks).
+  return r.data?.tasks ?? [];
+}
+
+// Goal id -> title, for the walk's group headers. Fails OPEN: a header that shows
+// a bare id is a cosmetic loss, and a review that refuses to start because the
+// goal list did not load would be a much worse trade.
+async function fetchGoalTitles() {
+  try {
+    const api = await cliClient();
+    const r = await api.goals.getGoals({ query: { limit: 200 } });
+    if (!r.ok) return new Map();
+    return new Map((r.data?.goals ?? []).map((g) => [String(g.id), g.title]));
+  } catch (_) {
+    return new Map();
+  }
+}
+
+async function promoteTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdPromote({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`promote failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+async function killTask(id, reason) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdAbandon({ id, body: { reason: reason || '' } });
+  if (!r.ok) throw Object.assign(new Error(`kill failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+// The gentlest verb: it changes no status and destroys nothing (routes/rot.js).
+// Its route is `requireBuilder` plus an ownership-or-atom check in the handler —
+// authorized iff you CREATED the task or you hold the see-all-rot atom — so it is
+// not unconditionally open, and a caller who is neither gets a 403 naming both
+// paths. Every caller of THIS script is already Metic+ (the skill's rank gate), who
+// hold that atom per ADR 0157, so in practice it always passes here; the 403 is
+// surfaced verbatim rather than swallowed in case that ever stops being true.
+async function waterTask(id) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdWater({ id, body: {} });
+  if (!r.ok) throw Object.assign(new Error(`water failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+function printCounts(buckets) {
+  const { stranded, nod, depGated, spikes } = buckets;
+  const total = stranded.length + nod.length + depGated.length + spikes.length;
+  console.log(`\nBacklog: ${total} rows`);
+  console.log(`  ${nod.length} awaiting a nod        — a human is the only thing gating these (walked)`);
+  console.log(`  ${stranded.length} stranded              — gated by an ABANDONED dependency; the auto-promote trigger can never fire (walked first)`);
+  console.log(`  ${depGated.length} waiting on a dependency — shipping the dep auto-promotes them (migration 163); not a human decision, not walked`);
+  console.log(`  ${spikes.length} spikes                — live at backlog by convention (migration 020); not walked`);
+}
+
+function printRow(task, idx, total, label) {
+  console.log(`\n[${idx + 1}/${total}] ${label} #${task.id}  ${task.title}`);
+  if (task.description) console.log(`  ${trim(task.description, 300)}`);
+  const bits = [];
+  if (task.goal_id) bits.push(`goal ${task.goal_id}`);
+  if (task.kind) bits.push(task.kind);
+  if (task.discipline && task.discipline !== 'unclassified') bits.push(task.discipline);
+  if (task.est_minutes) bits.push(`~${task.est_minutes}m`);
+  bits.push(task.credits_reward ? `${task.credits_reward} credits` : 'no reward set — promote assigns one');
+  if (task.created_at) bits.push(`filed ${String(task.created_at).slice(0, 10)}`);
+  console.log(`  ${bits.join(' · ')}`);
+  for (const d of task.dead_deps || []) {
+    console.log(`  ⚠ dependency ${d.id} is ${d.status}: "${trim(d.title, 60)}" — this edge can NEVER satisfy.`);
+  }
+  if (task.dead_deps && task.dead_deps.length) {
+    const first = task.dead_deps[0].id;
+    console.log('  → Resolve it deliberately: DROP the dead edge (DELETE /api/bongos/dependencies '
+      + `{"from_kind":"task","from_id":${task.id},"to_kind":"task","to_id":${first}}) `
+      + `or RESTORE the dependency (POST /api/bongos/tasks/${first}/promote returns an abandoned task to backlog).`);
+  }
+}
+
+// The per-row walk. Mutates `state.summary`; returns false when the user quits.
+async function walkRow(rl, task, idx, total, label, state) {
+  printRow(task, idx, total, label);
+  for (;;) {
+    const offer = verbsFor(task).includes('promote')
+      ? '  [p]romote (make claimable) / [k]ill / [w]ater (leave it, reset the clock) / [s]kip / [q]uit > '
+      : '  [k]ill / [w]ater / [s]kip / [q]uit > ';
+    const ans = (await prompt(rl, offer)).trim().toLowerCase();
+
+    if (ans === 'q' || ans === 'quit') return false;
+    if (ans === 's' || ans === 'skip' || ans === '') { state.summary.skipped++; return true; }
+
+    if (ans === 'p' || ans === 'promote') {
+      if (!verbsFor(task).includes('promote')) { console.log(`  ? #${task.id} is '${task.status}' — promote does not apply`); continue; }
+      try {
+        const data = await promoteTask(task.id);
+        state.summary.promoted++;
+        const assigned = data && data.assigned_credits_reward;
+        console.log(`  ✓ #${task.id} → ready${assigned ? ` (reward gate assigned ${assigned} credits)` : ''}`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'k' || ans === 'kill') {
+      const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+      try {
+        await killTask(task.id, reason || 'retired during /backlog-review — not going to happen');
+        state.summary.killed++;
+        console.log(`  ✖ #${task.id} abandoned (restorable: POST /tasks/${task.id}/promote returns it to backlog)`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    if (ans === 'w' || ans === 'water') {
+      try {
+        await waterTask(task.id);
+        state.summary.watered++;
+        console.log(`  ~ #${task.id} watered — the rot clock is reset; nothing else changed`);
+      } catch (err) { console.error(`  ! #${task.id}: ${err.message}`); }
+      return true;
+    }
+
+    console.log('  ? unknown — type p, k, w, s, or q');
+  }
+}
+
+async function main() {
+  await requireSession();
+
+  const goalId = arg('--goal');
+  const walkAll = hasFlag('--all');
+  const limitRaw = Number(arg('--limit'));
+  const walkLimit = walkAll ? Infinity : (Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : DEFAULT_WALK_LIMIT);
+
+  let rows;
+  try {
+    rows = await listBacklog({ goalId });
+  } catch (err) {
+    console.error(`backlog-review: ${err.message}`);
+    return cliExit(1);
+  }
+
+  const buckets = partitionBacklog(rows);
+  printCounts(buckets);
+
+  // Goal titles for the group headers — one extra read so a header names the goal
+  // instead of showing a bare id the reviewer has to go look up.
+  const goalTitles = await fetchGoalTitles();
+
+  // Stranded first, then the nod queue — see partitionBacklog's header. Each
+  // bucket is walked goal-by-goal (groupByGoal), and the flattened result keeps
+  // that grouping so the walk's own loop stays a simple sequence.
+  const queue = [];
+  for (const [bucket, label] of [[buckets.stranded, 'STRANDED'], [buckets.nod, 'awaiting a nod']]) {
+    for (const group of groupByGoal(bucket)) {
+      queue.push(...group.rows.map((t, i) => ({
+        task: t,
+        label,
+        // The header rides on the FIRST row of each group, so it prints exactly
+        // once even after the --limit slice cuts the queue mid-group.
+        groupHeader: i === 0
+          ? `${label === 'STRANDED' ? 'Stranded in' : 'Goal'} ${group.goal_id}${goalTitles.get(group.goal_id) ? ` — ${goalTitles.get(group.goal_id)}` : ''} (${group.rows.length} row${group.rows.length === 1 ? '' : 's'})`
+          : null,
+      })));
+    }
+  }
+
+  if (!queue.length) {
+    console.log('\nNothing to review — no backlog row is waiting on a person today.');
+    return cliExit(0);
+  }
+
+  const slice = queue.slice(0, walkLimit === Infinity ? queue.length : walkLimit);
+  if (slice.length < queue.length) {
+    console.log(`\nWalking the ${slice.length} oldest of ${queue.length} (--limit N or --all for more).`);
+  }
+
+  const state = { summary: { promoted: 0, killed: 0, watered: 0, skipped: 0 } };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (let i = 0; i < slice.length; i++) {
+      if (slice[i].groupHeader) {
+        console.log(`\n${'─'.repeat(72)}\n${slice[i].groupHeader}\n${'─'.repeat(72)}`);
+      }
+      const keepGoing = await walkRow(rl, slice[i].task, i, slice.length, slice[i].label, state);
+      if (!keepGoing) { console.log('\n(quit early)'); break; }
+    }
+  } finally {
+    rl.close();
+  }
+
+  const s = state.summary;
+  console.log(`\nReviewed: ${s.promoted} promoted · ${s.killed} killed · ${s.watered} watered · ${s.skipped} skipped`);
+  const left = queue.length - (s.promoted + s.killed + s.watered);
+  if (left > 0) console.log(`${left} row(s) still awaiting a human — run /backlog-review again to continue.`);
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`backlog-review: ${err && err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  groupByGoal,
+  partitionBacklog,
+  verbsFor,
+  unsatisfiedDeps,
+  deadDeps,
+  DEAD_DEP_STATUSES,
+  MAX_API_LIMIT,
+  DEFAULT_WALK_LIMIT,
+};

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.616'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.618'; // 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('dev-box'); log.info('mounted');
@@ -288,6 +288,32 @@ module.exports = {
   // it instead of reaching into src/branding.js directly (BV1.R86).
   userAgent: branding.userAgent,
   resolveEnv: instanceConfig.resolveEnv,
+  // --- the two ROOTS (ADR 0108 §1), added for task 1003739 because a module
+  //     that reads BOTH a core default and a host override cannot tell them
+  //     apart without these — and getting that wrong is silent, not loud.
+  //
+  //     resolveCoreRoot()     — where the core PACKAGE's own files live: core
+  //                             modules/, core migrations/, the *.neutral.json
+  //                             defaults. In a single checkout it is the repo
+  //                             root; once an instance installs the core as a
+  //                             dependency it is node_modules/@cloudbongos/core.
+  //     resolveInstanceRoot() — where HOST content lives: config/, instance
+  //                             modules/, identity. The instance repo, always.
+  //
+  //     THE FAILURE THEY EXIST TO PREVENT, stated because it already happened.
+  //     modules/government/config.js resolved BOTH from `path.resolve(__dirname,
+  //     '..', '..')` — correct while the two roots coincided, and wrong the day
+  //     cloudbongos.com started running a PINNED core. Its instance pack then
+  //     resolved to node_modules/@cloudbongos/core/config/government.json: the
+  //     host's real file was never read, and a ratified constitutional amendment
+  //     was written into node_modules, where the next `npm ci` erased it. The
+  //     board had decided and the decision quietly did not take. There is no
+  //     error to catch in that shape — both paths exist and both are writable —
+  //     so the only defence is resolving each from the root that owns it.
+  //     src/branding.js is the pattern to copy: NEUTRAL from the core root,
+  //     INSTANCE from the instance root.
+  resolveCoreRoot: instanceConfig.resolveCoreRoot,
+  resolveInstanceRoot: instanceConfig.resolveInstanceRoot,
   // --- the project's STALE-CLAIM TIMER (task 1003476, goal 1000072) — how long a
   //     claim may go silent before this project calls it abandoned. ONE number for
   //     every surface that reports or enforces it: before this, the sweeper that

package/tests/backlog_review.mjs

@@ -0,0 +1,183 @@
+// tests/backlog_review.mjs — the /backlog-review bucket rules and the
+// status-derived verb offer (task 1003746).
+//
+// These are the two claims the skill rests on, so they are the two things a test
+// has to execute rather than paraphrase: (1) a row waiting on a live TRIGGER is
+// never presented as waiting on a PERSON, and (2) the walk never offers a verb
+// the route will refuse. The `skill names a command it never runs` learning
+// (r155-documented-nonfunctional-command) is why the last test here actually
+// requires and calls the module the SKILL.md tells a builder to run.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const br = require('../scripts/gds/backlog-review.js');
+
+const task = (over = {}) => ({
+  id: 1, status: 'backlog', kind: 'feature', title: 't', created_at: '2026-01-01T00:00:00Z',
+  blocked_by: [], ...over,
+});
+
+test('a row with no unsatisfied dependency is awaiting a nod', () => {
+  const p = br.partitionBacklog([task({ id: 7 })]);
+  assert.deepEqual(p.nod.map((t) => t.id), [7]);
+  assert.equal(p.depGated.length, 0);
+  assert.equal(p.stranded.length, 0);
+});
+
+test('a satisfied dependency does NOT make a row dep-gated', () => {
+  const p = br.partitionBacklog([task({ id: 8, blocked_by: [{ id: 2, status: 'shipped', satisfied: true }] })]);
+  assert.deepEqual(p.nod.map((t) => t.id), [8], 'a shipped dep is not a gate');
+  assert.equal(p.depGated.length, 0);
+});
+
+test('a live unsatisfied dependency is dep-gated and is NOT walked as a nod', () => {
+  const p = br.partitionBacklog([task({ id: 9, blocked_by: [{ id: 3, status: 'ready', satisfied: false }] })]);
+  assert.deepEqual(p.depGated.map((t) => t.id), [9]);
+  assert.equal(p.nod.length, 0, 'the migration-163 trigger owns this row, not a human');
+});
+
+test('an ABANDONED dependency makes a row stranded, not merely dep-gated', () => {
+  const p = br.partitionBacklog([task({ id: 10, blocked_by: [{ id: 4, status: 'abandoned', satisfied: false }] })]);
+  assert.deepEqual(p.stranded.map((t) => t.id), [10]);
+  assert.equal(p.depGated.length, 0, 'stranded wins: "your gate is dead" is the actionable fact');
+  assert.deepEqual(p.stranded[0].dead_deps.map((d) => d.id), [4], 'the dead edges ride along for the hint');
+});
+
+test('stranded wins over spike too — a dead gate outranks the backlog-by-convention rule', () => {
+  const p = br.partitionBacklog([task({ id: 11, kind: 'spike', blocked_by: [{ id: 5, status: 'abandoned', satisfied: false }] })]);
+  assert.deepEqual(p.stranded.map((t) => t.id), [11]);
+  assert.equal(p.spikes.length, 0);
+});
+
+test('a spike lives at backlog by convention and is never walked', () => {
+  const p = br.partitionBacklog([task({ id: 12, kind: 'spike' })]);
+  assert.deepEqual(p.spikes.map((t) => t.id), [12]);
+  assert.equal(p.nod.length, 0, 'migration 020: spikes stay in backlog by convention');
+});
+
+test('rows that are not at backlog are ignored entirely', () => {
+  const p = br.partitionBacklog([task({ id: 13, status: 'ready' }), task({ id: 14, status: 'shipped' }), task({ id: 15, status: 'blocked' })]);
+  assert.equal(p.nod.length + p.depGated.length + p.stranded.length + p.spikes.length, 0);
+});
+
+test('partitionBacklog tolerates junk without throwing', () => {
+  assert.doesNotThrow(() => br.partitionBacklog(null));
+  assert.doesNotThrow(() => br.partitionBacklog([null, undefined, {}]));
+  const p = br.partitionBacklog([task({ id: 16, blocked_by: null })]);
+  assert.deepEqual(p.nod.map((t) => t.id), [16], 'a null blocked_by is no gate, not a crash');
+});
+
+test('both walked buckets are ordered oldest-first so an interrupted walk resumes in place', () => {
+  const p = br.partitionBacklog([
+    task({ id: 30, created_at: '2026-03-01T00:00:00Z' }),
+    task({ id: 31, created_at: '2026-01-01T00:00:00Z' }),
+    task({ id: 32, created_at: '2026-02-01T00:00:00Z' }),
+  ]);
+  assert.deepEqual(p.nod.map((t) => t.id), [31, 32, 30]);
+});
+
+// --- goal grouping --------------------------------------------------------
+
+test('rows are clustered by goal, not left interleaved', () => {
+  const g = br.groupByGoal([
+    task({ id: 40, goal_id: 1, created_at: '2026-01-01T00:00:00Z' }),
+    task({ id: 41, goal_id: 2, created_at: '2026-01-02T00:00:00Z' }),
+    task({ id: 42, goal_id: 1, created_at: '2026-01-03T00:00:00Z' }),
+  ]);
+  assert.equal(g.length, 2, 'two goals, two groups');
+  assert.deepEqual(g[0].rows.map((t) => t.id), [40, 42], 'goal 1 rows are adjacent');
+  assert.deepEqual(g[1].rows.map((t) => t.id), [41]);
+});
+
+test('goals are ordered by their OWN oldest row, so the longest-ignored goal comes first', () => {
+  const g = br.groupByGoal([
+    task({ id: 50, goal_id: 'new', created_at: '2026-05-01T00:00:00Z' }),
+    task({ id: 51, goal_id: 'old', created_at: '2026-01-01T00:00:00Z' }),
+    task({ id: 52, goal_id: 'new', created_at: '2026-05-02T00:00:00Z' }),
+  ]);
+  assert.deepEqual(g.map((x) => x.goal_id), ['old', 'new']);
+});
+
+test('rows inside a group stay oldest-first', () => {
+  const g = br.groupByGoal([
+    task({ id: 60, goal_id: 1, created_at: '2026-03-01T00:00:00Z' }),
+    task({ id: 61, goal_id: 1, created_at: '2026-01-01T00:00:00Z' }),
+    task({ id: 62, goal_id: 1, created_at: '2026-02-01T00:00:00Z' }),
+  ]);
+  assert.deepEqual(g[0].rows.map((t) => t.id), [61, 62, 60]);
+});
+
+test('a goal-less row is walkable in its own group, never dropped', () => {
+  const g = br.groupByGoal([task({ id: 70, goal_id: null }), task({ id: 71, goal_id: 5 })]);
+  const total = g.reduce((n, x) => n + x.rows.length, 0);
+  assert.equal(total, 2, 'every input row reaches a group');
+  assert.ok(g.some((x) => x.goal_id === '(no goal)'));
+});
+
+test('grouping loses no rows and duplicates none, on a mixed batch', () => {
+  const rows = [];
+  for (let i = 0; i < 25; i++) rows.push(task({ id: 100 + i, goal_id: i % 4, created_at: `2026-01-${String((i % 28) + 1).padStart(2, '0')}T00:00:00Z` }));
+  const g = br.groupByGoal(rows);
+  const ids = g.flatMap((x) => x.rows.map((t) => t.id)).sort((a, b) => a - b);
+  assert.equal(new Set(ids).size, 25);
+  assert.deepEqual(ids, rows.map((t) => t.id).sort((a, b) => a - b));
+});
+
+test('groupByGoal tolerates junk', () => {
+  assert.deepEqual(br.groupByGoal(null), []);
+  assert.deepEqual(br.groupByGoal([null, undefined]), []);
+});
+
+// --- the verb offer -------------------------------------------------------
+
+test('a backlog row is offered promote, never demote', () => {
+  const v = br.verbsFor(task({ status: 'backlog' }));
+  assert.ok(v.includes('promote'));
+  assert.ok(!v.includes('demote'), 'POST /tasks/:id/demote requires status=ready — it would 409 cannot_demote here');
+});
+
+test('a ready row is offered demote, never promote', () => {
+  const v = br.verbsFor(task({ status: 'ready' }));
+  assert.ok(v.includes('demote'));
+  assert.ok(!v.includes('promote'), 'POST /tasks/:id/promote accepts only backlog|blocked|abandoned');
+});
+
+test('blocked and abandoned rows accept promote (the blocked→ready and un-abandon paths)', () => {
+  assert.ok(br.verbsFor(task({ status: 'blocked' })).includes('promote'));
+  assert.ok(br.verbsFor(task({ status: 'abandoned' })).includes('promote'), 'ADR 0152: abandoned → backlog restore');
+});
+
+test('water is offered on every row and kill is never offered on a terminal one', () => {
+  for (const status of ['backlog', 'ready', 'blocked', 'active', 'shipped', 'abandoned']) {
+    assert.ok(br.verbsFor(task({ status })).includes('water'), `water missing for ${status}`);
+  }
+  assert.ok(!br.verbsFor(task({ status: 'shipped' })).includes('kill'));
+  assert.ok(!br.verbsFor(task({ status: 'abandoned' })).includes('kill'));
+  assert.ok(br.verbsFor(task({ status: 'backlog' })).includes('kill'));
+});
+
+test('the API limit the script asks for is within the route cap of 1000', () => {
+  assert.ok(br.MAX_API_LIMIT <= 1000, 'routes/tasks.js: "limit must be a positive integer up to 1000"');
+  assert.ok(br.MAX_API_LIMIT > 0);
+});
+
+// --- the skill names a command that exists and runs -----------------------
+
+test('SKILL.md names scripts/gds/backlog-review.js and that file loads and partitions', () => {
+  const skill = fs.readFileSync(path.join(ROOT, '.claude', 'skills', 'backlog-review', 'SKILL.md'), 'utf8');
+  assert.match(skill, /scripts\/gds\/backlog-review\.js/, 'the skill must name the script it runs');
+  // Executed, not paraphrased: the module the prose points at really answers.
+  const p = br.partitionBacklog([task({ id: 99 })]);
+  assert.deepEqual(p.nod.map((t) => t.id), [99]);
+});
+
+test('SKILL.md does not tell a builder to demote a backlog row', () => {
+  const skill = fs.readFileSync(path.join(ROOT, '.claude', 'skills', 'backlog-review', 'SKILL.md'), 'utf8');
+  assert.ok(!/\[p\]rune/.test(skill), 'prune/demote is a guaranteed 409 on a backlog row');
+});