@bongos/core 1.19.799 → 1.19.800

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.799",
-  "core_contract": "1.19.799",
-  "source_commit": "85b2cf74b5fa2c392c59c47b0b877e9b912503ac",
+  "core_version": "1.19.800",
+  "core_contract": "1.19.800",
+  "source_commit": "61c8980e6b9f6fb0cbd611f41520cbcae4780f11",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T01:33:26.348Z",
+  "built_at": "2026-09-17T02:01:42.605Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 487,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2699,
-  "tree_sha256": "6435ea324232356a39b076f0f83fad40beaa96485c1f9e9b3a38fea29feda830",
+  "tree_sha256": "0d54a704f2ba5c26c517372981337570ff4a70da884edee06ef52c30e836fda3",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -207,7 +207,7 @@
     {
       "path": ".claude/skills/planning-session/SKILL.md",
       "mode": "0000644",
-      "sha256": "9320b9a04d36d3169e5a01e4fb5dc595fe84ef292541307fd17974a283b4c509"
+      "sha256": "e05fd083784c0ff72eb54b6250dae4a58f464822f6b14347c524702b43a1f7ad"
     },
     {
       "path": ".claude/skills/priority-session/SKILL.md",
@@ -2532,7 +2532,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "4ad2853bc510a9ce3bfa2264734afb42eb41f75a28c0a51f639d48038e62e440"
+      "sha256": "07a1c706c1ddc1d0c51da0737e861e8af59c0a50caa9119cfca43f1ad3fde6ba"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5512,12 +5512,12 @@
     {
       "path": "modules/lifecycle/db-claims.js",
       "mode": "0000644",
-      "sha256": "e2b9e236090bc1936bed98a2487e0db9ab10e3c543597ababd68e664a396d8f3"
+      "sha256": "1c250de70282c19f66324f9203d0899eb874c8d59f14af940a004a235bf9d1b9"
     },
     {
       "path": "modules/lifecycle/db-deps-criteria.js",
       "mode": "0000644",
-      "sha256": "2fefa2efa05b2a63ee510345180c04d211d5068c8bc82c050392dac3d02cfac2"
+      "sha256": "76ffab3052ce0b48d0b78451a2e34d5cd3c5300410f0856b4a6667cbe708ba2b"
     },
     {
       "path": "modules/lifecycle/db-goals.js",
@@ -5567,7 +5567,7 @@
     {
       "path": "modules/lifecycle/dead-deps.js",
       "mode": "0000644",
-      "sha256": "e379969ef290aab09abeef50f2e4996e2df2fa16e6d4ea9fbd268e23518b3147"
+      "sha256": "c9f7aa89a4b1e9a201189608ff8ebc4910ee6ca19be33ce681f2d32cedb0b39d"
     },
     {
       "path": "modules/lifecycle/done-when.js",
@@ -7712,12 +7712,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1b8fa8ffcdeac7490e95f849daa69ef5580ffce9da1eed6d3434990e29dc957d"
+      "sha256": "2fa689bfe81f60fd4b8ca8e0304b2eac417c172af397d23c1de3427e0a6544a5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4dd1a1bfaad4b7ff8382bd13fdd0331f54536a84fdc928f7f9b97ad2b88e60ac"
+      "sha256": "2e40419061babf39395a90a2b45c7c7409e1acce44e86984a3913dd6010a485a"
     },
     {
       "path": "public-docs/index.html",
@@ -8007,7 +8007,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "8cf425aed2764fc043c8a8757f178f7514a907567d559e7f0b11e091f33b66e5"
+      "sha256": "53411af3a058d5fb22029a2ae923ef259fb1a45b1e39c20fd28e004a8c4d369f"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -9162,7 +9162,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "eba999956e81e6637af527334825d2c1b5ad9b4af165320eb011e28718c5df99"
+      "sha256": "6fb938914f50a8273640ca2bad871b3a3077102e36877c861e344235338ebef2"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9602,7 +9602,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4ad4e006b2f2916be9183776e9c33d49839b632b6a199180f23f99fb683f8e09"
+      "sha256": "0a1e5d3b5db82b4a63d3936fd70ff4e079a1eef0b81b8d7041fcb3f1aaffc109"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10502,7 +10502,7 @@
     {
       "path": "tests/dead_deps.mjs",
       "mode": "0000644",
-      "sha256": "07d2825c812a10cd1d39182883652dec15d360d3645dd38023a00a0593d36ddc"
+      "sha256": "65adddca46ac1ed3b4239e110a4018fd4b4ff113e1fbb1991742a7f4bcb28f16"
     },
     {
       "path": "tests/dead_feature_claim.mjs",
@@ -13362,7 +13362,7 @@
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "d30debaa35407998dcdd1949f9bcbf45c09b4a001d22cfdea9541b5bdbaa1274"
+      "sha256": "2e1fd181c580070c3625035d39d038c137dbf04c6c8e74132977b877c0d73c76"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/.claude/skills/planning-session/SKILL.md

@@ -89,6 +89,16 @@ This is where the user sees what they're shaping. Do not skip this — criteria
 
    Surface the list to the user and get a per-goal carry/replace decision before writing criteria — the carry-forward goals shape this version's goal set.
 
+5. **An `abandoned` task does NOT mean the work is missing — open it before you believe the status.** Whenever a prior goal you are about to depend on has abandoned tasks, read them. `abandoned` is overloaded across three situations a planning session has to treat differently:
+
+   - **dropped** — genuinely cut. A real gap; scope it again if it still matters.
+   - **superseded** — a different approach won. Maybe a gap; read what replaced it.
+   - **absorbed** — folded into a sibling task and shipped THERE. **Not a gap at all**, and putting an edge on it is actively wrong: it strands live work behind a prerequisite that already exists.
+
+   **The absorbed case has a marker you can check** — `merged_into_task_id`, which is what `POST /tasks/:id/merge` records (merge is "abandon, plus where it went"). It rides on the task row, on `blocked_by` entries from `GET /tasks?include=deps`, and on a claim refusal, which now names the absorbing task and tells you to RE-POINT the edge rather than restore anything (task 1003107). A row carrying that pointer is work that exists — go read the task it names.
+
+   **A row WITHOUT the pointer still needs its description read**, because the marker only exists from the day someone used merge instead of abandon-with-a-note, and the older rows are exactly the ones a rescope trips over. **Verify against the repo, not the row.** On 2026-08-16 a session read task 1003005 ("Rename modules/governance to modules/government") as `abandoned` and nearly put a false edge in a new goal's graph — the folder move had shipped under task 1003004, and only the prose said so. One `git log` over the paths the task named would have settled it.
+
 ### Phase 1.5 — Map the mechanism (process-change sessions only) — task 1003075
 
 **Run this phase when the session is scoped to CHANGING how an existing mechanism already works** (a redesign, not a net-new feature with nothing live to replace) — skip it for a purely additive version with no prior mechanism in play. The precedent is the 2026-08-17 idea-routing session (goal 1000071): a subagent mapping the LIVE capture→triage→promote path before Phase 2 turned "route bugs to goals" into the capture-time-promotion design and resolved the bugs-vs-features question almost by itself — the session's own retro named it the highest-value step, and until now the skill only implied it.

package/docs/module-api-changelog.md

@@ -2072,5 +2072,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.797 with no explicit bump. run 35170229509. (task 1002620)
   1.19.799 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.798 with no explicit bump. run 35170980369. (task 1002620)
+  1.19.800 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.799 with no explicit bump. run 35172784518. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-claims.js

@@ -23,6 +23,10 @@ const { touchesOverlap } = api.pathMatch;
 const { CLAIM_ANY, CLAIM_NEWCOMER } = require('./claim-eligibility.js');
 const { goalMembershipFailures } = require('./claim-feed.js');
 const { unsatisfiedDeps } = require('./db-deps-criteria.js');
+// depRefusalRow: the ONE shape a DEPS_NOT_SHIPPED refusal carries. All three
+// claim paths below use it — hand-building the object here is what made task
+// 1003107's merge pointer invisible on the live path (see its header).
+const { depRefusalRow } = require('./dead-deps.js');
 const { claimGate, claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName } = require('./db-rank-authz.js');
 const { sealSessionLog } = require('./db-shared.js');
 const { needsRebaseTasksForBuilder, shouldRefuseClaimResolve } = require('./db-ship.js');
@@ -216,7 +220,7 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     if (unmetDeps.length > 0) {
       throw {
         code: 'DEPS_NOT_SHIPPED',
-        deps: unmetDeps.map((r) => ({ kind: r.kind, id: r.id, title: r.title, status: r.state })),
+        deps: unmetDeps.map(depRefusalRow),
       };
     }
 
@@ -573,7 +577,7 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
         failures.push({
           task_id: t.id,
           reason: 'DEPS_NOT_SHIPPED',
-          deps: external.map((d) => ({ kind: d.kind, id: d.id, title: d.title, status: d.state })),
+          deps: external.map(depRefusalRow),
         });
       }
     }
@@ -916,7 +920,7 @@ async function validateClaimBatch({ taskIds, builderId }) {
     if (external.length > 0) {
       push(id, {
         reason: 'DEPS_NOT_SHIPPED',
-        deps: external.map((d) => ({ kind: d.kind, id: d.id, title: d.title, status: d.state })),
+        deps: external.map(depRefusalRow),
       });
     }
   }

package/modules/lifecycle/db-deps-criteria.js

@@ -73,7 +73,12 @@ async function attachTaskDepSummaries(tasks) {
       `SELECT d.from_id AS task_id,
               json_agg(json_build_object(
                 'id', t2.id, 'title', t2.title, 'status', t2.status,
-                'goal_id', t2.goal_id, 'satisfied', (t2.status = 'shipped')
+                'goal_id', t2.goal_id, 'satisfied', (t2.status = 'shipped'),
+                -- task 1003107: an abandoned dependency that was MERGED into a
+                -- sibling is not cut work, it is work that shipped somewhere
+                -- else. Carrying the pointer here is what lets dead-deps.js tell
+                -- the two apart; without it every reader re-derives it from prose.
+                'merged_into_task_id', t2.merged_into_task_id
               ) ORDER BY t2.id) AS blocked_by
          FROM dependencies d
          JOIN tasks t2 ON t2.id = d.to_id
@@ -452,16 +457,28 @@ async function unsatisfiedDeps(taskId, client = pool) {
            OR (d.from_kind = 'criterion' AND d.from_id IN (
                  SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id))
      )
-     SELECT 'task' AS kind, x.id, x.title, x.status::text AS state
+     -- The three extra columns are the ABSORBED case (task 1003107): an
+     -- abandoned dependency carrying merged_into_task_id was not cut, it was
+     -- folded into a sibling — and if that sibling SHIPPED, the work the edge
+     -- is waiting for exists. The gate still refuses (owner ruling 2026-08-21,
+     -- see dead-deps.js), but the refusal can now name the right remedy instead
+     -- of telling someone to restore a task nobody wants back. Only the task
+     -- branch can be absorbed; the other two carry NULLs to keep the UNION
+     -- arity honest.
+     SELECT 'task' AS kind, x.id, x.title, x.status::text AS state,
+            x.merged_into_task_id, m.status::text AS merged_into_status, m.title AS merged_into_title
        FROM gating g JOIN tasks x ON g.to_kind = 'task' AND x.id = g.to_id
+       LEFT JOIN tasks m ON m.id = x.merged_into_task_id
       WHERE x.status <> 'shipped'
      UNION ALL
      SELECT 'criterion' AS kind, x.id, x.criterion_md AS title,
-            (CASE WHEN x.satisfied THEN 'satisfied' ELSE 'unsatisfied' END) AS state
+            (CASE WHEN x.satisfied THEN 'satisfied' ELSE 'unsatisfied' END) AS state,
+            NULL::bigint, NULL::text, NULL::text
        FROM gating g JOIN done_when_criteria x ON g.to_kind = 'criterion' AND x.id = g.to_id
       WHERE x.satisfied = false
      UNION ALL
-     SELECT 'goal' AS kind, x.id, x.title, x.status::text AS state
+     SELECT 'goal' AS kind, x.id, x.title, x.status::text AS state,
+            NULL::bigint, NULL::text, NULL::text
        FROM gating g JOIN goals x ON g.to_kind = 'goal' AND x.id = g.to_id
       WHERE x.status <> 'achieved'`,
     [taskId]

package/modules/lifecycle/dead-deps.js

@@ -31,16 +31,80 @@
 // 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.
+// ABSORBED — the dead edge that is not actually cut work (task 1003107).
+//
+// 'abandoned' is overloaded. It covers work genuinely dropped, and it covers
+// work folded into a sibling task and SHIPPED THERE — the /tasks/:id/merge
+// transition, which is `abandonTask` plus a target and records that target in
+// `merged_into_task_id` (core_232). On status alone the two are identical, so a
+// reader who trusts the status treats shipped work as a gap and puts a false
+// edge in the graph. That really happened: task 1003005 read 'abandoned' while
+// the folder move it described had shipped under 1003004, and only the
+// description said so.
+//
+// This does NOT make an absorbed edge satisfy. The owner's 2026-08-21 ruling
+// above is that a cut prerequisite must force a deliberate human re-scope, and
+// an edge pointing at a task that no longer exists as work is exactly that —
+// someone has to decide whether the dependent still needs anything. What
+// changes is that the refusal stops SAYING the work was never built, and names
+// the remedy that fits: re-point the edge at the task that absorbed it.
+//
+// Reads the pointer from either shape the callers have: `merged_into_task_id`
+// on a blocked_by row or on an unsatisfiedDeps row.
+function absorbedInto(dep) {
+  const t = dep && dep.merged_into_task_id;
+  return t == null || t === '' ? null : String(t);
+}
+
+// Which of these unmet dependency rows are DEAD (never-satisfiable AS POINTED)
+// 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.
+//
+// `absorbed` is a SUBSET of `dead`, not a fourth bucket: an absorbed edge is
+// still dead as written (it points at a row that will never ship), it just has a
+// different and better remedy. Existing callers that read `dead` keep their
+// exact behaviour.
 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))) };
