@bongos/core 1.19.963 → 1.19.965

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/modules/provisioning/starter-bundles.js

@@ -100,16 +100,37 @@ const RETIRED_MODULES = Object.freeze(['dev-box']);
 // tests/provisioning_starter_bundles.mjs be the link back to the manifests — it
 // fails the build when the declared set drifts from the on-disk `default: false`
 // modules, so a new opt-in module cannot ship without owner-facing copy.
+// `aliases` are search words only — never rendered (the same standing the `key`
+// already has, ADR 0244 §3). They exist because the picker's search is a literal
+// substring filter over words we chose, so a module is findable only under the
+// vocabulary its own copy happens to use: typing "chat" found nothing, which is
+// the gap ADR 0244 named and deferred to an embeddings layer. Task 1003500 closed
+// it here instead — for a catalog this size a declared word list is more accurate
+// than a model, costs nothing to run, and is fixable by whoever reads the
+// complaint (ADR 0244 §3 amendment).
+//
+// This fixes the WORD, not the SENTENCE. ADR 0244 §3 illustrated the gap with
+// "somewhere for people to chat", and that query still finds nothing: the matcher
+// ANDs every term, so `somewhere` and `people` must appear too. Making a sentence
+// work means OR-then-rank, which §3 and §5 reject outright. Aliases raise the
+// chance an owner's ONE word lands; they do not make the filter understand a
+// phrase, and nothing here should imply they do.
+//
+// Write the LONGEST form an owner might type: the filter is substring-based, so
+// 'chatroom' in the haystack already answers "chat". A word the label or summary
+// already contains does not belong here — it is findable without it.
 const OPTIONAL_MODULES = Object.freeze([
   Object.freeze({
     key: 'agents',
     label: 'Extra agents',
     summary: 'More AI agents alongside the ones every project gets, for reading, research and review.',
+    aliases: Object.freeze(['bots', 'assistants', 'automation', 'llm', 'helpers']),
   }),
   Object.freeze({
     key: 'discord',
     label: 'Discord',
     summary: 'A Discord server that carries your build news, and lets people send ideas and bug reports back.',
+    aliases: Object.freeze(['chatroom', 'talk', 'messaging', 'community', 'announcements', 'notifications']),
   }),
 ]);
 
@@ -241,9 +262,12 @@ function allStarterBundles() {
 }
 
 // The opt-in catalog, as the picker reads it — fresh copies, so a caller may
-// sort or splice without corrupting the frozen declaration.
+// sort or splice without corrupting the frozen declaration. `aliases` is copied
+// too: a spread is shallow, so the old one-level copy handed every caller the
+// same FROZEN array, and the first one to take the liberty this comment offers
+// would have got a TypeError under strict mode rather than a private copy.
 function optionalModules() {
-  return OPTIONAL_MODULES.map((m) => ({ ...m }));
+  return OPTIONAL_MODULES.map((m) => (m.aliases ? { ...m, aliases: [...m.aliases] } : { ...m }));
 }
 
 // Apply the team-shape rules to one type's opt-in bundle. Returns the adjusted

package/modules/public-landing/public/projects.html

@@ -3528,12 +3528,25 @@ summary{min-height:24px;padding:3px 0;}
       return String(q == null ? '' : q).toLowerCase().split(/\s+/).filter(function (t) { return t.length > 0; });
     }
     /* Does one catalog row answer this search? Every term must appear somewhere in
-       the row's own words — its name, its one-line summary, or its key — as a
-       substring, case-insensitively. AND across terms, so adding a word narrows;
-       substring, so a half-typed word still finds its module. */
+       the row's own words — its name, its one-line summary, its key, or its
+       declared search aliases — as a substring, case-insensitively. AND across
+       terms, so adding a word narrows; substring, so a half-typed word still
+       finds its module.
+
+       The aliases are why typing "chat" now finds Discord: the row is findable
+       under words an owner would use, not only the ones its own copy happens to
+       use. They are declared in starter-bundles.js and never rendered — the same
+       standing the key already has (ADR 0244 §3, amended by task 1003500).
+
+       Still literal, and still AND across terms, so a SENTENCE still finds
+       nothing — "somewhere for people to chat" fails on `somewhere` and `people`
+       however many aliases the row carries. That is the honest limit of this
+       filter, not a bug in the list. */
     function moduleMatches(mod, terms) {
       if (!terms.length) return true;
-      var hay = (((mod && mod.label) || '') + ' ' + ((mod && mod.summary) || '') + ' ' + ((mod && mod.key) || '')).toLowerCase();
+      var aliases = (mod && mod.aliases) || [];
+      var hay = (((mod && mod.label) || '') + ' ' + ((mod && mod.summary) || '') + ' ' + ((mod && mod.key) || '')
+        + ' ' + (aliases.join ? aliases.join(' ') : '')).toLowerCase();
       for (var i = 0; i < terms.length; i++) if (hay.indexOf(terms[i]) === -1) return false;
       return true;
     }

package/modules/ui-design/kit/serve.js

@@ -128,8 +128,8 @@ const STARTER_BUNDLES_FIXTURE = {
     { type: 'not-sure', bundle: [] },
   ],
   optional: [
-    { key: 'agents', label: 'Extra agents', summary: 'More AI agents alongside the ones every project gets, for reading, research and review.' },
-    { key: 'discord', label: 'Discord', summary: 'A Discord server that carries your build news, and lets people send ideas and bug reports back.' },
+    { key: 'agents', label: 'Extra agents', summary: 'More AI agents alongside the ones every project gets, for reading, research and review.', aliases: ['bots', 'assistants', 'automation', 'llm', 'helpers'] },
+    { key: 'discord', label: 'Discord', summary: 'A Discord server that carries your build news, and lets people send ideas and bug reports back.', aliases: ['chatroom', 'talk', 'messaging', 'community', 'announcements', 'notifications'] },
   ],
 };
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.963",
+  "version": "1.19.965",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.963",
+      "version": "1.19.965",
       "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.965",
   "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.965'; // 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();