bmad-plus 0.12.2 → 0.14.0

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,450 @@
+#!/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 verifyDiagnostics(report, { packs, tools, derived }) {
+  assert.equal(report.schemaVersion, 1, 'Unsupported diagnostic report');
+  assert.equal(report.versions.installed, derived.product.version);
+  assert.equal(report.versions.cli, derived.product.version);
+  assert.equal(report.versions.published, null, 'Doctor must not invent npm freshness evidence');
+  sameSelection(
+    report.packs.map(({ id }) => id),
+    packs,
+    'diagnostic packs'
+  );
+  sameSelection(
+    report.integrations.map(({ tool }) => tool),
+    tools,
+    'diagnostic integrations'
+  );
+  for (const integration of report.integrations) {
+    assert.deepEqual(
+      integration,
+      {
+        tool: integration.tool,
+        ...derived.diagnostics.integrations[integration.tool],
+        ownership: 'unchanged',
+        hostVerified: false,
+      },
+      'An installed adapter must not imply verified host execution'
+    );
+  }
+  const expectedErrors = [];
+  assert.deepEqual(
+    report.checks
+      .filter(({ status }) => status === 'error')
+      .map(({ code, path: file }) => `${code}:${file}`)
+      .sort(),
+    expectedErrors.sort(),
+    'Every advertised pack must install without delivery errors'
+  );
+  assert.equal(report.summary.errors, expectedErrors.length);
+  assert.equal(report.inventory.status, 'complete');
+  assert(report.inventory.trackedFiles > 0, 'Doctor did not inspect the ownership inventory');
+  assert.equal(
+    report.checks.filter(({ code }) => code === 'file.unchanged').length,
+    report.inventory.trackedFiles,
+    'Every freshly installed managed file must have matching ownership'
+  );
+  assert(!report.checks.some(({ code }) => ['file.modified', 'file.unowned'].includes(code)));
+  for (const runtime of report.runtimes.filter(({ runtime }) => runtime === 'python')) {
+    assert.equal(
+      runtime.imports,
+      'not-verified',
+      'Presence of requirements cannot prove Python imports'
+    );
+    assert.equal(runtime.environment, 'missing', 'Contract checks must not provision Python');
+  }
+  const expectedStatus = expectedErrors.length
+    ? 'error'
+    : report.summary.warnings
+      ? 'warning'
+      : 'ok';
+  assert.equal(report.status, expectedStatus);
+}
+
+function run(command, args, { cwd, env, timeout = 60000, expectedExitCode = 0 }) {
+  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 !== expectedExitCode) {
+    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 });
+        const expectedExitCode = 0;
+        const diagnosis = run(
+          process.execPath,
+          [
+            path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+            'doctor',
+            '--json',
+            '--directory',
+            projectDir,
+          ],
+          { cwd: projectDir, env, expectedExitCode }
+        );
+        verifyDiagnostics(JSON.parse(diagnosis), {
+          packs: selection.packs,
+          tools,
+          derived: reference.derived,
+          variant,
+        });
+        if (selection.packs.includes('dev-studio')) {
+          const list = JSON.parse(
+            run(
+              process.execPath,
+              [
+                path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+                'studio',
+                'list',
+                '--directory',
+                projectDir,
+                '--json',
+              ],
+              { cwd: projectDir, env }
+            )
+          );
+          assert.equal(list.workflows.length, reference.derived.packs['dev-studio'].workflowCount);
+          const prepared = JSON.parse(
+            run(
+              process.execPath,
+              [
+                path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+                'studio',
+                'prepare',
+                'create-ux-design',
+                '--request',
+                'Design the sign-in flow',
+                '--directory',
+                projectDir,
+                '--json',
+              ],
+              { cwd: projectDir, env }
+            )
+          );
+          assert.equal(prepared.status, 'ready');
+          assert.equal(prepared.executed, false);
+          assert(prepared.instructions.some((item) => item.path.endsWith('/create-ux-design.md')));
+          assert(!fs.existsSync(path.join(projectDir, prepared.outputPath)));
+        }
+        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 { checkPythonDelivery } = require('./pack-delivery');
+    const { loadRegistry } = require('./generate');
+    assert.deepEqual(
+      checkPythonDelivery(loadRegistry(), {
+        packageRoot,
+        packageJson: JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')),
+      }),
+      [],
+      'Declared Python resources must exist in the real npm archive'
+    );
+    const packaged = runMatrix(packageRoot, 'npm', tempRoot, env, reference);
+    console.log(
+      `Install contract passed: ${source.installations + packaged.installations} installs and doctor JSON reports, ${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 };