bmad-method 6.12.2 → 6.12.3-next.1

package/.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
       "displayName": "BMad Method Analyze Plan Build",
       "source": "./",
       "description": "Full-lifecycle AI development framework — agents and workflows for product analysis, planning, architecture, and implementation.",
-      "version": "6.12.2",
+      "version": "6.12.4",
       "author": {
         "name": "Brian (BMad) Madison"
       },

package/bmad-modules.yaml

@@ -9,7 +9,9 @@
 # Omit to inherit the installer's hardcoded default (stable).
 #
 # pin (optional) — a git tag to install instead of the channel. Use it when
-# newer releases no longer work with this installer. Only --pin overrides it.
+# newer releases no longer work with this installer. The installer skips the
+# channel picker for a pinned module and prints a notice. --pin and --next=CODE
+# override the pin; --channel and --all-* do not.
 #
 # deprecated (optional, default false) — when true, the module is hidden from
 # the installer picker UNLESS it is already installed (so existing users can

package/body.md

@@ -0,0 +1,17 @@
+Picking a channel in the picker is ignored when the module has a registry `pin`.
+The `tea` pin (v1.27.2) wins, and the manifest records `channel: pinned` with no message.
+
+`decideChannelForModule` checked `registryPin` before `--next=CODE`, and the picker never recorded a `stable` pick.
+
+New order: `--pin` > `--next=CODE` or picker stable > registry pin > `--channel`/`--all-*` > registry default > `stable`.
+
+- `channel-plan.js`: explicit per-module picks resolve before the registry pin. New `stableSet` holds a `stable` pick.
+- `ui.js`: `next` is gone from the install picker and from the update flow's channel review. A stable pick fills `stableSet`. A legacy install that tracks `main` moves to stable without a prompt.
+- Tests: "registry pin beats --next" splits into three cases. Picker-level tests drive the install and update flows, including the all-stable fast path that keeps the pin.
+
+`--yes`, the all-stable fast path and `--channel` still get the pin.
+
+`--next=CODE` stays for headless use.
+On 6.12 it now installs `main` for a pinned module, which fails for TEA v2+ because that layout needs the v7 installer.
+
+`npm run quality` passes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.12.2",
+  "version": "6.12.3-next.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/pr2.md

@@ -0,0 +1,11 @@
+On 6.12.3 the TEA channel picker offers stable, which resolves to v3.0.2.
+The install then fails with `Expected 'src/module.yaml' to exist in version v3.0.2`, because TEA v2+ uses the v7 layout.
+
+A module with a registry `pin` now skips the picker, in both the install and update flows.
+The installer prints `tea is pinned to v1.27.2. Newer versions need the v7 installer: npx skills add bmad-code-org/bmad-method-test-architecture-enterprise`.
+Unpinned modules keep the stable and pin choices.
+`--pin CODE=TAG` still overrides a registry pin.
+
+Tests drive the install and update flows with a pinned and an unpinned module.
+They fail without the change and pass with it.
+`npm run quality` passes.

package/tools/installer/core/installer.js

