@bongos/core 1.19.642 → 1.19.643

package/docs/module-api-changelog.md

@@ -1733,5 +1733,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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.642",
+  "version": "1.19.643",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.642",
+      "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.642",
+  "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/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.642'; // 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');

package/tests/claude_materialize.mjs

@@ -255,6 +255,98 @@ t('disabledModuleSkills: only skills of DISABLED modules are collected (default
   rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- withdrawing a disabled module's skills on an EXISTING instance (task 1003632) ----
+// The bug: materializeClaude honoured `{"<key>": false}` on a FRESH instance (nothing
+// was copied) but only ever declined to COPY — so on an instance that already had the
+// files, `bongos upgrade` left them in .claude/skills/ for the harness to keep loading.
+// The withdrawal is PROVENANCE-GATED, which is the property that matters most here: a
+// skill the instance's owner wrote by hand is never in the manifest, so it must survive
+// even when a module declares the very same name.
+
+// Build a core with one module shipping two skills, and an instance with the module ON.
+function withdrawFixture() {
+  const core = mkdtempSync(join(tmpdir(), 'wd-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'wd-inst-'));
+  const modDir = join(core, 'modules', 'foo');
+  mkdirSync(join(modDir, 'skills', 'alpha'), { recursive: true });
+  mkdirSync(join(modDir, 'skills', 'beta'), { recursive: true });
+  mkdirSync(join(core, '.claude', 'skills'), { recursive: true });
+  writeFileSync(join(modDir, 'module.json'), JSON.stringify({ key: 'foo', default: true, contributes: { skills: ['alpha', 'beta'] } }));
+  writeFileSync(join(modDir, 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\n---\nbody\n');
+  writeFileSync(join(modDir, 'skills', 'beta', 'SKILL.md'), '---\nname: beta\n---\nbody\n');
+  return { core, inst, modDir };
+}
+const disable = (inst, key) => {
+  mkdirSync(join(inst, 'config'), { recursive: true });
+  writeFileSync(join(inst, 'config', 'modules.json'), JSON.stringify({ modules: { [key]: false } }));
+};
+
+t('materializeClaude: a module disabled on an EXISTING instance has its skills WITHDRAWN, not left to linger', () => {
+  const { core, inst } = withdrawFixture();
+  // upgrade 1 — module on: both land, and provenance is recorded
+  const first = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.equal(first.moduleSkills, 2);
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md')));
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'beta', 'SKILL.md')));
+  assert.deepEqual(first.withdrawnSkills, [], 'nothing to withdraw on the way in');
+  const mani = m.readInstanceSkillsManifest(join(inst, '.claude', 'skills'));
+  assert.deepEqual(Object.keys(mani.skills).sort(), ['alpha', 'beta'], 'the run records what it landed');
+
+  // upgrade 2 — module off: THIS is the bug. Both dirs must go.
+  disable(inst, 'foo');
+  const second = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(second.withdrawnSkills, ['alpha', 'beta']);
+  assert.ok(!existsSync(join(inst, '.claude', 'skills', 'alpha')), 'alpha withdrawn');
+  assert.ok(!existsSync(join(inst, '.claude', 'skills', 'beta')), 'beta withdrawn');
+  assert.deepEqual(Object.keys(m.readInstanceSkillsManifest(join(inst, '.claude', 'skills')).skills), [], 'provenance now records nothing landed');
+
+  // upgrade 3 — idempotent: nothing left to withdraw, no throw on the absent dirs
+  const third = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(third.withdrawnSkills, []);
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('materializeClaude: a skill the module STOPPED declaring is withdrawn too', () => {
+  const { core, inst, modDir } = withdrawFixture();
+  m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  // the module keeps only alpha
+  writeFileSync(join(modDir, 'module.json'), JSON.stringify({ key: 'foo', default: true, contributes: { skills: ['alpha'] } }));
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(res.withdrawnSkills, ['beta']);
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'alpha')), 'a still-declared skill stays');
+  assert.ok(!existsSync(join(inst, '.claude', 'skills', 'beta')));
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('materializeClaude: a HAND-WRITTEN skill is never withdrawn, even when a disabled module declares its name', () => {
+  const { core, inst } = withdrawFixture();
+  // The owner wrote .claude/skills/alpha themselves; no materialize ever landed it,
+  // so no manifest names it. Disabling foo must not touch it.
+  mkdirSync(join(inst, '.claude', 'skills', 'alpha'), { recursive: true });
+  writeFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'MINE — hand written\n');
+  disable(inst, 'foo');
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(res.withdrawnSkills, [], 'no provenance for it, so it is not ours to delete');
+  assert.equal(readFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8'), 'MINE — hand written\n', 'the owner\'s file is untouched');
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('materializeClaude: --dry-run reports the withdrawal without performing it; adopt mode declines to withdraw', () => {
+  const { core, inst } = withdrawFixture();
+  m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  disable(inst, 'foo');
+
+  const dry = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: true });
+  assert.deepEqual(dry.withdrawnSkills, ['alpha', 'beta'], 'reports what it would withdraw');
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'alpha')), 'a dry run deletes nothing');
+
+  const adopt = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false, overwrite: false });
+  assert.deepEqual(adopt.withdrawnSkills, [], 'adopt never clobbers what the owner has');
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'alpha')));
+  assert.ok(adopt.notes.some((n) => /adopt mode does not withdraw/.test(n)), 'and says so');
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
 // ---- module-owned skills (task 1003321 / ADR 0198) ---------------------------
 // A module ships a skill from modules/<key>/skills/<name>/ (its own) or
 // modules/<key>/skills/vendor/<name>/ (third-party + PROVENANCE.md); only a DECLARED
