@bongos/core 1.19.976 → 1.19.977

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.976",
-  "core_contract": "1.19.976",
-  "source_commit": "842af7dc231eb9ad6803f0de071d554622562402",
+  "core_version": "1.19.977",
+  "core_contract": "1.19.977",
+  "source_commit": "97ba854401629212275dafc294e6632004516781",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T15:01:32.683Z",
+  "built_at": "2026-09-23T15:21:57.063Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 516,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2382,
+    "functional_verbatim": 2386,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2924,
-  "tree_sha256": "6ad34cb8327cf6329010817bd052759a99e906fb785e2f370bb15ee113343cc1",
+  "file_count": 2928,
+  "tree_sha256": "bc6990ad901c42ffd73df27e947932152a51800591640250f55acda99925c20f",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -142,12 +142,12 @@
     {
       "path": ".claude/skills/goal-create/SKILL.md",
       "mode": "0000644",
-      "sha256": "b6ee07ebb27de1b8b4d3406617f0f577e07f72e38df9df0f65381b03eae00b39"
+      "sha256": "fef368de4b2a0b42aad43f505b053d7b84aac34bf8f1da7525053970e8e27f42"
     },
     {
       "path": ".claude/skills/goal-review/SKILL.md",
       "mode": "0000644",
-      "sha256": "606df145f399fb1aa483d608258eda0f2a88906142d5e675d7aacf272d235e0a"
+      "sha256": "39016b0c0bf7c42e0b0ee1dc9bff23b90401a1ad29c34f7a475406660855be79"
     },
     {
       "path": ".claude/skills/grade-audit/SKILL.md",
@@ -2702,7 +2702,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "9b3e01085f3f3648c51df5ecc0e6d6b4e6c687e90aceaa4e3c80689500767c88"
+      "sha256": "5df4d92085d7624d9c5acbf8f99af5a02d10731359071102d4cbe8b8eb73820c"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5797,7 +5797,7 @@
     {
       "path": "modules/lifecycle/db-tasks.js",
       "mode": "0000644",
-      "sha256": "ba8a41a33d3612f41509d50c65533f169b4008bbc8a01df783dbd03fe872afa4"
+      "sha256": "d0844d8f53c003e6026918ad2c132262a358b8c64951aa7927eace1e37fcd41f"
     },
     {
       "path": "modules/lifecycle/db-versions.js",
@@ -5814,6 +5814,11 @@
       "mode": "0000644",
       "sha256": "4738131a48e85dd7bf0644ddd3686c85d0d1d0da55ee623b1834d048c614b91c"
     },
+    {
+      "path": "modules/lifecycle/dependency-advisory.js",
+      "mode": "0000644",
+      "sha256": "b2d93f29010a27f50d5da5712e485b7fac0ef6582f3e531052699b321c693d5e"
+    },
     {
       "path": "modules/lifecycle/done-when.js",
       "mode": "0000644",
@@ -5964,6 +5969,11 @@
       "mode": "0000644",
       "sha256": "85f7c058dcd6bc3f3d7e4d46ee1c58047347c9bff833148ec715f2a29fe7d7a7"
     },
+    {
+      "path": "modules/lifecycle/missing-dep-classify.js",
+      "mode": "0000644",
+      "sha256": "d89f4659debd15dfac18258ba1e900f58c757e02937444d42391acec727afef0"
+    },
     {
       "path": "modules/lifecycle/module.json",
       "mode": "0000644",
@@ -6107,7 +6117,7 @@
     {
       "path": "modules/lifecycle/routes/task-write-routes.js",
       "mode": "0000644",
-      "sha256": "bb172485d8d5f84d96cdb611b0d57cd5f69ee768bdceddeb1eea42dc3f5676c1"
+      "sha256": "7f9419719070ec7048a2c81149427cbdaf3bf0e4a33993c1c79453161bdc06cc"
     },
     {
       "path": "modules/lifecycle/routes/tasks.js",
@@ -8132,12 +8142,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "de02838b05a35599823a045bae0ed5e317ee334951d9dee697785c790bd90e66"
+      "sha256": "94174c5cd82588020aca94cba69a1e64e311efc037ab4768df616028056268d3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a93b66e4c048714c36e8c237004cc15061ea8776795535ddd7b179fe1b1b1bfc"
+      "sha256": "97a39697bb451c4ace97d3d753dc66b8e6d77aa0c832fdc91f8d9dd60c10fea9"
     },
     {
       "path": "public-docs/index.html",
@@ -8272,7 +8282,7 @@
     {
       "path": "scripts/gds/audit-deps.js",
       "mode": "0000644",
-      "sha256": "ff7ccdf15ae2c215d3330e957d6a36adc7d48f5d9bd5042b5d61bb228b878073"
+      "sha256": "529829a6ba6de16a0166ac3bf4108366c2831d6ac76eac1b448b9fe3b397d775"
     },
     {
       "path": "scripts/gds/audit-exports.js",
@@ -10162,7 +10172,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "73c1013f0db275ad8c71b17973158d0ac150c99e9006a3d0aafac94758fa6f13"
+      "sha256": "a666eed999520506fa357a4b21c5f304f7237bad0b4ca25953505485a8eb14bc"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11209,6 +11219,11 @@
       "mode": "0000644",
       "sha256": "9d16748bfadb1b13969613bd7a43bed42ea3e1bdcc7254ab26fba14ea8b4c036"
     },
+    {
+      "path": "tests/dependency_advisory.mjs",
+      "mode": "0000644",
+      "sha256": "9141b1e9544eceeaf94d5156a4c150236db7011f769dafec9a70f5fd5f51bc25"
+    },
     {
       "path": "tests/deploy_audit_gate.mjs",
       "mode": "0000644",
@@ -12774,6 +12789,11 @@
       "mode": "0000644",
       "sha256": "1da3144c843ebcacc914f8ccc6e4e0578b2efc40bd3d2feb99d3665989923512"
     },
+    {
+      "path": "tests/missing_dep_classify.mjs",
+      "mode": "0000644",
+      "sha256": "0bd80e5c2a08bf90509563a878cceea2485d7755022f7818f036c37fe60a32e6"
+    },
     {
       "path": "tests/model_alloc_prefs.mjs",
       "mode": "0000644",

package/.claude/skills/goal-create/SKILL.md

@@ -153,6 +153,14 @@ Run the phases above **with the orphan task as the seed** — its title, descrip
 
 **A goal-less task is not an error and was never blocked.** `goal_advisory` is advice on a request that already succeeded. Never fail a build, refuse work, or badger the builder over it — if they say "later", file the idea and move on.
 
+## The sibling advisory: `dependency_advisory` (task 1002827)
+
+The same `POST /tasks` response can also carry a non-null **`dependency_advisory`** — a *different* check, unrelated to which goal the task landed in: it names OPEN tasks in the same version whose `touches[]` overlap this one's, with no declared dependency between them (`scripts/gds/audit-deps.js`'s detector, run live for the first time).
+
+- `dependency_advisory.candidates` is sorted by confidence (`high`/`medium`/`low`) — read each candidate's title before acting; most overlap is parallel work on a shared file, not a real build-order dependency.
+- Only backfill a **high**-confidence candidate, and only after reading both task descriptions. Add the edge with `POST /tasks/<id>/dependencies --body '{"depends_on_task_id":<dep_id>}'`.
+- **Same non-blocking contract as `goal_advisory`** — it is advice on a request that already succeeded, never a reason to redo the create, and a wrong edge GATES the dependent (`POST /claims` → 409 `DEPS_NOT_SHIPPED`) until the named blocker ships, so silence (skip it) beats a guessed edge.
+
 ## Why we run this
 
 Nothing in the system creates a goal on its own, and nothing errors when a task has none. `db.createTask` falls back to the version's `"<version> — general"` catch-all, and those rows were created **only** by migration 160, for the versions that existed at that moment — `db.createVersion` makes no such goal and there is no trigger. So on any newer version, every task quietly gets `goal_id = NULL`: no scope wall, no criteria gating it, no workspace where anyone reviews it. This skill is how a real goal comes to exist before that happens.

package/.claude/skills/goal-review/SKILL.md

@@ -96,6 +96,14 @@ Report to the user:
 - Deferred (count + ids — these surface again next session)
 - New queue `count`
 
+**Step 6 — dependency check (task 1002827, idea 1000276).** A cheap housekeeping pass over the same corpus this session already has open: run the likely-missing-dependency detector and surface any `high`-confidence candidate for a human to triage.
+
+```
+node scripts/gds/audit-deps.js --min high
+```
+
+Each line names an open task and an unshipped task whose files it overlaps with no declared dependency between them. **Read both task descriptions before backfilling an edge** — most overlap is parallel work on a shared file, not a build order; a wrong edge gates the dependent (`POST /claims` → 409 `DEPS_NOT_SHIPPED`) until the named blocker ships. Report the count in the same summary as Step 5; zero is the common case and needs no further comment. This is advisory only — it never blocks the review, and skipping it on a rushed pass is fine (it resurfaces next session, same as a deferred criterion).
+
 ## Why we run this
 
 Without a closing cadence, criteria pile up "done but unconfirmed" and goals never flip to achieved — the version looks perpetually in-progress even when the work has shipped. A fast pass keeps the rollup honest. As with `/idea-triage`, the cadence is the discipline; a quick walk with mostly defers beats skipping it.

package/docs/module-api-changelog.md

@@ -2426,5 +2426,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.974 with no explicit bump. run 35871083707. (task 1002620)
   1.19.976 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.975 with no explicit bump. run 35878415178. (task 1002620)
+  1.19.977 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.976 with no explicit bump. run 35880930697. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-tasks.js

@@ -765,6 +765,48 @@ async function listTasks({ versionId, status, kind, discipline, goalId, createdB
   return rows;
 }
 
+// task 1002827 — the candidate pool for the dependency advisory (POST /tasks'
+// `dependency_advisory` + the periodic sweep): OPEN tasks in this version that
+// carry touches[], the same OPEN set scripts/gds/audit-deps.js already treats
+// as "auditable" (ready, backlog, active, blocked). Bounded and cheap —
+// measured 2026-09-22, BONGOS-V2 carries ~51 such rows, since most tasks
+// declare no touches[] at all (ADR 0049 demoted the field to advisory, so
+// most authors skip it). `dependencies` is not selected: it lives in a join
+// table, not this one (see addTaskDependency), and this advisory only needs
+// the NEW task's own declared deps, supplied by its caller.
+//
+// VISIBILITY (ADR 0112's leak rule — the goal-graph.js precedent). A task's
+// title and touched paths are exactly the "prose" that rule protects: a task
+// under a PRIVATE goal the caller neither manages nor is a member of is
+// EXCLUDED here, not merely redacted — unlike the graph, this advisory has
+// no structural need to keep an invisible node in the picture (omitting a
+// candidate says nothing false; it just offers no advice about it). A
+// goal-less task carries no visibility concern (`t.goal_id IS NULL`).
+// `LIMIT` bounds the candidate count so a growing corpus cannot turn
+// classify()'s O(|a|×|b|) pairwise scan (dependency-advisory.js) into an
+// unbounded synchronous cost on this write path.
+const DEPENDENCY_ADVISORY_CANDIDATE_LIMIT = 200;
+async function listOpenTasksWithTouches(versionId, excludeId, { viewerId = null, viewerIsArchon = false } = {}) {
+  const { rows } = await pool.query(
+    `SELECT t.id, t.title, t.status, t.touches
+       FROM tasks t
+       LEFT JOIN goals g ON g.id = t.goal_id
+       LEFT JOIN goal_members gm ON gm.goal_id = g.id AND gm.builder_id = $4::bigint
+      WHERE t.version_id = $1
+        AND t.status = ANY($2::text[])
+        AND t.touches <> '{}'
+        AND ($3::bigint IS NULL OR t.id <> $3)
+        AND (t.goal_id IS NULL
+             OR g.visibility IS DISTINCT FROM 'private'
+             OR $5::boolean
+             OR gm.builder_id IS NOT NULL)
+      ORDER BY t.id
+      LIMIT ${DEPENDENCY_ADVISORY_CANDIDATE_LIMIT}`,
+    [versionId, ['ready', 'backlog', 'active', 'blocked'], excludeId, viewerId, viewerIsArchon]
+  );
+  return rows;
+}
+
 // Tasks that are ready, unblocked, and have no touches[] overlap
 // with currently active claims. Excludes tasks already claimed by this
 // builder (so the same builder doesn't see their own active claim listed
@@ -1269,6 +1311,7 @@ module.exports = {
   listActiveClaims,
   listClaimableTasks,
   listOpenArtistReviews,
+  listOpenTasksWithTouches,
   listTasks,
   promoteUnblockedBacklogTasks,
   rankCrossDisciplineRecommendations,

package/modules/lifecycle/dependency-advisory.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// modules/lifecycle/dependency-advisory.js — the MISSING-DEPENDENCY advisory
+// (task 1002827, goal 1000089).
+//
+// THE HOLE. scripts/gds/audit-deps.js has shipped a working
+// likely-missing-dependency detector since task 1000349 (unit-tested,
+// tests/audit_deps.mjs, tests/missing_dep_classify.mjs) — and nothing ever
+// called it. A task can be created touching the exact same files an
+// unshipped task already claims, with no declared dependency between them,
+// and nothing says so until a human happens to run the CLI by hand.
+//
+// This module wires that SAME detector's predicate —
+// modules/lifecycle/missing-dep-classify.js's `candidateEdge`/`classify`,
+// not a second copy of either — into two surfaces, mirroring
+// goal-advisory.js's own two-surface shape (task 1002539):
+//   1. POST /tasks attaches `dependency_advisory` to its 201 body (this
+//      file's `buildDependencyAdvisory`), read by the /goal-create skill's
+//      "sibling advisory" section (.claude/skills/goal-create/SKILL.md).
+//   2. The periodic sweep: `/goal-review`'s daily walk runs
+//      `node scripts/gds/audit-deps.js --min high` as one more housekeeping
+//      step (idea 1000276's half — see .claude/skills/goal-review/SKILL.md).
+//
+// HARD CONSTRAINT, same as goal-advisory.js and ADR 0162: advisory only. This
+// must never refuse a POST, and `buildDependencyAdvisory` swallows its own
+// failures for the same reason goal-advisory.js's does — the task row is
+// ALREADY COMMITTED by the time this runs, so a throw here would turn a
+// successful create into a 500 the caller then retries.
+//
+// VISIBILITY (ADR 0112's leak rule, the goal-graph.js precedent) — enforced
+// in the query, not here: `db.listOpenTasksWithTouches` excludes a candidate
+// under a PRIVATE goal the caller neither manages nor belongs to, so this
+// file never even sees a task it should not name in a 201 body.
+//
+// PURE core (`adviseDependencies`) + a DB-read wrapper, the criterion-suggest /
+// goal-advisory precedent, so every branch is pinned by a DB-free unit test.
+
+const { candidateEdge } = require('./missing-dep-classify.js');
+
+// How many candidates the advisory offers. Small on purpose (the
+// goal-advisory.js CANDIDATE_LIMIT precedent) — this is a hint for the author
+// to triage, not a browsable report; the full corpus scan already exists as
+// `node scripts/gds/audit-deps.js` for that. Separate from (and much smaller
+// than) db.listOpenTasksWithTouches's own query-side LIMIT, which bounds cost
+// rather than display.
+const CANDIDATE_LIMIT = 5;
+
+// adviseDependencies — PURE. `task` is the just-created (or just-fetched) row,
+// `candidates` is the OPEN-with-touches, visibility-filtered pool a caller
+// already fetched. Returns null when there is nothing worth naming (fail-open
+// on ambiguity, same posture as adviseGoal): no touches[] on the task at all,
+// or no candidate clears the shared classify() confidence bar.
+function adviseDependencies({ task, candidates = [] } = {}) {
+  if (!task || !Array.isArray(task.touches) || !task.touches.length) return null;
+  const declared = new Set((task.dependencies || []).map(String));
+  const edges = [];
+  for (const o of candidates) {
+    const e = candidateEdge(task, o, { declared });
+    if (e) edges.push({ dep_id: e.dep_id, dep_title: (o && o.title) || null, dep_status: e.dep_status, confidence: e.confidence, paths: e.paths });
+  }
+  if (!edges.length) return null;
+  const order = { high: 3, medium: 2, low: 1 };
+  edges.sort((a, b) => order[b.confidence] - order[a.confidence]);
+  return {
+    reason: 'possible_missing_dependency',
+    message: `${edges.length} open task(s) touch the same files as this one and are not declared `
+      + 'dependencies — most touches[] overlap is parallel work on a shared surface, not a build-order '
+      + 'dependency, so read each candidate before adding an edge (a wrong one gates the claim).',
+    candidates: edges.slice(0, CANDIDATE_LIMIT),
+  };
+}
+
+// buildDependencyAdvisory — the whole advisory, DB read included, so POST
+// /tasks calls one line (the buildGoalAdvisory precedent). Fails open: any
+// throw degrades to null rather than failing an otherwise-successful create.
+// `viewerId`/`viewerIsArchon` ride straight into the query's own visibility
+// filter — this file never post-filters what the query already excluded.
+async function buildDependencyAdvisory({ db, versionId, task, viewerId = null, viewerIsArchon = false }) {
+  try {
+    if (!Array.isArray(task.touches) || !task.touches.length) return null;
+    const candidates = await db.listOpenTasksWithTouches(versionId, task.id, { viewerId, viewerIsArchon });
+    const verdict = adviseDependencies({ task, candidates });
+    if (!verdict) return null;
+    return {
+      ...verdict,
+      next_step: 'Review each candidate; if it is a real build-order dependency, add it via '
+        + `POST /tasks/${task.id}/dependencies.`,
+    };
+  } catch (e) {
+    // Through the published logger seam (api.logger), not a raw console call
+    // — the est-advisory.js precedent. Lazy-required so the DB-free unit test
+    // that exercises this branch stays hermetic.
+    require('../../src/module-api').logger('lifecycle')
+      .error('dependency-advisory (non-blocking)', e && e.message);
+    return null;
+  }
+}
+
+module.exports = { adviseDependencies, buildDependencyAdvisory, CANDIDATE_LIMIT };

package/modules/lifecycle/missing-dep-classify.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// modules/lifecycle/missing-dep-classify.js — the PURE core of the
+// likely-missing-dependency detector (task 349, moved here from
+// scripts/gds/audit-deps.js by task 1002827 so a live route can reuse it
+// without pulling in that script's CLI-only machinery — cliClient(),
+// resolveDefaultVersion() — into the server process. The `dead-deps.js`
+// precedent beside this file: a pure lifecycle module, consumed both by the
+// audit-deps.js CLI (its --stranded arm) and now by dependency-advisory.js's
+// live POST /tasks path.
+//
+// THIS IS ADVISORY. Most touches[] overlaps are PARALLEL work on a shared
+// surface (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. Reuses
+// the ONE canonical overlap matcher (src/bongos/path-match.touchesOverlap,
+// reached via the module-api doorway) so it can't drift from the claim
+// gate's notion of "overlap".
+
+const api = require('../../src/module-api');
+const { touchesOverlap } = api.pathMatch;
+
+// 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 };
+}
+
+// candidateEdge — THE ONE predicate for "does `o` qualify as a missing-dependency
+// candidate for `t`", pulled out (task 1002827 grade round 1) so findMissingDeps
+// and dependency-advisory.js's live adviseDependencies call the SAME check
+// instead of two hand-typed copies that can drift on the next rule change.
+// `declared` is precomputed and passed in by findMissingDeps (one Set per `t`,
+// not per pair); a caller checking a single `t` against many candidates may
+// omit it and pay one Set build instead. Runs `classify` exactly ONCE — it
+// already returns null on no overlap, so a separate touchesOverlap pre-check
+// was dead work computing the same answer twice.
+function candidateEdge(t, o, { isBlocker = isUnshippedBlocker, declared } = {}) {
+  if (!o || String(o.id) === String(t.id)) return null;
+  if (!isBlocker(o.status)) return null;
+  if (!Array.isArray(o.touches) || !o.touches.length) return null;
+  const declaredSet = declared || new Set(((t && t.dependencies) || []).map(String));
+  if (declaredSet.has(String(o.id))) return null;
+  if (!Array.isArray(t.touches) || !t.touches.length) return null;
+  const c = classify(t.touches, o.touches);
+  if (!c) return null;
+  return { task_id: t.id, dep_id: o.id, dep_status: o.status, ...c };
+}
+
+// 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) {
+      const e = candidateEdge(t, o, { isBlocker, declared });
+      if (e) out.push(e);
+    }
+  }
+  return out;
+}
+
+module.exports = { OPEN, isUnshippedBlocker, HOTSPOTS, isHotspot, classify, candidateEdge, findMissingDeps };

package/modules/lifecycle/routes/task-write-routes.js

@@ -22,6 +22,7 @@ const db = require('../db');
 const hierarchy = require('../hierarchy');
 const { suggestCriteria } = require('../criterion-suggest');
 const { buildGoalAdvisory } = require('../goal-advisory');
+const { buildDependencyAdvisory } = require('../dependency-advisory');
 const { classifyTaskKind, VALID_KINDS, WRITABLE_DISCIPLINES, resolveWriteDiscipline, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
 const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
@@ -282,13 +283,21 @@ module.exports = function registerTaskWriteRoutes(router) {
       const goal_advisory = await buildGoalAdvisory({
         db, versionId: body.version_id, task, hasCriterionLink: criteria.length > 0,
       });
+      // task 1002827 — the missing-dependency advisory (scripts/gds/audit-deps.js's
+      // detector, wired live for the first time): OPEN tasks in this version that
+      // touch the same files as this one and are not declared dependencies.
+      // Non-blocking by construction — see dependency-advisory.js.
+      const dependency_advisory = await buildDependencyAdvisory({
+        db, versionId: body.version_id, task,
+        viewerId: req.builder.id, viewerIsArchon: req.builder.rank === 'archon',
+      });
       res.status(201).json({
         task,
         credits_reward: task.credits_reward,
         needs_migration: needsMigration,
         criteria,
         suggested_criteria,
-        goal_advisory, est_advisory: await require('../est-advisory').buildEstAdvisory({ db, task }), // task 1003148
+        goal_advisory, dependency_advisory, est_advisory: await require('../est-advisory').buildEstAdvisory({ db, task }), // task 1003148
       });
     } catch (err) {
       log.error('[gds] POST /tasks', err);

package/package-lock.json

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

package/tests/missing_dep_classify.mjs

@@ -0,0 +1,108 @@
+// tests/missing_dep_classify.mjs — the PURE missing-dependency detector core
+// (task 1002827), moved out of scripts/gds/audit-deps.js so a live route can
+// reuse it without pulling that script's CLI-only machinery into the server
+// process.
+//
+// tests/audit_deps.mjs already pins findMissingDeps/classify's BEHAVIOR
+// (unchanged by the move — it still imports them from audit-deps.js, which
+// now re-exports this module's names). This file instead pins the three
+// things that changed or were added: the module boundary (a module may reach
+// touchesOverlap only through the src/module-api.js doorway, never a deep
+// core require), the pure surface being intact post-move, and `candidateEdge`
+// — the ONE per-pair predicate findMissingDeps and dependency-advisory.js's
+// live adviseDependencies both call now, so neither re-types it.
+//
+// Run: node tests/missing_dep_classify.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { OPEN, isUnshippedBlocker, HOTSPOTS, classify, candidateEdge, findMissingDeps } =
+  require('../modules/lifecycle/missing-dep-classify.js');
+
+const { test, summary } = makeRunner();
+
+await test('OPEN names exactly the four auditable statuses', () => {
+  assert.deepEqual([...OPEN].sort(), ['active', 'backlog', 'blocked', 'ready']);
+});
+
+await test('isUnshippedBlocker: only shipped/abandoned are terminal', () => {
+  assert.equal(isUnshippedBlocker('shipped'), false);
+  assert.equal(isUnshippedBlocker('abandoned'), false);
+  assert.equal(isUnshippedBlocker('ready'), true);
+  assert.equal(isUnshippedBlocker('backlog'), true);
+});
+
+await test('classify: an exact non-hotspot file match is high confidence', () => {
+  const c = classify(['modules/foo/bar.js'], ['modules/foo/bar.js']);
+  assert.equal(c.confidence, 'high');
+});
+
+await test('classify: a hotspot-only overlap is low confidence', () => {
+  const c = classify(['CLAUDE.md'], ['CLAUDE.md']);
+  assert.equal(c.confidence, 'low');
+});
+
+await test('classify: no overlap at all returns null', () => {
+  assert.equal(classify(['a.js'], ['b.js']), null);
+});
+
+await test('findMissingDeps re-exported unchanged: a live example still flags', () => {
+  const tasks = [
+    { id: 1, status: 'ready', touches: ['modules/x/y.js'], dependencies: [] },
+    { id: 2, status: 'backlog', touches: ['modules/x/y.js'], dependencies: [] },
+  ];
+  assert.equal(findMissingDeps(tasks).length, 2);
+});
+
+// ---- candidateEdge: the ONE per-pair predicate, shared by findMissingDeps
+// and dependency-advisory.js's adviseDependencies (grade round 1 finding) ----
+
+await test('candidateEdge: an overlapping open non-dep is a real edge', () => {
+  const e = candidateEdge(
+    { id: 1, touches: ['modules/x/y.js'] },
+    { id: 2, status: 'ready', touches: ['modules/x/y.js'] },
+  );
+  assert.equal(e.task_id, 1);
+  assert.equal(e.dep_id, 2);
+  assert.equal(e.confidence, 'high');
+});
+
+await test('candidateEdge: null on self, terminal status, no touches, or an already-declared dep', () => {
+  const t = { id: 1, touches: ['a.js'], dependencies: ['2'] };
+  assert.equal(candidateEdge(t, { id: 1, status: 'ready', touches: ['a.js'] }), null, 'self');
+  assert.equal(candidateEdge(t, { id: 3, status: 'shipped', touches: ['a.js'] }), null, 'terminal');
+  assert.equal(candidateEdge(t, { id: 3, status: 'ready', touches: [] }), null, 'no touches');
+  assert.equal(candidateEdge(t, { id: 2, status: 'ready', touches: ['a.js'] }), null, 'already declared');
+});
+
+await test('candidateEdge: an explicit `declared` set is used instead of re-deriving from t.dependencies', () => {
+  const t = { id: 1, touches: ['a.js'], dependencies: [] };
+  const e = candidateEdge(t, { id: 2, status: 'ready', touches: ['a.js'] }, { declared: new Set(['2']) });
+  assert.equal(e, null, 'the passed-in declared set wins over the empty t.dependencies');
+});
+
+await test('candidateEdge runs classify exactly once — no separate touchesOverlap pre-check to duplicate', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/missing-dep-classify.js', import.meta.url), 'utf8');
+  const body = src.slice(src.indexOf('function candidateEdge'), src.indexOf('function findMissingDeps'));
+  assert.equal((body.match(/classify\(/g) || []).length, 1, 'exactly one classify() call in candidateEdge');
+  assert.equal(/touchesOverlap\(/.test(body), false, 'no redundant overlap pre-check — classify already answers that');
+});
+
+await test('the module reaches touchesOverlap through the module-api doorway, never a deep core require', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/missing-dep-classify.js', import.meta.url), 'utf8');
+  assert.match(src, /require\('\.\.\/\.\.\/src\/module-api'\)/, 'reaches core via the doorway');
+  assert.equal(/require\(['"]\.\.\/\.\.\/src\/bongos\//.test(src), false, 'never a direct src/bongos/* require (ADR 0083)');
+});
+
+await test('scripts/gds/audit-deps.js delegates to this module rather than redefining the pure core', () => {
+  const src = readFileSync(new URL('../scripts/gds/audit-deps.js', import.meta.url), 'utf8');
+  assert.match(src, /require\('\.\.\/\.\.\/modules\/lifecycle\/missing-dep-classify\.js'\)/);
+  assert.equal(/^function classify/m.test(src), false, 'classify is no longer redefined here');
+  assert.equal(/^function findMissingDeps/m.test(src), false, 'findMissingDeps is no longer redefined here');
+});
+
+summary();