@bongos/core 1.19.808 → 1.19.809

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.808",
-  "core_contract": "1.19.808",
-  "source_commit": "2a921818a3fc484b4f92c886ee223930bad60a61",
+  "core_version": "1.19.809",
+  "core_contract": "1.19.809",
+  "source_commit": "8a0d6205ab8651338ec9f196b0d2a76457ecd7de",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T05:17:38.715Z",
+  "built_at": "2026-09-17T05:51:03.923Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 487,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2196,
+    "functional_verbatim": 2198,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2708,
-  "tree_sha256": "fd285930374d70ebcd43b89ab506190f5d0d2e6a7b4a4c1d1f35aa16e00bc5ca",
+  "file_count": 2710,
+  "tree_sha256": "8ffacf4d6b6f9d1185a0367eef97d3f885c3219caa5f7b483c03e568f6e244cf",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2532,7 +2532,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "46d5189d51e7dbe1160b8b83a2af194f2f1722e78a0600dc7c9937344049ef01"
+      "sha256": "0fc3cc0ea86f2325096412d389457b095d7e12b175415e0f9bc41d5cd40946a1"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5459,6 +5459,11 @@
       "mode": "0000644",
       "sha256": "7cb9dac9cb87b679e1ae50e4112b3a7928a38ebb9902c8947a74d17bec4d9009"
     },
