bmad-plus 0.14.0 → 0.17.0

package/src/bmad-plus/skills/bmad-plus-uat/templates/uat-release-gate.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Gate G3 — production waits for a human run that was read and classified.
+ *
+ * Resolves the recipe covering the version in package.json, then runs
+ * `bmad-plus uat gate` on it. Exit 0 only when the gate passes: a finished run,
+ * answering the current revision of the recipe, with every failure classified and
+ * every writing step confirmed read-only.
+ *
+ *   node scripts/uat-release-gate.mjs
+ *   node scripts/uat-release-gate.mjs --id myproduct-1.4.0
+ *   node scripts/uat-release-gate.mjs --cli node_modules/bmad-plus/tools/cli/bmad-plus-cli.js
+ *   BMAD_PLUS_CLI=/path/to/bmad-plus-cli.js node scripts/uat-release-gate.mjs
+ *
+ * Exit codes mirror the command: 0 passed · 1 failed · 2 awaiting a run ·
+ * 3 the run answered another revision · 4 the gate could not be run at all.
+ *
+ * The gate establishes that the run is complete, current and classified. It never
+ * establishes that the tester looked at the right place: that stays human-observed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+const root = path.resolve(option('project', process.cwd()));
+const directory = option('dir', '_bmad-output/uat');
+const specs = path.join(root, directory, 'specs');
+
+function resolveId() {
+  const explicit = option('id', null);
+  if (explicit) return explicit;
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) throw new Error(`no package.json in ${root}; pass --id <recipe>`);
+  const version = JSON.parse(fs.readFileSync(file, 'utf8')).version;
+  if (!fs.existsSync(specs)) throw new Error(`no recipe folder at ${specs}`);
+  const covering = fs
+    .readdirSync(specs)
+    .filter((name) => name.endsWith('.json'))
+    .filter((name) => {
+      try {
+        const spec = JSON.parse(fs.readFileSync(path.join(specs, name), 'utf8'));
+        return Array.isArray(spec.versions) && spec.versions.includes(version);
+      } catch {
+        return false;
+      }
+    });
+  if (covering.length !== 1) {
+    throw new Error(
+      covering.length
+        ? `${covering.length} recipes name ${version}; pass --id to choose one`
+        : `no recipe names ${version}; write it before deploying`
+    );
+  }
+  return covering[0].replace(/\.json$/, '');
+}
+
+/**
+ * The CLI's own entry point, run by this Node: an explicit one, or the copy
+ * installed in the project. Never a shell, never `npx` — a `.cmd` shim cannot be
+ * spawned without a shell on Windows, and a gate must not depend on a download.
+ */
+function command() {
+  const candidates = [
+    option('cli', null),
+    process.env.BMAD_PLUS_CLI,
+    path.join(root, 'node_modules', 'bmad-plus', 'tools', 'cli', 'bmad-plus-cli.js'),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    const resolved = path.resolve(root, candidate);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  throw new Error(
+    'no BMAD+ CLI to run the gate with. Install bmad-plus in this project ' +
+      '(npm install --save-dev bmad-plus) or set BMAD_PLUS_CLI to its bmad-plus-cli.js. ' +
+      'A missing gate is not a passing gate.'
+  );
+}
+
+try {
+  const id = resolveId();
+  const cli = command();
+  const child = spawnSync(
+    process.execPath,
+    [cli, 'uat', 'gate', id, '--directory', root, '--dir', directory, '--json'],
+    { encoding: 'utf8', timeout: 120000, windowsHide: true }
+  );
+
+  // The verdict is read from the gate's own answer, not guessed from an exit code:
+  // a CLI that never ran also exits non-zero, and that is a different problem.
+  let verdict = null;
+  try {
+    const parsed = JSON.parse(child.stdout);
+    if (parsed && typeof parsed.status === 'string') verdict = parsed;
+  } catch {
+    verdict = null;
+  }
+  if (!verdict) {
+    console.error(
+      `uat: the gate could not be run for ${id}` +
+        `${child.error ? ` (${child.error.message})` : ''}.\n` +
+        `${(child.stdout || '').trim()}${(child.stderr || '').trim()}\n` +
+        'Install the CLI in this project, or set BMAD_PLUS_CLI to its path. ' +
+        'A missing gate is not a passing gate.'
+    );
+    process.exit(4);
+  }
+
+  const explanation = {
+    passed: `${id}: human-observed, complete, current and triaged.`,
+    failed: `${id} did not pass its gate — production stays where it is.`,
+    awaiting: `${id} has no finished run yet — someone still has to play it.`,
+    stale: `${id} was answered on another revision of the recipe — replay the affected steps.`,
+  };
+  const code = { passed: 0, failed: 1, awaiting: 2, stale: 3 }[verdict.status] ?? 4;
+  const report = code === 0 ? console.log : console.error;
+  report(explanation[verdict.status] || `${id}: unexpected gate status "${verdict.status}".`);
+  for (const reason of verdict.reasons || []) report(`  - ${reason}`);
+  process.exit(code);
+} catch (error) {
+  console.error(`uat: ${error.message}`);
+  process.exit(4);
+}

package/src/bmad-plus/skills/bmad-plus-uat/templates/uat-spec-present.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Gate G1 — a version does not leave without saying what a person must check.
+ *
+ * Fails when no acceptance recipe covers the version in package.json. Copy this
+ * file into your project and run it wherever your other checks run: a pre-push
+ * hook, a test script, a CI step. It needs nothing but Node.
+ *
+ *   node scripts/uat-spec-present.mjs
+ *   node scripts/uat-spec-present.mjs --version 1.4.0 --dir _bmad-output/uat --json
+ *
+ * Exit 0 when a recipe covers the version, 1 otherwise. A reminder printed after
+ * a deployment protects nothing; this one runs before.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+const json = args.includes('--json');
+const root = path.resolve(option('project', process.cwd()));
+const directory = path.resolve(root, option('dir', '_bmad-output/uat'));
+
+function projectVersion() {
+  const explicit = option('version', null);
+  if (explicit) return explicit;
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(`no package.json in ${root}; pass --version <x.y.z>`);
+  }
+  const version = JSON.parse(fs.readFileSync(file, 'utf8')).version;
+  if (!version) throw new Error('package.json declares no version');
+  return version;
+}
+
+/** Recipes that name this version, whether they cover one version or a campaign. */
+function covering(version) {
+  const specs = path.join(directory, 'specs');
+  if (!fs.existsSync(specs)) return [];
+  return fs
+    .readdirSync(specs)
+    .filter((name) => name.endsWith('.json'))
+    .filter((name) => {
+      try {
+        const spec = JSON.parse(fs.readFileSync(path.join(specs, name), 'utf8'));
+        // A grouped recipe covers a version because it NAMES it, never because its
+        // file name suggests a range.
+        return Array.isArray(spec.versions) && spec.versions.includes(version);
+      } catch {
+        return false;
+      }
+    })
+    .map((name) => name.replace(/\.json$/, ''));
+}
+
+try {
+  const version = projectVersion();
+  const found = covering(version);
+  if (json) {
+    console.log(JSON.stringify({ version, directory, covering: found, ok: found.length > 0 }, null, 2));
+  } else if (found.length) {
+    console.log(`uat: ${version} is covered by ${found.join(', ')}`);
+  } else {
+    console.error(
+      `uat: no acceptance recipe covers ${version}.\n` +
+        `Write ${path.relative(root, path.join(directory, 'specs'))}/<product>-${version}.json before shipping,\n` +
+        `or add ${version} to the versions of a grouped recipe. Ask your agent: "write the recette for this delivery".`
+    );
+  }
+  process.exit(found.length ? 0 : 1);
+} catch (error) {
+  console.error(`uat: ${error.message}`);
+  process.exit(1);
+}

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

