bmad-plus 0.21.0 → 0.23.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/swarm-deal.js

@@ -0,0 +1,116 @@
+/** Deterministic dealing: the same profile, n and seed give the same cards, on any platform. */
+'use strict';
+
+const crypto = require('node:crypto');
+
+const WORD = 2 ** 32;
+
+/** A counter-mode generator over SHA-256: the stream depends on the seed alone. */
+class Dealer {
+  constructor(seed) {
+    this.seed = String(seed);
+    this.block = 0;
+    this.words = [];
+  }
+
+  next() {
+    if (!this.words.length) {
+      const digest = crypto
+        .createHash('sha256')
+        .update(this.seed + ':' + this.block)
+        .digest();
+      this.block += 1;
+      for (let offset = 0; offset < digest.length; offset += 4)
+        this.words.push(digest.readUInt32BE(offset));
+    }
+    return this.words.shift();
+  }
+
+  /** Uniform integer in [0, n): values above the last full cycle are rejected, never folded. */
+  below(n) {
+    const limit = WORD - (WORD % n);
+    let value = this.next();
+    while (value >= limit) value = this.next();
+    return value % n;
+  }
+
+  between(low, high) {
+    if (Number.isInteger(low) && Number.isInteger(high)) return low + this.below(high - low + 1);
+    return Math.round((low + (this.next() / WORD) * (high - low)) * 100) / 100;
+  }
+
+  shuffle(items) {
+    for (let index = items.length - 1; index > 0; index -= 1) {
+      const other = this.below(index + 1);
+      [items[index], items[other]] = [items[other], items[index]];
+    }
+    return items;
+  }
+}
+
+/** Largest-remainder quotas: the counts add up to n exactly and follow the shares. */
+function quotas(shares, n) {
+  const exact = shares.map((share) => share * n);
+  const counts = exact.map((value) => Math.floor(value));
+  let left = n - counts.reduce((sum, count) => sum + count, 0);
+  const order = exact
+    .map((value, index) => ({ index, remainder: value - Math.floor(value) }))
+    .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+  for (const { index } of order) {
+    if (left === 0) break;
+    counts[index] += 1;
+    left -= 1;
+  }
+  return counts;
+}
+
+function unitId(prefix, position, n) {
+  return prefix + String(position).padStart(Math.max(3, String(n).length), '0');
+}
+
+function dealCards(profile, n, seed, idPrefix) {
+  const dealer = new Dealer(seed);
+  const slots = profile.dimensions.map((dimension) => {
+    const counts = quotas(
+      dimension.values.map((entry) => entry.share),
+      n
+    );
+    const column = [];
+    counts.forEach((count, index) => {
+      for (let k = 0; k < count; k += 1) column.push(index);
+    });
+    return dealer.shuffle(column);
+  });
+  const cards = [];
+  for (let position = 0; position < n; position += 1) {
+    const card = { id: unitId(idPrefix, position + 1, n) };
+    profile.dimensions.forEach((dimension, index) => {
+      const entry = dimension.values[slots[index][position]];
+      card[dimension.name] = entry.value;
+      // A note is a field of the whole dimension, so every card carries it, empty or not.
+      if (dimension.values.some((value) => value.note !== null))
+        card[dimension.name + '_note'] = entry.note ?? '';
+      for (const [name, [low, high]] of Object.entries(entry.ranges))
+        card[name] = dealer.between(low, high);
+    });
+    for (const [name, [low, high]] of Object.entries(profile.ranges))
+      card[name] = dealer.between(low, high);
+    for (const [name, pool] of Object.entries(profile.pools))
+      card[name] = pool[dealer.below(pool.length)];
+    cards.push(card);
+  }
+  return cards;
+}
+
+function listCards(units, idPrefix) {
+  const cards = units.map((unit, index) => ({
+    ...unit,
+    id: unit.id ?? unitId(idPrefix, index + 1, units.length),
+  }));
+  // Answer files are named by id, and some file systems fold case.
+  if (new Set(cards.map((card) => card.id.toLowerCase())).size !== cards.length)
+    throw new Error('Swarm: jury unit ids must be distinct once dealt, whatever their case.');
+  return cards;
+}
+
+module.exports = { Dealer, quotas, unitId, dealCards, listCards };

package/tools/cli/lib/swarm-defaults.js

@@ -0,0 +1,6 @@
+/** The swarm block bmad-plus install writes; an absent block in a project means these values. */
+'use strict';
+
+const SWARM_DEFAULTS = Object.freeze({ budget: 26, wave: 10, media_credits: 'ask' });
+
+module.exports = { SWARM_DEFAULTS };

package/tools/cli/lib/swarm-tally.js

