@bongos/core 1.19.282 → 1.19.284

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.282",
-  "core_contract": "1.19.282",
-  "source_commit": "06b7fb133710f33da97b1acf2ae417fe5ef6dfdf",
+  "core_version": "1.19.284",
+  "core_contract": "1.19.284",
+  "source_commit": "89eca5541c7cbfd95d598c46ba3a46f3ddc20827",
   "source_ref": "HEAD",
-  "built_at": "2026-08-21T21:00:51.271Z",
+  "built_at": "2026-08-21T22:01:22.829Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 319,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1380,
+    "functional_verbatim": 1382,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1721,
-  "tree_sha256": "beb62a53ae222fa7eef0b86c08c3ab454e41a66cfee904bd98c8a92ac8518d2e",
+  "file_count": 1723,
+  "tree_sha256": "271e5d408254a1834d4f24731b48a02ae7867dcfa154fbef7e3f1c7a98581bc1",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -3769,6 +3769,11 @@
       "mode": "0000644",
       "sha256": "74eedb9ee1c423c9ecdea6f09d8555fa3200ac9e3a86a194182774cb72f0cd0b"
     },
+    {
+      "path": "modules/lifecycle/dead-deps.js",
+      "mode": "0000644",
+      "sha256": "e083c4849b4f2e9e7fe25d6c0e7857c15412b7308bca7f5a8f74e71b5c36df84"
+    },
     {
       "path": "modules/lifecycle/done-when.js",
       "mode": "0000644",
@@ -3847,7 +3852,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "e02abac52a82fb02603dd92074d4ebd060ec03195803d704b021614806ef00fe"
+      "sha256": "b67f879dea205dd442685df384b8e8060a01b8caa34efc74e31253e556acfb25"
     },
     {
       "path": "modules/lifecycle/routes/dependencies.js",
@@ -4502,12 +4507,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "c81721f73d06dd3daab990c030c868a4cc63b463e4bf53722f82f7e7bd64e4ef"
+      "sha256": "d95061f94ca54af0ae3fb5631e87f8df10516b82c5f79c9214adb741ad6b6e02"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7be55d325cccc29714cdfc5e19acf3cd463e2dc58cdee6b3e8c8c7c4e08bece3"
+      "sha256": "958156249f9977ba6e0fa7584290663dc05f01627651b985050c030c42e37b9f"
     },
     {
       "path": "public-docs/index.html",
@@ -4832,7 +4837,7 @@
     {
       "path": "scripts/gds/abandon.js",
       "mode": "0000644",
-      "sha256": "226e266390bd7eac3c10526557427a3b1e7916749ad64dda2a7163c4fac43a74"
+      "sha256": "67e9a8dead2b0ea75f6011fd687a3db56a12df945a77f430eec2602a0ecac07c"
     },
     {
       "path": "scripts/gds/adopt-detect.js",
@@ -4877,7 +4882,7 @@
     {
       "path": "scripts/gds/audit-deps.js",
       "mode": "0000644",
-      "sha256": "6392f1b445685b1ec8de134191301ab475ee7d4fc3a9557494a9723d18fa3bcf"
+      "sha256": "84275f8b3c8981717c1648f346954a55742a0fecd2f6617257c4f77894609e12"
     },
     {
       "path": "scripts/gds/audit-exports.js",
@@ -4982,7 +4987,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "3e830a3e319c4b67d87547ae4ad2d647ee3ce74725c84d7f64788c094f0974c7"
+      "sha256": "528e0fd4a91933cab751524f4a0c930dd0f23945801538182343faacf02d9ef7"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -6152,7 +6157,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b19f1a794e05fa5029e67696eed1cf9f84e80453702ad9db3902e4080d40e877"
+      "sha256": "3408611b1d5426f7cfa78a23db5309455664b4ac644804932e0524b9f29097a5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6769,6 +6774,11 @@
       "mode": "0000644",
       "sha256": "4555a337ce7d795fbda7e463f4a33774583dd17c8c81af83b928cf0057823427"
     },
+    {
+      "path": "tests/dead_deps.mjs",
+      "mode": "0000644",
+      "sha256": "07d2825c812a10cd1d39182883652dec15d360d3645dd38023a00a0593d36ddc"
+    },
     {
       "path": "tests/dependencies_migration.mjs",
       "mode": "0000644",

package/modules/lifecycle/dead-deps.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// modules/lifecycle/dead-deps.js — a DEAD dependency edge: one that can never
+// satisfy, because the task it points at was abandoned (task 1003153).
+//
+// THE DEFECT THIS EXISTS FOR. Both dependency gates treat 'abandoned' as
+// unfinished work rather than cut work:
+//   - unsatisfiedDeps (db.js) — `WHERE x.status <> 'shipped'` — the
+//     DEPS_NOT_SHIPPED claim refusal, on all three claim paths.
+//   - task_is_fully_unblocked (migrations/163, replaced by 178) —
+//     `AND x.status = 'shipped'` — the auto-promotion trigger predicate.
+// So an abandoned dependency strands its dependents permanently: they never
+// auto-promote out of backlog, and a hand-promoted one cannot be claimed.
+//
+// OWNER RULING (2026-08-21): that strictness STAYS. A cut prerequisite must force
+// a deliberate human re-scope of the edge, not silently let dependent work
+// proceed on something that was never built. This file does NOT relax either
+// gate — it makes the refusal HONEST and the situation OBSERVABLE, which is the
+// actual bug: the CLI used to answer a dead edge with "Ship those first (or
+// release them) and try again", advice that can never be followed.
+//
+// Pure + DB-free so the CLI (scripts/gds/claim.js), the route
+// (modules/lifecycle/routes/claims.js) and the detector (scripts/gds/audit-deps.js)
+// all speak from ONE definition — the goal-authz.js precedent.
+
+// The one terminal task status that can gate a dependency edge. 'shipped' is the
+// satisfying end; 'abandoned' is the OTHER terminal end (migration 017's family:
+// "abandoned is a terminal state (deliberately cut), not pending work"), and it
+// is the one that can never satisfy. Kept as a set so a future terminal status
+// (none today — the tasks.status CHECK in migration 012 has exactly these eight)
+// is one edit, not a grep.
+const DEAD_DEP_STATUSES = new Set(['abandoned']);
+
+// Which of these unmet dependency rows are DEAD (never-satisfiable) vs merely
+// PENDING? `deps` are the DEPS_NOT_SHIPPED rows: { kind, id, title, status }.
+// Only task-kind edges can be dead — a criterion is unsatisfied-not-cut, and a
+// goal is unachieved-not-cut, both of which can still resolve.
+function splitDeadDeps(deps) {
+  const all = Array.isArray(deps) ? deps : [];
+  const dead = all.filter((d) => d && (d.kind === 'task' || d.kind === undefined)
+    && DEAD_DEP_STATUSES.has(String(d.status || d.state || '')));
+  const deadIds = new Set(dead.map((d) => String(d.id)));
+  return { dead, pending: all.filter((d) => !deadIds.has(String(d && d.id))) };
+}
+
+// The way-forward line for a refusal that includes at least one dead edge.
+// Names the TWO remedies that actually exist, and never tells anyone to ship an
+// abandoned task:
+//   - DROP the dead edge — DELETE /dependencies with the 4-tuple body
+//     { from_kind:'task', from_id:<this task>, to_kind:'task', to_id:<dead dep> }
+//     (routes/dependencies.js:69; needs dependency.cross_tier.manage).
+//   - RESTORE the dependency — POST /tasks/:id/promote, whose restore branch
+//     (db.restoreTask) returns an abandoned task to backlog at the same rank.
+// Returns null when nothing is dead, so callers keep their existing wording.
+// `taskId` is the DEPENDENT (optional) so the drop remedy can be spelled out
+// concretely rather than left as a shape to figure out.
+function deadDepHint(deps, taskId = null) {
+  const { dead, pending } = splitDeadDeps(deps);
+  if (dead.length === 0) return null;
+  const names = dead.map((d) => `task ${d.id}`).join(', ');
+  const first = dead[0].id;
+  const tuple = `{"from_kind":"task","from_id":${taskId ?? '<this task>'},"to_kind":"task","to_id":${first}}`;
+  return `${dead.length === 1 ? 'A dependency was ABANDONED' : `${dead.length} dependencies were ABANDONED`} (${names}) — `
+    + 'that edge can NEVER satisfy, so this task is STRANDED, not waiting. '
+    + 'An abandoned dependency is a top-priority thing to resolve deliberately; do not wait for it. '
+    + `Either DROP the dead edge (DELETE /api/bongos/dependencies with body ${tuple}) `
+    + `or RESTORE the dependency (POST /api/bongos/tasks/${first}/promote returns an abandoned task to backlog).`
+    + (pending.length ? ` ${pending.length} other dependenc${pending.length === 1 ? 'y is' : 'ies are'} still genuinely pending.` : '');
+}
+
+// Detector core (scripts/gds/audit-deps.js --stranded): which LIVE tasks are
+// gated by an abandoned dependency? `tasks` are rows carrying { id, status,
+// title, blocked_by: [{ id, status, title }] } — the GET /tasks?include=deps
+// shape. A dependent that is itself terminal is NOT stranded (nothing is
+// waiting), which is why the live corpus reports zero today even though 17
+// abandoned tasks still carry dependents. Pure + exported for tests.
+const LIVE_STATUSES = new Set(['backlog', 'ready', 'active', 'blocked']);
+
+function findStrandedTasks(tasks) {
+  const out = [];
+  for (const t of Array.isArray(tasks) ? tasks : []) {
+    if (!t || !LIVE_STATUSES.has(String(t.status))) continue;
+    const dead = (t.blocked_by || []).filter((d) => d && DEAD_DEP_STATUSES.has(String(d.status)));
+    if (dead.length) {
+      out.push({
+        task_id: t.id,
+        status: t.status,
+        title: t.title,
+        dead_deps: dead.map((d) => ({ id: d.id, title: d.title, status: d.status })),
+      });
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  DEAD_DEP_STATUSES, LIVE_STATUSES,
+  splitDeadDeps, deadDepHint, findStrandedTasks,
+};

package/modules/lifecycle/routes/claims.js

@@ -9,6 +9,9 @@ const db = require('../db');
 // never a direct require of a module file. The doorway re-exports the seam fns.
 const seams = api;
 const { validateOrRespond, LIMITS, parseId } = api;
+// task 1003153: the DEAD dependency edge (a dep that was abandoned, so can never
+// satisfy) — one pure definition shared with the CLI + the detector.
+const { deadDepHint, splitDeadDeps } = require('../dead-deps.js');
 
 // V3.R33 (#254): input validation guards. Length caps + shape checks at the
 // top of every write handler. Schemas describe KNOWN-field constraints only —
@@ -325,6 +328,20 @@ module.exports = function buildClaimsRouter() {
           const names = (err.blockers || []).map((b) => `blocker ${b.id} ("${b.title}")`);
           err.hint = `This task is waiting on ${names.join(', ') || 'an open blocker'}. Resolve it first (/blocker-solve N drives one to done; resolving auto-promotes its linked tasks) — or pick another task from /builder-start.`;
         }
+        // task 1003153: a DEPS_NOT_SHIPPED whose unmet set includes an ABANDONED
+        // task is not "waiting" — that edge can never satisfy, so the task is
+        // stranded. Say so and name the two real remedies (drop the edge, or
+        // restore the dep); the old silence let the CLI advise "ship those
+        // first", which is impossible for a cut task. The gate itself stays
+        // strict (owner ruling) — this only makes the refusal honest. `dead_deps`
+        // rides the body so the hall and any other client can render it too.
+        if (err.code === 'DEPS_NOT_SHIPPED') {
+          const hint = deadDepHint(err.deps, Number(taskId));
+          if (hint) {
+            err.hint = hint;
+            err.dead_deps = splitDeadDeps(err.deps).dead;
+          }
+        }
         return res.fail(err.code, status, { ...err });
       }
       console.error('[gds] POST /claims', err);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.282",
+  "version": "1.19.284",
   "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/abandon.js

@@ -18,6 +18,9 @@
 // restores it to backlog at the same rank (db.restoreTask) — no Archon SQL needed.
 
 const { cliClient, requireSession, arg } = require('./cli-lib');
+// task 1003153 — the live-status set, shared with the dead-edge detector so
+// "who did this cut strand" means the same thing in both places.
+const { LIVE_STATUSES } = require('../../modules/lifecycle/dead-deps.js');
 
 
 (async () => {
@@ -54,6 +57,28 @@ const { cliClient, requireSession, arg } = require('./cli-lib');
     console.log(`Abandoned task #${r.data.taskId}: ${r.data.taskTitle}`);
     console.log(`Status: ${r.data.previousStatus} -> abandoned.`);
   }
+
+  // task 1003153 — REPORT what this cut just stranded. An abandoned task can
+  // never ship, so every LIVE task depending on it is now permanently gated:
+  // it will not auto-promote (task_is_fully_unblocked wants status='shipped')
+  // and cannot be claimed (DEPS_NOT_SHIPPED). Per the owner ruling the gate
+  // stays strict, which makes surfacing this at cut time the whole remedy —
+  // the edge needs a deliberate decision, and the person cutting the task is
+  // the one who knows. Best-effort: never fail an abandon over the report.
+  try {
+    const dep = await api.tasks.getTasksId({ id: taskId, query: { include: 'deps' } });
+    const dependents = (dep?.data?.task?.blocks || []).filter((b) => LIVE_STATUSES.has(String(b.status)));
+    if (dependents.length) {
+      console.log('');
+      console.log(`⚠ TOP PRIORITY — this cut just STRANDED ${dependents.length} live task(s) that depend on #${taskId}:`);
+      for (const b of dependents) console.log(`    #${b.id}  [${b.status}]  ${b.title}`);
+      console.log('  They can never auto-promote or be claimed while this edge stands, because an');
+      console.log('  abandoned task can never ship. Resolve each edge deliberately — do not leave it:');
+      console.log(`    drop the edge:    node scripts/gds/api.js DELETE /api/bongos/dependencies --body '{"from_kind":"task","from_id":<dependent>,"to_kind":"task","to_id":${taskId}}'`);
+      console.log(`    or restore this:  node scripts/gds/api.js POST /api/bongos/tasks/${taskId}/promote`);
+      console.log('  Sweep for any you miss:  node scripts/gds/audit-deps.js --stranded');
+    }
+  } catch (_) { /* the abandon already landed — the report is advisory */ }
 })().catch((err) => {
   console.error('fatal:', err);
   process.exit(1);

package/scripts/gds/audit-deps.js

@@ -17,9 +17,13 @@
 // gate's notion of "overlap".
 //
 //   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)
 
 const { touchesOverlap } = require('../../src/bongos/path-match.js');
 const { cliClient } = require('./cli-lib');
+// task 1003153 — the DEAD-edge detector core, shared with the claim refusal so
+// "abandoned dependency" means one thing across the CLI, the route and this audit.
+const { findStrandedTasks } = require('../../modules/lifecycle/dead-deps.js');
 
 // Lifecycle statuses that count as "open" (auditable) vs "an unshipped blocker".
 const OPEN = new Set(['ready', 'backlog', 'active', 'blocked']);
@@ -76,8 +80,54 @@ function findMissingDeps(tasks, { open = OPEN, isBlocker = isUnshippedBlocker }
   return out;
 }
 
+// --stranded (task 1003153): the INVERSE audit. findMissingDeps asks "which edge
+// is MISSING"; this asks "which existing edge is DEAD" — a live task gated by an
+// ABANDONED dependency. That edge can never satisfy (an abandoned task can never
+// ship), so the dependent never auto-promotes and can never be claimed: stranded,
+// not waiting. Per the owner ruling (2026-08-21) the gates stay strict, which
+// makes this detector the remedy — an abandoned dependency must be REPORTED as a
+// top-priority thing to resolve rather than blocking silently and forever.
+// Exits 1 when anything is stranded, so a sweep or CI leg can gate on it.
+async function reportStranded({ asJson }) {
+  const api = await cliClient();
+  const r = await api.tasks.getTasks({ query: { include: 'deps', limit: 3000 } });
+  if (!r.ok) { console.error(`audit-deps: could not list tasks (${r.status})`); process.exit(1); }
+  const all = r.data.tasks || [];
+  const stranded = findStrandedTasks(all);
+
+  // Context worth stating even at zero: abandoned tasks that still CARRY
+  // dependents are the latent trap. They report clean only because every
+  // dependent happens to be terminal too — one promote would light them up.
+  const gatingAbandoned = new Set();
+  for (const t of all) for (const d of (t.blocked_by || [])) {
+    if (String(d.status) === 'abandoned') gatingAbandoned.add(String(d.id));
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ stranded, abandoned_deps_with_dependents: [...gatingAbandoned] }, null, 2));
+    return stranded.length ? 1 : 0;
+  }
+  console.log(`audit-deps --stranded: ${all.length} task(s) scanned — ${stranded.length} LIVE task(s) stranded by an abandoned dependency\n`);
+  for (const s of stranded) {
+    console.log(`[STRANDED] #${s.task_id} [${s.status}]  ${(s.title || '').slice(0, 70)}`);
+    for (const d of s.dead_deps) console.log(`           dead edge → #${d.id} [${d.status}]  ${(d.title || '').slice(0, 60)}`);
+    console.log(`           fix: drop the edge (DELETE /dependencies {"from_kind":"task","from_id":${s.task_id},"to_kind":"task","to_id":${s.dead_deps[0].id}})`);
+    console.log(`             or restore the dep (POST /tasks/${s.dead_deps[0].id}/promote)\n`);
+  }
+  if (!stranded.length) {
+    console.log('Nothing stranded — no live task is gated by an abandoned dependency.');
+    console.log(`Latent exposure: ${gatingAbandoned.size} abandoned task(s) still carry dependents; they read clean only`);
+    console.log('because those dependents are themselves terminal. Promoting one would strand it immediately.');
+  }
+  return stranded.length ? 1 : 0;
+}
+
 async function main() {
   const argv = process.argv.slice(2);
+  if (argv.includes('--stranded')) {
+    process.exitCode = await reportStranded({ asJson: argv.includes('--json') });
+    return;
+  }
   const ver = argv.includes('--version') ? argv[argv.indexOf('--version') + 1] : 'GDS-V3';
   const minRank = argv.includes('--min') ? argv[argv.indexOf('--min') + 1] : 'low';
   const asJson = argv.includes('--json');
@@ -114,7 +164,7 @@ async function main() {
   console.log('NB: advisory only. Backfill `high` edges by hand (POST /tasks/:id/dependencies) after reading both tasks; a wrong edge gates the dependent.');
 }
 
-module.exports = { findMissingDeps, classify, OPEN, isUnshippedBlocker, HOTSPOTS };
+module.exports = { findMissingDeps, classify, OPEN, isUnshippedBlocker, HOTSPOTS, reportStranded };
 
 if (require.main === module) {
   main().catch((e) => { console.error('audit-deps:', e.message); process.exit(1); });

package/scripts/gds/claim.js

@@ -15,6 +15,10 @@ const { nextNumbers, padAdr, padMig } = require('./next-number');
 const { CORE_NS } = require('./migration-namespace');
 const { contextPack, formatContextPack } = require('./context-pack');
 const { printClaimRecall } = require('./claim-recall');
+// task 1003153 — the DEAD dependency edge, one definition shared with the route
+// and the detector. A lifecycle CLI may require the lifecycle module directly
+// (the documented exception in modules/lifecycle/CLAUDE.md).
+const { splitDeadDeps, deadDepHint } = require('../../modules/lifecycle/dead-deps.js');
 
 // Fetch up to 3 learnings relevant to the task being claimed. touches[] cleanup
 // [3/8] (task 878): key off the task's discipline + title (always present) rather
@@ -260,9 +264,20 @@ function formatClaimFailure(r, taskId) {
     return { lines, exit: 1 };
   }
   if (code === 'DEPS_NOT_SHIPPED') {
-    lines.push(`Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
-    for (const dep of d.deps || []) lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}`);
-    lines.push('Ship those first (or release them) and try again.');
+    // task 1003153: an ABANDONED dependency can never ship, so "ship those
+    // first" was impossible advice — the task is STRANDED, not waiting. Mark the
+    // dead edges in the list and relay the server's hint (deadDepHint), which
+    // names the two real remedies. Falls back to the original wording when every
+    // unmet dep is genuinely still pending.
+    const dead = new Set(splitDeadDeps(d.deps).dead.map((x) => String(x.id)));
+    lines.push(dead.size
+      ? `Task #${taskId} is STRANDED — a dependency was abandoned and can never satisfy:`
+      : `Task #${taskId} can't be claimed yet — these dependencies are not shipped:`);
+    for (const dep of d.deps || []) {
+      const flag = dead.has(String(dep.id)) ? '  ← ABANDONED: this edge will never satisfy' : '';
+      lines.push(`  - #${dep.id}  [${dep.status}]  ${dep.title}${flag}`);
+    }
+    lines.push(d.hint || deadDepHint(d.deps, taskId) || 'Ship those first (or release them) and try again.');
     return { lines, exit: 1 };
   }
   if (code === 'OPEN_BLOCKER') {

package/src/module-api.js

@@ -991,8 +991,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.280 with no explicit bump. run 32525071763. (task 1002620)
 //   1.19.282 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.281 with no explicit bump. run 32526392955. (task 1002620)
+//   1.19.283 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.282 with no explicit bump. run 32527313879. (task 1002620)
+//   1.19.284 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.283 with no explicit bump. run 32531111199. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.282'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.284'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/dead_deps.mjs

@@ -0,0 +1,174 @@
+// tests/dead_deps.mjs — the DEAD dependency edge (task 1003153).
+//
+// A dependency on an ABANDONED task can never satisfy, because an abandoned task
+// can never ship. Both gates treat it as pending anyway (unsatisfiedDeps'
+// `<> 'shipped'`, and task_is_fully_unblocked's `= 'shipped'`), so the dependent
+// is STRANDED: it never auto-promotes and can never be claimed.
+//
+// OWNER RULING (2026-08-21): the gates STAY strict — a cut prerequisite must force
+// a deliberate re-scope, not silently release dependent work. So these tests pin
+// the two properties that ruling makes load-bearing:
+//   1. the refusal is HONEST (never "ship those first" for a task that can't ship)
+//   2. the situation is OBSERVABLE (a detector, so it can't strand work silently)
+//
+// Run:  node tests/dead_deps.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { splitDeadDeps, deadDepHint, findStrandedTasks, DEAD_DEP_STATUSES, LIVE_STATUSES } =
+  require('../modules/lifecycle/dead-deps.js');
+const { formatClaimFailure } = require('../scripts/gds/claim.js');
+const { test, summary } = makeRunner();
+
+const dep = (id, status, kind = 'task') => ({ kind, id, title: `t${id}`, status });
+
+// ---- the split: only a task-kind edge can be DEAD ----
+
+await test('splitDeadDeps: an abandoned TASK edge is dead; a pending one is not', () => {
+  const { dead, pending } = splitDeadDeps([dep(1, 'abandoned'), dep(2, 'ready'), dep(3, 'active')]);
+  assert.deepEqual(dead.map((d) => d.id), [1]);
+  assert.deepEqual(pending.map((d) => d.id), [2, 3]);
+});
+
+await test('splitDeadDeps: an unsatisfied CRITERION or unachieved GOAL is pending, never dead', () => {
+  // Those can still resolve — only a cut task is terminal-unsatisfiable.
+  const { dead } = splitDeadDeps([
+    { kind: 'criterion', id: 9, status: 'unsatisfied' },
+    { kind: 'goal', id: 8, status: 'open' },
+  ]);
+  assert.equal(dead.length, 0);
+});
+
+await test('splitDeadDeps: tolerates the shapes the two callers actually pass', () => {
+  assert.equal(splitDeadDeps(null).dead.length, 0, 'null is not a crash');
+  assert.equal(splitDeadDeps([]).dead.length, 0);
+  // unsatisfiedDeps names the column `state`; the route body names it `status`.
+  assert.equal(splitDeadDeps([{ kind: 'task', id: 1, state: 'abandoned' }]).dead.length, 1);
+  // a kind-less row (a bare task dep) still classifies
+  assert.equal(splitDeadDeps([{ id: 1, status: 'abandoned' }]).dead.length, 1);
+});
+
+await test('exactly one status is dead today, and it matches the tasks.status CHECK', () => {
+  assert.deepEqual([...DEAD_DEP_STATUSES], ['abandoned'],
+    "shipped is the satisfying end; abandoned is the other terminal end. A new terminal status must be added here deliberately.");
+  assert.ok(!DEAD_DEP_STATUSES.has('dropped'), "'dropped' is NOT a valid tasks.status (migration 012) — do not add it");
+});
+
+// ---- the hint: never impossible advice ----
+
+await test('deadDepHint: null when every unmet dep is genuinely pending (callers keep their wording)', () => {
+  assert.equal(deadDepHint([dep(2, 'ready'), dep(3, 'backlog')]), null);
+  assert.equal(deadDepHint([]), null);
+});
+
+await test('deadDepHint: names the dead edge, calls it stranded, and never says "ship"', () => {
+  const h = deadDepHint([dep(77, 'abandoned')], 42);
+  assert.match(h, /task 77/, 'names the dead dependency');
+  assert.match(h, /ABANDONED/, 'names the reason in the open');
+  assert.match(h, /STRANDED/, 'says stranded, not waiting');
+  assert.match(h, /top-priority/i, 'the owner ruling: report it as top priority to resolve');
+  assert.ok(!/\bship\b/i.test(h), 'must never advise shipping a task that can never ship');
+});
+
+await test('deadDepHint: gives BOTH real remedies, concretely — drop the edge or restore the dep', () => {
+  const h = deadDepHint([dep(77, 'abandoned')], 42);
+  assert.match(h, /DELETE \/api\/bongos\/dependencies/, 'the drop remedy names the real route');
+  assert.match(h, /"from_id":42/, 'the 4-tuple carries the DEPENDENT id');
+  assert.match(h, /"to_id":77/, 'and the dead dep id');
+  assert.match(h, /POST \/api\/bongos\/tasks\/77\/promote/, 'the restore remedy is the promote route (db.restoreTask)');
+});
+
+await test('deadDepHint: a mixed set reports the dead edge AND still accounts for genuine pending work', () => {
+  const h = deadDepHint([dep(77, 'abandoned'), dep(88, 'ready'), dep(99, 'active')], 42);
+  assert.match(h, /task 77/);
+  assert.match(h, /2 other dependencies are still genuinely pending/);
+  assert.ok(!/task 88/.test(h), 'pending deps are counted, not re-listed (the list is already printed)');
+});
+
+// ---- the CLI: the exact string this task exists to kill ----
+
+await test('claim.js DEPS_NOT_SHIPPED: an abandoned dep no longer gets "Ship those first"', () => {
+  const r = formatClaimFailure({
+    status: 409,
+    data: { error: { code: 'DEPS_NOT_SHIPPED', message: 'deps', details: { deps: [dep(77, 'abandoned')] } } },
+  }, 42);
+  const out = r.lines.join('\n');
+  assert.equal(r.exit, 1);
+  assert.ok(!/Ship those first/.test(out), 'THE REGRESSION: impossible advice for a task that can never ship');
+  assert.match(out, /STRANDED/, 'the header states the real situation');
+  assert.match(out, /← ABANDONED: this edge will never satisfy/, 'the dead row is flagged inline');
+  assert.match(out, /#77/, 'still lists the dep');
+});
+
+await test('claim.js DEPS_NOT_SHIPPED: an all-pending set keeps the original wording', () => {
+  const out = formatClaimFailure({
+    status: 409,
+    data: { error: { code: 'DEPS_NOT_SHIPPED', message: 'deps', details: { deps: [dep(88, 'ready')] } } },
+  }, 42).lines.join('\n');
+  assert.match(out, /can't be claimed yet — these dependencies are not shipped/);
+  assert.match(out, /Ship those first/, 'correct advice when the dep genuinely can still ship');
+  assert.ok(!/ABANDONED/.test(out));
+});
+
+await test('claim.js prefers the SERVER hint when present (one wording, not two)', () => {
+  const out = formatClaimFailure({
+    status: 409,
+    data: { error: { code: 'DEPS_NOT_SHIPPED', message: 'deps', details: { deps: [dep(77, 'abandoned')], hint: 'SERVER-SAID-THIS' } } },
+  }, 42).lines.join('\n');
+  assert.match(out, /SERVER-SAID-THIS/);
+});
+
+// ---- the route: the same decision, wired ----
+
+await test('routes/claims.js wires the shared hint onto DEPS_NOT_SHIPPED and rides dead_deps in the body', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/routes/claims.js', import.meta.url), 'utf8');
+  assert.match(src, /require\('\.\.\/dead-deps\.js'\)/, 'the route consumes the ONE definition');
+  assert.match(src, /err\.code === 'DEPS_NOT_SHIPPED'\) \{[\s\S]{0,220}deadDepHint\(err\.deps/, 'the hint is attached on that branch');
+  assert.match(src, /err\.dead_deps = splitDeadDeps/, 'the machine-readable set rides the body for other clients');
+});
+
+// ---- the detector: observable, so it can never strand silently again ----
+
+await test('findStrandedTasks: a LIVE task gated by an abandoned dep is stranded', () => {
+  const out = findStrandedTasks([
+    { id: 5, status: 'ready', title: 'live one', blocked_by: [dep(77, 'abandoned')] },
+  ]);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].task_id, 5);
+  assert.deepEqual(out[0].dead_deps.map((d) => d.id), [77]);
+});
+
+await test('findStrandedTasks: a TERMINAL dependent is NOT stranded — nothing is waiting', () => {
+  // This is exactly why the live corpus reports zero while 17 abandoned tasks
+  // still carry dependents: whole chains were cut together.
+  const out = findStrandedTasks([
+    { id: 6, status: 'abandoned', blocked_by: [dep(77, 'abandoned')] },
+    { id: 7, status: 'shipped', blocked_by: [dep(77, 'abandoned')] },
+  ]);
+  assert.equal(out.length, 0);
+});
+
+await test('findStrandedTasks: every live status counts, and a healthy dep never flags', () => {
+  for (const s of LIVE_STATUSES) {
+    assert.equal(findStrandedTasks([{ id: 1, status: s, blocked_by: [dep(77, 'abandoned')] }]).length, 1, `${s} must count as live`);
+  }
+  assert.equal(findStrandedTasks([{ id: 1, status: 'ready', blocked_by: [dep(77, 'shipped')] }]).length, 0);
+  assert.equal(findStrandedTasks([{ id: 1, status: 'ready', blocked_by: [] }]).length, 0);
+  assert.equal(findStrandedTasks(null).length, 0, 'null is not a crash');
+});
+
+await test('audit-deps exposes the --stranded mode and abandon.js reports what a cut strands', () => {
+  const audit = readFileSync(new URL('../scripts/gds/audit-deps.js', import.meta.url), 'utf8');
+  assert.match(audit, /--stranded/, 'the mode is documented in the usage header');
+  assert.match(audit, /findStrandedTasks/, 'and uses the shared core, not a second copy');
+  const abandon = readFileSync(new URL('../scripts/gds/abandon.js', import.meta.url), 'utf8');
+  assert.match(abandon, /TOP PRIORITY/, 'cutting a depended-on task reports the strand at cut time');
+  assert.match(abandon, /LIVE_STATUSES/, 'and shares the live-status definition with the detector');
+});
+
+summary();