@bongos/core 1.19.963 → 1.19.964

package/modules/lifecycle/routes/goals.js

@@ -31,6 +31,7 @@ const goalEdits = require('../goal-edits.js'); // task 1003102 — goal self-edi
 const goalCategory = require('../goal-category.js'); // task 1003275 — the ADVISORY human category (gates nothing)
 const goalRollup = require('../goal-rollup.js'); // task 1003278 — per-goal rollups computed in SQL, not in the browser
 const goalGraph = require('../goal-graph.js'); // task 1003479 — the goal graph: nodes + cross-goal edges, aggregated in SQL
+const goalForest = require('../goal-forest.js'); // task 1003480 — per-goal dependency forest
 const { suggestCriteria } = require('../criterion-suggest');
 const { classifyTaskKind, VALID_KINDS, WRITABLE_DISCIPLINES, resolveWriteDiscipline, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { validateOrRespond, parseId, LIMITS } = api;
@@ -908,14 +909,13 @@ module.exports = function buildGoalsRouter() {
       return res.fail('transfer_failed', { status: 500, message: 'internal error' });
     }
   });
-
-  // GET /goals/:id/conflicts — the server-side task-conflict view (task 1736).
-  // Replaces the hall Goals page's client-side exact-string approximation (the
-  // page feature-detects on 404): glob-aware touches[] intersection via the
-  // canonical path-match machinery, claim-aware severity, and cross-goal
-  // overlaps against other OPEN goals sharing scope_modules. Detection only —
-  // resolution is the POST below.
-  // rank: any-builder — a read; the same audience as GET /goals/:id.
+  // rank: any-builder — GET /goals/:id/dependency-forest, the per-goal task dependency drill-down (task 1003480, ADR 0227 §6.4).
+  router.get('/goals/:id/dependency-forest', auth.requireBuilder, goalForest.goalForestHandler({ getGoal: db.getGoal, parseId, log }));
+  // GET /goals/:id/conflicts — the server-side task-conflict view (task 1736). Replaces the hall Goals
+  // page's client-side exact-string approximation (the page feature-detects on 404): glob-aware touches[]
+  // intersection via the canonical path-match machinery, claim-aware severity, and cross-goal overlaps
+  // against other OPEN goals sharing scope_modules. Detection only — resolution is the POST below.
+  // rank: any-builder — a read, GET /goals/:id's audience.
   router.get('/goals/:id/conflicts', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.963",
+  "version": "1.19.964",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.963",
+      "version": "1.19.964",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.963",
+  "version": "1.19.964",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claude-materialize.js

@@ -404,15 +404,36 @@ function rebrandSettings(text, rebrand) {
 
 // Credential files are derived from where the CLI actually reads them, not rebranded from the
 // core's literals: the rebrand would also move the host-keyed store, which sits at a fixed anchor
-// whatever the brand (cli-lib sessionStoreDir, task 1003741). The shelf rule is the only layer an
-// instance gets against the repo-global stash stack, since the git-guard hook does not ship.
-function starterDeny(branding = {}) {
+// whatever the brand (cli-lib sessionStoreDir, task 1003741).
+//
+// credentialDeny is the half that may be added to a settings.json the instance already owns.
+// Every rule here stops the agent READING A SECRET, and nothing an instance legitimately does
+// requires reading its own key or session token from inside an agent session — which is what
+// makes appending one provably safe (ADR 0326: a deny rule is monotonic in the safe direction).
+function credentialDeny(branding = {}) {
   const dirs = [...new Set([effConfigDir(branding), ...ic.LEGACY_DIRS])];
   const credentialFiles = ['env', ...ic.SESSION_FILENAMES];
   return [
     ...STARTER_DENY_SECRETS,
     ...dirs.flatMap((dir) => credentialFiles.map((file) => `Read(~/.config/${dir}/${file})`)),
     SESSION_STORE_DENY,
+  ];
+}
+
+// starterDeny — what a FRESH instance gets: the credential half plus the shelf rules, which are
+// the only layer an instance has against the repo-global stash stack since the git-guard hook is
+// topology and does not ship.
+//
+// The shelf rules are starter-only, and deliberately NOT in the top-up (task 1004158, amending
+// ADR 0326, which named this exclusion as the remedy if the rule ever bit). They guard a WORKFLOW
+// rather than a secret, so the monotonicity argument that licenses the top-up does not reach them:
+// with no provenance by design, and deny beating allow in Claude Code's permission order, an
+// instance whose builders used the shelf as a set-aside could not re-enable it from its own
+// settings.json afterwards. A fresh instance is different in kind — there the rule is a visible
+// default present from the first commit, editable before any workflow has grown around it.
+function starterDeny(branding = {}) {
+  return [
+    ...credentialDeny(branding),
     ...STARTER_SHELL_TOOLS.map((tool) => `${tool}(git stash:*)`),
   ];
 }
@@ -453,7 +474,7 @@ function topUpStarterDeny(existingText, wanted) {
 // package-only install. Permissions ONLY: no hooks (they are topology), no env.
 function renderStarterSettings(branding = {}) {
   return `${JSON.stringify({
-    _doc: 'Starter written by scripts/gds/claude-materialize.js (tasks 1003962, 1003966). Permissions only — the blessed Bongos commands, mirroring the core repo\'s own allow-list (ADR 0104), and the deny rules that keep the local agent from reading keys and session tokens. An allow-rule lets the local agent RUN a command; it grants no authority, which the server decides per request from your live rank (ADR 0016). Yours to edit: a later materialize never removes or rewrites a rule you wrote. It will ADD a deny rule this starter has gained since (task 1004156) and name it in the run output — additive only, so it can never widen what the local agent may do.',
+    _doc: 'Starter written by scripts/gds/claude-materialize.js (tasks 1003962, 1003966). Permissions only — the blessed Bongos commands, mirroring the core repo\'s own allow-list (ADR 0104), and the deny rules that keep the local agent from reading keys and session tokens. An allow-rule lets the local agent RUN a command; it grants no authority, which the server decides per request from your live rank (ADR 0016). Yours to edit: a later materialize never removes or rewrites a rule you wrote. It will ADD a CREDENTIAL deny rule this starter has gained since (task 1004156) and name it in the run output — additive only, so it can never widen what the local agent may do. Only that half is topped up: the shell rules below guard a workflow rather than a secret, so once this file exists they are yours alone and an upgrade will neither add nor remove one (task 1004158).',
     permissions: { allow: STARTER_ALLOW, deny: starterDeny(branding) },
   }, null, 2)}\n`;
 }
@@ -749,11 +770,13 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     if (fs.existsSync(settingsDest)) {
       // The instance owns this file — but a deny rule the starter has gained since is ADDED to
       // it rather than withheld forever (task 1004156). Nothing of theirs is removed or changed.
+      // Only the CREDENTIAL half is offered: the starter's shelf rules guard a workflow, not a
+      // secret, and are starter-only (task 1004158).
       // The read is guarded: existsSync passing does not mean readable (a directory at that path,
       // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
       // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
       let topUp;
-      try { topUp = topUpStarterDeny(fs.readFileSync(settingsDest, 'utf8'), starterDeny(toBranding)); }
+      try { topUp = topUpStarterDeny(fs.readFileSync(settingsDest, 'utf8'), credentialDeny(toBranding)); }
       catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
       if (topUp.text) {
         if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
@@ -779,7 +802,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
       } else {
         summary.skippedFiles.push('settings.json');
-        log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every starter deny rule).');
+        log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
       }
     } else {
       if (!dryRun) {

package/scripts/hall-preview/server.js

@@ -101,6 +101,7 @@ let liveWhy = null;
 // paths fall back to the generic names below so one fixture serves any id.
 const FIXTURE_FALLBACKS = [
   [/^goals\/\d+\/conflicts$/, 'goals__conflicts'],
+  [/^goals\/\d+\/dependency-forest$/, 'goals__dependency-forest'],
   [/^goals\/\d+\/requests$/, 'goals__requests'],
   [/^goals\/\d+$/, 'goals__detail'],
   [/^tasks\/\d+$/, 'tasks__detail'],

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.963'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.964'; // 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');

package/tests/claude_materialize.mjs

@@ -895,6 +895,12 @@ t('a checkout-materialized instance keeps the session-store rule at its fixed an
 // safety argument — a deny rule can only narrow what the agent may do, so appending one cannot
 // widen this instance's permissions. ADR 0121 §2 already licenses "merge OR leave-and-report"
 // for a pre-existing file; this implements the merge half for the one shape that is provably safe.
+// task 1004158 — the top-up asks for the CREDENTIAL half only. Derived here by excluding the
+// shell-tool rules rather than read back from the implementation's own list, so this states the
+// contract independently instead of agreeing with whatever the code happens to do.
+const topUpDenyFor = (branding) => starterDenyFor(branding).filter((r) => !/^(?:Bash|PowerShell)\(/.test(r));
+const shelfRules = (branding) => starterDenyFor(branding).filter((r) => /^(?:Bash|PowerShell)\(/.test(r));
+
 const topUpFixture = (settings) => {
   const core = mkdtempSync(join(tmpdir(), 'w3-topup-core-'));
   const inst = mkdtempSync(join(tmpdir(), 'w3-topup-inst-'));
@@ -912,8 +918,8 @@ t('an instance still on the allow-only starter GAINS the deny rules on its next
   const f = topUpFixture({ _doc: 'the task-1003962 starter', permissions: { allow: m.STARTER_ALLOW } });
   const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
   const after = JSON.parse(f.read());
-  assert.deepEqual(after.permissions.deny, starterDenyFor({ configDir: 'acme' }),
-    "every starter deny rule, pointed at THIS instance's config dir");
+  assert.deepEqual(after.permissions.deny, topUpDenyFor({ configDir: 'acme' }),
+    "every credential deny rule, pointed at THIS instance's config dir — and nothing else");
   assert.deepEqual(after.permissions.allow, m.STARTER_ALLOW, 'its allow half is untouched');
   assert.equal(after._doc, 'the task-1003962 starter', 'and every other key it carried survives');
   assert.deepEqual(res.settingsDenyAdded, after.permissions.deny, 'the run names each rule it added');
@@ -939,12 +945,50 @@ t("an owner-edited settings.json keeps every rule of its own and only gains what
   assert.equal(after.permissions.deny.filter((r) => r === 'Read(**/*.pem)').length, 1,
     'a rule they already had is not added a second time');
   assert.ok(!res.settingsDenyAdded.includes('Read(**/*.pem)'), 'nor reported as added');
-  for (const rule of starterDenyFor({ configDir: 'acme' })) {
+  for (const rule of topUpDenyFor({ configDir: 'acme' })) {
     assert.ok(after.permissions.deny.includes(rule), `missing ${rule}`);
   }
   f.cleanup();
 });
 
+t('the shelf rules are starter-only — the TOP-UP never adds them to a file the instance owns', () => {
+  // Scoped to the top-up (the package-only branch, which is the one `bongos upgrade` always takes:
+  // the published core excludes .claude/settings.json). The CHECKOUT branch still overwrites an
+  // existing instance settings.json wholesale, shelf rules included — that predates this change
+  // and is not reachable from an upgrade, so it is out of scope here rather than disproved.
+  // task 1004158, amending ADR 0326. The top-up's licence is that a deny rule is monotonic in the
+  // safe direction, and that argument covers a rule about reading a SECRET. The shelf rules guard
+  // a WORKFLOW: an instance whose builders used the repo-global shelf as a set-aside would find it
+  // blocked after an upgrade and — no provenance by design, deny beating allow — could not re-enable
+  // it from its own settings.json. So the core stops handing it out to instances that already exist.
+  const brand = { configDir: 'acme' };
+  assert.deepEqual(shelfRules(brand), ['Bash(git stash:*)', 'PowerShell(git stash:*)'],
+    'the starter still carries both shelf rules — this change withholds them from the TOP-UP, not the starter');
+  const f = topUpFixture({ permissions: { allow: m.STARTER_ALLOW } });
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  const deny = JSON.parse(f.read()).permissions.deny;
+  for (const rule of shelfRules(brand)) {
+    assert.ok(!res.settingsDenyAdded.includes(rule), `${rule} must not be reported as added`);
+    assert.ok(!deny.includes(rule), `${rule} must not be written into a settings.json the instance owns`);
+  }
+  assert.ok(deny.includes('Read(~/.config/acme/bongos-session.json)'),
+    'while the credential half still lands — withholding the shelf rules must not withhold the secrets half');
+  f.cleanup();
+});
+
+t('an instance that already has a shelf rule keeps it — this withholds, it never removes', () => {
+  // The top-up only ever appends, so an instance that took the shelf rules (from the starter, from
+  // an upgrade before task 1004158, or by hand) is unaffected. Live cloudbongos.com is in exactly
+  // this position after its 0-to-20 run: lifting them there is a hand-edit, not something an
+  // upgrade will undo.
+  const f = topUpFixture({ permissions: { allow: [], deny: ['Bash(git stash:*)'] } });
+  m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  const deny = JSON.parse(f.read()).permissions.deny;
+  assert.equal(deny[0], 'Bash(git stash:*)', 'the rule they already had keeps its place at the front');
+  assert.ok(!deny.includes('PowerShell(git stash:*)'), 'and its twin is still not volunteered');
+  f.cleanup();
+});
+
 t('the top-up is idempotent — a second materialize changes nothing', () => {
   const f = topUpFixture({ permissions: { allow: m.STARTER_ALLOW } });
   m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
@@ -961,7 +1005,7 @@ t('a dry run names the missing deny rules and writes nothing', () => {
   const before = f.read();
   const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: true });
   assert.equal(f.read(), before, 'a dry run writes nothing');
-  assert.deepEqual(res.settingsDenyAdded, starterDenyFor({ configDir: 'acme' }),
+  assert.deepEqual(res.settingsDenyAdded, topUpDenyFor({ configDir: 'acme' }),
     'but it still names what a real run would add');
   f.cleanup();
 });

package/tests/goal_category_ui.mjs

@@ -23,6 +23,7 @@ const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
 const SRC = read('modules/hall-ui/public/goals-page.js');
 const TASK_LIB_SRC = read('modules/hall-ui/public/task-lib.js');
 const GOALS_LIB_SRC = read('modules/hall-ui/public/goals-lib.js');
+const GOAL_FOREST_RENDER_SRC = read('modules/hall-ui/public/goal-forest-render.js');
 const GOALS_RENDER_SRC = read('modules/hall-ui/public/goals-render.js');
 const DOM_UTILS_SRC = read('modules/hall-ui/public/dom-utils.js');
 const WORK_SRC = read('modules/hall-ui/public/work.js');
@@ -124,6 +125,7 @@ async function renderList() {
   windowObj.OTB.toast = () => {};
   vm.runInContext(TASK_LIB_SRC, sandbox, { filename: 'task-lib.js' });
   vm.runInContext(GOALS_LIB_SRC, sandbox, { filename: 'goals-lib.js' });
+  vm.runInContext(GOAL_FOREST_RENDER_SRC, sandbox, { filename: 'goal-forest-render.js' });
   vm.runInContext(GOALS_RENDER_SRC, sandbox, { filename: 'goals-render.js' });
   vm.runInContext(SRC, sandbox, { filename: 'goals-page.js' });
   for (let i = 0; i < 30; i++) await new Promise((r) => setTimeout(r, 0));

package/tests/goal_criterion_confirm_ui.mjs

@@ -44,6 +44,7 @@ const GOALS_LIB_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/go
 // (window.OTBGoalsRender) — the second half of the same carve. Run the REAL file
 // too, for the same reason: this is the only test that executes either board, so
 // stubbing the renderers would let them rot unwatched.
+const GOAL_FOREST_RENDER_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/goal-forest-render.js'), 'utf8');
 const GOALS_RENDER_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/goals-render.js'), 'utf8');
 
 const { test, summary } = makeRunner();
@@ -154,6 +155,7 @@ async function render({ rank = 'metic', goalStatus = 'open', criteria = Object.v
   vm.createContext(sandbox);
   vm.runInContext(TASK_LIB_SRC, sandbox, { filename: 'task-lib.js' });
   vm.runInContext(GOALS_LIB_SRC, sandbox, { filename: 'goals-lib.js' });
+  vm.runInContext(GOAL_FOREST_RENDER_SRC, sandbox, { filename: 'goal-forest-render.js' });
   vm.runInContext(GOALS_RENDER_SRC, sandbox, { filename: 'goals-render.js' });
   vm.runInContext(SRC, sandbox, { filename: 'goals-page.js' });
 

package/tests/goal_forest.mjs

@@ -0,0 +1,160 @@
+// tests/goal_forest.mjs — GET /goals/:id/dependency-forest, the per-goal task
+// drill-down (task 1003480, goal 1000089, ADR 0227 §6 item 4 + §10.5).
+//
+// NOT A ZOOM OF THE GOAL MAP. This pins the filter that keeps the two views
+// from overlapping or double-drawing anything: an edge counts here ONLY when
+// BOTH its tasks sit in the goal being opened — the exact opposite of
+// goal-graph.js's cross-goal filter — and a goal with no such edge returns an
+// empty forest rather than an error, so the page can say so plainly.
+//
+// DB-free: the pure shaper runs directly, the SQL against a recording fake
+// pool, the handler against stub collaborators.
+//
+// Run:  node tests/goal_forest.mjs
+process.env.NODE_ENV = 'test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { shapeForest, goalForestRows, goalForest, goalForestHandler } = require(path.join(ROOT, 'modules/lifecycle/goal-forest.js'));
+const GOALS_ROUTE = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/goals.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const t = (id, extra = {}) => ({ id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
+const e = (from, to) => ({ from_task_id: String(from), to_task_id: String(to) });
+
+// ---- shapeForest ----------------------------------------------------------
+
+await test('an edge means "from waits on to"; both endpoints become nodes with the right degree', () => {
+  const out = shapeForest({ tasks: [t(1), t(2), t(3)], edges: [e(1, 2), e(1, 3)] });
+  const by = Object.fromEntries(out.nodes.map((n) => [n.task_id, n]));
+  assert.deepEqual(out.edges, [{ from: '1', to: '2' }, { from: '1', to: '3' }]);
+  assert.equal(by['1'].depends_on, 2);
+  assert.equal(by['2'].depended_on_by, 1);
+  assert.equal(by['2'].depends_on, 0);
+});
+
+await test('a task with NO edge is never a node — the omission is the finding, not a gap (ADR 0227 §3)', () => {
+  const out = shapeForest({ tasks: [t(1), t(2), t(3)], edges: [e(1, 2)] });
+  assert.deepEqual(out.nodes.map((n) => n.task_id).sort(), ['1', '2']);
+  assert.equal(out.counts.tasks, 2);
+});
+
+await test('a self edge and a duplicate are dropped; an edge to a task not in the fetched set is dropped, not drawn to nowhere', () => {
+  const out = shapeForest({ tasks: [t(1), t(2)], edges: [e(2, 2), e(1, 2), e(1, 2), e(1, 99)] });
+  assert.deepEqual(out.edges, [{ from: '1', to: '2' }]);
+});
+
+await test('a task whose only edge was dropped (a stale endpoint) does not appear as a lone edge-less node', () => {
+  const out = shapeForest({ tasks: [t(1), t(2), t(3)], edges: [e(1, 99), e(2, 3)] });
+  assert.deepEqual(out.nodes.map((n) => n.task_id).sort(), ['2', '3']);
+});
+
+await test('priority is coerced to a number or null; status/title pass through verbatim', () => {
+  const out = shapeForest({ tasks: [t(1, { priority: '2' }), t(2, { priority: null, status: 'blocked', title: 'Blocked one' })], edges: [e(1, 2)] });
+  const by = Object.fromEntries(out.nodes.map((n) => [n.task_id, n]));
+  assert.strictEqual(by['1'].priority, 2);
+  assert.strictEqual(by['2'].priority, null);
+  assert.equal(by['2'].status, 'blocked');
+  assert.equal(by['2'].title, 'Blocked one');
+});
+
+await test('an empty corpus is a valid, empty forest', () => {
+  assert.deepEqual(shapeForest({}), { nodes: [], edges: [], counts: { tasks: 0, edges: 0 } });
+});
+
+// ---- the SQL, against a recording pool ----------------------------------------
+
+function fakePool(edgeRows = [], taskRows = []) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      return { rows: /FROM tasks\s*$|WHERE id = ANY/.test(sql) ? taskRows : edgeRows };
+    },
+  };
+}
+
+await test('the edge query is bound to ONE goal id, on BOTH endpoints — the opposite of the goal map\'s cross-goal filter', async () => {
+  const pool = fakePool();
+  await goalForestRows(42, { pool });
+  const [q] = pool.calls;
+  assert.deepEqual(q.params, [42]);
+  assert.match(q.sql, /ft\.goal_id = \$1 AND tt\.goal_id = \$1/);
+  assert.match(q.sql, /d\.from_kind = 'task'/);
+  assert.match(q.sql, /d\.to_kind\s+= 'task'/);
+});
+
+await test('no edges at all short-circuits — the task-facts query never runs', async () => {
+  const pool = fakePool([]);
+  const out = await goalForestRows(1, { pool });
+  assert.equal(pool.calls.length, 1, 'only the edge query ran');
+  assert.deepEqual(out, { edges: [], tasks: [] });
+});
+
+await test('the task-facts query is scoped to exactly the ids the edges named — never the goal\'s whole task list', async () => {
+  const pool = fakePool([e(1, 2), e(2, 3)], [t(1), t(2), t(3)]);
+  await goalForestRows(1, { pool });
+  const factsQ = pool.calls[1];
+  assert.deepEqual(factsQ.params[0].sort((a, b) => a - b), [1, 2, 3]);
+  assert.match(factsQ.sql, /WHERE id = ANY/);
+});
+
+await test('an end-to-end fake read produces the shaped forest', async () => {
+  const pool = fakePool([e(1, 2)], [t(1), t(2)]);
+  const out = await goalForest(1, { pool });
+  assert.equal(out.counts.tasks, 2);
+  assert.deepEqual(out.edges, [{ from: '1', to: '2' }]);
+});
+
+// ---- the handler ---------------------------------------------------------------
+
+function run(handler, req) {
+  const res = { body: null, failed: null, statusCode: null, json(b) { this.body = b; return this; }, fail(code, o) { this.failed = { code, o }; return this; } };
+  return handler(req, res).then(() => res);
+}
+const parseId = (req) => { const n = Number(req.params.id); return Number.isInteger(n) && n > 0 ? n : null; };
+
+await test('a missing goal is a 404, and the forest is never read', async () => {
+  let readCalled = false;
+  const h = goalForestHandler({ getGoal: async () => null, read: async () => { readCalled = true; return {}; }, parseId, log: { error() {} } });
+  const res = await run(h, { params: { id: '5' } });
+  assert.equal(res.failed.code, 'goal_not_found');
+  assert.equal(res.failed.o, 404);
+  assert.equal(readCalled, false);
+});
+
+await test('a real goal returns the forest with the goal id attached', async () => {
+  const h = goalForestHandler({ getGoal: async () => ({ id: 5 }), read: async () => ({ nodes: [], edges: [], counts: { tasks: 0, edges: 0 } }), parseId, log: { error() {} } });
+  const res = await run(h, { params: { id: '5' } });
+  assert.equal(res.body.ok, true);
+  assert.equal(res.body.goal_id, 5);
+  assert.deepEqual(res.body.nodes, []);
+});
+
+await test('a failed read is a named 500, never a stack trace', async () => {
+  const errors = [];
+  const h = goalForestHandler({ getGoal: async () => ({ id: 1 }), read: async () => { throw new Error('db down'); }, parseId, log: { error: (...a) => errors.push(a) } });
+  const res = await run(h, { params: { id: '1' } });
+  assert.equal(res.failed.code, 'forest_failed');
+  assert.equal(res.failed.o.status, 500);
+  assert.equal(errors.length, 1);
+});
+
+// ---- mounting --------------------------------------------------------------------
+
+await test('/goals/:id/dependency-forest is mounted for any signed-in builder', () => {
+  const at = GOALS_ROUTE.indexOf("router.get('/goals/:id/dependency-forest'");
+  assert.ok(at > -1, 'the route is registered');
+  assert.match(GOALS_ROUTE.slice(at, at + 200), /auth\.requireBuilder/);
+  assert.match(GOALS_ROUTE.slice(Math.max(0, at - 260), at), /rank: any-builder/, 'the route-rank scanner needs its declaration');
+});
+
+summary();

package/tests/goal_forest_lib.mjs

@@ -0,0 +1,153 @@
+// tests/goal_forest_lib.mjs — the per-goal dependency forest's model and
+// layout, EXECUTED (task 1003480, goal 1000089, ADR 0227 §6 item 4 + §10.5).
+//
+// goal-forest-lib.js is pure, so this runs the real code over synthetic
+// corpora, including one at the measured worst case (§10.5: the biggest single
+// goal's forest is 127 tasks). What is pinned: no task is drawn twice or on
+// top of another, a task always sits right of what it depends on, two
+// independent chains in one goal share the picture without overlapping, and
+// every fact in the picture is also a table row.
+//
+// Run:  node tests/goal_forest_lib.mjs
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const L = require(path.join(ROOT, 'modules/hall-ui/public/goal-forest-lib.js'));
+
+const { test, summary } = makeRunner();
+
+const node = (id, extra = {}) => ({ task_id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
+const edge = (from, to) => ({ from: String(from), to: String(to) });
+
+function overlaps(a, b) {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+function assertSound(a, lay, label) {
+  const ids = lay.nodes.map((n) => n.id);
+  assert.equal(new Set(ids).size, ids.length, `${label}: no task drawn twice`);
+  assert.equal(ids.length, a.order.length, `${label}: every analysed node is drawn — none are edge-less by construction`);
+  for (let i = 0; i < lay.nodes.length; i++) {
+    for (let j = i + 1; j < lay.nodes.length; j++) {
+      assert.equal(overlaps(lay.nodes[i], lay.nodes[j]), false, `${label}: ${lay.nodes[i].id} overlaps ${lay.nodes[j].id}`);
+    }
+  }
+  for (const n of lay.nodes) {
+    assert.ok(n.x >= 0 && n.y >= 0, `${label}: ${n.id} is on the canvas`);
+    assert.ok(n.x + n.w <= lay.width && n.y + n.h <= lay.height, `${label}: ${n.id} fits inside the svg's own size`);
+  }
+}
+
+// ---- structure -----------------------------------------------------------------
+
+await test('an edge means "from waits on to", and each node counts its own degree', () => {
+  const a = L.analyse({ nodes: [node(1), node(2), node(3)], edges: [edge(1, 2), edge(1, 3)] });
+  assert.equal(a.waits['1'].length, 2);
+  assert.equal(a.needed['2'].length, 1);
+});
+
+await test('a self edge, a duplicate, and an edge to an unknown task are all ignored', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(1, 99), edge(2, 2), edge(1, 2), edge(1, 2)] });
+  assert.equal(a.edges.length, 1);
+});
+
+await test('chains are found, largest first — two disjoint pairs are two chains of size 2, not one', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6, 7].map((i) => node(i)), edges: [edge(1, 2), edge(3, 4), edge(5, 6), edge(6, 7)] });
+  assert.deepEqual(a.chains.map((c) => c.length), [3, 2, 2]);
+});
+
+// ---- layout --------------------------------------------------------------------
+
+await test('a task sits to the RIGHT of every task it depends on', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(4, 2)] });
+  const lay = L.layout(a);
+  const x = Object.fromEntries(lay.nodes.map((n) => [n.id, n.x]));
+  for (const e of a.edges) assert.ok(x[e.to] < x[e.from], `${e.from} waits on ${e.to}, must be right of it`);
+});
+
+await test('two independent chains in one goal share the picture with no overlap', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(1, 2), edge(3, 4)] });
+  const lay = L.layout(a);
+  assertSound(a, lay, 'two chains');
+});
+
+await test('a would-be cycle terminates and still places every task', () => {
+  const a = L.analyse({ nodes: [1, 2, 3].map((i) => node(i)), edges: [edge(1, 2), edge(2, 1), edge(3, 1)] });
+  const lay = L.layout(a);
+  assert.equal(lay.nodes.length, 3);
+  assertSound(a, lay, 'cycle');
+});
+
+await test('the same data always gives the same picture', () => {
+  const p = { nodes: [1, 2, 3, 4, 5].map((i) => node(i)), edges: [edge(2, 1), edge(3, 1), edge(4, 2), edge(5, 2)] };
+  assert.deepEqual(L.layout(L.analyse(p)), L.layout(L.analyse(p)));
+});
+
+await test('an edge path starts at the dependency\'s right edge and ends at the dependent\'s left edge', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(2, 1)] });
+  const lay = L.layout(a);
+  const by = Object.fromEntries(lay.nodes.map((n) => [n.id, n]));
+  const [e] = lay.edges;
+  assert.ok(e.d.startsWith(`M${by['1'].x + lay.nodeW} ${by['1'].y + lay.nodeH / 2}`));
+  assert.ok(e.d.endsWith(`${by['2'].x} ${by['2'].y + lay.nodeH / 2}`));
+});
+
+await test('THE MEASURED WORST CASE: a 127-task single goal forest lays out soundly and fast (ADR 0227 §10.5)', () => {
+  let seed = 20260921;
+  const rnd = () => { seed = (seed * 1664525 + 1013904223) % 4294967296; return seed / 4294967296; };
+  const ids = Array.from({ length: 127 }, (_, i) => i + 1);
+  const nodes = ids.map((i) => node(i));
+  const edges = [];
+  for (let i = 1; i < ids.length; i++) edges.push(edge(ids[i], ids[Math.floor(rnd() * i)]));
+  const a = L.analyse({ nodes, edges });
+  const t0 = Date.now();
+  const lay = L.layout(a);
+  const ms = Date.now() - t0;
+  assertSound(a, lay, 'worst case');
+  assert.ok(ms < 500, `laid out in ${ms}ms`);
+});
+
+// ---- table + description ---------------------------------------------------------
+
+await test('the table has one row per task and carries both directions by name', () => {
+  const a = L.analyse({ nodes: [node(1, { title: 'Base' }), node(2, { title: 'Top' })], edges: [edge(2, 1)] });
+  const rows = L.tableRows(a);
+  const base = rows.find((r) => r.id === '1');
+  const top = rows.find((r) => r.id === '2');
+  assert.deepEqual(top.waits, [{ id: '1', title: 'Base' }]);
+  assert.deepEqual(base.needed, [{ id: '2', title: 'Top' }]);
+});
+
+await test('priority renders as P1..P5, or an em dash for null', () => {
+  const a = L.analyse({ nodes: [node(1, { priority: 1 }), node(2, { priority: null })], edges: [edge(1, 2)] });
+  const rows = L.tableRows(a);
+  assert.equal(rows.find((r) => r.id === '1').priority, 'P1');
+  assert.equal(rows.find((r) => r.id === '2').priority, '—');
+});
+
+await test('a lone pair is labelled plainly, a real chain is labelled and counted', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(1, 2), edge(2, 3), edge(2, 4)] });
+  const rows = L.tableRows(a);
+  assert.match(rows[0].chainLabel, /^Chain 1 · 4 tasks$/);
+});
+
+await test('describe states the numbers plainly, and an empty forest says so', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(1, 2)] });
+  assert.match(L.describe(a), /^2 tasks in this goal have a dependency.*in 1 chain\.$/);
+  assert.equal(L.describe(L.analyse({})), 'No task in this goal depends on another task in this goal.');
+});
+
+// ---- purity -----------------------------------------------------------------------
+
+await test('the lib is pure: no DOM, no fetch, no cross-goal input', () => {
+  const fs = require('fs');
+  const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/goal-forest-lib.js'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  assert.equal(/\bdocument\b|\bfetch\b|\bwindow\b|XMLHttpRequest/.test(src.replace(/root\.OTBGoalForestLib/, '')), false);
+  assert.equal(/goal_id|category/i.test(src), false, 'this file knows nothing about goals or categories — that is the map, not the forest');
+});
+
+summary();