bmad-plus 0.18.0 → 0.20.0

package/tools/cli/lib/review.js

@@ -0,0 +1,634 @@
+/**
+ * Code review evidence: a sealed scope, findings anchored on quoted code, and a gate that
+ * derives the verdict from coverage — never from how many findings were written.
+ *
+ * The host agent reviews; this module only establishes what must be reviewed, where each
+ * finding really is, which checklists apply, and whether every selected file was accounted
+ * for. Written for BMAD+ after studying open-code-review (docs/research/open-code-review-2026-09-25)
+ * for ideas only. No model call, no network, no write outside the review folder.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { matchesAny } = require('./glob');
+const { redactFields } = require('./redact');
+const rules = require('./review-rules');
+
+const SCOPE_SCHEMA = 'bmad-plus/review-scope/1';
+const FINDINGS_SCHEMA = 'bmad-plus/review-findings/1';
+const COVERAGE_SCHEMA = 'bmad-plus/review-coverage/1';
+const DEFAULT_DIR = '_bmad-output/review';
+
+const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+const CATEGORIES = [
+  'correctness',
+  'security',
+  'data-loss',
+  'concurrency',
+  'performance',
+  'error-handling',
+  'compatibility',
+  'test-gap',
+  'maintainability',
+  'documentation',
+];
+const DISPOSITIONS = ['confirmed', 'refuted', 'unresolved'];
+const CONFIDENCE = ['high', 'medium', 'low'];
+const OUTCOMES = ['completed', 'failed', 'waived'];
+
+/** Files whose content must never reach a review packet, whatever an include pattern says. */
+const SECRET_PATTERNS = [
+  '**/.env',
+  '**/.env.*',
+  '**/*.pem',
+  '**/*.key',
+  '**/*.p12',
+  '**/*.pfx',
+  '**/id_rsa*',
+  '**/id_ed25519*',
+  '**/.credentials/**',
+  '**/credentials/**',
+  '**/secrets/**',
+  '**/*.keystore',
+  '**/.npmrc',
+  '**/.netrc',
+];
+const GENERATED_PATTERNS = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/coverage/**',
+  '**/vendor/**',
+  '**/*.min.js',
+  '**/*.min.css',
+  '**/*.map',
+  '**/package-lock.json',
+  '**/yarn.lock',
+  '**/pnpm-lock.yaml',
+  '**/Cargo.lock',
+  '**/go.sum',
+  '**/poetry.lock',
+];
+const UNIT_LIMITS = { files: 8, lines: 400 };
+
+/**
+ * How much reviewing a change deserves. A pass is a complete read of the scope; later
+ * passes look for what the earlier ones missed and stop early when a pass adds nothing.
+ */
+const EFFORTS = {
+  low: { passes: 1, refute: false },
+  medium: { passes: 2, refute: true },
+  high: { passes: 3, refute: true },
+};
+const CHURN = { plan: 150, split: 400 };
+
+/** The reviewing plan follows the effort chosen and the measured size of the change. */
+function reviewPlan(effort, lines, units) {
+  const { passes, refute } = EFFORTS[effort];
+  return {
+    effort,
+    passes,
+    refute,
+    planFirst: lines >= CHURN.plan,
+    parallelUnits: units > 1 && lines >= CHURN.split,
+  };
+}
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+function git(projectDir, args) {
+  const result = spawnSync('git', args, {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+    shell: false,
+  });
+  if (result.error) throw new Error(`git is unavailable: ${result.error.message}`);
+  if (result.status !== 0)
+    throw new Error(`git ${args[0]} failed: ${(result.stderr || '').trim().split('\n')[0]}`);
+  return result.stdout;
+}
+
+/** A ref given on the command line is resolved to a commit or refused; it never reaches git as an option. */
+function resolveCommit(projectDir, ref) {
+  if (typeof ref !== 'string' || !ref || ref.startsWith('-'))
+    throw new Error(`invalid ref "${ref}"`);
+  return git(projectDir, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+}
+
+/** `git diff --numstat -z` entries: {path, oldPath?, added, removed, binary}. */
+function parseNumstat(output) {
+  const parts = output.split('\0');
+  const entries = [];
+  for (let i = 0; i < parts.length; i++) {
+    const head = parts[i];
+    if (!head) continue;
+    const match = /^(-|\d+)\t(-|\d+)\t(.*)$/.exec(head);
+    if (!match) continue;
+    const [, added, removed, rest] = match;
+    const binary = added === '-' || removed === '-';
+    if (rest === '') {
+      // Rename or copy: old path and new path follow as separate fields.
+      const oldPath = parts[++i];
+      const newPath = parts[++i];
+      entries.push({ path: newPath, oldPath, added: +added || 0, removed: +removed || 0, binary });
+    } else {
+      entries.push({ path: rest, added: +added || 0, removed: +removed || 0, binary });
+    }
+  }
+  return entries;
+}
+
+function nameStatus(output) {
+  const parts = output.split('\0');
+  const status = new Map();
+  for (let i = 0; i < parts.length; i++) {
+    const code = parts[i];
+    if (!code) continue;
+    const kind = code[0];
+    if (kind === 'R' || kind === 'C') {
+      i += 2;
+      status.set(parts[i], kind === 'R' ? 'renamed' : 'copied');
+    } else {
+      i += 1;
+      status.set(
+        parts[i],
+        { A: 'added', D: 'deleted', M: 'modified', T: 'modified' }[kind] || 'modified'
+      );
+    }
+  }
+  return status;
+}
+
+/** Deterministic review units: files grouped by directory, cut at the file and line limits, in path order. */
+function planUnits(selected, limits = UNIT_LIMITS) {
+  const units = [];
+  let current = null;
+  const flush = () => {
+    if (current && current.paths.length) units.push(current);
+    current = null;
+  };
+  for (const item of selected) {
+    const dir = path.posix.dirname(item.path);
+    const lines = item.added + item.removed;
+    if (
+      !current ||
+      current.dir !== dir ||
+      current.paths.length >= limits.files ||
+      (current.lines + lines > limits.lines && current.paths.length > 0)
+    ) {
+      flush();
+      current = { dir, paths: [], lines: 0 };
+    }
+    current.paths.push(item.path);
+    current.lines += lines;
+  }
+  flush();
+  return units.map((unit, index) => ({
+    id: `u${index + 1}`,
+    paths: unit.paths,
+    lines: unit.lines,
+  }));
+}
+
+/**
+ * The review scope: what changed between base and head (or the working tree), which files
+ * are selected, and why every other changed file is not. Secrets are excluded before any
+ * include pattern is considered.
+ */
+function buildScope(projectDir, options = {}) {
+  const head = options.workspace ? null : resolveCommit(projectDir, options.head || 'HEAD');
+  const base = resolveCommit(projectDir, options.base || 'HEAD~1');
+  const mergeBase = git(projectDir, ['merge-base', base, head || 'HEAD']).trim();
+  const range = options.workspace ? [mergeBase] : [mergeBase, head];
+  const numstat = parseNumstat(
+    git(projectDir, ['diff', '--numstat', '-z', '--find-renames', ...range, '--'])
+  );
+  const statuses = nameStatus(
+    git(projectDir, ['diff', '--name-status', '-z', '--find-renames', ...range, '--'])
+  );
+  const changed = numstat.map((entry) => ({
+    ...entry,
+    status: statuses.get(entry.path) || 'modified',
+  }));
+  if (options.workspace) {
+    const untracked = git(projectDir, ['ls-files', '--others', '--exclude-standard', '-z'])
+      .split('\0')
+      .filter(Boolean);
+    for (const file of untracked) {
+      if (changed.some((entry) => entry.path === file)) continue;
+      let lines = 0;
+      let binary;
+      try {
+        const bytes = fs.readFileSync(path.join(projectDir, file));
+        binary = bytes.includes(0);
+        lines = binary ? 0 : bytes.toString('utf8').split('\n').length;
+      } catch {
+        binary = true;
+      }
+      changed.push({ path: file, added: lines, removed: 0, binary, status: 'added' });
+    }
+  }
+  changed.sort((a, b) => a.path.localeCompare(b.path));
+
+  const include = options.include || [];
+  const exclude = options.exclude || [];
+  const selected = [];
+  const excluded = [];
+  for (const entry of changed) {
+    const file = entry.path;
+    let reason = null;
+    if (matchesAny(file, SECRET_PATTERNS)) reason = 'secret';
+    else if (entry.binary) reason = 'binary';
+    else if (entry.status === 'deleted') reason = 'deleted';
+    else if (matchesAny(file, exclude)) reason = 'excluded-by-pattern';
+    else if (matchesAny(file, GENERATED_PATTERNS) && !matchesAny(file, include))
+      reason = 'generated-or-vendored';
+    else if (include.length && !matchesAny(file, include)) reason = 'not-included';
+    if (reason) excluded.push({ path: file, reason, status: entry.status });
+    else
+      selected.push({
+        path: file,
+        status: entry.status,
+        added: entry.added,
+        removed: entry.removed,
+        ...(entry.oldPath ? { oldPath: entry.oldPath } : {}),
+      });
+  }
+  const effort = options.effort || 'medium';
+  if (!EFFORTS[effort]) throw new Error(`effort must be one of ${Object.keys(EFFORTS).join('|')}`);
+  const ruleset = options.ruleset || rules.loadRuleset(projectDir);
+  for (const item of selected) item.rules = rules.rulesFor(ruleset, item.path);
+  const identity = {
+    base,
+    head: head || 'WORKTREE',
+    mergeBase,
+    workspace: Boolean(options.workspace),
+    include,
+    exclude,
+    effort,
+    rulesSha256: ruleset.sha256,
+  };
+  const units = planUnits(selected, options.unitLimits).map((unit) => ({
+    ...unit,
+    rules: [...new Set(unit.paths.flatMap((p) => selected.find((s) => s.path === p).rules))],
+  }));
+  const lines = selected.reduce((n, item) => n + item.added + item.removed, 0);
+  const plan = reviewPlan(effort, lines, units.length);
+  const body = { identity, selected, excluded, units, plan };
+  return {
+    schema: SCOPE_SCHEMA,
+    id: options.id,
+    ...body,
+    totals: {
+      changed: changed.length,
+      selected: selected.length,
+      excluded: excluded.length,
+      lines,
+    },
+    sha256: sha256(JSON.stringify(body)),
+  };
+}
+
+// ── Findings ──────────────────────────────────────────────────────────────────
+
+const FINDING_KEYS = [
+  'id',
+  'path',
+  'existing_code',
+  'content',
+  'category',
+  'severity',
+  'confidence',
+  'disposition',
+  'trigger',
+  'consequence',
+  'evidence',
+  'refutation',
+  'fix',
+  'rule',
+];
+
+/** Unknown values are errors, never coerced: a wrong enum is a wrong finding. */
+function validateFindings(doc, scope) {
+  const errors = [];
+  if (!doc || doc.schema !== FINDINGS_SCHEMA) errors.push(`schema must be "${FINDINGS_SCHEMA}"`);
+  if (scope && doc && doc.scopeSha256 !== scope.sha256)
+    errors.push(
+      'scopeSha256 does not match the current scope — the findings answer another review'
+    );
+  const ids = new Set();
+  for (const [index, finding] of ((doc && doc.findings) || []).entries()) {
+    const at = `finding ${finding?.id ?? index}`;
+    for (const key of Object.keys(finding || {}))
+      if (!FINDING_KEYS.includes(key)) errors.push(`${at}: unknown key "${key}"`);
+    if (!finding.id || ids.has(finding.id)) errors.push(`${at}: id missing or duplicated`);
+    ids.add(finding.id);
+    if (typeof finding.path !== 'string' || !finding.path) errors.push(`${at}: path is required`);
+    if (typeof finding.existing_code !== 'string' || !finding.existing_code.trim())
+      errors.push(
+        `${at}: existing_code is required — quote the code the finding is about, verbatim`
+      );
+    if (typeof finding.content !== 'string' || !finding.content.trim())
+      errors.push(`${at}: content is required`);
+    if (!CATEGORIES.includes(finding.category))
+      errors.push(`${at}: category "${finding.category}" is not one of ${CATEGORIES.join('|')}`);
+    if (!SEVERITIES.includes(finding.severity))
+      errors.push(`${at}: severity "${finding.severity}" is not one of ${SEVERITIES.join('|')}`);
+    if (!CONFIDENCE.includes(finding.confidence))
+      errors.push(
+        `${at}: confidence "${finding.confidence}" is not one of ${CONFIDENCE.join('|')}`
+      );
+    if (!DISPOSITIONS.includes(finding.disposition))
+      errors.push(
+        `${at}: disposition "${finding.disposition}" is not one of ${DISPOSITIONS.join('|')}`
+      );
+    if (finding.disposition === 'refuted' && !String(finding.refutation || '').trim())
+      errors.push(`${at}: a refuted finding keeps its refutation — the quoted ground`);
+    if (finding.disposition === 'confirmed' && !String(finding.evidence || '').trim())
+      errors.push(`${at}: a confirmed finding needs evidence`);
+    const entry = scope && scope.selected.find((item) => item.path === finding.path);
+    if (scope && finding.path && !entry)
+      errors.push(`${at}: ${finding.path} is not in the review scope`);
+    // A finding may name the checklist rule that led to it; the rule must apply to that file.
+    if (finding.rule !== undefined && entry && !(entry.rules || []).includes(finding.rule))
+      errors.push(`${at}: rule "${finding.rule}" does not apply to ${finding.path}`);
+  }
+  return errors;
+}
+
+const normalizeLine = (line) => line.replace(/\r$/, '').replace(/\s+/g, ' ').trim();
+
+/**
+ * Where a quoted snippet is in a file: every place its lines appear consecutively, compared
+ * after whitespace normalisation. The model's line numbers are never used.
+ */
+function locate(fileText, snippet) {
+  const fileLines = fileText.split('\n').map(normalizeLine);
+  const wanted = snippet
+    .split('\n')
+    .map(normalizeLine)
+    .filter((line, index, all) => line || (index > 0 && index < all.length - 1));
+  while (wanted.length && !wanted[0]) wanted.shift();
+  while (wanted.length && !wanted[wanted.length - 1]) wanted.pop();
+  if (!wanted.length) return [];
+  const hits = [];
+  for (let i = 0; i + wanted.length <= fileLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < wanted.length; j++) {
+      if (fileLines[i + j] !== wanted[j]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) hits.push({ lineStart: i + 1, lineEnd: i + wanted.length });
+  }
+  return hits;
+}
+
+function readAtHead(projectDir, scope, file) {
+  if (scope.identity.workspace) return fs.readFileSync(path.join(projectDir, file), 'utf8');
+  return git(projectDir, ['show', `${scope.identity.head}:${file}`]);
+}
+
+/** Every finding gets a location status: located (unique), ambiguous (several), unlocated (none). */
+function anchorFindings(projectDir, scope, doc) {
+  const cache = new Map();
+  const anchored = doc.findings.map((finding) => {
+    let text = cache.get(finding.path);
+    if (text === undefined) {
+      try {
+        text = readAtHead(projectDir, scope, finding.path);
+      } catch {
+        text = null;
+      }
+      cache.set(finding.path, text);
+    }
+    if (text === null)
+      return { ...finding, location: { status: 'unlocated', reason: 'file unreadable at head' } };
+    const hits = locate(text, finding.existing_code);
+    if (hits.length === 1) return { ...finding, location: { status: 'located', ...hits[0] } };
+    if (hits.length > 1)
+      return { ...finding, location: { status: 'ambiguous', candidates: hits.slice(0, 10) } };
+    return {
+      ...finding,
+      location: { status: 'unlocated', reason: 'the quoted code is not in the file' },
+    };
+  });
+  const counts = { located: 0, ambiguous: 0, unlocated: 0, redactions: 0 };
+  for (const finding of anchored) {
+    counts[finding.location.status] += 1;
+    // Located first, redacted second: the anchor needs the quote, the written record must not carry a secret.
+    const redacted = redactFields(finding, REDACTED_FIELDS);
+    if (redacted) finding.redactions = redacted;
+    counts.redactions += redacted;
+  }
+  return { findings: anchored, counts };
+}
+
+const REDACTED_FIELDS = [
+  'existing_code',
+  'content',
+  'trigger',
+  'consequence',
+  'evidence',
+  'refutation',
+  'fix',
+];
+
+// ── Coverage and gate ─────────────────────────────────────────────────────────
+
+function validateCoverage(doc, scope) {
+  const errors = [];
+  if (!doc || doc.schema !== COVERAGE_SCHEMA) errors.push(`schema must be "${COVERAGE_SCHEMA}"`);
+  if (doc && doc.scopeSha256 !== scope.sha256)
+    errors.push('scopeSha256 does not match the current scope');
+  const seen = new Set();
+  for (const item of (doc && doc.items) || []) {
+    if (!scope.selected.some((entry) => entry.path === item.path))
+      errors.push(`${item.path}: not in the review scope`);
+    if (seen.has(item.path)) errors.push(`${item.path}: listed twice`);
+    seen.add(item.path);
+    if (!OUTCOMES.includes(item.outcome))
+      errors.push(`${item.path}: outcome "${item.outcome}" is not one of ${OUTCOMES.join('|')}`);
+    if (
+      (item.outcome === 'waived' || item.outcome === 'failed') &&
+      !String(item.reason || '').trim()
+    )
+      errors.push(`${item.path}: a ${item.outcome} file needs a reason`);
+  }
+  return errors;
+}
+
+/**
+ * The review verdict. `incomplete` whenever a selected file was not accounted for, failed,
+ * or the evidence is invalid; otherwise `findings` or `clean` — the latter only means no
+ * confirmed or unresolved finding within a fully covered scope.
+ */
+function reviewGate({ scope, findings, coverage, anchored }) {
+  const reasons = [];
+  if (!coverage) reasons.push('no coverage.json: which files were reviewed is not established');
+  else reasons.push(...validateCoverage(coverage, scope));
+  if (!findings) reasons.push('no findings.json: write it even when there is nothing to report');
+  else reasons.push(...validateFindings(findings, scope));
+  const covered = new Map(((coverage && coverage.items) || []).map((item) => [item.path, item]));
+  const missing = scope.selected.filter((item) => !covered.has(item.path)).map((item) => item.path);
+  const failed = [...covered.values()]
+    .filter((item) => item.outcome === 'failed')
+    .map((item) => item.path);
+  const waived = [...covered.values()]
+    .filter((item) => item.outcome === 'waived')
+    .map((item) => item.path);
+  if (missing.length)
+    reasons.push(
+      `${missing.length} selected file(s) never accounted for: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? '…' : ''}`
+    );
+  if (failed.length)
+    reasons.push(`${failed.length} file(s) whose review failed: ${failed.slice(0, 5).join(', ')}`);
+  const open = ((anchored && anchored.findings) || []).filter((f) => f.disposition !== 'refuted');
+  const unlocated = open.filter((f) => f.location.status !== 'located');
+  if (unlocated.length)
+    reasons.push(
+      `${unlocated.length} open finding(s) not anchored on the code at head: ${unlocated
+        .map((f) => f.id)
+        .slice(0, 5)
+        .join(', ')}`
+    );
+  const total = scope.selected.length;
+  const done = [...covered.values()].filter((item) => item.outcome === 'completed').length;
+  const coverageRate = total ? Math.round((done / total) * 1000) / 10 : 100;
+  const status = reasons.length ? 'incomplete' : open.length ? 'findings' : 'clean';
+  return {
+    status,
+    reasons,
+    coverage: {
+      selected: total,
+      completed: done,
+      waived: waived.length,
+      failed: failed.length,
+      missing: missing.length,
+      rate: coverageRate,
+    },
+    findings: {
+      open: open.length,
+      confirmed: open.filter((f) => f.disposition === 'confirmed').length,
+      unresolved: open.filter((f) => f.disposition === 'unresolved').length,
+      refuted: ((anchored && anchored.findings) || []).length - open.length,
+      bySeverity: Object.fromEntries(
+        SEVERITIES.map((s) => [s, open.filter((f) => f.severity === s).length])
+      ),
+    },
+  };
+}
+
+// ── Comparing two reviews ─────────────────────────────────────────────────────
+
+const COMPARE_SCHEMA = 'bmad-plus/review-compare/1';
+
+/** A finding's identity survives moved lines and reindentation: path, category, normalised quote. */
+function findingKey(file, finding) {
+  const code = String(finding.existing_code || '')
+    .split('\n')
+    .map(normalizeLine)
+    .filter(Boolean)
+    .join('\n');
+  return JSON.stringify([file, finding.category, code]);
+}
+
+/**
+ * What became of the open findings of an earlier review. `resolved` needs the later review
+ * to have completed that file; otherwise the finding is `not_reviewed`, never assumed fixed.
+ * Renames recorded in the later scope carry findings to the new path.
+ */
+function compareReviews(before, after) {
+  const renamed = new Map(
+    after.scope.selected.filter((item) => item.oldPath).map((item) => [item.oldPath, item.path])
+  );
+  const completed = new Set(
+    ((after.coverage && after.coverage.items) || [])
+      .filter((item) => item.outcome === 'completed')
+      .map((item) => item.path)
+  );
+  const isOpen = (finding) => finding.disposition !== 'refuted';
+  const afterByKey = new Map(after.findings.findings.map((f) => [findingKey(f.path, f), f]));
+  const beforeKeys = new Set();
+  const buckets = { new: [], persisting: [], resolved: [], refuted: [], not_reviewed: [] };
+
+  for (const finding of before.findings.findings.filter(isOpen)) {
+    const file = renamed.get(finding.path) || finding.path;
+    const key = findingKey(file, finding);
+    beforeKeys.add(key);
+    const match = afterByKey.get(key);
+    const entry = {
+      before: finding.id,
+      path: file,
+      category: finding.category,
+      severity: finding.severity,
+    };
+    if (match && isOpen(match)) buckets.persisting.push({ ...entry, after: match.id });
+    else if (match) buckets.refuted.push({ ...entry, after: match.id });
+    else if (completed.has(file)) buckets.resolved.push(entry);
+    else buckets.not_reviewed.push(entry);
+  }
+  for (const finding of after.findings.findings.filter(isOpen)) {
+    if (!beforeKeys.has(findingKey(finding.path, finding)))
+      buckets.new.push({
+        after: finding.id,
+        path: finding.path,
+        category: finding.category,
+        severity: finding.severity,
+      });
+  }
+  return {
+    schema: COMPARE_SCHEMA,
+    before: { id: before.scope.id, scopeSha256: before.scope.sha256 },
+    after: { id: after.scope.id, scopeSha256: after.scope.sha256 },
+    counts: Object.fromEntries(Object.entries(buckets).map(([name, list]) => [name, list.length])),
+    buckets,
+  };
+}
+
+function layout(projectDir, dir = DEFAULT_DIR, id) {
+  const root = path.resolve(projectDir, dir, id);
+  return {
+    root,
+    scope: path.join(root, 'scope.json'),
+    findings: path.join(root, 'findings.json'),
+    anchored: path.join(root, 'findings.anchored.json'),
+    coverage: path.join(root, 'coverage.json'),
+    checklist: path.join(root, 'checklist.md'),
+    compare: path.join(root, 'compare.json'),
+  };
+}
+
+module.exports = {
+  SCOPE_SCHEMA,
+  FINDINGS_SCHEMA,
+  COVERAGE_SCHEMA,
+  COMPARE_SCHEMA,
+  DEFAULT_DIR,
+  EFFORTS,
+  SEVERITIES,
+  CATEGORIES,
+  DISPOSITIONS,
+  CONFIDENCE,
+  OUTCOMES,
+  SECRET_PATTERNS,
+  GENERATED_PATTERNS,
+  parseNumstat,
+  planUnits,
+  buildScope,
+  validateFindings,
+  locate,
+  anchorFindings,
+  validateCoverage,
+  reviewGate,
+  reviewPlan,
+  findingKey,
+  compareReviews,
+  layout,
+};

package/tools/cli/lib/uat.js

@@ -4,6 +4,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { redactFields } = require('./redact');
 
 const SPEC_SCHEMA = 'bmad-plus/uat-spec/2';
 const RESULTS_SCHEMA = 'bmad-plus/uat-results/2';
@@ -90,7 +91,7 @@ function readJson(file) {
   const stat = fs.lstatSync(file);
   if (stat.isSymbolicLink()) throw new Error(`${file} is a symbolic link; refused.`);
   if (stat.size > MAX_FILE) throw new Error(`${file} exceeds ${MAX_FILE} bytes.`);
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); // PowerShell 5.1 writes a BOM
 }
 
 // ── Spec: legacy adapter, validation, lint ────────────────────────────────────
