bmad-plus 0.9.1 → 0.12.0

package/tools/cli/commands/install.js

@@ -17,6 +17,21 @@ const { copyPackFiles } = require('../lib/pack-copy');
 const { initMemory } = require('../lib/memory-init');
 const { generateIDEConfig, IDE_CONFIGS } = require('../lib/ide-config');
 const { validateUserName } = require('../lib/validate');
+const { provisionPack } = require('../lib/python-provision');
+
+// Packs whose runtime includes Python (registry.yaml: runtime includes "python").
+// Provisioned only when the user opts in with --provision-python, so the default
+// install (and the test suite) never spawns Python. Kills SEO "broken on arrival".
+const PYTHON_PACKS = {
+  seo: {
+    requirements: ['oveanet-pack', 'seo-audit-360', 'requirements.txt'],
+    verifyModules: ['requests', 'bs4', 'defusedxml', 'lxml'],
+  },
+  memory: {
+    requirements: ['mcp-server', 'requirements.txt'],
+    verifyModules: ['chromadb'],
+  },
+};
 
 // Pack definitions are imported from the shared module: require('../lib/packs').PACKS
 
@@ -29,6 +44,7 @@ module.exports = {
     ['-y, --yes', 'Accept all defaults, skip prompts'],
     ['-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 (default: auto-detect)'],
+    ['--provision-python', 'Provision an isolated Python env for packs that need one (seo, memory)'],
   ],
   action: async (options) => {
     const projectDir = path.resolve(options.directory || process.cwd());
@@ -225,6 +241,36 @@ module.exports = {
       }
     }
 
