ma-agents 3.16.0 → 3.17.0-beta.0

package/lib/profile.js

@@ -19,6 +19,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const chalk = require('chalk');
 
 const MANIFEST_FILE = '.ma-agents.json';
 const VALID_PROFILES = ['on-prem', 'standard'];
@@ -211,6 +212,201 @@ function setBmadModules(projectRoot, modules) {
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
 
+/**
+ * Story 30.4 (FR245/FR246, NFR49) — generic one-time notice tracking.
+ *
+ * Notices are keyed by an arbitrary string id and persisted under a `notices`
+ * object in the project-root `.ma-agents.json` (`{ notices: { <id>: true } }`).
+ * This mirrors the `profile`/`bmadModules` field-ownership pattern above:
+ * read/write is scoped to this module, bootstrap-on-absence uses the same
+ * profile-only `bootstrapRootManifest()` shape, and no other field is
+ * disturbed. A notice is meant to be shown to the user exactly once, ever,
+ * regardless of how many times install/update subsequently runs.
+ */
+
+/**
+ * Returns true if the given notice id has already been recorded as shown.
+ * Missing/malformed manifest, or a manifest with no matching entry, both
+ * return false (never shown) — mirrors getProfile's non-throwing contract.
+ */
+function hasShownNotice(projectRoot, noticeId) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return false;
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  if (!manifest || typeof manifest !== 'object') return false;
+  return !!(manifest.notices && manifest.notices[noticeId] === true);
+}
+
+/**
+ * Persists that the given notice id has been shown, preserving all other
+ * `.ma-agents.json` fields (profile, bmadModules, profileHistory, ...).
+ * Bootstraps a profile-only root manifest if none exists yet (mirrors
+ * setProfile/setBmadModules).
+ */
+function markNoticeShown(projectRoot, noticeId) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  let manifest;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = null;
+    }
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    manifest = bootstrapRootManifest();
+  }
+  // Guard: `typeof null === 'object'` is already caught by `!manifest.notices`,
+  // but `typeof [] === 'object'` is NOT — a foreign tool that wrote
+  // `notices: []` would otherwise keep an array here, and a named property set
+  // on an array is dropped by JSON.stringify, silently defeating the
+  // show-once guarantee. Reject any non-plain-object shape.
+  if (!manifest.notices || typeof manifest.notices !== 'object' || Array.isArray(manifest.notices)) {
+    manifest.notices = {};
+  }
+  manifest.notices[noticeId] = true;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Story 30.7 (FR242) — persisted custom-marketplace source + selection.
+ *
+ * Stored under the `customMarketplace` key (a single object, NOT nested under
+ * `bmadModules`/`profile`) so a future multi-source design can introduce a
+ * sibling array field (e.g. `customMarketplaceSources`) without a breaking
+ * migration of this one. v1 supports exactly ONE marketplace source, per
+ * FR242 / architecture Decision P5-8.
+ *
+ * Shape:
+ *   {
+ *     source: string,            // original user input (local path or Git URL)
+ *     sourceUrl: string|null,    // resolved clone URL (Git sources) or null (local)
+ *     mode: 'discovery'|'direct',
+ *     selectedCodes: string[],
+ *     sha: string|null,          // resolved commit SHA pin (Git-URL sources only)
+ *     updatedAt: string,         // ISO timestamp of the last persist
+ *   }
+ */
+
+/**
+ * Reads the persisted custom-marketplace selection from `.ma-agents.json`.
+ * Returns undefined if the file is absent/malformed or the `customMarketplace`
+ * field is missing/malformed — mirrors getBmadModules' non-throwing contract.
+ */
+function getCustomMarketplaceSelection(projectRoot) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  if (!manifest || typeof manifest !== 'object') return undefined;
+  const entry = manifest.customMarketplace;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return undefined;
+  if (typeof entry.source !== 'string' || !entry.source) return undefined;
+  if (!Array.isArray(entry.selectedCodes)) return undefined;
+  return entry;
+}
+
+/**
+ * Persists the custom-marketplace source + selection into `.ma-agents.json`,
+ * preserving all other fields (profile, bmadModules, notices, ...). Creates
+ * the file via the standard profile-only bootstrap path if absent (mirrors
+ * setProfile/setBmadModules). Stamps `updatedAt` with the current time.
+ *
+ * @param {string} projectRoot
+ * @param {Object} entry
+ * @param {string} entry.source - Original source string (local path or Git URL).
+ * @param {string|null} [entry.sourceUrl] - Resolved clone URL (Git sources) or null.
+ * @param {'discovery'|'direct'} entry.mode
+ * @param {string[]} entry.selectedCodes
+ * @param {string|null} [entry.sha] - Commit SHA of the LAST-INSTALLED marketplace
+ *   state (Git-URL sources only; null for local paths). This is INFORMATIONAL —
+ *   it records what was installed, not a lock. Per FR242/NFR72, `update`
+ *   deliberately re-enumerates the source ref and floats to remote HEAD to offer
+ *   newly-published extensions; it does NOT check out this SHA. reconcile surfaces
+ *   this last-installed SHA and the float-to-HEAD behavior (see
+ *   reconcileCustomMarketplaceOnUpdate) but never pins/reverts to it.
+ */
+function setCustomMarketplaceSelection(projectRoot, entry) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('setCustomMarketplaceSelection expects an entry object');
+  }
+  if (typeof entry.source !== 'string' || !entry.source) {
+    throw new Error('setCustomMarketplaceSelection requires a non-empty "source" string');
+  }
+  if (entry.mode !== 'discovery' && entry.mode !== 'direct') {
+    throw new Error(`setCustomMarketplaceSelection requires mode 'discovery' or 'direct' (got ${JSON.stringify(entry.mode)})`);
+  }
+  if (!Array.isArray(entry.selectedCodes)) {
+    throw new Error('setCustomMarketplaceSelection requires "selectedCodes" to be an array');
+  }
+
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  let manifest;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = null;
+    }
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    manifest = bootstrapRootManifest();
+  }
+
+  manifest.customMarketplace = {
+    source: entry.source,
+    sourceUrl: entry.sourceUrl ?? null,
+    mode: entry.mode,
+    selectedCodes: [...new Set(entry.selectedCodes.filter(c => typeof c === 'string' && c.length > 0))],
+    sha: entry.sha ?? null,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+const DEMERZEL_DEPRECATION_NOTICE_ID = 'demerzel-deprecation';
+
+/**
+ * FR245/FR246 — idempotent one-time deprecation notice for the Demerzel
+ * (ML Scientist) agent. Prints an informational message the first time it is
+ * called for a given project root, then persists a `shown` flag so every
+ * subsequent call (any future install/update run) is a silent no-op.
+ *
+ * Deliberately does NOT touch any already-installed `ma-agent-ml`/`ml-*`
+ * content — that is the job of `migrateRetiredSkills()` for genuinely
+ * retired/renamed skills, and `ma-agent-ml`/`ml-*` are intentionally excluded
+ * from that sweep (NFR49 — existing installs are non-destructively preserved).
+ * Names no replacement target (FR246 — no in-tool migration).
+ *
+ * @param {string} projectRoot
+ * @returns {boolean} true if the notice was printed on this call, false if
+ *   it had already been shown previously (no-op).
+ */
+function showDemerzelDeprecationNoticeOnce(projectRoot) {
+  if (hasShownNotice(projectRoot, DEMERZEL_DEPRECATION_NOTICE_ID)) {
+    return false;
+  }
+  console.log(chalk.yellow(
+    '\n  Notice: the Demerzel (ML Scientist) agent - ma-agent-ml plus the 12 ml-*\n' +
+    '  workflow skills - is deprecated and is no longer installed by default for\n' +
+    '  new projects (FR244-FR247). Already-installed content on this or any other\n' +
+    '  project is left untouched; no action is required. Teams that still need ML\n' +
+    '  workflows can install a replacement from a custom BMAD marketplace source\n' +
+    '  (see --bmad-custom-source). This message is shown once.\n'
+  ));
+  markNoticeShown(projectRoot, DEMERZEL_DEPRECATION_NOTICE_ID);
+  return true;
+}
+
 module.exports = {
   getProfile,
   setProfile,
@@ -218,4 +414,9 @@ module.exports = {
   clearProfile,
   getBmadModules,
   setBmadModules,
+  hasShownNotice,
+  markNoticeShown,
+  showDemerzelDeprecationNoticeOnce,
+  getCustomMarketplaceSelection,
+  setCustomMarketplaceSelection,
 };

package/lib/skill-authoring.js

@@ -405,7 +405,9 @@ async function handleSetMandatory(args) {
 
 // ─── Story 3.4: BMAD Persona Customization Tooling ───────────────────────────
 
-const CUSTOM_AGENTS = ['bmm-sre', 'bmm-devops', 'bmm-cyber', 'bmm-qa', 'bmm-demerzel'];
+// Story 30.4 / FR244-FR247: 'bmm-demerzel' removed — Demerzel is deprecated for
+// new installs (see lib/agents.js for the full rationale).
+const CUSTOM_AGENTS = ['bmm-sre', 'bmm-devops', 'bmm-cyber', 'bmm-qa'];
 const BUILTIN_AGENTS = ['bmm-pm', 'bmm-architect', 'bmm-dev', 'bmm-sm', 'bmm-tech-writer', 'bmm-ux-designer'];
 
 const MANDATORY_CRITICAL_ACTIONS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.16.0",
+  "version": "3.17.0-beta.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bmad-version-bump.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js",
     "build:plugin": "node scripts/build-plugin.js",
     "build:atlas": "node scripts/build-atlas.js",
@@ -32,7 +32,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "bmad-method": "6.9.0",
+    "bmad-method": "6.10.0",
     "chalk": "^4.1.2",
     "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.1",

package/scripts/build-bmad-cache.js

@@ -47,18 +47,44 @@ const REGISTRY_CANDIDATES = [
   { parts: ['tools', 'cli', 'external-official-modules.yaml'], schema: 'legacy' },
 ];
 
-// The set of modules ma-agents bundles for offline installs. At v6.8.0 these
-// are exactly the `type: bmad-org` registry entries. The fail-loud guard
-// (NFR56) treats a resolved set SMALLER than this as a thin-cache failure —
-// the registry path has moved twice, so silent degradation is a recurring
-// risk that must abort the build rather than ship an incomplete cache.
+// The set of modules ma-agents bundles for offline installs — the CLOSED
+// ALLOWLIST. `normalizeModules()` includes ONLY these codes; every other
+// registry entry is dropped, regardless of its `type`. This is the load-bearing
+// safety posture (P5-8 / FR235): at v6.10.0 the registry gained `bmad-loop`
+// (`type: bmad-org`, `marketplace-plugin: true`, air-gap-hostile) and marked
+// `bmad-automator` `deprecated: true`. An open-by-default "keep every
+// `type: bmad-org`" filter would silently force-bundle `bmad-loop` (and any
+// FUTURE plain `bmad-org` module) onto air-gapped machines. Closing to this
+// allowlist means new/renamed/re-flagged upstream modules FAIL CLOSED (excluded)
+// rather than fail open.
 const KNOWN_BUNDLED_MODULES = ['tea', 'bmb', 'cis', 'gds', 'wds'];
 
-// Registry `type` values that mark a module for bundling. `bmad-org` modules
-// are first-party expansions ma-agents clones; `experimental` (e.g. automator)
-// is deliberately excluded from the offline bundle.
+// The registry `type` first-party expansions carry. Retained for diagnostics
+// and for the shape-flip assertion below (an allowlisted module is expected to
+// stay a plain `bmad-org` module). It is NO LONGER the include criterion — the
+// allowlist above is. `experimental` (automator) and `marketplace-plugin`
+// modules (bmad-loop) are excluded simply by not being on the allowlist.
 const BUNDLED_MODULE_TYPE = 'bmad-org';
 
+// Registry traits that DISQUALIFY a module from the offline bundle. If a module
+// that IS on the allowlist ever starts carrying one of these (an upstream
+// shape/status flip on a module we bundle), the build HALTS rather than silently
+// shipping it — see the assertion in normalizeModules(). `bmad-loop` carries
+// `marketplace-plugin: true`; deprecated modules carry `deprecated: true`.
+const DISQUALIFYING_FLAGS = ['marketplace-plugin', 'deprecated'];
+
+/**
+ * True when a parsed registry flag reads as boolean-true. The line parser
+ * stores YAML scalars as strings (`'true'`), but unit callers may pass a real
+ * boolean, so accept both. Anything else (absent, `'false'`, other) is false.
+ *
+ * @param {*} value Raw flag value off a parsed module entry.
+ * @returns {boolean}
+ */
+function isFlagTrue(value) {
+  return value === true || String(value).trim().toLowerCase() === 'true';
+}
+
 /**
  * Locate the bmad-method package on disk. Abort cleanly if missing so the
  * caller gets an actionable "run npm install" message instead of a MODULE_NOT_FOUND
@@ -179,20 +205,29 @@ function parseModulesYaml(content) {
  * Normalize parsed module entries into a uniform cache-ready shape:
  *   { code, url, name, branch }
  *
+ * CLOSED-BY-DEFAULT (FR235). The filter is an ALLOWLIST: an entry survives ONLY
+ * if its `code` is in KNOWN_BUNDLED_MODULES (tea, bmb, cis, gds, wds). Every
+ * other registry entry is dropped no matter its `type` — so a NEW upstream
+ * module (even a plain `type: bmad-org` one carrying neither disqualifying
+ * flag), `bmad-loop` (`marketplace-plugin: true`), the deprecated
+ * `bmad-automator`, `experimental` modules, and the built-in `bmm`/`core` are
+ * ALL excluded by default. This replaces the prior open-by-default posture
+ * ("keep every `type: bmad-org`, subtract known-bad"), which would silently
+ * bundle any future first-party module the moment it appeared upstream.
+ *
+ * SHAPE-FLIP HALT. For each entry that IS on the allowlist, assert it carries
+ * NONE of DISQUALIFYING_FLAGS (`marketplace-plugin: true` / `deprecated: true`).
+ * If a bundled module ever flips shape/status upstream, THROW — a bundled
+ * module turning into a marketplace-plugin or getting deprecated must be
+ * re-reviewed by a maintainer, never shipped silently.
+ *
  * - Requires both `code` and `url`.
- * - Keeps ONLY `type: bmad-org` modules (tea, bmb, cis, gds, wds) and drops
- *   everything else. This replaces the pre-6.8.0 `built_in` exclusion: the
- *   relocated registry no longer carries a `built_in` flag and instead tags
- *   each module with a `type`. `type: experimental` (e.g. `automator`) is
- *   excluded from the offline bundle; `bmm`/`core` are first-party modules
- *   that ship inside the npm package and are absent from the registry, so they
- *   are dropped here too (no `bmad-org` type → filtered out). There is NO
- *   `wds`-retired/skip path — `wds` is an active `bmad-org` clone at 6.8.0.
- * - Defaults `branch` to `main` when absent (the 6.8.0 schema omits it).
+ * - Defaults `branch` to `main` when absent (the 6.8.0+ schema omits it).
  * - Passes the URL through verbatim (git accepts both `repo` and `repo.git`).
  *
  * @param {Array<Object>} raw Entries from parseModulesYaml().
  * @returns {Array<{code: string, url: string, name: string, branch: string}>}
+ * @throws {Error} if an allowlisted entry carries a disqualifying flag.
  */
 // Module `code` values are used as directory names under lib/bmad-cache.
 // Reject anything that could escape the cache dir or inject shell characters;
@@ -200,25 +235,65 @@ function parseModulesYaml(content) {
 const MODULE_CODE_PATTERN = /^[a-zA-Z0-9_-]+$/;
 
 function normalizeModules(raw) {
+  const allowlist = new Set(KNOWN_BUNDLED_MODULES);
   return raw
     .filter(m => m.code && m.url)
-    .filter(m => {
-      // Bundle only `type: bmad-org`. Compare case-insensitively and trim so
-      // minor upstream whitespace/casing drift cannot silently drop a module.
-      const type = String(m.type || '').trim().toLowerCase();
-      return type === BUNDLED_MODULE_TYPE;
-    })
+    // CLOSED allowlist: include ONLY the known bundled codes. Anything not on
+    // the allowlist fails closed (excluded) — the safety-critical inversion.
+    .filter(m => allowlist.has(m.code))
     .filter(m => {
       if (MODULE_CODE_PATTERN.test(m.code)) return true;
       console.warn(`  ⚠  Skipping module with invalid code "${m.code}" (must match [a-zA-Z0-9_-]+)`);
       return false;
     })
-    .map(m => ({
-      code: m.code,
-      url: m.url,
-      name: m.name || m.key,
-      branch: m.branch || 'main',
-    }));
+    .map(m => {
+      // Shape-flip halt: a module we DO bundle must not have turned into a
+      // marketplace-plugin or been deprecated upstream. Fail loud, don't ship.
+      const tripped = DISQUALIFYING_FLAGS.filter(flag => isFlagTrue(m[flag]));
+      if (tripped.length > 0) {
+        throw new Error(
+          `Allowlisted bundled module "${m.code}" now carries disqualifying flag(s): ` +
+          `${tripped.map(f => `${f}: true`).join(', ')}. A bundled module changing shape/status ` +
+          `upstream must be re-reviewed before shipping (FR235) — refusing to build. ` +
+          `Remove it from KNOWN_BUNDLED_MODULES in scripts/build-bmad-cache.js, or coordinate ` +
+          `the upstream change, then rebuild.`
+        );
+      }
+      return {
+        code: m.code,
+        url: m.url,
+        name: m.name || m.key,
+        branch: m.branch || 'main',
+      };
+    });
+}
+
+/**
+ * Compare a RESOLVED bundle set (the codes normalizeModules() kept) against the
+ * closed allowlist and report both directions of drift (NFR73 two-sided
+ * set-EQUALITY). The resolved set must EQUAL the allowlist exactly.
+ *
+ * - `missing`: allowlisted codes the registry did NOT resolve — the thin-cache
+ *   case (a bundled module vanished / the registry relocated / a downgrade).
+ * - `extra`: resolved codes NOT on the allowlist — a silent upstream addition
+ *   (e.g. `bmad-loop`) that must never be force-bundled. Under the closed
+ *   allowlist filter this is normally empty; the check is defense-in-depth so a
+ *   future loosening of the filter can never ship an over-broad cache silently.
+ *
+ * Computed on the resolved/filtered set — NOT the final manifest keys, which
+ * the incremental-retention path deliberately augments with retired-upstream
+ * modules that are not on the allowlist (see AC #7 retention in main()).
+ *
+ * @param {Iterable<string>|Set<string>} resolvedCodes Codes kept by normalize.
+ * @param {Array<string>} [allowlist=KNOWN_BUNDLED_MODULES]
+ * @returns {{ missing: string[], extra: string[] }} Sorted; both empty = equal.
+ */
+function diffBundleSet(resolvedCodes, allowlist = KNOWN_BUNDLED_MODULES) {
+  const allow = new Set(allowlist);
+  const resolved = resolvedCodes instanceof Set ? resolvedCodes : new Set(resolvedCodes);
+  const missing = [...allow].filter(code => !resolved.has(code)).sort();
+  const extra = [...resolved].filter(code => !allow.has(code)).sort();
+  return { missing, extra };
 }
 
 function loadModuleDefinitions() {
@@ -371,12 +446,15 @@ function main() {
 
   const { modules, schema } = loadModuleDefinitions();
 
-  // Thin-cache fail-loud guard (NFR56). The registry path has moved twice;
-  // the real risk is no longer "zero modules" but the path moving again and
-  // the reader silently resolving FEWER than the known bundled set. Treat a
-  // deficient set as a hard error and abort BEFORE writing any manifest — a
-  // partial/empty cache-manifest.json would otherwise ship a broken offline
-  // bundle that "looks" successful.
+  // Two-sided set-EQUALITY fail-loud guard (NFR73, strengthening NFR56). The
+  // resolved bundle set must EQUAL the known allowlist — abort on a set that is
+  // either SMALLER (thin cache: a bundled module vanished / the registry moved /
+  // a downgrade below 6.8.0) OR LARGER (a silent upstream addition such as
+  // bmad-loop that must never be force-bundled). Abort BEFORE writing any
+  // manifest — a partial or over-broad cache-manifest.json would otherwise ship
+  // a broken/air-gap-hostile offline bundle that "looks" successful. Computed on
+  // the RESOLVED set (not the final manifest keys — the retention path below
+  // augments the manifest with non-allowlist retired modules by design).
   const resolvedCodes = new Set(modules.map(m => m.code));
 
   // Duplicate-code guard. Two registry entries sharing a `code` would clone
@@ -395,15 +473,18 @@ function main() {
     process.exit(1);
   }
 
-  const missing = KNOWN_BUNDLED_MODULES.filter(code => !resolvedCodes.has(code));
-  if (missing.length > 0) {
-    console.error('Error: registry resolved a thin module set — refusing to build a partial cache.');
-    console.error(`  Expected at least: ${KNOWN_BUNDLED_MODULES.join(', ')}`);
-    console.error(`  Resolved (type: ${BUNDLED_MODULE_TYPE}): ${[...resolvedCodes].join(', ') || '(none)'}`);
-    console.error(`  Missing: ${missing.join(', ')}`);
+  const { missing, extra } = diffBundleSet(resolvedCodes);
+  if (missing.length > 0 || extra.length > 0) {
+    console.error('Error: resolved bundle set does not EQUAL the known allowlist — refusing to build a');
+    console.error('  partial or over-broad cache (thin module set / silent upstream addition).');
+    console.error(`  Allowlist (KNOWN_BUNDLED_MODULES): ${KNOWN_BUNDLED_MODULES.join(', ')}`);
+    console.error(`  Resolved: ${[...resolvedCodes].sort().join(', ') || '(none)'}`);
+    console.error(`  Missing: ${missing.join(', ') || '(none)'}   (thin cache — a bundled module vanished/relocated)`);
+    console.error(`  Extra:   ${extra.join(', ') || '(none)'}   (silent upstream addition — must not be force-bundled)`);
     console.error('  Likely cause: bmad-method was downgraded below 6.8.0, the registry layout moved');
-    console.error('  again, or a bundled module was renamed/retired upstream. Update REGISTRY_CANDIDATES,');
-    console.error('  the type filter, or KNOWN_BUNDLED_MODULES in scripts/build-bmad-cache.js to match.');
+    console.error('  again, or a bundled module was added/renamed/retired upstream. Update');
+    console.error('  REGISTRY_CANDIDATES or KNOWN_BUNDLED_MODULES in scripts/build-bmad-cache.js to match —');
+    console.error('  and, for an EXTRA module, confirm it is safe to bundle offline before allowlisting it.');
     process.exit(1);
   }
   console.log(`Found ${modules.length} modules: ${modules.map(m => m.code).join(', ')}`);
@@ -587,9 +668,12 @@ if (require.main === module) {
   module.exports = {
     parseModulesYaml,
     normalizeModules,
+    diffBundleSet,
+    isFlagTrue,
     locateRegistry,
     KNOWN_BUNDLED_MODULES,
     BUNDLED_MODULE_TYPE,
+    DISQUALIFYING_FLAGS,
     REGISTRY_CANDIDATES,
   };
 }

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

@@ -1,59 +0,0 @@
----
-name: ma-agent-ml
-description: Demerzel (ML Scientist) — Machine Learning Scientist specializing in falsifiable hypothesis validation and failure-cost analysis
----
-
-# Agent: Demerzel — ML Scientist
-
-You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
-
-## Persona
-- **Role:** Machine Learning Scientist specializing in falsifiable hypothesis validation and failure-cost analysis.
-- **Identity:** Named after Eto Demerzel from Isaac Asimov's Foundation series. Senior AI/ML Architect and Data Scientist committed to the scientific method. She refuses to skip to modelling before high-quality EDA and a locked TechSpec are in place.
-- **Communication Style:** Professional, precise, and hypothesis-driven. Uses statistical terminology correctly. Prioritizes failure modes and their domain costs.
-- **Principles:**
-  - Scientific Rigor: No modelling without EDA. No modelling without a locked TechSpec.
-  - Dependency Integrity: Always use uv for project reproducibility.
-  - Failure Focus: Capture every failure mode and its domain cost.
-
-## Activation Sequence
-1. Load persona from this agent skill (already in context)
-2. Load and read {project-root}/_bmad/bmm/config.yaml — store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}. If config not loaded, STOP and report error to user.
-3. Remember: user's name is {user_name}
-4. Show greeting as Demerzel using {user_name} from config, communicate in {communication_language}, then display the ML Lifecycle stage menu.
-5. Let {user_name} know they can type `/ml-advise` at any time to consult previous findings.
-6. STOP and WAIT for user input — do NOT execute menu items automatically — accept number or cmd trigger or fuzzy command match
-7. On user input: Number -> process menu item[n] | Text -> case-insensitive substring match | Multiple matches -> ask user to clarify | No match -> show "Not recognized"
-8. When processing a menu item: load the referenced skill and follow its instructions
-
-### Rules
-- ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.
-- Stay in character until exit selected.
-- After each stage approval, commit all new/modified files under `_bmad-output/` with: `git add _bmad-output/ && git commit -m "feat(ml): stage [N] complete - [stage-name]"`
-- Never commit before explicit user approval — the commit is the confirmation receipt.
-- Display menu items as the item dictates and in the order given.
-
-## Menu
-| # | Cmd | Action | Trigger | Skill |
-|---|-----|--------|---------|-------|
-| 1 | MH | Redisplay Menu Help | "menu", "help" | _(built-in)_ |
-| 2 | CH | Chat with Demerzel about ML | "chat", "ml" | _(built-in)_ |
-| 3 | MLI | ML Ideation & PRD | "ideation", "prd" | ml-ideation |
-| 4 | MLE | ML EDA & Research Thesis | "eda", "thesis" | ml-eda |
-| 5 | MLA | ML Architecture Design | "architecture", "design" | ml-architecture |
-| 6 | MLD | ML Detailed Design | "detailed", "breakdown" | ml-detailed-design |
-| 7 | MLS | ML TechSpec (Lock Params) | "techspec", "lock" | ml-techspec |
-| 8 | MLNF| ML Infra & Smoke Test | "infra", "smoke" | ml-infra |
-| 9 | MLX | ML Experiment Execution | "experiment", "train" | ml-experiment |
-| 10 | MLAN| ML Analysis (vs TechSpec) | "analysis", "results" | ml-analysis |
-| 11 | MLH | ML HPO (Tuning) | "hpo", "tuning", "hyperparameter" | ml-hparam |
-| 12 | MLR | ML Iterative Revision | "revision", "iterate" | ml-revision |
-| 13 | MLAD| ML Advise & Search | "advise", "search", "findings" | ml-advise |
-| 14 | MLRT| ML Retrospective | "retro", "learnings" | ml-retrospective |
-| 15 | DA | Dismiss Demerzel | "dismiss", "exit" | _(built-in)_ |
-
-## Critical Actions
-1. Read the skills MANIFEST at {project-root}/_bmad/skills/demerzel/MANIFEST.yaml
-2. For each skill marked always_load: true, read the skill file completely
-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-ml/bmad-skill-manifest.yaml

@@ -1,11 +0,0 @@
-type: agent
-name: ma-agent-ml
-displayName: Demerzel
-title: ML Scientist
-icon: "\U0001F9EA"
-capabilities: "Machine Learning Ideation, EDA, Architecture, Training, Analysis, Retrospective"
-role: "Machine Learning Scientist specializing in falsifiable hypothesis validation and failure-cost analysis."
-identity: "Named after Eto Demerzel from Isaac Asimov's Foundation series. Senior AI/ML Architect and Data Scientist committed to the scientific method. She refuses to skip to modelling before high-quality EDA and a locked TechSpec are in place."
-communicationStyle: "Professional, precise, and hypothesis-driven. Uses statistical terminology correctly. Prioritizes failure modes and their domain costs."
-principles: "No modelling without EDA. Lock params in TechSpec before training. Focus on failure-cost attribution. Use uv for reproducibility."
-module: ma-skills