@bongos/core 1.21.87 → 1.21.88

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.87",
-  "core_contract": "1.21.87",
-  "source_commit": "3a000da66e4b7ed910b59eb0e1843e81a7e3f7fd",
+  "core_version": "1.21.88",
+  "core_contract": "1.21.88",
+  "source_commit": "4bfba51c57c0f602ad9c166e149b64f3440e88b9",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T05:06:35.756Z",
+  "built_at": "2026-10-09T05:24:37.080Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 590,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3000,
+    "functional_verbatim": 3001,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3619,
-  "tree_sha256": "94cb33a270055b9c3e008a1a26ad2e66038572aae76148fccb2f9b3bf2bbecf9",
+  "file_count": 3620,
+  "tree_sha256": "9c2cd52bac9f184d7097d5da786d1a69fe8403ddf698d36b914c4b39da21eeb7",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2862,7 +2862,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "39126044930a9015689ba736100232d99d1d13d43d723ec95a15dbe505c4390d"
+      "sha256": "ada2da687d2c0d7dbb14e027ab755e6fbd771ff026e48d62aeda44b5d14fa923"
     },
     {
       "path": "docs/modules-contract.md",
@@ -10097,12 +10097,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6953a80922eac656bc533d17e921f49228e939cacb64da8e56d1a90fa5f358db"
+      "sha256": "cfe8ee2b06d54070a847c417dc95352c7817ef56bf8a49e4ffe0d0bce8615c26"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "be88b7b575574dc07cbf071c639c419a4365cd89e7ed0b7bba058de98982b443"
+      "sha256": "50698c5b17011dbaf2098ae3bdcef8540a946ab36e2d5555c824666f778287ae"
     },
     {
       "path": "public-docs/index.html",
@@ -10122,7 +10122,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "ba7ae503bc8f34ef8244b2fb989462283e4128b6ea03ac066d050acfb35edbc5"
+      "sha256": "7d25584e81384714b841f849588e0ed95a630ed13d2adc5b106d9bc2940b5728"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10427,7 +10427,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "3dbededc4c7c82f844bc772ef10a9aefdf73bc3b1357db70177d164c7e2be87e"
+      "sha256": "1d141943f8367b8814e5a455c0c5d68a3915ac802df6cae9c3550f0628dbc384"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -11304,6 +11304,11 @@
       "mode": "0000644",
       "sha256": "084fa5c4da1e755fa0edde5ec770e5151a9f66a247bca222bc7a2366ccf61748"
     },
+    {
+      "path": "scripts/gds/retired-core-skills.json",
+      "mode": "0000644",
+      "sha256": "74dda013c4482bcd6a42bcfb36d0affa435044e7981a3c98c9e861f99ba3ade2"
+    },
     {
       "path": "scripts/gds/review-sheet.js",
       "mode": "0000644",
@@ -12377,7 +12382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "3ba47cbdc5c1c0dc86af2cf1302a6ffc3c9966a7646f88bd2a004f5dd67b0ded"
+      "sha256": "5408eebecc30a0da2527855d9aa1aff7b66658f32b504f4e71517938ad7dcb83"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13162,7 +13167,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "bf30601c49fb27cc0b230e6f48e4ed75af68c9cb6b8e8b5f7e13b38eb0241eec"
+      "sha256": "da076e811015020cb8a7cc730dc8f403d1b9e29749871078998ebca64113b0e5"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",

package/docs/module-api-changelog.md

@@ -3006,5 +3006,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.85 with no explicit bump. run 37885516955. (task 1002620)
   1.21.87 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.86 with no explicit bump. run 37886940909. (task 1002620)
+  1.21.88 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.87 with no explicit bump. run 37888371878. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.87",
+  "version": "1.21.88",
   "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/release-notes.json

@@ -9352,5 +9352,11 @@
       "id": "1002852",
       "text": "The task list a builder sees at the start of a session now opens with the goals they have joined and how much work in each is ready, and groups the tasks under their goals, with the builder's own goals first and anything witho"
     }
