@bongos/core 1.19.641 → 1.19.643

package/docs/module-api-changelog.md

@@ -1731,5 +1731,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.639 with no explicit bump. run 34506041899. (task 1002620)
   1.19.641 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.640 with no explicit bump. run 34506718627. (task 1002620)
+  1.19.642 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.641 with no explicit bump. run 34507442448. (task 1002620)
+  1.19.643 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.642 with no explicit bump. run 34509123612. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/builder-settings/builder-needs.js

@@ -121,6 +121,14 @@ function helpRequestsNeed(ctx) {
 
 // The registry. To add a future input the system needs from a builder, append a
 // pure (ctx) => need|null function here — every renderer picks it up for free.
+//
+// A need MAY carry `count: <positive integer>` (task 1003737) when the thing
+// waiting is countable. That is what a nav badge renders, and it is the whole
+// contract: the shell names a need id and reads this number, so a second
+// consumer — open help requests, the idea inbox — adopts the badge by adding
+// this one field rather than inventing a second notification mechanism.
+// The count is ADVISORY DECORATION, never authority: the roster's own ordering
+// (NEED_PRIORITY) and each surface's gate decide what a builder actually sees.
 // Open task RECOMMENDATIONS waiting on this builder (task 1003173 / C03, goal
 // 1000075; criterion collab-pass-a-task). Sibling of helpRequestsNeed above, and
 // here for the same reason C01's grader round put that one here: a recommendation
@@ -184,6 +192,12 @@ function boardVotesNeed(ctx) {
   const subject = n === 1 ? 'An idea is' : `${n} ideas are`;
   return {
     id: 'board_votes',
+    // The number, machine-readable (task 1003737). The message has always
+    // carried it in prose, which a sentence can render and a BADGE cannot. A
+    // need that is inherently countable states its count here; a need that is
+    // not (art_key — a key is set or it is not) simply omits it, and every
+    // renderer treats an absent count as "nothing to put in a badge".
+    count: n,
     title: n === 1 ? 'An idea is waiting on your vote' : 'Ideas are waiting on your vote',
     what: 'You sit on the board, and a Full Idea that cleared the completeness grade needs a decision.',
     state: 'action_needed',

package/modules/hall-ui/public/hall-render.js

@@ -216,6 +216,11 @@
       // the same reason: without it the index — the hall's busiest page — is the
       // one page a permission-gated nav item would never appear on.
       permissions: (ctx.lastMeState && ctx.lastMeState.permissions) || null,
+      // task 1003737: the needs roster, for the nav counts. Read off
+      // ctx.lastMeState for the same reason the two above are, and passed for the
+      // same reason: the index is where a builder lands, so omitting it here
+      // would mean the badge appeared everywhere EXCEPT the page they open first.
+      needs: (ctx.lastMeState && ctx.lastMeState.needs) || null,
       builder,
     });
 

package/modules/hall-ui/public/shell.js

@@ -129,6 +129,23 @@
   //               stays hidden — deliberately, since an unresolvable gate is a gate
   //               that cannot be vouched for.
   // `view` marks an index view (hash-routed); `module` gates on window.__MODULES__.
+  //
+  // `count` (task 1003737) names a NEED ID in the `needs` roster `/me` already
+  // returns; the item then carries a badge with that need's `count`. It is the
+  // hall's only badge mechanism and it is deliberately generic — a second
+  // consumer (open help requests, the idea inbox) adds `count: '<need id>'` here
+  // and a `count` field to its need, and inherits the rest.
+  //
+  // THREE RULES THE MECHANISM ENFORCES, not the caller:
+  //   ZERO IS SILENT — no badge, no empty ring. A badge means something is
+  //     genuinely waiting, so an absent need, a zero/absent count, or a need the
+  //     founding grace has quieted out of 'action_needed' all render nothing.
+  //   IT NEVER OUT-RUNS THE GATE — the badge is written only onto an item this
+  //     viewer can already see, and cleared from one they cannot, so a count can
+  //     never disclose activity in a room that is hidden from them.
+  //   IT SPEAKS — the numeral is aria-hidden and the need's own `title` rides
+  //     alongside it as sr-only text, because "3" alone in a link tells a screen
+  //     reader nothing about what is waiting.
   // task 2175: grouped by AUDIENCE of the data, so the sidebar reads in coherent
   // runs instead of one long list — the project (unlabeled), You, Community,
   // Docs, Government. A group's `gate` must match its most permissive item's, or the
@@ -168,7 +185,12 @@
       // are unchanged.
       //
       // Cosmetic only, as every gate here is — the page gate is the wall (ADR 0016).
-      { id: 'board-room', label: 'Board Room', icon: 'admin', href: '/board-room', gate: 'perm:board.vote.cast' },
+      // task 1003737: the badge's first consumer. The owner's ask was to see that
+      // a sitting waits WITHOUT opening the room, and the count is already on
+      // /me (boardVotesNeed), pre-filtered to what the vote route would accept —
+      // so the badge counts ballots this viewer can actually cast, never "items
+      // open somewhere".
+      { id: 'board-room', label: 'Board Room', icon: 'admin', href: '/board-room', gate: 'perm:board.vote.cast', count: 'board_votes' },
       // task 1003113 (R02 of goal 1000074): the artist's queue over the words the
       // product shows people. gate 'signed' and NOT a craft gate — filing a flag
       // is open to every role on purpose (the engineer who wrote the toast and
@@ -344,8 +366,24 @@
           (it.external ? ' target="_blank" rel="noopener"' : '') +
           (it.view ? ' data-view="' + it.view + '"' : '') +
           ' data-gate="' + it.gate + '"' + (it.module ? ' data-module="' + it.module + '"' : '') +
+          (it.count ? ' data-count="' + esc(it.count) + '"' : '') +
           ' title="' + esc(it.label) + '" hidden>' + icon(it.icon) +
-          '<span class="nav-item__label">' + esc(it.label) + '</span></a>';
+          '<span class="nav-item__label">' + esc(it.label) + '</span>' +
+          // task 1003737: the badge ships EMPTY and hidden, and applyCounts fills
+          // it. Rendered here rather than injected later so the anchor's shape is
+          // fixed at first paint — a badge appended after the /me round-trip
+          // would reflow the rail under the reader's cursor.
+          //
+          // Two nodes, because they address two audiences: the numeral is
+          // aria-hidden decoration for the eye, and the sr-only span carries the
+          // need's own sentence for a screen reader. One node cannot do both —
+          // "3" read aloud inside a link named Board Room says nothing about what
+          // the 3 is.
+          (it.count
+            ? '<span class="nav-item__badge" data-badge aria-hidden="true" hidden></span>'
+              + '<span class="sr-only" data-badge-label></span>'
+            : '') +
+          '</a>';
       }).join('');
       // task 1003303: aria-controls names the region the head discloses. The
       // frozen markup carried aria-expanded pointing at nothing, which is an
