bmad-plus 0.13.0 → 0.16.0

package/tools/cli/commands/doctor.js

@@ -1,205 +1,66 @@
-/**
- * BMAD+ Doctor Command
- * Checks installation integrity and reports issues
- *
- * Author: Laurent Rochetta
- */
-
-const path = require('node:path');
-const fs = require('node:fs');
+/** Human and JSON output share one report; runtime execution is explicitly opt-in. */
 const clack = require('@clack/prompts');
 const pc = require('picocolors');
-const { t } = require('../i18n');
-const { EXPECTED_AGENTS } = require('../lib/packs');
-const { readInstallManifest } = require('../lib/install-manifest');
+const { collectInstallationHealth } = require('../lib/installation-health');
 
 module.exports = {
   command: 'doctor',
-  description: 'Check BMAD+ installation integrity',
+  description: 'Check BMAD+ installation integrity and declared capabilities',
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it'],
+    ['--json', 'Print the diagnostic report as JSON (read-only unless a probe is requested)'],
+    ['--verify-python', 'Execute installed Python interpreters to verify versions and imports'],
   ],
-  action: async (options) => {
-    const projectDir = path.resolve(options.directory || process.cwd());
-    const packageJson = require('../../../package.json');
-
-    clack.intro(pc.bgBlue(pc.white(` BMAD+ Doctor v${packageJson.version} `)));
-
-    let checks = 0;
-    let passed = 0;
-    let warnings = 0;
-    let errors = 0;
-
-    // ── Check 1: Installation manifest ──
-    checks++;
-    const manifestPath = path.join(projectDir, '_bmad', '.bmad-plus-install.json');
-    if (!fs.existsSync(manifestPath)) {
-      clack.log.error('❌ BMAD+ is not installed in this directory');
-      clack.outro(pc.red('Run `npx bmad-plus install` first.'));
-      return;
-    }
-
-    let manifest;
-    try {
-      manifest = readInstallManifest(manifestPath);
-    } catch (err) {
-      const i = t(options.lang || 'en');
-      clack.log.error(i.manifest_invalid(err.message));
-      clack.outro(pc.red(i.manifest_repair));
-      process.exitCode = 1;
+  action: async (options = {}) => {
+    const report = collectInstallationHealth({
+      projectDir: options.directory,
+      verifyPython: Boolean(options.verifyPython),
+    });
+    process.exitCode = report.summary.errors ? 1 : 0;
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
       return;
     }
-    clack.log.success(`✅ Manifest found — v${manifest.version}`);
-    passed++;
-
-    // ── Check 2: Version comparison ──
-    checks++;
-    if (manifest.version === packageJson.version) {
-      clack.log.success(`✅ Version up to date (v${manifest.version})`);
-      passed++;
-    } else {
-      clack.log.warn(`⚠️  Version mismatch: installed v${manifest.version} → latest v${packageJson.version}`);
-      clack.log.info('   Run `npx bmad-plus update` to upgrade');
-      warnings++;
+    clack.intro(pc.bgBlue(pc.white(' BMAD+ Doctor v' + report.versions.cli + ' ')));
+    for (const entry of report.checks.filter(
+      (item) => item.status !== 'pass' || item.code === 'manifest.valid'
+    )) {
+      const log =
+        entry.status === 'error'
+          ? clack.log.error
+          : entry.status === 'warning'
+            ? clack.log.warn
+            : clack.log.success;
+      log(
+        entry.message +
+          (entry.path && !entry.message.includes(entry.path) ? ' (' + entry.path + ')' : '')
+      );
     }
-
-    // ── Check 3: Agent files ──
-    checks++;
-    const agentsDir = path.join(projectDir, '.agents', 'skills');
-    if (fs.existsSync(agentsDir)) {
-      const agentDirs = fs.readdirSync(agentsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
-      clack.log.success(`✅ ${agentDirs.length} agent/skill directories found`);
-      passed++;
-
-      // Check each expected agent from manifest packs using shared EXPECTED_AGENTS module
-      for (const pack of (manifest.packs || ['core'])) {
-        const entry = EXPECTED_AGENTS[pack];
-        if (!entry) continue;
-
-        // Check individual agent directories
-        for (const agent of (entry.agents || [])) {
-          checks++;
-          const agentPath = path.join(agentsDir, agent);
-          if (fs.existsSync(agentPath)) {
-            passed++;
-          } else {
-            clack.log.warn(`⚠️  Missing agent: ${agent} (pack: ${pack})`);
-            warnings++;
-          }
-        }
-
-        // Check pack directory if applicable
-        if (entry.packDir) {
-          checks++;
-          const packPath = path.join(agentsDir, entry.packDir);
-          if (fs.existsSync(packPath)) {
-            passed++;
-
-            // These packs bundle their agents as files inside packDir — verify
-            // them there (not as loose directories, which would falsely warn).
-            for (const agentFile of (entry.packAgents || [])) {
-              checks++;
-              if (fs.existsSync(path.join(packPath, agentFile))) {
-                passed++;
-              } else {
-                clack.log.warn(`⚠️  Missing agent: ${agentFile} (pack: ${pack})`);
-                warnings++;
-              }
-            }
-          } else {
-            clack.log.warn(`⚠️  Missing pack directory: ${entry.packDir} (pack: ${pack})`);
-            warnings++;
-          }
-        }
-      }
-    } else {
-      clack.log.error('❌ No .agents/skills/ directory found');
-      errors++;
+    if (report.versions.installed) {
+      clack.note(
+        [
+          report.summary.passed + '/' + report.checks.length + ' checks passed',
+          report.summary.errors + ' error(s), ' + report.summary.warnings + ' warning(s)',
+          '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'
+      );
     }
-
-    // ── Check 4: Config files ──
-    checks++;
-    const configPath = path.join(projectDir, '_bmad', 'config.yaml');
-    if (fs.existsSync(configPath)) {
-      clack.log.success('✅ config.yaml present');
-      passed++;
-    } else {
-      clack.log.error('❌ config.yaml missing');
-      errors++;
-    }
-
-    // ── Check 5: Module config ──
-    checks++;
-    const moduleYaml = path.join(projectDir, '_bmad', 'module.yaml');
-    if (fs.existsSync(moduleYaml)) {
-      clack.log.success('✅ module.yaml present');
-      passed++;
-    } else {
-      clack.log.warn('⚠️  module.yaml missing');
-      warnings++;
-    }
-
-    // ── Check 6: IDE configs ──
-    checks++;
-    const ideFiles = ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md'].filter(f =>
-      fs.existsSync(path.join(projectDir, f))
+    clack.log.info(
+      'Published version is not checked here. Use `bmad-plus update-check --json` to check npm.'
+    );
+    clack.outro(
+      report.status === 'ok'
+        ? pc.green('Installation checks passed.')
+        : pc.yellow(
+            options.verifyPython
+              ? 'Review the reported evidence. Python import probes ran; no provisioning was requested.'
+              : 'Review the reported evidence before changing files. Doctor did not modify the project.'
+          )
     );
-    if (ideFiles.length > 0) {
-      clack.log.success(`✅ ${ideFiles.length} IDE config(s): ${ideFiles.join(', ')}`);
-      passed++;
-    } else {
-      clack.log.warn('⚠️  No IDE config files found');
-      warnings++;
-    }
-
-    // ── Check 7: Output directories ──
-    checks++;
-    const outputDir = path.join(projectDir, '_bmad-output');
-    if (fs.existsSync(outputDir)) {
-      clack.log.success('✅ _bmad-output/ directory exists');
-      passed++;
-    } else {
-      clack.log.warn('⚠️  _bmad-output/ not found');
-      warnings++;
-    }
-
-    // ── Check 8: Skills integrity (SKILL.md exists in pack dirs) ──
-    if (manifest.packs && manifest.packs.includes('seo')) {
-      checks++;
-      const seoSkill = path.join(agentsDir, 'pack-seo', 'SKILL.md');
-      if (fs.existsSync(seoSkill)) {
-        clack.log.success('✅ SEO Engine SKILL.md present');
-        passed++;
-      } else {
-        clack.log.error('❌ SEO Engine SKILL.md missing — /seo audit will not work');
-        errors++;
-      }
-    }
-
-    // ── Summary ──
-    const summaryColor = errors > 0 ? pc.red : warnings > 0 ? pc.yellow : pc.green;
-    const summaryIcon = errors > 0 ? '❌' : warnings > 0 ? '⚠️' : '✅';
-
-    clack.note([
-      `${summaryIcon} ${passed}/${checks} checks passed`,
-      errors > 0 ? `❌ ${errors} error(s)` : null,
-      warnings > 0 ? `⚠️  ${warnings} warning(s)` : null,
-      '',
-      `📦 Version: v${manifest.version}`,
-      `📅 Installed: ${manifest.installed.split('T')[0]}`,
-      `🗣️  Language: ${manifest.language || 'N/A'}`,
-      `📦 Packs: ${(manifest.packs || ['core']).join(', ')}`,
-    ].filter(Boolean).join('\n'), '🩺 BMAD+ Health Report');
-
-    clack.outro(summaryColor(
-      errors > 0
-        ? 'Issues found — run `npx bmad-plus install` to fix'
-        : warnings > 0
-          ? 'Minor issues found — consider running `npx bmad-plus update`'
-          : 'Everything looks great! 🎉'
-    ));
   },
 };

package/tools/cli/commands/install.js

@@ -35,7 +35,7 @@ module.exports = {
     ['-l, --lang <code>', 'Language code: en, fr, es, de, pt-br, ru, zh, he, ja, it (overrides auto-detection)'],
     ['--tools <tools>', 'Comma-separated IDE IDs, all, or none (default: auto-detect)'],
     ['--mode <mode>', 'Execution mode: manual, autopilot, hybrid (default: manual)'],
-    ['--provision-python', 'Provision an isolated Python env for packs that need one (seo, memory)'],
+    ['--provision-python', 'Provision isolated environments for selected Python packs'],
   ],
   action: async (options) => {
     // A closed/piped stdin cannot answer prompts. Require explicit defaults
@@ -180,6 +180,7 @@ module.exports = {
     let userName = process.env.USER || process.env.USERNAME || 'Developer';
     let commLang = 'French';
     let execMode = options.mode || 'manual';
+    let uatEnvironment = '';
 
     if (!options.yes) {
       const userConfig = await clack.group({
@@ -192,6 +193,13 @@ module.exports = {
           message: i.comm_language,
           options: getCommLanguageOptions(),
         }),
+        uatEnvironment: () => clack.text({
+          message:
+            i.uat_environment ||
+            'Test environment for human acceptance recipes (URL, blank if none)',
+          placeholder: 'https://demo.example.com',
+          defaultValue: '',
+        }),
         execMode: () => clack.select({
           message: i.exec_mode,
           options: [
@@ -215,6 +223,7 @@ module.exports = {
       userName = validatedName;
       commLang = userConfig.commLang;
       execMode = options.mode || userConfig.execMode;
+      uatEnvironment = String(userConfig.uatEnvironment || '').trim();
     }
 
     const releaseLock = acquireProjectLock(projectDir);
@@ -366,7 +375,7 @@ module.exports = {
     }
 
     // ── Step 6: Create config.yaml ──
-    const configYaml = generateConfigYaml(userName, commLang, projectDir, execMode);
+    const configYaml = generateConfigYaml(userName, commLang, projectDir, execMode, uatEnvironment);
     const configPath = path.join(targetBmadDir, 'config.yaml');
     fs.writeFileSync(configPath, configYaml, 'utf8');
 
@@ -522,7 +531,7 @@ module.exports = {
   _internal: { writeIDEConfigs, generateConfigYaml },
 };
 
-function generateConfigYaml(userName, language, projectDir, execMode = 'manual') {
+function generateConfigYaml(userName, language, projectDir, execMode = 'manual', uatEnvironment = '') {
   if (!['manual', 'autopilot', 'hybrid'].includes(execMode)) throw new Error('Unknown execution mode: ' + execMode);
   return '# BMAD+ Project Configuration\n# Generated by bmad-plus install\n\n' + yaml.dump({
     user_name: userName,
@@ -539,5 +548,15 @@ function generateConfigYaml(userName, language, projectDir, execMode = 'manual')
       story: execMode === 'autopilot' ? 'notify_only' : 'require_approval',
       delivery: 'require_approval',
     },
+    // Human acceptance recipes. advisory: every delivery produces and offers its page and
+    // nothing is ever blocked. gate: the delivery waits for a passing "bmad-plus uat gate".
+    // off: no recipe, and the delivery report says so.
+    uat: {
+      mode: 'advisory',
+      granularity: 'delivery',
+      environment: { name: uatEnvironment ? 'TEST' : '', url: uatEnvironment || '' },
+      page_budget: { max_steps: 15, max_minutes: 30 },
+      dir: '_bmad-output/uat',
+    },
   }, { lineWidth: -1, forceQuotes: true, quotingType: '"' });
 }

package/tools/cli/commands/memory-journal-cmd.js

@@ -32,6 +32,8 @@
 const path = require('node:path');
 const fs = require('node:fs');
 const mj = require('../lib/memory-journal');
+const store = require('../lib/memory-store');
+const outcomes = require('../lib/memory-outcomes');
 
 // ── Pattern score store ──────────────────────────────────────────────────────
 // Lives next to the journal in the north-star scope (.bmad/memory/). Keyed by
@@ -63,9 +65,7 @@ function readScores(baseDir) {
 }
 
 function writeScores(baseDir, scores) {
-  const file = scoresPath(baseDir);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify(scores, null, 2) + '\n', 'utf8');
+  store.writeJson(baseDir, SCORES_RELPATH, scores);
 }
 
 // ── Flag parsing helpers ─────────────────────────────────────────────────────
@@ -104,12 +104,30 @@ function truncate(text, max = 120) {
  * @returns {object[]} ranked entries (same shape as memory-journal.recall)
  */
 function runRecall(query, opts = {}) {
-  const { baseDir = process.cwd(), scope = 'project', portfolioDir = null, limit = 8, now = null, json = false, log = console.log } = opts;
+  const {
+    baseDir = process.cwd(),
+    scope = 'project',
+    portfolioDir = null,
+    limit = 8,
+    now = null,
+    json = false,
+    log = console.log,
+    ranking = 'lexical',
+    contextScope,
+  } = opts;
 
-  const results = mj.recall(query, { baseDir, scope, portfolioDir, limit, now });
+  const results = mj.recall(query, {
+    baseDir,
+    scope,
+    portfolioDir,
+    limit,
+    now,
+    ranking,
+    contextScope,
+  });
 
   if (json) {
-    log(JSON.stringify({ query, scope, count: results.length, results }, null, 2));
+    log(JSON.stringify({ query, scope, ranking, count: results.length, results }, null, 2));
     return results;
   }
 
@@ -119,7 +137,8 @@ function runRecall(query, opts = {}) {
   }
   log(`mem recall: ${results.length} match(es) for "${query}" (scope: ${scope})`);
   results.forEach((r, i) => {
-    const origin = r.kind === 'event' ? `event ${r.source}#${r.ref}` : `note ${r.source} § ${r.ref}`;
+    const origin =
+      r.kind === 'event' ? `event ${r.source}#${r.ref}` : `note ${r.source} § ${r.ref}`;
     log(`  ${i + 1}. [${r.score.toFixed(3)}] ${origin}`);
     log(`     ${truncate(r.text)}`);
   });
@@ -134,7 +153,18 @@ function runRecall(query, opts = {}) {
  * @returns {object} the persisted event
  */
 function runWrite(opts = {}) {
-  const { baseDir = process.cwd(), agent, cli = null, model = null, task = '', outcome = undefined, signals = {}, now, json = false, log = console.log } = opts;
+  const {
+    baseDir = process.cwd(),
+    agent,
+    cli = null,
+    model = null,
+    task = '',
+    outcome = undefined,
+    signals = {},
+    now,
+    json = false,
+    log = console.log,
+  } = opts;
 
   const event = mj.appendEvent(baseDir, {
     ts: now,
@@ -150,7 +180,9 @@ function runWrite(opts = {}) {
     log(JSON.stringify({ written: event }, null, 2));
   } else {
     log(`mem write: event ${event.id} appended (${event.ts})`);
-    log(`  agent=${event.agent} cli=${event.cli || '-'} model=${event.model || '-'} outcome=${event.outcome || '-'}`);
+    log(
+      `  agent=${event.agent} cli=${event.cli || '-'} model=${event.model || '-'} outcome=${event.outcome || '-'}`
+    );
     if (event.task) log(`  task: ${truncate(event.task)}`);
   }
   return event;
@@ -168,10 +200,24 @@ function runWrite(opts = {}) {
  * @returns {{patternId:string, reward:number, previous:object, next:object, promotion:object|null}}
  */
 function runReinforce(opts = {}) {
-  const { baseDir = process.cwd(), patternId, signals = {}, evidence = [], now, json = false, log = console.log } = opts;
+  return store.withMemoryLock(opts.baseDir || process.cwd(), () => reinforceUnderLock(opts));
+}
+
+function reinforceUnderLock(opts = {}) {
+  const {
+    baseDir = process.cwd(),
+    patternId,
+    signals = {},
+    evidence = [],
+    now,
+    json = false,
+    log = console.log,
+  } = opts;
 
   if (typeof patternId !== 'string' || patternId.trim().length === 0) {
-    throw new TypeError('mem reinforce: --pattern <id> is required (the pattern heading in patterns.md)');
+    throw new TypeError(
+      'mem reinforce: --pattern <id> is required (the pattern heading in patterns.md)'
+    );
   }
 
   const reward = mj.computeReward(signals);
@@ -198,7 +244,15 @@ function runReinforce(opts = {}) {
     );
   }
 
-  const result = { patternId, reward, previous, next, promotion };
+  const result = {
+    patternId,
+    reward,
+    previous,
+    next,
+    promotion,
+    evidenceStatus: 'self-reported',
+    rankingEligible: false,
+  };
 
   if (json) {
     log(JSON.stringify(result, null, 2));
@@ -209,12 +263,16 @@ function runReinforce(opts = {}) {
   log(`mem reinforce: pattern "${patternId}"`);
   log(`  reward   ${reward.toFixed(3)} (from ${JSON.stringify(signals)})`);
   log(`  elo      ${prevElo.toFixed(1)} -> ${next.elo.toFixed(1)}`);
-  log(`  mean     ${next.mean.toFixed(3)} (alpha=${next.alpha.toFixed(2)}, beta=${next.beta.toFixed(2)}, updates=${next.updates})`);
+  log(
+    `  mean     ${next.mean.toFixed(3)} (alpha=${next.alpha.toFixed(2)}, beta=${next.beta.toFixed(2)}, updates=${next.updates})`
+  );
   if (promotion) {
     log(`  promotion PROPOSED (${promotion.id}): ${promotion.fromStatus} -> ${promotion.toStatus}`);
     log(`  awaiting human/Shield approval — never auto-applied (governance guard)`);
   } else {
-    log(`  promotion: none proposed (needs mean >= ${PROMOTION_MEAN_THRESHOLD} and >= ${PROMOTION_MIN_UPDATES} updates)`);
+    log(
+      `  promotion: none proposed (needs mean >= ${PROMOTION_MEAN_THRESHOLD} and >= ${PROMOTION_MIN_UPDATES} updates)`
+    );
   }
   return result;
 }
@@ -223,14 +281,20 @@ function runReinforce(opts = {}) {
 
 module.exports = {
   command: 'mem <action> [query...]',
-  description: 'Karpathy memory loop — recall | write | reinforce (portable across agent CLIs)',
+  description: 'Project memory — recall | write | reinforce | observe | outcomes',
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['--scope <scope>', 'Recall scope: project | portfolio', 'project'],
     ['--portfolio <path>', 'Portfolio brain directory (used with --scope portfolio)'],
     ['--limit <n>', 'Max recall results', '8'],
+    ['--ranking <mode>', 'Recall ranking: lexical | evidence (project only)', 'lexical'],
+    ['--context-scope <paths>', 'Comma-separated project paths for evidence recall'],
+    ['--input <file>', 'Project-relative JSON outcome observation input (observe)'],
     ['--agent <name>', 'Agent that produced the event (write)'],
-    ['--cli <name>', 'Driving CLI: claude-code, gemini-cli, codex-cli, cursor, opencode, aider, antigravity'],
+    [
+      '--cli <name>',
+      'Driving CLI: claude-code, gemini-cli, codex-cli, cursor, opencode, aider, antigravity',
+    ],
     ['--model <id>', 'Model id used (model-agnostic: claude/gpt/gemini/local)'],
     ['--task <text>', 'What was attempted (write)'],
     ['--outcome <outcome>', 'success | failure | partial | abandoned (write)'],
@@ -245,6 +309,8 @@ module.exports = {
     recall: 'Ranked retrieval over the journal + memory files',
     write: 'Append a structured event to .bmad/memory/journal.ndjson',
     reinforce: 'Apply a reward to a pattern score (promotions PROPOSED only)',
+    observe: 'Record accepted current Nexus evidence for an exact memory section',
+    outcomes: 'Inspect stored outcomes and their current eligibility',
   },
 
   action: async (action, query, options = {}) => {
@@ -264,6 +330,12 @@ module.exports = {
           limit: Number(options.limit || 8),
           now,
           json,
+          ranking: options.ranking || 'lexical',
+          contextScope: options.contextScope
+            ? String(options.contextScope)
+                .split(',')
+                .map((s) => s.trim())
+            : undefined,
         });
       } else if (action === 'write') {
         runWrite({
@@ -282,16 +354,44 @@ module.exports = {
           baseDir,
           patternId: options.pattern,
           signals: parseSignals(options),
-          evidence: options.evidence ? String(options.evidence).split(',').map(s => s.trim()).filter(Boolean) : [],
+          evidence: options.evidence
+            ? String(options.evidence)
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : [],
           now,
           json,
         });
+      } else if (action === 'observe') {
+        const input = JSON.parse(store.readText(baseDir, options.input));
+        const written = outcomes.observeOutcome(baseDir, input, { now });
+        console.log(
+          json
+            ? JSON.stringify({ written }, null, 2)
+            : `mem observe: ${written.id} recorded; lesson causality remains unmeasured.`
+        );
+      } else if (action === 'outcomes') {
+        const results = outcomes.inspectOutcomes(baseDir);
+        console.log(
+          json
+            ? JSON.stringify({ count: results.length, results }, null, 2)
+            : results
+                .map(
+                  (record) =>
+                    `${record.id}: ${record.eligible ? 'accepted-current' : record.reason}`
+                )
+                .join('\n') || 'mem outcomes: no observations.'
+        );
       } else {
-        console.error(`mem: unknown action '${action}' — expected recall | write | reinforce`);
+        console.error(
+          `mem: unknown action '${action}' — expected recall | write | reinforce | observe | outcomes`
+        );
         process.exitCode = 1;
       }
     } catch (err) {
-      console.error(`mem ${action}: ${err.message}`);
+      if (json) console.log(JSON.stringify({ error: err.message }));
+      else console.error(`mem ${action}: ${err.message}`);
       process.exitCode = 1;
     }
   },