bmad-plus 0.13.0 → 0.16.0

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);
+    }
+  },
+};

package/tools/cli/commands/studio.js

@@ -0,0 +1,68 @@
+/** Inspect installed Dev Studio routes and prepare actual host instructions. */
+const path = require('node:path');
+const { installedPack, validatePack, prepare } = require('../lib/studio');
+
+module.exports = {
+  command: 'studio <action> [workflow]',
+  description: 'List Dev Studio workflows or prepare read-only execution context',
+  options: [
+    ['-d, --directory <path>', 'Installed project directory'],
+    ['--request <text>', 'Task scope for the host assistant'],
+    [
+      '--input <file>',
+      'Project-relative input file (repeatable)',
+      (file, files) => [...files, file],
+      [],
+    ],
+    ['--json', 'Print machine-readable context and evidence'],
+  ],
+  action: (action, workflow, options = {}) => {
+    try {
+      const projectDir = path.resolve(options.directory || process.cwd());
+      let result;
+      if (action === 'list' && !workflow) {
+        const { catalog, resources } = validatePack(installedPack(projectDir));
+        result = {
+          schemaVersion: 1,
+          execution: 'host-managed',
+          ...catalog,
+          validatedResources: resources.length,
+        };
+      } else if (action === 'prepare' && workflow) {
+        result = prepare({ projectDir, workflow, request: options.request, inputs: options.input });
+      } else throw new Error('Use studio list or studio prepare WORKFLOW.');
+      process.exitCode = result.status === 'needs-input' ? 2 : 0;
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else if (action === 'list')
+        console.log(
+          result.workflows.map((w) => `${w.id} (${w.agent}; input: ${w.input})`).join('\n')
+        );
+      else
+        console.log(
+          [
+            `${result.workflow}: ${result.status} — prepared for the host, not executed.`,
+            `Project: ${result.projectDir}`,
+            `Request: ${result.request || '(none supplied)'}`,
+            `Resolved configuration:\n${JSON.stringify(result.config.values, null, 2)}`,
+            `Defaulted fields: ${result.config.defaultsUsed.join(', ') || '(none)'}`,
+            `Proposed report: ${result.outputPath}`,
+            ...result.missingInputs,
+            ...result.instructions.map(
+              (item) => `\n--- ${item.path} (${item.sha256}) ---\n${item.content}`
+            ),
+            ...result.inputs.map(
+              (item) => `\n--- Project input: ${item.path} (${item.sha256}) ---\n${item.content}`
+            ),
+            result.previousReport
+              ? `\n--- Continue existing report ---\n${result.previousReport.content}`
+              : '',
+          ].join('\n')
+        );
+    } catch (error) {
+      process.exitCode = 1;
+      if (options.json)
+        console.log(JSON.stringify({ schemaVersion: 1, status: 'error', error: error.message }));
+      else console.error('Dev Studio: ' + error.message);
+    }
+  },
+};

package/tools/cli/commands/uat.js