@@ -1474,7 +1474,7 @@ class Installer {
     // 'pinned' would trigger a stable-channel tag lookup at config-collection
     // time, burning GitHub API quota and potentially failing.
     const manifestData = await this.manifest.read(bmadDir);
-    const channelOptions = { global: null, nextSet: new Set(), pins: new Map(), warnings: [] };
+    const channelOptions = { global: null, nextSet: new Set(), stableSet: new Set(), pins: new Map(), warnings: [] };
     if (manifestData?.modulesDetailed) {
       const { fetchStableTags, classifyUpgrade, parseGitHubRepo } = require('../modules/channel-resolver');
       for (const entry of manifestData.modulesDetailed) {

package/tools/installer/modules/channel-plan.js

@@ -10,7 +10,8 @@
  *   3. Registry defaults (default_channel from bmad-modules.yaml)
  *   4. Hardcoded fallback 'stable'
  *
- * Precedence: --pin > --next=CODE > --channel (global) > registry default > 'stable'.
+ * Precedence: --pin > explicit per-module choice (--next=CODE, picker next/stable) > registry pin
+ * > --channel (global) > registry default > 'stable'.
  *
  * This module is pure. No prompts, no git, no filesystem.
  */
@@ -24,6 +25,7 @@ const VALID_CHANNELS = new Set(['stable', 'next']);
  * @returns {{
  *   global: 'stable'|'next'|null,
  *   nextSet: Set<string>,
+ *   stableSet: Set<string>,
  *   pins: Map<string, string>,
  *   warnings: string[]
  * }}
@@ -58,6 +60,9 @@ function parseChannelOptions(options = {}) {
     nextSet.add(trimmed);
   }
 
+  // Filled only by the interactive per-module picker (no CLI flag).
+  const stableSet = new Set();
+
   // --pin CODE=TAG (repeatable)
   const pins = new Map();
   for (const spec of options.pin || []) {
@@ -76,7 +81,7 @@ function parseChannelOptions(options = {}) {
   // headless installs with --next=/--pin for a community module don't hang.
   const acceptBypass = options.yes === true || options.acceptBypass === true;
 
-  return { global, nextSet, pins, warnings, acceptBypass };
+  return { global, nextSet, stableSet, pins, warnings, acceptBypass };
 }
 
 function normalizeChannel(raw, warnings, flagName) {
@@ -109,17 +114,20 @@ function parsePinSpec(spec) {
  *   source describes where the decision came from, for logging / debugging.
  */
 function decideChannelForModule({ code, channelOptions, registryDefault, registryPin }) {
-  const { global, nextSet, pins } = channelOptions || { nextSet: new Set(), pins: new Map() };
+  const { global, nextSet, stableSet, pins } = channelOptions || { nextSet: new Set(), stableSet: new Set(), pins: new Map() };
 
   if (pins && pins.has(code)) {
     return { channel: 'pinned', pin: pins.get(code), source: 'flag:--pin' };
   }
-  if (registryPin) {
-    return { channel: 'pinned', pin: registryPin, source: 'registry:pin' };
-  }
   if (nextSet && nextSet.has(code)) {
     return { channel: 'next', source: 'flag:--next' };
   }
+  if (stableSet && stableSet.has(code)) {
+    return { channel: 'stable', source: 'picker:stable' };
+  }
+  if (registryPin) {
+    return { channel: 'pinned', pin: registryPin, source: 'registry:pin' };
+  }
   if (global) {
     return { channel: global, source: 'flag:--channel' };
   }

package/tools/installer/ui.js

@@ -1931,12 +1931,6 @@ class UI {
    * Mutates channelOptions.pins and channelOptions.nextSet to reflect picker choices.
    */
   async _interactiveChannelGate({ options, channelOptions, selectedModules }) {
-    if (options.yes) return;
-    // If the user already declared their channel intent via flags, trust them
-    // and skip the gate.
-    const haveFlagIntent = channelOptions.global || channelOptions.nextSet.size > 0 || channelOptions.pins.size > 0;
-    if (haveFlagIntent) return;
-
     // Figure out which selected modules actually get a channel (externals only).
     // Bundled core/bmm and custom modules skip the picker.
     const externalManager = new ExternalModuleManager();
@@ -1949,6 +1943,20 @@ class UI {
     });
     if (channelSelectable.length === 0) return;
 
+    // A registry pin marks the newest version this installer can install.
+    // Offering stable or next there leads to a failed install, so say what is
+    // pinned (headless installs included) and skip the picker for those modules.
+    await this._announcePinnedModules(channelSelectable, externalByCode, channelOptions);
+
+    if (options.yes) return;
+    // If the user already declared their channel intent via flags, trust them
+    // and skip the gate.
+    const haveFlagIntent = channelOptions.global || channelOptions.nextSet.size > 0 || channelOptions.pins.size > 0;
+    if (haveFlagIntent) return;
+
+    const choosable = channelSelectable.filter((code) => !externalByCode.get(code).pin);
+    if (choosable.length === 0) return;
+
     const fastPath = await prompts.confirm({
       message: `Ready to install (all stable)? Pick "n" to customize channels or pin versions.`,
       default: true,
@@ -1958,7 +1966,7 @@ class UI {
     // Customize path: per-module picker.
     const { fetchStableTags, parseGitHubRepo } = require('./modules/channel-resolver');
 
-    for (const code of channelSelectable) {
+    for (const code of choosable) {
       const info = externalByCode.get(code);
       const repoUrl = info.url;
 
@@ -1980,15 +1988,12 @@ class UI {
         message: `${code}: choose a channel`,
         choices: [
           { name: stableLabel, value: 'stable' },
-          { name: 'next   (main HEAD \u2014 current development)', value: 'next' },
           { name: 'pin    (specific version)', value: 'pin' },
         ],
         default: 'stable',
       });
 
-      if (choice === 'next') {
-        channelOptions.nextSet.add(code);
-      } else if (choice === 'pin') {
+      if (choice === 'pin') {
         const pinValue = await prompts.text({
           message: `Enter a version tag for '${code}' (e.g. v1.6.0):`,
           validate: (value) => {
@@ -1998,8 +2003,25 @@ class UI {
           },
         });
         channelOptions.pins.set(code, String(pinValue).trim());
+      } else {
+        channelOptions.stableSet.add(code);
       }
-      // 'stable' is the default; nothing to record.
+    }
+  }
+
+  /**
+   * Tell the user which selected modules sit on a registry pin and how to get a
+   * newer version. Skips a module whose version the user set with --pin/--next.
+   */
+  async _announcePinnedModules(codes, externalByCode, channelOptions) {
+    const { parseGitHubRepo } = require('./modules/channel-resolver');
+    for (const code of codes) {
+      const info = externalByCode.get(code);
+      if (!info || !info.pin || info.builtIn) continue;
+      if (channelOptions.pins.has(code) || channelOptions.nextSet.has(code)) continue;
+      const repo = info.url ? parseGitHubRepo(info.url) : null;
+      const where = repo ? ` Newer versions need the v7 installer: npx skills add ${repo.owner}/${repo.repo}` : '';
+      await prompts.log.info(`${code} is pinned to ${info.pin}.${where}`);
     }
   }
 
@@ -2014,8 +2036,7 @@ class UI {
    *     frozen unless the user also passes `--pin CODE=NEW_TAG`.
    *   - On `next`: no prompt (pull HEAD).
    *   - On `pinned`: no prompt (stays pinned).
-   *   - No channel recorded and `version: null`: one-time migration prompt
-   *     ("Switch to stable / Keep on next").
+   *   - No channel recorded and `version: null`: moves to stable, no prompt.
    *
    * Decisions that freeze the current version are applied by adding a pin to
    * `channelOptions.pins` so downstream clone logic honors them.
@@ -2046,11 +2067,11 @@ class UI {
         const prev = existingByName.get(code);
         if (!prev) return false;
         const info = externalByCode.get(code);
-        return info && !info.builtIn;
+        return info && !info.builtIn && !info.pin;
       });
       if (existingWithChannel.length > 0) {
         reviewChannels = await prompts.confirm({
-          message: 'Review channel assignments (stable / next / pin) for your existing modules?',
+          message: 'Review channel assignments (stable / pin) for your existing modules?',
           default: false,
         });
       }
@@ -2066,12 +2087,25 @@ class UI {
       // their version is stapled to the CLI version, not a git tag. Skip
       // tag-API lookups for them; the "upgrade" mechanism is `npx bmad@X install`.
       if (info.builtIn) continue;
+      // A registry-pinned module stays on its pin; the channel logic below would
+      // move it to a version this installer cannot install. A version the user
+      // pinned earlier is kept.
+      if (info.pin) {
+        const decided = channelOptions.global || channelOptions.nextSet.has(code) || channelOptions.pins.has(code);
+        const keepsOwnPin = !decided && prev.channel === 'pinned' && prev.version && prev.version !== info.pin;
+        if (keepsOwnPin) {
+          channelOptions.pins.set(code, prev.version);
+        } else {
+          await this._announcePinnedModules([code], externalByCode, channelOptions);
+        }
+        continue;
+      }
 
       const repoUrl = info.url;
       const parsed = repoUrl ? parseGitHubRepo(repoUrl) : null;
 
       // Legacy migration: manifest carries no channel and a null/empty
-      // version. Offer the one-time pick between stable and next.
+      // version. The next channel is gone from the picker, so move it to stable.
       const recordedChannel = prev.channel || null;
       const needsMigration = !recordedChannel && (prev.version == null || prev.version === '');
       if (needsMigration) {
@@ -2079,15 +2113,7 @@ class UI {
           // Conservative headless default: stable.
           continue;
         }
-        const chosen = await prompts.select({
-          message: `${code}: your existing install tracks the main branch. Switch to stable releases (recommended for production), or keep on main?`,
-          choices: [
-            { name: 'Switch to stable', value: 'stable' },
-            { name: 'Keep on main (next)', value: 'next' },
-          ],
-          default: 'stable',
-        });
-        if (chosen === 'next') channelOptions.nextSet.add(code);
+        channelOptions.stableSet.add(code);
         continue;
       }
 
@@ -2105,9 +2131,6 @@ class UI {
         if (recordedChannel !== 'stable') {
           switchChoices.push({ name: 'Switch to stable (released version)', value: 'stable' });
         }
-        if (recordedChannel !== 'next') {
-          switchChoices.push({ name: 'Switch to next (main HEAD)', value: 'next' });
-        }
         switchChoices.push({ name: 'Pin to a specific version tag', value: 'pin' });
 
         const choice = await prompts.select({
@@ -2116,10 +2139,6 @@ class UI {
           default: 'keep',
         });
 
-        if (choice === 'next') {
-          channelOptions.nextSet.add(code);
-          continue;
-        }
         if (choice === 'pin') {
           const pinValue = await prompts.text({
             message: `Enter a version tag for '${code}' (e.g. v1.6.0):`,
@@ -2135,6 +2154,7 @@ class UI {
         if (choice === 'stable') {
           // Switch to stable: install at the top stable tag without an
           // upgrade-classification prompt (the user explicitly opted in).
+          channelOptions.stableSet.add(code);
           // Also warm the tag cache here so the actual clone step doesn't
           // need a second GitHub API call (can hit rate limits).
           if (parsed) {