+  return {
+    dead,
+    absorbed: dead.filter((d) => absorbedInto(d) !== null),
+    pending: all.filter((d) => !deadIds.has(String(d && d.id))),
+  };
+}
+
+// depRefusalRow — one `unsatisfiedDeps` row in the shape a DEPS_NOT_SHIPPED
+// refusal carries.
+//
+// THIS EXISTS BECAUSE THE FIRST VERSION OF TASK 1003107 SHIPPED A DEAD FEATURE.
+// Three claim paths in db-claims.js each built this object by hand, whitelisting
+// four fields. Enriching the QUERY with the merge pointer therefore changed
+// nothing on the real path: all three projections dropped the new columns, so
+// `absorbedInto` saw `undefined` and the ABSORBED branch could never fire in
+// production — while the unit tests, which fed `deadDepHint` hand-built rows,
+// stayed green. A pure core with hand-copied callers is only as shared as its
+// least-updated copy. One mapper is the fix; `tests/dead_deps.mjs` pins that all
+// three sites use it rather than spelling the object again.
+//
+// The merge fields are added only when present, so a row for a task that was
+// never merged keeps its exact previous shape.
+function depRefusalRow(r) {
+  const row = { kind: r.kind, id: r.id, title: r.title, status: r.state };
+  if (r.merged_into_task_id != null) {
+    row.merged_into_task_id = r.merged_into_task_id;
+    if (r.merged_into_status != null) row.merged_into_status = r.merged_into_status;
+    // A task TITLE, author-supplied. It already flows to the same consumers via
+    // blocked_by[].title and dead_deps[].title, so this is not a new surface —
+    // but it is untrusted text in a string a UI may render, and any renderer
+    // must escape it exactly as it already escapes those.
+    if (r.merged_into_title != null) row.merged_into_title = r.merged_into_title;
+  }
+  return row;
 }
 
 // The way-forward line for a refusal that includes at least one dead edge.