+    // ── Python provisioning (opt-in) — for packs whose runtime needs Python ──
+    // Off by default so `install` never spawns Python unless asked. Closes the
+    // "SEO pack ships prompts that call scripts never installed" gap (PROD-02).
+    if (options.provisionPython) {
+      const pythonPacks = selectedPacks.filter((p) => PYTHON_PACKS[p]);
+      for (const packId of pythonPacks) {
+        const cfg = PYTHON_PACKS[packId];
+        const requirementsPath = path.join(projectRoot, ...cfg.requirements);
+        if (!fs.existsSync(requirementsPath)) {
+          clack.log.warn(`Python provisioning skipped for ${packId}: ${requirementsPath} not found.`);
+          continue;
+        }
+        const pySpinner = clack.spinner();
+        pySpinner.start(`Provisioning Python runtime for ${PACKS[packId].name}…`);
+        const res = provisionPack({
+          envDir: path.join(projectDir, '.bmad', 'venv', packId),
+          requirementsPath,
+          verifyModules: cfg.verifyModules,
+        });
+        pySpinner.stop(
+          res.ok
+            ? `${PACKS[packId].name}: Python runtime ready (${res.tool}).`
+            : `${PACKS[packId].name}: Python not provisioned — ${res.messages[res.messages.length - 1] || 'see guidance'}`
+        );
+        if (!res.ok) {
+          clack.log.warn(`Run \`${PACKS[packId].name}\` Python tools after installing Python ≥3.11; the pack's prompts still work, only the local scripts need the runtime.`);
+        }
+      }
+    }
+
     // Copy module config
     const moduleYaml = path.join(bmadSrc, 'module.yaml');
     if (fs.existsSync(moduleYaml)) {
@@ -246,12 +292,32 @@ module.exports = {
       ideSpinner.start(i.configuring_ides);
 
       const configContent = generateIDEConfig(userName, commLang, selectedPacks);
+      // Marker present in every BMAD+-generated IDE config (see lib/ide-config.js).
+      const BMAD_MARKER = 'BMAD+ — AI Agent Configuration';
 
       for (const ideId of detectedIDEs) {
         const ide = IDE_CONFIGS[ideId];
         if (!ide) continue;
 
         const configPath = path.join(projectDir, ide.configFile);
+
+        // NODE-02: never clobber a hand-authored config without protecting it.
+        if (fs.existsSync(configPath)) {
+          const existing = fs.readFileSync(configPath, 'utf8');
+          if (!existing.includes(BMAD_MARKER)) {
+            if (!options.yes) {
+              // Interactive: keep the user's file untouched.
+              clack.log.warn(`⚠️  ${ide.configFile} already exists and was not created by BMAD+ — kept your file (skipped). Re-run with --yes to back it up and overwrite.`);
+              continue;
+            }
+            // Non-interactive: back up before overwriting, never destroy data.
+            let backupPath = `${configPath}.bak`;
+            if (fs.existsSync(backupPath)) backupPath = `${configPath}.${Date.now()}.bak`;
+            fs.copyFileSync(configPath, backupPath);
+            clack.log.warn(`⚠️  Backed up existing ${ide.configFile} → ${path.basename(backupPath)}`);
+          }
+        }
+
         fs.writeFileSync(configPath, configContent, 'utf8');
       }
 

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

@@ -0,0 +1,311 @@
+/**
+ * BMAD+ `mem` Command — portable Karpathy memory loop (Pillar 3)
+ *
+ * Exposes tools/cli/lib/memory-journal.js through the CLI so recall / write /
+ * reinforce behave IDENTICALLY no matter which agent CLI is driving
+ * (claude-code, gemini-cli, codex-cli, cursor, opencode, aider, antigravity):
+ *
+ *   bmad-plus mem recall <query...>   — ranked retrieval over journal + memory files
+ *   bmad-plus mem write               — append a structured event (--agent --cli --model --task --outcome)
+ *   bmad-plus mem reinforce           — apply a reward to a pattern score; any resulting
+ *                                       promotion is persisted as PROPOSED, never applied
+ *
+ * NOTE: registered as `mem` (not `memory`) — `memory` is already taken by the
+ * brain scanner in tools/cli/commands/memory.js and must not be disturbed.
+ *
+ * Design rules (mirroring memory-journal.js):
+ *   - The clock is read ONCE inside the action (new Date().toISOString()) and
+ *     injected into every library call. Nothing reads the clock at import time.
+ *   - The run* handlers take an injected `now` + `log`, so tests drive them
+ *     deterministically against a tmp dir (tests/unit/memory-journal-cmd.test.js).
+ *   - Output goes through plain log lines (+ --json for machine consumption) so
+ *     ANY driving CLI can parse results — no interactive prompts, no TTY needs.
+ *   - Governance guard: reinforce may PROPOSE a pattern promotion when the
+ *     posterior mean crosses the threshold, but the record is always written
+ *     with status PROPOSED (memory-journal.appendPromotion forces it anyway).
+ *
+ * Author: Laurent Rochetta
+ */
+
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const mj = require('../lib/memory-journal');
+
+// ── Pattern score store ──────────────────────────────────────────────────────
+// Lives next to the journal in the north-star scope (.bmad/memory/). Keyed by
+// patternId (the `### heading` in patterns.md). This file is CLI-owned state;
+// memory-journal.js stays a pure library and never touches it.
+
+const SCORES_RELPATH = path.join('.bmad', 'memory', 'pattern-scores.json');
+
+// Promotion proposal thresholds (candidate → validated). Tuned conservatively:
+// the posterior mean is decayed-Bayesian (memory-journal.updatePatternScore),
+// so 0.7 over >= 3 updates means a genuinely recent, repeated success signal.
+const PROMOTION_MEAN_THRESHOLD = 0.7;
+const PROMOTION_MIN_UPDATES = 3;
+
+function scoresPath(baseDir) {
+  return path.join(baseDir, SCORES_RELPATH);
+}
+
+function readScores(baseDir) {
+  const file = scoresPath(baseDir);
+  if (!fs.existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    // Corrupt store never blocks the loop — reinforcement restarts from priors.
+    return {};
+  }
+}
+
+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');
+}
+
+// ── Flag parsing helpers ─────────────────────────────────────────────────────
+
+/** Map CLI flags to the memory-journal signals shape { evalScore, acceptance, ci }. */
+function parseSignals(opts) {
+  const signals = {};
+  if (opts.eval !== undefined && opts.eval !== null) {
+    signals.evalScore = Number(opts.eval);
+  }
+  if (opts.accept !== undefined && opts.accept !== null) {
+    const raw = String(opts.accept).toLowerCase();
+    if (raw === 'true' || raw === 'yes') signals.acceptance = true;
+    else if (raw === 'false' || raw === 'no') signals.acceptance = false;
+    else signals.acceptance = Number(opts.accept);
+  }
+  if (opts.ci !== undefined && opts.ci !== null) {
+    signals.ci = opts.ci === 'pass' || opts.ci === 'fail' ? opts.ci : Number(opts.ci);
+  }
+  return signals;
+}
+
+function truncate(text, max = 120) {
+  const oneLine = String(text).replace(/\s+/g, ' ').trim();
+  return oneLine.length > max ? oneLine.slice(0, max - 1) + '…' : oneLine;
+}
+
+// ── Action handlers (dependency-injected, unit-testable) ─────────────────────
+
+/**
+ * `mem recall <query...>` — ranked retrieval over journal events + memory notes.
+ *
+ * @param {string} query
+ * @param {object} opts - { baseDir, scope, portfolioDir, limit, now, json, log }
+ *                        `now` is the INJECTED clock (enables recency decay).
+ * @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 results = mj.recall(query, { baseDir, scope, portfolioDir, limit, now });
+
+  if (json) {
+    log(JSON.stringify({ query, scope, count: results.length, results }, null, 2));
+    return results;
+  }
+
+  if (results.length === 0) {
+    log(`mem recall: no matches for "${query}" (scope: ${scope})`);
+    return results;
+  }
+  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}`;
+    log(`  ${i + 1}. [${r.score.toFixed(3)}] ${origin}`);
+    log(`     ${truncate(r.text)}`);
+  });
+  return results;
+}
+
+/**
+ * `mem write` — append a structured event to the journal.
+ *
+ * @param {object} opts - { baseDir, agent, cli, model, task, outcome, signals, now, json, log }
+ *                        `now` is the INJECTED clock used as the event ts.
+ * @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 event = mj.appendEvent(baseDir, {
+    ts: now,
+    agent,
+    cli,
+    model,
+    task,
+    outcome,
+    signals,
+  });
+
+  if (json) {
+    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 || '-'}`);
+    if (event.task) log(`  task: ${truncate(event.task)}`);
+  }
+  return event;
+}
+
+/**
+ * `mem reinforce` — fold reward signals into a pattern's score.
+ *
+ * Updates the CLI-owned pattern-scores.json (Elo for ranking, decayed-Bayesian
+ * mean for promotion). When the mean crosses PROMOTION_MEAN_THRESHOLD with
+ * enough updates, a promotion is PROPOSED via memory-journal's governance
+ * guard — persisted as PROPOSED, applied only after human/Shield approval.
+ *
+ * @param {object} opts - { baseDir, patternId, signals, evidence, now, json, log }
+ * @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;
+
+  if (typeof patternId !== 'string' || patternId.trim().length === 0) {
+    throw new TypeError('mem reinforce: --pattern <id> is required (the pattern heading in patterns.md)');
+  }
+
+  const reward = mj.computeReward(signals);
+  const scores = readScores(baseDir);
+  const previous = scores[patternId] || null;
+  const next = mj.updatePatternScore(previous, reward, { ts: now });
+  scores[patternId] = next;
+  writeScores(baseDir, scores);
+
+  // Governance: promotion is only ever PROPOSED here. appendPromotion() forces
+  // status PROPOSED on disk regardless, and applying requires
+  // assertPromotionApplicable() to pass with a human/Shield approval.
+  let promotion = null;
+  if (next.mean >= PROMOTION_MEAN_THRESHOLD && next.updates >= PROMOTION_MIN_UPDATES) {
+    promotion = mj.appendPromotion(
+      baseDir,
+      mj.proposePromotion({
+        patternId,
+        ts: now,
+        reason: `posterior mean ${next.mean.toFixed(3)} >= ${PROMOTION_MEAN_THRESHOLD} over ${next.updates} update(s)`,
+        evidence,
+        score: next,
+      })
+    );
+  }
+
+  const result = { patternId, reward, previous, next, promotion };
+
+  if (json) {
+    log(JSON.stringify(result, null, 2));
+    return result;
+  }
+
+  const prevElo = previous ? previous.elo : mj.INITIAL_PATTERN_SCORE.elo;
+  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})`);
+  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)`);
+  }
+  return result;
+}
+
+// ── Commander wiring ─────────────────────────────────────────────────────────
+
+module.exports = {
+  command: 'mem <action> [query...]',
+  description: 'Karpathy memory loop — recall | write | reinforce (portable across agent CLIs)',
+  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'],
+    ['--agent <name>', 'Agent that produced the event (write)'],
+    ['--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)'],
+    ['--pattern <id>', 'Pattern id to reinforce (its heading in patterns.md)'],
+    ['--eval <score>', 'Eval suite score in [0,1] (write/reinforce signal)'],
+    ['--accept <bool>', 'User acceptance: true | false | [0,1] (write/reinforce signal)'],
+    ['--ci <result>', 'CI outcome: pass | fail | [0,1] (write/reinforce signal)'],
+    ['--evidence <ids>', 'Comma-separated journal event ids backing a reinforcement'],
+    ['--json', 'Machine-readable JSON output'],
+  ],
+  subcommands: {
+    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)',
+  },
+
+  action: async (action, query, options = {}) => {
+    // Clock is read HERE, at call time, then injected everywhere below —
+    // memory-journal.js never reads it (see its determinism contract).
+    const now = new Date().toISOString();
+    const baseDir = path.resolve(options.directory || process.cwd());
+    const json = Boolean(options.json);
+    const queryText = Array.isArray(query) ? query.join(' ') : query || '';
+
+    try {
+      if (action === 'recall') {
+        runRecall(queryText, {
+          baseDir,
+          scope: options.scope || 'project',
+          portfolioDir: options.portfolio || null,
+          limit: Number(options.limit || 8),
+          now,
+          json,
+        });
+      } else if (action === 'write') {
+        runWrite({
+          baseDir,
+          agent: options.agent,
+          cli: options.cli || null,
+          model: options.model || null,
+          task: options.task || '',
+          outcome: options.outcome,
+          signals: parseSignals(options),
+          now,
+          json,
+        });
+      } else if (action === 'reinforce') {
+        runReinforce({
+          baseDir,
+          patternId: options.pattern,
+          signals: parseSignals(options),
+          evidence: options.evidence ? String(options.evidence).split(',').map(s => s.trim()).filter(Boolean) : [],
+          now,
+          json,
+        });
+      } else {
+        console.error(`mem: unknown action '${action}' — expected recall | write | reinforce`);
+        process.exitCode = 1;
+      }
+    } catch (err) {
+      console.error(`mem ${action}: ${err.message}`);
+      process.exitCode = 1;
+    }
+  },
+
+  // Exported for tests + future MCP wrapper (memory.recall / memory.write tools)
+  _internal: {
+    runRecall,
+    runWrite,
+    runReinforce,
+    parseSignals,
+    readScores,
+    writeScores,
+    SCORES_RELPATH,
+    PROMOTION_MEAN_THRESHOLD,
+    PROMOTION_MIN_UPDATES,
+  },
+};

package/tools/cli/commands/scan.js

@@ -118,6 +118,22 @@ function scanDirectory(rootDir, maxDepth = 4, currentDepth = 0, activeDays = 30,
   return projects;
 }
 
+/**
+ * Normalize a filesystem path for stable hashing.
+ * On Windows the same project can be referenced as `D:\proj` or `d:\proj`
+ * (case-insensitive drive) with mixed separators. Resolving + lowercasing the
+ * drive letter ensures the same project produces the same index key and is not
+ * double-indexed.
+ * @param {string} p - Raw filesystem path
+ * @returns {string} Normalized path suitable for hashing
+ */
+function normalizePathForHash(p) {
+  let resolved = path.resolve(p);
+  // Lowercase a leading Windows drive letter (e.g. "D:" → "d:").
+  resolved = resolved.replace(/^([A-Za-z]):/, (_m, drive) => drive.toLowerCase() + ':');
+  return resolved;
+}
+
 /**
  * Index a single project in the global brain by writing its metadata YAML file.
  * @param {object} project - Project metadata object
@@ -125,7 +141,7 @@ function scanDirectory(rootDir, maxDepth = 4, currentDepth = 0, activeDays = 30,
  * @returns {void}
  */
 function indexProject(project, globalBrainDir) {
-  const hash = crypto.createHash('sha256').update(project.path).digest('hex').slice(0, 8);
+  const hash = crypto.createHash('sha256').update(normalizePathForHash(project.path)).digest('hex').slice(0, 8);
   const meta = {
     path: project.path,
     name: project.name,
@@ -341,6 +357,7 @@ module.exports = {
     getProjectName,
     hasBmadInstalled,
     scanDirectory,
+    normalizePathForHash,
     indexProject,
     indexProjects,
   },

package/tools/cli/commands/uninstall.js

@@ -86,7 +86,9 @@ module.exports = {
       const p = path.join(projectDir, configFile);
       if (fs.existsSync(p)) {
         const content = fs.readFileSync(p, 'utf8');
-        if (content.includes('BMAD+')) {
+        // NODE-05: only remove a config BMAD+ actually generated (it carries the
+        // marker below). A hand-authored file that merely mentions "BMAD+" is kept.
+        if (content.includes('BMAD+ — AI Agent Configuration')) {
           fs.unlinkSync(p);
           removed++;
         }

package/tools/cli/commands/update.js

@@ -39,7 +39,21 @@ module.exports = {
       return;
     }
 
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      clack.log.error(`Install manifest is unreadable or corrupt: ${err.message}`);
+      clack.log.info('Re-run `npx bmad-plus install` to repair the installation.');
+      clack.outro(pc.red('Update aborted.'));
+      return;
+    }
+    if (!manifest || typeof manifest !== 'object') {
+      clack.log.error('Install manifest is malformed (not an object).');
+      clack.log.info('Re-run `npx bmad-plus install` to repair the installation.');
+      clack.outro(pc.red('Update aborted.'));
+      return;
+    }
     const lang = options.lang || manifest.uiLanguage || 'en';
     const i = t(lang);
 
@@ -51,7 +65,10 @@ module.exports = {
       return;
     }
 
-    const selectedPacks = manifest.packs || ['core'];
+    // Guard against a missing/malformed `packs` field (NODE-04): coerce to an array.
+    const selectedPacks = Array.isArray(manifest.packs) && manifest.packs.length > 0
+      ? manifest.packs
+      : ['core'];
     clack.log.info(`${i.selected_packs}: ${selectedPacks.join(', ')}`);
 
     const confirm = await clack.confirm({

package/tools/cli/lib/README-memory-journal.md

@@ -0,0 +1,125 @@
+# memory-journal.js — Karpathy Learning Layer core (Pillar 3)
+
+Portable data structures + helpers for the BMAD+ **memory → reward → reinforcement** loop.
+Prompt-level learning only: scores steer retrieval and pattern promotion — there is
+**no base-model fine-tuning** (see `audit/2026-07-01/north-star/registry.yaml` →
+`memory.reward_signal.applies_to`).
+
+Builds **on top of** the existing `pack-memory` (Zecher, Karpathy guardrails G1–G4,
+`decisions/lessons/patterns/context.md` templates). It never modifies those files or
+`tools/cli/lib/memory-init.js` — it adds a structured, machine-readable layer beside them.
+
+```
+.bmad/memory/journal.ndjson      ← structured event log (this module, north-star scope)
+.bmad/memory/promotions.ndjson   ← governance queue (always PROPOSED)
+.agents/memory/*.md              ← human memory (pack-memory, current layout) — READ ONLY here
+.bmad/memory/*.md                ← human memory (north-star layout) — READ ONLY here
+```
+
+## Hard rules baked into the module
+
+| Rule | Enforcement |
+|---|---|
+| No hidden clock / randomness | `ts` is a **required, caller-injected** field; ids are content hashes (sha256). The module never calls `Date.now()` or `Math.random()` — at import or runtime. |
+| Node stdlib only | `fs`, `path`, `crypto`. No network, no native deps → runs identically under every CLI. |
+| Journal is append-only, corruption-tolerant | `readJournal`/`readPromotions` skip torn lines instead of throwing (concurrent CLIs may write). |
+| Promotions are never auto-applied | `proposePromotion()` only emits `status: 'PROPOSED'`; `appendPromotion()` **forces** `PROPOSED` + clears approval fields on disk even for tampered records; `assertPromotionApplicable()` throws unless `status === 'APPROVED'` **and** `approvedBy` names a human/Shield reviewer. |
+
+## API
+
+### 1. Journal
+
+```js
+const mj = require('./memory-journal');
+
+mj.appendEvent(projectDir, {
+  ts: new Date().toISOString(),        // REQUIRED — injected by the caller
+  agent: 'forge',                      // REQUIRED
+  cli: 'claude-code',                  // claude-code | gemini-cli | antigravity | cursor | codex-cli | opencode | aider
+  model: 'claude',                     // model-agnostic by contract (claude/gpt/gemini/local)
+  task: 'refactor postgres pooling',
+  outcome: 'success',                  // success | failure | partial | abandoned
+  signals: { evalScore: 0.9, acceptance: true, ci: 'pass' },
+  artifactHashes: ['abc123'],          // traceability to produced artifacts
+});
+
+mj.readJournal(projectDir);            // → events[], oldest first, corrupt lines skipped
+```
+
+### 2. Recall (lexical first cut + vector-backend seam)
+
+```js
+mj.recall('postgres pooling', {
+  baseDir: projectDir,
+  scope: 'project',                    // or 'portfolio' + portfolioDir: 'D:/travail/DEV/_brain'
+  limit: 8,
+  now: new Date().toISOString(),       // optional injected clock → recency decay on events
+  halfLifeDays: 30,
+});
+// → [{ score, kind: 'event'|'note', source, ref, text, event? }] ranked desc
+```
+
+Sources merged: `journal.ndjson` events + `### `-sectioned entries from
+`decisions.md` / `lessons.md` / `patterns.md` in **both** `.bmad/memory/` (north-star)
+and `.agents/memory/` (current pack-memory layout), plus `<portfolioDir>/memory/*.md`
+when `scope: 'portfolio'`.
+
+**ChromaDB seam** — pass `backend: { search(query, opts) }` and ranking is delegated
+wholesale to it. The intended production backend is the existing RAG stack
+(`mcp-server/rag.py`: ChromaDB + SentenceTransformers — `registry.yaml → memory.index`).
+Backends must return the same entry shape as the lexical fallback, so callers never
+know which engine served them. The lexical scorer is the zero-dependency fallback for
+machines without Python provisioned.
+
+### 3. Reward + pattern score
+
+```js
+const reward = mj.computeReward({ evalScore: 0.8, acceptance: true, ci: 'fail' });
+// weights eval 0.5 / acceptance 0.3 / ci 0.2 (registry.yaml → memory.reward_signal.inputs)
+// missing signals renormalize the remaining weights; result always in [0, 1]
+
+let score = mj.INITIAL_PATTERN_SCORE;              // { elo: 1200, alpha: 1, beta: 1, mean: 0.5, ... }
+score = mj.updatePatternScore(score, reward, { ts: eventTs });
+```
+
+Two complementary estimators per pattern:
+
+- **Elo** (`k=32`, baseline 1200): `elo' = elo + K·(reward − expected)` — fast-moving,
+  ordinal, used to **rank** patterns in recall. Fresh pattern + reward 1 → 1216.
+- **Decayed Bayesian (Beta)**: evidence decays multiplicatively toward the uniform
+  prior (1,1) — per-update (`decay=0.98`) and time-based (`halfLifeDays=90`, only when
+  `ts` is injected) — so `mean = α/(α+β)` tracks the **recent** success rate, used for
+  **promotion thresholds** (`candidate → validated → deprecated` in `patterns.md`).
+
+Pure function: never mutates input, never reads the clock.
+
+### 4. Governance guard
+
+```js
+const p = mj.proposePromotion({ patternId: 'chromadb batch ingestion', ts, reason: 'mean 0.82 / 12 events', evidence: [eventIds] });
+mj.appendPromotion(projectDir, p);        // persisted as PROPOSED, always
+// ... a human / Shield reviewer flips it to APPROVED with approvedBy elsewhere ...
+mj.assertPromotionApplicable(approved);   // the gate every apply path MUST call
+```
+
+Governed by **Shield** (`registry.yaml → memory.reward_signal.governed_by`): bounded
+self-modification, versioned (append-only ndjson) and reversible (a promotion record
+never rewrites history; a rollback is just another proposal).
+
+## Testing
+
+```
+npx jest tests/unit/memory-journal.test.js
+```
+
+32 tests: append/recall round-trip on a tmp dir, corrupt-line tolerance, recency decay
+with injected clock, portfolio scope, backend-seam delegation, exact Elo/Beta math,
+purity, and the anti-tamper governance guard.
+
+## Future wiring (done by the orchestrator, not this module)
+
+- **MCP tools** `memory.write` / `memory.recall` in `mcp-server/` — thin wrappers over
+  this ndjson contract so every MCP-capable CLI shares one memory (Pillar 5).
+- **CLI commands** `bmad-plus memory log|recall|promote` in `tools/cli/commands/memory.js`.
+- **Zecher consolidation**: pack-memory's archivist reads `journal.ndjson` during
+  session consolidation and proposes pattern promotions via `proposePromotion()`.