ma-agents 3.12.3 → 3.13.1

package/lib/templates/instruction-block-onprem.template.md

@@ -1,86 +1,86 @@
-## On-Prem / Local-LLM Guardrails
-
-These rules apply ONLY when this project is installed with `profile: on-prem`.
-They are appended to the universal block by the composer in `lib/installer.js`.
-Local LLMs (Nemotron, Qwen, DeepSeek, Llama-3, etc. served via vLLM, Ollama, or
-TGI) fail in patterns cloud LLMs rarely exhibit — the rules below pin those
-failure modes down explicitly. Keep these rules verbatim in every response
-context where tool use is possible.
-
-### Reasoning mode: `/no_think` on planning-phase prompts
-
-Local reasoning-capable models (Nemotron-variants and similar) default to
-chain-of-thought reasoning that bloats planning-phase prompts with internal
-deliberation the operator does not need to read. Prepend the literal token
-`/no_think` as the first line of any planning-phase system prompt or user turn
-you compose. The token is consumed by the serving layer and suppresses the
-model's reasoning trace on that turn.
-
-- Planning-phase turns (PM, Architect, Tech Lead): begin the turn with
-  `/no_think` on its own line. Reasoning-mode OFF.
-- Implementation-phase turns (Dev): omit `/no_think`. Reasoning-mode ON is
-  desirable for stepwise code synthesis and debugging.
-- Review / QA turns: omit `/no_think` when the review benefits from explicit
-  reasoning (root-cause analysis). Include `/no_think` for mechanical checks
-  (lint, style, formatting).
-
-If the downstream serving layer does not recognize `/no_think`, it is a no-op
-text token — safe to include unconditionally on planning turns.
-
-### No writes to `~/.claude/` or any user home directory
-
-Local LLMs frequently hallucinate paths under `~/.claude/`, `~/.cache/`,
-`~/Library/`, or `%APPDATA%` — imitating patterns learned from Claude Code and
-Cursor training data. These paths are OUTSIDE the project and cross-contaminate
-other projects on the same machine.
-
-- NEVER create, write, or modify files under `~/.claude/`, `~/.cache/`,
-  `~/Library/`, `~/AppData/`, `%APPDATA%`, or any path that resolves outside
-  the current project directory.
-- All project artifacts — code, configuration, logs, scratch notes, and agent
-  state — MUST land under the current working directory (the project root) or
-  an explicitly-named subdirectory thereof.
-- When a tool call appears to target a home-directory path, refuse the write
-  and respond in text explaining the violation. Ask the user for an explicit
-  in-project path before proceeding.
-
-### No `str_replace_editor` or Claude Code-specific tools
-
-Local LLMs hallucinate Anthropic-proprietary tools — most commonly
-`str_replace_editor`, `text_editor_20241022`, and `computer_use_preview` — that
-do NOT exist outside the Anthropic API. Calling them against a local-LLM
-serving layer produces a tool-not-found error or, worse, a silent no-op.
-
-- Do NOT emit tool calls named `str_replace_editor`, `text_editor_*`,
-  `computer_use_*`, or any other tool whose name includes `str_replace_editor`
-  or matches Anthropic-specific tool schemas.
-- Use only tools enumerated in the active tool manifest (`MANIFEST.yaml`) or
-  the IDE's native tool surface (Roo Code, Cline, OpenCode native tools).
-- When you want to edit a file, use the native file-write tool of the active
-  agent — not `str_replace_editor`. If unsure what tool is available, list
-  available tools or ask the user before emitting a tool call.
-
-### Per-phase reasoning and sampling guidance
-
-Local LLMs require tighter sampling control than cloud LLMs. Use these defaults
-unless the serving layer overrides them.
-
-- **Planning phase (PM, Architect, Tech Lead):**
-  - Reasoning: OFF (`/no_think` prepended).
-  - Temperature: low (0.0 – 0.3). Planning artifacts should be deterministic
-    and reproducible.
-  - Top-p: 0.9 or unset. Top-k: unset.
-  - Max tokens: generous (8k+) — planning documents are long.
-- **Implementation phase (Dev):**
-  - Reasoning: ON (omit `/no_think`).
-  - Temperature: moderate (0.3 – 0.6). Code synthesis benefits from controlled
-    exploration but not creative rewriting.
-  - Top-p: 0.95 or unset. Top-k: unset.
-  - Max tokens: generous (8k+) — full-file rewrites are common.
-- **Review / QA phase:**
-  - Reasoning: ON for root-cause analysis; OFF for mechanical checks.
-  - Temperature: low (0.0 – 0.2). Reviews should be deterministic.
-
-If the serving layer applies its own sampler defaults, the per-phase guidance
-above is advisory — but the phase boundary and `/no_think` placement are
-load-bearing and MUST be honored on every turn.
+## On-Prem / Local-LLM Guardrails
+
+These rules apply ONLY when this project is installed with `profile: on-prem`.
+They are appended to the universal block by the composer in `lib/installer.js`.
+Local LLMs (Nemotron, Qwen, DeepSeek, Llama-3, etc. served via vLLM, Ollama, or
+TGI) fail in patterns cloud LLMs rarely exhibit — the rules below pin those
+failure modes down explicitly. Keep these rules verbatim in every response
+context where tool use is possible.
+
+### Reasoning mode: `/no_think` on planning-phase prompts
+
+Local reasoning-capable models (Nemotron-variants and similar) default to
+chain-of-thought reasoning that bloats planning-phase prompts with internal
+deliberation the operator does not need to read. Prepend the literal token
+`/no_think` as the first line of any planning-phase system prompt or user turn
+you compose. The token is consumed by the serving layer and suppresses the
+model's reasoning trace on that turn.
+
+- Planning-phase turns (PM, Architect, Tech Lead): begin the turn with
+  `/no_think` on its own line. Reasoning-mode OFF.
+- Implementation-phase turns (Dev): omit `/no_think`. Reasoning-mode ON is
+  desirable for stepwise code synthesis and debugging.
+- Review / QA turns: omit `/no_think` when the review benefits from explicit
+  reasoning (root-cause analysis). Include `/no_think` for mechanical checks
+  (lint, style, formatting).
+
+If the downstream serving layer does not recognize `/no_think`, it is a no-op
+text token — safe to include unconditionally on planning turns.
+
+### No writes to `~/.claude/` or any user home directory
+
+Local LLMs frequently hallucinate paths under `~/.claude/`, `~/.cache/`,
+`~/Library/`, or `%APPDATA%` — imitating patterns learned from Claude Code and
+Cursor training data. These paths are OUTSIDE the project and cross-contaminate
+other projects on the same machine.
+
+- NEVER create, write, or modify files under `~/.claude/`, `~/.cache/`,
+  `~/Library/`, `~/AppData/`, `%APPDATA%`, or any path that resolves outside
+  the current project directory.
+- All project artifacts — code, configuration, logs, scratch notes, and agent
+  state — MUST land under the current working directory (the project root) or
+  an explicitly-named subdirectory thereof.
+- When a tool call appears to target a home-directory path, refuse the write
+  and respond in text explaining the violation. Ask the user for an explicit
+  in-project path before proceeding.
+
+### No `str_replace_editor` or Claude Code-specific tools
+
+Local LLMs hallucinate Anthropic-proprietary tools — most commonly
+`str_replace_editor`, `text_editor_20241022`, and `computer_use_preview` — that
+do NOT exist outside the Anthropic API. Calling them against a local-LLM
+serving layer produces a tool-not-found error or, worse, a silent no-op.
+
+- Do NOT emit tool calls named `str_replace_editor`, `text_editor_*`,
+  `computer_use_*`, or any other tool whose name includes `str_replace_editor`
+  or matches Anthropic-specific tool schemas.
+- Use only tools enumerated in the active tool manifest (`MANIFEST.yaml`) or
+  the IDE's native tool surface (Roo Code, Cline, OpenCode native tools).
+- When you want to edit a file, use the native file-write tool of the active
+  agent — not `str_replace_editor`. If unsure what tool is available, list
+  available tools or ask the user before emitting a tool call.
+
+### Per-phase reasoning and sampling guidance
+
+Local LLMs require tighter sampling control than cloud LLMs. Use these defaults
+unless the serving layer overrides them.
+
+- **Planning phase (PM, Architect, Tech Lead):**
+  - Reasoning: OFF (`/no_think` prepended).
+  - Temperature: low (0.0 – 0.3). Planning artifacts should be deterministic
+    and reproducible.
+  - Top-p: 0.9 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — planning documents are long.
+- **Implementation phase (Dev):**
+  - Reasoning: ON (omit `/no_think`).
+  - Temperature: moderate (0.3 – 0.6). Code synthesis benefits from controlled
+    exploration but not creative rewriting.
+  - Top-p: 0.95 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — full-file rewrites are common.
+- **Review / QA phase:**
+  - Reasoning: ON for root-cause analysis; OFF for mechanical checks.
+  - Temperature: low (0.0 – 0.2). Reviews should be deterministic.
+
+If the serving layer applies its own sampler defaults, the per-phase guidance
+above is advisory — but the phase boundary and `/no_think` placement are
+load-bearing and MUST be honored on every turn.