+  ],
+  "1.21.88": [
+    {
+      "id": "1004482",
+      "text": "Upgrading a project now clears out commands Bongos used to ship but has since retired (the old dev-box commands, the old /dev /ideate /paint playbooks, the pixel-art commands), so the Commands page and Claude's menu only list"
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -30,6 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
 const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
@@ -277,6 +278,59 @@ function moduleSkillSources(opts) {
   return out;
 }
 
+// ---- retired core skills: the tombstone list (task 1004482) -----------------
+// A skill the core USED to ship from its own .claude/skills/ and no longer does (the dev-box
+// verbs, the old /dev /ideate /paint role playbooks, the pixel-art skills that moved into a
+// default-off module). Every instance materialized before task 1004482 received them as core
+// skills, and the provenance manifest then recorded only module-declared names — so step 1c
+// could never prove it had put them there and they stayed in .claude/skills/ for the harness to
+// load and the hall's Commands page to list, forever.
+//
+// From task 1004482 on the manifest records EVERY skill a materialize lands, so a skill the core
+// drops later is withdrawn by step 1c's ordinary rule. This list closes the historical gap only,
+// and is therefore a closed set: it should not need a new entry.
+//
+// "Never touch a skill the instance authored" is held by a fingerprint, not by the name: each
+// entry lists sha256 digests (first 16 hex) of every description the core ever shipped under that
+// name, as written and as bongosify() rewrote it. A dir whose SKILL.md description matches none of
+// them is not ours and is left in place with a note — an owner who wrote their own /dev keeps it.
+const RETIRED_CORE_SKILLS_FILE = path.join(__dirname, 'retired-core-skills.json');
+
+// The `description:` value of a SKILL.md's frontmatter, whitespace-collapsed — a plain scalar,
+// a quoted one, or a block scalar (`>` / `|`) with its indented continuation lines. null when
+// the file has no frontmatter or no description. PURE + exported.
+function skillDescription(text) {
+  const m = String(text == null ? '' : text).replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!m) return null;
+  const lines = m[1].split('\n');
+  const i = lines.findIndex((l) => /^description:/.test(l));
+  if (i < 0) return null;
+  const parts = [lines[i].replace(/^description:\s*/, '')];
+  if (/^[>|][+-]?$/.test(parts[0])) parts[0] = '';
+  for (let j = i + 1; j < lines.length && /^\s+\S/.test(lines[j]); j += 1) parts.push(lines[j]);
+  const value = parts.join(' ').replace(/\s+/g, ' ').trim().replace(/^(["'])([\s\S]*)\1$/, '$2').trim();
+  return value || null;
+}
+
+function descriptionDigest(desc) {
+  return crypto.createHash('sha256').update(String(desc)).digest('hex').slice(0, 16);
+}
+
+// Does this instance skill dir carry a description the core shipped under `name`? Reads the
+// tombstone's digests; an unreadable SKILL.md or a missing description answers "no" (keep it).
+function isRetiredCoreCopy(dir, digests) {
+  if (!Array.isArray(digests) || !digests.length) return false;
+  let text;
+  try { text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8'); } catch { return false; }
+  const desc = skillDescription(text);
+  return desc != null && digests.includes(descriptionDigest(desc));
+}
+
+function readRetiredCoreSkills(file = RETIRED_CORE_SKILLS_FILE) {
+  const j = readJsonSafe(file);
+  return j && j.skills && typeof j.skills === 'object' ? j.skills : {};
+}
+
 // ---- I/O: copy a tree, transforming text files through bongosify ----------
 
 const TEXT_EXT = new Set(['.md', '.txt', '.sh']); // command-bearing text we rewrite (skills are SKILL.md)
@@ -759,10 +813,38 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   // exists to fix. Deliberately asked of the CORE source tree rather than the roster, so a
   // name no enabled module declares any more is still recognised as legitimately sourced.
   const coreShipsNow = (name) => fs.existsSync(path.join(skillsSrc, name)) && !skipSkills.has(name);
+  // Every CORE skill step 1 landed is recorded too (task 1004482), so a skill the core stops
+  // shipping in a later release is withdrawn by the rule below instead of lingering forever.
+  // When the core's .claude/skills/ could not be read at all, nothing was landed from it and
+  // nothing may be withdrawn on that account: the previous core entries are carried forward.
+  const coreTreeRead = skillsRes.present;
+  if (coreTreeRead) {
+    for (const name of fs.readdirSync(skillsSrc)) {
+      if (landedNow[name] || !SKILL_NAME_RE.test(name) || skillSkip(name)) continue;
+      if (!fs.statSync(path.join(skillsSrc, name)).isDirectory()) continue;
+      if (!dryRun && !fs.existsSync(path.join(skillsDest, name))) continue;
+      landedNow[name] = { source: `.claude/skills/${name}`, coreShipped: true };
+    }
+  } else {
+    for (const [name, rec] of Object.entries(landedPreviously)) if (rec && rec.coreShipped && !rec.module && !landedNow[name]) landedNow[name] = rec;
+  }
   const withdrawable = Object.keys(landedPreviously).filter((n) => SKILL_NAME_RE.test(n) && !landedNow[n] && !coreShipsNow(n));
+  // The historical half (task 1004482): a skill the core retired BEFORE the manifest recorded
+  // core skills is withdrawn when its dir still carries a description the core shipped under
+  // that name. Anything else under a retired name is the instance's own and stays.
+  const retired = readRetiredCoreSkills();
+  const keptAsOwn = [];
+  for (const [name, entry] of Object.entries(retired)) {
+    if (!SKILL_NAME_RE.test(name) || landedNow[name] || coreShipsNow(name) || withdrawable.includes(name)) continue;
+    const dir = path.join(skillsDest, name);
+    if (!fs.existsSync(dir)) continue;
+    if (isRetiredCoreCopy(dir, entry && entry.descriptionDigests)) withdrawable.push(name);
+    else keptAsOwn.push(name);
+  }
+  if (keptAsOwn.length) summary.notes.push(`${keptAsOwn.length} skill dir(s) share a name the core once shipped but are not the core's copy (their description is not one it shipped), so they were left in place as the instance's own: ${keptAsOwn.sort().join(', ')}.`);
   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(', ')}.`);
+    if (withdrawable.length) summary.notes.push(`${withdrawable.length} skill(s) the core no longer lands here 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);
@@ -774,7 +856,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       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 (summary.withdrawnSkills.length) log(`  ${dryRun ? '[dry-run] would withdraw' : '✓ withdrew'} ${summary.withdrawnSkills.length} stale skill dir(s) the core no longer ships here (retired, or its module is off): ${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.');
@@ -788,7 +870,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   // the pre-flight halts on and the real run then rewrites anyway.
   if (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]])) };
+    const manifest = { _doc: 'GENERATED by scripts/gds/claude-materialize.js (tasks 1003632, 1004482): every skill a materialize landed in this instance, core and module alike. It is the provenance record that lets a later run WITHDRAW a skill the core stopped shipping or whose module has since been disabled — a name absent from here is never deleted on that account, so a hand-written skill is safe. Commit it; do not hand-edit.', skills: Object.fromEntries(names.map((n) => [n, landedNow[n]])) };
     if (!dryRun) {
       fs.mkdirSync(skillsDest, { recursive: true });
       fs.writeFileSync(path.join(skillsDest, INSTANCE_SKILLS_MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
@@ -1112,4 +1194,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, 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 };
+module.exports = { skillDescription, descriptionDigest, isRetiredCoreCopy, readRetiredCoreSkills, RETIRED_CORE_SKILLS_FILE, scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, 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/scripts/gds/retired-core-skills.json

@@ -0,0 +1,101 @@
+{
+  "_doc": "Tombstone list (task 1004482): skills the core once shipped from its own .claude/skills/ and no longer does, from before materialize recorded core skills in an instance's .instance-skills.json. Each lists sha256 digests (first 16 hex) of every description the core ever shipped under that name, as written and as bongosify() rewrote it; claude-materialize.js withdraws an instance dir under one of these names ONLY when its SKILL.md description matches, so a skill the instance wrote itself is never touched. A closed historical set: a skill the core drops from now on is withdrawn through the manifest, with no entry here.",
+  "skills": {
+    "builder-box": {
+      "descriptionDigests": [
+        "14913228d8aefa2a",
+        "3a8458946af072fb",
+        "7695811a3bb4fa8a",
+        "d77e96d673b77f5b"
+      ]
+    },
+    "builder-connect": {
+      "descriptionDigests": [
+        "27137471966e6a98",
+        "2bc0f02001bf7311",
+        "5bfb4795ceb3e77a",
+        "a9442b55f9588a06",
+        "d661c46a8076a1ea"
+      ]
+    },
+    "builder-sync": {
+      "descriptionDigests": [
+        "3fad042c07a1d8e7",
+        "50c1a8505aead99b"
+      ]
+    },
+    "close-box": {
+      "descriptionDigests": [
+        "03d839f2e5909448",
+        "4f30758956f46d88",
+        "66aef8299b4c39af",
+        "b3f6743fdb4a07fe",
+        "d119bb63ffaba1e8"
+      ]
+    },
+    "dev": {
+      "descriptionDigests": [
+        "7836b393796e9ee0",
+        "8cf08a65be57d5f1"
+      ]
+    },
+    "feedback": {
+      "descriptionDigests": [
+        "211c55ddd59ef937",
+        "2f58da0a75816b09",
+        "3b48dc4cf9e43692",
+        "7bca081fc8092577",
+        "85bb6d1200234a28",
+        "a309ad6d9ea56a5f",
+        "ab21803079a7530c",
+        "e090c86c838c0f97"
+      ]
+    },
+    "ideate": {
+      "descriptionDigests": [
+        "466396868c0d2d37"
+      ]
+    },
+    "otb-character-review": {
+      "descriptionDigests": [
+        "518356210d594d2e",
+        "af216311f26edffd",
+        "eb529abb98348cd1"
+      ]
+    },
+    "otb-design-review": {
+      "descriptionDigests": [
+        "1b1375bc9ea12faa",
+        "9f97a32f15c805bc"
+      ]
+    },
+    "otb-feedback-capture": {
+      "descriptionDigests": [
+        "6ba86ab812dd9495",
+        "c915f0de7ab1e8fd"
+      ]
+    },
+    "otb-figma-sync": {
+      "descriptionDigests": [
+        "281987db3241a779",
+        "61132c40a0388319"
+      ]
+    },
+    "otb-tile-generate": {
+      "descriptionDigests": [
+        "57981088137a89ee",
+        "b1db07959665a454"
+      ]
+    },
+    "paint": {
+      "descriptionDigests": [
+        "944ae7795b04d726"
+      ]
+    },
+    "tweak": {
+      "descriptionDigests": [
+        "a8d84a40f2e3d8a2"
+      ]
+    }
+  }
+}

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.87'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.88'; // 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('discord'); log.info('mounted');

package/tests/claude_materialize.mjs

@@ -19,6 +19,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
 import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -420,6 +421,87 @@ t('materializeClaude: --dry-run reports the withdrawal without performing it; ad
   for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
 });
 
+// ---- withdrawing skills the CORE stopped shipping (task 1004482) ----------------
+// The bug: the manifest recorded only module-declared skills, so a skill the core shipped
+// from its own .claude/skills/ and later dropped (the dev-box verbs, /dev /ideate /paint,
+// the pixel-art skills) stayed in every upgraded instance, loaded by the harness and listed
+// on the hall's Commands page. Two halves: the manifest now records core skills (future
+// retirements), and a tombstone list fingerprinted by description covers the past ones.
+
+// The /ideate description the core shipped until 2026-09-09, verbatim — a block scalar.
+const IDEATE_SHIPPED = '---\nname: ideate\ndescription: >-\n  The ideation session — the operating playbook for ideator-discipline work. Triggers when the user says "/ideate", "let\'s ideate", "I want to brainstorm", "help me think through an idea", "start an ideation session", or when a claimed task\'s discipline routes here (claim.js prints a directive to invoke /ideate for ideator tasks). Inverts the usual dynamic: the human ideator drives, Claude is the sounding board. Open to any rank for FILING ideas (Xenos+ can capture; only Metic+ can triage).\n---\nbody\n';
+
+function coreSkillFixture() {
+  const core = mkdtempSync(join(tmpdir(), 'rt-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'rt-inst-'));
+  for (const n of ['keep', 'gamma']) {
+    mkdirSync(join(core, '.claude', 'skills', n), { recursive: true });
+    writeFileSync(join(core, '.claude', 'skills', n, 'SKILL.md'), `---\nname: ${n}\ndescription: ${n} skill\n---\nbody\n`);
+  }
+  return { core, inst };
+}
+
+t('skillDescription: reads plain, quoted and block-scalar descriptions; null without one', () => {
+  assert.equal(m.skillDescription('---\nname: a\ndescription: one line\n---\n'), 'one line');
+  assert.equal(m.skillDescription('---\r\nname: a\r\ndescription: "quoted"\r\n---\r\n'), 'quoted');
+  assert.equal(m.skillDescription('---\ndescription: >-\n  folded\n  over two\nname: a\n---\n'), 'folded over two');
+  assert.equal(m.skillDescription('---\nname: a\n---\n'), null);
+  assert.equal(m.skillDescription('no frontmatter'), null);
+});
+
+t('materializeClaude: a core skill the core STOPPED shipping is withdrawn on the next upgrade (task 1004482)', () => {
+  const { core, inst } = coreSkillFixture();
+  m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  const mani = m.readInstanceSkillsManifest(join(inst, '.claude', 'skills'));
+  assert.ok(mani.skills.gamma && mani.skills.gamma.coreShipped, 'core skills are recorded as landed now');
+  rmSync(join(core, '.claude', 'skills', 'gamma'), { recursive: true, force: true });
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(res.withdrawnSkills, ['gamma']);
+  assert.ok(!existsSync(join(inst, '.claude', 'skills', 'gamma')), 'the retired core skill is gone');
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'keep')), 'a skill the core still ships stays');
+  assert.ok(res.writtenPaths.includes('.claude/skills/gamma/SKILL.md'), 'the deletion is reported so the pin commit carries it');
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('materializeClaude: a core with no readable .claude/skills/ withdraws no core skill (task 1004482)', () => {
+  const { core, inst } = coreSkillFixture();
+  m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  rmSync(join(core, '.claude', 'skills'), { recursive: true, force: true });
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(res.withdrawnSkills, [], 'nothing landed from the core, so nothing is withdrawn on that account');
+  assert.ok(existsSync(join(inst, '.claude', 'skills', 'gamma')));
+  assert.ok(m.readInstanceSkillsManifest(join(inst, '.claude', 'skills')).skills.gamma, 'and the provenance is carried forward');
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('materializeClaude: a RETIRED core skill with the description the core shipped is withdrawn; one the instance wrote under that name is kept (task 1004482)', () => {
+  const { core, inst } = coreSkillFixture();
+  const skills = join(inst, '.claude', 'skills');
+  // an instance materialized before core skills were recorded: no manifest names either dir
+  mkdirSync(join(skills, 'ideate'), { recursive: true });
+  writeFileSync(join(skills, 'ideate', 'SKILL.md'), IDEATE_SHIPPED);
+  mkdirSync(join(skills, 'dev'), { recursive: true });
+  writeFileSync(join(skills, 'dev', 'SKILL.md'), '---\nname: dev\ndescription: our own dev loop\n---\nMINE\n');
+  const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
+  assert.deepEqual(res.withdrawnSkills, ['ideate'], 'the core\'s old /ideate goes');
+  assert.ok(!existsSync(join(skills, 'ideate')));
+  assert.equal(readFileSync(join(skills, 'dev', 'SKILL.md'), 'utf8'), '---\nname: dev\ndescription: our own dev loop\n---\nMINE\n', 'the owner\'s /dev is untouched');
+  assert.ok(res.notes.some((n) => /left in place as the instance's own: dev/.test(n)), 'and the run says why it kept it');
+  for (const d of [core, inst]) rmSync(d, { recursive: true, force: true });
+});
+
+t('retired-core-skills.json: names the dev-box verbs, the old role playbooks and the pixel-art skills, none of which the core ships now', () => {
+  const retired = m.readRetiredCoreSkills();
+  for (const n of ['builder-box', 'builder-connect', 'builder-sync', 'close-box', 'dev', 'ideate', 'paint', 'otb-tile-generate', 'otb-design-review']) {
+    assert.ok(retired[n] && retired[n].descriptionDigests.length, `${n} is tombstoned with at least one digest`);
+  }
+  // A tombstone on a name the core still ships would be inert (step 1 lands it), but it would
+  // also mean the list was built wrong — tracked files only, since a checkout holds untracked
+  // module-skill copies (ADR 0224) under the same directory.
+  const tracked = execFileSync('git', ['-C', ROOT, 'ls-files', '.claude/skills'], { encoding: 'utf8' });
+  for (const n of Object.keys(retired)) assert.ok(!tracked.includes(`.claude/skills/${n}/`), `${n} is not a skill the core ships from .claude/skills/`);
+});
+
 // ---- 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