@@ -473,6 +565,9 @@ t('--module-skills-only: an instance materialised FROM a core that carries mater
   assert.ok(res.moduleSkills >= 2, 'alpha landed through step 1b');
   assert.match(readFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8'), /bongos ship 1/, 'transformed on the way into the instance');
   for (const f of [m.MODULE_SKILLS_MANIFEST, '.gitignore']) assert.ok(!existsSync(join(inst, '.claude', 'skills', f)), `${f} is not shipped to an instance`);
+  // The instance writes its OWN provenance record under a different name (task 1003632)
+  // — it is not the core's dotfile leaking across the boundary the line above guards.
+  assert.ok(existsSync(join(inst, '.claude', 'skills', m.INSTANCE_SKILLS_MANIFEST)), 'the instance records what it landed, under its own filename');
   assert.ok(existsSync(join(inst, '.claude', 'skills', 'core-one', 'SKILL.md')) && existsSync(join(inst, '.claude', 'skills', 'shared', 'SKILL.md')), 'the core skills still land');
   rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true });
 });

package/tests/government_board_summons.mjs

@@ -200,6 +200,9 @@ test('pending votes are action_needed and deep-link the oldest sitting', () => {
   assert.equal(n.id, 'board_votes');
   assert.equal(n.state, 'action_needed');
   assert.equal(n.action.href, '/board-room?item=1');
+  // task 1003737: the number, machine-readable. The message has always carried it
+  // in prose, which a sentence can render and the nav badge cannot.
+  assert.equal(n.count, 9, 'the need states its count for a badge to read');
   // The item is a query param, because `/board-room` reads `?item=` and a
   // FRAGMENT would never reach the server (ADR 0266). The old
   // `/government…#board-room` form survives only as government.js's
@@ -207,6 +210,22 @@ test('pending votes are action_needed and deep-link the oldest sitting', () => {
   assert.ok(!n.action.href.includes('#board-room'), 'never emits the retired hash form');
 });
 
+test('the founding grace keeps the count but drops the demand', () => {
+  // The badge keys on state, not on the number, precisely because of this: the
+  // grace rewrites the row to 'covered' and the count rides through the spread.
+  // A renderer keyed on `count` alone would shout through a new instance's
+  // first days, which is the one thing the grace exists to prevent.
+  const out = needs.computeNeeds({
+    rank: 'archon', ownKeySet: true,
+    pendingBoardVotes: { count: 5, first_item_id: '1' },
+    isFoundingOwner: true, founderCreatedAt: new Date().toISOString(),
+  });
+  const row = out.items.find((i) => i.id === 'board_votes');
+  assert.equal(row.count, 5, 'the count survives');
+  assert.equal(row.state, 'covered', 'but it is no longer a demand');
+  assert.equal(out.has_action_needed, false);
+});
+
 test('a count with no item id still links the room', () => {
   const n = needs.boardVotesNeed({ pendingBoardVotes: { count: 2 } });
   assert.equal(n.action.href, '/board-room');