@bongos/core 1.19.962 → 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.962",
+  "version": "1.19.964",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.962",
+      "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.962",
+  "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,24 +404,77 @@ 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:*)`),
   ];
 }
 
+// topUpStarterDeny — the deny rules an instance's OWN settings.json is missing, added to it
+// (task 1004156). The starter is only ever written when the file is ABSENT, so every instance
+// that took the allow-only starter from task 1003962 keeps it forever and its local agent can
+// still read .env files, keys and session tokens. ADDING is the whole safety argument: a deny
+// rule can only ever narrow what the agent may do, so appending one cannot widen this instance's
+// permissions — which is why the owner's call (task 1004156) was "add them, and say which".
+// "Never clobber" is unchanged in the sense that matters: nothing the instance wrote is removed
+// or rewritten. Returns { text, added, reason }; `text` is null when nothing should be written.
+// `reason` is the STRUCTURED signal that the file could not be CHECKED — null means "healthy",
+// so callers branch on its presence rather than on the wording of a message. An unparseable or
+// unexpectedly-shaped file is LEFT ALONE and reported, the posture task 1004023 took for a
+// settings.json that will not parse: a half-understood rewrite of a permissions file is worse
+// than the gap it closes. Note the write re-emits the whole document at 2-space JSON, so an
+// instance indented some other way sees a whole-file diff — the RULES are still append-only,
+// which is what the safety argument rests on, and the run output says so.
+function topUpStarterDeny(existingText, wanted) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const deny = perms.deny === undefined ? [] : perms.deny;
+  if (!Array.isArray(deny)) return cannotCheck('its "permissions.deny" is not an array');
+  const have = new Set(deny);
+  const added = wanted.filter((rule) => !have.has(rule));
+  if (!added.length) return { text: null, added: [], reason: null }; // healthy: every rule already there
+  const next = { ...doc, permissions: { ...perms, deny: [...deny, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
 // The starter an instance gets when the core root carries no settings.json — a
 // 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 clobbers this file.',
+    _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`;
 }
@@ -493,11 +546,14 @@ function transformSettings(srcPath) {
 // Materialize the .claude/ surface from `coreRoot` into `instanceDir`. Returns a summary.
 // `overwrite` defaults true (greenfield init / upgrade — unchanged). `overwrite: false`
 // is the `bongos init --adopt` layering path (ADR 0121): every pre-existing .claude/
-// file is LEFT untouched and recorded in `summary.skippedFiles` (never clobbered).
+// file is LEFT untouched and recorded in `summary.skippedFiles` (never clobbered). The ONE
+// exception is settings.json in a package-only install, which GAINS any starter deny rule it is
+// missing and reports them in `summary.settingsDenyAdded` (task 1004156) — additive only, so
+// nothing the instance wrote is removed or rewritten.
 const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
 
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, settingsUnparsed: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
+  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, settingsUnparsed: false, settingsDenyAdded: [], settingsDenyUncheckable: null, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
   // Every instance-relative path this run WROTE or REMOVED (task 1003957). `bongos upgrade`
   // hands these to persistPin as artifactPaths, exactly as task 1003926 already does for
   // regenerateApiArtifacts' output: committing only the pin left the materialized files dirty,
@@ -712,8 +768,42 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     // permissions owns them, and a later materialize must never clobber them.
     const settingsDest = path.join(destClaude, 'settings.json');
     if (fs.existsSync(settingsDest)) {
-      summary.skippedFiles.push('settings.json');
-      log('  • .claude/settings.json already present — left untouched (the instance owns it).');
+      // 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'), 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);
+        // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
+        // the upgrade pre-flight IGNORES when it checks for a dirty tree (task 1004122), and that
+        // waiver is justified by "materialize overwrites these unconditionally, so whatever they
+        // hold now is discarded either way" — which is precisely NOT true of a top-up, the one
+        // path here that preserves existing content. Leaving it out of the dry-run preview keeps
+        // an owner's uncommitted edit to settings.json halting the bump, as it always did; putting
+        // it in the real run's summary still hands it to persistPin, so the pin commit carries the
+        // added rules and the next upgrade does not read them as a human's stray work.
+        if (!dryRun) addWritten('.claude/settings.json');
+        summary.settingsDenyAdded = topUp.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED ${topUp.added.length} missing deny rule(s) — an instance that took the starter before task 1003966 carried none of them, so its local agent could still read keys and session tokens: ${topUp.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} ${topUp.added.length} missing deny rule(s) to .claude/settings.json — every rule you wrote is kept, the file is re-indented to 2 spaces: ${topUp.added.join(', ')}`);
+      } else if (topUp.reason) {
+        // The security gap PERSISTS here, so it does not get the same quiet bullet as the
+        // all-clear. upgrade.js never iterates summary.notes, so this log line is the only
+        // channel that reaches the operator's terminal.
+        summary.skippedFiles.push('settings.json');
+        summary.settingsDenyUncheckable = topUp.reason;
+        summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
+        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 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) {
         fs.mkdirSync(destClaude, { recursive: true });

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.962'; // 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

@@ -885,6 +885,173 @@ t('a checkout-materialized instance keeps the session-store rule at its fixed an
   rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- task 1004156: the deny rules reach an instance that ALREADY has a settings.json ----
+// THE DEFECT. The starter is written only when the file is ABSENT, so every instance that took
+// the allow-only starter (task 1003962) kept it forever and never received task 1003966's deny
+// half — its local agent could still read .env files, keys and session tokens. `bongos upgrade`
+// always takes this branch: it materializes from the published package, which excludes
+// .claude/settings.json on purpose, so the starter branch always meets a file already there.
+// THE FIX, and the owner's call: ADD the missing deny rules and name them. Additive is the whole
+// 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-'));
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true }); // skills ship; settings.json does not
+  mkdirSync(join(inst, '.claude'), { recursive: true });
+  mkdirSync(join(inst, 'config'), { recursive: true });
+  writeFileSync(join(inst, 'config', 'branding.json'), JSON.stringify({ configDir: 'acme', envPrefix: 'ACME' }));
+  const settingsPath = join(inst, '.claude', 'settings.json');
+  writeFileSync(settingsPath, typeof settings === 'string' ? settings : `${JSON.stringify(settings, null, 2)}\n`);
+  return { core, inst, settingsPath, read: () => readFileSync(settingsPath, 'utf8'),
+    cleanup: () => { rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true }); } };
+};
+
+t('an instance still on the allow-only starter GAINS the deny rules on its next materialize', () => {
+  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, 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');
+  assert.ok(res.writtenPaths.some((p) => p.replace(/\\/g, '/') === '.claude/settings.json'),
+    'the path is reported as written, or upgrade\'s clean-tree pre-flight halts on it as human work');
+  f.cleanup();
+});
+
+t("an owner-edited settings.json keeps every rule of its own and only gains what's missing", () => {
+  const f = topUpFixture({
+    permissions: { allow: ['Bash(npm test:*)'], deny: ['Read(secrets/**)', 'Read(**/*.pem)'], ask: ['Bash(rm:*)'] },
+    hooks: { Stop: [{ hooks: [{ type: 'command', command: 'echo mine' }] }] },
+    env: { MY_VAR: '1' },
+  });
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  const after = JSON.parse(f.read());
+  assert.deepEqual(after.permissions.allow, ['Bash(npm test:*)'], "the owner's allow list is theirs alone");
+  assert.deepEqual(after.permissions.ask, ['Bash(rm:*)'], 'a permissions key we do not manage is untouched');
+  assert.deepEqual(after.env, { MY_VAR: '1' }, 'and so is every key outside permissions');
+  assert.deepEqual(after.hooks.Stop[0].hooks[0], { type: 'command', command: 'echo mine' }, 'their hooks survive');
+  assert.deepEqual(after.permissions.deny.slice(0, 2), ['Read(secrets/**)', 'Read(**/*.pem)'],
+    "the owner's own deny rules keep their place at the front — appended, never reordered");
+  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 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 });
+  const settled = f.read();
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  assert.deepEqual(res.settingsDenyAdded, [], 'nothing left to add');
+  assert.equal(f.read(), settled, 'and the file comes back byte-identical');
+  assert.ok(res.skippedFiles.includes('settings.json'), 'reported as left alone, as it was before');
+  f.cleanup();
+});
+
+t('a dry run names the missing deny rules and writes nothing', () => {
+  const f = topUpFixture({ permissions: { allow: m.STARTER_ALLOW } });
+  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, topUpDenyFor({ configDir: 'acme' }),
+    'but it still names what a real run would add');
+  f.cleanup();
+});
+
+t("the DRY RUN does not waive settings.json from upgrade's dirty-tree pre-flight", () => {
+  // writtenPaths doubles as the set the pre-flight IGNORES when it looks for uncommitted work
+  // (task 1004122). That waiver is justified by "materialize overwrites these unconditionally,
+  // so whatever they hold now is discarded either way" — which is exactly NOT true of the
+  // top-up, the one path that PRESERVES what is there. If the preview listed settings.json, an
+  // owner's half-finished edit to it would stop halting the bump and would be committed and
+  // pushed by --commit-pin unreviewed. The real run still reports it, so persistPin commits the
+  // rules it added and the next upgrade does not read them as a human's stray work.
+  const f = topUpFixture({ permissions: { allow: m.STARTER_ALLOW } });
+  const preview = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: true });
+  const settings = (paths) => paths.some((p) => p.replace(/\\/g, '/') === '.claude/settings.json');
+  assert.equal(settings(preview.writtenPaths), false,
+    "a dirty settings.json must still halt the bump — the preview may not vouch for a file we don't overwrite");
+  const real = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  assert.equal(settings(real.writtenPaths), true,
+    'the real run reports it, so the pin commit carries the rules it added');
+  f.cleanup();
+});
+
+t('a settings.json we cannot parse is left byte-for-byte alone, and said so', () => {
+  // Same posture task 1004023 took for the core's own file: a rewrite we cannot reason about is
+  // worse than the gap. The operator is told, rather than the file being quietly half-fixed.
+  const raw = '{ "permissions": { "allow": [] } // a comment JSON cannot hold\n}';
+  const f = topUpFixture(raw);
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  assert.equal(f.read(), raw, 'we never rewrite a file we could not parse');
+  assert.deepEqual(res.settingsDenyAdded, [], 'and nothing is claimed to have been added');
+  assert.match(res.settingsDenyUncheckable, /not valid JSON/);
+  assert.ok(res.notes.some((n) => n.includes('could not be checked for missing deny rules')),
+    'the gap is reported rather than silently left');
+  f.cleanup();
+});
+
+t('a deny half that is not a list is left alone rather than coerced', () => {
+  const f = topUpFixture({ permissions: { allow: [], deny: 'Read(**/*.pem)' } });
+  const before = f.read();
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false });
+  assert.equal(f.read(), before, 'an unexpected shape is never rewritten into our own');
+  assert.match(res.settingsDenyUncheckable, /permissions\.deny/);
+  f.cleanup();
+});
+
 // task 1004012 — the other source: a CHECKOUT core root does carry a settings.json, and the
 // instance used to receive its allow-list verbatim, naming scripts its skills no longer run.
 t('a checkout-materialized instance gets allow-rules in the bongos form, end to end', () => {
@@ -903,16 +1070,25 @@ t('a checkout-materialized instance gets allow-rules in the bongos form, end to
   rmSync(inst, { recursive: true, force: true });
 });
 
-t("an instance's OWN settings.json is never clobbered", () => {
+// SUPERSEDED BY task 1004156, deliberately. This test used to assert the file came back
+// BYTE-IDENTICAL. That spelling of "never clobbered" also froze out the deny rules — an instance
+// on the allow-only starter could never receive them (task 1003966's fix reached only instances
+// materialized after it). The contract the project actually wants is the strictly stronger one
+// asserted here: nothing the instance wrote is removed, reordered or rewritten — a deny rule may
+// be APPENDED, and that can only ever narrow what the local agent may do.
+t("an instance's OWN settings.json keeps every rule it has — only deny rules are added", () => {
   const core = mkdtempSync(join(tmpdir(), 'w3-keep-core-'));
   const inst = mkdtempSync(join(tmpdir(), 'w3-keep-inst-'));
   mkdirSync(join(core, '.claude', 'skills'), { recursive: true });
   mkdirSync(join(inst, '.claude'), { recursive: true });
-  const mine = JSON.stringify({ permissions: { allow: ['Bash(echo hello:*)'] } }, null, 2);
-  writeFileSync(join(inst, '.claude', 'settings.json'), mine);
+  const mine = { permissions: { allow: ['Bash(echo hello:*)'] } };
+  writeFileSync(join(inst, '.claude', 'settings.json'), JSON.stringify(mine, null, 2));
   m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
-  assert.equal(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'), mine,
+  const after = JSON.parse(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'));
+  assert.deepEqual(after.permissions.allow, mine.permissions.allow,
     'an upgrade must never overwrite permissions the instance has grown');
+  assert.deepEqual(Object.keys(after), Object.keys(mine), 'and it grows no key of its own');
+  assert.ok(after.permissions.deny.length > 0, 'the deny half it never had does arrive');
   rmSync(core, { recursive: true, force: true });
   rmSync(inst, { recursive: true, force: true });
 });

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();