@@ -55,17 +119,40 @@ function splitDeadDeps(deps) {
 // `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);
+  const { dead, absorbed, pending } = splitDeadDeps(deps);
   if (dead.length === 0) return null;
   const names = dead.map((d) => `task ${d.id}`).join(', ');
+  const tail = pending.length
+    ? ` ${pending.length} other dependenc${pending.length === 1 ? 'y is' : 'ies are'} still genuinely pending.`
+    : '';
+  const edge = (to) => `{"from_kind":"task","from_id":${taskId ?? '<this task>'},"to_kind":"task","to_id":${to}}`;
+
+  // The ABSORBED case leads, because it is the one whose usual advice is wrong:
+  // nobody wants that task restored, and dropping the edge without re-pointing
+  // it loses the ordering that was real. Naming the target turns a judgement
+  // call into two concrete calls.
+  if (absorbed.length) {
+    const a = absorbed[0];
+    const into = absorbedInto(a);
+    const shipped = String(a.merged_into_status || '') === 'shipped';
+    return `${absorbed.length === 1 ? 'A dependency was ABSORBED' : `${absorbed.length} dependencies were ABSORBED`} into another task `
+      + `(task ${a.id} → task ${into}${a.merged_into_title ? `, "${a.merged_into_title}"` : ''}${a.merged_into_status ? `, ${a.merged_into_status}` : ''}) — `
+      + 'it was NOT cut work: it was folded into a sibling and '
+      + (shipped ? 'SHIPPED there. ' : 'is being done there. ')
+      + 'So do not restore it and do not treat the work as missing. '
+      + `RE-POINT the edge: drop the stale one (DELETE /api/bongos/dependencies with body ${edge(a.id)}) `
+      + `and add the real one (POST /api/bongos/dependencies with body ${edge(into)}).`
+      + (dead.length > absorbed.length ? ` ${dead.length - absorbed.length} other dead edge(s) here were genuinely abandoned — see below.` : '')
+      + tail;
+  }
+
   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}) `
+    + `Either DROP the dead edge (DELETE /api/bongos/dependencies with body ${edge(first)}) `
     + `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.` : '');
+    + tail;
 }
 
 // Detector core (scripts/gds/audit-deps.js --stranded): which LIVE tasks are
@@ -90,11 +177,21 @@ function findStrandedTasks(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) {
+      // absorbed_deps is a SUBSET of dead_deps, reported separately because the
+      // two need different work: an absorbed edge has a mechanical fix (re-point
+      // it at the task named right here), a genuinely abandoned one needs a
+      // human to decide whether the dependent still wants anything. A sweep that
+      // cannot tell them apart makes every row look like the expensive kind.
       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 })),
+        dead_deps: dead.map((d) => ({
+          id: d.id, title: d.title, status: d.status,
+          merged_into_task_id: absorbedInto(d),
+        })),
+        absorbed_deps: dead.filter((d) => absorbedInto(d) !== null)
+          .map((d) => ({ id: d.id, title: d.title, merged_into_task_id: absorbedInto(d) })),
       });
     }
   }
@@ -103,5 +200,5 @@ function findStrandedTasks(tasks) {
 
 module.exports = {
   DEAD_DEP_STATUSES, LIVE_STATUSES,
-  splitDeadDeps, deadDepHint, findStrandedTasks,
+  absorbedInto, depRefusalRow, splitDeadDeps, deadDepHint, findStrandedTasks,
 };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.799",
+  "version": "1.19.800",
   "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/claude-materialize.js

@@ -257,6 +257,20 @@ function moduleSkillSources(opts) {
 
 const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
 
+// Every file under `dir`, as paths relative to it. Used to name a withdrawn skill dir's
+// files before it is removed — a deletion git reports one file at a time, never the dir.
+function listFilesRecursive(dir, base = '') {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(path.join(dir, base), { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const rel = path.join(base, e.name);
+    if (e.isDirectory()) out.push(...listFilesRecursive(dir, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
 // `overwrite` defaults true (greenfield init / upgrade — byte-identical to before).
 // `overwrite: false` is the `bongos init --adopt` layering path (ADR 0121): a file
 // that already exists at the destination is NEVER clobbered — it is skipped and
@@ -368,7 +382,26 @@ function transformSettings(srcPath) {
 const HOOK_TEXT_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.sh', '.md', '.txt']); // hooks are .js — rebrand them too
 
 function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite = true, log = () => {} }) {
-  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, notes: [] };
+  const summary = { skipped: false, skills: 0, moduleSkills: 0, settings: false, hooks: 0, scheduledTasks: 0, skippedFiles: [], excludedSkills: [], withdrawnSkills: [], rebrandRules: 0, claudeMd: false, writtenPaths: [], notes: [] };
+  // Every instance-relative path this run WROTE or REMOVED (task 1003957). `bongos upgrade`
+  // hands these to persistPin as artifactPaths, exactly as task 1003926 already does for
+  // regenerateApiArtifacts' output: committing only the pin left the materialized files dirty,
+  // so the NEXT sweep's clean-tree guard called them "a human's work" and skipped the instance
+  // FOREVER — an enrolled co-tenant upgraded exactly once (proven on `charter` 2026-09-16).
+  //
+  // Recording what we wrote is a STRONGER provenance than a static file list: every path here
+  // is one this very run produced. It cannot carry an owner's edit either, and not for the
+  // "generated end to end" reason API_ARTIFACT_FILES gives — for a sharper one. Under
+  // `overwrite` the copy ALREADY replaced whatever the file held before reaching this line, so
+  // the only choice left is commit that overwrite or strand the instance; leaving it dirty
+  // protects nothing and stops every future update. Under `overwrite: false` (the `init
+  // --adopt` path) nothing is clobbered — copyTreeTransformed reports those as `skipped` and
+  // addWritten ignores them — so an adopting instance records nothing here and commits nothing.
+  const rel = (p) => String(p).split(path.sep).join('/');
+  const addWritten = (p) => { summary.writtenPaths.push(rel(p)); };
+  // A copyTreeTransformed onFile that records real writes under `base` and ignores the
+  // leave-and-report entries adopt mode emits.
+  const recordUnder = (base) => (r, info) => { if (!info || !info.skipped) addWritten(path.join(base, r)); };
   if (path.resolve(instanceDir) === path.resolve(coreRoot)) {
     summary.skipped = true;
     summary.notes.push('instance dir is the core root — nothing to materialize (byte-identical no-op).');
@@ -410,6 +443,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   const skillsSrc = path.join(srcClaude, 'skills');
   const skillsRes = copyTreeTransformed(skillsSrc, path.join(destClaude, 'skills'), {
     dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), skip: skillSkip,
+    onFile: recordUnder('.claude/skills'),
   });
   summary.skills = skillsRes.files;
   summary.excludedSkills = skillsRes.excluded || [];