@@ -0,0 +1,389 @@
+/** Build, serve and read human acceptance recipes (recette); the gate stays evidence-bound. */
+'use strict';
+
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const { URL } = require('node:url');
+const yaml = require('js-yaml');
+const uat = require('../lib/uat');
+
+const MAX_BODY = 4 * 1024 * 1024;
+const RUN_ID = /^[0-9a-z][0-9a-z-]{0,63}$/;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function resolveSpec(target, paths) {
+  if (!target) fail('an id or a spec file is required');
+  const file = target.endsWith('.json')
+    ? path.resolve(target)
+    : path.join(paths.specs, `${target}.json`);
+  if (!fs.existsSync(file)) fail(`no spec at ${file}`);
+  return uat.loadSpec(file);
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    fail('nothing on standard input');
+    return '';
+  }
+}
+
+function print(json, payload, lines) {
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
+  else for (const line of lines) console.log(line);
+}
+
+function runsFor(spec, paths) {
+  const dir = path.join(paths.results, spec.id);
+  return uat.readRuns(fs.existsSync(dir) ? dir : paths.results, spec);
+}
+
+function triageFile(spec, paths) {
+  return path.join(paths.triage, `${spec.id}.json`);
+}
+
+/** The project's communication language, so a tester reads the page in their own. */
+function projectLanguage(projectDir) {
+  try {
+    const config = yaml.load(
+      fs.readFileSync(path.join(projectDir, '_bmad', 'config.yaml'), 'utf8')
+    );
+    return (config && config.communication_language) || null;
+  } catch {
+    return null;
+  }
+}
+
+function serve(spec, paths, options) {
+  const page = path.join(paths.pages, `uat-${spec.id}.html`);
+  if (!fs.existsSync(page)) fail(`no page at ${page} — run "bmad-plus uat build ${spec.id}" first`);
+  const html = fs.readFileSync(page);
+  const resultsDir = path.join(paths.results, spec.id);
+  fs.mkdirSync(resultsDir, { recursive: true });
+  const port = Number.parseInt(options.port || '4173', 10);
+
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url, 'http://127.0.0.1');
+    const send = (code, body, type = 'application/json') => {
+      response.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' });
+      response.end(body);
+    };
+    if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '/index.html')) {
+      return send(200, html, 'text/html; charset=utf-8');
+    }
+    if (request.method === 'GET' && url.pathname === '/__uat/ping') {
+      return send(
+        200,
+        JSON.stringify({ uat: true, specId: spec.id, specSha256: uat.specHash(spec) })
+      );
+    }
+    if (request.method === 'PUT' && url.pathname.startsWith('/__uat/results/')) {
+      const runId = url.pathname.slice('/__uat/results/'.length);
+      if (!RUN_ID.test(runId)) return send(400, JSON.stringify({ error: 'invalid runId' }));
+      let size = 0;
+      const chunks = [];
+      request.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_BODY) {
+          request.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      request.on('end', () => {
+        try {
+          const run = uat.normalizeRun(JSON.parse(Buffer.concat(chunks).toString('utf8')), spec);
+          if (run.runId !== runId || run.specId !== spec.id)
+            fail('run identity does not match the request');
+          fs.writeFileSync(path.join(resultsDir, `${runId}.json`), JSON.stringify(run, null, 2));
+          const s = run.summary;
+          console.log(
+            `${new Date().toISOString().slice(11, 19)}  ${runId} — ${s.passed} passed, ${s.failed} failed, ${s.blocked} blocked, ${s.unanswered} to do${run.finishedAt ? ' — finished' : ''}`
+          );
+          send(200, JSON.stringify({ stored: runId }));
+        } catch (error) {
+          send(400, JSON.stringify({ error: error.message }));
+        }
+      });
+      return undefined;
+    }
+    return send(404, JSON.stringify({ error: 'not found' }));
+  });
+
+  // Loopback only: a tester on another machine uses the artifact or the file (decision D5).
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`uat serve: http://127.0.0.1:${port}  (${spec.id}, ${spec.steps.length} steps)`);
+    console.log(`results → ${resultsDir}`);
+    console.log('Ctrl+C to stop.');
+  });
+  return server;
+}
+
+module.exports = {
+  command: 'uat <action> [target]',
+  aliases: ['recette'],
+  description: 'Human acceptance recipes: lint, build, serve, import, read, gate, order',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--dir <path>', 'Recipe folder inside the project', uat.DEFAULT_DIR],
+    [
+      '--src <path>',
+      'Source folder checked for on-screen labels (repeatable)',
+      (value, all) => [...all, value],
+      [],
+    ],
+    ['--language <code>', 'Page language (code or name); defaults to the project language'],
+    ['--input <file>', 'Results file to import ("-" reads standard input)'],
+    ['--port <number>', 'Port for serve (loopback only)'],
+    ['--emit-check', 'Write the self-contained Nexus verifier next to the recipe'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, target, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const paths = uat.layout(projectDir, options.dir || uat.DEFAULT_DIR);
+    const json = Boolean(options.json);
+    try {
+      if (action === 'lint') {
+        const { spec, legacy } = resolveSpec(target, paths);
+        const report = uat.lintSpec(spec, { sources: options.src });
+        print(json, { action, specId: spec.id, legacy, ...report }, [
+          `${spec.id}: ${spec.steps.length} steps, ${spec.steps.reduce((n, s) => n + s.expect.length, 0)} expectations, ${report.labels} on-screen labels${report.scannedFiles ? ` checked against ${report.scannedFiles} source files` : ''}`,
+          ...report.errors.map((line) => `  error   ${line}`),
+          ...report.warnings.map((line) => `  warning ${line}`),
+          report.errors.length ? '' : '  no error',
+        ]);
+        process.exitCode = report.errors.length ? 1 : 0;
+        return;
+      }
+
+      if (action === 'build') {
+        const { spec } = resolveSpec(target, paths);
+        const report = uat.lintSpec(spec, { sources: options.src });
+        if (report.errors.length) {
+          print(json, { action, specId: spec.id, status: 'error', errors: report.errors }, [
+            `${spec.id}: not built, ${report.errors.length} error(s)`,
+            ...report.errors.map((line) => `  error   ${line}`),
+          ]);
+          process.exitCode = 1;
+          return;
+        }
+        const page = uat.buildPage(spec, {
+          language: options.language || projectLanguage(projectDir),
+        });
+        fs.mkdirSync(paths.pages, { recursive: true });
+        const file = path.join(paths.pages, `uat-${spec.id}.html`);
+        fs.writeFileSync(file, page.html, 'utf8');
+        print(
+          json,
+          {
+            action,
+            specId: spec.id,
+            file,
+            specSha256: page.sha256,
+            language: page.language,
+            languages: Object.keys(uat.STRINGS),
+            warnings: report.warnings,
+          },
+          [
+            `${file} — ${spec.steps.length} steps, ${(page.html.length / 1024).toFixed(0)} KiB, spec ${page.sha256.slice(0, 12)}`,
+            `opens in ${uat.STRINGS[page.language].name}; the tester can switch to any of the ${Object.keys(uat.STRINGS).length} languages on the page`,
+            ...report.warnings.map((line) => `  warning ${line}`),
+          ]
+        );
+        return;
+      }
+
+      if (action === 'serve') {
+        const { spec } = resolveSpec(target, paths);
+        serve(spec, paths, options);
+        return;
+      }
+
+      if (action === 'import') {
+        const { spec } = resolveSpec(target, paths);
+        if (!options.input) fail('--input <file> or --input - is required');
+        const fromStdin = options.input === '-';
+        const source = fromStdin
+          ? readStdin()
+          : fs.readFileSync(path.resolve(options.input), 'utf8');
+        const document = JSON.parse(source);
+        // The first artifact exports carried neither runId nor specId; the file name holds the run.
+        if (!document.runId && !fromStdin) {
+          const marked = /(\d{8}-[0-9a-z-]+)$/.exec(path.basename(options.input, '.json'));
+          if (marked) document.runId = marked[1];
+        }
+        if (!document.specId) document.specId = spec.id;
+        const run = uat.normalizeRun(document, spec);
+        if (run.specId !== spec.id) fail(`these results answer ${run.specId}, not ${spec.id}`);
+        const dir = path.join(paths.results, spec.id);
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${run.runId}.json`);
+        fs.writeFileSync(file, JSON.stringify(run, null, 2));
+        print(json, { action, specId: spec.id, runId: run.runId, file, summary: run.summary }, [
+          `${file} — ${run.summary.passed} passed, ${run.summary.failed} failed, ${run.summary.blocked} blocked, ${run.summary.unanswered} to do`,
+        ]);
+        return;
+      }
+
+      if (action === 'read') {
+        const { spec } = resolveSpec(target, paths);
+        const runs = runsFor(spec, paths);
+        if (!runs.length) {
+          print(json, { action, specId: spec.id, status: 'awaiting', runs: [] }, [
+            `${spec.id}: no run yet`,
+          ]);
+          process.exitCode = 2;
+          return;
+        }
+        const payload = runs.map((run) => ({
+          runId: run.runId,
+          tester: run.tester,
+          startedAt: run.startedAt,
+          finishedAt: run.finishedAt,
+          stale: run.stale,
+          unsigned: run.unsigned,
+          summary: run.summary,
+          failures: uat.failures(run, spec),
+          unanswered: uat.unanswered(run, spec),
+          overallNote: run.overallNote,
+          file: run.file,
+        }));
+        const lines = [];
+        for (const run of payload) {
+          const s = run.summary;
+          lines.push('');
+          lines.push(
+            `■ ${spec.product} ${spec.versions.join(' · ')} — ${run.tester} — ${String(run.startedAt).slice(0, 16).replace('T', ' ')}${run.finishedAt ? ', finished' : ', IN PROGRESS'}`
+          );
+          lines.push(
+            `  ${s.passed} passed · ${s.failed} failed · ${s.blocked} blocked · ${s.skipped} skipped · ${s.unanswered} to do   (${run.file})`
+          );
+          if (run.stale)
+            lines.push('  ⚠ answered another revision of the spec — replay the affected steps');
+          else if (run.unsigned)
+            lines.push('  ⚠ run without a spec fingerprint (page built before fingerprints)');
+          if (run.overallNote) lines.push(`  overall: ${run.overallNote}`);
+          for (const failure of run.failures) {
+            lines.push(
+              `  ✗ ${failure.step}/${failure.expect} (${failure.state}) — ${failure.title}`
+            );
+            if (failure.missingFromSpec)
+              lines.push('      expectation: ABSENT from the current spec');
+            else if (failure.text) lines.push(`      expectation: ${failure.text}`);
+            lines.push(
+              failure.note
+                ? `      seen instead: ${failure.note.replace(/\s+/g, ' ').trim()}`
+                : '      (no note — ask the tester what they saw)'
+            );
+          }
+          if (!run.failures.length) lines.push('  ✓ nothing failed');
+        }
+        print(json, { action, specId: spec.id, runs: payload }, lines);
+        process.exitCode = payload[0].stale
+          ? 3
+          : payload.some((run) => run.failures.length)
+            ? 1
+            : 0;
+        return;
+      }
+
+      if (action === 'gate') {
+        const { spec } = resolveSpec(target, paths);
+        const runs = runsFor(spec, paths);
+        const triage = uat.loadTriage(triageFile(spec, paths));
+        const verdict = uat.gate({ spec, runs, triage });
+        let check = null;
+        if (options.emitCheck) {
+          fs.mkdirSync(paths.checks, { recursive: true });
+          check = path.join(paths.checks, `gate-${spec.id}.cjs`);
+          fs.writeFileSync(
+            check,
+            uat.emitCheck({
+              specId: spec.id,
+              specSha256: uat.specHash(spec),
+              dir: options.dir || uat.DEFAULT_DIR,
+              writeSteps: spec.steps.filter((step) => step.writes).map((step) => step.id),
+            }),
+            'utf8'
+          );
+        }
+        print(
+          json,
+          {
+            action,
+            specId: spec.id,
+            status: verdict.status,
+            reasons: verdict.reasons,
+            runId: verdict.run?.runId || null,
+            check,
+          },
+          [
+            `${spec.id}: ${verdict.status}${verdict.run ? ` (run ${verdict.run.runId} by ${verdict.run.tester})` : ''}`,
+            ...verdict.reasons.map((reason) => `  - ${reason}`),
+            check ? `  verifier: ${check}` : '',
+            verdict.status === 'passed'
+              ? '  human-observed: complete, current and triaged. It does not establish that the tester looked at the right place.'
+              : '',
+          ].filter(Boolean)
+        );
+        process.exitCode = { passed: 0, failed: 1, awaiting: 2, stale: 3 }[verdict.status];
+        return;
+      }
+
+      if (action === 'order') {
+        const specs = (fs.existsSync(paths.specs) ? fs.readdirSync(paths.specs) : [])
+          .filter((name) => name.endsWith('.json'))
+          .map((name) => uat.loadSpec(path.join(paths.specs, name)).spec);
+        if (!specs.length) fail(`no spec in ${paths.specs}`);
+        const { order, collisions, cycles } = uat.playOrder(specs);
+        const body = [
+          '# Play order',
+          '',
+          'Generated by `bmad-plus uat order`. A witness written by one recipe and read by another',
+          'decides the order; a step meant "for later" belongs to its own page.',
+          '',
+          ...order.map((id, index) => `${index + 1}. \`${id}\``),
+          '',
+          ...(collisions.length
+            ? [
+                '## Shared witnesses',
+                '',
+                ...collisions.map(
+                  (c) =>
+                    `- \`${c.witness}\`: written by \`${c.writtenBy}\`, read by \`${c.readBy}\``
+                ),
+                '',
+              ]
+            : []),
+          ...(cycles.length
+            ? ['## Cycles — decide by hand', '', ...cycles.map((c) => `- ${c}`), '']
+            : []),
+        ].join('\n');
+        fs.mkdirSync(paths.root, { recursive: true });
+        const file = path.join(paths.root, 'ORDER.md');
+        fs.writeFileSync(file, body, 'utf8');
+        print(json, { action, order, collisions, cycles, file }, [
+          file,
+          ...order.map((id, index) => `${index + 1}. ${id}`),
+          ...cycles.map((c) => `cycle: ${c}`),
+        ]);
+        process.exitCode = cycles.length ? 1 : 0;
+        return;
+      }
+
+      fail(`unknown action "${action}" (lint, build, serve, import, read, gate, order)`);
+    } catch (error) {
+      if (json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', message: error.message }, null, 2)
+        );
+      else console.error(`uat: ${error.message}`);
+      process.exitCode = 1;
+    }
+  },
+};

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

