bmad-method 6.9.1-next.9 → 6.10.1-next.0

package/src/core-skills/bmad-review-edge-case-hunter/references/deletion-check.md

@@ -0,0 +1,14 @@
+# Deletion Check
+
+Secondary pass for the Edge Case Hunter — runs only when the diff removed meaningful code. Subordinate to the edge-case pass; findings are usually few or none.
+
+For each chunk of removed or replaced code (ignore pure renames and whitespace), ask: did it carry behavior or a contract that the change neither re-established nor intentionally retired? Add a finding for any resulting regression, orphaned reference, or newly-dead code. Skip anything already covered by your edge-case findings.
+
+Append each finding to the same JSON array as the edge-case findings, with the four standard fields plus:
+
+- `kind`: `"deletion"`
+- `confidence`: `"high"`, `"medium"`, or `"low"` — these are inferences; rate them
+
+For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
+
+Add nothing if nothing qualifies.

package/src/core-skills/bmad-review-verification-gap/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: bmad-review-verification-gap
+description: 'Review a code change for changed behavior that could regress without reliable verification catching it. Use when checking whether a change is adequately verified.'
+---
+
+# Verification Gap Review
+
+**Goal:** Find changed behavior that could break without reliable verification catching it. Ask one question — "if the behavior this change is supposed to produce broke where it's actually used, would verification fail?" Do not hunt for correctness bugs, but report genuine problems you notice while tracing verification.
+
+The main verification gap shapes are:
+
+1. **Regression gap:** the changed code regresses where it's used, and no test covering that use would fail.
+2. **Missing-adoption gap:** a place that should now use the new behavior doesn't; it handles the same case its own way, or not at all, and no test would flag the omission.
+3. **Broken-verification gap:** a test appears to cover the changed behavior, but would not actually protect it because it is skipped, flaky, not run in the normal verification path, or too weak to observe the regression.
+
+## Evidence Rules
+
+- Read a test before claiming what it covers, runs, asserts, or misses.
+- Before claiming no test exists, search the whole repo by the symbol under test and by import references; expected file locations are not enough.
+- Never assert what you did not verify. If a finding cannot be grounded, drop it.
+- In a finding, say what you actually checked — "none of the tests I read cover this" — and show how far you looked. Say a test doesn't exist anywhere only when the symbol/import-reference search actually shows that.
+- Do not assign severity, confidence, priority, or ranking.
+
+## Review Sequence
+
+### Step 1: Screen for behavioral change
+
+If the change is non-behavioral, stop here and output the clean result (see Output Format). Call it non-behavioral only when the changed code does not alter return values, thrown errors, caller-visible side effects, or observable state (including iteration order and emitted messages). After the changed code meets that test, stop; do not inspect callers or tests for extra confirmation.
+
+Common non-behavioral examples: formatting, comments, whitespace; pure renames; trivial getters/setters and pass-throughs; type-only or compiler-enforced changes with no runtime effect; etc.
+
+### Step 2: Find the behavior that changed
+
+Identify what behavior changed compared to the previous version: output, side effect, branch, error path, schema/event shape, config default, validation/authorization rule, external contract, etc. If the change affects more than one behavior, handle each separately.
+
+Treat broad-impact changes as behavioral even when no single changed line looks important: dependency, toolchain, build/config, data-file, etc.
+
+### Step 3: Trace where that behavior is used
+
+Trace the changed behavior to the places that observe it. Start with direct callers and registered entry points (routes, commands, DI), contract consumers (schemas, events, APIs, database readers), and reverse-dependency info if already available.
+
+Follow a path only while the changed behavior is reachable and unverified. Stop when a test at that boundary would fail, the consumer does not observe the changed behavior, or the next hop is guesswork (dynamic dispatch, reflection, outside-repo consumers, etc.). Prefer the nearest observable boundary, often one to three hops away, especially across contract, integration, or service edges. If there are more than five similar consumers, group obvious repeats and check representative paths; expand only when a consumer observes the behavior differently.
+
+### Step 4: Qualify the consumer, then check its test
+
+For each consumer, name the smallest realistic regression this consumer would observe: invert the branch, drop the default, omit the field, return the old error code, skip the integration call, etc. This is the Demonstration. If no such regression exists, drop the path; untested downstream code is not a finding.
+
+A `Missing-adoption gap` qualifies not by the adoption failure alone but by a supersession signal: the change gives clear evidence the new behavior is meant to replace the local one — PR intent, naming or docs, a replaced sibling site, deleted duplicate logic, or a test defining the new rule — and the local site shares the same observable contract. Without a supersession signal and a shared observable contract, it is a refactor suggestion, not a verification-gap finding. Once both hold, check whether any test for that site would flag the non-adoption; missing coverage of the non-adoption is the gap itself, not a disqualifier.
+
+Find and read the relevant test. Ask whether the Demonstration would make an assertion fail.
+
+- If yes, the behavior is verified. No finding.
+- For a regression-style Demonstration: if no test runs the path, the test is skipped/flaky/not run normally, or the test runs the code without checking the changed result, report a `Regression gap` or `Broken-verification gap`.
+- For a qualifying Missing-adoption case: if none of the site tests you found assert it adopts the new behavior, report a `Missing-adoption gap`.
+
+A test counts only if it runs normally and an assertion observes the changed output, branch, or contract. These do not count: no execution; success/no-throw/snapshot-only checks; mock/log-call checks; human-only checks; tests that mock away the integration; e2e tests that pass through without checking the changed output; stale assertions or fixtures.
+
+Common patterns:
+
+- **Caller-path gap** — helper test covers the branch, but caller values skip it.
+- **Contract drift** — payload/schema/event changes must be verified at the consumer.
+- **Migration compatibility** — tests only create new-format rows or fresh schemas.
+- **Phantom exception** — handled partial-failure path has no test.
+- **Missing-adoption gap** — sibling site should use the new rule/helper and does not.
+- **Removed verification** — deleted test or weakened assertion leaves behavior unpinned.
+
+### Step 5: Confirm each finding is real
+
+Before writing a finding, re-open the specific tests or search results the finding relies on. Verify the Demonstration would not make any test you checked fail, or that the absence claim is backed by the symbol/import-reference search. Do not claim more than you verified; drop any finding you cannot ground.
+
+Do not report: compiler/type-checker-enforced cases; behavior already verified by an integration, contract, or e2e test; implementation-detail or mock-only tests; low coverage or a missing test file by itself; legacy untested code the change did not affect.
+
+Report genuine problems you noticed while tracing verification, even if they are not verification gaps. Put them under `Other findings` in the output. This permits reporting what you already reached, not extra hunting.
+
+## OUTPUT FORMAT
+
+Emit each verification-gap finding as one block. No general advice, no severity or confidence.
+
+```markdown
+### <one-line title naming the gap>
+
+- **Changed surface:** the exact behavior or contract that changed — `file:line`.
+- **Impacted consumer or site:** named concretely with `file:line` (e.g. "the `createInvoice` mutation used by the billing dashboard at `billing/dashboard.ts:88`," not "callers of this function").
+- **Existing test evidence:**
+  - `Regression gap`: what the relevant test actually asserts, with `file:line`; or, if none, the symbol/import-reference searches run and their result.
+  - `Missing-adoption gap`: tests for the impacted site, and whether any assert it adopts the new behavior.
+  - `Broken-verification gap`: the apparent test or verification path, and why it does not count.
+- **Missing verification:** the precise assertion or check that's absent.
+- **Demonstration:**
+  - `Regression gap` / `Broken-verification gap`: the concrete regression that would ship undetected, and why the tests you checked would not fail.
+  - `Missing-adoption gap`: the case the site mishandles by not adopting the new behavior, and that none of the tests you read assert adoption.
+- **Consequence:** the concrete thing that ships wrong — a regression the checked evidence would not catch, or a site that should use the new behavior and doesn't.
+- **Suggested test shape:** (optional) the kind of test that would close the gap, fit to the repo's own way of verifying — don't impose a generic test pyramid.
+```
+
+If you noticed genuine non-gap problems while tracing verification, append:
+
+```markdown
+## Other findings
+
+- <description only; no severity, confidence, priority, or ranking>
+```
+
+When you find no verification gaps and no other findings, output exactly this single line, not an empty response:
+
+`No verification gaps found.`

