@bongos/core 1.18.3 → 1.18.18

package/tests/goal_advisory.mjs

@@ -0,0 +1,251 @@
+// tests/goal_advisory.mjs — the orphan-task advisory (task 1002539).
+//
+// A task with no goal is NOT an error and was never blocked. db.createTask falls
+// back to the version's "<version> — general" catch-all; for any version created
+// after migration 160 that goal does not exist, so goal_id lands NULL silently.
+// `goal_advisory` on the POST /tasks 201 surfaces that without blocking anything.
+//
+// Two properties matter and both are pinned here:
+//   1. DETECTION is exact — the em dash is load-bearing, and a real goal is silent.
+//   2. The advisory can NEVER fail the create. The route's try/catch is asserted by
+//      driving it with a db that throws (the last test), because that invariant is
+//      the one a future refactor will quietly break.
+//
+// Run:  node tests/goal_advisory.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const { adviseGoal, candidateGoals, generalGoalTitle, buildGoalAdvisory } = require('../modules/lifecycle/goal-advisory.js');
+
+const tasksSrc = readFileSync(new URL('../modules/lifecycle/routes/tasks.js', import.meta.url), 'utf8');
+const dbSrc = readFileSync(new URL('../modules/lifecycle/db.js', import.meta.url), 'utf8');
+const { test, summary } = makeRunner();
+
+const V = 'BONGOS-V1';
+
+// ---- generalGoalTitle: the em dash is the whole contract ----
+
+await test('generalGoalTitle matches migration 160 exactly — spaced EM DASH (U+2014)', () => {
+  const t = generalGoalTitle(V);
+  assert.equal(t, 'BONGOS-V1 — general');
+  assert.equal(t.charCodeAt(V.length + 1), 0x2014, 'U+2014 EM DASH, not a hyphen or en dash');
+});
+
+// ---- adviseGoal: the two reasons ----
+
+await test('no_goal — a NULL goal_id is the structurally orphaned case', () => {
+  const a = adviseGoal({ versionId: V, goalId: null });
+  assert.equal(a.reason, 'no_goal');
+  assert.equal(a.goal_id, null);
+  assert.equal(a.version_id, V);
+});
+
+await test('catch_all — landing in "<version> — general" is a bucket, not a home', () => {
+  const a = adviseGoal({ versionId: V, goalId: 3, goalTitle: generalGoalTitle(V) });
+  assert.equal(a.reason, 'catch_all');
+  assert.equal(a.goal_id, 3, 'names the catch-all so a caller can PATCH away from it');
+});
+
+await test('a REAL goal is silent — null, not an empty object', () => {
+  assert.equal(adviseGoal({ versionId: V, goalId: 1000025, goalTitle: 'Builder experience — hall, dev box, and skills' }), null);
+});
+
+// The bug this guards: a near-miss title must not be mistaken for the catch-all.
+// db.generalGoalIdForVersion resolves the SAME string, so if these two ever disagree
+// a task would be filed into a goal the advisory then calls orphaned (or vice versa).
+await test('near-miss titles are NOT the catch-all — ascii hyphen, en dash, no spaces, other version', () => {
+  for (const title of ['BONGOS-V1 - general', 'BONGOS-V1 – general', 'BONGOS-V1—general', 'CB-V1 — general', 'general', '']) {
+    assert.equal(adviseGoal({ versionId: V, goalId: 5, goalTitle: title }), null, `"${title}" must not match`);
+  }
+});
+
+// ---- fail-OPEN (the inverse posture of an authorization gate) ----
+
+await test('FAIL-OPEN: ambiguous input says nothing rather than nagging', () => {
+  assert.equal(adviseGoal({ versionId: V, goalId: 5, goalTitle: undefined }), null, 'unknown title → silent');
+  assert.equal(adviseGoal({ versionId: null, goalId: 5, goalTitle: 'x — general' }), null, 'unknown version → silent');
+  assert.equal(adviseGoal({ versionId: V, goalId: 5, goalTitle: null }), null);
+});
+
+await test('FAIL-OPEN: a bare {} is the no_goal case, and nothing throws on junk', () => {
+  assert.equal(adviseGoal({}).reason, 'no_goal');
+  assert.doesNotThrow(() => adviseGoal());
+  assert.doesNotThrow(() => adviseGoal({ versionId: 1, goalId: 'x', goalTitle: 7 }));
+});
+
+// ---- candidateGoals ----
+
+await test('candidateGoals drops the catch-all, preserves order, shapes to id/title/scope', () => {
+  const goals = [
+    { id: 1, title: generalGoalTitle(V), scope_modules: [], status: 'open', created_by: null },
+    { id: 2, title: 'Builder experience', scope_modules: ['hall-ui'], status: 'open', extra: 'dropped' },
+    { id: 3, title: 'Governance', scope_modules: ['governance'], status: 'open' },
+  ];
+  const out = candidateGoals(goals, V);
+  assert.deepEqual(out, [
+    { id: 2, title: 'Builder experience', scope_modules: ['hall-ui'] },
+    { id: 3, title: 'Governance', scope_modules: ['governance'] },
+  ]);
+});
+
+await test('candidateGoals is total — non-array, empty, and missing scope_modules', () => {
+  assert.deepEqual(candidateGoals(null, V), []);
+  assert.deepEqual(candidateGoals(undefined, V), []);
+  assert.deepEqual(candidateGoals([], V), []);
+  assert.deepEqual(candidateGoals([{ id: 9, title: 'G' }], V), [{ id: 9, title: 'G', scope_modules: [] }]);
+});
+
+// ---- the ONE definition of the catch-all title ----
+
+await test('db.js resolves the catch-all through generalGoalTitle — no second spelling', () => {
+  assert.match(dbSrc, /require\('\.\/goal-advisory\.js'\)/, 'db.js imports the shared helper');
+  assert.match(dbSrc, /title = \$2 LIMIT 1/, 'the SQL binds the title rather than inlining it');
+  assert.equal(
+    (dbSrc.match(/' — general'/g) || []).length, 0,
+    'the em-dash literal must exist in exactly ONE place (goal-advisory.js), not in db.js too'
+  );
+});
+
+// ---- the non-blocking contract, asserted rather than commented ----
+
+await test('the route delegates to buildGoalAdvisory in one line — no inline logic to drift', () => {
+  assert.match(tasksSrc, /const goal_advisory = await buildGoalAdvisory\(\{ db, versionId: body\.version_id, task \}\);/);
+  assert.match(tasksSrc, /goal_advisory,\s*\}\);/, 'included in the 201 body');
+});
+
+// ---- buildGoalAdvisory: the real function, driven with a stub db ----
+
+const stubDb = ({ goal = null, goals = [], throwOn = null } = {}) => ({
+  async getGoal() { if (throwOn === 'getGoal') throw new Error('db down'); return goal; },
+  async listGoals() { if (throwOn === 'listGoals') throw new Error('db down'); return goals; },
+});
+
+await test('buildGoalAdvisory: a goal-less task yields the no_goal advisory + candidates', async () => {
+  const db = stubDb({ goals: [
+    { id: 1, title: generalGoalTitle(V), scope_modules: [] },
+    { id: 2, title: 'Builder experience', scope_modules: ['hall-ui'] },
+  ] });
+  const a = await buildGoalAdvisory({ db, versionId: V, task: { id: 42, goal_id: null } });
+  assert.equal(a.reason, 'no_goal');
+  assert.deepEqual(a.candidate_goals, [{ id: 2, title: 'Builder experience', scope_modules: ['hall-ui'] }],
+    'the catch-all is never offered as a home');
+  assert.match(a.next_step, /\/goal-create/);
+  assert.match(a.next_step, /PATCH \/tasks\/42/, 'names the actual task id');
+});
+
+await test('buildGoalAdvisory: a task in a REAL goal is silent, and never reads the goal list', async () => {
+  let listed = false;
+  const db = {
+    async getGoal() { return { id: 9, title: 'Builder experience' }; },
+    async listGoals() { listed = true; return []; },
+  };
+  assert.equal(await buildGoalAdvisory({ db, versionId: V, task: { id: 1, goal_id: 9 } }), null);
+  assert.equal(listed, false, 'the happy path costs exactly one query');
+});
+
+await test('buildGoalAdvisory: the catch-all is detected and named', async () => {
+  const db = stubDb({ goal: { id: 3, title: generalGoalTitle(V) }, goals: [] });
+  const a = await buildGoalAdvisory({ db, versionId: V, task: { id: 7, goal_id: 3 } });
+  assert.equal(a.reason, 'catch_all');
+  assert.equal(a.goal_id, 3);
+});
+
+// The invariant a future refactor will quietly break. Both DB calls are covered:
+// getGoal is only reached when goal_id is set, listGoals only on the unhappy path.
+await test('NON-BLOCKING: buildGoalAdvisory returns null when getGoal throws', async () => {
+  const a = await buildGoalAdvisory({ db: stubDb({ throwOn: 'getGoal' }), versionId: V, task: { id: 1, goal_id: 5 } });
+  assert.equal(a, null, 'degrades to silence — never propagates into the already-committed create');
+});
+
+await test('NON-BLOCKING: buildGoalAdvisory returns null when listGoals throws', async () => {
+  const a = await buildGoalAdvisory({ db: stubDb({ throwOn: 'listGoals' }), versionId: V, task: { id: 1, goal_id: null } });
+  assert.equal(a, null);
+});
+
+await test('NON-BLOCKING: a db missing the methods entirely still yields null, not a crash', async () => {
+  assert.equal(await buildGoalAdvisory({ db: {}, versionId: V, task: { id: 1, goal_id: 5 } }), null);
+});
+
+
+// ---- ROUTER-LEVEL: the invariant asserted over real HTTP ----
+// The unit tests above prove buildGoalAdvisory degrades to null. This proves the
+// thing that actually matters to a caller: when the advisory's DB reads blow up,
+// POST /tasks still answers 201 with the task, and goal_advisory is null. If this
+// ever regresses, a created task becomes a 500, the caller retries, and without a
+// source_ref that mints a duplicate.
+
+const express = require('express');
+
+function listen(app) {
+  return new Promise((resolve) => {
+    const server = app.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+function post(port, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(
+      { host: '127.0.0.1', port, path, method: 'POST',
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } },
+      (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(data || '{}') }));
+      }
+    );
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+// A miniature stand-in for the POST /tasks tail: the task row is already created,
+// then the advisory runs, then the 201 goes out — the exact ordering in tasks.js.
+function makeApp(db) {
+  const app = express();
+  app.use(express.json());
+  app.post('/tasks', async (req, res) => {
+    try {
+      const task = { id: 99, goal_id: null, credits_reward: 60 };   // already committed
+      const goal_advisory = await buildGoalAdvisory({ db, versionId: req.body.version_id, task });
+      res.status(201).json({ task, criteria: [], goal_advisory });
+    } catch (err) {
+      res.status(500).json({ error: { code: 'create_failed' } });
+    }
+  });
+  return app;
+}
+
+await test('HTTP: a healthy db yields 201 with a populated goal_advisory', async () => {
+  const db = { async getGoal() { return null; }, async listGoals() { return [{ id: 2, title: 'Builder experience', scope_modules: [] }]; } };
+  const server = await listen(makeApp(db));
+  try {
+    const r = await post(server.address().port, '/tasks', { version_id: V });
+    assert.equal(r.status, 201);
+    assert.equal(r.body.goal_advisory.reason, 'no_goal');
+    assert.deepEqual(r.body.goal_advisory.candidate_goals, [{ id: 2, title: 'Builder experience', scope_modules: [] }]);
+  } finally { server.close(); }
+});
+
+await test('HTTP: db.listGoals THROWS → still 201, task returned, goal_advisory null (never a 500)', async () => {
+  const db = {
+    async getGoal() { throw new Error('db down'); },
+    async listGoals() { throw new Error('db down'); },
+  };
+  const server = await listen(makeApp(db));
+  try {
+    const r = await post(server.address().port, '/tasks', { version_id: V });
+    assert.equal(r.status, 201, 'the create must NOT become a 500 the caller retries into a duplicate');
+    assert.equal(r.body.task.id, 99, 'the created task is still returned');
+    assert.equal(r.body.goal_advisory, null, 'the advisory degrades to silence');
+  } finally { server.close(); }
+});
+
+summary();

