@bongos/core 1.19.975 → 1.19.977

package/modules/provisioning/provisioning.js

@@ -58,7 +58,7 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // 'disconnect' (task 1003249, migration provisioning_016): the owner's true delete — ./disconnect.js.
 // 'core-upgrade' (task 1003159, ADR 0293): move this instance's core pin — the owner's
 // deploy door. The web tier only QUEUES it; the control-plane runner performs it.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight'];
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade', 'core-upgrade-preflight', 'repo-private'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept
@@ -1158,7 +1158,7 @@ async function enqueueIntent(db, instanceId, action, requestedBy, targetVersion
 // (the state CHECK has no 'superseded'; last_error says why) so the runner never
 // stands it up. A PENDING settings push is superseded the same way (task 1003140):
 // a push into a project about to be torn down is dead work, and letting it hold the
-// delete hostage would repeat 1002691. A pending 'restart' joins them for the same
+// delete hostage would repeat 1002691. A pending 'restart' or 'repo-private' (task 1004193) joins them for the same
 // reason (task 1003238) — and more sharply, since the owner reaches for Restart
 // precisely when a project looks broken, which is also when they give up and delete
 // it. A RUNNING intent is mid-flight and never yanked —
@@ -1171,7 +1171,7 @@ async function enqueueTeardown(db, instanceId, requestedBy) {
     `UPDATE provisioning_intents
         SET state = 'error', last_error = 'superseded: teardown requested',
             updated_at = now(), resolved_at = now()
-      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart') AND state = 'pending'
+      WHERE instance_id = $1 AND action IN ('provision', 'settings-apply', 'restart', 'repo-private') AND state = 'pending'
       RETURNING id`,
     [instanceId]
   );

package/modules/provisioning/repo-private.js

@@ -0,0 +1,29 @@
+// modules/provisioning/repo-private.js — the queue half of "make this project's repository
+// private" (task 1004193, split (b) of task 1003078; ADR 0176).
+//
+// A project stood up with a public repository reads its code with the platform's shared
+// key, which cannot read a private one — so the flip must wait until the project has its
+// own read-only deploy key. That wiring needs the box and the owner's stored credential, so
+// the web tier only enqueues; scripts/gds/provision-repo-private.js is the runner leg that
+// wires the key and THEN flips.
+//
+// Its own file because provisioning.js sits at the size ratchet. It reaches the queue
+// through the provisioning module OBJECT, so a test can stub enqueueIntent.
+'use strict';
+
+const provisioning = require('./provisioning');
+
+// Queue a flip-to-private. Arbitration is the restart shape: an open repo-private in
+// either state makes a repeat idempotent (the flip has no payload, so there is nothing a
+// second request could change); any OTHER open intent refuses it with
+// { conflict: 'open_intent' } rather than racing a standup, teardown or settings push over
+// the same checkout. The partial unique index ux_provisioning_intents_open stays the
+// arbiter if two requests interleave.
+async function enqueueRepoPrivate(db, instanceId, requestedBy) {
+  const { intent, created } = await provisioning.enqueueIntent(db, instanceId, 'repo-private', requestedBy);
+  if (created) return { intent, created: true };
+  if (intent.action === 'repo-private') return { intent, created: false };
+  return { intent, created: false, conflict: 'open_intent' };
+}
+
+module.exports = { enqueueRepoPrivate };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.975",
+  "version": "1.19.977",
   "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/audit-deps.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// scripts/gds/audit-deps.js — likely-missing-dependency detector (task 349).
+// scripts/gds/audit-deps.js — likely-missing-dependency detector CLI (task 349).
 //
 // WHY: an under-specified dependencies[] lets work start before the task it
 // implicitly builds on has shipped, racing already-built work (the original
@@ -11,16 +11,21 @@
 // (src/bongos/db.js, migrations/, CLAUDE.md, …), NOT a build-order dependency.
 // Backfilling a wrong edge GATES the dependent (POST /claims → 409
 // DEPS_NOT_SHIPPED) until the named blocker ships. So: act only on `high`
-// confidence, by hand, after reading both task descriptions. The detector reuses
-// the ONE canonical overlap matcher (src/bongos/path-match.touchesOverlap) — the
-// same one tests/touches_overlap.mjs covers — so it can't drift from the claim
-// gate's notion of "overlap".
+// confidence, by hand, after reading both task descriptions.
+//
+// PURE CORE MOVED to modules/lifecycle/missing-dep-classify.js (task 1002827),
+// so dependency-advisory.js's live POST /tasks path can reuse the ONE canonical
+// `classify`/`findMissingDeps` — the same one tests/audit_deps.mjs covers —
+// without pulling this file's CLI-only machinery (cliClient's session-token
+// I/O, resolveDefaultVersion) into the running server. This file is now the
+// CLI wrapper only: argv parsing, the corpus fetch, and --stranded's dead-edge
+// report. Every name below is RE-EXPORTED unchanged so no caller of this file
+// (including tests/audit_deps.mjs) needs to know it moved.
 //
 //   node scripts/gds/audit-deps.js [--version GDS-V3] [--min high|medium|low] [--json]
 //   node scripts/gds/audit-deps.js --stranded [--json]   # the INVERSE: dead edges (task 1003153),
 //                                                      # plus prose-declared gates naming a dead task (task 1003857, advisory)
 
-const { touchesOverlap } = require('../../src/bongos/path-match.js');
 const { cliClient } = require('./cli-lib');
 const { resolveDefaultVersion } = require('./version-select.js');
 // task 1003153 — the DEAD-edge detector core, shared with the claim refusal so
@@ -28,61 +33,8 @@ const { resolveDefaultVersion } = require('./version-select.js');
 const { findStrandedTasks, findProseGatedTasks } = require('../../modules/lifecycle/dead-deps.js');
 // task 1003752 — the route's page bound + the first-page offset rule, declared once.
 const { TASK_LIST_MAX_LIMIT, buildTaskPageQuery } = require('../../modules/lifecycle/task-list-limits.js');
-
-// Lifecycle statuses that count as "open" (auditable) vs "an unshipped blocker".
-const OPEN = new Set(['ready', 'backlog', 'active', 'blocked']);
-const isUnshippedBlocker = (s) => s !== 'shipped' && s !== 'abandoned';
-
-// Shared collaboration surfaces: an overlap here is a parallel-safety (touches[])
-// signal, not a dependency. A candidate whose ONLY overlap is one of these (or a
-// bare directory) is demoted to `low`. Deliberately broad; tune as the repo moves.
-const HOTSPOTS = [
-  'src/bongos/db.js', 'src/bongos/routes.js', 'server.js', 'migrations/', 'CLAUDE.md',
-  'modules/hall-ui/', 'tests/', 'scripts/gds/', 'src/bongos/', 'src/bongos/routes/',
-  'scripts/gds/ship.js', 'scripts/gds/api.js', 'scripts/gds/cli-lib.js',
-  'modules/grading/grader.js', 'docs/', 'docs/adr/', 'docs/adr/README.md', 'docs/recipes/',
-  'docs/architecture.md', 'docs/file-map.md', '.claude/skills/', '.claude/hooks/',
-  'infra/', 'public/assets/tiles/',
-];
-const isHotspot = (p) => HOTSPOTS.includes(p);
-
-// Confidence heuristic (advisory; a human decides):
-//   high   — an exact SAME non-hotspot, non-bare-dir FILE both tasks name.
-//   medium — a narrow (non-hotspot, non-bare-dir) overlap exists.
-//   low    — overlap only on a shared hotspot / bare directory.
-function classify(tTouches, oTouches) {
-  const pairs = [];
-  for (const a of tTouches) for (const b of oTouches) {
-    if (touchesOverlap([a], [b])) pairs.push({ a, b, exact: a === b });
-  }
-  if (!pairs.length) return null;
-  const narrow = pairs.filter((p) => !isHotspot(p.a) && !isHotspot(p.b) && !p.a.endsWith('/') && !p.b.endsWith('/'));
-  const confidence = narrow.some((p) => p.exact) ? 'high' : narrow.length ? 'medium' : 'low';
-  const paths = [...new Set(pairs.map((p) => (p.exact ? p.a : `${p.a} ~ ${p.b}`)))];
-  return { confidence, paths };
-}
-
-// Pure core — unit-tested with fixtures (no API). `tasks` is an array of
-// { id, status, touches:[], dependencies:[ids] }. Returns candidate edges
-// { task_id, dep_id, dep_status, confidence, paths }.
-function findMissingDeps(tasks, { open = OPEN, isBlocker = isUnshippedBlocker } = {}) {
-  const out = [];
-  for (const t of tasks) {
-    if (!open.has(t.status)) continue;
-    if (!Array.isArray(t.touches) || !t.touches.length) continue;
-    const declared = new Set((t.dependencies || []).map(String));
-    for (const o of tasks) {
-      if (String(o.id) === String(t.id)) continue;
-      if (!isBlocker(o.status)) continue;
-      if (!Array.isArray(o.touches) || !o.touches.length) continue;
-      if (declared.has(String(o.id))) continue;
-      if (!touchesOverlap(t.touches, o.touches)) continue;
-      const c = classify(t.touches, o.touches);
-      if (c) out.push({ task_id: t.id, dep_id: o.id, dep_status: o.status, ...c });
-    }
-  }
-  return out;
-}
+const { OPEN, isUnshippedBlocker, HOTSPOTS, classify, findMissingDeps } =
+  require('../../modules/lifecycle/missing-dep-classify.js');
 
 // Read the WHOLE task corpus, one allowed page at a time (task 1003752). This
 // was a single `limit: 3000` read, which GET /tasks caps at TASK_LIST_MAX_LIMIT

package/scripts/gds/provision-repo-private.js

@@ -0,0 +1,86 @@
+'use strict';
+// provision-repo-private.js — "make this project's repository private": the runner leg
+// (task 1004193, split (b) of task 1003078; ADR 0176).
+//
+// WHY. A project stood up while its repository was public reads its code with the
+// platform's shared deploy key, which cannot read a private repository. Flip such a
+// repository private and the project's next deploy pull fails (walk finding N4). Standups
+// since ADR 0176 give a private repository the project's own read-only deploy key; this
+// leg gives an EXISTING project the same wiring, and only then flips.
+//
+// ORDER IS THE SAFETY PROPERTY. Wire the key FIRST, flip SECOND. A deploy key authenticates
+// against a still-public repository, so wiring first leaves no window in which the repo is
+// private and the checkout still reads with the shared key. ensurePrivateRepoAccess would
+// see the repo as public and do nothing, so it is told where the repo is going
+// (`intendedPrivate`, task 1004167). If the flip then fails, the repository is public with
+// a working key — harmless, and the retry re-runs both steps idempotently.
+//
+// Every expected failure returns { ok:false } rather than throwing: a throw makes the
+// runner mark the whole project 'error', and a project that could not be made private is
+// still running fine. The error text is the owner's sentence — it rides error_note onto
+// the project card once the retries are spent.
+//
+// Its own file because provision.js sits at the size ratchet (the provision-disconnect.js
+// precedent). The web tier only enqueues (modules/provisioning/repo-private.js).
+
+const path = require('node:path');
+const { REPO_ROOT } = require('./provision-config.js');
+const { parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo-auth.js');
+const { ensurePrivateRepoAccess } = require('./provision-repo.js');
+
+async function repoPrivateInstance(inst, deps) {
+  const { db, provisioning, log, apply } = deps;
+  log(`repo-private ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status})`);
+
+  // Only a standalone project has its own checkout to wire; any other shape reads from a
+  // checkout this project does not own, so a key minted here would change nothing.
+  if (inst.hosting_shape !== 'standalone') {
+    return { ok: false, error: 'This project shares its code checkout with others, so its repository cannot be made private from here.' };
+  }
+  if (inst.status !== 'active') {
+    return { ok: false, error: `This project is ${inst.status}, not running, so its repository was not changed. Try again once it is live.` };
+  }
+  const repo = parseTargetRef(inst.target_ref);
+  if (!repo) return { ok: false, error: 'This project has no GitHub repository on record, so there is nothing to make private.' };
+
+  let wired;
+  try {
+    wired = await ensurePrivateRepoAccess(inst, { ...deps, intendedPrivate: true });
+  } catch (e) {
+    return { ok: false, error: (e && e.message) || String(e) };
+  }
+  if (!apply) {
+    log(`  [repo-private] would then make ${repo.owner}/${repo.name} private with the owner's credential — only after the deploy key above is wired (dry-run — nothing ran)`);
+    return { ok: true, planned: true };
+  }
+  if (!wired || wired.private !== true) {
+    // Defensive: with intendedPrivate set, a standalone row with a repo either wires or
+    // throws. Anything else means the checkout is unwired, and flipping would break it.
+    return { ok: false, error: `The deploy key for ${repo.owner}/${repo.name} could not be set up, so the repository was left public.` };
+  }
+
+  const token = await resolveOwnerGithubToken(inst, deps);
+  if (!token) {
+    return { ok: false, error: `${repo.owner}/${repo.name} was not made private: the project's GitHub credential could not be read. Its deploy key is already in place, so reconnect GitHub and try again.` };
+  }
+  const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
+  try {
+    log(`  [repo-private] making ${repo.owner}/${repo.name} private`);
+    await ghRepos.makeRepoPrivate(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+  } catch (e) {
+    const why = e && e.code === 'not_repo_admin' ? 'GitHub refused — the connected account cannot change this repository’s settings'
+      : e && e.code === 'repo_not_found' ? 'GitHub could not find the repository with the connected account'
+      : `GitHub could not make the change (${(e && e.message) || e})`;
+    return { ok: false, error: `${repo.owner}/${repo.name} is still public: ${why}. Its deploy key is already in place, so trying again is safe.` };
+  }
+
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'repo-private',
+    detail: `${repo.owner}/${repo.name} made private — the project now reads it with its own read-only deploy key${wired.minted ? ' (newly registered)' : ''}`,
+    actor: 'runner',
+  }).catch(() => {});
+  log(`  ✓ ${repo.owner}/${repo.name} is private; ${inst.slug} reads it with its own deploy key`);
+  return { ok: true, minted: !!wired.minted };
+}
+
+module.exports = { repoPrivateInstance };

package/scripts/gds/provision.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 'use strict';
-//
 // scripts/gds/provision.js — the INSTANCE-provisioning control-plane runner
 // (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944). A sibling of box.js.
 //
@@ -1294,6 +1293,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'disconnect') result = await disconnectInstance(inst, deps);
       else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
       else if (intent.action === 'core-upgrade-preflight') result = await preflightCoreUpgrade(inst, deps, intent); // changes nothing; caches what the move WOULD say (task 1004121)
