@bongos/core 1.19.808 → 1.19.810

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.810",
+  "core_contract": "1.19.810",
+  "source_commit": "a3d5dcdde5918a6ce46742502351896701a5a312",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T05:17:38.715Z",
+  "built_at": "2026-09-17T06:04:48.341Z",
   "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": "43e8bede11fa1d3c211405b457b91c73433af719f13cf34869cd9894607688b7",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2532,7 +2532,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "46d5189d51e7dbe1160b8b83a2af194f2f1722e78a0600dc7c9937344049ef01"
+      "sha256": "559a5a32d7f2bbdfc6059b033898244d10bba1abc6881cc9d42388d135c1a164"
     },
     {
       "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": "85db67c033657807d558c218faa46b3a94719479ca312e38fee928ea8e845d2a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "81b97d964fa32391c2affaeca8e06f4676c5cf748ca47da39e6f36fac964cd1c"
+      "sha256": "1ea12b0f66807661d162a59b47b20a2e166b5d356f88a766240c8a573cf95859"
     },
     {
       "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",
@@ -8972,7 +8977,7 @@
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "de8f1f66bf964bfcb8e4fa570f1f873782dfee8d633ff6e599fb894096aecd14"
+      "sha256": "bb39ac6572410567ce0a2881f26b0512df817fd04cec9130792ca24c48e8d02a"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -9427,7 +9432,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "f9d3e4e892d11bbe83b0f76c588fc4c76204f6a424257eb0249acf680f85967a"
+      "sha256": "8d7b749edca694b4c9d8a563a4334c7fe3fc7be64c520c3d14c3b63febff132a"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -9617,7 +9622,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "04156823d2a170b31bb9b3b7c5314224885d89429e6f7b83dbd30aeab5edf7b9"
+      "sha256": "a73a30f63258ab08abe959da6d8f31f8428c30c5d49772350beecb72e9131b2f"
     },
     {
       "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",
@@ -11932,7 +11942,7 @@
     {
       "path": "tests/module-scope-map.mjs",
       "mode": "0000644",
-      "sha256": "d985570340fb9706224c72ed27a2b9a9a84b985f56d2a45fcac564dc463175d4"
+      "sha256": "e277e0579dd6c8fea459cc5a3b4adf04dda12c95e69a415eeea5cfd2de52d760"
     },
     {
       "path": "tests/module_api.mjs",

package/docs/module-api-changelog.md

@@ -2090,5 +2090,9 @@ 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)
+  1.19.810 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.809 with no explicit bump. run 35188253911. (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.810",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.808",
+      "version": "1.19.810",
       "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.810",
   "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/scripts/gds/ship-flow.js

@@ -11,8 +11,7 @@
 const { cliClient, requireSession, arg, detectWorktreeName, cardFlagsFromMe } = require('./cli-lib');
 const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal, staleSummaryNotice } = require('./ship-honesty.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
-const { scopeForModule, isModuleKey } = require('../../src/bongos/module-scope-map');
-const { matchOne } = require('../../src/bongos/path-match');
+const { isModuleKey, scopeForModule, moduleDriftFiles: computeModuleDrift } = require('../../src/bongos/module-scope-map');
 const { runShipGate } = require('./sandbox-stage');
 const { captureSurpriseLearning, promptSurprise } = require('./ship-surprise.js');
 // task 1003109: the optional `--visual` leg of a ship (goal 1000072).
@@ -270,9 +269,18 @@ async function shipMain() {
   // ---- Module drift check (BV1.R53, task 1422) ----
   // If the task carries a module_key, verify the committed diff doesn't stray
   // into a DIFFERENT module's territory. "You said game, you touched dev-box" is
-  // the semantic violation this catches. Files outside all module scopes (docs,
-  // session logs, general scripts) are allowed — they're cross-cutting. Only
-  // contact with a DIFFERENT module's glob set is refused.
+  // the semantic violation this catches. Files no module owns are allowed —
+  // they're cross-cutting — as is the territory of a CROSS-CUTTING module, which
+  // every craft legitimately writes into. Only contact with a different OWNING
+  // module's glob set is flagged.
+  //
+  // The rule itself lives in module-scope-map.js (moduleDriftFiles) next to the
+  // map it reads, so it can be tested without running a ship (task 1003770). It
+  // used to be inline here, and read "files outside all module scopes (docs,
+  // session logs, general scripts) are allowed" — a premise task 1002989 ended by
+  // giving `methodology` the whole docs/ subtree. Since every ship writes a
+  // session log, the advisory then fired for 25 of the 26 module keys on that log
+  // alone. See CROSS_CUTTING_KEYS for why the glob was not shrunk instead.
   //
   // The check is ADVISORY (warns but does not refuse) on the first cut because
   // the module_key column is new and existing tasks may carry a broader diff scope
@@ -280,24 +288,26 @@ async function shipMain() {
   // ac.module_key comes from getActiveClaimsForBuilder (t.module_key in the join).
   const enforceModule = args.includes('--enforce-module');
   if (ac.module_key && isModuleKey(ac.module_key) && committedFiles.length > 0) {
-    const declaredScope = scopeForModule(ac.module_key);
-    const { MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map');
-    const moduleDriftFiles = committedFiles.filter((f) => {
-      if (declaredScope && matchOne(f, declaredScope.globs)) return false;
-      for (const [key, entry] of Object.entries(MODULE_SCOPE_MAP)) {
-        if (key === ac.module_key) continue;
-        if (matchOne(f, entry.globs)) return true;
-      }
-      return false;
-    });
+    const moduleDriftFiles = computeModuleDrift(ac.module_key, committedFiles);
     if (moduleDriftFiles.length > 0) {
+      // Name the module's REAL territory rather than guessing 'modules/<key>/'.
+      // That guess is wrong for every module whose code has not been carved out
+      // yet (ADR 0083) — kernel lives in src/bongos/, methodology in docs/ — so
+      // the advisory used to tell those builders to move their work somewhere
+      // their module does not own. scopeForModule is the roster's own answer.
+      const declared = scopeForModule(ac.module_key);
+      const territory = declared && declared.globs.length
+        ? declared.globs.slice(0, 4).join(', ') + (declared.globs.length > 4 ? `, +${declared.globs.length - 4} more` : '')
+        : `modules/${ac.module_key}/`;
       const msg = [
         `\n⚠ Module drift detected: task is scoped to '${ac.module_key}' but ${moduleDriftFiles.length} file(s) touch a different module:`,
         ...moduleDriftFiles.map((f) => `  - ${f}`),
         '',
+        `  '${ac.module_key}' owns: ${territory}`,
+        '',
         enforceModule
-          ? 'Refused (--enforce-module). Confine your changes to modules/' + ac.module_key + '/ or clear the module_key label.'
-          : 'Advisory — ship proceeds, but consider confining your changes to modules/' + ac.module_key + '/.',
+          ? `Refused (--enforce-module). Confine your changes to that territory, or clear the module_key label.`
+          : 'Advisory — ship proceeds, but consider confining your changes to that territory.',
       ].join('\n');
       console.log(msg);
       if (enforceModule) process.exit(1);

package/src/bongos/module-scope-map.js

@@ -37,7 +37,7 @@
 'use strict';
 
 const { PROTECTED_GLOBS } = require('./permission-path-check');
-const { touchesOverlap } = require('./path-match');
+const { touchesOverlap, matchOne } = require('./path-match');
 
 // key → the path globs that constitute the module's code (exact paths or
 // trailing-'/' subtree prefixes). See the header for the auto-tighten contract.
@@ -486,6 +486,62 @@ function scopeIncludesProtected(keys) {
   return (keys || []).some((k) => isProtectedModule(k) === true);
 }
 
+// ---- CROSS-CUTTING MODULES (task 1003770) ----
+//
+// A module whose territory EVERY craft legitimately writes into, whatever its own
+// task is scoped to. Distinct from SHARED_GLOBS above: a shared glob is owned by
+// nobody, while a cross-cutting module genuinely owns its paths — `methodology`
+// really is the owner of docs/ — it is just that owning them cannot mean other
+// modules are trespassing when they write there.
+//
+// WHAT THIS IS AND IS NOT FOR. This narrows ONE consumer: the ship-time module-
+// drift advisory (moduleDriftFiles below), whose question is "you said game, did
+// you touch dev-box?" — module-to-module confusion. It does NOT touch the goal
+// scope wall, claim collisions (touchesOverlap), or the protected-path wall.
+// Those keep counting methodology's territory as methodology's.
+//
+// WHY IT WAS NEEDED. Task 1002989 gave `methodology` the whole docs/ subtree.
+// Since every ship writes a session log under docs/session-logs/, that made the
+// advisory fire on 25 of the 26 module keys for the session log ALONE — it warned
+// on essentially every module-keyed ship, which is not a signal, it is weather.
+//
+// WHY NOT SHRINK THE GLOB INSTEAD. The glob format has no wildcards (see the
+// header), so "all of docs/ except session-logs" is inexpressible; enumerating
+// docs/ subtree-by-subtree would rot on the next doc.
+//
+// THE BAR, deliberately high — "every task legitimately writes here as a normal
+// part of shipping". `devsecops` is NOT on this list even though it owns
+// package.json: a task that edits .github/, .husky/ or fitness.js while scoped to
+// another module IS the confusion this advisory exists to surface, and lockfile
+// churn is occasional rather than universal.
+const CROSS_CUTTING_KEYS = Object.freeze(['methodology']);
+
+function isCrossCuttingModule(key) {
+  return CROSS_CUTTING_KEYS.includes(key);
+}
+
+// Pure: of `files`, the ones that stray into a DIFFERENT module's territory for a
+// task scoped to `moduleKey`. Extracted from scripts/gds/ship-flow.js (BV1.R53,
+// task 1422) so the rule is testable without running a ship.
+//
+// A file is drift only if it is (a) outside the declared module's own globs and
+// (b) inside some OTHER module's globs — a path no module owns is cross-cutting
+// and always fine. Cross-cutting modules are skipped in (b): their territory
+// never makes a file someone else's. An unknown moduleKey yields no drift, since
+// there is no declared scope to stray from.
+function moduleDriftFiles(moduleKey, files) {
+  const declaredScope = scopeForModule(moduleKey);
+  if (!declaredScope) return [];
+  return (files || []).filter((file) => {
+    if (matchOne(file, declaredScope.globs)) return false;
+    for (const [key, entry] of Object.entries(MODULE_SCOPE_MAP)) {
+      if (key === moduleKey || isCrossCuttingModule(key)) continue;
+      if (matchOne(file, entry.globs)) return true;
+    }
+    return false;
+  });
+}
+
 module.exports = {
   MODULE_GLOBS,
   MODULE_SCOPE_MAP,
@@ -498,5 +554,6 @@ module.exports = {
   isProtectedModule,
   protectedModules,
   globsForModules,
+  moduleDriftFiles,
   scopeIncludesProtected,
 };

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.810'; // 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 }]);
+});

package/tests/module-scope-map.mjs

@@ -291,3 +291,99 @@ test('the gap this closed: an honest task declaring its own test is now authoriz
   const r = gsc.check(['ideas'], ['modules/ideas/inbox.js', 'tests/idea_routing.mjs'], 'thetes');
   assert.equal(r.ok, true, r.reason);
 });
+
+
+// ---- module drift advisory: cross-cutting territory (task 1003770) ----
+
+const SESSION_LOG = 'docs/session-logs/2026-09-16-task-1003770-example.md';
+
+test('THE BUG: a module-scoped task writing a session log is not drift (task 1003770)', () => {
+  // The row's own acceptance criterion. Task 1002989 gave `methodology` the whole
+  // docs/ subtree, and every ship writes a session log under it — so the advisory
+  // started firing on almost every module-keyed ship.
+  for (const key of scope.moduleKeys()) {
+    assert.deepEqual(
+      scope.moduleDriftFiles(key, [SESSION_LOG]), [],
+      `a '${key}' task writing a session log must not read as drift`,
+    );
+  }
+});
+
+test('the regression this replaces: the OLD rule flagged 25 of 26 keys on that one file', () => {
+  // Reproduce the pre-fix predicate — identical except that it does not skip
+  // cross-cutting modules — and prove it fails where the new one passes. Without
+  // this, the test above could pass for the wrong reason (e.g. nobody owning
+  // docs/) and go quietly vacuous if the glob moved again.
+  const { matchOne } = require(path.join(ROOT, 'src', 'bongos', 'path-match.js'));
+  const oldRule = (moduleKey, files) => {
+    const declared = scope.scopeForModule(moduleKey);
+    return files.filter((file) => {
+      if (declared && matchOne(file, declared.globs)) return false;
+      return Object.entries(scope.MODULE_SCOPE_MAP)
+        .some(([k, e]) => k !== moduleKey && matchOne(file, e.globs));
+    });
+  };
+  const flaggedBefore = scope.moduleKeys().filter((k) => oldRule(k, [SESSION_LOG]).length);
+  assert.ok(
+    flaggedBefore.length >= 20,
+    `expected the old rule to flag most keys on a session log, it flagged ${flaggedBefore.length}`,
+  );
+  assert.ok(flaggedBefore.includes('lifecycle'), 'sanity: lifecycle was among them');
+});
+
+test('a cross-cutting module owns its paths everywhere EXCEPT the drift advisory', () => {
+  // The narrowness is the point: this must not become a hole in the scope wall.
+  // methodology still genuinely owns docs/ — only moduleDriftFiles looks away.
+  // Asserted through behaviour, not through the roster constant: the constant is
+  // internal (nothing outside the module reads it), and "docs/ stops counting as
+  // someone else's territory" is the property that actually matters.
+  assert.deepEqual(scope.moduleDriftFiles('lifecycle', ['docs/architecture.md']), []);
+  assert.ok(scope.scopeForModule('methodology').globs.includes('docs/'));
+  const owners = Object.entries(scope.MODULE_SCOPE_MAP)
+    .filter(([, e]) => e.globs.includes('docs/'))
+    .map(([k]) => k);
+  assert.deepEqual(owners, ['methodology'], 'docs/ is still owned, not orphaned');
+  // And the goal scope wall still places docs/ inside methodology, unchanged.
+  assert.equal(gsc.check(['methodology'], ['docs/architecture.md'], 'thetes').ok, true);
+});
+
+test('real cross-module contact is still flagged — the signal the advisory exists for', () => {
+  // "You said lifecycle, you touched dev-box."
+  assert.deepEqual(
+    scope.moduleDriftFiles('lifecycle', ['modules/dev-box/app/src/box-controller.js']),
+    ['modules/dev-box/app/src/box-controller.js'],
+  );
+  // Its own territory, and territory no module owns, both stay quiet.
+  assert.deepEqual(scope.moduleDriftFiles('lifecycle', ['modules/lifecycle/rot.js']), []);
+  assert.deepEqual(scope.moduleDriftFiles('lifecycle', ['some/unowned/path.txt']), []);
+  // A mixed diff reports only the straying file.
+  assert.deepEqual(
+    scope.moduleDriftFiles('lifecycle', ['modules/lifecycle/rot.js', SESSION_LOG, 'modules/discord/discord-bot.js']),
+    ['modules/discord/discord-bot.js'],
+  );
+});
+
+test('devsecops is deliberately NOT cross-cutting (task 1003770)', () => {
+  // The bar is "every task legitimately writes here as part of shipping". Editing
+  // .github/ or fitness.js while scoped elsewhere IS the confusion being surfaced,
+  // so this stays a signal. Widening the cross-cutting roster to devsecops would
+  // red these, which is the point: it should take a deliberate edit, not a shrug.
+  for (const f of ['.github/workflows/unit.yml', 'scripts/gds/fitness.js', 'package.json']) {
+    assert.deepEqual(scope.moduleDriftFiles('lifecycle', [f]), [f], `${f} must still read as drift`);
+  }
+  // And exactly one module is cross-cutting: every other key's territory still
+  // counts against a lifecycle-scoped task. Proven over the whole roster rather
+  // than by naming the constant, so adding a second cross-cutting module fails here.
+  const quiet = scope.moduleKeys().filter((k) => k !== 'lifecycle'
+    && scope.moduleDriftFiles('lifecycle', scope.scopeForModule(k).globs).length === 0);
+  assert.deepEqual(quiet, ['methodology']);
+});
+
+test('moduleDriftFiles degrades safely on junk input', () => {
+  // ship-flow calls this with whatever the claim carries; it must never throw.
+  assert.deepEqual(scope.moduleDriftFiles('not-a-module', ['modules/dev-box/app.js']), [],
+    'an unknown key has no declared scope to stray from');
+  assert.deepEqual(scope.moduleDriftFiles('lifecycle', []), []);
+  assert.deepEqual(scope.moduleDriftFiles('lifecycle', null), []);
+  assert.deepEqual(scope.moduleDriftFiles(null, ['modules/dev-box/app.js']), []);
+});