@@ -436,7 +470,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       summary.notes.push(`module skill "${s.name}" (${s.module}) also exists under the core's .claude/skills/ — the core copy was materialized, the module copy ignored.`);
       continue;
     }
-    const r = copyTreeTransformed(s.dir, path.join(destClaude, 'skills', s.name), { dryRun, overwrite, transform: (t) => rebrand(bongosify(t)) });
+    const r = copyTreeTransformed(s.dir, path.join(destClaude, 'skills', s.name), { dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), onFile: recordUnder(`.claude/skills/${s.name}`) });
     summary.moduleSkills += r.files;
     for (const rel of r.skipped || []) summary.skippedFiles.push(`skills/${s.name}/${rel}`);
   }
@@ -500,6 +534,10 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     for (const name of withdrawable.sort()) {
       const dir = path.join(skillsDest, name);
       if (!fs.existsSync(dir)) continue;
+      // A DELETION is a dirty path too, and `git status` names the individual files rather
+      // than the directory — so enumerate before removing, or the withdrawal is exactly the
+      // kind of leftover that wedges the next sweep (task 1003957).
+      for (const f of listFilesRecursive(dir)) addWritten(path.join('.claude/skills', name, f));
       if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
       summary.withdrawnSkills.push(name);
     }
@@ -514,6 +552,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
     const manifest = { _doc: 'GENERATED by scripts/gds/claude-materialize.js (task 1003632): the module-declared skills a materialize landed in this instance. It is the provenance record that lets a later run WITHDRAW a skill whose module has since been disabled — a name absent from here is never deleted, so a hand-written skill is safe. Commit it; do not hand-edit.', skills: Object.fromEntries(names.map((n) => [n, landedNow[n]])) };
     fs.mkdirSync(skillsDest, { recursive: true });
     fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
