ma-agents 2.22.2 → 3.0.0

package/test/bmad-extension.test.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 /**
- * Tests for Story 8.3: Create BMAD Extension Module Structure
+ * Tests for BMAD Extension Module and Built-in Agent Customizations
  *
- * Validates extension module files, directory structure, customize.yaml contents,
- * and deployment logic in bmad.js.
+ * Story 8.3: Extension module structure (module.yaml, module-help.csv, workflows)
+ * Story 15.6: Built-in agent customizations separated to lib/bmad-customize/
+ *
+ * Validates extension module files, directory structure, built-in customize.yaml
+ * contents, and deployment logic in bmad.js.
  */
 'use strict';
 
@@ -28,9 +31,9 @@ function test(name, fn) {
 }
 
 const extDir = path.join(__dirname, '..', 'lib', 'bmad-extension');
-const agentsDir = path.join(extDir, 'agents');
+const customizeDir = path.join(__dirname, '..', 'lib', 'bmad-customize');
 
-// ─── AC #1: module.yaml, module-help.csv, and 11 agent files exist ──────────
+// ─── AC #1: Extension module structure (module.yaml, module-help.csv, workflows) ──
 
 console.log('\nAC #1 — Extension module structure');
 
@@ -38,8 +41,15 @@ test('1.1: lib/bmad-extension/ directory exists', () => {
   assert.ok(fs.existsSync(extDir), 'lib/bmad-extension/ must exist');
 });
 