+    {
+      "path": "modules/lifecycle/abandon-leftovers.js",
+      "mode": "0000644",
+      "sha256": "a9d762f64176c26b3d3058a9e769f966b838fbb8b0dabeceeeabd8ce324ca471"
+    },
     {
       "path": "modules/lifecycle/activity.js",
       "mode": "0000644",
@@ -7722,12 +7727,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6710303099e13ad8ed4480666184efecef047f30f6d8ef94a7ab197b53030747"
+      "sha256": "bce83e06aea9721525e159bbe1446154fcda006c89fdcde14fd6ab46f624366a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "81b97d964fa32391c2affaeca8e06f4676c5cf748ca47da39e6f36fac964cd1c"
+      "sha256": "714b48f38c2da73d5a2353c66228b8f4aa8cd375f7c712a1421f59bb0cf22e09"
     },
     {
       "path": "public-docs/index.html",
@@ -7777,7 +7782,7 @@
     {
       "path": "scripts/gds/abandon.js",
       "mode": "0000644",
-      "sha256": "67e9a8dead2b0ea75f6011fd687a3db56a12df945a77f430eec2602a0ecac07c"
+      "sha256": "723aea2c66f8897822507a7b3c7556170336ec021676b3cb8898e5c3bc4e98ca"
     },
     {
       "path": "scripts/gds/accessibility-replay.js",
@@ -9617,7 +9622,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "04156823d2a170b31bb9b3b7c5314224885d89429e6f7b83dbd30aeab5edf7b9"
+      "sha256": "03b5ce71d6aeab750b5bd2dad14f89d459472a4b42a701b4923bb430cafa384e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9669,6 +9674,11 @@
       "mode": "0000644",
       "sha256": "2e46d071e5c61d302f34507215dd0a5f20a0887841ae0f7b033be865c2cb8af5"
     },
+    {
+      "path": "tests/abandon_leftovers.mjs",
+      "mode": "0000644",
+      "sha256": "fe9562bd27fc127f5113de4316d1abe784874aa198d87be79caa302d526ecf17"
+    },
     {
       "path": "tests/abandon_task.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2090,5 +2090,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.806 with no explicit bump. run 35183654397. (task 1002620)
   1.19.808 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.807 with no explicit bump. run 35185130913. (task 1002620)
+  1.19.809 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.808 with no explicit bump. run 35187322516. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/abandon-leftovers.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// modules/lifecycle/abandon-leftovers.js — what a retired task leaves behind
+// (task 1003779).
+//
+// THE DEFECT THIS EXISTS FOR. Abandoning a task retires the ROW and nothing else.
+// Task 1002464 was abandoned carrying two commits on `task-1002464` that are not
+// ancestors of origin/main, and an open PR. Nothing said so — not at the moment
+// of abandonment, not afterwards — so the branch read as live work, and a
+// follow-up filed off its grading pass (task 1003626) sat at `ready` asking for
+// three nits in a function that exists nowhere on main. `sequence.js --check`
+// called it "clear to run". The cost landed on whoever claimed it.
+//
+// SIBLING OF dead-deps.js, deliberately. That file makes an abandoned
+// DEPENDENCY observable; this one makes abandoned CODE observable. Same posture:
+// pure and git-free here so the CLI is the only place that shells out, and the
+// rule can be tested without a repository.
+//
+// WHAT THIS IS NOT. It does not delete a branch, close a PR, or touch the
+// remote. Retiring a row is reversible (POST /tasks/:id/promote); deleting the
+// only copy of unmerged work is not, and which of the two a leftover branch
+// deserves is a human call. This reports, loudly, with the commands to hand.
+//
+// WHY NOT source_ref, which the report suggested. The incident that motivated
+// this task is the counter-example: 1003626's `source_ref` is `idea:1000935`,
+// not the branch or task it was stranded behind — the relationship lived only in
+// the prose of its description. A source_ref sweep would have found nothing.
+// The branch is the artifact that actually exists, so the branch is what is
+// checked.
+
+// A branch belongs to task N if it is `task-N` or `task-N-<slug>` (the two
+// shapes worktree.js produces). Anchored at both ends so task-1002450 never
+// matches task-10024501 — a prefix match here would report another task's work
+// as this one's leftovers, which is worse than reporting nothing.
+function branchesForTask(taskId, branches) {
+  const id = String(taskId == null ? '' : taskId).trim();
+  if (!/^\d+$/.test(id)) return [];
+  const re = new RegExp(`^task-${id}(?:-[A-Za-z0-9._-]+)?$`);
+  // Deduped after stripping the remote prefix: a caller may pass the same branch
+  // as both 'task-N' and 'origin/task-N' (git branch -r vs ls-remote), and the
+  // notice would then tell a builder to delete one branch twice.
+  const seen = new Set();
+  for (const raw of branches || []) {
+    const b = String(raw || '').trim().replace(/^origin\//, '');
+    if (re.test(b)) seen.add(b);
+  }
+  return [...seen];
+}
+
+// Pure: the leftover report for one task. `aheadCount(branch)` answers "how many
+// commits does this branch carry that main does not" — a number, or null when it
+// could not be determined.
+//
+// null is NOT folded into 0. "I could not look" and "there is nothing there"
+// must not render as the same sentence (the strand-watch.js rule): an
+// undetermined branch is reported as undetermined, so a network failure cannot
+// quietly certify a branch as clean.
+function leftoversForTask(taskId, { branches, aheadCount }) {
+  const out = [];
+  for (const branch of branchesForTask(taskId, branches)) {
+    let raw;
+    try { raw = aheadCount(branch); } catch (_) { raw = null; }
+    const n = Number(raw);
+    // Anything that is not a finite number is UNDETERMINED, not zero. The first
+    // cut of this tested only for null/undefined, so a NaN — what
+    // `Number(git rev-list output)` yields when the command prints nothing —
+    // fell through to the "> 0" test, failed it, and was dropped as clean. That
+    // is the exact failure this module's header forbids: a branch nobody could
+    // read certified as a branch with nothing on it.
+    if (raw === null || raw === undefined || !Number.isFinite(n)) {
+      out.push({ branch, ahead: null, undetermined: true });
+      continue;
+    }
+    if (n > 0) out.push({ branch, ahead: n, undetermined: false });
+  }
+  return out;
+}
+
+// The message a builder sees. Returns null when there is nothing to say, so the
+// caller can stay silent on the clean path rather than printing a reassurance
+// nobody reads (and which would train people to skip the line that matters).
+function leftoverNotice(taskId, leftovers) {
+  if (!leftovers || !leftovers.length) return null;
+  const lines = [`\n⚠ Task #${taskId} is retired, but its work is still on the remote:`];
+  for (const l of leftovers) {
+    lines.push(l.undetermined
+      ? `  - ${l.branch} — could not tell whether it carries unmerged commits`
+      : `  - ${l.branch} — ${l.ahead} commit(s) not on main`);
+  }
+  lines.push(
+    '',
+    'An abandoned task with a live branch reads as live work, and anything filed',
+    'off its review sits against code that does not exist on main. Decide which:',
+    '',
+    `  git push origin --delete ${leftovers[0].branch}    # the work is cut — drop it`,
+    `  node scripts/gds/api.js POST /api/gds/tasks/${taskId}/promote   # it is not cut — revive the task`,
+    '',
+    'Close or draft the branch\'s PR either way — the remote is not this tool\'s to change.',
+  );
+  return lines.join('\n');
+}
+
+module.exports = { branchesForTask, leftoversForTask, leftoverNotice };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.808",
+  "version": "1.19.809",
   "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

@@ -21,6 +21,38 @@ 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');
+// task 1003779 — the other thing a cut leaves behind: the code itself.
+const { leftoversForTask, leftoverNotice } = require('../../modules/lifecycle/abandon-leftovers.js');
+const { execFileSync } = require('node:child_process');
+
+// Best-effort git, always. Every call here is advisory decoration on an abandon
+// that has ALREADY landed, so a missing git, a detached network or a shallow
+// clone must return "I don't know" — never throw, and never abort the command.
+function git(args, ms = 20000) {
+  return execFileSync('git', args, { encoding: 'utf8', timeout: ms, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+// The remote branches this task owns. ONE network round trip, scoped to the two
+// name shapes worktree.js produces — listing all 800-odd heads to filter locally
+// would be the expensive way to learn the same thing.
+function remoteBranchesFor(taskId) {
+  try {
+    const out = git(['ls-remote', '--heads', 'origin', `refs/heads/task-${taskId}`, `refs/heads/task-${taskId}-*`]);
+    return out.split('\n').map((l) => l.split('\t')[1] || '').filter(Boolean)
+      .map((r) => r.replace(/^refs\/heads\//, ''));
+  } catch (_) { return null; }  // null = could not look
+}
+
+// How many commits the branch carries that main does not. Returns null when it
+// cannot be determined, which leftoversForTask reports as undetermined rather
+// than folding into "clean" — see that module's header.
+function commitsAheadOfMain(branch) {
+  try {
+    git(['fetch', 'origin', '--quiet', branch, 'main']);
+    const n = Number(String(git(['rev-list', '--count', 'FETCH_HEAD', '--not', 'origin/main'])).trim());
+    return Number.isFinite(n) ? n : null;
+  } catch (_) { return null; }
+}
 
 
 (async () => {
@@ -79,6 +111,22 @@ const { LIVE_STATUSES } = require('../../modules/lifecycle/dead-deps.js');
       console.log('  Sweep for any you miss:  node scripts/gds/audit-deps.js --stranded');
     }
   } catch (_) { /* the abandon already landed — the report is advisory */ }
+
+  // task 1003779 — REPORT the code this cut orphaned. Abandoning retires the ROW;
+  // the branch and its PR stay exactly where they were, reading as live work.
+  // Task 1002464 was cut carrying two commits never merged to main, and the
+  // follow-up filed off its review (task 1003626) then sat at 'ready' asking for
+  // changes to a function that exists nowhere on main — 'sequence.js --check'
+  // called it clear to run. Nothing had said the branch was dead, so nothing could.
+  // Same posture as the stranded-dependents report above: best-effort, and it
+  // never fails an abandon that already landed.
+  try {
+    const branches = remoteBranchesFor(taskId);
+    if (branches && branches.length) {
+      const notice = leftoverNotice(taskId, leftoversForTask(taskId, { branches, aheadCount: commitsAheadOfMain }));
+      if (notice) console.log(notice);
+    }
+  } catch (_) { /* advisory only */ }
 })().catch((err) => {
   console.error('fatal:', err);
   process.exit(1);

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

@@ -0,0 +1,87 @@
+// tests/abandon_leftovers.mjs — what a retired task leaves on the remote
+// (task 1003779). Pure + git-free: the ancestry oracle is injected, so these run
+// with no repository, no network and no fixtures.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { branchesForTask, leftoversForTask, leftoverNotice } =
+  require(path.join(ROOT, 'modules', 'lifecycle', 'abandon-leftovers.js'));
+
+test('both branch shapes worktree.js produces belong to the task', () => {
+  const branches = ['task-1002464', 'task-1002503-backfill-recovery', 'main'];
+  assert.deepEqual(branchesForTask(1002464, branches), ['task-1002464']);
+  assert.deepEqual(branchesForTask(1002503, branches), ['task-1002503-backfill-recovery']);
+});
+
+test('THE MISREPORT THIS MUST NOT MAKE: a longer id is not a prefix match', () => {
+  // task-10024501 is ANOTHER task's branch. Matching it would tell a builder to
+  // delete someone else's unmerged work as their own leftovers — worse than
+  // reporting nothing at all, which is why the pattern is anchored at both ends.
+  assert.deepEqual(branchesForTask(1002450, ['task-10024501', 'task-1002450x', 'xtask-1002450']), []);
+  assert.deepEqual(branchesForTask(1002450, ['task-1002450', 'task-10024501']), ['task-1002450']);
+});
+
+test('the same branch given twice is reported once', () => {
+  // Callers may pass `git branch -r` output (origin/task-N) and `ls-remote`
+  // output (task-N) together; the notice would otherwise say "delete it" twice.
+  assert.deepEqual(branchesForTask(1002464, ['task-1002464', 'origin/task-1002464']), ['task-1002464']);
+});
+
+test('a non-numeric or missing id matches nothing rather than building a loose regex', () => {
+  for (const id of ['', null, undefined, 'x', '10*', '.*']) {
+    assert.deepEqual(branchesForTask(id, ['task-1002464', 'task-x']), [], `id ${JSON.stringify(id)}`);
+  }
+});
+
+test('a branch already merged into main is not a leftover — the silent path', () => {
+  // The load-bearing negative. Every shipped task keeps its branch, so if a
+  // merged branch counted, the notice would fire on nearly every abandon and
+  // become weather (the lesson task 1003770 recorded about the drift advisory).
+  assert.deepEqual(leftoversForTask(1002464, { branches: ['task-1002464'], aheadCount: () => 0 }), []);
+  assert.equal(leftoverNotice(1002464, []), null, 'nothing to say means say nothing');
+});
+
+test('unmerged commits are reported with their count', () => {
+  assert.deepEqual(
+    leftoversForTask(1002464, { branches: ['task-1002464'], aheadCount: () => 2 }),
+    [{ branch: 'task-1002464', ahead: 2, undetermined: false }],
+  );
+});
+
+test('"could not look" is never folded into "nothing there"', () => {
+  // A network failure must not silently certify a branch as clean — the
+  // strand-watch.js rule. null and a throw both surface as undetermined.
+  for (const oracle of [() => null, () => undefined, () => { throw new Error('offline'); }, () => NaN]) {
+    const r = leftoversForTask(1002464, { branches: ['task-1002464'], aheadCount: oracle });
+    assert.equal(r.length, 1);
+    assert.equal(r[0].undetermined, true);
+    assert.equal(r[0].ahead, null);
+  }
+  assert.match(leftoverNotice(1002464, leftoversForTask(1002464,
+    { branches: ['task-1002464'], aheadCount: () => null })), /could not tell/);
+});
+
+test('the notice names the task, the branch, and both ways out', () => {
+  const notice = leftoverNotice(1002464, leftoversForTask(1002464,
+    { branches: ['task-1002464'], aheadCount: () => 2 }));
+  assert.match(notice, /#1002464/);
+  assert.match(notice, /task-1002464 — 2 commit\(s\) not on main/);
+  // Both dispositions, because which one applies is a human call: the work is
+  // cut (drop the branch) or it is not (revive the task).
+  assert.match(notice, /git push origin --delete task-1002464/);
+  assert.match(notice, /tasks\/1002464\/promote/);
+});
+
+test('a mixed set reports only the branches that actually carry work', () => {
+  const branches = ['task-1002464', 'task-1002464-followup'];
+  const r = leftoversForTask(1002464, {
+    branches,
+    aheadCount: (b) => (b === 'task-1002464' ? 3 : 0),
+  });
+  assert.deepEqual(r, [{ branch: 'task-1002464', ahead: 3, undetermined: false }]);
+});