+    addWritten(path.join('.claude/skills', INSTANCE_SKILLS_MANIFEST));
   }
 
   // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
@@ -528,6 +567,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         fs.mkdirSync(destClaude, { recursive: true });
         fs.writeFileSync(settingsDest, rebrand(transformSettings(settingsSrc)));
       }
+      addWritten('.claude/settings.json');
       summary.settings = true;
       log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (hook commands→bongos, identity rebranded)`);
     }
@@ -547,6 +587,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         fs.mkdirSync(destClaude, { recursive: true });
         fs.writeFileSync(settingsDest, renderStarterSettings());
       }
+      addWritten('.claude/settings.json');
       summary.settings = true;
       summary.notes.push(`.claude/settings.json written from the starter — ${STARTER_ALLOW.length} blessed command(s), permissions only.`);
       log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} .claude/settings.json (starter: ${STARTER_ALLOW.length} blessed commands, no hooks)`);
@@ -557,7 +598,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   //    the founder origin/config-dir). Their core require()s self-resolve at runtime via
   //    the copied _core-resolve.js sibling (task 2139) — no path rewriting needed here.
   const hooksRes = copyTreeTransformed(path.join(srcClaude, 'hooks'), path.join(destClaude, 'hooks'), {
-    dryRun, overwrite, transform: rebrand, textExt: HOOK_TEXT_EXT,
+    dryRun, overwrite, transform: rebrand, textExt: HOOK_TEXT_EXT, onFile: recordUnder('.claude/hooks'),
   });
   summary.hooks = hooksRes.files;
   for (const rel of hooksRes.skipped || []) summary.skippedFiles.push(`hooks/${rel}`);
@@ -577,7 +618,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   //     paths: they resolve core require()s at runtime via the copied _core-resolve.js sibling
   //     (task 2139), and run-routine.js finds the routines under resolveInstanceRoot() post-split.
   const routinesRes = copyTreeTransformed(path.join(srcClaude, 'scheduled-tasks'), path.join(destClaude, 'scheduled-tasks'), {
-    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), textExt: HOOK_TEXT_EXT,
+    dryRun, overwrite, transform: (t) => rebrand(bongosify(t)), textExt: HOOK_TEXT_EXT, onFile: recordUnder('.claude/scheduled-tasks'),
   });
   summary.scheduledTasks = routinesRes.files;
   for (const rel of routinesRes.skipped || []) summary.skippedFiles.push(`scheduled-tasks/${rel}`);
@@ -601,6 +642,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       fs.mkdirSync(instanceDir, { recursive: true });
       fs.writeFileSync(claudeMdPath, renderInstanceClaudeMd(toBranding));
     }
+    addWritten('CLAUDE.md');
     summary.claudeMd = true;
     log(`  ${dryRun ? '[dry-run] would write' : '✓ wrote'} CLAUDE.md (starter, brand-substituted for this instance)`);
   }

package/scripts/gds/upgrade.js

@@ -1228,9 +1228,17 @@ async function runUpgrade(opts, deps = {}) {
   } else log('  • migrate skipped (--skip-migrate)');
 
   // 5. materialize .claude/ from the freshly-installed core.
+  //
+  // Its output rides the pin commit for the same reason the regenerated API artifacts below
+  // do (task 1003957 extending task 1003926): left dirty, the NEXT sweep's clean-tree guard
+  // reads `.claude/skills/*` as a human's uncommitted work and skips the instance forever —
+  // an enrolled co-tenant that upgrades exactly once. materializeClaude reports the paths it
+  // actually wrote or withdrew, so this is what THIS run touched, not a static list.
+  let materializedPaths = [];
   if (!opts.skipMaterialize) {
     const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
     const sum = materialize({ coreRoot, instanceDir, log: (m) => log(m) });
+    materializedPaths = sum.writtenPaths || [];
     log(`  ✓ materialized .claude/ (${sum.skills} skill file(s)${sum.settings ? ', settings.json' : ''}${sum.hooks ? `, ${sum.hooks} hook(s)` : ''})`);
   } else log('  • materialize skipped (--skip-materialize)');
 
@@ -1355,8 +1363,12 @@ async function runUpgrade(opts, deps = {}) {
   // actually coming: --commit-pin without --pin-no-push, not a dry run, and the pin
   // files really are dirty. Nothing reads a credential it will not spend (task 1003081).
   const remote = opts.gitRemote || 'origin';
+  // Everything this upgrade generated into the instance's tree: the API artifacts (task
+  // 1003926) and the materialized .claude/ (task 1003957). One list, so the push-credential
+  // probe and persistPin agree on what "the upgrade rewrote" means.
+  const generatedPaths = [...regenArtifacts, ...materializedPaths];
   const pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun
-    && ((dirtyPinFiles(instanceDir, run) || []).length > 0 || (dirtyPaths(instanceDir, regenArtifacts, run) || []).length > 0);
+    && ((dirtyPinFiles(instanceDir, run) || []).length > 0 || (dirtyPaths(instanceDir, generatedPaths, run) || []).length > 0);
   const pushAuth = pushComing ? await (deps.resolvePinPushAuth || resolvePinPushAuth)({ instanceDir, remote }, deps, run) : null;
   const pin = persistPin({
     instanceDir,
@@ -1367,7 +1379,7 @@ async function runUpgrade(opts, deps = {}) {
     remote,
     dryRun: opts.dryRun,
     pushAuth,
-    artifactPaths: regenArtifacts,
+    artifactPaths: generatedPaths,
   }, run, log, err);
 
   const ok = versionOk && healthOk !== false && servedOk !== false;

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

@@ -11,6 +11,15 @@
 //   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)
 //
+// task 1003107 adds the third: 'abandoned' is OVERLOADED, and one of the things
+// it covers is not cut work at all. `/tasks/:id/merge` is `abandonTask` plus a
+// target, so a task folded into a sibling and shipped there ends up 'abandoned'
+// carrying `merged_into_task_id`. On status alone it is indistinguishable from
+// dropped work — which is how task 1003005 read as a gap while the rename it
+// described had shipped under 1003004. These tests pin that the ABSORBED case is
+// told apart and given the remedy that fits, WITHOUT relaxing the gate: the
+// owner ruling above still holds, and an absorbed edge is still dead as written.
+//
 // Run:  node tests/dead_deps.mjs
 
 import { strict as assert } from 'node:assert';
@@ -20,7 +29,7 @@ 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 } =
+const { absorbedInto, depRefusalRow, 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();
@@ -171,4 +180,148 @@ await test('audit-deps exposes the --stranded mode and abandon.js reports what a
   assert.match(abandon, /LIVE_STATUSES/, 'and shares the live-status definition with the detector');
 });
 
+// ---- task 1003107: ABSORBED is not the same as dropped ---------------------
+
+const ABSORBED_DEP = Object.freeze({
+  kind: 'task', id: '1003005', title: 'Rename modules/governance to modules/government',
+  status: 'abandoned', merged_into_task_id: '1003004',
+  merged_into_status: 'shipped', merged_into_title: 'The rename, absorbed',
+});
+const DROPPED_DEP = Object.freeze({ kind: 'task', id: '999', title: 'Cut work', status: 'abandoned' });
+
+await test('an absorbed edge is still DEAD — the gate is not relaxed (owner ruling 2026-08-21)', () => {
+  const { dead, absorbed, pending } = splitDeadDeps([ABSORBED_DEP]);
+  assert.equal(dead.length, 1, 'still dead as written: it points at a row that will never ship');
+  assert.equal(absorbed.length, 1, 'and it is recognised as the absorbed kind');
+  assert.equal(pending.length, 0, 'it is not quietly reclassified as pending, which would release the dependent');
+  assert.equal(absorbed[0], dead[0], 'absorbed is a SUBSET of dead, not a fourth bucket');
+});
+
+await test('absorbed vs dropped are told apart, and neither is invented out of nothing', () => {
+  assert.equal(splitDeadDeps([DROPPED_DEP]).absorbed.length, 0, 'a plain abandon is not absorbed');
+  assert.equal(absorbedInto(DROPPED_DEP), null);
+  assert.equal(absorbedInto(ABSORBED_DEP), '1003004');
+  assert.equal(absorbedInto({ merged_into_task_id: null }), null);
+  assert.equal(absorbedInto({ merged_into_task_id: '' }), null, 'an empty string is not a task id');
+  assert.equal(absorbedInto(null), null);
+  assert.equal(absorbedInto({ merged_into_task_id: 1003004 }), '1003004', 'a numeric id normalises to a string');
+
+  const mixed = splitDeadDeps([DROPPED_DEP, ABSORBED_DEP]);
+  assert.equal(mixed.dead.length, 2);
+  assert.deepEqual(mixed.absorbed.map((d) => d.id), ['1003005']);
+});
+
+await test('the hint for an absorbed edge names the target and the RE-POINT remedy, not restore', () => {
+  const hint = deadDepHint([ABSORBED_DEP], 1003107);
+  assert.match(hint, /ABSORBED/, 'it does not call absorbed work abandoned');
+  assert.match(hint, /task 1003004/, 'it names the task that absorbed it');
+  assert.match(hint, /SHIPPED there/, 'and says the work exists');
+  assert.match(hint, /RE-POINT/, 'the remedy is to move the edge');
+  assert.doesNotMatch(hint, /promote/, 'it must NOT advise restoring a task nobody wants back');
+  assert.doesNotMatch(hint, /can NEVER satisfy/, 'that wording is false here — the work shipped');
+  // Both halves of the re-point are spelled out, against the right ids.
+  assert.match(hint, /DELETE[\s\S]*"to_id":1003005/, 'drop the stale edge');
+  assert.match(hint, /POST[\s\S]*"to_id":1003004/, 'add the real one');
+});
+
+await test('an absorbing task that has NOT shipped is described honestly', () => {
+  const hint = deadDepHint([{ ...ABSORBED_DEP, merged_into_status: 'active', merged_into_title: 'still going' }], 7);
+  assert.match(hint, /is being done there/, 'not claimed as shipped');
+  assert.doesNotMatch(hint, /SHIPPED there/);
+});
+
+await test('a plain abandoned edge keeps its original wording exactly', () => {
+  const hint = deadDepHint([DROPPED_DEP], 1003107);
+  assert.match(hint, /was ABANDONED/);
+  assert.match(hint, /can NEVER satisfy/);
+  assert.match(hint, /promote/, 'restore is still offered where it IS the right remedy');
+  assert.doesNotMatch(hint, /ABSORBED/);
+});
+
+await test('a mixed refusal leads with the absorbed edge and still accounts for the rest', () => {
+  const hint = deadDepHint([DROPPED_DEP, ABSORBED_DEP, { kind: 'task', id: '3', status: 'ready' }], 1003107);
+  assert.match(hint, /ABSORBED/, 'the absorbed case leads — its usual advice is the wrong one');
+  assert.match(hint, /1 other dead edge/, 'the genuinely abandoned one is not swallowed');
+  assert.match(hint, /1 other dependency is still genuinely pending/, 'and pending edges are still counted');
+});
+
+await test('the detector reports absorbed strands separately, because they have a mechanical fix', () => {
+  const stranded = findStrandedTasks([{
+    id: 1001702, status: 'ready', title: 'a live dependent',
+    blocked_by: [
+      { id: '1003005', title: 'absorbed one', status: 'abandoned', merged_into_task_id: '1003004' },
+      { id: '999', title: 'dropped one', status: 'abandoned' },
+    ],
+  }]);
+  assert.equal(stranded.length, 1);
+  assert.equal(stranded[0].dead_deps.length, 2, 'both are still strands — nothing is released');
+  assert.deepEqual(stranded[0].absorbed_deps.map((d) => d.id), ['1003005']);
+  assert.equal(stranded[0].absorbed_deps[0].merged_into_task_id, '1003004', 'carrying where to re-point');
+  assert.equal(stranded[0].dead_deps.find((d) => d.id === '999').merged_into_task_id, null);
+});
+
+await test('the merge pointer actually reaches these functions — both queries select it', () => {
+  const deps = readFileSync(new URL('../modules/lifecycle/db-deps-criteria.js', import.meta.url), 'utf8');
+  const hits = deps.match(/merged_into_task_id/g) || [];
+  // The count is the vacuity guard: this test is worthless if the field is
+  // absent from the SQL, and absence looks exactly like a passing regex.
+  assert.ok(hits.length >= 2, `expected the merge pointer in both dep queries, found ${hits.length}`);
+  assert.match(deps, /'merged_into_task_id', t2\.merged_into_task_id/, 'blocked_by carries it');
+  assert.match(deps, /x\.merged_into_task_id/, 'the claim-refusal rows carry it');
+  assert.match(deps, /LEFT JOIN tasks m ON m\.id = x\.merged_into_task_id/, 'and what became of the absorbing task');
+});
+
+// ---- the pointer has to survive the trip to the caller ---------------------
+//
+// The first version of task 1003107 enriched the QUERY and every test above
+// still passed, because they all hand-build dep rows with the pointer already
+// on them. On the real path three claim sites projected the row into a
+// four-field object and dropped it, so the ABSORBED branch was unreachable in
+// production. These are the tests that would have caught that.
+
+// A row shaped the way unsatisfiedDeps actually returns one — 'state', not
+// 'status', and the merge columns alongside.
+const RAW_ABSORBED_ROW = Object.freeze({
+  kind: 'task', id: '1003005', title: 'Rename modules/governance to modules/government',
+  state: 'abandoned', merged_into_task_id: '1003004',
+  merged_into_status: 'shipped', merged_into_title: 'The rename, absorbed',
+});
+
+await test('depRefusalRow carries the merge pointer from a QUERY row into the refusal shape', () => {
+  const row = depRefusalRow(RAW_ABSORBED_ROW);
+  assert.equal(row.status, 'abandoned', "the query's 'state' becomes the refusal's 'status'");
+  assert.equal(row.merged_into_task_id, '1003004');
+  assert.equal(row.merged_into_status, 'shipped');
+  assert.equal(row.merged_into_title, 'The rename, absorbed');
+});
+
+await test('a row for a task that was never merged keeps its exact previous shape', () => {
+  const row = depRefusalRow({ kind: 'task', id: '999', title: 'Cut work', state: 'abandoned' });
+  assert.deepEqual(Object.keys(row).sort(), ['id', 'kind', 'status', 'title']);
+  assert.equal(absorbedInto(row), null);
+});
+
+await test('END TO END: a query row projected by depRefusalRow reaches the ABSORBED branch', () => {
+  // This is the composition the live path runs: unsatisfiedDeps row →
+  // depRefusalRow → err.deps → deadDepHint. Asserting it here is the difference
+  // between the feature working and the feature being unreachable.
+  const hint = deadDepHint([depRefusalRow(RAW_ABSORBED_ROW)], 1003107);
+  assert.match(hint, /ABSORBED/, 'the branch fires on a row that came through the projection');
+  assert.match(hint, /task 1003004/);
+  assert.doesNotMatch(hint, /promote/);
+});
+
+await test('all three DEPS_NOT_SHIPPED sites use the shared mapper — none spells the object again', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/db-claims.js', import.meta.url), 'utf8');
+  const uses = (src.match(/\.map\(depRefusalRow\)/g) || []).length;
+  // The count IS the vacuity guard, and it is the exact number that was wrong
+  // before: three sites, all of which must be taught at once.
+  assert.equal(uses, 3, `expected all 3 claim paths to use depRefusalRow, found ${uses}`);
+  assert.doesNotMatch(
+    src, /status:\s*[rd]\.state/,
+    'a hand-built dep projection is back — it will silently drop whatever dead-deps.js learns next'
+  );
+  assert.match(src, /require\('\.\/dead-deps\.js'\)/, 'and it imports the mapper rather than copying it');
+});
+
 summary();