package/lib/templates/instruction-block-universal.template.md

@@ -1,29 +1,29 @@
-# AI Agent Skills - Planning Instruction
-
-You have access to a library of skills in your skills directory. Before starting any task:
-
-1. Read the skill manifest at {{MANIFEST_PATH}}
-2. Based on the task description, select which skills are relevant
-3. Read only the selected skill files
-4. Then proceed with the task
-
-Always load skills marked with always_load: true.
-Do not load skills that are not relevant to the current task.
-
-## Respond in TEXT vs. create FILES
-
-Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
-
-- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
-- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
-- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
-- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
-- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
-
-## BMAD phase discipline
-
-BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
-
-- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
-- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
-- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.
+# AI Agent Skills - Planning Instruction
+
+You have access to a library of skills in your skills directory. Before starting any task:
+
+1. Read the skill manifest at {{MANIFEST_PATH}}
+2. Based on the task description, select which skills are relevant
+3. Read only the selected skill files
+4. Then proceed with the task
+
+Always load skills marked with always_load: true.
+Do not load skills that are not relevant to the current task.
+
+## Respond in TEXT vs. create FILES
+
+Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
+
+- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
+- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
+- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
+- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
+- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
+
+## BMAD phase discipline
+
+BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
+
+- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
+- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
+- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.12.3",
+  "version": "3.13.1",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,10 +8,11 @@
   },
   "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/bmad-version-bump.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/onprem-injection.test.js && node test/onprem-layer.test.js && node test/roomodes.test.js && node test/clinerules.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",