package/tests/goal_criterion_confirm_ui.mjs

@@ -0,0 +1,269 @@
+// tests/goal_criterion_confirm_ui.mjs — in-hall criterion confirmation (task 1002164).
+//
+// The goal's bx-hall criterion says core task actions must work in the builders
+// hall WITHOUT invoking the LLM. Criterion confirmation violated that: the goal
+// detail page rendered only two states (satisfied ✓ / not) and its summary line
+// literally told the builder to go run the /goal-review CLI skill. The server
+// side already derived "met — pending review" (ADR 0086 §6 / BV1.R63) and already
+// exposed POST /done-when/:id/satisfy at Metic+; only the UI was missing.
+//
+// This EXECUTES the real modules/hall-ui/public/goals-page.js in a vm under a
+// minimal DOM/kit stub (the tests/hall_signout.mjs precedent — there is no jsdom
+// in this repo), boots it against a fake API serving one goal with all three
+// criterion states, and asserts on the HTML it actually writes. It then drives a
+// real click on the rendered Confirm button and proves the POST fires.
+//
+// Covers:
+//   • the three criterion states render distinguishably (satisfied / pending / open)
+//   • a Metic sees Confirm on a pending criterion — and only on a pending one
+//   • a Xenos sees the state but NOT the control (server still enforces)
+//   • an achieved or archived goal offers no Confirm at all
+//   • the summary line no longer points at /goal-review, and counts what's ready
+//   • clicking Confirm POSTs /done-when/:id/satisfy and re-reads the goal
+//   • goal_achieved:true is announced to the builder
+//
+// Run:  node tests/goal_criterion_confirm_ui.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/goals-page.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const CRIT = {
+  satisfied: { id: 501, criterion_id: 'c-done', criterion_md: 'Already confirmed', satisfied: true, pending_review: false },
+  pending: { id: 502, criterion_id: 'c-pending', criterion_md: 'All its tasks shipped', satisfied: false, pending_review: true },
+  open: { id: 503, criterion_id: 'c-open', criterion_md: 'Still has open work', satisfied: false, pending_review: false },
+};
+
+// Boot goals-page.js against a fake API and return what it rendered + recorded.
+// `rank` drives the client-side control gate; `goalStatus` drives the goal state.
+async function render({ rank = 'metic', goalStatus = 'open', criteria = Object.values(CRIT), satisfyResponse } = {}) {
+  const calls = { requests: [], toasts: [] };
+  const els = new Map();
+  const listeners = new Map(); // selector -> [handler]
+
+  const makeEl = (key) => {
+    const el = {
+      _key: key, dataset: {}, style: {}, title: '', textContent: '', hidden: false, disabled: false, value: '',
+      innerHTML: '',
+      classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+      setAttribute() {}, getAttribute() { return null; }, removeAttribute() {},
+      appendChild() {}, focus() {}, click() {}, querySelectorAll() { return []; },
+      addEventListener(type, fn) {
+        if (type !== 'click') return;
+        if (!listeners.has(key)) listeners.set(key, []);
+        listeners.get(key).push(fn);
+      },
+    };
+    return el;
+  };
+  const $ = (sel) => {
+    if (!sel) return null;
+    if (!els.has(sel)) els.set(sel, makeEl(sel));
+    return els.get(sel);
+  };
+
+  const goal = { id: 7, version_id: 'V1', title: 'Builder experience', description: '', status: goalStatus, visibility: 'public', created_by: 999, scope_modules: [] };
+  const detail = { goal, members: [], criteria, dependencies: [] };
+
+  const api = {
+    request(method, p) {
+      calls.requests.push([method, p]);
+      const reply = (data, status = 200) => Promise.resolve({ status, ok: true, data });
+      if (method === 'GET' && /\/me$/.test(p)) return reply({ builder: { id: 1, rank }, active_claims: [] });
+      if (method === 'GET' && /\/goals$/.test(p)) return reply({ goals: [goal] });
+      if (method === 'GET' && /\/goals\/7$/.test(p)) return reply(detail);
+      if (method === 'GET' && /\/tasks\?/.test(p)) return reply({ tasks: [] });
+      if (method === 'GET' && /\/conflicts$/.test(p)) return reply({ pairs: [] });
+      if (method === 'GET' && /\/requests$/.test(p)) return reply({ requests: [] });
+      if (method === 'POST' && /\/done-when\/\d+\/satisfy$/.test(p)) {
+        return Promise.resolve(satisfyResponse || { status: 200, ok: true, data: { criterion: {}, goal_achieved: false, goal: null } });
+      }
+      return reply({});
+    },
+  };
+
+  const pager = (prefix) => ({ prefix, page: 1, perPage: 25 });
+  const windowObj = {
+    OTB: {
+      escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch])),
+      $, fmtNum: (n) => String(n), fmtDate: () => '', rankLabel: (r) => r,
+      toast: (m) => calls.toasts.push(m),
+    },
+    OTBKit: {
+      makePager: (prefix) => pager(prefix),
+      paginate: (rows) => rows,
+      wirePager() {}, pagerBarHtml: () => '',
+      makeTabs: () => ({ setCount() {}, select() {}, activate() {} }),
+      makeFilterBar() {},
+      emptyStateHtml: (m) => `<div class="kit-empty">${m}</div>`,
+      skeletonRows: () => '',
+    },
+    OTBBranding: { currencyLabel: () => 'credits', taskSettled: () => false, taskCreditValue: () => 0 },
+    BongosClient: { createClient: () => api },
+    location: { hash: '#/goal/7', pathname: '/builders/goals', assign() {} },
+    addEventListener() {},
+    scrollTo() {},
+    matchMedia: () => ({ matches: false, addEventListener() {} }),
+    localStorage: { getItem() { return null; }, setItem() {} },
+  };
+  const documentObj = {
+    body: { dataset: {} },
+    documentElement: { dataset: {}, style: {}, classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } } },
+    getElementById: (id) => $(`#${id}`),
+    querySelector: (sel) => $(sel),
+    querySelectorAll: () => [],
+    createElement: () => makeEl('created'),
+    addEventListener() {},
+  };
+
+  const sandbox = { window: windowObj, document: documentObj, location: windowObj.location, console, setTimeout, clearTimeout, Set, Map, Number, String, Array, Object, JSON, Math, encodeURIComponent, Promise };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(SRC, sandbox, { filename: 'goals-page.js' });
+
+  // Let boot()'s promise chain settle (me → goals → details → route → render).
+  for (let i = 0; i < 25; i++) await new Promise((r) => setTimeout(r, 0));
+
+  const clickConfirm = async (critId) => {
+    const handlers = listeners.get('#goal-completion-body') || [];
+    assert.ok(handlers.length > 0, 'a click listener must be wired on the completion band');
+    const btn = { disabled: false, textContent: 'Confirm', dataset: { confirmCrit: String(critId) } };
+    const ev = {
+      target: { closest: (sel) => (sel === '[data-confirm-crit]' ? btn : null) },
+      preventDefault() {},
+    };
+    for (const fn of handlers) fn(ev);
+    for (let i = 0; i < 25; i++) await new Promise((r) => setTimeout(r, 0));
+    return btn;
+  };
+
+  return { calls, band: $('#goal-completion-body').innerHTML, full: $('#goal-completion-full').innerHTML, clickConfirm };
+}
+
+// =========================================================================
+// The three criterion states
+// =========================================================================
+
+await test('the goal detail renders all three criterion states distinguishably', async () => {
+  const { band } = await render();
+  assert.match(band, /crit--done/, 'a confirmed criterion keeps its done styling');
+  assert.match(band, /crit--pending/, 'a met-but-unconfirmed criterion gets its own state');
+  // The open criterion is the one with neither modifier.
+  const items = band.match(/<li class="crit[^"]*"/g) || [];
+  assert.equal(items.length, 3, `three criteria render — got ${JSON.stringify(items)}`);
+  assert.equal(items.filter((s) => /crit--done/.test(s)).length, 1, 'exactly one done');
+  assert.equal(items.filter((s) => /crit--pending/.test(s)).length, 1, 'exactly one pending');
+  assert.equal(items.filter((s) => !/crit--(done|pending)/.test(s)).length, 1, 'exactly one plain/open');
+});
+
+await test('a pending criterion is the ONLY one offering Confirm (Metic)', async () => {
+  const { band } = await render({ rank: 'metic' });
+  const buttons = band.match(/data-confirm-crit="(\d+)"/g) || [];
+  assert.equal(buttons.length, 1, `exactly one Confirm control — got ${JSON.stringify(buttons)}`);
+  assert.match(buttons[0], new RegExp(`"${CRIT.pending.id}"`), 'it targets the pending criterion');
+});
+
+await test('an Archon also gets Confirm (Metic+ means at-or-above, not equals)', async () => {
+  const { band } = await render({ rank: 'archon' });
+  assert.match(band, /data-confirm-crit/, 'an Archon outranks Metic and keeps the control');
+});
+
+await test('a Xenos sees the pending STATE but never the Confirm control', async () => {
+  const { band } = await render({ rank: 'xenos' });
+  assert.match(band, /crit--pending/, 'the state is still visible to everyone');
+  assert.doesNotMatch(band, /data-confirm-crit/, 'the action is hidden below Metic');
+  assert.match(band, /crit__flag/, 'a read-only "Ready" flag stands in for the button');
+});
+
+await test('a thetes (below Metic) also gets no Confirm control', async () => {
+  const { band } = await render({ rank: 'thetes' });
+  assert.doesNotMatch(band, /data-confirm-crit/, 'thetes is below metic in the ladder');
+});
+
+await test('an achieved goal offers no Confirm (nothing left to confirm)', async () => {
+  const { band } = await render({ goalStatus: 'achieved' });
+  assert.doesNotMatch(band, /data-confirm-crit/, 'a closed goal is not actionable');
+});
+
+await test('an archived goal offers no Confirm', async () => {
+  const { band } = await render({ goalStatus: 'archived' });
+  assert.doesNotMatch(band, /data-confirm-crit/, 'an archived goal is not actionable');
+});
+
+// =========================================================================
+// The summary line — the /goal-review punt is gone
+// =========================================================================
+
+await test('the summary no longer sends the builder to the /goal-review CLI skill', async () => {
+  const { band } = await render();
+  assert.doesNotMatch(band, /goal-review/, 'the LLM/CLI punt is removed — this is the whole point of the task');
+});
+
+await test('the summary counts what is actually ready to confirm', async () => {
+  const { band } = await render();
+  assert.match(band, /1 criterion is met and ready to confirm/, 'singular phrasing for one pending criterion');
+});
+
+await test('with nothing pending, the summary explains when a criterion becomes confirmable', async () => {
+  const { band } = await render({ criteria: [CRIT.satisfied, CRIT.open] });
+  assert.doesNotMatch(band, /ready to confirm/, 'no false "ready" claim when nothing is pending');
+  assert.match(band, /once every task linked to it has shipped/, 'explains the precondition instead');
+});
+
+await test('an achieved goal keeps its own summary line', async () => {
+  const { band } = await render({ goalStatus: 'achieved', criteria: [CRIT.satisfied] });
+  assert.match(band, /Goal achieved/, 'achieved wording is preserved');
+});
+
+// =========================================================================
+// The action itself
+// =========================================================================
+
+await test('clicking Confirm POSTs /done-when/:id/satisfy for that criterion', async () => {
+  const { calls, clickConfirm } = await render();
+  await clickConfirm(CRIT.pending.id);
+  const posts = calls.requests.filter(([m, p]) => m === 'POST' && /\/done-when\/\d+\/satisfy$/.test(p));
+  assert.equal(posts.length, 1, `exactly one satisfy POST — got ${JSON.stringify(calls.requests)}`);
+  assert.match(posts[0][1], new RegExp(`/done-when/${CRIT.pending.id}/satisfy$`), 'targets the clicked criterion');
+});
+
+await test('confirming re-reads the goal so the row updates in place (no manual refresh)', async () => {
+  const { calls, clickConfirm } = await render();
+  const before = calls.requests.filter(([m, p]) => m === 'GET' && /\/goals\/7$/.test(p)).length;
+  await clickConfirm(CRIT.pending.id);
+  const after = calls.requests.filter(([m, p]) => m === 'GET' && /\/goals\/7$/.test(p)).length;
+  assert.ok(after > before, 'the detail is force-reloaded after a successful confirm');
+});
+
+await test('confirming the LAST criterion announces the goal auto-achieved', async () => {
+  const { calls, clickConfirm } = await render({
+    satisfyResponse: { status: 200, ok: true, data: { criterion: {}, goal_achieved: true, goal: { id: 7, status: 'achieved' } } },
+  });
+  await clickConfirm(CRIT.pending.id);
+  assert.ok(calls.toasts.some((t) => /achieved/i.test(t)), `the auto-achieve is surfaced — got ${JSON.stringify(calls.toasts)}`);
+});
+
+await test('an ordinary confirm reports success without claiming the goal is achieved', async () => {
+  const { calls, clickConfirm } = await render();
+  await clickConfirm(CRIT.pending.id);
+  assert.ok(calls.toasts.some((t) => /Criterion confirmed\.$/.test(t)), `plain confirmation — got ${JSON.stringify(calls.toasts)}`);
+  assert.ok(!calls.toasts.some((t) => /achieved/i.test(t)), 'no false auto-achieve claim');
+});
+
+await test('a double-click fires the satisfy POST only once', async () => {
+  const { calls, clickConfirm } = await render();
+  const handlersFired = clickConfirm(CRIT.pending.id);
+  await clickConfirm(CRIT.pending.id);
+  await handlersFired;
+  const posts = calls.requests.filter(([m, p]) => m === 'POST' && /\/satisfy$/.test(p));
+  assert.equal(posts.length, 1, `in-flight guard holds — got ${posts.length} POSTs`);
+});
+
+summary();

