ma-agents 3.18.0-beta.1 → 3.18.0-beta.2

package/README.md

@@ -277,6 +277,21 @@ Both messages end by stating that nothing was read or written on your behalf.
 These are stated here, in the shipped documentation, rather than only in the
 repository's changelog — which is **not** part of the npm package.
 
+- **Versions 3.7.0 through 3.17.1 could silently delete hand-authored skills.**
+  When a tool's skills directory moved between versions, the installer removed
+  the old directory recursively once the new one had content, destroying any
+  skill you had written there yourself and reporting it as a successful
+  cleanup. This affected `.github/copilot/skills`, `.github/skills`,
+  `.roo/skills` and `.kilocode/skills`. **It is fixed in this version** — the
+  sweep now removes only what ma-agents installed and preserves the directory
+  if anything else remains — but deletions already made are not recoverable
+  from ma-agents: no backup was written and nothing but the directory name was
+  recorded. Check your version control if you kept such skills.
+- **A file placed inside a skill directory ma-agents installed is still removed
+  with it.** The sweep's unit is the skill directory, not the file. If you have
+  edited a shipped skill in place, that edit is lost when the directory is
+  swept. Keep your own skills in their own directories, which are preserved.
+
 - **Every claim in this release about behaviour with a Confluence MCP *present*
   is mock-verified, not live.** No authorised Confluence MCP was available to
   the implementation or to any review, so the MCP-present branches were

package/bin/cli.js

@@ -157,9 +157,13 @@ ${chalk.bold('Install options:')}
   ${chalk.cyan('--yes')}             Skip all prompts, use defaults (for CI/CD)
   ${chalk.cyan('--agent <name>')}    Target a specific agent (skip agent selection)
   ${chalk.cyan('--bmad-modules [csv]')} Control BMAD module selection.
-                       Bare:    open a multiselect prompt
+                       Bare:    open a multiselect prompt (offers every
+                                bundled module, incl. gds and wds)
                        With CSV: install exactly those (e.g. tea,bmb)
-                       Omitted: install every non-retired module (default)
+                       Omitted: install bmm,tea,bmb,cis (default). The
+                                design-studio modules gds and wds are
+                                bundled but not installed by default —
+                                select them to install them.
                        'bmm' is always force-included.
   ${chalk.cyan('--bmad-custom-source <ref>')} Enumerate extensions from ONE custom
                        marketplace repo (local path or Git URL containing
@@ -347,7 +351,7 @@ function parseFlags(args) {
   // --bmad-modules — controls BMad module selection. Optional-value flag:
   //   bare         → ask the user via multiselect prompt
   //   with CSV     → install exactly those (bmm force-prepended, unknowns rejected)
-  //   not present  → install all non-retired modules (no prompt)
+  //   not present  → install FR123's default set, bmm+tea+bmb+cis (no prompt)
   // Force-prepending of `bmm` and validation of unknown ids is handled
   // centrally by lib/bmad.resolveBmadModules.
   let bmadModulesFlag = '';
@@ -3671,18 +3675,30 @@ async function collectSprintManagementLocation(concern, existingRecord) {
  *
  * Three branches:
  *   1. `--bmad-modules <csv>` → install exactly those (bmm force-prepended,
- *      unknowns rejected with a clear error)
- *   2. `--bmad-modules` bare  → multiselect prompt; bmm is required and
- *      pre-checked, others default-checked so a no-op confirmation matches
- *      the no-flag default
- *   3. (no flag)              → install every non-retired module from the
- *      cache manifest, no prompt — restores the originally-intended
- *      behavior that the hardcoded ['bmm'] literal had been suppressing
+ *      unknowns rejected with a clear error). An explicit selection always
+ *      wins, including one that names `gds` or `wds`.
+ *   2. `--bmad-modules` bare  → multiselect prompt; EVERY bundled module is
+ *      offered, bmm is required and pre-checked, and the remaining initial
+ *      check state is the FR123 default set — so a no-op confirmation lands
+ *      on exactly the same modules as branch 3.
+ *   3. (no flag)              → no prompt. In order: a persisted selection
+ *      from a prior run (bug 27.13), else the modules already present under
+ *      `_bmad/`, else `bmad.getDefaultBmadModules()` — FR123's amended
+ *      default set, bmm + tea + bmb + cis.
+ *
+ * WHY BRANCH 3 IS NO LONGER "EVERY NON-RETIRED MODULE" (FR123, amended
+ * 2026-08-02): that default is what put a five-folder `design-artifacts/`
+ * tree at the root of a Copilot+Cline project that had never asked for UX
+ * tooling — `wds` installed unasked and materialised its `directories:`
+ * block. `gds` and `wds` are still BUNDLED and still installable offline;
+ * they are simply no longer installed without being asked for. Bundling and
+ * installing are different decisions made at different times, and only the
+ * second one moved.
  *
  * `bmm` is force-included in every path because the BMad core agents
  * (analyst, PM, dev, architect, ...) live there and downstream skills
- * break without them. Retired modules (currently only `wds`) are filtered
- * out unconditionally.
+ * break without them. Retired modules (none at v6.10.0) are filtered out
+ * unconditionally.
  */
 async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt, projectRoot } = {}) {
   const installable = bmad.getInstallableBmadModules().filter(m => !m.retired);
@@ -3712,15 +3728,22 @@ async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt, projectRo
 
   // Branch 2: bare --bmad-modules → multiselect prompt.
   if (bmadModulesPrompt) {
+    // FR123: every bundled module is OFFERED — this prompt is the documented
+    // route by which `gds`/`wds` remain reachable offline — but the initial
+    // check state is the default INSTALL set, so pressing Enter without
+    // touching anything lands on the same modules as the no-flag branch below.
+    // Checking them all here would silently reintroduce the very "installs
+    // everything" default this change removes.
+    const defaultIds = new Set(bmad.getDefaultBmadModules(installable));
     const choices = installable.map(m => {
       const isCore = m.id === 'bmm';
       const requiredTag = isCore ? chalk.yellow(' (required)') : '';
       return {
         title: chalk.white(m.id) + requiredTag + chalk.gray(` — ${m.description}`),
         value: m.id,
-        // Default-check everything so hitting Enter matches the no-flag
-        // "install all" default. Users uncheck what they want to skip.
-        selected: true,
+        // bmm is force-included downstream regardless; pre-checking it keeps
+        // the prompt honest about that.
+        selected: isCore || defaultIds.has(m.id),
       };
     });
 
@@ -3740,22 +3763,52 @@ async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt, projectRo
     return persist(bmad.resolveBmadModules({ requested: chosenModules, available: installable }));
   }
 
-  // Branch 3: no flag → use the persisted selection from a prior run if present
-  // (bug 27.13 — a previous deselection must survive); otherwise fall back to
-  // the original "install every available module" default. The persisted set is
-  // intersected with the currently-installable set so a since-retired module
-  // does not resurface, and bmm is force-included via resolveBmadModules.
+  // Branch 3: no flag. Three fallbacks, most-specific first.
+  const availableIds = new Set(installable.map(m => m.id));
+
+  // 3a — a persisted selection from a prior run (bug 27.13): a previous
+  // deselection must survive. Intersected with the currently-installable set so
+  // a since-retired module does not resurface; bmm is force-included via
+  // resolveBmadModules.
   const persisted = getBmadModules(root);
   if (persisted && persisted.length > 0) {
-    const availableIds = new Set(installable.map(m => m.id));
     const stillInstallable = persisted.filter(id => availableIds.has(id));
     try {
       return persist(bmad.resolveBmadModules({ requested: stillInstallable, available: installable }));
     } catch {
-      // If the persisted set somehow fails validation, fall through to default.
+      // If the persisted set somehow fails validation, fall through.
     }
   }
-  return persist(installable.map(m => m.id));
+
+  // 3b — NON-DESTRUCTIVE MIGRATION. Narrowing the default (FR123, amended
+  // 2026-08-02) is behaviour-visible to projects that already installed under
+  // the old every-module default, and an update run passes this same resolved
+  // list to `bmad.updateBmad`. A project that already has `wds` under `_bmad/`
+  // must not have it dropped out of its own module list just because the
+  // default moved — narrowing applies to NEW installs, not to existing ones.
+  //
+  // 3a covers projects installed since bug 27.13 landed persistence; this
+  // covers the ones installed before it, where `.ma-agents.json` carries no
+  // `bmadModules` field at all and disk is the only record of what was chosen.
+  // A fresh project has no `_bmad/`, so this is inert for new installs — which
+  // is exactly the "existing installs unchanged, only NEW installs get the
+  // narrower default" posture NFR49 / Story 30.4 established for Demerzel.
+  // Persisting the result also migrates the project onto 27.13's durable
+  // record, so this disk probe is needed at most once per project.
+  const alreadyInstalled = bmad.getInstalledBmadModules(root).filter(id => availableIds.has(id));
+  if (alreadyInstalled.length > 0) {
+    try {
+      return persist(bmad.resolveBmadModules({ requested: alreadyInstalled, available: installable }));
+    } catch {
+      // Fall through to the default set.
+    }
+  }
+
+  // 3c — a genuinely fresh install: FR123's amended default set.
+  return persist(bmad.resolveBmadModules({
+    requested: bmad.getDefaultBmadModules(installable),
+    available: installable,
+  }));
 }
 
 // --- Custom marketplace source (Story 30.6a) ---