@@ -559,7 +597,7 @@
   // not establish authority. null is NOT "holds nothing that matters": it is
   // unreadable, and unreadable hides the link, the same call gateAllows()'s
   // `default: false` and the social mode's OFF-is-the-fallback rule make.
-  var access = { authed: null, rank: null, graduated: false, showWork: false, permissions: null };
+  var access = { authed: null, rank: null, graduated: false, showWork: false, permissions: null, needs: null };
 
   function gateAllows(gate) {
     var authed = access.authed === true;
@@ -626,8 +664,47 @@
     el.classList.toggle('nav-item--craft', isArtist);
   }
 
-  // applyAccess({ authed, rank, graduated, showWork, social }) — settle nav
-  // visibility and the social mode.
+  // task 1003737: the nav badge mechanism. Reads the `needs` roster `/me`
+  // already returns and writes the count onto every item that declared one.
+  //
+  // WHY IT RUNS INSIDE applyAccess AND AFTER THE GATE LOOP, not beside it: the
+  // gate loop is the thing that decides whether this viewer may see the item at
+  // all, so reading `el.hidden` afterwards is reading the answer rather than
+  // re-deriving it — the same discipline task 1003744 applied to `permissions`
+  // (a surface that decides for itself can disagree with the rest of the hall).
+  // A hidden item is CLEARED rather than skipped: skipping would leave a stale
+  // count in the DOM of someone who just lost access to the room.
+  //
+  // Silence has four causes and they are deliberately indistinguishable to the
+  // reader: no needs payload yet (the /me round-trip is still out), no such need,
+  // a need the founding grace has moved out of 'action_needed', or a count of
+  // zero. In every one of them the honest badge is no badge.
+  function applyCounts() {
+    var needs = (access.needs && Array.isArray(access.needs.items)) ? access.needs.items : [];
+    document.querySelectorAll('#app-sidebar .nav-item[data-count]').forEach(function (el) {
+      var badge = el.querySelector('[data-badge]');
+      var label = el.querySelector('[data-badge-label]');
+      if (!badge || !label) return;
+      var need = null;
+      for (var i = 0; i < needs.length; i++) {
+        if (needs[i] && needs[i].id === el.dataset.count) { need = needs[i]; break; }
+      }
+      // 'action_needed' is the gate on LOUDNESS: the founding grace rewrites a
+      // demanding need to 'covered' precisely so a newborn instance does not
+      // greet its owner with demands, and a badge is a demand.
+      var n = (need && need.state === 'action_needed') ? Number(need.count) : 0;
+      var show = !el.hidden && Number.isFinite(n) && n > 0;
+      badge.hidden = !show;
+      badge.textContent = show ? (n > 99 ? '99+' : String(n)) : '';
+      // The need's own title, which is already a sentence written for a person
+      // ("Ideas are waiting on your vote"). Falling back to a bare count would
+      // reintroduce exactly the floating numeral this avoids.
+      label.textContent = show ? (need.title || (n + ' waiting')) : '';
+    });
+  }
+
+  // applyAccess({ authed, rank, graduated, showWork, social, needs }) — settle nav
+  // visibility, the social mode, and the nav counts.
   // Called by builders.js on the index (it owns /me there) and by the shell's own
   // probe elsewhere. Cosmetic only; the server enforces (ADR 0016).
   function applyAccess(state) {
@@ -643,6 +720,11 @@
       if ('permissions' in state) {
         access.permissions = (state.permissions && typeof state.permissions === 'object') ? state.permissions : null;
       }
+      // task 1003737: the needs roster, for the nav counts. Stored as given —
+      // null means "the shell has not been told yet", which reads as no badge.
+      if ('needs' in state) {
+        access.needs = (state.needs && typeof state.needs === 'object') ? state.needs : null;
+      }
       if ('social' in state) applySocial(state.social);
       if (state.builder) { renderUser(state.builder); applyCraftEmphasis(state.builder); }
     }
