bmad-plus 0.12.2 → 0.13.0

package/tools/build/adapters.config.js

@@ -6,7 +6,7 @@
  * hand-written instruction they contained was folded into THIS file — the UNION
  * of all three pre-adoption root files, nothing dropped:
  *
- *   - Agents roster (personas + Hebrew names + pack qualifiers) — from all three
+ * Agent personas now live in registry.yaml; only repository-specific prose is here.
  *   - Skills paths (installed `.agents/` layout AND repo `src/bmad-plus/` layout)
  *   - Project Structure                                      — from GEMINI/AGENTS
  *   - Communication (user name + language policy)            — from CLAUDE
@@ -23,7 +23,7 @@
  *
  * Numbers policy: NO counts are hand-typed here (they drift — see audit DOC-06).
  * All counts live in the generated "Registry facts" section, derived from
- * registry.yaml. That is why the Shield line below carries no agent count.
+ * registry.yaml. Agent personas and their pack membership live there too.
  *
  * Author: Laurent Rochetta
  */
@@ -34,54 +34,7 @@
  * Markdown lines (LF-joined by the generator). Headings are `##` level so the
  * block nests directly under each generated file's H1.
  */
-const PROJECT_INSTRUCTIONS = [
-  '## Agents',
-  '',
-  'To activate an agent, say its name or persona:',
-  '',
-  '- **Atlas** (Strategist) — Business analysis + Product management',
-  '- **Forge** (Architect-Dev) — Architecture + Development + Documentation',
-  '- **Sentinel** (Quality) — QA + UX review',
-  '- **Nexus** (Orchestrator) — Sprint management + Autopilot + Parallel execution',
-  '- **Shadow** (OSINT) — Investigation + Scraping + Psychoprofiling (if OSINT pack installed)',
-  '- **Maker** (Agent Creator) — Design, build, validate, and package new BMAD+ agents',
-  '- **Shield** (GRC) — Compliance agents for GDPR, ISO 27001, SOC 2, HIPAA, EU AI Act, DORA, NIS2 and more (derived counts: see Registry facts below)',
-  '- **Miriam** (מרים) — Business Analyst — Strategic analysis, research, product briefs (Dev Studio)',
-  '- **Huldah** (חולדה) — Technical Writer — Documentation, diagrams, editorial review (Dev Studio)',
-  '- **Yosef** (יוסף) — Product Manager — PRD, requirements, feature prioritization (Dev Studio)',
-  '- **Rachel** (רחל) — UX Designer — User experience, wireframes, empathy mapping (Dev Studio)',
-  '- **Bezalel** (בצלאל) — System Architect — Architecture, ADRs, epics & stories (Dev Studio)',
-  '- **Oholiab** (אהליאב) — Senior Engineer — TDD, sprint, code review, implementation (Dev Studio)',
-  '- **Zecher** (זכר, Memory Guardian) — Memory Archivist — Persistent cross-session memory, consolidation, project scanning, context recall, session handoffs',
-  '',
-  '## Skills',
-  '',
-  '- Installed projects load skills from `.agents/skills/`; in this repository the sources live in `src/bmad-plus/skills/` and `src/bmad-plus/agents/`.',
-  '- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules.',
-  '- Auto-activation triggers: `.agents/data/role-triggers.yaml` (source: `src/bmad-plus/data/role-triggers.yaml`).',
-  '',
-  '## Project Structure',
-  '',
-  '- `src/bmad-plus/` — Custom module (agents, skills, data)',
-  '- `monitor/` — Upstream monitoring system (VPS)',
-  '- `mcp-server/` — Audit 360° MCP Server',
-  '- `osint-agent-package/` — OSINT package',
-  '- `upstream/` — BMAD-METHOD reference clone',
-  '',
-  '## Communication',
-  '',
-  '- User name: laurent',
-  '- Default language: Français for user-facing content, English for code and technical docs.',
-  '',
-  '## Commit Rules',
-  '',
-  '- NEVER add "Co-Authored-By: Claude" or any AI co-author attribution.',
-  '- The sole author is Laurent Rochetta.',
-  '',
-  '## Repository Maintenance Rule',
-  '',
-  'When updating the main README.md (English), you MUST synchronously update all translations in the readme-international/ directory (fr, es, de).',
-  '',
+const MEMORY_INSTRUCTIONS = [
   '## Memory Protocol (Karpathy Guardrails)',
   '',
   'Agents MUST follow these behavioral principles:',
@@ -114,4 +67,60 @@ const PROJECT_INSTRUCTIONS = [
   '- `.agents/memory/context.md` — Update at session end with project state',
 ];
 
-module.exports = { PROJECT_INSTRUCTIONS };
+/** Shared once-per-session update instruction for source and installed projects. */
+const UPDATE_INSTRUCTIONS = [
+  '## Framework updates',
+  '',
+  'Once per session, check the installed framework before starting project work. If this is the BMAD+ source checkout, use `node tools/cli/bmad-plus-cli.js update-check --json`; otherwise use `npx --no-install bmad-plus update-check --json` from the project root.',
+  'If the command is unavailable or the result is off, unknown, offline or stale, continue the user task. Do not install a CLI just to perform this check or claim that an offline version is current.',
+  'When `updateAvailable` is true and `canAutoApply` is true, run the same CLI with `update --latest --auto`. This follows the project update policy; it does not grant permission to expand that policy.',
+  'When an update is available but automatic application is not eligible, explain the version and reason. An explicit request to update can be fulfilled with `update --latest --yes`; do not change the policy, overwrite customized files, or resolve conflicts without the user request covering that action.',
+  'After a successful update, reread the project spine and relevant installed skills, or start a fresh session if the client cannot reload them. Respect preserved local instructions. Check only once even when several adapters include this section.',
+];
+
+const PROJECT_INSTRUCTIONS = [
+  '## Skills',
+  '',
+  '- Installed projects load skills from `.agents/skills/`; in this repository the sources live in `src/bmad-plus/skills/` and `src/bmad-plus/agents/`.',
+  '- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules.',
+  '- Auto-activation triggers: `.agents/data/role-triggers.yaml` (source: `src/bmad-plus/data/role-triggers.yaml`).',
+  '',
+  '## Project Structure',
+  '',
+  '- `src/bmad-plus/` — Custom module (agents, skills, data)',
+  '- `monitor/` — Upstream monitoring system (VPS)',
+  '- `mcp-server/` — Audit 360° MCP Server',
+  '- `osint-agent-package/` — OSINT package',
+  '- `upstream/` — BMAD-METHOD reference clone',
+  '',
+  '## Communication',
+  '',
+  '- User name: laurent',
+  '- Default language: Français for user-facing content, English for code and technical docs.',
+  '',
+  '## Commit Rules',
+  '',
+  '- NEVER add "Co-Authored-By: Claude" or any AI co-author attribution.',
+  '- The sole author is Laurent Rochetta.',
+  '',
+  '## Repository Maintenance Rule',
+  '',
+  'When updating the main README.md (English), you MUST synchronously update all translations in the readme-international/ directory (fr, es, de).',
+  '',
+  ...MEMORY_INSTRUCTIONS,
+  '',
+  ...UPDATE_INSTRUCTIONS,
+];
+
+/** Tool display/detection metadata; installable tools and paths come from DERIVED. */
+const TOOL_METADATA = {
+  'claude-code': { name: 'Claude Code', detect: ['.claude'] },
+  'gemini-cli': { name: 'Gemini CLI', detect: ['.gemini'] },
+  antigravity: { name: 'Antigravity', detect: ['.gemini/antigravity'] },
+  cursor: { name: 'Cursor', detect: ['.cursor'] },
+  'codex-cli': { name: 'Codex CLI', detect: ['.codex'] },
+  opencode: { name: 'OpenCode', detect: ['.opencode'] },
+  aider: { name: 'Aider', detect: ['.aider.conf.yml'] },
+};
+
+module.exports = { PROJECT_INSTRUCTIONS, MEMORY_INSTRUCTIONS, UPDATE_INSTRUCTIONS, TOOL_METADATA };

package/tools/build/check-counts.js

@@ -42,7 +42,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
-const { loadRegistry, DEFAULT_REGISTRY_PATH } = require('./generate');
+const { loadRegistry, buildDerived, DEFAULT_REGISTRY_PATH } = require('./generate');
 
 const REPO_ROOT = path.join(__dirname, '..', '..');
 
@@ -84,12 +84,6 @@ function isFrozenHistoryRow(line) {
 
 /* ── Derivation ─────────────────────────────────────────────────────────── */
 
-/** Sum of list lengths for a given key across a pack's categories. */
-function sumCategories(pack, key) {
-  if (!Array.isArray(pack.categories)) return 0;
-  return pack.categories.reduce((n, c) => n + (Array.isArray(c[key]) ? c[key].length : 0), 0);
-}
-
 /** Count *.md agent files on disk for a packaged pack's categories/ tree. */
 function countAgentFilesOnDisk(packDir) {
   const root = path.join(REPO_ROOT, 'src', 'bmad-plus', 'packs', packDir, 'categories');
@@ -111,36 +105,28 @@ function countWorkflowFilesOnDisk(packDir) {
   return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
 }
 
-/** Installer languages, read from the CLI's own i18n module (its SSOT). */
-function deriveLanguages() {
-  const { LANGUAGES } = require(path.join(REPO_ROOT, 'tools', 'cli', 'i18n.js'));
-  return Object.keys(LANGUAGES);
-}
-
 /**
  * Derive every count this gate enforces, from registry.yaml + the filesystem.
  * Cross-checks the registry against the files on disk: if they disagree, the
  * derivation itself is untrustworthy and that is reported as a drift.
  */
-function deriveTruth(registryPath = DEFAULT_REGISTRY_PATH) {
-  const registry = loadRegistry(registryPath);
-  const packs = registry.packs;
+function deriveTruth(registryPath = DEFAULT_REGISTRY_PATH, options = {}) {
+  const registry = typeof registryPath === 'string' ? loadRegistry(registryPath) : registryPath;
+  const derived = buildDerived(registry, options);
+  const packs = derived.packs;
   const shield = packs.shield;
   const devStudio = packs['dev-studio'];
-
-  const shieldAgents = sumCategories(shield, 'agents');
-  const shieldWorkflows = (shield.workflows || []).length;
-  const shieldCategories = (shield.categories || []).length;
-  const shieldFrameworks = (shield.compliance_tags || []).length;
-
-  const installerAgents = Object.values(packs).reduce((n, p) => n + p.agents.length, 0);
-  const devStudioSubAgents = (devStudio.sub_agents || []).length;
-  const devStudioWorkflows =
-    (devStudio.workflows || []).length + sumCategories(devStudio, 'workflows');
+  const { installerAgents, totalAgents } = derived;
+  const shieldAgents = shield.categoryAgentCount;
+  const shieldWorkflows = shield.workflowCount;
+  const shieldCategories = shield.categoryCount;
+  const shieldFrameworks = shield.frameworkCount;
+  const devStudioSubAgents = devStudio.subAgentCount;
+  const devStudioWorkflows = devStudio.workflowCount;
 
   const mismatches = [];
-  const onDiskAgents = countAgentFilesOnDisk(shield.pack_dir);
-  const onDiskWorkflows = countWorkflowFilesOnDisk(shield.pack_dir);
+  const onDiskAgents = countAgentFilesOnDisk(registry.packs.shield.pack_dir);
+  const onDiskWorkflows = countWorkflowFilesOnDisk(registry.packs.shield.pack_dir);
   if (onDiskAgents !== null && onDiskAgents !== shieldAgents) {
     mismatches.push(
       `registry.yaml declares ${shieldAgents} shield category agents but ${onDiskAgents} agent files exist on disk`
@@ -152,26 +138,24 @@ function deriveTruth(registryPath = DEFAULT_REGISTRY_PATH) {
     );
   }
 
-  // Every distinct agent a user can talk to: the installer entry points plus
-  // the specialists the two packaged orchestrators route to.
-  const totalAgents = installerAgents + shieldAgents + devStudioSubAgents;
   // Sizes of the declared per-category agent groups ("5 agents", "6 agents"…),
   // which are legitimate claims wherever a category is described.
-  const perCategorySizes = new Set((shield.categories || []).map((c) => (c.agents || []).length));
+  const perCategorySizes = new Set(shield.categoryAgentCounts);
   // Sizes of the per-pack installer rosters ("3 agents (Scout, Chief, Judge)").
-  const perPackInstallerSizes = new Set(Object.values(packs).map((p) => p.agents.length));
+  const perPackInstallerSizes = new Set(Object.values(packs).map((p) => p.installerAgentCount));
 
   return {
-    packCount: Object.keys(packs).length,
+    packCount: derived.packCount,
     installerAgents,
     shieldAgents,
     shieldWorkflows,
     shieldCategories,
     shieldFrameworks,
+    shieldReferenceFiles: shield.referenceFiles,
     devStudioSubAgents,
     devStudioWorkflows,
     totalAgents,
-    languages: deriveLanguages(),
+    languages: derived.languages,
     perCategorySizes,
     // The COMPLETE vocabulary of numbers that may legitimately precede "agents"
     // anywhere in the product's own copy. Default-deny: a value outside this set
@@ -188,7 +172,7 @@ function deriveTruth(registryPath = DEFAULT_REGISTRY_PATH) {
     ]),
     // Same idea for the workflow dimension. Anchored lines get graded against
     // the one pack they name; unanchored ones must still be *some* real total.
-    workflowCounts: new Set([shieldWorkflows, devStudioWorkflows]),
+    workflowCounts: new Set(Object.values(packs).map((p) => p.workflowCount).filter(Boolean)),
     derivationMismatches: mismatches,
   };
 }
@@ -228,21 +212,18 @@ const FOREIGN_TABLE_HEADER_RE = /^\s*\|\s*BMAD-METHOD\s*\|/i;
  * `\s` already covers U+00A0/U+202F, which the French copy uses before
  * punctuation.
  *
- * `-` and `_` are deliberately NOT separators. This repo is full of agent
- * IDENTIFIERS — `iso27001-agent`, `nist-800-53-agent`, `section508-agent`,
- * `iso42001-agent` — and a hyphen-tolerant gap would read every one of them as
- * a claim of "27001 agents". A qualifier may still *contain* a hyphen
- * ("multi-role", "GRC-Compliance-"); it just may not START with one.
+ * Hyphens allow compounds such as "12-language". The leading token guard in
+ * claimRe prevents digits inside identifiers such as `nist-800-53-agent` from
+ * becoming counts; the separator itself need not suppress legitimate claims.
  */
-const GAP = '[\\s*`]*';
+const GAP = '[\\s*`-]*';
 
 /** One qualifier word: hyphenated and accented forms included. */
 const WORD = '[A-Za-zÀ-ÖØ-öø-ÿ][A-Za-zÀ-ÖØ-öø-ÿ-]*';
 
 /**
- * How many qualifiers a claim may carry. The bound is load-bearing: it is what
- * stops a match from walking across a whole sentence and inventing a claim
- * ("5 reasons why you should hire agents").
+ * Maximum qualifiers echoed in diagnostics. Longer adjective runs are still
+ * graded; clause/dimension boundaries below prevent cross-sentence claims.
  */
 const MAX_QUALIFIERS = 4;
 
@@ -263,6 +244,10 @@ const NOT_A_QUALIFIER = new Set(
    and or plus with across of in on for to the a an
    et ou des les la le du dans sur pour avec y con de en und oder mit für`.split(/\s+/)
 );
+const DIMENSION_WORDS = new Set(
+  'agent agents agente agentes agenten workflow workflows pack packs test tests category categories catégorie catégories categoría categorías kategorie kategorien framework frameworks language languages langue langues idioma idiomas sprache sprachen skill skills phase phases level levels reference files'.split(' ')
+);
+const CLAUSE_WORDS = new Set('why you we they should would could must can will'.split(' '));
 
 /**
  * Quantity approximators sitting in front of the number. "over 47 agents" is
@@ -279,14 +264,13 @@ const APPROX_PREFIX_RE = new RegExp(
 /**
  * Build a /g/ claim regex for one dimension's noun alternatives.
  *
- * The leading `\b` is load-bearing: it forbids the number from starting inside
- * a word. Without it a qualifier run happily bridges the stray digit in "E2E
- * tests" into a claim of "2 tests", and reads `section508-agent` as a count.
- * A claim's number is always a whole token.
+ * The leading guard forbids a number inside a word, version or identifier.
+ * Qualifier tokens require separators, so an unbounded adjective run does not
+ * create ambiguous character-by-character partitions when no noun follows.
  */
 function claimRe(noun) {
   return new RegExp(
-    `\\b(\\d+)${GAP}(\\+)?${GAP}((?:${WORD}${GAP}){0,${MAX_QUALIFIERS}}?)(?:${noun})\\b`,
+    `(?<![\\w.-])(\\d+)${GAP}(\\+)?${GAP}((?:${WORD}[\\s*\u0060-]+)*?)(${noun})\\b`,
     'gi'
   );
 }
@@ -298,12 +282,13 @@ const PACKS_RE = claimRe('packs?');
 const TESTS_RE = claimRe('tests?');
 const FRAMEWORKS_RE = claimRe('frameworks?');
 const LANGUAGES_RE = claimRe('languages?|langues?|idiomas?|Sprachen?');
+const REFERENCE_FILES_RE = claimRe('reference files?');
 
 /**
  * Collect every claim `re` finds on `line`.
  * `re` must be a /g/ regex; it is reset before use so it is safe to reuse.
- * Matches whose qualifier run crosses a NOT_A_QUALIFIER word are dropped: the
- * number belongs to a different dimension (or a different sentence).
+ * Dimension/clause crossings are discarded. Connectives truncate the echoed
+ * qualifiers without discarding a claim such as "38 compliance and GRC agents".
  * @returns {{value:number, plus:boolean, approx:boolean, text:string}[]}
  */
 function matchAll(re, line) {
@@ -312,14 +297,16 @@ function matchAll(re, line) {
   let m;
   while ((m = re.exec(line)) !== null) {
     const qualifiers = (m[3] || '').split(/[^A-Za-zÀ-ÖØ-öø-ÿ]+/).filter(Boolean);
-    if (qualifiers.some((w) => NOT_A_QUALIFIER.has(w.toLowerCase()))) continue;
+    if (qualifiers.some((w) => DIMENSION_WORDS.has(w.toLowerCase()) || CLAUSE_WORDS.has(w.toLowerCase()))) continue;
+    const connective = qualifiers.findIndex((w) => NOT_A_QUALIFIER.has(w.toLowerCase()));
+    const bounded = qualifiers.slice(0, Math.min(connective < 0 ? qualifiers.length : connective, MAX_QUALIFIERS));
     out.push({
       value: Number(m[1]),
       plus: m[2] === '+',
       approx: APPROX_PREFIX_RE.test(line.slice(0, m.index)),
       // Markers are dropped from the echoed text so a bolded claim reports as
       // `38 compliance agents`, not `38** compliance agents`. file:line locates it.
-      text: m[0].replace(/[*`]+/g, ' ').replace(/\s+/g, ' ').trim(),
+      text: [m[1] + (m[2] || ''), ...bounded, m[4]].join(' '),
     });
   }
   return out;
@@ -334,6 +321,11 @@ function matchAll(re, line) {
  * @returns {string[]} human-readable drift descriptions (empty when the line is fine)
  */
 function checkLine(line, truth, { foreignSubject = false } = {}) {
+  // In a comparison table only the first cell describes the upstream product.
+  if (foreignSubject && line.trimStart().startsWith('|')) {
+    const ownCells = line.trim().split('|').slice(2, -1).join(' | ');
+    return checkLine(ownCells, truth);
+  }
   const problems = [];
   const shieldLine = SHIELD_ANCHOR.test(line);
   const devStudioLine = DEV_STUDIO_ANCHOR.test(line);
@@ -466,6 +458,12 @@ function checkLine(line, truth, { foreignSubject = false } = {}) {
     }
   }
 
+  for (const { value, plus, approx, text } of matchAll(REFERENCE_FILES_RE, line)) {
+    if (value !== truth.shieldReferenceFiles || plus || approx) {
+      problems.push(`"${text}" — Shield has ${truth.shieldReferenceFiles} reference files on disk`);
+    }
+  }
+
   return problems;
 }
 

package/tools/build/check-install-contract.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * Verify that real source and npm-package installs deliver the adapter contract.
+ * Uses existing dependencies, temporary projects and an isolated brain; no
+ * lifecycle scripts, dependency installation or Python provisioning are run.
+ *
+ * Run: node tools/build/check-install-contract.js
+ * Author: Laurent Rochetta
+ */
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TEMP_PREFIX = 'bmad-install-contract-';
+
+function resolveWithin(root, relative) {
+  assert(typeof relative === 'string' && relative.length > 0, 'Expected a relative file path');
+  assert(
+    !path.win32.isAbsolute(relative) && !path.posix.isAbsolute(relative),
+    `Absolute path: ${relative}`
+  );
+  const target = path.resolve(root, relative);
+  const fromRoot = path.relative(root, target);
+  assert(
+    fromRoot &&
+      !path.isAbsolute(fromRoot) &&
+      !fromRoot.startsWith(`..${path.sep}`) &&
+      fromRoot !== '..',
+    `Path escapes project: ${relative}`
+  );
+  return target;
+}
+
+function sameSelection(actual, expected, label) {
+  assert(Array.isArray(actual), `Manifest ${label} must be an array`);
+  assert.deepEqual(
+    [...actual].sort(),
+    [...expected].sort(),
+    `Manifest ${label} differs from requested selection`
+  );
+}
+
+/** Compare the installed bytes, normalizing only Windows/Unix line endings. */
+function verifyInstallation(projectDir, { packs, tools, derived, ideConfigs, renderFiles, requireInventory = false }) {
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(projectDir, '_bmad', '.bmad-plus-install.json'), 'utf8')
+  );
+  sameSelection(manifest.packs, packs, 'packs');
+  sameSelection(manifest.ides, tools, 'ides');
+  assert(typeof manifest.user === 'string' && manifest.user, 'Manifest user is missing');
+  assert(
+    typeof manifest.language === 'string' && manifest.language,
+    'Manifest language is missing'
+  );
+
+  const files = renderFiles(derived, {
+    packs,
+    userName: manifest.user,
+    language: manifest.language,
+    tools: manifest.ides,
+  });
+  const expectedPaths = new Set(files.map(({ file }) => file));
+  assert.equal(expectedPaths.size, files.length, 'Renderer returned duplicate output paths');
+  assert.equal(
+    derived.targets.spine,
+    'AGENTS.md',
+    'Install contract requires the root AGENTS.md spine'
+  );
+  assert(
+    expectedPaths.has(derived.targets.spine),
+    'Renderer must include the root AGENTS.md spine'
+  );
+  for (const tool of tools) {
+    assert(expectedPaths.has(ideConfigs[tool].configFile), `Renderer omitted the ${tool} adapter`);
+  }
+
+  for (const { file, content } of files) {
+    const target = resolveWithin(projectDir, file);
+    assert(fs.existsSync(target), `Missing installed file: ${file}`);
+    const actual = fs.readFileSync(target, 'utf8').replace(/\r\n/g, '\n');
+    const expected = content.replace(/\r\n/g, '\n');
+    assert(actual === expected, `Installed adapter differs from renderer: ${file}`);
+  }
+  for (const { configFile } of Object.values(ideConfigs)) {
+    assert(
+      expectedPaths.has(configFile) || !fs.existsSync(resolveWithin(projectDir, configFile)),
+      `Unselected adapter was installed: ${configFile}`
+    );
+  }
+  if (requireInventory) {
+    assert.equal(manifest.fileInventory?.schemaVersion, 1, 'Missing file inventory');
+    const { collectManagedFiles } = require('../cli/lib/update-transaction');
+    const managedFiles = collectManagedFiles({ projectDir, packs });
+    assert.deepEqual(Object.keys(manifest.fileInventory.files).sort(), managedFiles.map(entry => entry.file).sort(),
+      'Inventory does not cover exactly the selected framework files');
+    for (const { file } of managedFiles) {
+      const actualHash = crypto.createHash('sha256').update(fs.readFileSync(resolveWithin(projectDir, file))).digest('hex');
+      assert.equal(manifest.fileInventory.files[file], actualHash, `Inventory differs from installed bytes: ${file}`);
+    }
+  }
+  return files.length;
+}
+
+function run(command, args, { cwd, env, timeout = 60000 }) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    timeout,
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error || result.status !== 0) {
+    const reason = result.error
+      ? result.error.message
+      : `exit ${result.status}, signal ${result.signal || 'none'}`;
+    throw new Error(
+      `${path.basename(command)} ${args.join(' ')}: ${reason}\n${result.stdout || ''}${result.stderr || ''}`
+    );
+  }
+  return result.stdout;
+}
+
+/** Invoke npm without a shell, including Windows where npm.cmd is not executable. */
+function npmCommand(env) {
+  const candidates = [
+    env.npm_execpath,
+    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ...(env.PATH || env.Path || '')
+      .split(path.delimiter)
+      .map((dir) => path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')),
+  ];
+  const cli = candidates.find(
+    (candidate) => candidate && /npm-cli\.js$/i.test(candidate) && fs.existsSync(candidate)
+  );
+  if (cli) return { command: process.execPath, args: [cli] };
+  assert(process.platform !== 'win32', 'Could not locate npm-cli.js beside Node or on PATH');
+  return { command: 'npm', args: [] };
+}
+
+function packAndExtract(tempRoot, env) {
+  const destination = path.join(tempRoot, 'distribution');
+  fs.mkdirSync(destination);
+  const npm = npmCommand(env);
+  const output = run(
+    npm.command,
+    [
+      ...npm.args,
+      'pack',
+      '--ignore-scripts',
+      '--offline',
+      '--json',
+      '--pack-destination',
+      destination,
+      '--cache',
+      path.join(tempRoot, 'npm-cache'),
+    ],
+    { cwd: REPO_ROOT, env, timeout: 120000 }
+  );
+  const packed = JSON.parse(output);
+  assert(Array.isArray(packed) && packed.length === 1, 'npm pack must produce exactly one package');
+  const archive = resolveWithin(destination, packed[0].filename);
+  const entries = run('tar', ['-tzf', archive], { cwd: destination, env }).trim().split(/\r?\n/);
+  for (const entry of entries) {
+    assert(entry.startsWith('package/'), `Unexpected npm archive entry: ${entry}`);
+    resolveWithin(destination, entry);
+  }
+  run('tar', ['-xzf', archive, '-C', destination], { cwd: destination, env });
+  const packageRoot = path.join(destination, 'package');
+  assert(
+    !fs.existsSync(path.join(packageRoot, 'registry.yaml')),
+    'npm contract must work without registry.yaml'
+  );
+  assert(fs.statSync(packageRoot).isDirectory(), 'npm package directory is missing');
+  return packageRoot;
+}
+
+function runMatrix(packageRoot, variant, tempRoot, env, reference) {
+  const allPacks = Object.keys(reference.packDefinitions).filter(
+    (id) => !reference.packDefinitions[id].disabled
+  );
+  const allTools = Object.keys(reference.ideConfigs);
+  assert(allTools.length > 0, 'IDE_CONFIGS must expose at least one target');
+  const selections = [
+    { argument: 'core', packs: ['core'] },
+    { argument: 'core,osint', packs: ['core', 'osint'] },
+    { argument: 'core,memory', packs: ['core', 'memory'] },
+    { argument: 'all', packs: allPacks },
+  ];
+  const toolSelections = [...allTools.map((tool) => [tool]), allTools];
+  let installations = 0;
+  let files = 0;
+  for (const selection of selections) {
+    for (const tools of toolSelections) {
+      const label = `${variant}/${selection.argument}/${tools.join(',')}`;
+      const projectDir = path.join(tempRoot, `${variant}-project-${++installations}`);
+      fs.mkdirSync(projectDir);
+      try {
+        run(
+          process.execPath,
+          [
+            path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+            'install',
+            '--yes',
+            '--lang',
+            'en',
+            '--directory',
+            projectDir,
+            '--packs',
+            selection.argument,
+            '--tools',
+            tools.join(','),
+          ],
+          { cwd: projectDir, env }
+        );
+        files += verifyInstallation(projectDir, { ...reference, packs: selection.packs, tools });
+        if (tools.length === allTools.length) {
+          const output = run(process.execPath, [
+            path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+            'update-check', '--offline', '--json', '--directory', projectDir,
+          ], { cwd: projectDir, env });
+          const checked = JSON.parse(output);
+          assert.equal(checked.status, 'unknown', 'Offline check must not claim the latest release');
+          assert.equal(checked.updateAvailable, null);
+          assert.equal(checked.canAutoApply, false);
+        }
+      } catch (error) {
+        throw new Error(`${label}: ${error.message}`, { cause: error });
+      }
+    }
+    console.log(
+      `OK ${variant}: ${selection.argument} across ${toolSelections.length} tool selections`
+    );
+  }
+  return { installations, files };
+}
+
+function main() {
+  const { PACKS, DERIVED } = require('../cli/lib/packs');
+  const { IDE_CONFIGS } = require('../cli/lib/ide-config');
+  const { generateUserFiles } = require('./generate-adapters');
+  assert(
+    DERIVED && typeof generateUserFiles === 'function',
+    'Generated install contract exports are missing'
+  );
+  const reference = {
+    packDefinitions: PACKS,
+    derived: DERIVED,
+    ideConfigs: IDE_CONFIGS,
+    renderFiles: generateUserFiles,
+    requireInventory: true,
+  };
+  const tempParent = fs.realpathSync(os.tmpdir());
+  const tempRoot = fs.mkdtempSync(path.join(tempParent, TEMP_PREFIX));
+  try {
+    const brain = path.join(tempRoot, 'brain');
+    fs.mkdirSync(brain);
+    const env = {
+      ...process.env,
+      BMAD_PLUS_BRAIN: brain,
+      NODE_PATH: path.join(REPO_ROOT, 'node_modules'),
+      NO_COLOR: '1',
+      NPM_CONFIG_UPDATE_NOTIFIER: 'false',
+    };
+    const source = runMatrix(REPO_ROOT, 'source', tempRoot, env, reference);
+    const packageRoot = packAndExtract(tempRoot, env);
+    const packaged = runMatrix(packageRoot, 'npm', tempRoot, env, reference);
+    console.log(
+      `Install contract passed: ${source.installations + packaged.installations} installs, ${source.files + packaged.files} files compared (source + npm without registry.yaml).`
+    );
+    return 0;
+  } finally {
+    // Delete only this mkdtemp-owned direct child of the verified temp directory.
+    assert(
+      path.dirname(tempRoot) === tempParent && path.basename(tempRoot).startsWith(TEMP_PREFIX)
+    );
+    assert(fs.realpathSync(tempRoot) === tempRoot && !fs.lstatSync(tempRoot).isSymbolicLink());
+    fs.rmSync(tempRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    console.error(`Install contract failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { main, resolveWithin, verifyInstallation };