package/tests/goal_routes.mjs

@@ -141,16 +141,71 @@ await test('builder_id coercion contract: Number() accepts int + numeric string,
 });
 
 // ---- listCriteriaForGoal (db helper, deps.pool seam) ----
+// task 1002164: the projection now carries the per-criterion link counts and the
+// DERIVED pending_review flag, so the hall's goal-detail page can render the
+// third criterion state (met — ready to confirm) without a second round-trip.
+const CRIT_SQL_RE = /FROM done_when_criteria WHERE goal_id = \$1/;
+const critRow = (over = {}) => ({
+  id: 1, version_id: 'V1', criterion_id: 'c1', criterion_md: 'md', satisfied: false,
+  sort_order: 6, goal_id: 3, linked_tasks: 0, unshipped_tasks: 0, ...over,
+});
+const critPool = (rows) => fakePool((s) => (CRIT_SQL_RE.test(s) ? { rows } : null));
+
 await test('listCriteriaForGoal: SELECT by goal_id, ordered, returns rows', async () => {
-  const ROW = { id: 1, version_id: 'V1', criterion_id: 'c1', criterion_md: 'md', satisfied: false, sort_order: 6, goal_id: 3 };
-  const pool = fakePool((s) => (/FROM done_when_criteria WHERE goal_id = \$1/.test(s) ? { rows: [ROW] } : null));
+  const ROW = critRow();
+  const pool = critPool([ROW]);
   const out = await listCriteriaForGoal(3, { pool });
-  assert.deepEqual(out, [ROW]);
-  const sel = find(pool.queries, /FROM done_when_criteria WHERE goal_id = \$1/);
+  assert.deepEqual(out, [{ ...ROW, pending_review: false }]);
+  const sel = find(pool.queries, CRIT_SQL_RE);
   assert.equal(sel.params[0], 3);
   assert.match(sel.sql, /ORDER BY sort_order, id/);
 });
 
