bmad-plus 0.21.0 → 0.22.0

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

@@ -1,8 +1,9 @@
 /**
- * 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.
+ * Review checklists chosen by path. Built-in rules ship with the CLI; an installed pack may
+ * add its own (Shield's compliance rules); 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. A rule may
+ * name the compliance controls it examines. The resolved set is hashed into the review scope.
  */
 'use strict';
 
@@ -11,12 +12,16 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const yaml = require('js-yaml');
 const { compile, matchesAny } = require('./glob');
+const { parseControls } = require('./control-refs');
+const { PACKS } = require('./packs');
 
 const SCHEMA = 'bmad-plus/review-rules/1';
 const BUILTIN_DIR = path.join(__dirname, '..', 'review-rules');
 const PROJECT_FILE = path.join('_bmad', 'review-rules.yaml');
+/** Where an installed pack keeps its rules, below its own folder in `.agents/skills`. */
+const PACK_RULES_DIR = 'review-rules';
 const RULE_ID = /^[a-z0-9][a-z0-9-]{0,60}$/;
-const RULE_KEYS = ['id', 'title', 'group', 'globs', 'doc'];
+const RULE_KEYS = ['id', 'title', 'group', 'globs', 'doc', 'controls'];
 const MAX_DOC_BYTES = 64 * 1024;
 const MAX_INDEX_BYTES = 256 * 1024;
 
@@ -47,8 +52,8 @@ function parseLayer(root, indexName, layer) {
   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`);
+  if (layer !== 'project' && doc.disable)
+    throw new Error(`${where}: only a project's rules can 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`);
@@ -74,6 +79,7 @@ function parseLayer(root, indexName, layer) {
     )
       throw new Error(`${at}: globs must be a non-empty list of patterns`);
     for (const glob of rule.globs) compile(glob);
+    const controls = rule.controls === undefined ? [] : parseControls(rule.controls, at);
     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`);
@@ -83,6 +89,7 @@ function parseLayer(root, indexName, layer) {
       // A rule family reviewers can split by; a rule without one is a family of its own.
       group: rule.group === undefined ? rule.id : rule.group,
       globs: [...rule.globs],
+      controls,
       layer,
       source: rule.doc,
       text,
@@ -91,13 +98,35 @@ function parseLayer(root, indexName, layer) {
   return { rules: parsed, disable };
 }
 
+/** Rule indexes of the packs installed in the project, in pack order. */
+function installedPackLayers(projectDir) {
+  const layers = [];
+  for (const [pack, { packDir }] of Object.entries(PACKS)) {
+    if (!packDir) continue;
+    const relative = ['.agents', 'skills', packDir, PACK_RULES_DIR, 'index.yaml'];
+    if (fs.existsSync(path.join(projectDir, ...relative)))
+      layers.push({ pack, file: relative.join('/') });
+  }
+  return layers;
+}
+
 /**
- * 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.
+ * The effective rule set for a project: built-in rules, then those of installed packs, then
+ * the project's own. A pack only adds; a project rule with an existing id replaces it, and
+ * `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]));
+  const packFiles = installedPackLayers(projectDir);
+  for (const { pack, file } of packFiles) {
+    const layer = parseLayer(path.join(projectDir, path.dirname(file)), 'index.yaml', 'pack');
+    for (const rule of layer.rules) {
+      if (ordered.has(rule.id))
+        throw new Error(`${pack} review rules: rule ${rule.id} already exists; a pack only adds`);
+      ordered.set(rule.id, { ...rule, pack });
+    }
+  }
   let disabled = [];
   const projectIndex = path.join(projectDir, PROJECT_FILE);
   let project = null;
@@ -111,16 +140,20 @@ function loadRuleset(projectDir, { builtinDir = BUILTIN_DIR } = {}) {
     for (const id of disabled) ordered.delete(id);
   }
   const list = [...ordered.values()];
+  // Controls join the fingerprint only when a rule names some, so a rule set without any
+  // keeps the hash it had before rules could carry controls.
   const fingerprint = list.map((rule) => [
     rule.id,
     rule.group,
     rule.layer,
     rule.globs,
     sha256(rule.text),
+    ...(rule.controls.length ? [rule.controls] : []),
   ]);
   return {
     rules: list,
     disabled,
+    packFiles: packFiles.map(({ file }) => file),
     projectFile: project ? PROJECT_FILE.split(path.sep).join('/') : null,
     sha256: sha256(JSON.stringify({ rules: fingerprint, disabled })),
   };
@@ -142,35 +175,68 @@ function groupsOf(ruleset, ids) {
 }
 
 /**
- * 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.
+ * The compliance controls a set of rule ids examines, each with the rules that name it, in
+ * rule order. A control touched is a prompt to look at its requirement, not a finding.
+ */
+function controlsOf(ruleset, ids) {
+  const controls = new Map();
+  for (const rule of ruleset.rules) {
+    if (!ids.includes(rule.id)) continue;
+    for (const control of rule.controls)
+      controls.set(control, [...(controls.get(control) || []), rule.id]);
+  }
+  return [...controls].map(([id, rules]) => ({ id, rules }));
+}
+
+/**
+ * The reviewer's checklist for a scope: the controls the change touches, then each
+ * applicable rule once, with the files it covers. Rules that match nothing 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)' : ''}`,
+  const applied = ruleset.rules.filter((rule) => files.has(rule.id));
+  const controls = controlsOf(
+    ruleset,
+    applied.map((rule) => rule.id)
+  );
+  const touched = controls.length
+    ? [
+        '## Controls this change touches',
         '',
-        `Group: \`${rule.group}\``,
+        ...controls.map(
+          ({ id, rules }) => `- \`${id}\` — ${rules.map((rule) => `\`${rule}\``).join(', ')}`
+        ),
         '',
-        `Applies to: ${files
-          .get(rule.id)
-          .map((file) => `\`${file}\``)
-          .join(', ')}`,
+        'List in the `controls` of a finding the control it breaks; a control listed here is not a finding.',
         '',
-        rule.text,
-      ].join('\n')
-    );
+      ]
+    : [];
+  const sections = applied.map((rule) =>
+    [
+      `## ${rule.title} \`${rule.id}\`${rule.layer === 'project' ? ' (project rule)' : ''}${rule.pack ? ` (${rule.pack} rule)` : ''}`,
+      '',
+      `Group: \`${rule.group}\``,
+      ...(rule.controls.length
+        ? ['', `Controls: ${rule.controls.map((control) => `\`${control}\``).join(', ')}`]
+        : []),
+      '',
+      `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.`,
     '',
+    ...touched,
     ...sections.flatMap((section) => [section, '']),
   ].join('\n');
 }
@@ -179,8 +245,10 @@ module.exports = {
   SCHEMA,
   BUILTIN_DIR,
   PROJECT_FILE,
+  PACK_RULES_DIR,
   loadRuleset,
   rulesFor,
   groupsOf,
+  controlsOf,
   checklist,
 };

package/tools/cli/lib/review.js

@@ -295,6 +295,9 @@ function buildScope(projectDir, options = {}) {
   const ruleset = options.ruleset || rules.loadRuleset(projectDir);
   for (const item of selected) {
     item.rules = rules.rulesFor(ruleset, item.path);
+    // Kept only when a rule names controls, so a scope without any keeps its digest.
+    const controls = rules.controlsOf(ruleset, item.rules).map(({ id }) => id);
+    if (controls.length) item.controls = controls;
     // A commit fixes the content under review; a working tree does not, so its bytes are sealed.
     if (options.workspace) item.sha256 = contentDigest(projectDir, item.path);
   }
@@ -312,8 +315,14 @@ function buildScope(projectDir, options = {}) {
   };
   const units = planUnits(selected, options.unitLimits).map((unit) => {
     const ids = [...new Set(unit.paths.flatMap((p) => selected.find((s) => s.path === p).rules))];
+    const controls = rules.controlsOf(ruleset, ids).map(({ id }) => id);
     // Rule groups let parallel reviewers split one unit by rule family.
-    return { ...unit, rules: ids, groups: rules.groupsOf(ruleset, ids) };
+    return {
+      ...unit,
+      rules: ids,
+      groups: rules.groupsOf(ruleset, ids),
+      ...(controls.length ? { controls } : {}),
+    };
   });
   const lines = selected.reduce((n, item) => n + item.added + item.removed, 0);
   const plan = reviewPlan(effort, lines, units.length);
@@ -349,6 +358,7 @@ const FINDING_KEYS = [
   'refutation',
   'fix',
   'rule',
+  'controls',
 ];
 
 /** Unknown values are errors, never coerced: a wrong enum is a wrong finding. */
@@ -395,6 +405,21 @@ function validateFindings(doc, 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}`);
+    // It may name the controls it breaks: only those the rules for that file examine.
+    if (finding.controls !== undefined) {
+      if (
+        !Array.isArray(finding.controls) ||
+        !finding.controls.length ||
+        !finding.controls.every((control) => typeof control === 'string')
+      )
+        errors.push(`${at}: controls must be a non-empty list of control ids`);
+      else if (entry)
+        for (const control of finding.controls)
+          if (!(entry.controls || []).includes(control))
+            errors.push(
+              `${at}: control "${control}" is not examined by the rules for ${finding.path}`
+            );
+    }
   }
   return errors;
 }
@@ -755,6 +780,7 @@ function checkResult({ id, scope, verdict, anchored }) {
       confidence: f.confidence,
       disposition: f.disposition,
       ...(f.rule !== undefined ? { rule: f.rule } : {}),
+      ...(f.controls !== undefined ? { controls: f.controls } : {}),
       anchor: f.location.status,
       lineStart: f.location.status === 'located' ? f.location.lineStart : null,
       lineEnd: f.location.status === 'located' ? f.location.lineEnd : null,
@@ -934,6 +960,7 @@ function remainingWork({ scope, coverage, anchored, findingErrors = [] }) {
       id: unit.id,
       paths: unit.paths.filter((file) => pending.has(file)),
       rules: unit.rules,
+      ...(unit.controls ? { controls: unit.controls } : {}),
       // Rule groups another reviewer already completed are not handed out again.
       ...(unit.groups
         ? { groups: unit.groups.filter((group) => !done.has(`${unit.id}/${group.id}`)) }

package/tools/cli/lib/uat.js

@@ -5,6 +5,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { redactFields } = require('./redact');
+const { foreignAddresses } = require('./page-origins');
 
 const SPEC_SCHEMA = 'bmad-plus/uat-spec/2';
 const RESULTS_SCHEMA = 'bmad-plus/uat-results/2';
@@ -176,6 +177,9 @@ function checkMarkup(value, where, errors) {
     rest = rest.replace(match[0], '');
   }
   if (rest.includes('<')) errors.push(`${where}: a "<" is left outside any allowed tag`);
+  // The page renders this text as markup: it is read as the template is, so the page loads
+  // nothing from another origin whatever the allowed tags come to be.
+  for (const found of foreignAddresses(value)) errors.push(`${where}: ${found}`);
 }
 
 function eachMarkup(spec, visit) {
@@ -575,22 +579,34 @@ const PAGE_GUARANTEES = [
     what: 'the exported JSON is the run as answered, and nothing is exported before a run exists',
     markers: ['download(runId + ".json", JSON.stringify(run, null, 2))'],
   },
+  {
+    id: 'no-third-party-requests',
+    what: 'opening and using the page asks nothing of any origin but its own: no remote font, stylesheet, script, image or frame',
+    markers: [],
+    // An absence has no marker: the template is read as a browser reads it, and every address
+    // it would reach on another origin, in markup, style or script, is refused by name.
+    refuses: foreignAddresses,
+  },
 ];
 
 /**
  * Which guarantees a template carries: every marker present, in the required order where one
- * is set. Checked on the TEMPLATE, never on the built page: a recipe's own text must not be
- * able to satisfy or defeat a marker.
+ * is set, and nothing it refuses. Checked on the TEMPLATE, never on the built page: a recipe's
+ * own text must not be able to satisfy or defeat a marker.
  */
 function pageGuarantees(template) {
   const missing = [];
   for (const guarantee of PAGE_GUARANTEES) {
-    const lost = guarantee.markers.filter((marker) => !template.includes(marker));
+    const lost = guarantee.markers
+      .filter((marker) => !template.includes(marker))
+      .map((marker) => `missing ${marker}`);
     if (!lost.length && guarantee.order) {
       const positions = guarantee.order.map((marker) => template.indexOf(marker));
       if (positions.some((at) => at < 0) || positions.some((at, i) => i && at < positions[i - 1]))
-        lost.push(`order ${guarantee.order.join(' → ')}`);
+        lost.push(`missing order ${guarantee.order.join(' → ')}`);
     }
+    if (guarantee.refuses)
+      for (const found of guarantee.refuses(template)) lost.push(`carries ${found}`);
     if (lost.length) missing.push({ id: guarantee.id, what: guarantee.what, lost });
   }
   const carried = PAGE_GUARANTEES.map((g) => g.id).filter(
@@ -607,7 +623,7 @@ function buildPage(spec, options = {}) {
   if (!guarantees.ok) {
     throw new Error(
       `the page template (${options.template ? 'the template given' : TEMPLATE}) lost a guarantee — not built: ${guarantees.missing
-        .map((entry) => `${entry.id}: ${entry.what} — missing ${entry.lost.join(', ')}`)
+        .map((entry) => `${entry.id}: ${entry.what} — ${entry.lost.join(', ')}`)
         .join('; ')}`
     );
   }
@@ -1013,6 +1029,7 @@ module.exports = {
   TRIAGE_SCHEMA,
   DEFAULT_DIR,
   DEFAULT_BUDGET,
+  ALLOWED_TAGS,
   STATES,
   TRIAGE_CLASSES,
   TRIAGE_DECISIONS,