bmad-plus 0.14.0 → 0.17.0

package/tools/cli/commands/install.js

@@ -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;
     }
   },

package/tools/cli/commands/nexus.js

@@ -0,0 +1,111 @@
+/** Persist host-owned work, reconcile interruptions and verify current artifacts. */
+const fs = require('node:fs');
+const path = require('node:path');
+const nexus = require('../lib/nexus');
+
+function inputFile(file, option) {
+  if (!file) throw new Error(option + ' requires a JSON file.');
+  const absolute = path.resolve(file);
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) {
+    throw new Error(option + ' must name a regular JSON file no larger than 1 MiB.');
+  }
+  const value = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(option + ' must contain a JSON object.');
+  }
+  return value;
+}
+
+function summary(result) {
+  if (!result.tasks) return JSON.stringify(result, null, 2);
+  return [
+    `Nexus run ${result.id} — durable task coordination`,
+    ...result.tasks.map((task) => {
+      const attempt = task.attempts.at(-1);
+      const observation = result.observations?.find((item) => item.taskId === task.id);
+      return (
+        `${task.id}: ${attempt?.execution || 'not started'}; verification=${attempt?.verification.status || 'pending'}; acceptance=${task.integration}` +
+        (attempt
+          ? `\n  Attempt: ${attempt.id}; ${attempt.backend.kind}: ${attempt.backend.id}/${attempt.backend.sessionId}`
+          : '') +
+        (observation
+          ? `\n  ${observation.hint}${observation.stale ? ' STALE: ' + observation.staleReason : ''}`
+          : '')
+      );
+    }),
+    'Use inspect --json for recorded evidence and reconciliation observations.',
+  ].join('\n');
+}
+
+module.exports = {
+  command: 'nexus <action> [run] [task]',
+  description:
+    'Launch or coordinate attempts, recover interrupted work and verify current artifacts',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--plan <file>', 'JSON task plan for create'],
+    ['--input <file>', 'JSON observation or host identity for a mutation'],
+    ['--json', 'Print durable state and evidence as JSON'],
+  ],
+  action: async (action, runId, taskId, options = {}) => {
+    try {
+      const directory = path.resolve(options.directory || process.cwd());
+      let result;
+      if (action === 'create' && !runId && !taskId) {
+        if (options.input) throw new Error('create uses --plan.');
+        result = nexus.createRun(directory, inputFile(options.plan, '--plan'));
+      } else if (action === 'recover-lock' && !runId && !taskId) {
+        if (options.plan) throw new Error('recover-lock uses --input.');
+        result = nexus.recoverLock(directory, inputFile(options.input, '--input'));
+      } else if (action === 'inspect' && !taskId) {
+        if (options.input || options.plan)
+          throw new Error('inspect is read-only and takes no input file.');
+        result = nexus.inspectRun(directory, runId);
+      } else {
+        const mutations = {
+          start: nexus.startTask,
+          launch: nexus.launchTask,
+          collect: nexus.collectTask,
+          record: nexus.recordAttempt,
+          reconcile: nexus.reconcileAttempt,
+          verify: nexus.verifyTask,
+          retry: nexus.retryTask,
+          cancel: nexus.cancelTask,
+          accept: nexus.acceptTask,
+        };
+        if (!Object.hasOwn(mutations, action) || !runId || !taskId || options.plan) {
+          throw new Error(
+            'Use nexus create --plan FILE, inspect RUN, or start|launch|collect|record|reconcile|verify|retry|cancel|accept RUN TASK.'
+          );
+        }
+        const needsInput = !['verify', 'accept'].includes(action);
+        if (!needsInput && options.input)
+          throw new Error(action + ' executes its recorded contract and takes no input file.');
+        result = await mutations[action](
+          directory,
+          runId,
+          taskId,
+          action === 'launch' && !options.input
+            ? {}
+            : needsInput
+              ? inputFile(options.input, '--input')
+              : undefined
+        );
+      }
+      const latest = result.tasks?.find((task) => task.id === taskId)?.attempts.at(-1);
+      process.exitCode =
+        (action === 'verify' && latest?.verification.status !== 'passed') ||
+        (action === 'launch' && latest?.process?.receipt?.outcome !== 'completed') ||
+        (action === 'collect' && latest?.execution !== 'completed')
+          ? 1
+          : 0;
+      console.log(options.json ? JSON.stringify(result, null, 2) : summary(result));
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
+      else console.error('Nexus: ' + error.message);
+    }
+  },
+};