+      else if (intent.action === 'repo-private') result = await require('./provision-repo-private.js').repoPrivateInstance(inst, deps); // wire the deploy key, THEN flip (task 1004193); required here — this file is at the size ratchet
       else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {

package/src/bongos/github-repos.js

@@ -129,17 +129,14 @@ async function getUserRepo(token, { owner, name, fetchImpl = fetch } = {}) {
   };
 }
 
-// Flip one repo PUBLIC — and only public. Like createUserRepo's private:false,
-// the direction is deliberately not a parameter: the deploy pull still runs as
-// the shared deploy key that cannot read a private repo (walk finding N4), so
-// nothing in this codebase may flip a repo private until that fix lands — the
-// route refuses the request; this helper makes the refusal structural
-// (task 1003045). Returns the same shape as getUserRepo.
-async function makeRepoPublic(token, { owner, name, fetchImpl = fetch } = {}) {
+// The visibility PATCH both directions share. Deliberately NOT exported: callers get
+// one named function per direction, so the name stays the contract and no caller can
+// pass a direction it did not mean (the createUserRepo private:false precedent).
+async function setRepoPrivate(token, { owner, name, fetchImpl = fetch }, isPrivate) {
   const res = await fetchImpl(`${GH_API}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`, {
     method: 'PATCH',
     headers: ghHeaders(token, { 'Content-Type': 'application/json' }),
-    body: JSON.stringify({ private: false }),
+    body: JSON.stringify({ private: isPrivate }),
   });
   if (res.status === 401) {
     throw new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
@@ -162,6 +159,22 @@ async function makeRepoPublic(token, { owner, name, fetchImpl = fetch } = {}) {
   };
 }
 
+// Flip one repo PUBLIC (task 1003045). Needs no deploy-key wiring — the shared key
+// reads a public repo — so the core route may call it directly. Returns the same
+// shape as getUserRepo.
+async function makeRepoPublic(token, ref = {}) {
+  return setRepoPrivate(token, ref, false);
+}
+
+// Flip one repo PRIVATE. Only the control-plane runner may call this, and only AFTER
+// ensurePrivateRepoAccess has wired the project's own read-only deploy key: the
+// shared key cannot read a private repo, so flipping first breaks the next deploy
+// pull (walk finding N4, ADR 0176). scripts/gds/provision-repo-private.js is that
+// caller (task 1004193); no web route calls it. Returns the same shape as getUserRepo.
+async function makeRepoPrivate(token, ref = {}) {
+  return setRepoPrivate(token, ref, true);
+}
+
 // ---- deploy keys (task 1002735 / ADR 0176) ----
 // The per-repo credential a PRIVATE repo's recurring deploy pull authenticates
 // with: provisioning mints an ed25519 keypair, registers its public half here with
@@ -237,7 +250,7 @@ async function deleteDeployKey(token, { owner, name, keyId, fetchImpl = fetch }
 }
 
 module.exports = {
-  listUserRepos, createUserRepo, getUserRepo, makeRepoPublic,
+  listUserRepos, createUserRepo, getUserRepo, makeRepoPublic, makeRepoPrivate,
   listDeployKeys, addDeployKey, deleteDeployKey,
   GithubApiError, MAX_PAGES,
 };

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.975'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.977'; // 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/dependency_advisory.mjs

@@ -0,0 +1,231 @@
+// tests/dependency_advisory.mjs — the missing-dependency advisory on POST
+// /tasks (task 1002827, goal 1000089).
+//
+// scripts/gds/audit-deps.js has shipped a working likely-missing-dependency
+// detector since task 1000349 (tests/audit_deps.mjs, tests/missing_dep_classify.mjs)
+// and nothing called it. This wires the SAME detector's pure core
+// (modules/lifecycle/missing-dep-classify.js) live, mirroring goal-advisory.js's
+// two properties:
+//   1. DETECTION reuses the one canonical overlap matcher — no second copy.
+//   2. The advisory can NEVER fail the create — asserted here by driving it
+//      with a db that throws.
+//
+// Run: node tests/dependency_advisory.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { makeRunner, taskRoutesSource } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const { adviseDependencies, buildDependencyAdvisory, CANDIDATE_LIMIT } = require('../modules/lifecycle/dependency-advisory.js');
+
+const tasksSrc = taskRoutesSource();
+const { test, summary } = makeRunner();
+
+// ---- adviseDependencies: the pure core ----
+
+await test('no touches[] on the new task — silent, no candidates read', () => {
+  assert.equal(adviseDependencies({ task: { id: 1, touches: [] }, candidates: [{ id: 2, status: 'ready', touches: ['a.js'] }] }), null);
+  assert.equal(adviseDependencies({ task: { id: 1 }, candidates: [] }), null);
+});
+
+await test('an exact narrow-file overlap with an open candidate is flagged high', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['modules/foo/bar.js'] },
+    candidates: [{ id: 2, title: 'Sibling work', status: 'ready', touches: ['modules/foo/bar.js'] }],
+  });
+  assert.equal(a.reason, 'possible_missing_dependency');
+  assert.equal(a.candidates.length, 1);
+  assert.equal(a.candidates[0].dep_id, 2);
+  assert.equal(a.candidates[0].confidence, 'high');
+  assert.equal(a.candidates[0].dep_title, 'Sibling work');
+});
+
+await test('an already-declared dependency is never flagged', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['modules/foo/bar.js'], dependencies: ['2'] },
+    candidates: [{ id: 2, status: 'ready', touches: ['modules/foo/bar.js'] }],
+  });
+  assert.equal(a, null);
+});
+
+await test('a SHIPPED candidate never gates — the dependency system already treats it as satisfied', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['modules/foo/bar.js'] },
+    candidates: [{ id: 2, status: 'shipped', touches: ['modules/foo/bar.js'] }],
+  });
+  assert.equal(a, null);
+});
+
+await test('an ABANDONED candidate never gates', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['modules/foo/bar.js'] },
+    candidates: [{ id: 2, status: 'abandoned', touches: ['modules/foo/bar.js'] }],
+  });
+  assert.equal(a, null);
+});
+
+await test('a candidate never flags itself', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['modules/foo/bar.js'] },
+    candidates: [{ id: 1, status: 'ready', touches: ['modules/foo/bar.js'] }],
+  });
+  assert.equal(a, null);
+});
+
+await test('a hotspot-only overlap (e.g. CLAUDE.md) is flagged low, sorted after a high candidate', () => {
+  const a = adviseDependencies({
+    task: { id: 1, touches: ['CLAUDE.md', 'modules/foo/bar.js'] },
+    candidates: [
+      { id: 2, status: 'ready', touches: ['CLAUDE.md'] },
+      { id: 3, status: 'ready', touches: ['modules/foo/bar.js'] },
+    ],
+  });
+  assert.equal(a.candidates.length, 2);
+  assert.equal(a.candidates[0].dep_id, 3, 'high confidence sorts first');
+  assert.equal(a.candidates[0].confidence, 'high');
+  assert.equal(a.candidates[1].confidence, 'low');
+});
+
+await test('candidates are capped at CANDIDATE_LIMIT', () => {
+  const candidates = Array.from({ length: CANDIDATE_LIMIT + 3 }, (_, i) => ({ id: i + 2, status: 'ready', touches: ['modules/foo/bar.js'] }));
+  const a = adviseDependencies({ task: { id: 1, touches: ['modules/foo/bar.js'] }, candidates });
+  assert.equal(a.candidates.length, CANDIDATE_LIMIT);
+});
+
+// ---- buildDependencyAdvisory: DB-read wrapper, fail-open ----
+
+await test('buildDependencyAdvisory: no touches[] skips the DB read entirely', async () => {
+  let read = false;
+  const db = { async listOpenTasksWithTouches() { read = true; return []; } };
+  const a = await buildDependencyAdvisory({ db, versionId: 'V', task: { id: 1, touches: [] } });
+  assert.equal(a, null);
+  assert.equal(read, false);
+});
+
+await test('buildDependencyAdvisory: a real candidate yields a next_step naming the actual task id', async () => {
+  const db = { async listOpenTasksWithTouches() { return [{ id: 2, title: 'Sibling', status: 'ready', touches: ['modules/foo/bar.js'] }]; } };
+  const a = await buildDependencyAdvisory({ db, versionId: 'V', task: { id: 42, touches: ['modules/foo/bar.js'] } });
+  assert.equal(a.reason, 'possible_missing_dependency');
+  assert.match(a.next_step, /POST \/tasks\/42\/dependencies/);
+});
+
+await test('NON-BLOCKING: buildDependencyAdvisory returns null when db.listOpenTasksWithTouches throws', async () => {
+  const db = { async listOpenTasksWithTouches() { throw new Error('db down'); } };
+  const a = await buildDependencyAdvisory({ db, versionId: 'V', task: { id: 1, touches: ['a.js'] } });
+  assert.equal(a, null, 'degrades to silence — never propagates into the already-committed create');
+});
+
+await test('NON-BLOCKING: a db missing the method entirely still yields null, not a crash', async () => {
+  const a = await buildDependencyAdvisory({ db: {}, versionId: 'V', task: { id: 1, touches: ['a.js'] } });
+  assert.equal(a, null);
+});
+
+await test('buildDependencyAdvisory forwards viewerId/viewerIsArchon to the query (ADR 0112 visibility)', async () => {
+  let seen = null;
+  const db = {
+    async listOpenTasksWithTouches(versionId, excludeId, opts) { seen = { versionId, excludeId, opts }; return []; },
+  };
+  await buildDependencyAdvisory({ db, versionId: 'V', task: { id: 42, touches: ['a.js'] }, viewerId: 7, viewerIsArchon: true });
+  assert.deepEqual(seen, { versionId: 'V', excludeId: 42, opts: { viewerId: 7, viewerIsArchon: true } });
+});
+
+await test('buildDependencyAdvisory defaults viewerId/viewerIsArchon when the caller omits them', async () => {
+  let seen = null;
+  const db = { async listOpenTasksWithTouches(v, e, opts) { seen = opts; return []; } };
+  await buildDependencyAdvisory({ db, versionId: 'V', task: { id: 1, touches: ['a.js'] } });
+  assert.deepEqual(seen, { viewerId: null, viewerIsArchon: false });
+});
+
+// ---- ADR 0112: the query itself must carry the visibility predicate ----
+// (SQL correctness for this file is integration-tested elsewhere in this
+// codebase's own convention — no local Postgres here — so this is the same
+// source-scan safety net the goal-advisory/goal-graph precedents use to
+// catch an accidental removal of the join/predicate.)
+
+await test('listOpenTasksWithTouches SQL joins goals + goal_members and excludes an unseen private goal', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/db-tasks.js', import.meta.url), 'utf8');
+  const fn = src.slice(src.indexOf('async function listOpenTasksWithTouches'), src.indexOf('async function listOpenTasksWithTouches') + 1200);
+  assert.match(fn, /LEFT JOIN goals g ON g\.id = t\.goal_id/);
+  assert.match(fn, /LEFT JOIN goal_members gm ON gm\.goal_id = g\.id/);
+  assert.match(fn, /g\.visibility IS DISTINCT FROM 'private'/);
+  assert.match(fn, /gm\.builder_id IS NOT NULL/, 'a viewer\'s own membership admits a private goal\'s task');
+  assert.match(fn, /LIMIT \$\{DEPENDENCY_ADVISORY_CANDIDATE_LIMIT\}/, 'the candidate pool is bounded');
+});
+
+// ---- the route wiring, asserted over source (the goal_advisory.mjs precedent) ----
+
+await test('the route delegates to buildDependencyAdvisory — no inline logic to drift — and forwards the viewer identity for ADR 0112', () => {
+  assert.match(tasksSrc, /await buildDependencyAdvisory\(\{[\s\S]{0,80}?db, versionId: body\.version_id, task,[\s\S]{0,200}?viewerId: req\.builder\.id, viewerIsArchon: req\.builder\.rank === 'archon',[\s\S]{0,20}?\}\);/);
+  const body201 = (tasksSrc.match(/res\.status\(201\)\.json\(\{[\s\S]*?\}\);/) || [''])[0];
+  assert.ok(body201, 'found the 201 response body');
+  assert.match(body201, /dependency_advisory,/, 'included in the 201 body');
+});
+
+// ---- ROUTER-LEVEL: the non-blocking invariant asserted over real HTTP ----
+
+function listen(app) {
+  return new Promise((resolve) => {
+    const server = app.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+function post(port, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(
+      { host: '127.0.0.1', port, path, method: 'POST',
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } },
+      (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => resolve({ status: res.statusCode, body: JSON.parse(data || '{}') }));
+      }
+    );
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function makeApp(db) {
+  const express = require('express');
+  const app = express();
+  app.use(express.json());
+  app.post('/tasks', async (req, res) => {
+    try {
+      const task = { id: 99, touches: req.body.touches || [], credits_reward: 60 }; // already committed
+      const dependency_advisory = await buildDependencyAdvisory({ db, versionId: req.body.version_id, task });
+      res.status(201).json({ task, criteria: [], dependency_advisory });
+    } catch (err) {
+      res.status(500).json({ error: { code: 'create_failed' } });
+    }
+  });
+  return app;
+}
+
+await test('HTTP: a healthy db yields 201 with a populated dependency_advisory', async () => {
+  const db = { async listOpenTasksWithTouches() { return [{ id: 2, title: 'Sibling', status: 'ready', touches: ['modules/foo/bar.js'] }]; } };
+  const server = await listen(makeApp(db));
+  try {
+    const r = await post(server.address().port, '/tasks', { version_id: 'V', touches: ['modules/foo/bar.js'] });
+    assert.equal(r.status, 201);
+    assert.equal(r.body.dependency_advisory.reason, 'possible_missing_dependency');
+  } finally { server.close(); }
+});
+
+await test('HTTP: db.listOpenTasksWithTouches THROWS → still 201, task returned, dependency_advisory null (never a 500)', async () => {
+  const db = { async listOpenTasksWithTouches() { throw new Error('db down'); } };
+  const server = await listen(makeApp(db));
+  try {
+    const r = await post(server.address().port, '/tasks', { version_id: 'V', touches: ['modules/foo/bar.js'] });
+    assert.equal(r.status, 201, 'the create must NOT become a 500 the caller retries into a duplicate');
+    assert.equal(r.body.task.id, 99, 'the created task is still returned');
+    assert.equal(r.body.dependency_advisory, null, 'the advisory degrades to silence');
+  } finally { server.close(); }
+});
+
+summary();