@@ -0,0 +1,195 @@
+/** Counts valid answers by group; quotes stay verbatim and the disclosure comes first. */
+'use strict';
+
+const round = (value) => Math.round(value * 10000) / 10000;
+
+function stats(values) {
+  if (!values.length) return { count: 0, median: null, mean: null, min: null, max: null };
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = sorted.length >> 1;
+  const median = sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+  return {
+    count: sorted.length,
+    median: round(median),
+    mean: round(sorted.reduce((sum, value) => sum + value, 0) / sorted.length),
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+  };
+}
+
+function rateOf(rows, field) {
+  const of = rows.length;
+  const yes = rows.filter(({ answer }) => answer[field] === true).length;
+  return { yes, of, rate: of ? round(yes / of) : null };
+}
+
+function countsOf(rows, field, values) {
+  const counts = Object.fromEntries(values.map((value) => [value, 0]));
+  for (const { answer } of rows) if (Object.hasOwn(answer, field)) counts[answer[field]] += 1;
+  return counts;
+}
+
+function quotesOf(rows, field, keep) {
+  return rows
+    .filter(({ answer }) => typeof answer[field] === 'string' && answer[field].trim())
+    .slice(0, keep)
+    .map(({ card, answer }) => ({ unit: card.id, text: answer[field] }));
+}
+
+function numbersOf(rows, field) {
+  return stats(
+    rows.map(({ answer }) => answer[field]).filter((value) => typeof value === 'number')
+  );
+}
+
+/**
+ * @param rows valid answers in unit order: [{ card, answer }]
+ * @param skipped units without a valid answer: [{ unit, reason }]
+ */
+function tally({ run, definition, cards, rows, skipped }) {
+  const { groupBy } = definition.tally;
+  const groupValues = Object.fromEntries(
+    groupBy.map((field) => [field, [...new Set(cards.map((card) => String(card[field])))]])
+  );
+  const partition = (compute) => ({
+    all: compute(rows),
+    groups: Object.fromEntries(
+      groupBy.map((field) => [
+        field,
+        Object.fromEntries(
+          groupValues[field].map((value) => [
+            value,
+            compute(rows.filter(({ card }) => String(card[field]) === value)),
+          ])
+        ),
+      ])
+    ),
+  });
+  const { rate, counts, quotes, numbers } = definition.tally;
+  return {
+    schemaVersion: 1,
+    run: run.id,
+    definition: definition.id,
+    kind: definition.kind,
+    title: definition.title,
+    disclosure: definition.disclosure,
+    units: { total: cards.length, valid: rows.length, skipped },
+    groupBy,
+    rate: rate ? { field: rate, ...partition((set) => rateOf(set, rate)) } : null,
+    counts: Object.fromEntries(
+      counts.map((field) => [
+        field,
+        partition((set) => countsOf(set, field, definition.answer.fields[field].values)),
+      ])
+    ),
+    quotes: Object.fromEntries(
+      Object.entries(quotes).map(([field, keep]) => [
+        field,
+        { keep, ...partition((set) => quotesOf(set, field, keep)) },
+      ])
+    ),
+    numbers: Object.fromEntries(
+      numbers.map((field) => [field, partition((set) => numbersOf(set, field))])
+    ),
+  };
+}
+
+const percent = (rate) => (rate === null ? 'n/a' : (rate * 100).toFixed(1) + '%');
+const cell = (value) => (value === null ? 'n/a' : String(value));
+
+function sections(section, render) {
+  const lines = render('all', section.all);
+  for (const [field, values] of Object.entries(section.groups))
+    for (const [value, subset] of Object.entries(values))
+      lines.push(...render(field + ' = ' + value, subset));
+  return lines;
+}
+
+function renderTally(result) {
+  const lines = [
+    '> ' + result.disclosure,
+    '',
+    '# ' + result.title + ' (run ' + result.run + ')',
+    '',
+  ];
+  const skipped = result.units.skipped;
+  lines.push(
+    result.units.valid +
+      ' of ' +
+      result.units.total +
+      ' units gave a valid answer; ' +
+      skipped.length +
+      ' skipped' +
+      (skipped.length
+        ? ': ' + skipped.map((entry) => entry.unit + ' (' + entry.reason + ')').join(', ')
+        : '') +
+      '.'
+  );
+  if (result.rate) {
+    lines.push(
+      '',
+      '## Rate: ' + result.rate.field,
+      '',
+      '| group | yes | of | rate |',
+      '|---|---|---|---|'
+    );
+    lines.push(
+      ...sections(result.rate, (name, value) => [
+        '| ' + name + ' | ' + value.yes + ' | ' + value.of + ' | ' + percent(value.rate) + ' |',
+      ])
+    );
+  }
+  for (const [field, section] of Object.entries(result.counts)) {
+    const values = Object.keys(section.all);
+    lines.push(
+      '',
+      '## Counts: ' + field,
+      '',
+      '| group | ' + values.join(' | ') + ' |',
+      '|---|' + values.map(() => '---|').join('')
+    );
+    lines.push(
+      ...sections(section, (name, value) => [
+        '| ' + name + ' | ' + values.map((key) => value[key]).join(' | ') + ' |',
+      ])
+    );
+  }
+  for (const [field, section] of Object.entries(result.quotes)) {
+    lines.push('', '## Quotes: ' + field + ' (up to ' + section.keep + ' per group, verbatim)');
+    lines.push(
+      ...sections(section, (name, value) => [
+        '',
+        '**' + name + '**',
+        ...(value.length
+          ? value.map((quote) => '- ' + quote.unit + ': ' + JSON.stringify(quote.text))
+          : ['- (no quote)']),
+      ])
+    );
+  }
+  for (const [field, section] of Object.entries(result.numbers)) {
+    lines.push(
+      '',
+      '## Numbers: ' + field,
+      '',
+      '| group | count | median | mean | min | max |',
+      '|---|---|---|---|---|---|'
+    );
+    lines.push(
+      ...sections(section, (name, value) => [
+        '| ' +
+          [
+            name,
+            value.count,
+            cell(value.median),
+            cell(value.mean),
+            cell(value.min),
+            cell(value.max),
+          ].join(' | ') +
+          ' |',
+      ])
+    );
+  }
+  return lines.join('\n') + '\n';
+}
+
+module.exports = { tally, renderTally, stats };