@@ -714,6 +715,20 @@ function normalizeRun(doc, spec) {
   return run;
 }
 
+/**
+ * Tester notes are free text, and testers paste terminal output into them: credentials go
+ * before the run is written. Returns the number of replacements, recorded on the run.
+ */
+function redactRun(run) {
+  let count = redactFields(run, ['overallNote']);
+  for (const step of Object.values(run.steps || {})) {
+    count += redactFields(step, ['note']);
+    for (const expect of Object.values(step.expect || {})) count += redactFields(expect, ['note']);
+  }
+  if (count) run.redactions = (run.redactions || 0) + count;
+  return count;
+}
+
 function readRuns(dir, spec) {
   const runs = [];
   const seen = new Set();
@@ -1013,6 +1028,7 @@ module.exports = {
   pageGuarantees,
   languageCode,
   normalizeRun,
+  redactRun,
   readRuns,
   stepState,
   failures,

package/tools/cli/review-rules/ci-workflows.md

@@ -0,0 +1,7 @@
+- **Untrusted triggers.** `pull_request_target`, `workflow_run` or `issue_comment` jobs that check out or execute code from a pull request with secrets or a write token available.
+- **Script injection.** Expressions such as `${{ github.event.* }}`, branch names, titles or commit messages interpolated directly into `run:`; pass them through `env:` and quote them.
+- **Permissions.** No top-level `permissions:` (defaults may be broad), or `write` scopes a job does not need; `id-token: write` on jobs that do not publish.
+- **Pinning.** Third-party actions referenced by a moving tag or branch instead of a full commit SHA; container images without a digest.
+- **Secrets.** Secrets echoed, written to artifacts or caches, or exposed to steps that run third-party code; `ACTIONS_STEP_DEBUG` left on.
+- **Runners.** Self-hosted runners on public repositories; a job that assumes a tool preinstalled on GitHub-hosted images (`node`, `python`, `jq`) before setting it up.
+- **Gates.** A step that should block marked `continue-on-error`; a required check that can be skipped by a path filter; a release job that does not depend on the test jobs.

package/tools/cli/review-rules/configuration.md

@@ -0,0 +1,5 @@
+- **Secrets.** A real credential, token, private URL or personal data committed in a configuration file or an example file; an example file whose placeholder looks real.
+- **Dependencies.** A new dependency: is it maintained, necessary, and from the expected publisher (typosquatting)? A version range widened to accept a major; a lockfile out of step with its manifest; install scripts from a new package.
+- **Defaults.** A security-relevant setting weakened (TLS verification, CORS origins, cookie flags, debug mode, log level exposing data) or a default that now differs between environments.
+- **Consistency.** A key renamed in one environment file and not the others; a value duplicated where one source of truth exists; a feature flag left on.
+- **Parsing.** YAML values that change type silently (`no`, `on`, `0755`, unquoted dates and versions); JSON with duplicate keys.