@@ -238,24 +238,221 @@ function packAndExtract(tempRoot, env) {
     ],
     { 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');
+  // npm 11 reports a list, npm 12 an object keyed by package name.
+  const reported = JSON.parse(output);
+  const packed = Array.isArray(reported) ? reported : Object.values(reported);
+  assert(
+    packed.length === 1 && typeof packed[0]?.filename === 'string',
+    '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/);
+  // The archive already sits in cwd, and it is named relatively on purpose: GNU tar
+  // reads a Windows "C:\..." argument as a remote host and refuses to open it.
+  const archiveName = path.basename(archive);
+  const entries = run('tar', ['-tzf', archiveName], { 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 });
+  run('tar', ['-xzf', archiveName, '-C', '.'], { 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');
+  for (const file of ['LICENSE', 'THIRD-PARTY-LICENSES.md', 'SECURITY.md']) {
+    assert(fs.statSync(path.join(packageRoot, file)).isFile(), `npm archive is missing ${file}`);
+  }
+  assert(
+    !fs.existsSync(path.join(packageRoot, 'src/bmad-plus/packs/pack-seo/scripts/__pycache__')),
+    'npm archive must exclude local Python caches'
+  );
   return packageRoot;
 }
 
+function verifyNexusConsumer(packageRoot, projectDir, env) {
+  const invoke = (args) =>
+    JSON.parse(
+      run(
+        process.execPath,
+        [
+          path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+          'nexus',
+          ...args,
+          '--directory',
+          projectDir,
+          '--json',
+        ],
+        { cwd: projectDir, env }
+      )
+    );
+  const input = (name, value) => {
+    const file = path.join(projectDir, name);
+    fs.writeFileSync(file, JSON.stringify(value));
+    return file;
+  };
+  const instruction = '.agents/skills/agent-orchestrator/SKILL.md';
+  assert(
+    fs
+      .readFileSync(path.join(projectDir, instruction), 'utf8')
+      .includes('Durable host-managed attempts')
+  );
+  fs.mkdirSync(path.join(projectDir, 'checks'));
+  fs.mkdirSync(path.join(projectDir, 'result'));
+  fs.writeFileSync(
+    path.join(projectDir, 'checks/accepted.cjs'),
+    "const fs=require('node:fs');const assert=require('node:assert/strict');assert.equal(fs.readFileSync('result/value.txt','utf8'),'accepted');\n"
+  );
+  const plan = input('nexus-plan.json', {
+    id: 'consumer',
+    tasks: [
+      {
+        id: 'work',
+        objective: 'Verify a real relocated npm/source consumer',
+        scope: ['result'],
+        artifacts: ['result/value.txt'],
+        resources: [instruction, 'checks/accepted.cjs'],
+        checks: [{ id: 'actual-output', command: 'node', args: ['checks/accepted.cjs'] }],
+      },
+    ],
+  });
+  invoke(['create', '--plan', plan]);
+  const backend = { kind: 'host', id: 'consumer-check', sessionId: 'observed-attempt' };
+  const started = invoke([
+    'start',
+    'consumer',
+    'work',
+    '--input',
+    input('nexus-host.json', { backend }),
+  ]);
+  const attemptId = started.tasks[0].attempts[0].id;
+  fs.writeFileSync(path.join(projectDir, 'result/value.txt'), 'accepted');
+  // A separate CLI process reconciles an interrupted host without repeating its work.
+  invoke([
+    'reconcile',
+    'consumer',
+    'work',
+    '--input',
+    input('nexus-observation.json', {
+      attemptId,
+      backend,
+      ownerStopped: true,
+      outcome: 'completed',
+      summary: 'Test host stopped after writing its artifact; independent checker follows.',
+    }),
+  ]);
+  const checked = invoke(['verify', 'consumer', 'work']);
+  assert.equal(checked.tasks[0].attempts[0].verification.status, 'passed');
+  const accepted = invoke(['accept', 'consumer', 'work']);
+  assert.equal(accepted.tasks[0].integration, 'accepted');
+  assert.equal(accepted.tasks[0].integrationReceipt.gitOperation, null);
+  const observed = invoke(['inspect', 'consumer']);
+  assert.equal(observed.observations[0].evidenceEligible, true);
+  assert.equal(observed.observations[0].stale, false);
+
+  fs.mkdirSync(path.join(projectDir, 'processed'));
+  fs.writeFileSync(path.join(projectDir, 'checks/task.txt'), 'Write the supervised result.\n');
+  fs.writeFileSync(
+    path.join(projectDir, 'checks/worker.cjs'),
+    "require('node:fs').writeFileSync('processed/value.txt','supervised');\n"
+  );
+  fs.writeFileSync(
+    path.join(projectDir, 'checks/process.cjs'),
+    "require('node:assert/strict').equal(require('node:fs').readFileSync('processed/value.txt','utf8'),'supervised');\n"
+  );
+  invoke([
+    'create',
+    '--plan',
+    input('process-plan.json', {
+      id: 'process-consumer',
+      tasks: [
+        {
+          id: 'work',
+          objective: 'Verify the packaged foreground process backend',
+          scope: ['processed'],
+          artifacts: ['processed/value.txt'],
+          resources: [instruction, 'checks/process.cjs'],
+          checks: [{ id: 'process-output', command: 'node', args: ['checks/process.cjs'] }],
+          execution: {
+            adapter: 'command',
+            command: 'node',
+            args: ['checks/worker.cjs'],
+            resources: ['checks/worker.cjs'],
+            input: 'checks/task.txt',
+          },
+        },
+      ],
+    }),
+  ]);
+  const launched = invoke(['launch', 'process-consumer', 'work']);
+  const processAttempt = launched.tasks[0].attempts[0];
+  assert.equal(processAttempt.process.receipt.outcome, 'completed');
+  invoke([
+    'collect',
+    'process-consumer',
+    'work',
+    '--input',
+    input('collect.json', {
+      attemptId: processAttempt.id,
+      backend: processAttempt.backend,
+    }),
+  ]);
+  assert.equal(
+    invoke(['verify', 'process-consumer', 'work']).tasks[0].attempts[0].verification.status,
+    'passed'
+  );
+  assert.equal(invoke(['accept', 'process-consumer', 'work']).tasks[0].integration, 'accepted');
+
+  const mem = (args) =>
+    JSON.parse(
+      run(
+        process.execPath,
+        [
+          path.join(packageRoot, 'tools/cli/bmad-plus-cli.js'),
+          'mem',
+          ...args,
+          '--directory',
+          projectDir,
+          '--json',
+        ],
+        { cwd: projectDir, env }
+      )
+    );
+  const memoryFile = '.agents/memory/patterns.md';
+  fs.mkdirSync(path.dirname(path.join(projectDir, memoryFile)), { recursive: true });
+  fs.appendFileSync(
+    path.join(projectDir, memoryFile),
+    '\n### Consumer supervision evidence\nVerify the supervised artifact before accepting process work.\n'
+  );
+  input('memory-observation.json', {
+    runId: 'process-consumer',
+    taskId: 'work',
+    memory: { file: memoryFile, heading: 'Consumer supervision evidence' },
+    scope: ['processed'],
+    interpretation:
+      'Consumer fixture links this note to the accepted result; causality is unmeasured.',
+  });
+  mem(['observe', '--input', 'memory-observation.json']);
+  const recall = () =>
+    mem([
+      'recall',
+      'Consumer supervision evidence',
+      '--ranking',
+      'evidence',
+      '--context-scope',
+      'processed',
+    ]);
+  assert(recall().results.some((entry) => entry.ref === 'Consumer supervision evidence'));
+  fs.writeFileSync(path.join(projectDir, 'processed/value.txt'), 'changed after acceptance');
+  assert(
+    !recall().results.some((entry) => entry.ref === 'Consumer supervision evidence'),
+    'Packaged memory must reject evidence after its accepted artifact changes'
+  );
+}
+
 function runMatrix(packageRoot, variant, tempRoot, env, reference) {
   const allPacks = Object.keys(reference.packDefinitions).filter(
     (id) => !reference.packDefinitions[id].disabled
@@ -313,6 +510,7 @@ function runMatrix(packageRoot, variant, tempRoot, env, reference) {
           derived: reference.derived,
           variant,
         });
+        if (installations === 1) verifyNexusConsumer(packageRoot, projectDir, env);
         if (selection.packs.includes('dev-studio')) {
           const list = JSON.parse(
             run(

package/tools/build/generate.js

@@ -189,6 +189,21 @@ function validateRegistry(registry) {
       'registry.yaml: targets.integration must declare the delivered instruction integration'
     );
   }
+  const processBackend = registry.targets?.optional_process_backend;
+  if (
+    processBackend &&
+    (!isDeepStrictEqual(processBackend.adapters, ['command', 'codex-exec']) ||
+      processBackend.supervisor !== 'foreground' ||
+      processBackend.launch !== 'explicit-plan' ||
+      processBackend.collect !== 'exact-attempt-receipt' ||
+      processBackend.cancellation !== 'original-owner-direct-child' ||
+      processBackend.verification !== 'independent-required' ||
+      processBackend.scheduling !== 'none')
+  ) {
+    throw new Error(
+      'registry.yaml: optional process backend differs from the delivered Nexus contract'
+    );
+  }
   for (const [runtime, config] of Object.entries(registry.runtimes || {})) {
     if (
       typeof config?.min_version !== 'string' ||
@@ -359,6 +374,7 @@ function buildDerived(registry, { sourceRoot = path.join(REPO_ROOT, 'src', 'bmad
     pythonPacks,
     diagnostics: {
       schemaVersion: 1,
+      processExecution: registry.targets.optional_process_backend || null,
       runtimeMinimums: Object.fromEntries(
         Object.entries(registry.runtimes).map(([id, runtime]) => [id, runtime.min_version])
       ),

package/tools/build/generated-adapters/.codex/AGENTS.md

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/.cursor/rules/bmad-plus.mdc

@@ -118,7 +118,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/.opencode/AGENTS.md

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/AGENTS.md

@@ -111,7 +111,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/CLAUDE.md

@@ -114,7 +114,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/CONVENTIONS.md

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/GEMINI.md

@@ -118,7 +118,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.14.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/cli/bmad-plus-cli.js

@@ -45,9 +45,7 @@ for (const option of install.options || []) {
 installCmd.action(install.action);
 
 // Uninstall command
-const uninstallCmd = program
-  .command('uninstall')
-  .description('Remove BMAD+ from your project');
+const uninstallCmd = program.command('uninstall').description('Remove BMAD+ from your project');
 for (const option of uninstall.options || []) {
   uninstallCmd.option(...option);
 }
@@ -64,9 +62,7 @@ for (const option of update.options || []) {
 updateCmd.action(update.action);
 
 // Doctor command
-const doctorCmd = program
-  .command('doctor')
-  .description('Check BMAD+ installation integrity');
+const doctorCmd = program.command('doctor').description('Check BMAD+ installation integrity');
 
 for (const option of doctor.options || []) {
   doctorCmd.option(...option);
@@ -81,7 +77,9 @@ const scanCmd = program
 for (const option of scan.options || []) {
   scanCmd.option(...option);
 }
-scanCmd.action((scanPath, options) => scan.action({ ...options, directory: scanPath || options.directory }));
+scanCmd.action((scanPath, options) =>
+  scan.action({ ...options, directory: scanPath || options.directory })
+);
 
 // Memory command
 const memoryCmd = program
@@ -95,9 +93,7 @@ memoryCmd.action(memory.action);
 
 // Mem command (Karpathy memory loop — journal recall/write/reinforce)
 const memJournal = require('./commands/memory-journal-cmd');
-const memJournalCmd = program
-  .command(memJournal.command)
-  .description(memJournal.description);
+const memJournalCmd = program.command(memJournal.command).description(memJournal.description);
 
 for (const option of memJournal.options || []) {
   memJournalCmd.option(...option);
@@ -116,15 +112,22 @@ for (const option of autoconfig.options || []) {
 autoconfigCmd.action(autoconfig.action);
 
 // Version discovery and explicit per-project update policy.
-for (const modulePath of ['./commands/update-check', './commands/update-policy', './commands/studio']) {
+for (const modulePath of [
+  './commands/update-check',
+  './commands/update-policy',
+  './commands/studio',
+  './commands/nexus',
+  './commands/uat',
+]) {
   const command = require(modulePath);
   const configured = program.command(command.command).description(command.description);
+  if (command.aliases) configured.aliases(command.aliases);
   for (const option of command.options || []) configured.option(...option);
   configured.action(command.action);
 }
 
 // Await asynchronous registry checks and updates before completing the CLI.
-program.parseAsync(process.argv).catch(error => {
+program.parseAsync(process.argv).catch((error) => {
   console.error(`BMAD+: ${error.message}`);
   process.exitCode = 1;
 });

package/tools/cli/commands/autoconfig.js

@@ -87,7 +87,9 @@ function calculateHealth(structure) {
   return { pct, checks };
 }
 
-function recommendPacks(stack, structure, health) {
+// `health` is measured elsewhere and does not change the recommendation: a project
+// with failing checks needs the same packs as a healthy one.
+function recommendPacks(stack, structure) {
   const packs = ['core', 'memory']; // Always
   const reasons = {
     core: 'Essential multi-role agents (Atlas, Forge, Sentinel, Nexus)',
@@ -215,7 +217,7 @@ module.exports = {
       const stack = detectStack(projectDir);
       const structure = analyzeStructure(projectDir);
       const health = calculateHealth(structure);
-      const { packs, reasons } = recommendPacks(stack, structure, health);
+      const { packs, reasons } = recommendPacks(stack, structure);
       const recs = generateRecommendations(stack, structure, health);
 
       spinner.stop('Analysis complete');

package/tools/cli/commands/doctor.js

@@ -45,6 +45,7 @@ module.exports = {
           'Installed: v' + report.versions.installed + ' | Executing CLI: v' + report.versions.cli,
           'Ownership inventory: ' + report.inventory.status,
           'Integrations use host-managed execution; host capabilities were not probed.',
+          'Optional Nexus process execution requires an explicit plan; executable availability was not probed.',
         ].join('\n'),
         'BMAD+ Health Report'
       );