package/tests/upgrade_persist_pin.mjs

@@ -351,3 +351,129 @@ test('real git: an owner edit outside the generated files is never swept into th
   assert.equal(git(dir, 'status', '--porcelain').stdout, ' M config/branding.json\n');
   assert.ok(!git(dir, 'show', '--name-only', '--format=', 'HEAD').stdout.includes('config/branding.json'));
 });
+
+// ── the MATERIALIZED .claude/ rides the pin commit too (task 1003957) ───────────
+//
+// Task 1003926 (above) made regenerateApiArtifacts' output ride the pin commit. The OTHER
+// half of what an upgrade rewrites — materializeClaude's `.claude/skills|hooks|
+// scheduled-tasks` + settings.json — did not, so the tree stayed dirty and the NEXT sweep's
+// clean-tree guard read it as a human's work and skipped the instance. Proven on the
+// co-tenant `charter` 2026-09-16: it upgraded 1.19.737 → 1.19.785 successfully, left 6 skill
+// files dirty, and was skipped by every sweep afterwards.
+//
+// Both reported symptoms are this one cause. subscribe.js's post-upgrade commitPin REFUSES
+// when anything but the pin is dirty, which is simultaneously the `failed=1` on a successful
+// upgrade and the next sweep's permanent halt.
+
+const { materializeClaude } = require('../scripts/gds/claude-materialize.js');
+
+// A minimal core package: just the .claude/ tree materialize copies out of it.
+function scratchCore(version) {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-core-'));
+  put(dir, 'package.json', JSON.stringify({ name: '@bongos/core', version }));
+  put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
+  put(dir, '.claude/skills/builder-end/SKILL.md', `# builder-end (core ${version})\n`);
+  put(dir, '.claude/skills/builder-ship/SKILL.md', `# builder-ship (core ${version})\n`);
+  put(dir, '.claude/settings.json', JSON.stringify({ permissions: { allow: [version] } }, null, 2));
+  put(dir, '.claude/hooks/stop.js', `// hook for ${version}\n`);
+  return dir;
+}
+
+// A scaffolded co-tenant that already TRACKS the .claude/ a previous materialize landed.
+function scratchCoTenant(version = '1.19.737') {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-cotenant-'));
+  git(dir, 'init', '-q');
+  git(dir, 'config', 'user.email', 'upgrade-test@example.invalid');
+  git(dir, 'config', 'user.name', 'upgrade test');
+  git(dir, 'config', 'core.autocrlf', 'false');
+  put(dir, 'package.json', JSON.stringify({ dependencies: { '@bongos/core': version } }));
+  put(dir, 'package-lock.json', `lock ${version}\n`);
+  put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
+  put(dir, 'CLAUDE.md', 'the instance owns this\n');
+  materializeClaude({ coreRoot: scratchCore(version), instanceDir: dir, log: quiet });
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'scaffold');
+  return dir;
+}
+
+// One `bongos upgrade`: move the pin, materialize the new core, persist both.
+function sweep(dir, from, to, { artifactPaths } = {}) {
+  put(dir, 'package.json', JSON.stringify({ dependencies: { '@bongos/core': to } }));
+  put(dir, 'package-lock.json', `lock ${to}\n`);
+  const sum = materializeClaude({ coreRoot: scratchCore(to), instanceDir: dir, log: quiet });
+  const paths = artifactPaths === undefined ? sum.writtenPaths : artifactPaths;
+  const r = persistPin({ instanceDir: dir, fromVersion: from, toVersion: to, commitPin: true, push: false, artifactPaths: paths }, spawnSync, quiet, quiet);
+  return { sum, pin: r };
+}
+
+test('materializeClaude reports every path it wrote, as instance-relative POSIX paths', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-mat-'));
+  put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
+  const sum = materializeClaude({ coreRoot: scratchCore('1.19.785'), instanceDir: dir, log: quiet });
+  // 2 skills + settings.json + 1 hook + the provenance manifest + the starter CLAUDE.md.
+  assert.deepEqual([...sum.writtenPaths].sort(), [
+    '.claude/hooks/stop.js',
+    '.claude/settings.json',
+    '.claude/skills/.instance-skills.json',
+    '.claude/skills/builder-end/SKILL.md',
+    '.claude/skills/builder-ship/SKILL.md',
+    'CLAUDE.md',
+  ]);
+  assert.ok(sum.writtenPaths.every((p) => !p.includes('\\')), 'git wants forward slashes on every platform');
+});
+
+test('real git: the done-when — two consecutive co-tenant sweeps, no human hands', () => {
+  const dir = scratchCoTenant();
+  for (const [from, to] of [['1.19.737', '1.19.785'], ['1.19.785', '1.19.786']]) {
+    assert.equal(gitTreeClean(dir).ok, true, `the clean-tree pre-flight passes before ${to}`);
+    const { pin } = sweep(dir, from, to);
+    assert.equal(pin.committed, true, `upgrade to ${to} committed`);
+    assert.equal(git(dir, 'status', '--porcelain').stdout, '', `upgrade to ${to} leaves NOTHING dirty`);
+  }
+});
+
+test('real git: WITHOUT the materialized paths the instance wedges after exactly one sweep', () => {
+  const dir = scratchCoTenant();
+  sweep(dir, '1.19.737', '1.19.785', { artifactPaths: [] }); // the pre-1003957 behaviour
+  const dirty = git(dir, 'status', '--porcelain').stdout;
+  assert.match(dirty, /\.claude\/skills\/builder-end\/SKILL\.md/, 'the materialized output is what stayed behind');
+  assert.equal(gitTreeClean(dir).ok, false, 'so the NEXT sweep halts here — forever');
+});
+
+test('real git: an owner edit is never swept into the pin commit, tracked or untracked', () => {
+  const dir = scratchCoTenant();
+  put(dir, 'config/branding.json', 'the owner was here\n');
+  put(dir, '.claude/skills/my-own-skill/SKILL.md', 'hand-written — no materialize ever landed this\n');
+  sweep(dir, '1.19.737', '1.19.785');
+  const committed = git(dir, 'show', '--name-only', '--format=', 'HEAD').stdout;
+  assert.ok(!committed.includes('config/branding.json'), 'a tracked owner edit stays the owner\'s');
+  assert.ok(!committed.includes('my-own-skill'), 'a hand-written skill is not materialize output, so it is not ours to commit');
+  assert.match(git(dir, 'status', '--porcelain').stdout, /config\/branding\.json/, 'and it is still there afterwards');
+});
+
+test('real git: a skill WITHDRAWN by the upgrade is committed as a deletion, not left dirty', () => {
+  const dir = scratchCoTenant();
+  // A skill a previous materialize landed and this core no longer ships.
+  const core = scratchCore('1.19.785');
+  put(dir, '.claude/skills/retired/SKILL.md', 'landed by an older core\n');
+  writeFileSync(join(dir, '.claude/skills/.instance-skills.json'),
+    JSON.stringify({ skills: { retired: { module: 'gone', source: 'modules/gone/skills/retired' } } }, null, 2) + '\n');
+  git(dir, 'add', '-A'); git(dir, 'commit', '-q', '-m', 'an older core');
+  const sum = materializeClaude({ coreRoot: core, instanceDir: dir, log: quiet });
+  assert.deepEqual(sum.withdrawnSkills, ['retired']);
+  assert.ok(sum.writtenPaths.includes('.claude/skills/retired/SKILL.md'), 'a deletion is a dirty path too');
+  persistPin({ instanceDir: dir, fromVersion: '1.19.737', toVersion: '1.19.785', commitPin: true, push: false, artifactPaths: sum.writtenPaths }, spawnSync, quiet, quiet);
+  assert.equal(git(dir, 'status', '--porcelain').stdout, '', 'the withdrawal is committed, so nothing wedges the next sweep');
+});
+
+test('adopt mode records nothing, so `init --adopt` never commits over what it refused to clobber', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-adopt-'));
+  put(dir, 'config/branding.json', JSON.stringify({ identity: {} }));
+  put(dir, '.claude/skills/builder-end/SKILL.md', 'the adopting project already had this\n');
+  put(dir, '.claude/settings.json', '{"mine":true}');
+  put(dir, 'CLAUDE.md', 'mine\n');
+  const sum = materializeClaude({ coreRoot: scratchCore('1.19.785'), instanceDir: dir, overwrite: false, log: quiet });
+  assert.ok(!sum.writtenPaths.includes('.claude/skills/builder-end/SKILL.md'), 'a file it declined to clobber was never written');
+  assert.ok(!sum.writtenPaths.includes('.claude/settings.json'));
+  assert.equal(readFileSync(join(dir, '.claude/skills/builder-end/SKILL.md'), 'utf8'), 'the adopting project already had this\n');
+});