package/tools/installer/core/installer.js

@@ -102,6 +102,11 @@ class Installer {
 
       const restoreResult = await this._restoreUserFiles(paths, updateState);
 
+      // Surface any "action needed" post-install messages for installed modules
+      // (e.g. run a setup skill) and let the user acknowledge them before the
+      // final summary, so "BMAD is ready to use!" stays the last thing shown.
+      await this._displayPostInstallMessages(config, officialModules);
+
       // Render consolidated summary
       await this.renderInstallSummary(results, {
         bmadDir: paths.bmadDir,
@@ -1246,6 +1251,56 @@ class Installer {
     });
   }
 
+  /**
+   * Display registry-defined post-install messages for the modules installed in
+   * this run. These are "action needed" notices (e.g. "run the bmad-loop-setup
+   * skill") that the user must see to finish setup. They are defined via the
+   * `post-install-message` property on a module's bmad-modules.yaml entry.
+   *
+   * Interactive installs require the user to acknowledge each message (press
+   * Enter); non-interactive (--yes / skipPrompts) installs print the message
+   * and continue without blocking, so CI/scripted installs don't hang.
+   *
+   * @param {Object} config - Install config (config.modules, config.skipPrompts)
+   * @param {Object} officialModules - OfficialModules instance (carries the registry)
+   */
+  async _displayPostInstallMessages(config, officialModules) {
+    const moduleCodes = config.modules || [];
+    if (moduleCodes.length === 0) return;
+
+    const externalManager = officialModules.externalModuleManager;
+    if (!externalManager) return;
+
+    const color = await prompts.getColor();
+
+    for (const code of moduleCodes) {
+      let moduleInfo;
+      try {
+        moduleInfo = await externalManager.getModuleByCode(code);
+      } catch {
+        continue; // Built-in modules (core/bmm) aren't in the registry — skip.
+      }
+
+      const message = moduleInfo && moduleInfo.postInstallMessage;
+      if (!message) continue;
+
+      await prompts.box(String(message).trim(), `⚑ Action needed — ${moduleInfo.name || code}`, {
+        rounded: true,
+        formatBorder: color.yellow,
+      });
+
+      // Interactive: require the user to acknowledge before continuing. Skip the
+      // blocking prompt in non-interactive installs (the message is still shown).
+      if (!config.skipPrompts) {
+        await prompts.text({
+          message: 'Press Enter to acknowledge',
+          placeholder: '',
+          default: '',
+        });
+      }
+    }
+  }
+
   /**
    * Quick update method - preserves all settings and only prompts for new config fields
    * @param {Object} config - Configuration with directory
@@ -1262,10 +1317,32 @@ class Installer {
 
     // Detect existing installation
     const existingInstall = await ExistingInstall.detect(bmadDir);
-    const installedModules = existingInstall.moduleIds;
     const configuredIdes = existingInstall.ides;
     const projectRoot = path.dirname(bmadDir);
 
+    // Resolve any legacy/aliased module codes (e.g. an install recorded as
+    // `bauto` before the registry renamed it to `bmad-loop`) to their current
+    // canonical code up front. Without this, a renamed module's old installs
+    // would fall out of `availableModuleIds` below and get silently frozen
+    // (see the `baut` → `automator` incident in CHANGELOG v6.7.1) instead of
+    // migrating forward.
+    const aliasMigrations = [];
+    const seenModuleIds = new Set();
+    const installedModules = [];
+    for (const rawId of existingInstall.moduleIds) {
+      const canonicalId = await this.externalModuleManager.resolveCanonicalCode(rawId);
+      if (canonicalId !== rawId) {
+        aliasMigrations.push({ from: rawId, to: canonicalId });
+      }
+      if (!seenModuleIds.has(canonicalId)) {
+        seenModuleIds.add(canonicalId);
+        installedModules.push(canonicalId);
+      }
+    }
+    for (const { from, to } of aliasMigrations) {
+      await prompts.log.info(`Migrating installed module '${from}' to its renamed successor '${to}'.`);
+    }
+
     // Get available modules (what we have source for)
     const availableModulesData = await new OfficialModules().listAvailable();
     const availableModules = [...availableModulesData.modules];
@@ -1410,6 +1487,18 @@ class Installer {
 
     await this.install(installConfig);
 
+    // Now that the canonical module has been installed successfully, remove
+    // the stale directory left behind under its old code so the two don't
+    // coexist (e.g. `_bmad/bauto/` once `_bmad/bmad-loop/` is in place).
+    for (const { from, to } of aliasMigrations) {
+      if (!modulesToUpdate.includes(to)) continue; // new code wasn't actually installed this run
+      const oldModuleDir = path.join(bmadDir, from);
+      if (await fs.pathExists(oldModuleDir)) {
+        await fs.remove(oldModuleDir);
+        await prompts.log.success(`Removed legacy '${from}' directory after migrating to '${to}'.`);
+      }
+    }
+
     return {
       success: true,
       moduleCount: modulesToUpdate.length,

package/tools/installer/core/uv-check.js

@@ -77,7 +77,7 @@ async function checkUvEnvironment() {
   const detected = module.exports.detectUv();
 
   if (detected) {
-    await prompts.log.success(`uv ${detected.version.raw} detected — ready to run BMAD's Python-powered scripts via \`uv run\`.`);
+    await prompts.log.success(`✅ Python UV check pass (uv ${detected.version.raw} detected).`);
     return { status: 'found', detected };
   }
 

package/tools/installer/modules/external-manager.js

@@ -62,6 +62,13 @@ class ExternalModuleManager {
   // ExternalModuleManager) sees resolutions made during install.
   static _resolutions = new Map();
 
+  // moduleCode → ResolvedModule (from PluginResolver). Populated for registry
+  // modules flagged `marketplace-plugin: true`, whose installable skills live
+  // outside a single module.yaml directory and must be resolved from
+  // .claude-plugin/marketplace.json. Shared across instances so install() can
+  // pick up the resolution computed during findExternalModuleSource.
+  static _pluginResolutions = new Map();
+
   constructor() {}
 
   /**
@@ -73,6 +80,15 @@ class ExternalModuleManager {
     return ExternalModuleManager._resolutions.get(moduleCode) || null;
   }
 
+  /**
+   * Get the cached marketplace-plugin resolution for a module (if any).
+   * @param {string} moduleCode
+   * @returns {Object|null} ResolvedModule from PluginResolver, or null
+   */
+  getPluginResolution(moduleCode) {
+    return ExternalModuleManager._pluginResolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from the bundled YAML file.
    * @returns {Object} Parsed YAML content with modules array
@@ -113,8 +129,16 @@ class ExternalModuleManager {
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
+      deprecated: mod.deprecated === true,
+      deprecationMessage: mod.deprecation_message || mod['deprecation-message'] || mod.deprecationMessage || null,
+      marketplacePlugin: mod.marketplace_plugin === true || mod['marketplace-plugin'] === true || mod.marketplacePlugin === true,
+      postInstallMessage: mod.post_install_message || mod['post-install-message'] || mod.postInstallMessage || null,
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
+      // Prior codes this module was registered under (e.g. `bmad-loop` was
+      // `bauto`). Lets a renamed module keep resolving existing installs
+      // instead of orphaning them — see getModuleByCode().
+      aliases: Array.isArray(mod.aliases) ? mod.aliases : [],
     };
   }
 
@@ -139,13 +163,27 @@ class ExternalModuleManager {
   }
 
   /**
-   * Get module info by code
-   * @param {string} code - The module code (e.g., 'cis')
+   * Get module info by code. Falls back to matching a registry entry's
+   * `aliases` list, so a module that was renamed (its `code` changed) still
+   * resolves for installs recorded under the prior code.
+   * @param {string} code - The module code (e.g., 'cis'), current or aliased
    * @returns {Object|null} Module info or null if not found
    */
   async getModuleByCode(code) {
     const modules = await this.listAvailable();
-    return modules.find((m) => m.code === code) || null;
+    return modules.find((m) => m.code === code) || modules.find((m) => m.aliases.includes(code)) || null;
+  }
+
+  /**
+   * Resolve a possibly-legacy module code to its current canonical code.
+   * Returns the input unchanged if it doesn't match any registry entry or
+   * alias (e.g. a custom/unknown module).
+   * @param {string} code
+   * @returns {Promise<string>}
+   */
+  async resolveCanonicalCode(code) {
+    const info = await this.getModuleByCode(code);
+    return info ? info.code : code;
   }
 
   /**
@@ -176,6 +214,11 @@ class ExternalModuleManager {
       throw new Error(`External module '${moduleCode}' not found in the BMad registry`);
     }
 
+    // Normalize to the canonical code so cache dir, in-memory resolutions,
+    // and log/error text stay consistent even when called with a renamed
+    // module's prior alias (getModuleByCode resolves aliases above).
+    moduleCode = moduleInfo.code;
+
     const cacheDir = this.getExternalCacheDir();
     const moduleCacheDir = path.join(cacheDir, moduleCode);
     const silent = options.silent || false;
@@ -468,6 +511,22 @@ class ExternalModuleManager {
       return null;
     }
 
+    // Normalize to the canonical code — see cloneExternalModule for why.
+    moduleCode = moduleInfo.code;
+
+    // Marketplace-plugin modules (registry entries flagged `marketplace-plugin`)
+    // ship a .claude-plugin/marketplace.json and keep their module.yaml inside a
+    // skill's assets/ rather than in one directory alongside the skills. Resolve
+    // them through the PluginResolver (the same machinery custom-URL installs
+    // use) and return the directory that holds module.yaml so config/version/
+    // directory callers work; install() copies the resolved skill dirs.
+    if (moduleInfo.marketplacePlugin) {
+      const pluginMod = await this.resolvePluginModule(moduleCode, options);
+      if (pluginMod && pluginMod.moduleYamlPath) {
+        return path.dirname(pluginMod.moduleYamlPath);
+      }
+    }
+
     // Clone the external module repo
     const cloneDir = await this.cloneExternalModule(moduleCode, options);
 
@@ -521,6 +580,87 @@ class ExternalModuleManager {
         `The repository may have been restructured after this release was tagged.${channelHint}`,
     );
   }
+
+  /**
+   * Resolve a marketplace-plugin registry module to an installable plugin
+   * definition. Clones the repo (respecting the channel plan), reads its
+   * .claude-plugin/marketplace.json, and runs the PluginResolver against the
+   * plugin matching this module. The result (skillPaths + module.yaml +
+   * module-help.csv) is cached so install() can copy the resolved skill dirs.
+   *
+   * @param {string} moduleCode - Code of the external module
+   * @param {Object} options - Options passed to cloneExternalModule
+   * @returns {Promise<Object|null>} ResolvedModule from PluginResolver, or null
+   *   when the module is not a marketplace plugin or cannot be resolved.
+   */
+  async resolvePluginModule(moduleCode, options = {}) {
+    const moduleInfo = await this.getModuleByCode(moduleCode);
+    if (!moduleInfo || moduleInfo.builtIn || !moduleInfo.marketplacePlugin) {
+      return null;
+    }
+
+    // Normalize to the canonical code — see cloneExternalModule for why.
+    moduleCode = moduleInfo.code;
+
+    const cloneDir = await this.cloneExternalModule(moduleCode, options);
+
+    const marketplacePath = path.join(cloneDir, '.claude-plugin', 'marketplace.json');
+    if (!(await fs.pathExists(marketplacePath))) {
+      return null;
+    }
+
+    let marketplace;
+    try {
+      marketplace = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+    } catch {
+      return null;
+    }
+
+    const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+    if (plugins.length === 0) {
+      return null;
+    }
+
+    // Prefer the plugin whose name matches the registry's plugin_name (or code),
+    // falling back to any plugin that declares skills.
+    const preferredName = moduleInfo.pluginName || moduleInfo.code;
+    const ordered = [...plugins].sort((a, b) => {
+      const am = a?.name === preferredName ? 0 : 1;
+      const bm = b?.name === preferredName ? 0 : 1;
+      return am - bm;
+    });
+
+    const { PluginResolver } = require('./plugin-resolver');
+    const resolver = new PluginResolver();
+
+    for (const plugin of ordered) {
+      if (!plugin || !Array.isArray(plugin.skills) || plugin.skills.length === 0) {
+        continue;
+      }
+      let resolvedMods;
+      try {
+        resolvedMods = await resolver.resolve(cloneDir, plugin);
+      } catch {
+        continue;
+      }
+      if (!resolvedMods || resolvedMods.length === 0) {
+        continue;
+      }
+      // Match the registry code, then the preferred plugin name, then accept a
+      // lone resolved module.
+      const match =
+        resolvedMods.find((mod) => mod.code === moduleCode) ||
+        resolvedMods.find((mod) => mod.code === preferredName) ||
+        (resolvedMods.length === 1 ? resolvedMods[0] : null);
+      if (match) {
+        match.repoUrl = moduleInfo.url;
+        ExternalModuleManager._pluginResolutions.set(moduleCode, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
   cachedModules = null;
 }
 

package/tools/installer/modules/official-modules.js

@@ -277,7 +277,29 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    // Marketplace-plugin registry modules keep their installable skills outside
+    // the directory that holds module.yaml (sourcePath points at the -setup
+    // skill's assets/), so they cannot be installed by copying sourcePath. Copy
+    // the resolved skill directories instead, matching how custom marketplace
+    // installs lay out a module. Everything else (manifest, version info) flows
+    // through the standard external-module path below.
+    const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName);
+    if (moduleInfo && moduleInfo.marketplacePlugin) {
+      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
+      // Fail loud: copying sourcePath here would install only the -setup skill's
+      // assets/ (module.yaml + module-help.csv) and none of the skills — a
+      // silent, broken partial install. Abort instead.
+      if (!pluginResolution || !Array.isArray(pluginResolution.skillPaths) || pluginResolution.skillPaths.length === 0) {
+        throw new Error(
+          `Module '${moduleName}' is registered as a marketplace plugin but its skills could not be resolved ` +
+            `from .claude-plugin/marketplace.json (missing or malformed on the selected channel). ` +
+            `Aborting to avoid a partial install with no skills.`,
+        );
+      }
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+    } else {
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    }
 
     if (!options.skipModuleInstaller) {
       await this.createModuleDirectories(moduleName, bmadDir, options);
@@ -304,41 +326,66 @@ class OfficialModules {
   }
 
   /**
-   * Install a module from a PluginResolver resolution result.
-   * Copies specific skill directories and places module-help.csv at the target root.
+   * Lay out a PluginResolver resolution on disk: copy each resolved skill
+   * directory (flattened by leaf name) into targetPath and place module-help.csv
+   * at the module root. Shared by both custom marketplace installs
+   * (installFromResolution) and official marketplace-plugin registry installs
+   * (install), so the two paths cannot drift.
    * @param {Object} resolved - ResolvedModule from PluginResolver
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} targetPath - Destination module directory (e.g. bmadDir/<code>)
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Installation options
+   * @param {Object} moduleConfig - Module configuration passed to copy filtering
    */
-  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(bmadDir, resolved.code);
-
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     await fs.ensureDir(targetPath);
 
-    // Copy each skill directory, flattened by leaf name
+    // Copy each skill directory, flattened by leaf name. Leaf names must be
+    // unique — two skills that flatten to the same directory would silently
+    // overwrite each other, so fail loud instead.
+    const seenLeaves = new Map();
     for (const skillPath of resolved.skillPaths) {
       const skillDirName = path.basename(skillPath);
+      if (seenLeaves.has(skillDirName)) {
+        throw new Error(
+          `Cannot install module '${resolved.code}': skill directories '${seenLeaves.get(skillDirName)}' and ` +
+            `'${skillPath}' share the leaf name '${skillDirName}' and would overwrite each other. ` +
+            `Skill directory names must be unique.`,
+        );
+      }
+      seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
     }
 
-    // Place module-help.csv at the module root
+    // Place module-help.csv at the module root.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
     if (resolved.moduleHelpCsvPath) {
-      // Strategies 1-4: copy the existing file
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategies 1-4: copy the existing file.
       await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     } else if (resolved.synthesizedHelpCsv) {
-      // Strategy 5: write synthesized content
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategy 5: write synthesized content.
       await fs.writeFile(helpTarget, resolved.synthesizedHelpCsv, 'utf8');
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     }
+  }
+
+  /**
+   * Install a module from a PluginResolver resolution result.
+   * Copies specific skill directories and places module-help.csv at the target root.
+   * @param {Object} resolved - ResolvedModule from PluginResolver
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Installation options
+   */
+  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(bmadDir, resolved.code);
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {

package/tools/installer/ui.js

@@ -133,7 +133,12 @@ class UI {
     for (const moduleId of installedModuleIds) {
       if (moduleId === 'core') continue;
       if (!selectedSet.has(moduleId) && !options.preserveUnselected) continue;
-      if (officialCodes.has(moduleId)) continue;
+      // Resolve a possibly-renamed module code (e.g. `bauto` -> `bmad-loop`)
+      // before checking availability, so a registry rename doesn't freeze
+      // the install here the way it would have prior to the alias support
+      // in ExternalModuleManager.getModuleByCode().
+      const canonicalId = await externalManager.resolveCanonicalCode(moduleId);
+      if (officialCodes.has(canonicalId)) continue;
 
       const customSource = await customMgr.findModuleSourceByCode(moduleId, { bmadDir });
       if (!customSource) {
@@ -944,25 +949,32 @@ class UI {
       }
     }
 
-    // Add external registry modules (skip built-in duplicates)
-    const externalRegistryModules = registryModules.filter((mod) => !mod.builtIn && !builtInCodes.has(mod.code));
+    // Add external registry modules (skip built-in duplicates and deprecated
+    // modules that are not already installed — deprecated modules stay visible
+    // only so existing users can continue to manage them).
+    const externalRegistryModules = registryModules.filter(
+      (mod) => !mod.builtIn && !builtInCodes.has(mod.code) && (!mod.deprecated || installedModuleIds.has(mod.code)),
+    );
     let externalRegistryEntries = [];
     if (externalRegistryModules.length > 0) {
       const spinner = await prompts.spinner();
       spinner.start('Checking latest module versions...');
 
       externalRegistryEntries = await Promise.all(
-        externalRegistryModules.map(async (mod) => ({
-          code: mod.code,
-          entry: await buildModuleEntry(
+        externalRegistryModules.map(async (mod) => {
+          const entry = await buildModuleEntry(
             mod.code,
             mod.name,
             mod.description,
             mod.defaultSelected,
             mod.url || null,
             mod.defaultChannel || null,
-          ),
-        })),
+          );
+          if (mod.deprecated && mod.deprecationMessage) {
+            entry.hint = entry.hint ? `${entry.hint} — ${mod.deprecationMessage}` : mod.deprecationMessage;
+          }
+          return { code: mod.code, entry };
+        }),
       );
 
       spinner.stop('Checked latest module versions.');