@@ -651,6 +733,10 @@
       if (ok && el.dataset.module && !moduleOn(el.dataset.module)) ok = false;
       el.hidden = !ok;
     });
+    // AFTER the gate loop: applyCounts reads el.hidden, which the loop above is
+    // what settles. Reversing the order would badge an item still hidden from
+    // the previous state.
+    applyCounts();
     var signin = document.getElementById('shell-signin');
     if (signin) signin.hidden = access.authed !== false;
     var user = document.getElementById('shell-user');
@@ -862,6 +948,10 @@
         social: me.social || null,
         // task 1003744: the resolved permission map, for the `perm:` nav gates.
         permissions: me.permissions || null,
+        // task 1003737: the needs roster, for the nav counts. Same payload the
+        // hall's Standing card and the CLI nudge read — no new route, no extra
+        // poll, and the badge cannot disagree with the roster it came from.
+        needs: me.needs || null,
         builder: me.builder,
       });
     }).catch(function () { /* cosmetic only */ });

package/modules/hall-ui/public/style.css

@@ -667,6 +667,40 @@ main:focus { outline: none; }
 .nav-item--craft .nav-icon,
 .nav-item--craft .nav-item__label { color: var(--accent-ink); }
 
+/* task 1003737: the nav count badge — the hall's only badge mechanism, built
+   once and generically (shell.js `count:` names a need id; see the NAV model).
+   ABSOLUTE, not inline, because the rail has two shapes: it is a 64px icon strip
+   until hover/focus opens it, and the badge has to read in BOTH — the whole ask
+   was to see that a sitting waits WITHOUT opening anything. Anchoring it to the
+   icon's top-right corner is the one position that survives the label leaving
+   and re-entering the layout, so nothing reflows when the rail opens.
+   Accent because the world's grammar reserves accent for the one live thing
+   (the same rule --active and --craft follow); shell.js keeps it off entirely
+   when the count is zero, so an accent here always means something waits. */
+.nav-item__badge {
+  position: absolute;
+  top: 3px;
+  right: 3px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 17px;
+  height: 17px;
+  padding: 0 5px;
+  border-radius: var(--radius-pill);
+  background: var(--accent);
+  color: var(--accent-on);
+  font-size: 11px;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  pointer-events: none;
+}
+/* Open rail: the item grows a 12px gutter and left-aligns, so the badge follows
+   the right edge rather than sitting over the label's tail. */
+.app-sidebar:hover .nav-item__badge,
+.app-sidebar:focus-within .nav-item__badge { top: 50%; right: 12px; transform: translateY(-50%); }
+
 .app-sidebar__foot {
   padding: 10px 0;
   border-top: 1px solid var(--glass-edge);
@@ -1015,6 +1049,10 @@ main:focus { outline: none; }
   .nav-group--collapsible .nav-group__head { display: flex; }
   .app-sidebar__brand { justify-content: flex-start; padding: 0 22px; }
   .nav-item, .shell-home, .shell-signout { justify-content: flex-start; padding: 0 12px; }
+  /* task 1003737: the drawer IS the rail already open, and there is no hover on
+     a phone to trigger the open-rail rule — so the badge takes the open position
+     here unconditionally, or it would sit over the label on every mobile view. */
+  .nav-item__badge { top: 50%; right: 12px; transform: translateY(-50%); }
   .app-sidebar__foot { align-items: stretch; padding: 12px 16px; }
   .shell-user { justify-content: flex-start; }
   .topbar-menu { display: flex; }

package/modules/lifecycle/rot.js

@@ -80,6 +80,54 @@ const GOAL_VERBS = Object.freeze([
   Object.freeze({ verb: 'water', label: 'Water', method: 'POST', path: '/goals/:id/water', hint: 'leave it — reset the clock' }),
 ]);
 
+// WHICH of those verbs a given row may actually be offered — the half the list
+// above cannot express. A verb list attached by TIER alone is a list of what the
+// tier CAN do, not of what THIS row can do, and the two differ: promote and demote
+// are each valid for a disjoint set of statuses, so on every row in this feed one
+// of the two is a button whose route answers 409. That is exactly the drift the
+// note above says the design prevents ("the client renders what the server will
+// actually accept"); the intent was right and the implementation ignored status
+// (task 1003751).
+//
+// Mirrored from the route guards, which are the authority:
+//   prioritise -> POST /tasks/:id/promote refuses anything but backlog|blocked|
+//                 abandoned  ('cannot_promote', modules/lifecycle/routes/tasks.js)
+//   prune      -> POST /tasks/:id/demote  refuses anything but ready
+//                 ('cannot_demote', same file)
+// A verb ABSENT from this map is unconditional across the rottable set, and each
+// absence is a fact about its route rather than an omission:
+//   kill  -> /tasks/:id/abandon refuses only a shipped task or one holding an
+//            active claim. Neither can appear here: 'shipped' is not rottable, and
+//            a claimed task is 'active', which is not rottable either.
+//   water -> filters on TASK_ROTTABLE_STATUSES itself, which IS this feed's set.
+// Because the copy is unavoidable, tests/rot_inbox.mjs reads the accepted statuses
+// back out of the route source and fails if the two ever disagree — the same
+// pairing guard the rot clock gets against migration core_231.
+//
+// A SECOND copy of this decision lives in scripts/gds/backlog-review.js
+// (`verbsFor`, task 1003746), deliberately: that script is an HTTP client that must
+// run from a scoped checkout without loading the server's module tree, so it cannot
+// require this file. The route-guard pairing test below is what keeps both honest.
+const TASK_VERB_ACCEPTS = Object.freeze({
+  prioritise: Object.freeze(['backlog', 'blocked', 'abandoned']),
+  prune: Object.freeze(['ready']),
+});
+
+// verbsFor(tier, status) — the verbs to attach to ONE row: the tier's catalogue
+// narrowed to what this row's status will actually be accepted for.
+//
+// A goal gets its two unconditionally: /goals/:id/archive refuses only an ALREADY
+// archived goal, and /goals/:id/water filters on the rottable set — so for a goal
+// in this feed (status 'open') both always apply.
+function verbsFor(tier, status) {
+  if (tier === 'goal') return GOAL_VERBS;
+  const s = String(status);
+  return Object.freeze(TASK_VERBS.filter((v) => {
+    const accepts = TASK_VERB_ACCEPTS[v.verb];
+    return !accepts || accepts.includes(s);
+  }));
+}
+
 const MAX_ROT_ROWS = 200;
 
 // rottingFor({ builderId, canSeeAll, rotDays, limit }) — the rot lines this caller
@@ -146,7 +194,7 @@ async function rottingFor({ builderId, canSeeAll = false, rotDays, limit = 50 }
 
   const cutoffAt = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
   return {
-    rows: rows.map((r) => ({ ...r, verbs: r.tier === 'task' ? TASK_VERBS : GOAL_VERBS })),
+    rows: rows.map((r) => ({ ...r, verbs: verbsFor(r.tier, r.status) })),
     rotDays: days,
     cutoff: cutoffAt,
   };
@@ -203,6 +251,8 @@ module.exports = {
   GOAL_ROT_CLOCK,
   TASK_VERBS,
   GOAL_VERBS,
+  TASK_VERB_ACCEPTS,
+  verbsFor,
   MAX_ROT_ROWS,
   rottingFor,
   water,

package/package-lock.json

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

package/package.json

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

@@ -320,7 +320,7 @@ 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: [], 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, notes: [] };
   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).');
@@ -351,7 +351,11 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   // carries them as untracked copies plus two dotfiles; step 1 must not ship those as core
   // skills — step 1b lands them from the module, transformed, like everywhere else.
   const materialisedInCore = readModuleSkillsManifest(path.join(coreRoot, '.claude', 'skills')).skills;
-  const skillSkip = (rel) => { const top = String(rel).split(/[\\/]/)[0]; return skipSkills.has(top) || top === MODULE_SKILLS_MANIFEST || top === '.gitignore' || Object.prototype.hasOwnProperty.call(materialisedInCore, top); };
+  // The INSTANCE's own provenance record — what a PREVIOUS materialize landed here.
+  // Distinct from materialisedInCore above (that one is the core checkout's). Step 1c
+  // withdraws from this set and nothing else.
+  const landedPreviously = readInstanceSkillsManifest(path.join(destClaude, 'skills')).skills;
+  const skillSkip = (rel) => { const top = String(rel).split(/[\\/]/)[0]; return skipSkills.has(top) || top === MODULE_SKILLS_MANIFEST || top === INSTANCE_SKILLS_MANIFEST || top === '.gitignore' || Object.prototype.hasOwnProperty.call(materialisedInCore, top); };
 
   // 1. skills — ship in the core package; copy, rewrite invocations→bongos, rebrand
   //    identity, and exclude any skill owned by a disabled module.
@@ -390,6 +394,67 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   }
   if (summary.moduleSkills) log(`  ${dryRun ? '[dry-run] would materialize' : '✓ materialized'} ${summary.moduleSkills} module-owned skill file(s) → .claude/skills/ (from modules/<key>/skills/)`);
 