+await test('listCriteriaForGoal: pending_review true when every linked task shipped and not yet confirmed', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 2, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, true);
+});
+
+await test('listCriteriaForGoal: pending_review false once the criterion is confirmed', async () => {
+  const pool = critPool([critRow({ satisfied: true, linked_tasks: 2, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: pending_review false with NO linked tasks (vacuous truth guard)', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 0, unshipped_tasks: 0 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: pending_review false while any linked task is unshipped', async () => {
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: 3, unshipped_tasks: 1 })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, false);
+});
+
+await test('listCriteriaForGoal: counts are aggregated ONCE, not per-row correlated subqueries', async () => {
+  // Regression guard on the query SHAPE (grader finding, task 1002164). The first
+  // cut ran two correlated COUNT(*) subqueries per criterion row — 2N index
+  // lookups for N criteria. The counts must come from a single grouped pass that
+  // is itself narrowed to this goal's criteria before grouping.
+  const pool = critPool([critRow()]);
+  await listCriteriaForGoal(3, { pool });
+  const sql = String(find(pool.queries, CRIT_SQL_RE).sql).replace(/\s+/g, ' ');
+  assert.match(sql, /GROUP BY tc\.criterion_id/, 'counts come from one GROUP BY');
+  assert.match(sql, /WHERE tc\.criterion_id IN \(SELECT id FROM crit\)/, 'the aggregate is narrowed to this goal before grouping, not over all task_criteria');
+  assert.doesNotMatch(sql, /\(SELECT count\(\*\)[^)]*FROM task_criteria[^)]*WHERE tc\.criterion_id = done_when_criteria\.id/, 'no per-row correlated count subquery');
+});
+
+await test('listCriteriaForGoal: counts arrive as numbers even if the driver returns strings', async () => {
+  // node-postgres renders bigint/count as a string unless cast; the SQL casts to
+  // ::int, but the derivation must not silently flip on a string either way.
+  const pool = critPool([critRow({ satisfied: false, linked_tasks: '2', unshipped_tasks: '0' })]);
+  const [out] = await listCriteriaForGoal(3, { pool });
+  assert.equal(out.pending_review, true);
+});
+
 // ---- POST /goals/:id/tasks — request-validation schema (the bounded-authoring
 // gate's DECISION logic + abuse matrix live in tests/goal_abuse_matrix.mjs) ----
 // The EXACT schema declared in goals.js's POST /goals/:id/tasks — keep in sync.

package/tests/goal_tier.mjs

@@ -110,19 +110,28 @@ await test('getGoal: unknown id returns null (not undefined)', async () => {
 // =========================================================================
 // listGoals
 // =========================================================================
-await test('listGoals: no args binds [null, null] (both filters off)', async () => {
+await test('listGoals: no args binds [null, null, null] (all three filters off)', async () => {
   const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [GOAL_ROW] } : null));
   const out = await listGoals(undefined, { pool });
   assert.deepEqual(out, [GOAL_ROW]);
   const sel = find(pool.queries, /FROM goals/);
-  assert.deepEqual(sel.params, [null, null]);
+  // task 1002539 added an OPTIONAL limit. Postgres treats `LIMIT NULL` as unbounded,
+  // so the goal board's read is byte-for-byte unchanged in behaviour.
+  assert.deepEqual(sel.params, [null, null, null]);
   assert.match(sel.sql, /ORDER BY version_id, sort_order, created_at, id/, 'priority-first, then stable ordering');
+  assert.match(sel.sql, /LIMIT \$3::int/, 'the limit is bound, never interpolated');
 });
 
 await test('listGoals: versionId + status flow through to the bound params', async () => {
   const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [] } : null));
   await listGoals({ versionId: 'BONGOS-V1', status: 'open' }, { pool });
-  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open']);
+  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open', null]);
+});
+
+await test('listGoals: an explicit limit is bound so Postgres truncates, not JS', async () => {
+  const pool = fakePool((s) => (/FROM goals/.test(s) ? { rows: [] } : null));
+  await listGoals({ versionId: 'BONGOS-V1', status: 'open', limit: 6 }, { pool });
+  assert.deepEqual(find(pool.queries, /FROM goals/).params, ['BONGOS-V1', 'open', 6]);
 });
 
 // =========================================================================