@@ -4408,10 +4461,10 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
     // stage the plugin and invoke the installer in one pass.
     // v6.6.0: --tools none is rejected for fresh installs; skip BMAD entirely when no IDE tools selected.
     if (bmadTools.length > 0) {
-      // Resolve module set once per BMAD invocation. Default is "install
-      // every non-retired module"; users opt into a specific subset with
-      // --bmad-modules <csv> or open a multiselect prompt with --bmad-modules
-      // (bare).
+      // Resolve module set once per BMAD invocation. Default (FR123, amended
+      // 2026-08-02) is bmm+tea+bmb+cis; the bundled design-studio modules gds
+      // and wds install only when asked for, via --bmad-modules <csv> or the
+      // multiselect that bare --bmad-modules opens.
       const bmadModules = await selectBmadModules({
         bmadModulesFlag,
         bmadModulesPrompt,

package/docs/technical-notes/enforcement-hooks-research.md

@@ -294,11 +294,20 @@ All 11 BMAD agents have enforcement via `critical_actions` in `.customize.yaml`
 **Mechanism:**
 ```yaml
 critical_actions:
-  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml"
+  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/<agent-slug>/MANIFEST.yaml if it exists"
   2: "For each skill marked always_load: true, read the skill file completely"
   3: "Follow all skill directives during this session"
 ```
 
+> **Note (2026-09-12):** this snippet previously showed a bare
+> `{project-root}/_bmad/skills/MANIFEST.yaml`. That path is not what Story 8.3
+> specified — the manifest is per-agent-host, at
+> `{project-root}/_bmad/skills/<agent-slug>/MANIFEST.yaml`, where `<agent-slug>`
+> matches the `skillsDir` in `lib/agents.js` (`sre`, `devops`, `cyber`, `sqa`).
+> The bare form leaked from here into `ma-agent-sqa`'s Critical Actions block and
+> survived there until it was corrected. Keep the slug segment in any copy of this
+> snippet.
+
 **Deployment:** Extension module at `_bmad/extensions/ma-agents-skills/` deployed during BMAD customization pipeline (Stage 3 in `bmad.js`).
 
 **Coverage:**

package/lib/agents.js

@@ -242,8 +242,27 @@ const agents = [
     version: '1.0.0',
     category: 'ide',
     description: 'Google Deepmind Antigravity Agent',
-    skillsDir: '.antigravity/skills',
-    getProjectPath: () => path.join(process.cwd(), '.antigravity', 'skills'),
+    // Bug `antigravity-path-divergence`: this used to read `.antigravity/skills`,
+    // a path ma-agents invented from its own per-tool naming convention. Upstream
+    // bmad-method maps the SAME tool to `.agent/skills`
+    // (node_modules/bmad-method/tools/installer/ide/platform-codes.yaml, platform
+    // `antigravity`, in a file whose header records the paths as "verified against
+    // each tool's primary docs"; its global counterpart `~/.gemini/antigravity/skills`
+    // shows the entry was researched rather than guessed). Because ma-agents
+    // delegates part of the install to that installer, a single run produced TWO
+    // trees — and `.agent/skills`, the one Antigravity actually reads, was named by
+    // neither this registry nor lib/bmad.js, so every ma-agents post-deploy patch
+    // (the on-prem phase prefix among them) silently skipped it. Measured in a real
+    // on-prem project: .claude/.agents/.cline each carried the prefix on 6 personas,
+    // .agent/skills on 0.
+    // Upstream is the authority on which directory a tool reads, so we align —
+    // exactly as copilot/roo-code/kilocode were aligned to `.agents/skills` when
+    // bmad-method 6.5.0 moved them (see the copilot entry above). This is a
+    // per-tool decision on per-tool evidence: the other three divergences in the
+    // table are recorded in PLATFORM_PATH_DIVERGENCES below, deliberately unchanged.
+    // Existing installs migrate via OBSOLETE_TOOL_SKILL_DIRS in lib/installer.js.
+    skillsDir: '.agent/skills',
+    getProjectPath: () => path.join(process.cwd(), '.agent', 'skills'),
     getGlobalPath: () => {
       const platform = os.platform();
       if (platform === 'win32') {
@@ -356,6 +375,64 @@ const agents = [
   // Add them here in a dedicated future story if/when demand appears.
 ];
 
+/**
+ * Declared, deliberate divergences between this registry's project `skillsDir`
+ * and bmad-method's `installer.target_dir` for the SAME tool
+ * (`node_modules/bmad-method/tools/installer/ide/platform-codes.yaml`).
+ * Keyed by bmad platform code (see `getBmadPlatformCode`).
+ *
+ * Why this exists (bug `antigravity-path-divergence`): the two tables had drifted
+ * apart for four tools and nothing compared them outside the five flagships, so a
+ * whole second skill tree appeared in real projects with no owner and no patcher.
+ * `test/routing-parity.test.js` (section 5) now enumerates EVERY tool in BOTH
+ * tables and fails on any divergence that is not declared here — and on any
+ * declaration whose recorded paths have gone stale, so an entry cannot rot into
+ * cover for a different divergence.
+ *
+ * Scope note — PROJECT paths only. `getGlobalPath()` follows a per-OS
+ * application-data convention that differs from upstream's `global_target_dir`
+ * for EVERY tool, claude-code included (`%APPDATA%/Claude/skills` vs
+ * `~/.claude/skills`). That is a whole-table convention difference, not a
+ * per-tool divergence, and is deliberately out of scope here.
+ *
+ * To add an entry you must record BOTH live paths and a real reason. To remove
+ * one, align the paths — the test fails on a declaration whose paths now agree.
+ */
+const PLATFORM_PATH_DIVERGENCES = Object.freeze({
+  gemini: Object.freeze({
+    maSkillsDir: '.gemini/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      "Upstream's `gemini` platform is the Gemini CLI, which reads the shared " +
+      '`.agents/skills` tree; this registry entry targets Google Gemini Code Assist ' +
+      '(the IDE extension — note its instruction file `.gemini/gemini.md`), a ' +
+      'different product sharing the same code. Contained: upstream writes ' +
+      '`.agents/skills`, which is already an IDE skillsDir in this registry, already ' +
+      'a seed in lib/bmad.js TOOL_SKILL_DIRS, and already reconciled by bug 27.16 — ' +
+      'so no tree goes unpatched. Realigning is a compatibility call for its own story.'
+  }),
+  cursor: Object.freeze({
+    maSkillsDir: '.cursor/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      'Cursor reads its own `.cursor/` workspace directory (this registry also stamps ' +
+      '`.cursor/cursor.md` there); upstream routes it to the shared `.agents/skills` ' +
+      'cross-tool tree instead. Contained for the same reason as `gemini`: upstream ' +
+      "'s target is already a known, patched and reconciled tree. Kept deliberately " +
+      'so this bug fix changes the write path of exactly one tool, on that tool’s evidence.'
+  }),
+  opencode: Object.freeze({
+    maSkillsDir: '.opencode/skills',
+    bmadTargetDir: '.agents/skills',
+    reason:
+      'OpenCode is wired here through `opencode.json::instructions[]` plus AGENTS.md ' +
+      '(Story 21.4) against its own `.opencode/` tree; upstream routes it to the shared ' +
+      '`.agents/skills`. Contained for the same reason as `gemini` and `cursor`: ' +
+      "upstream's target is already a known, patched and reconciled tree. Realignment " +
+      'would also have to move the instruction wiring, so it belongs in its own story.'
+  })
+});
+
 function getAgent(agentId) {
   return agents.find(a => a.id === agentId);
 }
@@ -383,5 +460,6 @@ module.exports = {
   getAgent,
   getAllAgents,
   getAgentsByCategory,
-  getBmadPlatformCode
+  getBmadPlatformCode,
+  PLATFORM_PATH_DIVERGENCES
 };

package/lib/bmad-extension/skills/ma-agent-cyber/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/cyber/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/cyber/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension/skills/ma-agent-devops/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/devops/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/devops/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension/skills/ma-agent-sqa/SKILL.md

@@ -53,7 +53,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 14 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/sqa/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension/skills/ma-agent-sre/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/sre/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/sre/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.18.0-beta.1",
+      "version": "3.18.0-beta.2",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad-extension-plugin/skills/ma-agent-cyber/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/cyber/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/cyber/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension-plugin/skills/ma-agent-devops/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/devops/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/devops/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension-plugin/skills/ma-agent-sqa/SKILL.md

@@ -53,7 +53,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 14 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/sqa/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad-extension-plugin/skills/ma-agent-sre/SKILL.md

@@ -43,7 +43,7 @@ You must fully embody this agent's persona and follow all activation instruction
 | 6 | DA | Dismiss Agent | "dismiss", "exit", "quit" | _(built-in)_ |
 
 ## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/sre/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
+1. Read the skills MANIFEST at {project-root}/_bmad/skills/sre/MANIFEST.yaml if it exists
+2. For each skill marked always_load: true, read the skill file completely (only if that MANIFEST was read; if it was not, skip this step)
 3. If _bmad-output/project-context.md exists, read it completely
 4. Follow all skill directives and project-context rules during this session

package/lib/bmad.js

@@ -527,6 +527,69 @@ const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
     wds: 'Whiteport Design Studio — strategic UX and design-first planning',
 });
 
+/**
+ * FR123, as amended 2026-08-02 — the DEFAULT BMAD install set.
+ *
+ *   "the default install set is bmm plus the non-design bundled modules —
+ *    tea, bmb, cis — from the bundled cache manifest. The two design-studio
+ *    modules gds (Game Design Studio) and wds (Whiteport Design Studio) are
+ *    bundled but not installed by default."
+ *
+ * BUNDLING AND INSTALLING ARE DIFFERENT THINGS and this constant only speaks
+ * about the second one. `gds` and `wds` stay in `lib/bmad-cache/`, stay in
+ * `cache-manifest.json`, stay in `KNOWN_BUNDLED_MODULES`, and stay offered by
+ * the `--bmad-modules` multiselect — a `--bmad-modules wds` install still
+ * resolves entirely from the bundled cache with no network access (NFR2 /
+ * NFR50 / NFR57 are untouched). What changes is only that they no longer
+ * arrive uninvited.
+ *
+ * WHY THESE TWO AND NOT OTHERS: they are the only bundled modules that
+ * declare a `directories:` block scaffolding `design-artifacts/` at the
+ * project root, which is how a Copilot+Cline user with no interest in UX
+ * tooling ended up with an unexplained five-folder `design-artifacts/` tree
+ * (bug B2). Upstream itself declares `default_selected: false` on every
+ * bundled module and `true` only on `bmm`, so narrowing here moves ma-agents
+ * TOWARDS upstream's stated intent rather than away from it.
+ *
+ * DELIBERATELY A LITERAL, NOT DERIVED FROM THE MANIFEST. The previous
+ * behaviour — "every non-retired key of the cache manifest" — is precisely
+ * what made the set grow silently every time a module was bundled. Naming the
+ * members means the next bundled module has to be added here on purpose.
+ */
+const DEFAULT_BMAD_MODULE_IDS = Object.freeze(['bmm', 'tea', 'bmb', 'cis']);
+
+/**
+ * The counterpart to DEFAULT_BMAD_MODULE_IDS: bundled, fully installable, but
+ * only when explicitly asked for. Exported so callers (and tests) can state
+ * "bundled but not default" without re-deriving it by subtraction.
+ */
+const NON_DEFAULT_BMAD_MODULE_IDS = Object.freeze(['gds', 'wds']);
+
+/**
+ * The FR123 default set, intersected with what this bundle can actually
+ * install.
+ *
+ * The intersection is not ceremony: `getInstallableBmadModules()` degrades to
+ * `[bmm]` alone when the cache manifest is missing or unreadable, and a
+ * default set containing `tea` would then be handed to `resolveBmadModules`,
+ * which throws on unknown ids. A broken cache must degrade to a minimal
+ * install, not to a crash in the module-selection step.
+ *
+ * Order follows DEFAULT_BMAD_MODULE_IDS, so the resolved `--modules` value is
+ * deterministic (NFR21) regardless of manifest key order.
+ *
+ * @param {Array<{id: string}>|string[]} [available] - installable modules;
+ *   defaults to the non-retired installable set.
+ * @returns {string[]} module ids, `bmm` first
+ */
+function getDefaultBmadModules(available) {
+    const pool = Array.isArray(available)
+        ? available
+        : getInstallableBmadModules().filter(m => !m.retired);
+    const ids = new Set(pool.map(m => (m && typeof m === 'object' ? m.id : m)));
+    return DEFAULT_BMAD_MODULE_IDS.filter(id => ids.has(id));
+}
+
 /**
  * Return the BMAD modules this ma-agents bundle can install. `bmm` (the
  * BMad core) is always first because it ships inside the `bmad-method`
@@ -567,7 +630,18 @@ function getInstallableBmadModules() {
 /**
  * Detect which BMad modules are already installed under a given project
  * root by checking for `_bmad/<id>/` directories. Used by the install
- * wizard's update path to pre-check the user's existing module set.
+ * wizard's update path to pre-check the user's existing module set, and by
+ * `selectBmadModules` branch 3b as the non-destructive migration probe for
+ * projects that predate bug 27.13's persisted selection.
+ *
+ * DIRECTORIES, not merely entries. `fs.existsSync` answers yes for a regular
+ * file, so a stray `_bmad/wds` FILE was enough to make this report wds
+ * installed — and because branch 3b PERSISTS what it finds, that misreading
+ * became a durable "explicit user selection" the project could never shed.
+ * `prePopulateBmadCache` checks `stat.isDirectory()` in the analogous place
+ * (the cache-source walk); this matches it. `statSync` is wrapped because the
+ * entry can disappear between listing and stat and because a broken symlink
+ * throws ENOENT — both mean "not an installed module".
  *
  * @param {string} projectRoot - Absolute or relative project root
  * @returns {string[]} Module ids that have a corresponding `_bmad/<id>/` dir
@@ -577,7 +651,13 @@ function getInstalledBmadModules(projectRoot) {
     const bmadDir = path.join(projectRoot, BMAD_DIR);
     if (!fs.existsSync(bmadDir)) return [];
     const installable = getInstallableBmadModules().map(m => m.id);
-    return installable.filter(id => fs.existsSync(path.join(bmadDir, id)));
+    return installable.filter(id => {
+        try {
+            return fs.statSync(path.join(bmadDir, id)).isDirectory();
+        } catch {
+            return false;
+        }
+    });
 }
 
 /**
@@ -1271,23 +1351,166 @@ const PERSONA_SKILL_MAP = Object.freeze({
     'bmm-analyst':      'bmad-agent-analyst',
     'bmm-tech-writer':  'bmad-agent-tech-writer',
     'bmm-ux-designer':  'bmad-agent-ux-designer',
+    // INERT — these two never deploy. `bmad-agent-sm` and `bmad-agent-qa` were
+    // retired upstream (merged into Amelia) and ma-agents itself deletes them on
+    // every install via RETIRED_SKILL_IDS (lib/installer.js:2224-2229). Both
+    // `bmm-sm.customize.yaml` and `bmm-qa.customize.yaml` nevertheless author an
+    // `on_prem_phase_prefix`, so an authored behaviour is routed to a directory
+    // nothing writes: measured on a real on-prem install, six of these eight
+    // entries carry the prefix and these two are absent from all four trees.
+    // Left AS IS deliberately — repointing `bmm-qa` at `ma-agent-sqa` (the
+    // persona that file actually describes: Gadi, trigger `skill:ma-agent-sqa`)
+    // would start injecting into a shipped persona that has never carried it,
+    // which is a product decision, not a drive-by on an unrelated path fix.
+    // Filed as bug-on-prem-phase-prefix-is-authored-for-two-personas-that-are-
+    // never-deployed, with both readings and the measurement.
     'bmm-sm':           'bmad-agent-sm',
     'bmm-qa':           'bmad-agent-qa',
 });
 
-// Tool skill-dir roots. Kept in sync with `lib/agents.js` canonical
-// `skillsDir` values — duplicated here (not imported) to avoid pulling the
-// agents module into install-time code paths that don't need it. The five
-// IDE tools listed are the only targets that receive `bmad-agent-*` persona
-// skills post-22.6 (verified 2026-04-23 via scratch install).
-// bmad-method 6.5.0 moved copilot, roo, and kilo to the shared .agents/skills/
-// directory. Deduplicated here — F1a walks each unique dir once.
+// Tool skill-dir roots declared by `lib/agents.js` (category `ide`), deduplicated
+// — duplicated here rather than imported to avoid pulling the agents module into
+// install-time code paths that don't need it. `test/routing-parity.test.js` 5.4
+// asserts set equality against the IDE registry, so drift fails at build time.
+//
+// Bug `antigravity-path-divergence`: this list is a SEED, no longer the patch
+// target set. A hard-coded list can only ever name the trees ma-agents knows
+// about, and the defect was precisely a tree it did not — bmad-method wrote
+// Antigravity's skills to `.agent/skills` while this registry said
+// `.antigravity/skills`, so the on-prem phase-prefix pass walked straight past a
+// populated 166-skill tree and nothing failed. `discoverDeployedSkillTrees()`
+// below derives the real target set from what is on disk; the seed only survives
+// so a future registry entry outside the dot-container convention is still honoured.
 const TOOL_SKILL_DIRS = Object.freeze([
     path.join('.claude', 'skills'),
+    path.join('.gemini', 'skills'),
     path.join('.agents', 'skills'),   // copilot, roo-code, kilocode (bmad-method 6.5.0)
     path.join('.cline', 'skills'),
+    path.join('.cursor', 'skills'),
+    path.join('.agent', 'skills'),    // antigravity (aligned to bmad-method upstream)
+    path.join('.opencode', 'skills'),
 ]);
 
+// Directories never descended into while scanning for deployed skill trees.
+const DEPLOYED_TREE_SCAN_SKIP = Object.freeze(['.git', 'node_modules']);
+
+// Skill directory names whose presence marks a `<container>/skills` directory as
+// a DEPLOYED persona tree rather than an ordinary folder called "skills". Both
+// persona families are listed: the `bmad-agent-*` set BMAD deploys and the
+// `ma-agent-*` set this package ships, so a tree carrying either is discovered.
+const DEPLOYED_TREE_PERSONA_MARKERS = Object.freeze([
+    ...Object.values(PERSONA_SKILL_MAP),
+    'ma-agent-cyber',
+    'ma-agent-devops',
+    'ma-agent-sre',
+    'ma-agent-sqa',
+]);
+
+/**
+ * Derive the set of deployed skill trees present under `projectRoot` FROM DISK.
+ *
+ * A deployed tool skill tree is a directory `<container>/skills` (or
+ * `<container>/<sub>/skills`, e.g. `.github/copilot/skills`) that contains at
+ * least one persona skill directory with a `SKILL.md`. Any writer can create
+ * one — ma-agents' own standalone loop, bmad-method's PluginResolver, or a tool
+ * we have never registered — and post-deploy patches must reach all of them.
+ *
+ * The walk is deliberately confined to DOT-PREFIXED containers. Every
+ * `target_dir` in bmad-method's `platform-codes.yaml` is dot-prefixed, so this
+ * covers the whole upstream surface; it also guarantees the patcher can never
+ * reach a SOURCE checkout's own skill directories (`lib/bmad-extension/skills/`,
+ * `skills/`), which are shipped artifacts with pinned digests, not deployments.
+ *
+ * @param {string} projectRoot        Absolute project root to scan
+ * @param {string[]} [personaDirNames] Skill directory names that mark a tree as
+ *                                     a deployment target. Defaults to
+ *                                     DEPLOYED_TREE_PERSONA_MARKERS (both the
+ *                                     `bmad-agent-*` and `ma-agent-*` families);
+ *                                     callers may narrow it to the personas they
+ *                                     actually intend to patch.
+ *
+ * Known limit: the level-1 scan uses `Dirent.isDirectory()`, which is false for
+ * a symlink. A SYMLINKED, UNREGISTERED tool container is therefore not
+ * discovered; registered ones still are, because the seed pass stats (and so
+ * follows) their paths.
+ * @returns {string[]} Sorted tree paths relative to `projectRoot`, deduplicated
+ *                     case-insensitively on win32 (where `.Claude/skills` and
+ *                     `.claude/skills` are one physical directory) and
+ *                     case-sensitively everywhere else
+ */
+function discoverDeployedSkillTrees(projectRoot, personaDirNames = DEPLOYED_TREE_PERSONA_MARKERS) {
+    if (!projectRoot || typeof projectRoot !== 'string') return [];
+    if (!Array.isArray(personaDirNames) || personaDirNames.length === 0) return [];
+
+    const isDeployedTree = (relDir) => {
+        const abs = path.join(projectRoot, relDir);
+        try {
+            if (!fs.statSync(abs).isDirectory()) return false;
+        } catch {
+            return false;
+        }
+        // `isFile()`, not `existsSync()`: a DIRECTORY named `SKILL.md` would
+        // otherwise mark the tree as a deployment target, and every consumer
+        // then fails on EISDIR when it tries to read it. The read is guarded
+        // (the error is caught and warned), so this is not a crash — but the
+        // warning is misleading and the tree was never a deployment at all.
+        return personaDirNames.some(name => {
+            try {
+                return fs.statSync(path.join(abs, name, 'SKILL.md')).isFile();
+            } catch {
+                return false;
+            }
+        });
+    };
+
+    const subdirs = (rel) => {
+        try {
+            return fs.readdirSync(rel ? path.join(projectRoot, rel) : projectRoot, { withFileTypes: true })
+                .filter(e => e.isDirectory())
+                .map(e => e.name);
+        } catch {
+            return []; // unreadable dir — never fatal for a post-install pass
+        }
+    };
+
+    // Keyed by the case-folded path on case-insensitive filesystems, holding the
+    // FIRST spelling seen. On Windows `.Claude/skills` and `.claude/skills` are
+    // ONE physical directory: the seed pass stats the registry spelling and
+    // succeeds, then the on-disk scan reports whatever casing is actually on
+    // disk, so a plain Set enumerates the same tree twice. The second pass is
+    // idempotent (the marker block is replaced byte-for-byte), so this was never
+    // a correctness bug — but it double-counts in every caller's result list.
+    // Seeding runs first, so the registry's canonical spelling wins.
+    // Confined to win32 deliberately: macOS is case-insensitive by default but
+    // can be formatted case-sensitive, and we have no evidence to change
+    // behaviour there.
+    const found = new Map();
+    const caseKey = (rel) => (process.platform === 'win32' ? rel.toLowerCase() : rel);
+    const addTree = (rel) => {
+        const key = caseKey(rel);
+        if (!found.has(key)) found.set(key, rel);
+    };
+
+    // 1. Registry seed — honours any declared dir outside the dot convention.
+    for (const rel of TOOL_SKILL_DIRS) {
+        if (isDeployedTree(rel)) addTree(rel);
+    }
+
+    // 2. On-disk scan of dot-prefixed containers, one level of nesting deep.
+    for (const lvl1 of subdirs('')) {
+        if (!lvl1.startsWith('.') || DEPLOYED_TREE_SCAN_SKIP.includes(lvl1)) continue;
+        const direct = path.join(lvl1, 'skills');
+        if (isDeployedTree(direct)) addTree(direct);
+        for (const lvl2 of subdirs(lvl1)) {
+            if (lvl2 === 'skills' || DEPLOYED_TREE_SCAN_SKIP.includes(lvl2)) continue;
+            const nested = path.join(lvl1, lvl2, 'skills');
+            if (isDeployedTree(nested)) addTree(nested);
+        }
+    }
+
+    return [...found.values()].sort();
+}
+
 /**
  * Build the marker-wrapped block that is injected into a persona SKILL.md.
  * Kept as a single-source helper so the test assertions and the production
@@ -1420,10 +1643,16 @@ async function applyOnPremPhasePrefixToDeployedSkills(
     }
     if (personaPrefix.size === 0) return [];
 
+    // Bug `antigravity-path-divergence` — the target set is derived FROM DISK,
+    // not from TOOL_SKILL_DIRS. Walking a hard-coded registry list is exactly
+    // how a populated `.agent/skills` tree went unpatched in an on-prem project
+    // while `.claude`, `.agents` and `.cline` were patched: our registry had
+    // never heard of it. Discovery is keyed on the personas we actually have a
+    // prefix for, so a tree with none of them is not a target at all.
     const results = [];
-    for (const toolRel of TOOL_SKILL_DIRS) {
+    const targetTrees = discoverDeployedSkillTrees(projectRoot, [...personaPrefix.keys()]);
+    for (const toolRel of targetTrees) {
         const toolSkillsDir = path.join(projectRoot, toolRel);
-        if (!fs.existsSync(toolSkillsDir)) continue; // tool not installed
 
         for (const [skillDirName, prefix] of personaPrefix) {
             const skillDir = path.join(toolSkillsDir, skillDirName);
@@ -2767,10 +2996,18 @@ function getCandidateSkillDirNames(customizeFilename) {
 
 /**
  * Enumerate the IDE/BMAD tool skill directories that may contain deployed
- * persona skills. Reads from `lib/agents.js` so the list stays in lockstep
- * with the installer's own fan-out (Story 22.10). Returns absolute paths to
- * directories that actually exist on disk; non-existent tool dirs are
- * silently skipped (the tool was not selected for install).
+ * persona skills. Returns absolute paths to directories that actually exist on
+ * disk; non-existent tool dirs are silently skipped (the tool was not selected
+ * for install).
+ *
+ * Two sources, unioned — bug `antigravity-path-divergence`:
+ *   1. `lib/agents.js`, so the list stays in lockstep with the installer's own
+ *      fan-out (Story 22.10), including the `_bmad/skills/*` BMAD-persona roots
+ *      that the dot-container scan deliberately does not reach.
+ *   2. `discoverDeployedSkillTrees()`, so a tree written by another pipeline that
+ *      our registry has never heard of is patched too. This is the same blind
+ *      spot that left a populated `.agent/skills` unpatched: a registry-only
+ *      derivation can only ever find the directories we already named.
  *
  * @param {string} projectRoot - Absolute path to the project root
  * @returns {string[]} Absolute skills-dir paths that exist
@@ -2785,6 +3022,9 @@ function getDeployedSkillsRoots(projectRoot) {
             roots.add(abs);
         }
     }
+    for (const rel of discoverDeployedSkillTrees(projectRoot)) {
+        roots.add(path.resolve(projectRoot, rel));
+    }
     return [...roots];
 }
 
@@ -3479,6 +3719,9 @@ module.exports = {
     buildOnPremPrefixBlock,
     PERSONA_SKILL_MAP,
     TOOL_SKILL_DIRS,
+    // Bug `antigravity-path-divergence` — disk-derived patch-target set
+    discoverDeployedSkillTrees,
+    DEPLOYED_TREE_PERSONA_MARKERS,
     ON_PREM_PREFIX_MARKER_BEGIN,
     ON_PREM_PREFIX_MARKER_END,
     // Offline-safe recompile helpers (exported for testing — see bug
@@ -3498,6 +3741,11 @@ module.exports = {
     getInstallableBmadModules,
     getInstalledBmadModules,
     resolveBmadModules,
+    // FR123 (amended 2026-08-02) — the default INSTALL set, distinct from the
+    // bundled set. See the long note on DEFAULT_BMAD_MODULE_IDS.
+    DEFAULT_BMAD_MODULE_IDS,
+    NON_DEFAULT_BMAD_MODULE_IDS,
+    getDefaultBmadModules,
     // 3.12.2 — offline-fallback marker for bmad-method's cloneExternalModule
     ensureCacheMarker,
 };

package/lib/installer.js

@@ -2261,9 +2261,28 @@ const OBSOLETE_TOOL_SKILL_DIRS = Object.freeze([
   // tool-specific paths to the shared .agents/skills/ directory.
   { obsolete: '.github/skills', replacedBy: '.agents/skills', sinceVersion: '3.8.1' },
   { obsolete: '.roo/skills', replacedBy: '.agents/skills', sinceVersion: '3.8.1' },
-  { obsolete: '.kilocode/skills', replacedBy: '.agents/skills', sinceVersion: '3.8.1' }
+  { obsolete: '.kilocode/skills', replacedBy: '.agents/skills', sinceVersion: '3.8.1' },
+  // Bug `antigravity-path-divergence`: ma-agents declared `.antigravity/skills`
+  // while bmad-method writes Antigravity's skills to `.agent/skills`
+  // (platform-codes.yaml, platform `antigravity`). A single install therefore
+  // produced two trees, and the one the tool actually reads was patched by
+  // nobody. lib/agents.js is now aligned to upstream; this sweeps the tree
+  // ma-agents itself created on the old path — and only once `.agent/skills`
+  // has content, per migrateObsoleteToolDirs' preserve-on-empty rule.
+  // APPEND-ONLY: entries above are positional in test/obsolete-tool-dirs.test.js
+  // (results[0] must stay the copilot entry).
+  { obsolete: '.antigravity/skills', replacedBy: '.agent/skills', sinceVersion: '3.18.0' }
 ]);
 
+// Story 31.16 — the two bookkeeping files ma-agents itself writes into a skills
+// directory: `.ma-agents.json` (the per-install record, `writeManifest`) and
+// `MANIFEST.yaml` (derived from it, `generateSkillsManifest`). The obsolete-dir
+// sweep excludes these from its residue calculation, because neither is user
+// content and treating them as residue would make every manifested tree preserve
+// forever. Deliberately NOT exported: a test that took its expectation from this
+// constant would be asserting the implementation against itself.
+const OBSOLETE_SWEEP_MANIFEST_FILES = new Set([MANIFEST_FILE, 'MANIFEST.yaml']);
+
 async function migrateRetiredSkills(options = {}) {
   const { scope = 'project', customPath = '' } = options;
   const results = [];
@@ -2360,11 +2379,20 @@ async function migrateRetiredSkills(options = {}) {
  * legacy directory exists under `projectRoot`. Behaviour per entry:
  *
  *   - Obsolete dir absent          → no-op (idempotent)
- *   - Obsolete dir present AND
- *     replacedBy dir has content   → remove obsolete dir, log info message
  *   - Obsolete dir present BUT
  *     replacedBy dir is empty/gone → preserve obsolete dir, log warning
  *                                    (user may have local edits; safer to keep)
+ *   - Obsolete dir present AND replacedBy dir has content → Story 31.16 decides
+ *     per child, using the obsolete dir's OWN `.ma-agents.json::skills` as the
+ *     record of what ma-agents installed there:
+ *       owned    = manifest skill ids (each id IS a directory basename)
+ *       residue  = readdir(obsolete) − owned − {.ma-agents.json, MANIFEST.yaml}
+ *       residue empty     → remove the whole dir          → action 'removed'
+ *       residue non-empty → remove owned children, KEEP   → action 'preserved-partial'
+ *                           the dir, and name the residue
+ *     No manifest, an unparseable one, or `skills: {}` all yield an empty
+ *     `owned`, so the whole directory is residue and is preserved. Unknown
+ *     provenance fails safe; nothing is special-cased.
  *
  * @param {string} projectRoot — absolute path to the project root (process.cwd() in production)
  * @returns {Promise<Array<{entry, action, obsoletePath, replacedByPath, error}>>}
@@ -2391,13 +2419,101 @@ async function migrateObsoleteToolDirs(projectRoot) {
         }
 
         if (replacedByHasContent) {
-          // Safe to remove — skills have been migrated to the new location.
-          await fs.remove(obsoletePath);
-          action = 'removed';
-          console.log(chalk.green(
-            `  - Removed legacy tool skills directory ${entry.obsolete} ` +
-            `(moved to ${entry.replacedBy} in v${entry.sinceVersion})`
-          ));
+          // Story 31.16 — the sweep is manifest-aware. Removing the whole
+          // directory here destroyed hand-authored skills that ma-agents never
+          // installed and never migrated anywhere (bug
+          // `obsolete-tool-dir-sweep-deletes-user-authored-skills`).
+          //
+          // The directory's own `.ma-agents.json::skills` is ma-agents' record of
+          // exactly what it installed there, and a manifest key IS the on-disk
+          // directory basename (`performInstall` installs to
+          // `path.join(installPath, skillId)`). It is a POSITIVE record only:
+          // manifest-recorded implies ma-agents installed it, but the converse
+          // does NOT hold — many real trees carry no per-tree manifest at all,
+          // because bmad-method's PluginResolver also writes skills into these
+          // trees and writes no manifest. So anything unrecorded is content of
+          // unknown provenance and is preserved. This deliberately
+          // over-preserves: a stale directory costs the user the `rm -rf` we
+          // already print, a deleted hand-written skill costs them the file.
+          const obsoleteManifest = readManifest(obsoletePath);
+          const owned = obsoleteManifest && obsoleteManifest.skills
+            && typeof obsoleteManifest.skills === 'object'
+            ? Object.keys(obsoleteManifest.skills)
+            : [];
+          const ownedSet = new Set(owned);
+
+          // The two manifest files are ma-agents' own bookkeeping. They are
+          // EXCLUDED from residue rather than counted as owned: counting them as
+          // residue would make every manifested tree preserve forever and kill
+          // the cleanup outright. They are deleted only as part of a
+          // whole-directory removal — on the preserve path they are left
+          // byte-unchanged, so a second run recomputes the same `owned` set and
+          // behaves identically to the first.
+          //
+          // `entries` is the single source of truth for what is actually on
+          // disk here, and BOTH halves of the decision below are taken against
+          // it. A manifest key is file CONTENT, never a path: it is only ever
+          // matched against this listing, never joined onto `obsoletePath` and
+          // trusted. See the removal loop below for why that matters.
+          const entries = fs.readdirSync(obsoletePath);
+          const residue = entries
+            .filter(name => !ownedSet.has(name) && !OBSOLETE_SWEEP_MANIFEST_FILES.has(name));
+
+          if (residue.length === 0) {
+            // Everything present is ma-agents' own — safe to remove, skills have
+            // been migrated to the new location.
+            await fs.remove(obsoletePath);
+            action = 'removed';
+            console.log(chalk.green(
+              `  - Removed legacy tool skills directory ${entry.obsolete} ` +
+              `(moved to ${entry.replacedBy} in v${entry.sinceVersion})`
+            ));
+          } else {
+            // Something here is not ours. Remove only what the manifest records
+            // AND what the directory listing actually contains, and keep the
+            // directory, naming what caused the preservation.
+            //
+            // `entries.includes(id)` is not an optimisation — it is the safety
+            // property. Joining a raw manifest key onto `obsoletePath` and
+            // removing the result trusts file content as a filesystem path, and
+            // two concrete destruction paths follow from that:
+            //
+            //   1. CASE. `residue` is computed with case-SENSITIVE set
+            //      membership, but `fs.remove` resolves case-INSENSITIVELY on
+            //      NTFS and APFS. An on-disk `Code-Review` against a manifest
+            //      key `code-review` is therefore reported as residue ("items
+            //      ma-agents did not install"), the directory is declared
+            //      preserved — and the user's directory is deleted in the same
+            //      breath. `entries.includes` is case-sensitive, so the two
+            //      halves of the decision can no longer disagree.
+            //
+            //   2. CONTAINMENT. A manifest key is not validated to be a
+            //      basename. A `skills` map holding `../../../victim` escapes
+            //      the obsolete directory entirely and deletes an unrelated
+            //      path under the project root — while still taking THIS
+            //      branch, because a key matching nothing in `readdir` counts
+            //      as neither owned-present nor residue. A name that came out
+            //      of `readdir(obsoletePath)` can only ever be a real, direct
+            //      child of that directory, so no traversal survives the
+            //      filter. This function's stated premise is that provenance is
+            //      unknown and must fail safe; "the manifest is normally
+            //      ma-agents-written" is not a defence inside it.
+            //
+            // A recorded id with no directory on disk is now an explicit no-op
+            // — it is filtered out rather than being an incidentally harmless
+            // `fs.remove` of a non-existent path — which keeps this idempotent.
+            for (const skillId of owned.filter(id => entries.includes(id))) {
+              await fs.remove(path.join(obsoletePath, skillId));
+            }
+            action = 'preserved-partial';
+            console.log(chalk.yellow(
+              `  ! Legacy tool skills directory ${entry.obsolete} was preserved ` +
+              `because it contains ${residue.length} item(s) ma-agents did not install: ` +
+              `${residue.join(', ')}. ` +
+              `Remove it manually once you have confirmed there is nothing to keep: ` +
+              `rm -rf ${entry.obsolete}`
+            ));
+          }
         } else {
           // Replacement is absent or empty — do not silently destroy user content.
           action = 'preserved';
@@ -2695,6 +2811,12 @@ module.exports = {
   getStatus,
   readManifest,
   ensureManifest,
+  // Story 31.16 — exported so the obsolete-tool-dir tests can build their
+  // fixtures through the REAL manifest writer instead of hand-writing the
+  // `.ma-agents.json` shape. Behaviour unchanged; this is an export, not a new
+  // code path. `readManifest` and `ensureManifest` were already exported for the
+  // same reason.
+  writeManifest,
   getInstalledSkillInfo,
   getManifestAgents,
   compareSemver,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.18.0-beta.1",
+  "version": "3.18.0-beta.2",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {