bmad-plus 0.19.0 → 0.20.0

package/tools/cli/lib/review.js

@@ -3,10 +3,9 @@
  * 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, and whether every selected file was accounted for. Design taken from
- * the open-code-review study (docs/research/open-code-review-2026-09-25): deterministic
- * selection with named exclusion reasons, verbatim-snippet anchoring, coverage-derived
- * disposition. No model call, no network, no write outside the review folder.
+ * 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';
 
@@ -14,6 +13,9 @@ 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';
@@ -72,24 +74,30 @@ const GENERATED_PATTERNS = [
 ];
 const UNIT_LIMITS = { files: 8, lines: 400 };
 
-const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+/**
+ * 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 };
 
-/** A small glob: `**` spans directories, `*` stays within one, `?` is one character. Case-sensitive. */
-function globToRegExp(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}$`);
+/** 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 matchesAny = (file, patterns) => patterns.some((glob) => globToRegExp(glob).test(file));
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
 
 function git(projectDir, args) {
   const result = spawnSync('git', args, {
@@ -251,6 +259,10 @@ function buildScope(projectDir, options = {}) {
         ...(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',
@@ -258,10 +270,16 @@ function buildScope(projectDir, options = {}) {
     workspace: Boolean(options.workspace),
     include,
     exclude,
+    effort,
+    rulesSha256: ruleset.sha256,
   };
-  const units = planUnits(selected, options.unitLimits);
+  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 body = { identity, selected, excluded, units };
+  const plan = reviewPlan(effort, lines, units.length);
+  const body = { identity, selected, excluded, units, plan };
   return {
     schema: SCOPE_SCHEMA,
     id: options.id,
@@ -292,6 +310,7 @@ const FINDING_KEYS = [
   'evidence',
   'refutation',
   'fix',
+  'rule',
 ];
 
 /** Unknown values are errors, never coerced: a wrong enum is a wrong finding. */
@@ -332,8 +351,12 @@ function validateFindings(doc, scope) {
       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`);
-    if (scope && finding.path && !scope.selected.some((item) => item.path === finding.path))
+    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;
 }
@@ -396,11 +419,27 @@ function anchorFindings(projectDir, scope, doc) {
       location: { status: 'unlocated', reason: 'the quoted code is not in the file' },
     };
   });
-  const counts = { located: 0, ambiguous: 0, unlocated: 0 };
-  for (const finding of anchored) counts[finding.location.status] += 1;
+  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) {
@@ -486,6 +525,73 @@ function reviewGate({ scope, findings, coverage, anchored }) {
   };
 }
 
+// ── 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 {
@@ -494,6 +600,8 @@ function layout(projectDir, dir = DEFAULT_DIR, id) {
     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'),
   };
 }
 
@@ -501,7 +609,9 @@ module.exports = {
   SCOPE_SCHEMA,
   FINDINGS_SCHEMA,
   COVERAGE_SCHEMA,
+  COMPARE_SCHEMA,
   DEFAULT_DIR,
+  EFFORTS,
   SEVERITIES,
   CATEGORIES,
   DISPOSITIONS,
@@ -509,7 +619,6 @@ module.exports = {
   OUTCOMES,
   SECRET_PATTERNS,
   GENERATED_PATTERNS,
-  globToRegExp,
   parseNumstat,
   planUnits,
   buildScope,
@@ -518,5 +627,8 @@ module.exports = {
   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';
@@ -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.

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

@@ -0,0 +1,6 @@
+- **Privilege.** Containers running as root without need; `privileged: true`, added capabilities, host network or PID namespace; the Docker socket mounted into a container (root on the host).
+- **Images.** Base images on `latest` or an unpinned tag; packages installed without cleanup or version pins where reproducibility matters; secrets passed as build arguments or copied into a layer.
+- **Exposure.** Ports published on `0.0.0.0` for services that should stay internal (databases, caches, admin APIs); missing network separation between stacks.
+- **Health and restart.** No health check for a service others depend on; `depends_on` without a health condition; restart policies that loop a crashing container.
+- **Data.** Volumes for stateful services missing or anonymous; host paths mounted read-write where read-only suffices.
+- **Resources.** No memory or CPU limits on a shared host; Kubernetes pods without requests/limits, probes or a `securityContext` (`runAsNonRoot`, `readOnlyRootFilesystem`).

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

@@ -0,0 +1,10 @@
+Look for what the diff changes in behaviour, not how it reads.
+
+- **Callers.** Search every caller of a changed function, export, route, command or schema. A signature, return shape or error type that changed is a defect at the caller that was not updated.
+- **Removed behaviour.** Read what the diff deletes: a check, a branch, a cleanup, a log that an operator relies on. Deleted protection is the most often missed defect.
+- **Boundaries.** Empty input, one element, the last element, the maximum size, a missing optional field, a concurrent second call, a retry after a partial failure.
+- **Errors.** An error swallowed, logged and ignored, or turned into a success value. A failure path that leaves state half-written.
+- **Trust.** Data that crosses a boundary (request, file, environment, another service, a model's output) and reaches a query, a command, a path, HTML or a permission decision without validation.
+- **Tests.** A changed behaviour whose test still passes because it mocks the changed path, asserts nothing about the new case, or is skipped.
+
+Do not report formatting, naming or style a linter enforces, and do not propose rewrites the change did not need.

package/tools/cli/review-rules/index.yaml

@@ -0,0 +1,36 @@
+# Built-in review checklists, applied by path. Every matching rule applies to a file.
+# A project adds, replaces (same id) or disables rules in _bmad/review-rules.yaml.
+schema: bmad-plus/review-rules/1
+rules:
+  - id: general
+    title: Every change
+    globs: ['**']
+    doc: general.md
+  - id: javascript-typescript
+    title: JavaScript and TypeScript
+    globs: ['**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx}', '**/*.{vue,svelte}']
+    doc: javascript-typescript.md
+  - id: python
+    title: Python
+    globs: ['**/*.{py,pyi}']
+    doc: python.md
+  - id: sql-and-migrations
+    title: SQL, queries and migrations
+    globs: ['**/*.sql', '**/{migrations,migrate,db/migrate}/**', '**/*.prisma', '**/schema.rb']
+    doc: sql-and-migrations.md
+  - id: shell
+    title: Shell and PowerShell scripts
+    globs: ['**/*.{sh,bash,zsh,ps1,psm1}', '**/{Makefile,makefile}']
+    doc: shell.md
+  - id: ci-workflows
+    title: CI workflows
+    globs: ['.github/workflows/**/*.{yml,yaml}', '**/.gitlab-ci.yml', '**/{bitbucket-pipelines.yml,azure-pipelines.yml}']
+    doc: ci-workflows.md
+  - id: containers
+    title: Containers and deployment manifests
+    globs: ['**/{Dockerfile,Containerfile}', '**/*.dockerfile', '**/{docker-,}compose*.{yml,yaml}', '**/{k8s,kubernetes,helm,charts}/**/*.{yml,yaml}']
+    doc: containers.md
+  - id: configuration
+    title: Configuration and dependency manifests
+    globs: ['**/*.{json,yml,yaml,toml,ini,properties}', '**/.env.example', '**/{package.json,pyproject.toml,requirements*.txt,go.mod,Cargo.toml,composer.json}']
+    doc: configuration.md

package/tools/cli/review-rules/javascript-typescript.md

@@ -0,0 +1,7 @@
+- **Async.** A promise that is created but not awaited or returned; `forEach` with an async callback; an `await` inside a loop that should run in parallel, or `Promise.all` where one failure must not cancel the others (`allSettled`). Unhandled rejections in event handlers and timers.
+- **Nullish values.** Property access on a value that can be `undefined` after an `await`, a `find`, a map lookup or an optional API field; `||` used where `0`, `''` or `false` are valid values and `??` was meant.
+- **Equality and numbers.** Loose equality across types; floating-point money; `parseInt` without a radix or on user input without a `NaN` check; array index arithmetic off by one.
+- **Mutation.** A function that mutates its argument or a shared default object; sorting or splicing an array the caller still uses; state mutated in a React render or a reducer.
+- **Injection.** `innerHTML`, `dangerouslySetInnerHTML`, `v-html`, template literals building SQL, shell commands through `exec` or `shell: true`, `eval`/`new Function`, a user-controlled path reaching `fs` without confinement, a user-controlled URL fetched by the server (SSRF), `Object.assign`/spread of untrusted keys (`__proto__`).
+- **Types that lie.** `as` casts, non-null assertions (`!`) and `any` that hide a real `undefined` or a wrong shape at runtime.
+- **Resources.** Listeners, intervals, streams, file handles or database connections opened without a matching close on every path, including errors.

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

@@ -0,0 +1,6 @@
+- **Defaults and scope.** Mutable default arguments; a loop variable captured late by a closure; a module-level object mutated per request.
+- **Exceptions.** Bare `except:` or `except Exception` that swallows and continues; `raise` without `from` that loses the cause; cleanup that is not in `finally` or a context manager.
+- **Resources.** Files, sockets, database cursors and locks not managed by `with`; a subprocess whose output is never drained.
+- **Injection.** SQL built with f-strings or `%`; `subprocess` with `shell=True` or a string command built from input; `pickle`, `yaml.load` without a safe loader, `eval`/`exec` on untrusted data; `os.path.join` with an absolute user path; `tarfile`/`zipfile` extraction without member path checks.
+- **Types and values.** `None` returned on one path and used unconditionally; integer division where a float was meant; naive and aware datetimes compared; timezones assumed.
+- **Concurrency.** Shared state touched from threads or async tasks without a lock; a blocking call inside an `async def`.

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

@@ -0,0 +1,6 @@
+- **Failure handling.** Bash without `set -euo pipefail` (or an explicit reason); a failing command in a pipeline hidden by the last stage; PowerShell without `$ErrorActionPreference = 'Stop'` where errors must stop the script; native exit codes (`$LASTEXITCODE`) not checked.
+- **Quoting.** Unquoted variables and command substitutions that split on spaces or expand globs; `eval` or `Invoke-Expression` on data.
+- **Destructive commands.** `rm -rf`, `Remove-Item -Recurse`, `git reset --hard`, `DROP` or deploy commands on a path or target built from a variable that can be empty or wrong.
+- **Secrets.** Tokens passed on the command line (visible in process lists and logs), echoed, or written to world-readable files; `set -x` in a script that handles credentials.
+- **Portability.** Bash-only syntax under `#!/bin/sh`; GNU-only flags on macOS; PowerShell 7 syntax (`&&`, `??`, ternary) in scripts run by Windows PowerShell 5.1; CRLF line endings in a script run by Linux.
+- **Temporary files.** Predictable names in shared directories instead of `mktemp`/`New-TemporaryFile`, and no cleanup trap.

package/tools/cli/review-rules/sql-and-migrations.md

@@ -0,0 +1,6 @@
+- **Parameters.** Any value reaching a query must be bound, never concatenated; identifiers (table, column, sort order) chosen from an allow-list.
+- **Scope of writes.** An `UPDATE` or `DELETE` whose `WHERE` can match more rows than intended, or none at all silently; a missing tenant or owner filter.
+- **Migrations.** A migration that locks a large table, drops or renames a column still read by the running version, adds a `NOT NULL` column without a default or backfill, or cannot be rolled back. Data migrations must be idempotent and safe to rerun.
+- **Transactions.** Several writes that must succeed together outside a transaction; a transaction held open across a network call.
+- **Performance.** A new filter or join on a column without an index; a query inside a loop (N+1); an unbounded result set returned to a caller.
+- **Nulls.** Comparisons with `NULL` using `=`; aggregates or `NOT IN` over nullable columns.