@@ -1,9 +1,10 @@
 # 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`).
+Legacy manually supplied rewards can propose pattern promotion; they do not steer
+recall. The optional `memory-outcomes.js` layer derives a bounded recall boost from
+current accepted Nexus evidence. There is **no base-model fine-tuning**, and a
+retrieved memory is not evidence of improved downstream task quality.
 
 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
@@ -12,6 +13,8 @@ Builds **on top of** the existing `pack-memory` (Zecher, Karpathy guardrails G1
 ```
 .bmad/memory/journal.ndjson      ← structured event log (this module, north-star scope)
 .bmad/memory/promotions.ndjson   ← governance queue (always PROPOSED)
+.bmad/memory/outcomes.ndjson     ← immutable, provenance-backed accepted outcome receipts
+.bmad/memory/writer.lock         ← shared synchronous writer mutex
 .agents/memory/*.md              ← human memory (pack-memory, current layout) — READ ONLY here
 .bmad/memory/*.md                ← human memory (north-star layout) — READ ONLY here
 ```
@@ -20,9 +23,9 @@ Builds **on top of** the existing `pack-memory` (Zecher, Karpathy guardrails G1
 
 | 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). |
+| Injected event clock | `ts` is a **required, caller-injected** field; event/receipt IDs are content hashes. The storage mutex separately uses a random owner token; it does not affect event IDs. |
+| Node stdlib only | No network or additional service is required for project-local memory. Evidence inspection reads Nexus state and current filesystem identities. |
+| Serialized writes | Journal, scores, promotions and outcomes share the same project mutex. Legacy readers skip corrupt lines; new appends refuse an incomplete final line. Outcome parsing fails on corruption. |
 | 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
@@ -64,6 +67,14 @@ Sources merged: `journal.ndjson` events + `### `-sectioned entries from
 and `.agents/memory/` (current pack-memory layout), plus `<portfolioDir>/memory/*.md`
 when `scope: 'portfolio'`.
 
+For opt-in project-local evidence ranking, pass `ranking: 'evidence'` and
+`contextScope: ['src/component']`. Relevant notes with current accepted Nexus evidence
+receive at most a 25% boost; failed/unverified/duplicate observations cannot supply it.
+Stale, explicitly superseded or contradictory evidence is excluded, while unsupported
+notes remain labeled `unverified`. Alternative backends and portfolio scope are not
+part of evidence ranking. See the [outcome contract](../../../docs/specs/memory-outcomes.md)
+for observation input, freshness checks, limitations and recovery.
+
 **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`).
@@ -84,8 +95,8 @@ 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.
+- **Elo** (`k=32`, baseline 1200): `elo' = elo + K·(reward − expected)` — a legacy
+  descriptive score; it is not consumed by 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