-test('1.2: lib/bmad-extension/agents/ directory exists', () => {
-  assert.ok(fs.existsSync(agentsDir), 'lib/bmad-extension/agents/ must exist');
+test('1.2: lib/bmad-extension/agents/ has no .customize.yaml files (Story 15.6)', () => {
+  const agentsDir = path.join(extDir, 'agents');
+  // bmad-method may recreate an empty agents/ dir when processing --custom-content,
+  // so we check for absence of customize files, not absence of the directory itself.
+  if (fs.existsSync(agentsDir)) {
+    const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.customize.yaml'));
+    assert.strictEqual(files.length, 0, `agents/ must have 0 .customize.yaml files, found ${files.length}`);
+  }
+  // If directory doesn't exist, that's also correct
 });
 
 test('1.3: module.yaml exists with extends-module: bmm', () => {
@@ -47,7 +57,7 @@ test('1.3: module.yaml exists with extends-module: bmm', () => {
   assert.ok(fs.existsSync(filePath), 'module.yaml must exist');
   const content = fs.readFileSync(filePath, 'utf-8');
   assert.ok(content.includes('extends-module: bmm'), 'module.yaml must declare extends-module: bmm');
-  assert.ok(content.includes('name: ma-agents-skills'), 'module.yaml must have name: ma-agents-skills');
+  assert.ok(content.includes('name: "MA-Agents Skills & Agents"'), 'module.yaml must have name: "MA-Agents Skills & Agents"');
 });
 
 test('1.4: module-help.csv exists', () => {
@@ -55,81 +65,79 @@ test('1.4: module-help.csv exists', () => {
   assert.ok(fs.existsSync(filePath), 'module-help.csv must exist');
 });
 
-test('1.5: agents/ contains exactly 11 .customize.yaml files', () => {
-  const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.customize.yaml'));
-  assert.strictEqual(files.length, 11, `Expected 11 .customize.yaml files, found ${files.length}`);
+test('1.5: workflows/ directory exists in extension module', () => {
+  const workflowsDir = path.join(extDir, 'workflows');
+  assert.ok(fs.existsSync(workflowsDir), 'lib/bmad-extension/workflows/ must exist');
 });
 
-// ─── AC #2: 4 custom agents have full customization + critical_actions ──────
-
-console.log('\nAC #2 — Custom agents: persona + menu + critical_actions');
-
-const customAgents = [
-  { id: 'bmm-sre', slug: 'sre' },
-  { id: 'bmm-devops', slug: 'devops' },
-  { id: 'bmm-cyber', slug: 'cyber' },
-  { id: 'bmm-mil498', slug: 'mil498' }
-];
+// ─── AC #2: 8 built-in agents in lib/bmad-customize/ with critical_actions only ──
 
-for (const agent of customAgents) {
-  test(`2.${customAgents.indexOf(agent) + 1}: ${agent.id}.customize.yaml has persona, menu, AND critical_actions`, () => {
-    const filePath = path.join(agentsDir, `${agent.id}.customize.yaml`);
-    assert.ok(fs.existsSync(filePath), `${agent.id}.customize.yaml must exist`);
-    const content = fs.readFileSync(filePath, 'utf-8');
-
-    assert.ok(content.includes('persona:'), `${agent.id} must have persona section`);
-    assert.ok(content.includes('menu:'), `${agent.id} must have menu section`);
-    assert.ok(content.includes('critical_actions:'), `${agent.id} must have critical_actions section`);
-    assert.ok(content.includes(`skills/${agent.slug}/MANIFEST.yaml`),
-      `${agent.id} critical_actions must reference skills/${agent.slug}/MANIFEST.yaml`);
-  });
-}
+console.log('\nAC #2 — Built-in agent customizations in lib/bmad-customize/');
 
-test('2.5: custom agent critical_actions have all 3 steps', () => {
-  for (const agent of customAgents) {
-    const content = fs.readFileSync(path.join(agentsDir, `${agent.id}.customize.yaml`), 'utf-8');
-    assert.ok(content.includes('1:'), `${agent.id} must have step 1`);
-    assert.ok(content.includes('2:'), `${agent.id} must have step 2`);
-    assert.ok(content.includes('3:'), `${agent.id} must have step 3`);
-    assert.ok(content.includes('always_load: true'), `${agent.id} step 2 must reference always_load`);
-    assert.ok(content.includes('Follow all skill directives'), `${agent.id} step 3 must follow directives`);
-  }
+test('2.1: lib/bmad-customize/ directory exists', () => {
+  assert.ok(fs.existsSync(customizeDir), 'lib/bmad-customize/ must exist');
 });
 
-// ─── AC #3: 7 built-in agents have ONLY critical_actions ────────────────────
-
-console.log('\nAC #3 — Built-in agents: critical_actions only');
-
 const builtinAgents = [
   'bmm-pm', 'bmm-architect', 'bmm-dev', 'bmm-qa',
-  'bmm-sm', 'bmm-tech-writer', 'bmm-ux-designer'
+  'bmm-sm', 'bmm-tech-writer', 'bmm-ux-designer', 'bmm-bmad-master'
 ];
 
+test('2.2: lib/bmad-customize/ contains exactly 8 .customize.yaml files', () => {
+  const files = fs.readdirSync(customizeDir).filter(f => f.endsWith('.customize.yaml'));
+  assert.strictEqual(files.length, 8, `Expected 8 .customize.yaml files, found ${files.length}`);
+});
+
 for (const agentId of builtinAgents) {
-  test(`3.${builtinAgents.indexOf(agentId) + 1}: ${agentId}.customize.yaml has ONLY critical_actions (no persona/menu)`, () => {
-    const filePath = path.join(agentsDir, `${agentId}.customize.yaml`);
+  test(`2.3-${agentId}: ${agentId}.customize.yaml exists with correct content`, () => {
+    const filePath = path.join(customizeDir, `${agentId}.customize.yaml`);
     assert.ok(fs.existsSync(filePath), `${agentId}.customize.yaml must exist`);
     const content = fs.readFileSync(filePath, 'utf-8');
 
+    // Must have critical_actions
     assert.ok(content.includes('critical_actions:'), `${agentId} must have critical_actions`);
+
+    // Must use 6.2.0 array syntax (- "...") not numbered keys (1: "...")
+    assert.ok(content.includes('  - "'), `${agentId} must use array syntax (- "...")`);
+    assert.ok(!content.match(/^\s+\d+:/m), `${agentId} must NOT use numbered key syntax`);
+
+    // Must NOT have persona or menu
     assert.ok(!content.includes('persona:'), `${agentId} must NOT have persona section`);
     assert.ok(!content.includes('menu:'), `${agentId} must NOT have menu section`);
+
+    // Must reference project-level skills/MANIFEST.yaml
     assert.ok(content.includes('skills/MANIFEST.yaml'), `${agentId} must reference project-level skills/MANIFEST.yaml`);
+
+    // Must have all 4 critical actions
+    assert.ok(content.includes('Read the skills MANIFEST'), `${agentId} must have MANIFEST read action`);
+    assert.ok(content.includes('always_load: true'), `${agentId} must reference always_load`);
+    assert.ok(content.includes('project-context.md'), `${agentId} must reference project-context.md`);
+    assert.ok(content.includes('Follow all skill directives'), `${agentId} must have follow directives action`);
+
+    // Must have agent-specific comment header
+    assert.ok(content.includes(`MA-AGENTS: skill enforcement for ${agentId}`),
+      `${agentId} must have agent-specific comment header`);
   });
 }
 
-// ─── AC #4: bmad.js has extension deployment stage ──────────────────────────
+// ─── AC #3: bmad.js has extension and customize deployment stages ─────────
 
-console.log('\nAC #4 — bmad.js extension deployment');
+console.log('\nAC #3 — bmad.js deployment logic');
 
-test('4.1: bmad.js contains extension deployment code', () => {
+test('3.1: bmad.js contains extension deployment code', () => {
   const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
   assert.ok(bmadSrc.includes("'bmad-extension'"), 'bmad.js must reference bmad-extension source dir');
   assert.ok(bmadSrc.includes("'extensions'"), 'bmad.js must reference extensions target dir');
   assert.ok(bmadSrc.includes("'ma-agents-skills'"), 'bmad.js must reference ma-agents-skills');
 });
 
-test('4.2: extension deployment uses path.join for all paths', () => {
+test('3.2: bmad.js contains customize deployment code', () => {
+  const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
+  assert.ok(bmadSrc.includes("'bmad-customize'"), 'bmad.js must reference bmad-customize source dir');
+  assert.ok(bmadSrc.includes('Applied built-in customization'), 'bmad.js must log built-in customization deployment');
+});
+
+test('3.3: extension deployment uses path.join for all paths', () => {
   const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
   assert.ok(bmadSrc.includes("path.join(__dirname, 'bmad-extension')"),
     'extensionSource must use path.join');
@@ -137,37 +145,53 @@ test('4.2: extension deployment uses path.join for all paths', () => {
     'extensionTarget must use path.join');
 });
 
-test('4.3: extension deployment is AFTER recompile and BEFORE workflows', () => {
-  // Uses STAGE: markers in bmad.js comments — these are test-coupled anchors (see M2 review)
+test('3.4: customize deployment uses path.join for source', () => {
+  const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
+  assert.ok(bmadSrc.includes("path.join(__dirname, 'bmad-customize')"),
+    'customizeSource must use path.join');
+});
+
+test('3.5: deployment order is RECOMPILE > EXTENSION > CUSTOMIZE > WORKFLOWS', () => {
   const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
   const recompileIdx = bmadSrc.indexOf('STAGE:RECOMPILE');
   const extensionIdx = bmadSrc.indexOf('STAGE:EXTENSION');
+  const customizeIdx = bmadSrc.indexOf('STAGE:CUSTOMIZE');
   const workflowIdx = bmadSrc.indexOf('STAGE:WORKFLOWS');
 
   assert.ok(recompileIdx > 0, 'STAGE:RECOMPILE marker must exist');
   assert.ok(extensionIdx > 0, 'STAGE:EXTENSION marker must exist');
+  assert.ok(customizeIdx > 0, 'STAGE:CUSTOMIZE marker must exist');
   assert.ok(workflowIdx > 0, 'STAGE:WORKFLOWS marker must exist');
   assert.ok(extensionIdx > recompileIdx, 'extension deployment must come after recompile');
-  assert.ok(extensionIdx < workflowIdx, 'extension deployment must come before workflows');
+  assert.ok(customizeIdx > extensionIdx, 'customize deployment must come after extension');
+  assert.ok(customizeIdx < workflowIdx, 'customize deployment must come before workflows');
 });
 
-test('4.4: extension deployment logs with chalk.cyan', () => {
+test('3.6: extension deployment logs with chalk.cyan', () => {
   const bmadSrc = fs.readFileSync(path.join(__dirname, '..', 'lib', 'bmad.js'), 'utf-8');
   assert.ok(bmadSrc.includes("chalk.cyan('    + Deployed BMAD extension module: ma-agents-skills')"),
     'must log deployment with chalk.cyan');
 });
 
-test('4.5: existing bmad-customizations files are preserved (backward compatibility)', () => {
+test('3.7: bmad-customizations retains platform and generic files (agent files removed in Epic 15)', () => {
   const customDir = path.join(__dirname, '..', 'lib', 'bmad-customizations');
-  for (const agent of customAgents) {
-    const filePath = path.join(customDir, `${agent.id}.customize.yaml`);
-    assert.ok(fs.existsSync(filePath), `${agent.id}.customize.yaml must still exist in bmad-customizations/`);
+  // Platform-specific and generic files must still exist
+  const expectedFiles = ['claude-code', 'cursor', 'cline', 'gemini', 'generic', 'antigravity'];
+  for (const name of expectedFiles) {
+    const filePath = path.join(customDir, `${name}.customize.yaml`);
+    assert.ok(fs.existsSync(filePath), `${name}.customize.yaml must still exist in bmad-customizations/`);
+  }
+  // Custom agent files (bmm-sre, bmm-devops, etc.) were removed — now in skill folders
+  const removedAgents = ['bmm-sre', 'bmm-devops', 'bmm-cyber', 'bmm-mil498'];
+  for (const id of removedAgents) {
+    const filePath = path.join(customDir, `${id}.customize.yaml`);
+    assert.ok(!fs.existsSync(filePath), `${id}.customize.yaml should NOT exist in bmad-customizations/ (moved to skill folders)`);
   }
 });
 
-// ─── M3: Integration test — actual fs.copy deployment ───────────────────────
+// ─── Integration tests — actual fs.copy deployment ───────────────────────
 
-console.log('\nIntegration — applyCustomizations() deploys extension');
+console.log('\nIntegration — applyCustomizations() deployment');
 
 const fsExtra = require('fs-extra');
 const os = require('os');
@@ -206,12 +230,34 @@ async function runIntegrationTests() {
     const content = fsExtra.readFileSync(deployedModule, 'utf-8');
     assert.ok(content.includes('extends-module: bmm'),
       'deployed module.yaml must contain extends-module: bmm');
+  });
+
+  await asyncTest('INT-2: applyCustomizations deploys built-in customizations to _bmad/_config/agents/', async () => {
+    // Verify built-in customizations were deployed to config dir
+    const configAgentsDir = path.join(tmpDir, '_bmad', '_config', 'agents');
+
+    for (const agentId of builtinAgents) {
+      const deployedFile = path.join(configAgentsDir, `${agentId}.customize.yaml`);
+      assert.ok(fsExtra.existsSync(deployedFile),
+        `${agentId}.customize.yaml must be deployed to _bmad/_config/agents/`);
+
+      const content = fsExtra.readFileSync(deployedFile, 'utf-8');
+      assert.ok(content.includes('critical_actions:'),
+        `deployed ${agentId}.customize.yaml must contain critical_actions`);
+      assert.ok(content.includes('skills/MANIFEST.yaml'),
+        `deployed ${agentId}.customize.yaml must reference skills/MANIFEST.yaml`);
+    }
+  });
 
-    // Verify agent files deployed
-    const deployedAgents = path.join(tmpDir, '_bmad', 'extensions', 'ma-agents-skills', 'agents');
-    assert.ok(fsExtra.existsSync(deployedAgents), 'agents/ directory must be deployed');
-    const files = fsExtra.readdirSync(deployedAgents).filter(f => f.endsWith('.customize.yaml'));
-    assert.strictEqual(files.length, 11, `Expected 11 deployed agent files, found ${files.length}`);
+  await asyncTest('INT-3: deployed customizations use array syntax not numbered keys', async () => {
+    const configAgentsDir = path.join(tmpDir, '_bmad', '_config', 'agents');
+
+    for (const agentId of builtinAgents) {
+      const deployedFile = path.join(configAgentsDir, `${agentId}.customize.yaml`);
+      const content = fsExtra.readFileSync(deployedFile, 'utf-8');
+      assert.ok(content.includes('  - "'), `deployed ${agentId} must use array syntax`);
+      assert.ok(!content.match(/^\s+\d+:/m), `deployed ${agentId} must NOT use numbered keys`);
+    }
   });
 
   // Cleanup

package/test/bmad-version-bump.test.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * Tests for Story 15.1: Bump bmad-method to 6.2.1 and Update Cache
+ *
+ * Task 1: Verify package.json dependency updated
+ * Task 2: Verify build:bmad-cache compatibility
+ * Task 3: Verify bmad.js CLI compatibility
+ * Task 4: Verify prePopulateBmadCache compatibility
+ */
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs-extra');
+const path = require('path');
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  \u2717 ${name}: ${err.message}`);
+    failed++;
+    errors.push({ name, err });
+  }
+}
+
+const projectRoot = path.resolve(__dirname, '..');
+
+console.log('\nStory 15.1: Bump bmad-method to 6.2.1 and Update Cache\n');
+
+// ---- Task 1: package.json dependency ----
+
+console.log('Task 1: package.json dependency');
+
+test('package.json pins bmad-method at 6.2.1', () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+  assert.strictEqual(pkg.dependencies['bmad-method'], '6.2.1');
+});
+
+test('installed bmad-method is version 6.2.1', () => {
+  const bmadPkg = JSON.parse(
+    fs.readFileSync(path.join(projectRoot, 'node_modules', 'bmad-method', 'package.json'), 'utf8')
+  );
+  assert.strictEqual(bmadPkg.version, '6.2.1');
+});
+
+test('require.resolve finds bmad-npx-wrapper.js', () => {
+  const resolved = require.resolve('bmad-method/tools/bmad-npx-wrapper.js');
+  assert.ok(resolved.includes('bmad-npx-wrapper.js'), `Unexpected path: ${resolved}`);
+  assert.ok(fs.existsSync(resolved), `File does not exist: ${resolved}`);
+});
+
+// ---- Task 2: build:bmad-cache compatibility ----
+
+console.log('\nTask 2: build:bmad-cache compatibility');
+
+test('external-official-modules.yaml exists in 6.2.1', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const yamlPath = path.join(bmadDir, 'tools', 'cli', 'external-official-modules.yaml');
+  assert.ok(fs.existsSync(yamlPath), `YAML not found at ${yamlPath}`);
+});
+
+test('YAML parser extracts 5 modules from 6.2.1', () => {
+  // Import the parser from build-bmad-cache.js by reading and evaluating it
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const yamlPath = path.join(bmadDir, 'tools', 'cli', 'external-official-modules.yaml');
+  const content = fs.readFileSync(yamlPath, 'utf8');
+
+  // Replicate the parser logic
+  const modules = [];
+  const lines = content.split('\n');
+  let inModules = false;
+  let currentModule = null;
+
+  for (const line of lines) {
+    const trimmed = line.trimEnd();
+    if (trimmed === '' || trimmed.match(/^\s*#/)) continue;
+    if (trimmed === 'modules:') { inModules = true; continue; }
+    if (!inModules) continue;
+
+    const moduleKeyMatch = trimmed.match(/^\s{1,4}([a-zA-Z0-9_-]+):\s*$/);
+    if (moduleKeyMatch) {
+      if (currentModule) modules.push(currentModule);
+      currentModule = { key: moduleKeyMatch[1] };
+      continue;
+    }
+
+    if (currentModule) {
+      const propMatch = trimmed.match(/^\s{2,8}([a-zA-Z0-9_-]+):\s+"([^"]*)"$/);
+      if (propMatch) {
+        currentModule[propMatch[1]] = propMatch[2];
+      } else {
+        const unquotedMatch = trimmed.match(/^\s{2,8}([a-zA-Z0-9_-]+):\s+(.+)$/);
+        if (unquotedMatch) {
+          currentModule[unquotedMatch[1]] = unquotedMatch[2].trim();
+        }
+      }
+    }
+  }
+  if (currentModule) modules.push(currentModule);
+
+  const parsed = modules.filter(m => m.code && m.url).map(m => ({
+    code: m.code,
+    url: m.url,
+    name: m.name || m.key,
+    branch: m.branch || 'main'
+  }));
+
+  assert.strictEqual(parsed.length, 5, `Expected 5 modules, got ${parsed.length}`);
+  const codes = parsed.map(m => m.code).sort();
+  assert.deepStrictEqual(codes, ['bmb', 'cis', 'gds', 'tea', 'wds']);
+});
+
+test('wds module is present in parsed YAML', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const yamlPath = path.join(bmadDir, 'tools', 'cli', 'external-official-modules.yaml');
+  const content = fs.readFileSync(yamlPath, 'utf8');
+  assert.ok(content.includes('code: wds'), 'wds module code not found in YAML');
+  assert.ok(content.includes('bmad-method-wds-expansion'), 'wds repo URL not found in YAML');
+});
+
+test('cache-manifest.json exists and lists 5 modules', () => {
+  const manifestPath = path.join(projectRoot, 'lib', 'bmad-cache', 'cache-manifest.json');
+  assert.ok(fs.existsSync(manifestPath), `Manifest not found at ${manifestPath}`);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const moduleCodes = Object.keys(manifest.modules);
+  assert.strictEqual(moduleCodes.length, 5, `Expected 5 modules in manifest, got ${moduleCodes.length}`);
+  assert.deepStrictEqual(moduleCodes.sort(), ['bmb', 'cis', 'gds', 'tea', 'wds']);
+});
+
+test('cache-manifest.json records bmadMethodVersion as 6.2.1', () => {
+  const manifestPath = path.join(projectRoot, 'lib', 'bmad-cache', 'cache-manifest.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  assert.strictEqual(manifest.bmadMethodVersion, '6.2.1');
+});
+
+test('each cached module has a commit SHA in manifest', () => {
+  const manifestPath = path.join(projectRoot, 'lib', 'bmad-cache', 'cache-manifest.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  for (const [code, info] of Object.entries(manifest.modules)) {
+    assert.ok(info.commitSha, `Module ${code} missing commitSha`);
+    assert.ok(info.commitSha.match(/^[a-f0-9]+$/), `Module ${code} has invalid SHA: ${info.commitSha}`);
+  }
+});
+
+test('lib/bmad-cache/wds/ directory exists with content', () => {
+  const wdsDir = path.join(projectRoot, 'lib', 'bmad-cache', 'wds');
+  assert.ok(fs.existsSync(wdsDir), `wds cache dir not found at ${wdsDir}`);
+  const entries = fs.readdirSync(wdsDir);
+  assert.ok(entries.length > 0, 'wds cache directory is empty');
+  assert.ok(entries.includes('_git_preserved'), 'wds missing _git_preserved directory');
+});
+
+test('all 5 cached modules have _git_preserved directory', () => {
+  const cacheDir = path.join(projectRoot, 'lib', 'bmad-cache');
+  const expected = ['bmb', 'cis', 'gds', 'tea', 'wds'];
+  for (const mod of expected) {
+    const preserved = path.join(cacheDir, mod, '_git_preserved');
+    assert.ok(fs.existsSync(preserved), `${mod} missing _git_preserved at ${preserved}`);
+  }
+});
+
+// ---- Task 3: bmad.js CLI compatibility ----
+
+console.log('\nTask 3: bmad.js CLI compatibility');
+
+const bmad = require('../lib/bmad');
+
+test('getBmadCommand resolves bmad-npx-wrapper.js from 6.2.1', () => {
+  const result = bmad.buildBmadArgs({
+    projectRoot: '/test',
+    modules: ['bmm'],
+    tools: [],
+    action: 'install',
+  });
+  assert.ok(result.includes('bmad-npx-wrapper.js'), `Expected wrapper path in: ${result}`);
+  assert.ok(result.startsWith('node "'), `Expected node command prefix: ${result}`);
+});
+
+test('buildBmadArgs generates valid --action update flag', () => {
+  const result = bmad.buildBmadArgs({
+    projectRoot: '/test',
+    modules: ['bmm', 'bmb'],
+    tools: ['claude-code'],
+    action: 'update',
+  });
+  assert.ok(result.includes('--action update'), `Expected --action update in: ${result}`);
+});
+
+test('6.2.1 CLI accepts --directory flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--directory'), '6.2.1 install.js missing --directory flag');
+});
+
+test('6.2.1 CLI accepts --modules flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--modules'), '6.2.1 install.js missing --modules flag');
+});
+
+test('6.2.1 CLI accepts --tools flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--tools'), '6.2.1 install.js missing --tools flag');
+});
+
+test('6.2.1 CLI accepts --custom-content flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--custom-content'), '6.2.1 install.js missing --custom-content flag');
+});
+
+test('6.2.1 CLI accepts --action flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--action'), '6.2.1 install.js missing --action flag');
+});
+
+test('6.2.1 CLI accepts --yes flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--yes'), '6.2.1 install.js missing --yes flag');
+});
+
+test('6.2.1 CLI accepts --user-name flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--user-name'), '6.2.1 install.js missing --user-name flag');
+});
+
+test('6.2.1 CLI accepts --communication-language flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--communication-language'), '6.2.1 install.js missing --communication-language flag');
+});
+
+test('6.2.1 CLI accepts --document-output-language flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--document-output-language'), '6.2.1 install.js missing --document-output-language flag');
+});
+
+test('6.2.1 CLI accepts --output-folder flag', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const installCmd = path.join(bmadDir, 'tools', 'cli', 'commands', 'install.js');
+  const content = fs.readFileSync(installCmd, 'utf8');
+  assert.ok(content.includes('--output-folder'), '6.2.1 install.js missing --output-folder flag');
+});
+
+test('module.yaml custom-content format is accepted by 6.2.1', () => {
+  const bmadDir = path.dirname(require.resolve('bmad-method/package.json'));
+  const handlerPath = path.join(bmadDir, 'tools', 'cli', 'installers', 'lib', 'custom', 'handler.js');
+  const content = fs.readFileSync(handlerPath, 'utf8');
+  // 6.2.1 still looks for module.yaml files
+  assert.ok(content.includes('module.yaml'), '6.2.1 handler.js no longer references module.yaml');
+});
+
+// ---- Task 4: prePopulateBmadCache compatibility ----
+
+console.log('\nTask 4: prePopulateBmadCache compatibility');
+
+test('prePopulateBmadCache is exported', () => {
+  assert.strictEqual(typeof bmad.prePopulateBmadCache, 'function');
+});
+
+test('prePopulateBmadCache source handles all cache modules dynamically', () => {
+  // The function iterates fs.readdir(cacheSource) and handles any number of modules
+  // No hardcoded module list = automatically handles 5 modules including wds
+  const bmadSource = fs.readFileSync(path.join(projectRoot, 'lib', 'bmad.js'), 'utf8');
+  assert.ok(bmadSource.includes('fs.readdir(cacheSource)'), 'prePopulateBmadCache should iterate cache directory');
+  assert.ok(!bmadSource.includes("'bmb'") || !bmadSource.includes("['bmb',"), 'prePopulateBmadCache should not hardcode module list');
+});
+
+test('restoreGitDir logic exists in bmad.js', () => {
+  const bmadSource = fs.readFileSync(path.join(projectRoot, 'lib', 'bmad.js'), 'utf8');
+  assert.ok(bmadSource.includes('restoreGitDir'), 'Missing restoreGitDir function');
+  assert.ok(bmadSource.includes('_git_preserved'), 'Missing _git_preserved reference');
+  assert.ok(bmadSource.includes('file://'), 'Missing file:// URL for offline fetch');
+});
+
+test('wds cache directory has src/ with module content', () => {
+  const wdsSrc = path.join(projectRoot, 'lib', 'bmad-cache', 'wds', 'src');
+  assert.ok(fs.existsSync(wdsSrc), `wds/src/ not found at ${wdsSrc}`);
+  const entries = fs.readdirSync(wdsSrc);
+  assert.ok(entries.length > 0, 'wds/src/ is empty');
+});
+
+// ---- Summary ----
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (errors.length > 0) {
+  console.log('\nFailures:');
+  errors.forEach(({ name, err }) => {
+    console.log(`  ${name}:`);
+    console.log(`    ${err.message}`);
+  });
+}
+process.exit(failed > 0 ? 1 : 0);