ma-agents 3.5.6 → 3.6.0

package/test/instruction-block.test.js

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * Story 21.2 — Unit + integration tests for composeInstructionBlock and mergers.
+ *
+ * AC coverage:
+ *   5.1  Universal template reads and {{MANIFEST_PATH}} substitutes exactly once
+ *   5.2  standard profile returns universal-only (even when on-prem file exists)
+ *   5.3  on-prem profile appends on-prem content; throws when on-prem file missing
+ *   5.4  Idempotency — composer returns byte-identical output across calls
+ *   5.5  NFR44 — standard profile output lacks /no_think, str_replace_editor, ~/.claude/
+ *   5.6  Defensive — throws when universal template missing / no placeholder
+ *   5.7  Marker-block replace preserves content outside markers (two installs)
+ *   5.8  Fresh install writes universal block to markdown-merger agents
+ *   5.9  OpenCode json-merge receives composed string; other keys untouched;
+ *        second install replaces (not duplicates) ma-agents entry
+ *   5.10 Upgrade-safety: clean/drifted --yes warning + backup; no backup for clean
+ *   5.11 Backup filename format matches the canonical <target>.backup-<ISO-timestamp>
+ */
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  \u2713 ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  \u2717 ${name}: ${err.stack || err.message}`);
+    failed++;
+    errors.push({ name, error: err.message });
+  }
+}
+
+const installerModule = require('../lib/installer');
+const {
+  composeInstructionBlock,
+  buildBackupFilename,
+  formatBackupTimestamp,
+  _testUpdateAgentInstructions: updateAgentInstructions,
+  UNIVERSAL_INSTRUCTION_TEMPLATE_PATH,
+  ONPREM_INSTRUCTION_TEMPLATE_PATH
+} = installerModule;
+const { setProfile } = require('../lib/profile');
+const agents = require('../lib/agents');
+
+function mktemp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ma-agents-instr-block-test-'));
+}
+
+function cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+}
+
+console.log('\n instruction-block unit + integration tests (Story 21.2)\n');
+
+async function runAll() {
+  // 5.1 — Universal template reads + {{MANIFEST_PATH}} substitution
+  await test('5.1 composer returns universal template containing {{MANIFEST_PATH}} exactly once', () => {
+    const dir = mktemp();
+    try {
+      const out = composeInstructionBlock({ profile: 'standard', projectRoot: dir });
+      const matches = out.match(/\{\{MANIFEST_PATH\}\}/g) || [];
+      assert.strictEqual(matches.length, 1, 'expected exactly one {{MANIFEST_PATH}} placeholder');
+      // Post-composition substitution is caller-owned, verify a literal replace works
+      const substituted = out.replace(/\{\{MANIFEST_PATH\}\}/g, '.claude/skills/MANIFEST.yaml');
+      assert.ok(substituted.includes('.claude/skills/MANIFEST.yaml'));
+      assert.ok(!substituted.includes('{{MANIFEST_PATH}}'));
+    } finally { cleanup(dir); }
+  });
+
+  // 5.2 — standard profile returns universal only even when on-prem template exists
+  await test('5.2 standard profile returns universal-only content', () => {
+    const dir = mktemp();
+    try {
+      // Universal template ships with the package; just verify profile='standard' returns it without any on-prem sentinel
+      const out = composeInstructionBlock({ profile: 'standard', projectRoot: dir });
+      assert.ok(out.includes('# AI Agent Skills - Planning Instruction'));
+      // We don't write to lib/templates/ from tests (guarded by AC #9 isolation rules).
+      // Instead we assert that standard output is independent of the on-prem file's existence.
+      const withoutOnprem = composeInstructionBlock({ profile: 'standard', projectRoot: dir });
+      assert.strictEqual(out, withoutOnprem);
+    } finally { cleanup(dir); }
+  });
+
+  // 5.3a — on-prem throws when on-prem template is absent (decision A: NO silent fallback)
+  await test('5.3a on-prem profile throws when instruction-block-onprem.template.md is missing', () => {
+    // ONPREM_INSTRUCTION_TEMPLATE_PATH is the canonical ship-path. If the package
+    // does not include the on-prem template yet (Story 21.6 ships it), the composer
+    // must throw the pinned error. This test skips itself if the file is already present.
+    if (fs.existsSync(ONPREM_INSTRUCTION_TEMPLATE_PATH)) {
+      console.log('    (skipped — on-prem template already present; verified in 5.3b)');
+      return;
+    }
+    assert.throws(
+      () => composeInstructionBlock({ profile: 'on-prem', projectRoot: mktemp() }),
+      /on-prem profile selected but instruction-block-onprem\.template\.md is missing/
+    );
+  });
+
+  // 5.3b — on-prem appends on-prem content when template file is present
+  await test('5.3b on-prem profile appends on-prem content when file present (simulated via temp template)', () => {
+    // To test without modifying ship-files, we write a sibling on-prem template to the
+    // canonical location only if absent, exercise the composer, and delete it afterward.
+    // This is the same tmp-file discipline as profile.test.js.
+    if (fs.existsSync(ONPREM_INSTRUCTION_TEMPLATE_PATH)) {
+      // File genuinely exists (Story 21.6 shipped) — exercise directly.
+      const out = composeInstructionBlock({ profile: 'on-prem', projectRoot: mktemp() });
+      assert.ok(out.includes('# AI Agent Skills - Planning Instruction'));
+      return;
+    }
+    const sentinel = '## [TEST] On-prem sentinel marker ONPREM-SENTINEL-12345';
+    fs.writeFileSync(ONPREM_INSTRUCTION_TEMPLATE_PATH, sentinel + '\n', 'utf-8');
+    try {
+      const out = composeInstructionBlock({ profile: 'on-prem', projectRoot: mktemp() });
+      assert.ok(out.includes('# AI Agent Skills - Planning Instruction'), 'universal content should be present');
+      assert.ok(out.includes('ONPREM-SENTINEL-12345'), 'on-prem sentinel should be appended');
+      // There should be exactly one blank line separating universal from on-prem
+      // i.e., the joined string contains "\n\n" between the last universal line and the first on-prem line.
+      const splitIdx = out.indexOf('ONPREM-SENTINEL');
+      assert.ok(splitIdx > 0);
+      const preceding = out.slice(0, splitIdx);
+      assert.ok(/\n\n[^\n]*ONPREM-SENTINEL/.test(out), 'expected single blank line between universal and on-prem');
+      void preceding;
+    } finally {
+      try { fs.unlinkSync(ONPREM_INSTRUCTION_TEMPLATE_PATH); } catch {}
+    }
+  });
+
+  // 5.4 — Idempotency
+  await test('5.4 composer is idempotent (byte-identical across calls)', () => {
+    const dir = mktemp();
+    try {
+      const a = composeInstructionBlock({ profile: 'standard', projectRoot: dir });
+      const b = composeInstructionBlock({ profile: 'standard', projectRoot: dir });
+      assert.strictEqual(a, b);
+    } finally { cleanup(dir); }
+  });
+
+  // 5.5 — NFR44: no local-LLM-specific strings in standard profile
+  await test('5.5 NFR44 — standard profile output lacks /no_think, str_replace_editor, ~/.claude/', () => {
+    const out = composeInstructionBlock({ profile: 'standard', projectRoot: mktemp() });
+    assert.ok(!out.includes('/no_think'), 'contains forbidden /no_think');
+    assert.ok(!out.includes('str_replace_editor'), 'contains forbidden str_replace_editor');
+    assert.ok(!out.includes('~/.claude/'), 'contains forbidden ~/.claude/');
+  });
+
+  // 5.6 — defensive throw
+  await test('5.6 composer throws when universal template is missing', () => {
+    // Temporarily rename the universal template to simulate absence.
+    const bak = UNIVERSAL_INSTRUCTION_TEMPLATE_PATH + '.bak-test';
+    fs.renameSync(UNIVERSAL_INSTRUCTION_TEMPLATE_PATH, bak);
+    try {
+      assert.throws(
+        () => composeInstructionBlock({ profile: 'standard', projectRoot: mktemp() }),
+        /universal instruction template not found/
+      );
+    } finally {
+      fs.renameSync(bak, UNIVERSAL_INSTRUCTION_TEMPLATE_PATH);
+    }
+  });
+
+  // 5.7 — Marker-block replace preserves surrounding content across two installs
+  await test('5.7 Marker-block replace preserves content outside markers (two installs)', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const claudeMdPath = path.join(dir, '.claude', 'CLAUDE.md');
+      fs.mkdirSync(path.dirname(claudeMdPath), { recursive: true });
+      const before = '# My Project\n\nUser notes above.\n';
+      const after = '\n## Trailing section\n\nMore notes.\n';
+      // Write a file with pre-existing markers wrapping old content
+      const preMarker = '<!-- MA-AGENTS-START -->\nOLD STALE CONTENT\n<!-- MA-AGENTS-END -->';
+      fs.writeFileSync(claudeMdPath, before + preMarker + after, 'utf-8');
+
+      const agent = agents.getAgent('claude-code');
+      await updateAgentInstructions(agent, dir);
+      const first = fs.readFileSync(claudeMdPath, 'utf-8');
+      assert.ok(first.startsWith(before), 'pre-marker content byte-preserved');
+      assert.ok(first.endsWith(after), 'post-marker content byte-preserved');
+      assert.ok(!first.includes('OLD STALE CONTENT'));
+
+      await updateAgentInstructions(agent, dir);
+      const second = fs.readFileSync(claudeMdPath, 'utf-8');
+      assert.strictEqual(first, second, 'idempotent: second install byte-identical to first');
+    } finally { cleanup(dir); }
+  });
+
+  // 5.8 — Fresh install writes universal block for each markdown-merger agent
+  await test('5.8 Fresh install writes universal block to markdown-merger agents', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const agent = agents.getAgent('claude-code');
+      const cwdOriginal = process.cwd();
+      process.chdir(dir);
+      try {
+        await updateAgentInstructions(agent, dir);
+      } finally {
+        process.chdir(cwdOriginal);
+      }
+      const p = path.join(dir, '.claude', 'CLAUDE.md');
+      assert.ok(fs.existsSync(p), 'instruction file created');
+      const content = fs.readFileSync(p, 'utf-8');
+      assert.ok(content.includes('<!-- MA-AGENTS-START -->'));
+      assert.ok(content.includes('<!-- MA-AGENTS-END -->'));
+      assert.ok(content.includes('# AI Agent Skills - Planning Instruction'));
+      assert.ok(content.includes('Respond in TEXT vs. create FILES'), 'universal rule section present');
+      assert.ok(content.includes('BMAD phase discipline'), 'phase-discipline section present');
+    } finally { cleanup(dir); }
+  });
+
+  // 5.9 — OpenCode json-merge path (NFR18)
+  await test('5.9 OpenCode json-merge receives composed string; other keys untouched; re-install replaces entry', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const opencode = agents.getAgent('opencode');
+      if (!opencode) {
+        console.log('    (skipped — opencode agent not registered in lib/agents.js)');
+        return;
+      }
+      // Seed opencode.json with a user entry and an unrelated key to guard NFR18.
+      const filePath = path.join(dir, opencode.instructionFiles[0]);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify({
+        instructions: ['user-kept-entry'],
+        somethingElse: { keep: true, count: 42 }
+      }, null, 2), 'utf-8');
+
+      const cwdOriginal = process.cwd();
+      process.chdir(dir);
+      try {
+        await updateAgentInstructions(opencode, dir);
+      } finally {
+        process.chdir(cwdOriginal);
+      }
+
+      let data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      assert.deepStrictEqual(data.somethingElse, { keep: true, count: 42 }, 'unrelated keys untouched');
+      assert.ok(Array.isArray(data.instructions));
+      assert.ok(data.instructions.includes('user-kept-entry'), 'user entry preserved');
+      const maEntries = data.instructions.filter(e => typeof e === 'string' && e.startsWith('[ma-agents]'));
+      assert.strictEqual(maEntries.length, 1, 'exactly one ma-agents entry');
+      assert.ok(maEntries[0].includes('# AI Agent Skills - Planning Instruction'));
+      assert.ok(maEntries[0].includes('Respond in TEXT vs. create FILES'));
+      // Placeholder must have been substituted AFTER composition
+      assert.ok(!maEntries[0].includes('{{MANIFEST_PATH}}'));
+
+      // Re-install — should replace, not duplicate
+      process.chdir(dir);
+      try {
+        await updateAgentInstructions(opencode, dir);
+      } finally {
+        process.chdir(cwdOriginal);
+      }
+      data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      const maEntries2 = data.instructions.filter(e => typeof e === 'string' && e.startsWith('[ma-agents]'));
+      assert.strictEqual(maEntries2.length, 1, 'still exactly one ma-agents entry after re-install');
+      assert.ok(data.instructions.includes('user-kept-entry'), 'user entry still preserved');
+    } finally { cleanup(dir); }
+  });
+
+  // 5.10a — Clean re-install: no warning, no backup
+  await test('5.10a Upgrade-safety — clean marker block produces no backup on re-install', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const agent = agents.getAgent('claude-code');
+      await updateAgentInstructions(agent, dir);
+      const targetPath = path.join(dir, '.claude', 'CLAUDE.md');
+      const siblingBefore = fs.readdirSync(path.dirname(targetPath));
+      await updateAgentInstructions(agent, dir);
+      const siblingAfter = fs.readdirSync(path.dirname(targetPath));
+      const backupsBefore = siblingBefore.filter(n => n.startsWith('CLAUDE.md.backup-'));
+      const backupsAfter = siblingAfter.filter(n => n.startsWith('CLAUDE.md.backup-'));
+      assert.strictEqual(backupsBefore.length, 0);
+      assert.strictEqual(backupsAfter.length, 0, 'clean re-install must not create a backup');
+    } finally { cleanup(dir); }
+  });
+
+  // 5.10b — Hand-edited marker block with yesMode: WARNING emitted + backup file created
+  await test('5.10b Upgrade-safety — hand-edited block + yesMode emits WARNING and writes backup', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const agent = agents.getAgent('claude-code');
+      // Seed an existing file with a hand-edited marker block
+      const targetPath = path.join(dir, '.claude', 'CLAUDE.md');
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      const handEdited = '<!-- MA-AGENTS-START -->\nHAND EDITED STALE CONTENT\n<!-- MA-AGENTS-END -->';
+      fs.writeFileSync(targetPath, 'prefix\n' + handEdited + '\nsuffix\n', 'utf-8');
+
+      // Capture console.log to verify WARNING line
+      const origLog = console.log;
+      let captured = '';
+      console.log = (...args) => { captured += args.join(' ') + '\n'; };
+      // Force yesMode via env flag honored by the drift handler
+      const origYes = process.env.MA_AGENTS_YES;
+      process.env.MA_AGENTS_YES = '1';
+      try {
+        await updateAgentInstructions(agent, dir);
+      } finally {
+        console.log = origLog;
+        if (origYes === undefined) delete process.env.MA_AGENTS_YES;
+        else process.env.MA_AGENTS_YES = origYes;
+      }
+
+      assert.ok(
+        captured.includes('WARNING: ma-agents marker-block content modified since last install'),
+        'pinned WARNING line should be emitted'
+      );
+      assert.ok(captured.includes('backed up to'), 'WARNING must name the backup path');
+
+      const siblings = fs.readdirSync(path.dirname(targetPath));
+      const backups = siblings.filter(n => n.startsWith('CLAUDE.md.backup-'));
+      assert.strictEqual(backups.length, 1, 'exactly one backup created');
+      const backupContent = fs.readFileSync(path.join(path.dirname(targetPath), backups[0]), 'utf-8');
+      // Backup contains ONLY the marker-block region including marker lines
+      assert.strictEqual(backupContent, handEdited, 'backup contains only the marker-block region');
+
+      // Prefix/suffix outside markers preserved after overwrite
+      const afterContent = fs.readFileSync(targetPath, 'utf-8');
+      assert.ok(afterContent.startsWith('prefix\n'), 'prefix preserved');
+      assert.ok(afterContent.endsWith('suffix\n'), 'suffix preserved');
+      assert.ok(!afterContent.includes('HAND EDITED STALE CONTENT'));
+    } finally { cleanup(dir); }
+  });
+
+  // 5.10c — opts.yesMode (passed by cli.js --yes) takes precedence over absent env var
+  await test('5.10c Upgrade-safety — opts.yesMode bypasses interactive prompt without env var', async () => {
+    const dir = mktemp();
+    try {
+      setProfile(dir, 'standard');
+      const agent = agents.getAgent('claude-code');
+      const targetPath = path.join(dir, '.claude', 'CLAUDE.md');
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, 'prefix\n<!-- MA-AGENTS-START -->\nDRIFT\n<!-- MA-AGENTS-END -->\nsuffix\n', 'utf-8');
+
+      // Ensure env var is NOT set
+      const origYes = process.env.MA_AGENTS_YES;
+      delete process.env.MA_AGENTS_YES;
+      const origLog = console.log;
+      let captured = '';
+      console.log = (...args) => { captured += args.join(' ') + '\n'; };
+      try {
+        await updateAgentInstructions(agent, dir, { yesMode: true });
+      } finally {
+        console.log = origLog;
+        if (origYes !== undefined) process.env.MA_AGENTS_YES = origYes;
+      }
+      assert.ok(
+        captured.includes('WARNING: ma-agents marker-block content modified since last install'),
+        'opts.yesMode should route through non-interactive WARNING path'
+      );
+      const backups = fs.readdirSync(path.dirname(targetPath)).filter(n => n.startsWith('CLAUDE.md.backup-'));
+      assert.strictEqual(backups.length, 1, 'backup written via opts.yesMode path');
+    } finally { cleanup(dir); }
+  });
+
+  // 5.11 — Backup filename format matches canonical
+  await test('5.11 buildBackupFilename produces <target>.backup-<ISO-timestamp> with hyphens not colons', () => {
+    const fixed = new Date('2026-04-15T12:30:00.000Z');
+    const name = buildBackupFilename('.roomodes', fixed);
+    assert.strictEqual(name, '.roomodes.backup-2026-04-15T12-30-00Z');
+    assert.ok(!name.includes(':'), 'no colons allowed (Windows filename safety)');
+    const ts = formatBackupTimestamp(fixed);
+    assert.strictEqual(ts, '2026-04-15T12-30-00Z');
+  });
+
+  console.log(`\n ${passed} passed, ${failed} failed\n`);
+  if (failed > 0) {
+    errors.forEach(e => console.error(`   ${e.name}: ${e.error}`));
+    process.exit(1);
+  }
+}
+
+runAll().catch(err => {
+  console.error('Unhandled error:', err);
+  process.exit(1);
+});

package/test/integration-verification.test.js

@@ -184,11 +184,11 @@ console.log('\nTask 1 — End-to-end IDE agent test');
           `lib/bmad-extension/agents/ must have 0 .customize.yaml files after Story 15.6, found ${agentFiles.length}`);
       }
 
-      // 8 built-in customize.yaml files now in lib/bmad-customize/
+      // 10 built-in customize.yaml files now in lib/bmad-customize/
       const customizeDir = path.join(__dirname, '..', 'lib', 'bmad-customize');
       assert.ok(await fs.pathExists(customizeDir), 'lib/bmad-customize/ must exist');
       const files = (await fs.readdir(customizeDir)).filter(f => f.endsWith('.customize.yaml'));
-      assert.strictEqual(files.length, 8, `Expected 8 .customize.yaml files in bmad-customize/, found ${files.length}`);
+      assert.strictEqual(files.length, 10, `Expected 10 .customize.yaml files in bmad-customize/, found ${files.length}`);
     });
 
     // Task 2.2 (continued): Verify deployment via fs.copy

package/test/migration-validation.test.js

@@ -438,10 +438,10 @@ test('6.2: bmad.js applyCustomizations is exported', () => {
   assert.ok(typeof bmad.applyCustomizations === 'function', 'applyCustomizations must be exported');
 });
 
-test('6.3: lib/bmad-customize/ has exactly 8 built-in agent files', () => {
+test('6.3: lib/bmad-customize/ has exactly 10 built-in agent files', () => {
   assert.ok(fs.existsSync(CUSTOMIZE_DIR), 'lib/bmad-customize/ must exist');
   const files = fs.readdirSync(CUSTOMIZE_DIR).filter(f => f.endsWith('.customize.yaml'));
-  assert.strictEqual(files.length, 8, `Expected 8 built-in agent files, found ${files.length}`);
+  assert.strictEqual(files.length, 10, `Expected 10 built-in agent files, found ${files.length}`);
 });
 
 const BUILTIN_AGENTS = [

package/test/offline-recompile.test.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * Regression tests for bug-bmad-recompile-fails-on-airgapped-network.
+ *
+ * bmad-method 6.2.2's installer unconditionally performs `git fetch` /
+ * `git clone` / `npm install` against external module repos. On an
+ * air-gapped host those commands fail and lib/bmad.js used to swallow the
+ * error with a one-line red banner ("BMAD recompile failed: ..."). These
+ * tests lock in the new offline-safe classifier behaviour:
+ *
+ *   - Offline declared + cache intact -> WARN (downgrade)
+ *   - Offline declared + cache missing -> ERROR (actionable remediation)
+ *   - Not offline and error doesn't look offline -> RETHROW (loud failure)
+ *
+ * We mock the cache inspector and the environment so the test runs
+ * deterministically and cross-platform (including in CI where ~/.bmad may
+ * not exist). No real subprocess is spawned.
+ */
+'use strict';
+
+const assert = require('assert');
+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 });
+    }
+}
+
+console.log('\nBug: BMAD recompile on air-gapped network\n');
+
+const bmad = require('../lib/bmad');
+
+// ---- isOfflineModeDeclared ----
+
+console.log('isOfflineModeDeclared()');
+
+test('returns false when env is unset', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    delete process.env.MA_AGENTS_OFFLINE;
+    try {
+        assert.strictEqual(bmad.isOfflineModeDeclared(), false);
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+    }
+});
+
+test('returns true for "1", "true", "yes" (case-insensitive)', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    try {
+        for (const v of ['1', 'true', 'TRUE', 'yes', 'YES']) {
+            process.env.MA_AGENTS_OFFLINE = v;
+            assert.strictEqual(bmad.isOfflineModeDeclared(), true, `failed for ${v}`);
+        }
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+        else delete process.env.MA_AGENTS_OFFLINE;
+    }
+});
+
+test('returns false for "0", "false", empty', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    try {
+        for (const v of ['0', 'false', '', 'no']) {
+            process.env.MA_AGENTS_OFFLINE = v;
+            assert.strictEqual(bmad.isOfflineModeDeclared(), false, `failed for "${v}"`);
+        }
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+        else delete process.env.MA_AGENTS_OFFLINE;
+    }
+});
+
+// ---- looksLikeOfflineFailure ----
+
+console.log('\nlooksLikeOfflineFailure()');
+
+test('detects ENOTFOUND', () => {
+    const err = new Error('getaddrinfo ENOTFOUND github.com');
+    assert.strictEqual(bmad.looksLikeOfflineFailure(err), true);
+});
+
+test('detects git fetch failure', () => {
+    const err = new Error("Command failed: git fetch origin --depth 1\nfatal: unable to access 'https://github.com/...': Could not resolve host");
+    assert.strictEqual(bmad.looksLikeOfflineFailure(err), true);
+});
+
+test('detects connection refused / timed out', () => {
+    assert.strictEqual(
+        bmad.looksLikeOfflineFailure(new Error('connect ECONNREFUSED 140.82.114.3:443')),
+        true,
+    );
+    assert.strictEqual(
+        bmad.looksLikeOfflineFailure(new Error('connect ETIMEDOUT')),
+        true,
+    );
+});
+
+test('ignores non-network failures', () => {
+    assert.strictEqual(
+        bmad.looksLikeOfflineFailure(new Error('SyntaxError in agent.yaml at line 42')),
+        false,
+    );
+    assert.strictEqual(bmad.looksLikeOfflineFailure(null), false);
+    assert.strictEqual(bmad.looksLikeOfflineFailure(undefined), false);
+});
+
+test('inspects stderr/stdout properties too', () => {
+    const err = new Error('Command failed');
+    err.stderr = 'fatal: unable to access https://github.com/bmad-code-org/...';
+    assert.strictEqual(bmad.looksLikeOfflineFailure(err), true);
+});
+
+// ---- classifyRecompileFailure ----
+
+console.log('\nclassifyRecompileFailure()');
+
+const intactCache = () => ({
+    present: ['bmb', 'cis', 'gds', 'tea', 'wds'],
+    missing: [],
+    intact: true,
+    cacheDir: '/fake/.bmad/cache/external-modules',
+});
+
+const missingCache = () => ({
+    present: ['bmb'],
+    missing: ['cis', 'gds', 'tea', 'wds'],
+    intact: false,
+    cacheDir: '/fake/.bmad/cache/external-modules',
+});
+
+test('rethrows loudly when error does not look offline and offline not declared', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    delete process.env.MA_AGENTS_OFFLINE;
+    try {
+        const result = bmad.classifyRecompileFailure(
+            new Error('SyntaxError in customize.yaml'),
+            { cacheInspector: intactCache },
+        );
+        assert.strictEqual(result.action, 'rethrow');
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+    }
+});
+
+test('warns and proceeds when offline declared and cache intact', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    process.env.MA_AGENTS_OFFLINE = '1';
+    try {
+        const result = bmad.classifyRecompileFailure(
+            new Error('getaddrinfo ENOTFOUND github.com'),
+            { cacheInspector: intactCache },
+        );
+        assert.strictEqual(result.action, 'warn');
+        assert.ok(result.message.includes('vendored cache is intact'));
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+        else delete process.env.MA_AGENTS_OFFLINE;
+    }
+});
+
+test('warns when offline is merely inferred (error looks like network) and cache intact', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    delete process.env.MA_AGENTS_OFFLINE;
+    try {
+        const result = bmad.classifyRecompileFailure(
+            new Error("fatal: unable to access 'https://github.com/...': Could not resolve host"),
+            { cacheInspector: intactCache },
+        );
+        assert.strictEqual(result.action, 'warn');
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+    }
+});
+
+test('emits actionable error when offline and cache incomplete', () => {
+    const prev = process.env.MA_AGENTS_OFFLINE;
+    process.env.MA_AGENTS_OFFLINE = '1';
+    try {
+        const result = bmad.classifyRecompileFailure(
+            new Error('getaddrinfo ENOTFOUND github.com'),
+            { cacheInspector: missingCache },
+        );
+        assert.strictEqual(result.action, 'error');
+        assert.deepStrictEqual(result.missing, ['cis', 'gds', 'tea', 'wds']);
+        assert.ok(
+            result.message.includes('npm run build:bmad-cache'),
+            'error should include actionable remediation command',
+        );
+        assert.ok(
+            result.message.includes('/fake/.bmad/cache/external-modules'),
+            'error should include cache path',
+        );
+    } finally {
+        if (prev !== undefined) process.env.MA_AGENTS_OFFLINE = prev;
+        else delete process.env.MA_AGENTS_OFFLINE;
+    }
+});
+
+// ---- inspectBmadCache (lightweight integration — uses real manifest) ----
+
+console.log('\ninspectBmadCache()');
+
+test('reads real cache-manifest.json and reports expected modules', () => {
+    // Point at a directory that doesn't exist so every module is "missing"
+    // — the test just verifies we consult the manifest correctly.
+    const result = bmad.inspectBmadCache(path.join(__dirname, '__nonexistent_cache__'));
+    assert.ok(Array.isArray(result.present));
+    assert.ok(Array.isArray(result.missing));
+    // cache-manifest.json ships with bmb/cis/gds/tea/wds
+    assert.ok(
+        result.missing.includes('bmb'),
+        `expected bmb in missing, got: ${JSON.stringify(result.missing)}`,
+    );
+    assert.strictEqual(result.intact, false);
+});
+
+// ---- Summary ----
+
+console.log(`\n${passed} passed, ${failed} failed\n`);
+if (failed > 0) {
+    for (const { name, err } of errors) {
+        console.error(`FAIL: ${name}`);
+        console.error(err.stack || err);
+    }
+    process.exit(1);
+}