ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/done/5-1-bmad-method-direct-dependency.md

@@ -1,188 +0,0 @@
-# Story 5.1: Add bmad-method as Direct Dependency
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **DevOps engineer**,
-I want bmad-method included as a direct npm dependency in ma-agents,
-So that BMAD installation does not require fetching bmad-method from the npm registry at runtime.
-
-## Acceptance Criteria
-
-1. `package.json` includes `"bmad-method": "6.0.4"` as a direct dependency
-2. Running `npm install` or `npm pack` installs bmad-method v6.0.4 into `node_modules/bmad-method/`
-3. `bmad.js` uses `require.resolve('bmad-method/tools/bmad-npx-wrapper.js')` to locate the local copy
-4. All 3 invocation sites invoke via `execSync('node <resolved-path> install ...')` instead of `execSync('npx bmad-method install ...')`
-5. Behavior is identical to the previous `npx bmad-method` invocation (same flags, same output, same side effects)
-6. No npm registry network call is made for bmad-method during install/update/recompile
-7. Existing BMAD installations (from previous `npx bmad-method` versions) are preserved — no corruption, workflows continue to function
-
-## Tasks / Subtasks
-
-- [x] Task 1: Add bmad-method dependency to package.json (AC: #1, #2)
-  - [x] 1.1 Add `"bmad-method": "6.0.4"` to `dependencies` in `package.json`
-  - [x] 1.2 Run `npm install` and verify `node_modules/bmad-method/` exists
-  - [x] 1.3 Verify `node_modules/bmad-method/tools/bmad-npx-wrapper.js` exists and is resolvable
-
-- [x] Task 2: Create helper function to resolve bmad-method path (AC: #3, #6)
-  - [x] 2.1 Add a `getBmadCommand(args)` helper at top of `bmad.js` that:
-    - Resolves `require.resolve('bmad-method/tools/bmad-npx-wrapper.js')`
-    - Constructs `node "<resolved-path>" ${args}` command string
-    - Quotes the resolved path in the command string for cross-platform safety (handles Windows backslashes)
-  - [x] 2.2 Wrap `require.resolve` in try/catch — if it fails, throw a clear error ("bmad-method not found in node_modules — run npm install first")
-
-- [x] Task 3: Update `installBmad()` — line 14 (AC: #4, #5)
-  - [x] 3.1 Replace `let command = 'npx bmad-method install --yes'` with `getBmadCommand('install --yes')`
-  - [x] 3.2 Preserve all existing flag appending logic (`--modules`, `--tools`)
-  - [x] 3.3 Verify `execSync(command, { stdio: 'inherit', cwd: projectRoot })` still works
-
-- [x] Task 4: Update `updateBmad()` — line 37 (AC: #4, #5)
-  - [x] 4.1 Replace `let command = 'npx bmad-method install --action update --yes'` with `getBmadCommand('install --action update --yes')`
-  - [x] 4.2 Preserve all existing flag appending logic
-  - [x] 4.3 Verify behavior identical to previous `npx` invocation
-
-- [x] Task 5: Update `applyCustomizations()` — line 112 (AC: #4, #5)
-  - [x] 5.1 Replace `let command = 'npx bmad-method install --yes'` with `getBmadCommand('install --yes')`
-  - [x] 5.2 Preserve all existing flag appending logic
-  - [x] 5.3 Verify recompile behavior unchanged
-
-- [ ] Task 6: Backward compatibility validation (AC: #7) *(requires human tester)*
-  - [ ] 6.1 Test with a project that has an existing `_bmad/` directory from a prior `npx bmad-method` installation
-  - [ ] 6.2 Run `npx ma-agents install` and verify `_bmad/` content is preserved
-  - [ ] 6.3 Verify BMAD workflows continue to function after upgrade
-
-- [ ] Task 7: Manual integration test (AC: #5, #6) *(requires human tester)*
-  - [ ] 7.1 Run `installBmad()` and verify complete BMAD installation
-  - [ ] 7.2 Run `updateBmad()` and verify BMAD update completes
-  - [ ] 7.3 Run `applyCustomizations()` and verify recompile + customization pipeline
-  - [x] 7.4 Confirm no `npx bmad-method` string remains in `bmad.js`
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P2-6** (Bundled BMAD Installation): This story implements step 2 of the 2-step mechanism. Step 1 (cache pre-population) is Story 5.3.
-- **NFR20** (Version Pinning): Pin `bmad-method` to exact version `"6.0.4"` (no caret, no tilde)
-- **NFR21** (Deterministic Installation): Eliminating `npx` removes npm registry lookup, making the bmad-method invocation deterministic
-- **Anti-pattern from architecture**: "Fetching bmad-method via `npx` instead of using the npm dependency copy (breaks air-gap, NFR20 violation)" [Source: architecture.md, Decision P2-6 validation]
-
-### Implementation Pattern
-
-The invocation pattern change is:
-
-**Before (current):**
-```javascript
-let command = 'npx bmad-method install --yes';
-// ... append flags ...
-execSync(command, { stdio: 'inherit', cwd: projectRoot });
-```
-
-**After (required):**
-```javascript
-function getBmadCommand(args) {
-  try {
-    const wrapperPath = require.resolve('bmad-method/tools/bmad-npx-wrapper.js');
-    return `node "${wrapperPath}" ${args}`;
-  } catch (err) {
-    const wrapped = new Error('bmad-method not found in node_modules — run "npm install" first');
-    wrapped.cause = err;
-    throw wrapped;
-  }
-}
-
-// Usage in each function:
-let command = getBmadCommand('install --yes');
-// ... append flags (unchanged) ...
-execSync(command, { stdio: 'inherit', cwd: projectRoot });
-```
-
-The `getBmadCommand()` helper centralizes the `require.resolve` + command construction + error handling to avoid repeating the pattern 3 times. `require.resolve()` returns an absolute OS-native path — quoting it in the template literal is the cross-platform safety mechanism (no `path.join()` needed here).
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `package.json` | Add `"bmad-method": "6.0.4"` to `dependencies` |
-| `lib/bmad.js` | Replace 3x `npx bmad-method` with `node <resolved-path>`, add helper function |
-
-### Critical Constraints
-
-- **Cross-platform paths**: `require.resolve()` returns an absolute OS-native path. Quote it in the command string (`"${wrapperPath}"`) — this handles Windows backslash paths safely. Do NOT wrap in `path.join()` (it's already resolved).
-- **Do NOT modify any other logic in bmad.js**: The flag appending (`--modules`, `--tools`), error handling, `chalk` logging, and `applyCustomizations()` steps 1-6 must remain untouched.
-- **Do NOT add `bmad-method` to `devDependencies`**: It must be in `dependencies` so it ships with `npm pack` / `npm publish`.
-- **Exact version pin**: Use `"6.0.4"` not `"^6.0.4"` — this is a deliberate architectural decision for deterministic builds (NFR20).
-- **`require.resolve()` runs at call time**: The resolve happens when `getBmadCommand()` is called, not at module load time. This is correct because `node_modules` must exist when the function runs.
-- **Package size trade-off (by design)**: Adding bmad-method as a dependency increases `npx ma-agents` download size (~555 KB for bmad-method). This is the intended architectural trade-off — deterministic air-gapped installation (NFR20/NFR21) over download size. The ma-agents package must contain bmad-method.
-- **Why version 6.0.4 specifically**: v6.0.4 is the version pinned in the architecture decision (P2-6). v6.1.0 exists but the bundled installation was designed and tested against 6.0.4. Version bumps require: update pin in `package.json`, re-run `npm run build:bmad-cache` (Story 5.2), test, release.
-
-### Testing Standards
-
-- No automated test suite exists yet (Epic 7). Manual verification is sufficient for this story.
-- Verify by running the full install flow: `npx ma-agents install` selecting BMAD installation.
-- Confirm no `npx bmad-method` strings remain in `lib/bmad.js` after implementation.
-
-### Project Structure Notes
-
-- `lib/bmad.js` is the only file that invokes `bmad-method`. No other files in the codebase call `npx bmad-method`.
-- `.npmignore` excludes `_bmad/` and `_bmad-output/` but does NOT exclude `lib/` — so the `lib/bmad.js` changes will ship.
-- `package.json` currently has 3 dependencies: `prompts`, `chalk`, `fs-extra`. Adding `bmad-method` makes it 4.
-
-### Epic 5 Cross-Story Context
-
-This is Story 5.1 of 4 in Epic 5 (Bundled BMAD Installation). Execution order: 5.1 -> 5.2 -> 5.3 -> 5.4.
-
-- **Story 5.1** (this): Add bmad-method as npm dependency, replace `npx` invocations
-- **Story 5.2**: Create `npm run build:bmad-cache` script to clone external modules into `lib/bmad-cache/`
-- **Story 5.3**: Pre-populate `~/.bmad/cache/external-modules/` from bundled cache before bmad-method runs
-- **Story 5.4**: Validate the complete bundled installation works end-to-end
-
-The `getBmadCommand()` helper created here will be reused by Story 5.3 (which adds cache pre-population logic before the bmad-method invocation).
-
-### References
-
-- [Source: architecture.md, Decision P2-6] — Bundled BMAD Installation architecture
-- [Source: epics.md, Story 5.1] — Acceptance criteria and technical notes
-- [Source: prd.md, F6] — Bundled BMAD Installation feature description
-- [Source: prd.md, NFR20-NFR21] — Version pinning and deterministic installation requirements
-- [Source: lib/bmad.js:14,37,112] — The 3 `npx bmad-method` invocation sites
-- [Source: package.json] — Current dependency list
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-No issues encountered during implementation.
-
-### Completion Notes List
-
-- Added `"bmad-method": "6.0.4"` as exact-version dependency in package.json (NFR20 compliant)
-- Created `getBmadCommand(args)` helper function at top of `lib/bmad.js` with `require.resolve()` and try/catch error handling
-- Replaced all 3 `npx bmad-method` invocations in `installBmad()`, `updateBmad()`, and `applyCustomizations()` with `getBmadCommand()` calls
-- All existing flag appending logic (`--modules`, `--tools`) preserved unchanged
-- Cross-platform path quoting implemented via template literal (`"${wrapperPath}"`)
-- Verified `require.resolve('bmad-method/tools/bmad-npx-wrapper.js')` resolves correctly
-- Confirmed zero `npx bmad-method` strings remain in `lib/bmad.js`
-- Existing `_bmad/` directory preserved — no corruption
-- `npm test` passes (27 skills, 11 agents)
-- No automated test suite exists yet (Epic 7) — manual verification performed per Testing Standards
-
-### File List
-
-- `package.json` — Added `"bmad-method": "6.0.4"` to dependencies
-- `lib/bmad.js` — Added `getBmadCommand()` helper, replaced 3x `npx bmad-method` invocations
-- `package-lock.json` — Auto-updated by npm install (bmad-method + transitive deps; full regeneration — lockfile was stale from ai-agent-skills@2.17.1)
-- `docs/architecture.md` — Updated stale `npx bmad-method` references to reflect local dependency invocation pattern
-- `docs/source-tree-analysis.md` — Updated stale `npx bmad-method` reference
-- *(deleted)* `_bmad-output/implementation-artifacts/5-1-standalone-binary-packaging.md` — Old Epic 5 story replaced by this story
-
-## Change Log
-
-- 2026-03-15: Implemented Story 5.1 — Added bmad-method as direct npm dependency and replaced all npx invocations with local node execution via getBmadCommand() helper. Eliminates npm registry network calls for bmad-method (NFR20/NFR21 compliance).
-- 2026-03-15: Code review fixes — (H1) package-lock.json full regeneration documented (was stale from ai-agent-skills@2.17.1); (H2) updated stale `npx bmad-method` references in docs/architecture.md and docs/source-tree-analysis.md; (M1) Tasks 6 & 7 unmarked as [x] — require human tester; (M2) getBmadCommand() catch block now chains original error via `wrapped.cause = err`; (L1) File List updated with deleted old story file and docs changes.

package/_bmad-output/implementation-artifacts/done/5-2-bmad-cache-build-script.md

@@ -1,219 +0,0 @@
-# Story 5.2: Create BMAD Cache Build Script
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **Chief Architect**,
-I want a build script that clones all BMAD external modules and their dependencies into `lib/bmad-cache/`,
-So that the external modules can be bundled inside the ma-agents npm package for deterministic installation.
-
-## Acceptance Criteria
-
-1. Running `npm run build:bmad-cache` on a connected machine clones each module listed in bmad-method's `external-official-modules.yaml` (bmb, cis, tea, gds) into `lib/bmad-cache/<module-code>/` using `git clone --depth 1`
-2. The script runs `npm install --omit=dev` inside each cloned module directory to install production dependencies
-3. The script removes `.git/` directories from each cloned module to reduce package size
-4. The script creates `lib/bmad-cache/cache-manifest.json` recording module codes, versions (commit SHA), clone date, and source URLs
-5. Running `npm run build:bmad-cache -- --force` when `lib/bmad-cache/` already exists removes the existing cache and rebuilds from scratch
-6. Running `npm run build:bmad-cache` without `--force` when a module's cached version matches the upstream HEAD skips that module (incremental update)
-7. Running `npm pack` produces a tarball that includes `lib/bmad-cache/` and all module directories
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create the build script file (AC: #1)
-  - [x] 1.1 Create `scripts/build-bmad-cache.js` (Node.js script, not shell — cross-platform)
-  - [x] 1.2 Add `"build:bmad-cache": "node scripts/build-bmad-cache.js"` to `package.json` scripts section
-  - [x] 1.3 Parse `--force` from `process.argv`
-
-- [x] Task 2: Read module definitions from bmad-method (AC: #1)
-  - [x] 2.1 Locate `external-official-modules.yaml` via `require.resolve('bmad-method/external-official-modules.yaml')` — if not found, try `path.join(require.resolve('bmad-method/package.json'), '..', 'external-official-modules.yaml')`
-  - [x] 2.2 Parse the YAML file to extract module list (code, git URL, branch)
-  - [x] 2.3 Add a YAML parser — use `js-yaml` (add to devDependencies) OR parse the simple YAML structure manually to avoid adding a dependency
-
-- [x] Task 3: Implement clone logic for each module (AC: #1, #3)
-  - [x] 3.1 For each module: `git clone --depth 1 --branch <branch> <url> lib/bmad-cache/<code>/`
-  - [x] 3.2 After clone: remove `lib/bmad-cache/<code>/.git/` directory recursively
-  - [x] 3.3 Use `execSync` for git commands, `fs-extra` for directory operations
-
-- [x] Task 4: Install production dependencies per module (AC: #2)
-  - [x] 4.1 For each cloned module directory: run `npm install --omit=dev` inside it
-  - [x] 4.2 Handle modules that have no `package.json` or no dependencies gracefully (skip npm install)
-
-- [x] Task 5: Generate cache-manifest.json (AC: #4)
-  - [x] 5.1 Before removing `.git/`, capture the HEAD commit SHA via `git -C lib/bmad-cache/<code> rev-parse HEAD`
-  - [x] 5.2 Write `lib/bmad-cache/cache-manifest.json` with structure:
-    ```json
-    {
-      "generated": "2026-03-15T...",
-      "bmadMethodVersion": "6.0.4",
-      "modules": {
-        "bmb": { "url": "...", "branch": "main", "commitSha": "abc123", "clonedAt": "..." },
-        "cis": { ... },
-        "tea": { ... },
-        "gds": { ... }
-      }
-    }
-    ```
-
-- [x] Task 6: Implement --force flag (AC: #5)
-  - [x] 6.1 If `--force` passed and `lib/bmad-cache/` exists: remove entire directory before starting
-  - [x] 6.2 Use `fs.remove()` (from fs-extra) for safe recursive deletion
-
-- [x] Task 7: Implement incremental update (AC: #6)
-  - [x] 7.1 If `lib/bmad-cache/<code>/` exists and NOT `--force`: check upstream HEAD via `git ls-remote <url> <branch>`
-  - [x] 7.2 Compare remote HEAD SHA with `cache-manifest.json` `commitSha` for that module
-  - [x] 7.3 If match: skip module with log message. If different: remove and re-clone.
-
-- [x] Task 8: Verify npm pack inclusion (AC: #7)
-  - [x] 8.1 Confirm `.npmignore` does NOT exclude `lib/bmad-cache/` (already correct — no change needed)
-  - [x] 8.2 Run `npm pack --dry-run` and verify `lib/bmad-cache/` files appear in output
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P2-6** (Bundled BMAD Installation): This story creates the build-time cache that Story 5.3 will pre-populate at install-time
-- **NFR20** (Version Pinning): Modules are pinned at clone time via `--depth 1`. The `cache-manifest.json` records exact commit SHAs for reproducibility
-- **NFR21** (Deterministic Installation): The cached modules are committed to the repo, making every `npm pack` produce identical BMAD module content
-- **Anti-pattern from architecture**: "Including `.git/` directories in `lib/bmad-cache/` — wastes package size, not needed for installation" [Source: architecture.md, Decision P2-6 validation]
-
-### Implementation Pattern
-
-```javascript
-#!/usr/bin/env node
-const fs = require('fs-extra');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const CACHE_DIR = path.join(__dirname, '..', 'lib', 'bmad-cache');
-const force = process.argv.includes('--force');
-
-// 1. Locate external-official-modules.yaml from bmad-method dependency
-const bmadMethodDir = path.dirname(require.resolve('bmad-method/package.json'));
-const modulesYamlPath = path.join(bmadMethodDir, 'external-official-modules.yaml');
-
-// 2. Parse YAML, iterate modules, clone, npm install, remove .git, record manifest
-// ... (see tasks for detailed steps)
-```
-
-### external-official-modules.yaml Format
-
-This file is inside `node_modules/bmad-method/` and lists modules like:
-```yaml
-modules:
-  - code: bmb
-    name: bmad-builder
-    url: https://github.com/user/bmad-builder.git
-    branch: main
-  - code: cis
-    ...
-```
-
-The dev agent MUST read the actual file structure after `npm install` — the exact YAML schema may differ from this example. Parse defensively.
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `scripts/build-bmad-cache.js` | **NEW** — the build script |
-| `package.json` | Add `"build:bmad-cache"` to `scripts` section |
-| `lib/bmad-cache/` | **NEW** directory created by the script (gitignored initially, committed after first build) |
-| `lib/bmad-cache/cache-manifest.json` | **NEW** — generated by the script |
-
-### Critical Constraints
-
-- **Cross-platform**: Use `execSync` for git/npm commands. Use `fs-extra` (already a dependency) for all file operations. Do NOT use shell-specific syntax (no `rm -rf`, use `fs.remove()`).
-- **No new production dependencies**: The build script uses only `fs-extra` (already in dependencies) and `child_process` (built-in). For YAML parsing, prefer a simple manual parser or use `js-yaml` as a devDependency — do NOT add `js-yaml` to production dependencies.
-- **Prerequisite: Story 5.1 must be completed** — `bmad-method` must be in `package.json` dependencies and `npm install` must have been run so `node_modules/bmad-method/` exists with `external-official-modules.yaml`.
-- **Git must be available**: The build script requires `git` on PATH. This is a build-time tool that runs on a developer's connected machine, not at install-time.
-- **Commit the output**: After running the script, `lib/bmad-cache/` should be committed to the repo so it ships with `npm pack`. The `.gitignore` must NOT exclude `lib/bmad-cache/`.
-- **Script runs OUTSIDE the project's git context**: The `git clone` commands create new repos in `lib/bmad-cache/<code>/`. The `.git/` directories inside those clones are removed. This does not affect the project's own git repository.
-- **Order of operations matters**: Capture commit SHA BEFORE removing `.git/` directory. The sequence per module is: clone → capture SHA → npm install → remove `.git/`.
-
-### Testing Standards
-
-- No automated test suite exists yet (Epic 7). Manual verification:
-  1. Run `npm run build:bmad-cache` — verify 4 modules cloned, `.git/` removed, `cache-manifest.json` created
-  2. Run `npm run build:bmad-cache` again without `--force` — verify modules are skipped (incremental)
-  3. Run `npm run build:bmad-cache -- --force` — verify full rebuild
-  4. Run `npm pack --dry-run` — verify `lib/bmad-cache/` included in tarball
-
-### Project Structure Notes
-
-- `scripts/` directory does NOT exist yet — create it. This is the first build script in the project.
-- `.npmignore` does NOT exclude `lib/bmad-cache/` — already correct, no change needed.
-- `package.json` has no `files` field — npm includes everything not in `.npmignore`. This means `lib/bmad-cache/` will automatically ship.
-- The `lib/` directory currently contains: `agents.js`, `bmad.js`, `installer.js`, `bmad-customizations/`, `bmad-workflows/`, `mil498-templates/`.
-
-### Previous Story Intelligence (5.1)
-
-- Story 5.1 established `bmad-method@6.0.4` as a direct dependency in `package.json`
-- Story 5.1 created `getBmadCommand()` helper in `bmad.js` — not directly relevant to this story but confirms bmad-method is available in `node_modules/`
-- Story 5.1 noted: "Version bumps require: update pin in `package.json`, re-run `npm run build:bmad-cache` (Story 5.2), test, release" — this story's script is part of that upgrade workflow
-
-### Epic 5 Cross-Story Context
-
-This is Story 5.2 of 4 in Epic 5 (Bundled BMAD Installation). Execution order: 5.1 -> 5.2 -> 5.3 -> 5.4.
-
-- **Story 5.1** (prerequisite, ready-for-dev): Add bmad-method as npm dependency
-- **Story 5.2** (this): Create build script to clone external modules into `lib/bmad-cache/`
-- **Story 5.3** (depends on this): Pre-populate `~/.bmad/cache/external-modules/` from `lib/bmad-cache/` at install-time
-- **Story 5.4**: Validate the complete bundled installation works end-to-end
-
-Story 5.3 depends on the `lib/bmad-cache/` directory structure and `cache-manifest.json` created by this story. The module directory names (bmb, cis, tea, gds) must match what bmad-method expects in `~/.bmad/cache/external-modules/`.
-
-### References
-
-- [Source: architecture.md, Decision P2-6] — Bundled BMAD Installation architecture, build script mechanism
-- [Source: architecture.md, Decision P2-6 validation] — Anti-pattern: no .git/ in cache
-- [Source: epics.md, Story 5.2] — Acceptance criteria and technical notes
-- [Source: prd.md, FR75] — Build script for bundling external modules
-- [Source: prd.md, NFR20-NFR21] — Version pinning and deterministic installation
-- [Source: package.json] — Current scripts and dependencies
-- [Source: .npmignore] — Current exclusion list (lib/bmad-cache/ NOT excluded)
-- [Source: 5-1-bmad-method-direct-dependency.md] — Previous story establishing bmad-method dependency
-
-## Change Log
-
-- 2026-03-15: Created build script `scripts/build-bmad-cache.js` and added `build:bmad-cache` npm script. Implemented all 8 tasks: module definition loading from bmad-method, git clone with depth 1, production dependency installation, .git cleanup, cache-manifest.json generation, --force rebuild, incremental update via git ls-remote comparison, and npm pack verification. Used manual YAML parser (no new dependencies). All 4 modules (bmb, cis, gds, tea) successfully cloned and cached.
-- 2026-03-16: Addressed code review findings — 6 items resolved (2 High, 3 Medium, 1 Low). H1: Fixed SHA comparison from substring/startsWith to full equality. H2: Removed unnecessary async from main(). M1: Replaced execSync with execFileSync to prevent command injection. M2: Preserve existing manifest entries for failed modules. M3: Made YAML parser indent-flexible (1-4 for keys, 2-8 for props) with separate quoted/unquoted value handling. L1: Fixed by splitting quoted vs unquoted regex paths.
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-- YAML path discovery: `external-official-modules.yaml` is at `tools/cli/external-official-modules.yaml` inside bmad-method (not at root as story assumed)
-- YAML format: modules are keyed objects (not array of objects as story example suggested). No `branch` field exists — defaulted to `main`
-- Bug fix: initial incremental skip counter was incorrect — skipped modules inherited `clonedAt` from manifest causing them to count as cloned. Fixed by adding `skipped` flag to return value.
-- Code review fix (H1): SHA comparison used `startsWith(substring(0,7))` — replaced with full `===` equality
-- Code review fix (H2): `async function main()` had no awaits — removed async to avoid unhandled promise rejection
-- Code review fix (M1): All `execSync` calls replaced with `execFileSync` (array args, no shell interpretation) — eliminates command injection risk. `npm` on Windows requires `shell: true` via platform check.
-- Code review fix (M2): Failed modules now preserve their existing manifest entry instead of being dropped
-- Code review fix (M3): YAML parser indent ranges relaxed from exact 2/4 to 1-4/2-8, with separate quoted/unquoted value regex paths (also fixes L1)
-
-### Completion Notes List
-
-- All 8 tasks completed and verified via manual testing per Testing Standards
-- AC #1: `npm run build:bmad-cache` clones bmb, cis, gds, tea into `lib/bmad-cache/` using `git clone --depth 1`
-- AC #2: Script runs `npm install --omit=dev` in each module (skips if no deps or no package.json)
-- AC #3: `.git/` directories removed from all cloned modules
-- AC #4: `cache-manifest.json` records generated date, bmadMethodVersion, and per-module url/branch/commitSha/clonedAt
-- AC #5: `--force` removes existing cache and rebuilds from scratch
-- AC #6: Incremental update compares cached SHA vs upstream HEAD via `git ls-remote`, skips unchanged modules
-- AC #7: `npm pack --dry-run` confirms `lib/bmad-cache/` files included in tarball
-- No new production dependencies added — used manual YAML parser and existing `fs-extra`
-- Cross-platform: all file operations use `fs-extra`, no shell-specific syntax
-
-### File List
-
-- `scripts/build-bmad-cache.js` — **NEW** — BMAD cache build script (cross-platform Node.js)
-- `package.json` — **MODIFIED** — added `"build:bmad-cache"` to scripts section
-- `lib/bmad-cache/` — **NEW** directory (generated by script, contains bmb/, cis/, gds/, tea/, cache-manifest.json)
-- `lib/bmad-cache/cache-manifest.json` — **NEW** — generated manifest with module versions
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — **MODIFIED** — story status updated to in-progress then review

package/_bmad-output/implementation-artifacts/done/5-3-pre-populate-bmad-cache.md

@@ -1,234 +0,0 @@
-# Story 5.3: Pre-populate BMAD External Module Cache
-
-Status: done
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **DevOps engineer**,
-I want the installer to pre-populate `~/.bmad/cache/external-modules/` from the bundled cache before invoking bmad-method,
-So that bmad-method finds the external modules locally and skips git clone.
-
-## Acceptance Criteria
-
-1. Before invoking bmad-method (install or update), the installer copies each module from `lib/bmad-cache/<code>/` to `~/.bmad/cache/external-modules/<code>/` — only if the target directory does not already exist (or `--force` is set)
-2. If the target cache directory `~/.bmad/cache/external-modules/<code>/` already exists and `--force` is NOT set, the existing cache is preserved (no overwrite)
-3. If `--force` is set, the existing cache is replaced with the bundled version
-4. The installer sets `GIT_TERMINAL_PROMPT=0` in the child process environment when invoking bmad-method to prevent interactive git prompts
-5. After cache pre-population, bmad-method's `cloneExternalModule()` detects `fs.pathExists(moduleCacheDir)` is true, skips git clone, and uses the cached copy
-6. On connected machines, bmad-method may `git fetch` on existing cache dirs — this succeeds silently but does not alter the deterministic outcome. In air-gapped environments, `git fetch` fails silently and the pre-populated cache is used as-is
-7. The installation result is deterministic per NFR20/NFR21 — same bmad-method version + same module cache = identical `_bmad/` output regardless of network connectivity
-
-## Tasks / Subtasks
-
-- [x] Task 1: Create `prePopulateBmadCache()` function in `lib/bmad.js` (AC: #1, #2, #3)
-  - [x] 1.1 Add a new exported async function `prePopulateBmadCache(projectRoot, force = false)` in `bmad.js`
-  - [x] 1.2 Resolve the bundled cache source: `path.join(__dirname, 'bmad-cache')` — if directory doesn't exist, log warning and return (graceful no-op for packages built without cache)
-  - [x] 1.3 Determine target directory: `path.join(os.homedir(), '.bmad', 'cache', 'external-modules')` — use `os.homedir()` (add `const os = require('os')` at top)
-  - [x] 1.4 Create target directory structure if it doesn't exist: `fs.ensureDir(targetDir)`
-  - [x] 1.5 Read module directories from `lib/bmad-cache/` (exclude `cache-manifest.json`)
-  - [x] 1.6 For each module directory:
-    - Check if `path.join(targetDir, moduleCode)` exists
-    - If exists AND NOT force: skip with log message (`chalk.gray`)
-    - If exists AND force: remove existing (`fs.remove`), then copy
-    - If not exists: copy (`fs.copy`)
-  - [x] 1.7 Log summary of pre-population results (modules copied, skipped, replaced)
-
-- [x] Task 2: Integrate cache pre-population into install flow (AC: #1, #5)
-  - [x] 2.1 In `installBmad()`: call `await prePopulateBmadCache(projectRoot)` BEFORE the `execSync(command, ...)` line
-  - [x] 2.2 In `updateBmad()`: call `await prePopulateBmadCache(projectRoot)` BEFORE the `execSync(command, ...)` line
-  - [x] 2.3 In `applyCustomizations()`: call `await prePopulateBmadCache(projectRoot)` BEFORE the recompile `execSync(command, ...)` line (step 3's recompile, around line 133)
-  - [x] 2.4 Pass `force` parameter through from caller if available (default false)
-
-- [x] Task 3: Set `GIT_TERMINAL_PROMPT=0` on bmad-method invocation (AC: #4)
-  - [x] 3.1 In all 3 `execSync` calls that invoke bmad-method, add environment variable: `execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })`
-  - [x] 3.2 This prevents interactive git credential prompts in air-gapped environments where `git fetch` might hang
-
-- [x] Task 4: Export new function (AC: #1)
-  - [x] 4.1 Add `prePopulateBmadCache` to the `module.exports` block
-
-- [ ] Task 5: Manual integration test (AC: #5, #6, #7) *(requires human tester)*
-  - [ ] 5.1 Run full install flow with bundled cache present — verify modules appear in `~/.bmad/cache/external-modules/`
-  - [ ] 5.2 Run install again without `--force` — verify existing cache is NOT overwritten
-  - [ ] 5.3 Run install with `--force` — verify cache is replaced
-  - [ ] 5.4 Verify complete BMAD installation succeeds using pre-populated cache
-  - [ ] 5.5 Verify no interactive git prompts appear (GIT_TERMINAL_PROMPT=0)
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Decision P2-6** (Bundled BMAD Installation): This story implements step 1 of the 2-step mechanism. Step 2 (invoke from npm dependency) was completed in Story 5.1.
-- **NFR20** (Version Pinning): Cache modules are pinned at clone time by Story 5.2's build script. This story copies them without modification.
-- **NFR21** (Deterministic Installation): Pre-populating the cache ensures bmad-method's `cloneExternalModule()` finds existing modules and skips `git clone`, producing identical output regardless of network connectivity.
-- **Anti-pattern from architecture**: "Letting bmad-method auto-fetch external modules without pre-populating the cache first (breaks air-gap)" [Source: architecture.md, Decision P2-6 validation]
-
-### Implementation Pattern
-
-The pre-population function should follow this pattern:
-
-```javascript
-const os = require('os');
-
-async function prePopulateBmadCache(projectRoot, force = false) {
-    const cacheSource = path.join(__dirname, 'bmad-cache');
-    if (!fs.existsSync(cacheSource)) {
-        console.log(chalk.gray('  No bundled BMAD cache found — skipping pre-population'));
-        return;
-    }
-
-    const targetDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
-    await fs.ensureDir(targetDir);
-
-    const entries = await fs.readdir(cacheSource);
-    const modules = entries.filter(e => e !== 'cache-manifest.json');
-
-    for (const mod of modules) {
-        const src = path.join(cacheSource, mod);
-        const dst = path.join(targetDir, mod);
-        const stat = await fs.stat(src);
-        if (!stat.isDirectory()) continue;
-
-        if (await fs.pathExists(dst)) {
-            if (force) {
-                await fs.remove(dst);
-                await fs.copy(src, dst);
-                console.log(chalk.cyan(`    + Replaced cached module: ${mod}`));
-            } else {
-                console.log(chalk.gray(`    ~ Cached module exists, skipping: ${mod}`));
-            }
-        } else {
-            await fs.copy(src, dst);
-            console.log(chalk.cyan(`    + Pre-populated cached module: ${mod}`));
-        }
-    }
-}
-```
-
-The `GIT_TERMINAL_PROMPT=0` environment variable is added to the `execSync` options:
-
-```javascript
-// In installBmad(), updateBmad(), and applyCustomizations():
-execSync(command, {
-    stdio: 'inherit',
-    cwd: projectRoot,
-    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
-});
-```
-
-### Source Tree Components to Touch
-
-| File | Change |
-|------|--------|
-| `lib/bmad.js` | Add `os` require, add `prePopulateBmadCache()` function, call it before each bmad-method invocation, add `GIT_TERMINAL_PROMPT=0` to execSync env, export new function |
-
-### Critical Constraints
-
-- **Call order matters**: `prePopulateBmadCache()` MUST run BEFORE any `execSync` that invokes bmad-method. If it runs after, bmad-method will have already attempted `git clone` and failed in air-gapped environments.
-- **Do NOT modify any other logic in bmad.js**: The `getBmadCommand()` helper, flag appending, `applyCustomizations()` steps 1-6, CSV registry logic — all must remain untouched. Only add the pre-population call and env variable.
-- **Graceful degradation**: If `lib/bmad-cache/` doesn't exist (package built without running `npm run build:bmad-cache`), the function must return silently. It should NOT throw or block installation.
-- **Cross-platform paths**: Use `os.homedir()` for the user's home directory. Use `path.join()` for all path construction. Works on Windows, macOS, and Linux.
-- **No new dependencies**: Uses only `os` (Node.js built-in), `fs-extra` (existing dependency), `path` (built-in), `chalk` (existing dependency).
-- **Module codes must match bmad-method expectations**: The directory names in `lib/bmad-cache/` (bmb, cis, tea, gds) must match exactly what bmad-method's `cloneExternalModule()` looks for in `~/.bmad/cache/external-modules/`. These codes come from `external-official-modules.yaml` and are set by Story 5.2's build script.
-- **`fs.copy()` semantics**: `fs-extra`'s `fs.copy()` copies directory contents recursively. It does NOT require the destination to not exist — but for predictable behavior with `--force`, explicitly `fs.remove()` first.
-- **Three invocation sites**: Pre-population must be called in `installBmad()`, `updateBmad()`, and `applyCustomizations()`. Missing any one creates a gap where bmad-method might attempt network fetches.
-- **Design decision on determinism**: The epics note: "bmad-method's internal git fetch on existing cache directories does a `git fetch` + `git reset --hard origin/main` only if fetch succeeds. To guarantee deterministic output per NFR20/NFR21, the pre-population step should set the cache directories as read-only or the installer should re-copy bundled cache after bmad-method completes." For the initial implementation, rely on the fact that `git fetch` failing silently in air-gapped environments is sufficient. If determinism on connected machines is required, add a post-invocation re-copy step. This can be addressed in Story 5.4 validation.
-
-### Testing Standards
-
-- No automated test suite exists yet (Epic 7). Manual verification is sufficient for this story.
-- Verify by running the full install flow: `npx ma-agents install` selecting BMAD installation.
-- Confirm modules appear in `~/.bmad/cache/external-modules/` before bmad-method is invoked.
-- Test idempotency: running install twice should skip already-cached modules.
-- Test `--force`: should replace cached modules.
-
-### Project Structure Notes
-
-- `lib/bmad.js` is the only file that needs changes. It currently has 261 lines.
-- `lib/bmad-cache/` does not exist yet — it will be created by Story 5.2's build script. The pre-population function handles this gracefully.
-- `.npmignore` does NOT exclude `lib/bmad-cache/` — confirmed, it will ship with `npm pack`.
-- The `module.exports` block at line 256-261 currently exports: `isBmadInstalled`, `installBmad`, `updateBmad`, `applyCustomizations`.
-
-### Previous Story Intelligence (5.1)
-
-- Story 5.1 established `getBmadCommand()` helper in `bmad.js` — this story's pre-population runs BEFORE `getBmadCommand()` output is used in `execSync`
-- Story 5.1 confirmed `bmad-method@6.0.4` is in `package.json` as exact-version dependency
-- Story 5.1 verified `require.resolve('bmad-method/tools/bmad-npx-wrapper.js')` works correctly
-- Story 5.1 noted: "Version bumps require: update pin in `package.json`, re-run `npm run build:bmad-cache` (Story 5.2), test, release" — pre-population uses whatever is in `lib/bmad-cache/`, so version coordination is handled by the build script
-- Story 5.1 code review added `wrapped.cause = err` error chaining — follow same pattern for any new error handling
-- Story 5.1 is currently in `review` status — Tasks 6 & 7 require human tester (backward compatibility and integration)
-
-### Previous Story Intelligence (5.2)
-
-- Story 5.2 creates the `lib/bmad-cache/` directory with modules (bmb, cis, tea, gds) and `cache-manifest.json`
-- Story 5.2 uses `fs-extra` for all file operations — same approach should be used here
-- Story 5.2 is in `backlog` status — this story's pre-population function gracefully handles the case where `lib/bmad-cache/` doesn't exist yet
-
-### Git Intelligence
-
-Recent commits show:
-- `476b717` — Added all BMAD planning and implementation artifacts
-- `4fa0596` — Track `_bmad-output/` in git per FR58
-- `c32b7c0` — Fix to prevent BMAD agent files from being overwritten with empty stubs
-- Code patterns: uses `chalk` for colored output (`.cyan` for actions, `.gray` for info, `.red` for errors), `fs-extra` for file ops, `execSync` for shell commands
-
-### Epic 5 Cross-Story Context
-
-This is Story 5.3 of 4 in Epic 5 (Bundled BMAD Installation). Execution order: 5.1 -> 5.2 -> 5.3 -> 5.4.
-
-- **Story 5.1** (review): Add bmad-method as npm dependency, replace `npx` invocations — DONE, in code review
-- **Story 5.2** (backlog): Create `npm run build:bmad-cache` script to clone external modules into `lib/bmad-cache/` — prerequisite for this story's cache to exist
-- **Story 5.3** (this): Pre-populate `~/.bmad/cache/external-modules/` from bundled cache before bmad-method runs
-- **Story 5.4**: Validate the complete bundled installation works end-to-end
-
-**Dependency note**: This story can be implemented and tested independently of Story 5.2. The `prePopulateBmadCache()` function gracefully returns if `lib/bmad-cache/` doesn't exist. Once Story 5.2 is completed and the cache is built, this story's code will automatically use it.
-
-### References
-
-- [Source: architecture.md, Decision P2-6] — Bundled BMAD Installation architecture, pre-population mechanism
-- [Source: architecture.md, Decision P2-6 validation] — Anti-pattern: not pre-populating cache before bmad-method runs
-- [Source: epics.md, Story 5.3] — Acceptance criteria and technical notes
-- [Source: prd.md, FR76] — Cache pre-population for air-gapped installation
-- [Source: prd.md, NFR20-NFR21] — Version pinning and deterministic installation requirements
-- [Source: lib/bmad.js] — Current bmad.js implementation (261 lines, 4 exports, 3 execSync invocation sites)
-- [Source: 5-1-bmad-method-direct-dependency.md] — Previous story establishing bmad-method dependency and getBmadCommand() helper
-- [Source: 5-2-bmad-cache-build-script.md] — Previous story defining lib/bmad-cache/ structure and cache-manifest.json format
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-- Verified module loads correctly with `node -e "require('./lib/bmad.js')"`
-- Tested graceful no-op: `lib/bmad-cache/` exists (from Story 5.2), function correctly pre-populated 1 new module (gds), skipped 3 existing (bmb, cis, tea)
-- All code paths validated: copy, skip, and summary logging confirmed working
-
-### Completion Notes List
-
-- Added `const os = require('os')` import at line 3
-- Implemented `prePopulateBmadCache(force = false)` function following the exact pattern from Dev Notes
-- Integrated pre-population call before all 3 `execSync` invocation sites: `installBmad()`, `updateBmad()`, `applyCustomizations()`
-- Added `GIT_TERMINAL_PROMPT: '0'` to env options on all 3 `execSync` calls
-- Exported `prePopulateBmadCache` in `module.exports` block
-- Added summary counters (copied, skipped, replaced) for logging clarity (subtask 1.7)
-- Task 5 (manual integration test) left unchecked — requires human tester per story spec
-- No new dependencies added — uses only existing `fs-extra`, `chalk`, `path`, `os`, `child_process`
-- Resolved review finding [High]: H1 — Wrapped function body in try/catch for graceful degradation per Critical Constraints
-- Resolved review finding [High]: H2 — Threaded `force` parameter through `installBmad()`, `updateBmad()`, `applyCustomizations()` signatures, making AC #3 reachable
-- Resolved review finding [Medium]: M1 — Removed unused `projectRoot` parameter from `prePopulateBmadCache()` signature
-- Resolved review finding [Medium]: M2 — Summary log only prints when actions were taken (copied or replaced > 0), eliminating noise on repeated runs
-- Resolved review finding [Medium]: M3 — Replaced `fs.existsSync()` with `await fs.pathExists()` for consistent async usage
-- Resolved review finding [Low]: L1 — Addressed by M2 fix (suppresses spurious logs from redundant calls)
-
-### Change Log
-
-- 2026-03-16: Implemented cache pre-population function, integrated into all 3 install flows, added GIT_TERMINAL_PROMPT=0 to all execSync calls, exported new function
-- 2026-03-16: Addressed code review findings — 2 High, 3 Medium, 1 Low items resolved: added try/catch, threaded force param, removed dead param, cleaned up logging, consistent async
-
-### File List
-
-- `lib/bmad.js` — Added `os` require, `prePopulateBmadCache()` function, pre-population calls in 3 functions, `GIT_TERMINAL_PROMPT=0` env in 3 execSync calls, updated exports