bmad-plus 0.18.0 → 0.20.0

package/tools/cli/commands/review.js

@@ -0,0 +1,261 @@
+/** Code review evidence: seal the scope, anchor the findings, derive the verdict from coverage. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const review = require('../lib/review');
+const reviewRules = require('../lib/review-rules');
+
+const ID = /^[a-z0-9][a-z0-9.-]{0,80}$/;
+const ACTIONS = ['scope', 'anchor', 'gate', 'compare', 'rules'];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function readJson(file, what) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    // PowerShell 5.1 writes UTF-8 with a byte-order mark; JSON.parse refuses it.
+    return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+  } catch (error) {
+    fail(`${what} is not valid JSON (${error.message})`);
+    return null;
+  }
+}
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+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 requireId(value, what = 'a review id') {
+  if (!value || !ID.test(value))
+    fail(`${what} is required: lowercase letters, digits, dots and dashes`);
+  return value;
+}
+
+function loadReview(projectDir, dir, id) {
+  const paths = review.layout(projectDir, dir, id);
+  const scope = readJson(paths.scope, `${id}/scope.json`);
+  if (!scope) fail(`no scope at ${paths.scope} — run "bmad-plus review scope ${id}" first`);
+  return { paths, scope };
+}
+
+/** `review rules [path]`: the effective rule set, or the rules one path would get. */
+function rulesAction(projectDir, target, json) {
+  const ruleset = reviewRules.loadRuleset(projectDir);
+  const file = target ? target.split(path.sep).join('/').replace(/^\.\//, '') : null;
+  const ids = file ? reviewRules.rulesFor(ruleset, file) : ruleset.rules.map((rule) => rule.id);
+  const listed = ruleset.rules.filter((rule) => ids.includes(rule.id));
+  print(
+    json,
+    {
+      action: 'rules',
+      path: file,
+      sha256: ruleset.sha256,
+      projectFile: ruleset.projectFile,
+      disabled: ruleset.disabled,
+      rules: listed.map(({ id, title, layer, globs, source }) => ({
+        id,
+        title,
+        layer,
+        globs,
+        source,
+      })),
+    },
+    [
+      `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
+      ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
+      ...listed.map(
+        (rule) => `  ${rule.id.padEnd(24)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+      ),
+      ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
+    ]
+  );
+}
+
+module.exports = {
+  command: 'review <action> [id]',
+  description: 'Code review evidence: scope, anchor, gate, compare, rules',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--dir <path>', 'Review folder inside the project', review.DEFAULT_DIR],
+    ['--base <ref>', 'Base commit or branch (default HEAD~1)'],
+    ['--head <ref>', 'Head commit or branch (default HEAD)'],
+    ['--workspace', 'Review the working tree, untracked files included, against the base'],
+    ['--include <glob>', 'Only review matching paths (repeatable)', (v, all) => [...all, v], []],
+    ['--exclude <glob>', 'Never review matching paths (repeatable)', (v, all) => [...all, v], []],
+    [
+      '--effort <level>',
+      `Review depth: ${Object.keys(review.EFFORTS).join(', ')} (default medium)`,
+    ],
+    ['--since <id>', 'compare: the earlier review to compare against'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: (action, id, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const dir = options.dir || review.DEFAULT_DIR;
+    const json = Boolean(options.json);
+    try {
+      if (!ACTIONS.includes(action)) fail(`unknown action "${action}" (${ACTIONS.join(', ')})`);
+      if (action === 'rules') return rulesAction(projectDir, id, json);
+      requireId(id);
+
+      if (action === 'scope') {
+        const ruleset = reviewRules.loadRuleset(projectDir);
+        const scope = review.buildScope(projectDir, {
+          id,
+          base: options.base,
+          head: options.head,
+          workspace: Boolean(options.workspace),
+          include: options.include,
+          exclude: options.exclude,
+          effort: options.effort,
+          ruleset,
+        });
+        const paths = review.layout(projectDir, dir, id);
+        fs.mkdirSync(paths.root, { recursive: true });
+        writeJson(paths.scope, scope);
+        const byPath = Object.fromEntries(scope.selected.map((item) => [item.path, item.rules]));
+        fs.writeFileSync(
+          paths.checklist,
+          reviewRules.checklist(ruleset, byPath, { title: `Review checklist — ${id}` })
+        );
+        const reasons = {};
+        for (const item of scope.excluded) reasons[item.reason] = (reasons[item.reason] || 0) + 1;
+        const { plan } = scope;
+        print(
+          json,
+          {
+            action,
+            id,
+            file: paths.scope,
+            checklist: paths.checklist,
+            totals: scope.totals,
+            units: scope.units.length,
+            excluded: reasons,
+            plan,
+            rulesSha256: scope.identity.rulesSha256,
+            sha256: scope.sha256,
+          },
+          [
+            `${paths.scope}`,
+            `${scope.totals.selected} file(s) to review, ${scope.totals.lines} changed lines, ${scope.units.length} unit(s) — scope ${scope.sha256.slice(0, 12)}`,
+            ...Object.entries(reasons).map(([reason, n]) => `  excluded ${n} × ${reason}`),
+            `checklist: ${paths.checklist}`,
+            `plan: ${plan.effort} effort, ${plan.passes} pass(es)${plan.refute ? ', refutation pass' : ''}${plan.planFirst ? ', plan before reading' : ''}${plan.parallelUnits ? ', units can be reviewed in parallel' : ''}`,
+            'Every selected file must end in coverage.json as completed, failed or waived (with a reason).',
+          ]
+        );
+        return undefined;
+      }
+
+      const { paths, scope } = loadReview(projectDir, dir, id);
+
+      if (action === 'anchor') {
+        const findings = readJson(paths.findings, 'findings.json');
+        if (!findings) fail(`no findings at ${paths.findings}`);
+        const errors = review.validateFindings(findings, scope);
+        if (errors.length) {
+          print(
+            json,
+            { action, id, status: 'error', errors },
+            errors.map((e) => `  error   ${e}`)
+          );
+          process.exitCode = 1;
+          return undefined;
+        }
+        const anchored = review.anchorFindings(projectDir, scope, findings);
+        writeJson(paths.anchored, {
+          schema: review.FINDINGS_SCHEMA,
+          scopeSha256: scope.sha256,
+          ...anchored,
+        });
+        const loose = anchored.findings.filter((f) => f.location.status !== 'located');
+        const { counts } = anchored;
+        print(json, { action, id, file: paths.anchored, counts }, [
+          `${paths.anchored} — ${counts.located} located, ${counts.ambiguous} ambiguous, ${counts.unlocated} unlocated`,
+          ...loose.map(
+            (f) =>
+              `  ${f.location.status.padEnd(9)} ${f.id} ${f.path}: quote a longer, exact excerpt`
+          ),
+          ...(counts.redactions
+            ? [
+                `  ${counts.redactions} credential-like value(s) replaced by [REDACTED] in the written record`,
+              ]
+            : []),
+        ]);
+        process.exitCode = loose.length ? 1 : 0;
+        return undefined;
+      }
+
+      if (action === 'gate') {
+        const findings = readJson(paths.findings, 'findings.json');
+        const coverage = readJson(paths.coverage, 'coverage.json');
+        let anchored = null;
+        if (findings && !review.validateFindings(findings, scope).length)
+          anchored = review.anchorFindings(projectDir, scope, findings);
+        const verdict = review.reviewGate({ scope, findings, coverage, anchored });
+        print(
+          json,
+          { action, id, ...verdict },
+          [
+            `${id}: ${verdict.status} — coverage ${verdict.coverage.completed}/${verdict.coverage.selected} completed (${verdict.coverage.waived} waived), ${verdict.findings.open} open finding(s), ${verdict.findings.refuted} refuted`,
+            ...verdict.reasons.map((reason) => `  - ${reason}`),
+            verdict.status === 'clean'
+              ? '  clean: no open finding within a fully covered scope. It does not prove the code correct.'
+              : '',
+          ].filter(Boolean)
+        );
+        process.exitCode = { clean: 0, findings: 1, incomplete: 2 }[verdict.status];
+        return undefined;
+      }
+
+      // compare: this review against an earlier one.
+      const sinceId = requireId(options.since, '--since <earlier review id>');
+      if (sinceId === id) fail('--since must name a different review');
+      const earlier = loadReview(projectDir, dir, sinceId);
+      const load = (entry, label) => {
+        const findings = readJson(entry.paths.findings, `${label}/findings.json`);
+        if (!findings) fail(`no findings at ${entry.paths.findings}`);
+        const errors = review.validateFindings(findings, entry.scope);
+        if (errors.length) fail(`${label}/findings.json is invalid: ${errors[0]}`);
+        return findings;
+      };
+      const result = review.compareReviews(
+        { scope: earlier.scope, findings: load(earlier, sinceId) },
+        {
+          scope,
+          findings: load({ paths, scope }, id),
+          coverage: readJson(paths.coverage, `${id}/coverage.json`),
+        }
+      );
+      writeJson(paths.compare, result);
+      const c = result.counts;
+      print(
+        json,
+        { action, id, since: sinceId, file: paths.compare, counts: c },
+        [
+          `${id} since ${sinceId}: ${c.new} new, ${c.persisting} persisting, ${c.resolved} resolved, ${c.refuted} refuted, ${c.not_reviewed} not reviewed`,
+          c.not_reviewed
+            ? '  not reviewed: earlier findings on files this review did not complete — they are not known to be fixed.'
+            : '',
+        ].filter(Boolean)
+      );
+      return undefined;
+    } catch (error) {
+      if (json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', message: error.message }, null, 2)
+        );
+      else console.error(`review: ${error.message}`);
+      process.exitCode = 3;
+      return undefined;
+    }
+  },
+};

package/tools/cli/commands/uat.js

@@ -145,6 +145,7 @@ function serve(spec, paths, options) {
               return;
             }
           }
+          uat.redactRun(run);
           fs.writeFileSync(file, JSON.stringify(run, null, 2));
           const s = run.summary;
           console.log(
@@ -284,10 +285,22 @@ module.exports = {
         const dir = path.join(paths.results, spec.id);
         fs.mkdirSync(dir, { recursive: true });
         const file = path.join(dir, `${run.runId}.json`);
+        uat.redactRun(run);
         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`,
-        ]);
+        print(
+          json,
+          {
+            action,
+            specId: spec.id,
+            runId: run.runId,
+            file,
+            summary: run.summary,
+            redactions: run.redactions || 0,
+          },
+          [
+            `${file} — ${run.summary.passed} passed, ${run.summary.failed} failed, ${run.summary.blocked} blocked, ${run.summary.unanswered} to do`,
+          ]
+        );
         return;
       }
 

package/tools/cli/lib/glob.js

@@ -0,0 +1,73 @@
+/**
+ * Path patterns for review scopes and rules. Deliberately small and dependency-free:
+ * `**` spans directories, `*` stays within one segment, `?` is one character, and
+ * `{a,b}` alternates — every group, nested groups included. Paths use `/`.
+ */
+'use strict';
+
+const MAX_EXPANSIONS = 256;
+const cache = new Map();
+
+/** `src/{a,b{c,d}}/*.js` → four patterns. An unbalanced brace is an error, never a literal. */
+function expandBraces(pattern) {
+  const open = pattern.indexOf('{');
+  if (open < 0) {
+    if (pattern.includes('}')) throw new Error(`unbalanced "}" in pattern "${pattern}"`);
+    return [pattern];
+  }
+  let depth = 0;
+  let close = -1;
+  const commas = [];
+  for (let i = open; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) {
+      close = i;
+      break;
+    } else if (c === ',' && depth === 1) commas.push(i);
+  }
+  if (close < 0) throw new Error(`unbalanced "{" in pattern "${pattern}"`);
+  const head = pattern.slice(0, open);
+  const tail = pattern.slice(close + 1);
+  const bounds = [open, ...commas, close];
+  const results = [];
+  for (let i = 0; i < bounds.length - 1; i++) {
+    const option = pattern.slice(bounds[i] + 1, bounds[i + 1]);
+    for (const expanded of expandBraces(head + option + tail)) {
+      results.push(expanded);
+      if (results.length > MAX_EXPANSIONS)
+        throw new Error(`pattern "${pattern}" expands to more than ${MAX_EXPANSIONS} forms`);
+    }
+  }
+  return results;
+}
+
+function toRegExp(glob) {
+  let source = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      const slash = glob[i + 2] === '/';
+      source += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** Compiled once per pattern: the same patterns are tested against every changed file. */
+function compile(pattern) {
+  let compiled = cache.get(pattern);
+  if (!compiled) {
+    compiled = expandBraces(pattern).map(toRegExp);
+    cache.set(pattern, compiled);
+  }
+  return compiled;
+}
+
+const matches = (file, pattern) => compile(pattern).some((re) => re.test(file));
+const matchesAny = (file, patterns) => patterns.some((pattern) => matches(file, pattern));
+
+module.exports = { expandBraces, compile, matches, matchesAny };

package/tools/cli/lib/packs.js

@@ -191,7 +191,7 @@ const DERIVED = {
   "product": {
     "code": "bmad-plus",
     "displayName": "BMAD+",
-    "version": "0.18.0",
+    "version": "0.20.0",
     "derivedFrom": "BMAD-METHOD v6.6.0"
   },
   "packOrder": [

package/tools/cli/lib/redact.js

@@ -0,0 +1,116 @@
+/**
+ * Redaction floor for free text that BMAD+ writes to disk or prints: reviewer notes,
+ * tester notes, finding descriptions. It removes credentials that commonly end up pasted
+ * into such text; it is a floor, not a scanner, and never a reason to paste secrets.
+ */
+'use strict';
+
+const MARK = '[REDACTED]';
+const MAX_LENGTH = 20000;
+
+/**
+ * A value that names where a secret comes from rather than holding it: an environment or
+ * secret-store reference, a template placeholder, or an UPPER_SNAKE variable name (an
+ * underscore is required, so an all-capitals random key is still masked).
+ */
+const REFERENCE =
+  /^(?:process\.env\b|os\.environ\b|os\.getenv\b|getenv\b|env\.|secrets\.|vars\.|\$|%|<|\{\{|[A-Z][A-Z0-9]*_[A-Z0-9_]*$|\[REDACTED\]$)/;
+
+/** Ordered: whole blocks first, then structured forms, then well-known token shapes. */
+const RULES = [
+  {
+    kind: 'private-key',
+    pattern:
+      /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g,
+    replace: () => `-----${MARK} PRIVATE KEY-----`,
+  },
+  {
+    kind: 'url-credentials',
+    pattern: /\b([a-z][a-z0-9+.-]{1,20}:\/\/)[^\s/?#@:]+:[^\s/?#@]+@/gi,
+    replace: (_, scheme) => `${scheme}${MARK}@`,
+  },
+  {
+    kind: 'authorization',
+    pattern:
+      /\b((?:authorization|proxy-authorization)\s*[:=]\s*)(bearer|basic|token|digest)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+    replace: (_, lead, scheme) => `${lead}${scheme} ${MARK}`,
+  },
+  {
+    kind: 'bearer',
+    pattern: /\b(bearer\s+)[A-Za-z0-9._~+/=-]{16,}/gi,
+    replace: (_, lead) => `${lead}${MARK}`,
+  },
+  {
+    kind: 'assignment',
+    // name = value where the name says it holds a credential; the name stays readable.
+    pattern:
+      /\b([A-Za-z0-9_.-]*(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?key|credentials?)[A-Za-z0-9_.-]*["']?\s*[:=]\s*)(["']?)([^\s"',;]{6,})\2/gi,
+    replace: (whole, lead, quote, value) =>
+      REFERENCE.test(value) ? whole : `${lead}${quote}${MARK}${quote}`,
+  },
+  {
+    kind: 'known-token',
+    pattern: new RegExp(
+      [
+        'gh[pousr]_[A-Za-z0-9]{30,}',
+        'github_pat_[A-Za-z0-9_]{40,}',
+        'glpat-[A-Za-z0-9_-]{20,}',
+        'npm_[A-Za-z0-9]{30,}',
+        'sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}',
+        'xox[abprs]-[A-Za-z0-9-]{10,}',
+        'AKIA[0-9A-Z]{16}',
+        'AIza[0-9A-Za-z_-]{35}',
+        'eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}',
+      ]
+        .map((source) => `\\b${source}`)
+        .join('|'),
+      'g'
+    ),
+    replace: () => MARK,
+  },
+];
+
+/** Control characters other than tab, line feed and carriage return are dropped. */
+function stripControl(text) {
+  let out = '';
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127)) out += char;
+  }
+  return out;
+}
+
+/**
+ * Returns the text with credentials replaced by a marker, and what was replaced by kind.
+ * Non-strings pass through untouched so callers can map over mixed records.
+ */
+function redact(value, { maxLength = MAX_LENGTH } = {}) {
+  if (typeof value !== 'string') return { text: value, found: {} };
+  let text = stripControl(value);
+  const found = {};
+  for (const rule of RULES) {
+    text = text.replace(rule.pattern, (...match) => {
+      found[rule.kind] = (found[rule.kind] || 0) + 1;
+      return rule.replace(...match);
+    });
+  }
+  if (text.length > maxLength) {
+    text = `${text.slice(0, maxLength)} […${text.length - maxLength} characters cut]`;
+    found.truncated = 1;
+  }
+  return { text, found };
+}
+
+/** Redacts the listed string fields of a record in place; returns the number of replacements. */
+function redactFields(record, fields, options) {
+  let count = 0;
+  for (const field of fields) {
+    if (typeof record[field] !== 'string') continue;
+    const { text, found } = redact(record[field], options);
+    record[field] = text;
+    count += Object.entries(found).reduce((n, [kind, k]) => (kind === 'truncated' ? n : n + k), 0);
+  }
+  return count;
+}
+
+module.exports = { MARK, redact, redactFields };

package/tools/cli/lib/review-rules.js

@@ -0,0 +1,156 @@
+/**
+ * Review checklists chosen by path. Built-in rules ship with the CLI; a project adds,
+ * replaces or disables rules in `_bmad/review-rules.yaml`. Every rule whose patterns match
+ * a file applies to it — rules add up, so a broad project rule never silences the built-in
+ * ones by accident. The resolved set is hashed into the review scope.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { compile, matchesAny } = require('./glob');
+
+const SCHEMA = 'bmad-plus/review-rules/1';
+const BUILTIN_DIR = path.join(__dirname, '..', 'review-rules');
+const PROJECT_FILE = path.join('_bmad', 'review-rules.yaml');
+const RULE_ID = /^[a-z0-9][a-z0-9-]{0,60}$/;
+const RULE_KEYS = ['id', 'title', 'globs', 'doc'];
+const MAX_DOC_BYTES = 64 * 1024;
+const MAX_INDEX_BYTES = 256 * 1024;
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+/** A file this module reads must be a regular file inside `root`, of bounded size. */
+function readConfined(root, relative, maxBytes, what) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative))
+    throw new Error(`${what}: expected a relative path, got "${relative}"`);
+  const realRoot = fs.realpathSync(root);
+  const file = path.resolve(realRoot, relative);
+  if (file !== realRoot && !file.startsWith(realRoot + path.sep))
+    throw new Error(`${what}: "${relative}" leaves ${root}`);
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile()) throw new Error(`${what}: "${relative}" is not a regular file`);
+  if (stat.size > maxBytes) throw new Error(`${what}: "${relative}" exceeds ${maxBytes} bytes`);
+  return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+}
+
+function parseLayer(root, indexName, layer) {
+  const where = `${layer} review rules (${path.join(root, indexName)})`;
+  let doc;
+  try {
+    doc = yaml.load(readConfined(root, indexName, MAX_INDEX_BYTES, where));
+  } catch (error) {
+    throw new Error(`${where}: ${error.message}`, { cause: error });
+  }
+  if (!doc || doc.schema !== SCHEMA) throw new Error(`${where}: schema must be "${SCHEMA}"`);
+  const extra = Object.keys(doc).filter((key) => !['schema', 'rules', 'disable'].includes(key));
+  if (extra.length) throw new Error(`${where}: unknown key(s) ${extra.join(', ')}`);
+  if (layer === 'builtin' && doc.disable)
+    throw new Error(`${where}: built-in rules cannot disable`);
+  const disable = doc.disable || [];
+  if (!Array.isArray(disable) || !disable.every((id) => typeof id === 'string'))
+    throw new Error(`${where}: disable must be a list of rule ids`);
+  const rules = doc.rules || [];
+  if (!Array.isArray(rules)) throw new Error(`${where}: rules must be a list`);
+  const seen = new Set();
+  const parsed = rules.map((rule, index) => {
+    const at = `${where}: rule ${rule?.id ?? index}`;
+    if (!rule || typeof rule !== 'object') throw new Error(`${at}: must be a mapping`);
+    const unknown = Object.keys(rule).filter((key) => !RULE_KEYS.includes(key));
+    if (unknown.length) throw new Error(`${at}: unknown key(s) ${unknown.join(', ')}`);
+    if (!RULE_ID.test(String(rule.id))) throw new Error(`${at}: invalid id`);
+    if (seen.has(rule.id)) throw new Error(`${at}: duplicate id`);
+    seen.add(rule.id);
+    if (typeof rule.title !== 'string' || !rule.title.trim())
+      throw new Error(`${at}: title is required`);
+    if (
+      !Array.isArray(rule.globs) ||
+      !rule.globs.length ||
+      !rule.globs.every((g) => typeof g === 'string' && g)
+    )
+      throw new Error(`${at}: globs must be a non-empty list of patterns`);
+    for (const glob of rule.globs) compile(glob);
+    if (!/\.md$/i.test(String(rule.doc))) throw new Error(`${at}: doc must be a Markdown file`);
+    const text = readConfined(root, rule.doc, MAX_DOC_BYTES, at).trim();
+    if (!text) throw new Error(`${at}: ${rule.doc} is empty`);
+    return {
+      id: rule.id,
+      title: rule.title.trim(),
+      globs: [...rule.globs],
+      layer,
+      source: rule.doc,
+      text,
+    };
+  });
+  return { rules: parsed, disable };
+}
+
+/**
+ * The effective rule set for a project: built-in rules, then the project's own. A project
+ * rule with a built-in id replaces it; `disable` removes rules by id and is reported.
+ */
+function loadRuleset(projectDir, { builtinDir = BUILTIN_DIR } = {}) {
+  const builtin = parseLayer(builtinDir, 'index.yaml', 'builtin');
+  const ordered = new Map(builtin.rules.map((rule) => [rule.id, rule]));
+  let disabled = [];
+  const projectIndex = path.join(projectDir, PROJECT_FILE);
+  let project = null;
+  if (fs.existsSync(projectIndex)) {
+    project = parseLayer(path.dirname(projectIndex), path.basename(projectIndex), 'project');
+    for (const rule of project.rules) ordered.set(rule.id, rule);
+    const unknown = project.disable.filter((id) => !ordered.has(id));
+    if (unknown.length)
+      throw new Error(`project review rules: disable names unknown rule(s) ${unknown.join(', ')}`);
+    disabled = [...project.disable];
+    for (const id of disabled) ordered.delete(id);
+  }
+  const list = [...ordered.values()];
+  const fingerprint = list.map((rule) => [rule.id, rule.layer, rule.globs, sha256(rule.text)]);
+  return {
+    rules: list,
+    disabled,
+    projectFile: project ? PROJECT_FILE.split(path.sep).join('/') : null,
+    sha256: sha256(JSON.stringify({ rules: fingerprint, disabled })),
+  };
+}
+
+/** Ids of every rule that applies to a path, in rule order. */
+function rulesFor(ruleset, file) {
+  return ruleset.rules.filter((rule) => matchesAny(file, rule.globs)).map((rule) => rule.id);
+}
+
+/**
+ * The reviewer's checklist for a scope: each applicable rule once, with the files it
+ * covers. Rules that match nothing in the scope are left out.
+ */
+function checklist(ruleset, byPath, { title = 'Review checklist' } = {}) {
+  const files = new Map();
+  for (const [file, ids] of Object.entries(byPath)) {
+    for (const id of ids) files.set(id, [...(files.get(id) || []), file]);
+  }
+  const sections = ruleset.rules
+    .filter((rule) => files.has(rule.id))
+    .map((rule) =>
+      [
+        `## ${rule.title} \`${rule.id}\`${rule.layer === 'project' ? ' (project rule)' : ''}`,
+        '',
+        `Applies to: ${files
+          .get(rule.id)
+          .map((file) => `\`${file}\``)
+          .join(', ')}`,
+        '',
+        rule.text,
+      ].join('\n')
+    );
+  return [
+    `# ${title}`,
+    '',
+    `Rule set ${ruleset.sha256.slice(0, 12)}. Report a finding only with its quoted code; a rule is a prompt to look, not a finding.`,
+    '',
+    ...sections.flatMap((section) => [section, '']),
+  ].join('\n');
+}
+
+module.exports = { SCHEMA, BUILTIN_DIR, PROJECT_FILE, loadRuleset, rulesFor, checklist };