+  // 1c. WITHDRAW a skill a previous materialize landed here that this run no longer
+  //     lands — the module was switched off (or stopped declaring the name) on an
+  //     instance that ALREADY has the files. Step 1's skillSkip and step 1b's
+  //     `enabled` check both only decline to COPY, which is the whole bug: disabling
+  //     a module was honoured on a fresh instance and silently ignored on
+  //     `bongos upgrade`, leaving stale dirs in .claude/skills/ for the harness to
+  //     keep loading (task 1003632, found by the on/off proof of task 1003331).
+  //     materializeModuleSkillsIntoCore has done this for the core checkout since
+  //     task 1003330; this is the same mechanism for the instance side.
+  //
+  //     PROVENANCE-GATED, and that gate is the safety property: only a name the
+  //     manifest says a previous run LANDED is eligible. A skill the instance's owner
+  //     wrote by hand was never in the manifest, so it can never be deleted here even
+  //     if a module happens to declare the same name. With no manifest at all — an
+  //     instance last materialized before this shipped — nothing is withdrawn and a
+  //     note says so: that first run writes the provenance, and every run after it
+  //     honours a disable. Refusing to guess is the point; deleting a builder's skill
+  //     because we cannot prove we put it there is the one outcome worth avoiding.
+  const skillsDest = path.join(destClaude, 'skills');
+  const landedNow = {};
+  for (const src of sources) {
+    if (!src.enabled) continue;
+    // A dry run copied nothing, so it records what WOULD land; a real run confirms
+    // the dir is actually there before claiming provenance over it.
+    if (!dryRun && !fs.existsSync(path.join(skillsDest, src.name))) continue;
+    landedNow[src.name] = { module: src.module, source: path.relative(coreRoot, src.dir).split(path.sep).join('/'), vendored: src.vendored };
+  }
+  // A core-SHIPPED skill whose name a module also declares is landed by step 1, not
+  // step 1b — but it is withdrawable by the same disabled-module rule, so it needs
+  // provenance too.
+  for (const mod of roster) {
+    if (!mod.enabled) continue;
+    for (const name of mod.skills) {
+      if (landedNow[name] || !fs.existsSync(path.join(skillsSrc, name))) continue;
+      landedNow[name] = { module: mod.key, source: `.claude/skills/${name}`, coreShipped: true };
+    }
+  }
+  const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n]);
+  if (!overwrite) {
+    // adopt mode never clobbers what the owner already has; withdrawing is a clobber.
+    if (withdrawable.length) summary.notes.push(`${withdrawable.length} skill(s) of a now-disabled module were left in place (adopt mode does not withdraw): ${withdrawable.sort().join(', ')}.`);
+  } else {
+    for (const name of withdrawable.sort()) {
+      const dir = path.join(skillsDest, name);
+      if (!fs.existsSync(dir)) continue;
+      if (!dryRun) fs.rmSync(dir, { recursive: true, force: true });
+      summary.withdrawnSkills.push(name);
+    }
+    if (summary.withdrawnSkills.length) log(`  ${dryRun ? '[dry-run] would withdraw' : '✓ withdrew'} ${summary.withdrawnSkills.length} stale skill dir(s) whose module is no longer enabled: ${summary.withdrawnSkills.join(', ')}`);
+  }
+  if (!Object.keys(landedPreviously).length && summary.excludedSkills.length) {
+    summary.notes.push('no .instance-skills.json provenance in .claude/skills/ yet, so nothing was withdrawn — this run records it; a later run can withdraw the skills of a module that has since been disabled.');
+  }
+  // Record what landed, so the NEXT run can withdraw what this one placed.
+  if (!dryRun && overwrite) {
+    const names = Object.keys(landedNow).sort();
+    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');
+  }
+
   // 2. settings.json — topology; present in the checkout/core repo, absent in a package-only install.
   const settingsSrc = path.join(srcClaude, 'settings.json');
   if (fs.existsSync(settingsSrc)) {
@@ -494,10 +559,23 @@ function isCoreCheckoutRoot(root) {
 }
 
 const MODULE_SKILLS_MANIFEST = '.module-skills.json';
-function readModuleSkillsManifest(skillsDir) {
-  const m = readJsonSafe(path.join(skillsDir, MODULE_SKILLS_MANIFEST));
+// The INSTANCE-side provenance record, deliberately a DIFFERENT filename from the
+// core's (task 1003632). They are different artifacts: MODULE_SKILLS_MANIFEST lists
+// the untracked copies materializeModuleSkillsIntoCore made inside a core CHECKOUT,
+// and is asserted never to travel to an instance; this one lists what materializeClaude
+// landed INTO an instance, and is what step 1c withdraws against. Sharing one name made
+// the instance's own record look like a core dotfile that had leaked across the boundary.
+const INSTANCE_SKILLS_MANIFEST = '.instance-skills.json';
+function readSkillsManifest(skillsDir, file) {
+  const m = readJsonSafe(path.join(skillsDir, file));
   return m && m.skills && typeof m.skills === 'object' ? m : { skills: {} };
 }
+function readModuleSkillsManifest(skillsDir) {
+  return readSkillsManifest(skillsDir, MODULE_SKILLS_MANIFEST);
+}
+function readInstanceSkillsManifest(skillsDir) {
+  return readSkillsManifest(skillsDir, INSTANCE_SKILLS_MANIFEST);
+}
 function materializeModuleSkillsIntoCore({ coreRoot, dryRun = false, clean = false, log = () => {} }) {
   const skillsDir = path.join(coreRoot, '.claude', 'skills');
   const summary = { materialized: [], removed: [], refused: [], excluded: [], keptCore: [], files: 0, notes: [] };
@@ -559,4 +637,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, transformSettings, copyTreeTransformed, materializeClaude, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/src/bongos/db.js

@@ -517,11 +517,12 @@ async function getLatestRankChangeForBuilder(builderId) {
 // Graceful builder exit (V3.R88 #307). Deactivating a builder is reversible
 // and lossless: drachmae (credits) + credit_log, shipped tasks, and historical
 // session_logs all stay. What changes: status → inactive (blocks new claims via
-// claimTask's guard), rank → 'xenos' (sandboxed tier), active claims released
-// cleanly with a final 'abandoned' session_log sealing each, and the tasks
-// returned to 'ready' for someone else. Reactivation flips status back; rank
-// is NOT auto-restored (an Archon re-promotes deliberately via PATCH
-// /builders/:id/rank). Memory archival is local-first and handled by the
+// claimTask's guard), rank → 'xenos' (sandboxed tier) WITH its seeded rank-role
+// rotated to match (task 1003193 — the direct SQL used to skip that), active claims
+// released cleanly with a final 'abandoned' session_log sealing each, and the tasks
+// returned to 'ready' for someone else. Reactivation flips status back and re-syncs
+// the rank-role; rank itself is NOT auto-restored (an Archon re-promotes deliberately
+// via PATCH /builders/:id/rank). Memory archival is local-first and handled by the
 // /builder-exit skill — the server never holds another builder's local memory
 // (the server-side memory store is criterion #54's job, not this task's).
 
@@ -571,6 +572,18 @@ async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
                   deactivated_at, reactivated_at, deactivated_reason`,
       [builderId, reason ?? null]
     );
+    // BV1.R95b — rotate the seeded rank-role IN THIS TRANSACTION, exactly as
+    // _applyRankChangeTx does (task 1003193). The UPDATE above forces rank to
+    // 'xenos' by direct SQL rather than through setBuilderRank, so without this the
+    // builder's OLD seeded rank-role (archon, say) survives in
+    // government_builder_ranks — getRankKeysForBuilder has no builders.status filter.
+    // It is not a live grant while they are inactive (every session is revoked below
+    // and requireBuilder denies 'inactive' per request), but reactivateBuilder flips
+    // status back without touching rank, so the stale-high role would return live.
+    // The rank is read back from the row just written rather than re-spelled here.
+    // Deliberately uncaught, for the same reason as the twin: a committed
+    // deactivation whose rotation failed IS the privilege-retention bug.
+    await syncGovernanceRankRole(client, builderId, updated[0].rank);
     // Interim audit (→ audit_log when R36 lands). delta=0 = no-op for credits.
     await client.query(
       `INSERT INTO credit_log (builder_id, task_id, delta, reason)
@@ -629,6 +642,15 @@ async function reactivateBuilder({ builderId, actorBuilderId }) {
     );
     // Rank is intentionally left at whatever it is (xenos after a deactivation):
     // an Archon re-promotes deliberately via PATCH /builders/:id/rank.
+    //
+    // REACTIVATION IS THE EXPOSURE (task 1003193). Rank does not move here, but
+    // status flipping back to 'active' makes whatever seeded rank-role the builder
+    // still holds live again — getActiveBuildersWithRank, builderHoldsRankActive,
+    // the board roll and the R10 tally denominator all read it. So sync to the row's
+    // CURRENT rank: a stale-high role left by a deactivation predating this fix (or
+    // drifted in from anywhere else) is removed as PART of the reactivation rather
+    // than after it. Idempotent — a consistent builder costs two SELECTs, no write.
+    await syncGovernanceRankRole(client, builderId, updated[0].rank);
     await client.query(
       `INSERT INTO credit_log (builder_id, task_id, delta, reason)
        VALUES ($1, NULL, 0, $2)`,

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