+    "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/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/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",
     "build:bmad-cache": "node scripts/build-bmad-cache.js",
     "build:plugin": "node scripts/build-plugin.js",
-    "prepare": "node scripts/build-plugin.js"
+    "prepare": "node scripts/build-plugin.js",
+    "version": "node scripts/build-plugin.js && git add lib/bmad-extension-plugin"
   },
   "keywords": [
     "ai",
@@ -29,7 +30,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "bmad-method": "6.6.0",
+    "bmad-method": "6.8.0",
     "chalk": "^4.1.2",
     "fs-extra": "^11.1.1",
     "js-yaml": "^4.1.1",

package/scripts/build-bmad-cache.js

@@ -9,22 +9,56 @@ const CACHE_DIR = path.join(__dirname, '..', 'lib', 'bmad-cache');
 const MANIFEST_PATH = path.join(CACHE_DIR, 'cache-manifest.json');
 const force = process.argv.includes('--force');
 
-// bmad-method 6.3.0 replaced `tools/cli/external-official-modules.yaml` with
-// `tools/installer/modules/registry-fallback.yaml` (the bundled fallback that
-// mirrors the upstream marketplace `registry/official.yaml`). We read the
-// fallback because (a) it is deterministic across offline builds and (b) it
-// matches what bmad-method itself loads when the network registry is
-// unreachable. The new schema uses map keys with properties — crucially, it
-// no longer carries a `branch` field, and non-external `built_in: true`
-// modules (like `core` and `bmm`) are shipped inside bmad-method itself and
-// must not be cached as separate git clones.
+// The bundled module registry has stayed YAML throughout bmad-method's
+// history, but its PATH has moved across versions (see Decision P5-5 in
+// architecture.md):
+//
+//   ≤6.2.x   tools/cli/external-official-modules.yaml
+//   6.3.0    tools/installer/modules/registry-fallback.yaml  (retired in 6.7.0)
+//   6.8.0    bmad-modules.yaml  (package root)
+//
+// We read the bundled registry because (a) it is deterministic across offline
+// builds and (b) it matches what bmad-method itself loads when the network
+// registry is unreachable. The 6.8.0 file is a `modules:` map whose entries
+// carry `code`/`url`/`name`/`type` — the same shape the parser already reads.
+// Crucially the new schema carries no `branch` field (default to `main`) and
+// it expresses the bundle decision via a `type` field rather than the old
+// `built_in` flag: `type: bmad-org` modules (tea, bmb, cis, gds, wds) are
+// cloned; `type: experimental` (automator) is excluded; `bmm`/`core` are
+// built into the npm package itself and are absent from the registry entirely.
+//
+// Candidates are tried in order; the first that exists on disk wins. The
+// package-root path is listed first because it is the live 6.8.0+ location.
+//
+// The two older paths are retained only as diagnostics: they carry the
+// pre-6.8.0 `built_in` schema, which the `type: bmad-org` filter below does
+// NOT understand, so they resolve zero bundled modules. If one of them is the
+// only file present (i.e. someone downgraded bmad-method below 6.8.0), the
+// thin-cache guard in main() aborts with an actionable message rather than
+// silently shipping an empty cache. They are kept so `locateRegistry` reports
+// "found <old path>" instead of a bare "nothing found", which points the
+// maintainer at the version mismatch.
 const REGISTRY_CANDIDATES = [
-  // v6.3.0+
-  ['tools', 'installer', 'modules', 'registry-fallback.yaml'],
-  // legacy v6.2.x fallback (kept so a partial downgrade doesn't explode)
-  ['tools', 'cli', 'external-official-modules.yaml'],
+  // v6.8.0+ — relocated to the package root (the supported, filterable schema)
+  { parts: ['bmad-modules.yaml'], schema: 'package-root-v68' },
+  // v6.3.0–6.6.x bundled fallback (diagnostic only — pre-`type` schema)
+  { parts: ['tools', 'installer', 'modules', 'registry-fallback.yaml'], schema: 'registry-fallback' },
+  // legacy v6.2.x fallback (diagnostic only — pre-`type` schema)
+  { 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.
+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.
+const BUNDLED_MODULE_TYPE = 'bmad-org';
+
 /**
  * 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
@@ -41,36 +75,54 @@ function locateBmadMethodDir() {
 
 /**
  * Locate the first registry YAML that exists on disk.
- * Returns { yamlPath, schema } where schema is 'v63' (new map format) or
- * 'legacy' (the pre-6.3 top-level map with `url`/`branch` fields).
+ *
+ * @param {string} bmadMethodDir Absolute path to the bmad-method package dir.
+ * @returns {{ yamlPath: string, schema: string }} The resolved registry path
+ *   and its schema tag (`package-root-v68` for the relocated 6.8.0 YAML,
+ *   `registry-fallback` for 6.3.0–6.6.x, or `legacy` for ≤6.2.x).
+ *
+ * Resolution is fail-loud: if no candidate exists, prints an actionable error
+ * and exits non-zero (NFR56) rather than returning a falsy result that a
+ * caller might silently treat as "zero modules".
  */
 function locateRegistry(bmadMethodDir) {
-  for (let i = 0; i < REGISTRY_CANDIDATES.length; i++) {
-    const parts = REGISTRY_CANDIDATES[i];
-    const candidate = path.join(bmadMethodDir, ...parts);
-    if (fs.existsSync(candidate)) {
-      return { yamlPath: candidate, schema: i === 0 ? 'v63' : 'legacy' };
+  for (const candidate of REGISTRY_CANDIDATES) {
+    const candidatePath = path.join(bmadMethodDir, ...candidate.parts);
+    if (fs.existsSync(candidatePath)) {
+      return { yamlPath: candidatePath, schema: candidate.schema };
     }
   }
   console.error('Error: no module registry YAML found in bmad-method.');
-  console.error(`  Searched: ${REGISTRY_CANDIDATES.map(p => p.join('/')).join(', ')}`);
+  console.error(`  Searched: ${REGISTRY_CANDIDATES.map(c => c.parts.join('/')).join(', ')}`);
+  console.error('  Expected the relocated package-root "bmad-modules.yaml" at bmad-method >= 6.8.0.');
   process.exit(1);
 }
 
 /**
  * Parse the bundled module registry YAML.
  *
- * Both the v6.3.0 (`registry-fallback.yaml`) and legacy
- * (`external-official-modules.yaml`) schemas use the same shape:
+ * Every registry version (legacy `external-official-modules.yaml`, the
+ * `registry-fallback.yaml`, and the relocated package-root `bmad-modules.yaml`
+ * at 6.8.0) uses the same `modules:` map shape, so a single parser serves all:
  *
  *     modules:
  *       <module-key>:
  *         url: "..."
  *         code: "..."
  *         name: "..."
- *         [branch: "..."]            # legacy only
- *         [built_in: true]           # v6.3.0 only — filter these out
- *         [module-definition: "..."] # v6.3.0 only — informational
+ *         type: "..."                # v6.8.0 — drives the bundle filter
+ *         [branch: "..."]            # legacy only (absent at 6.8.0 → main)
+ *         [built_in: true]           # 6.3.0–6.6.x only (superseded by `type`)
+ *         [module-definition: "..."] # informational, ignored
+ *
+ * The parser already captures arbitrary scalar properties (including `type`),
+ * so the 6.8.0 relocation needed no parser change — only the docblock and the
+ * downstream filter were updated.
+ *
+ * @param {string} content Raw UTF-8 YAML text.
+ * @returns {Array<Object>} One object per module entry; keys mirror the YAML
+ *   property names plus a synthetic `key` (the map key). No filtering is done
+ *   here — that is normalizeModules()'s job.
  *
  * We keep a minimal line-by-line parser (no js-yaml dep) since the file is
  * flat and well-formed.
@@ -128,19 +180,20 @@ function parseModulesYaml(content) {
  *   { code, url, name, branch }
  *
  * - Requires both `code` and `url`.
- * - Drops entries flagged `built_in: true` / `built_in: "true"` — those are
- *   first-party bmad-method modules (e.g. `core`, `bmm`) that live inside the
- *   npm package itself and must not be cached as external git clones. The
- *   test `'built_in' filter` under "Task 2" in bmad-version-bump.test.js pins
- *   this invariant.
- * - Defaults `branch` to `main` when absent (v6.3.0 schema omits it).
+ * - 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).
  * - 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}>}
  */
-// Values that YAML may use to express a truthy boolean. bmad-method uses
-// canonical `true`, but be generous so a future registry that emits `yes`/
-// `on`/`1` cannot accidentally cache a built-in module as an external clone.
-const TRUTHY_STRINGS = new Set(['true', 'yes', 'on', '1', 'y']);
-
 // Module `code` values are used as directory names under lib/bmad-cache.
 // Reject anything that could escape the cache dir or inject shell characters;
 // registry data is trusted today, but this is cheap defense-in-depth.
@@ -150,8 +203,10 @@ function normalizeModules(raw) {
   return raw
     .filter(m => m.code && m.url)
     .filter(m => {
-      const builtIn = String(m.built_in || '').toLowerCase();
-      return !TRUTHY_STRINGS.has(builtIn);
+      // 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;
     })
     .filter(m => {
       if (MODULE_CODE_PATTERN.test(m.code)) return true;
@@ -315,8 +370,40 @@ function main() {
   console.log('='.repeat(40));
 
   const { modules, schema } = loadModuleDefinitions();
-  if (modules.length === 0) {
-    console.error('Error: No modules found in registry YAML');
+
+  // 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.
+  const resolvedCodes = new Set(modules.map(m => m.code));
+
+  // Duplicate-code guard. Two registry entries sharing a `code` would clone
+  // into the same cache directory and silently overwrite each other's manifest
+  // entry (last-write-wins), and the Set above would mask the collision from
+  // the thin-cache check below. Fail loud instead.
+  if (modules.length !== resolvedCodes.size) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const m of modules) {
+      if (seen.has(m.code)) dupes.add(m.code);
+      seen.add(m.code);
+    }
+    console.error('Error: registry contains duplicate module codes — refusing to build an ambiguous cache.');
+    console.error(`  Duplicated: ${[...dupes].join(', ')}`);
+    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(', ')}`);
+    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.');
     process.exit(1);
   }
   console.log(`Found ${modules.length} modules: ${modules.map(m => m.code).join(', ')}`);
@@ -491,4 +578,18 @@ function main() {
   }
 }
 
-main();
+// Run the build only when executed directly (`node scripts/build-bmad-cache.js`).
+// When required as a module (by unit tests), export the pure reader functions
+// instead so they can be exercised against fixtures without cloning anything.
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    parseModulesYaml,
+    normalizeModules,
+    locateRegistry,
+    KNOWN_BUNDLED_MODULES,
+    BUNDLED_MODULE_TYPE,
+    REGISTRY_CANDIDATES,
+  };
+}

package/lib/bmad-cache/bmb/_git_preserved/refs/remotes/origin/HEAD

@@ -1 +0,0 @@
-ref: refs/remotes/origin/main

package/lib/bmad-cache/bmb/_git_preserved/refs/tags/v1.7.0

@@ -1 +0,0 @@
-6c66cf215b5ec6701d70cf2d9df968fa09433cfe