bmad-plus 0.12.0 → 0.12.2

package/tools/build/check-counts.js

@@ -0,0 +1,628 @@
+#!/usr/bin/env node
+/**
+ * BMAD+ Build — hand-typed count drift checker (audit NS-01 / ARCH-04 / DOC-06)
+ *
+ * Every "N agents" / "N workflows" / "N packs" claim in a shipped surface is a
+ * fact that MUST be derivable from registry.yaml (+ the files on disk). This
+ * script derives the truth, scans the tracked truth surfaces for hand-typed
+ * numbers that contradict it, and exits non-zero listing every drift.
+ *
+ * Why this exists: `- **Shield** (GRC) — 38 compliance agents` shipped into
+ * every generated user config for months. 38 was not a typo — it was
+ * 27 agents + 11 workflows summed into one dimension. A definition error
+ * re-drifts on every pack change, so it needs a gate, not a one-off correction.
+ *
+ * DIMENSIONS ARE THE POINT. 38 is a legitimate number in this repo (Dev Studio
+ * has 38 workflows); it is only wrong when attached to `agents`. Every rule
+ * below therefore checks a (subject, dimension) pair, never a bare integer.
+ *
+ * Usage:
+ *   node tools/build/check-counts.js            # verify (exit 1 on drift)
+ *   node tools/build/check-counts.js --print    # print the derived truth and exit 0
+ *
+ * The test-count claim ("N tests") is the one number here that cannot be
+ * derived statically — it requires running Jest. So it is gated by an env var:
+ *
+ *   BMAD_PLUS_TEST_COUNT unset/empty  → test claims are listed as NOT GATED and
+ *                                       the run says OK (PARTIAL). Never fails:
+ *                                       a local `node tools/build/check-counts.js`
+ *                                       must not need a full Jest run first.
+ *   BMAD_PLUS_TEST_COUNT=<integer>    → every "N tests" claim must equal it.
+ *                                       CI arms this with the Jest-reported
+ *                                       total, which is the only run that
+ *                                       proves the README's test number.
+ *   BMAD_PLUS_TEST_COUNT=<garbage>    → exit 1. A misspelled total must not
+ *                                       masquerade as coverage.
+ *
+ * Author: Laurent Rochetta
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { loadRegistry, DEFAULT_REGISTRY_PATH } = require('./generate');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+
+/**
+ * Files whose numeric claims describe the CURRENT product. Anything not listed
+ * is out of scope by construction, so the gate can never be "fixed" by quietly
+ * moving a lie into an unscanned file — adding a surface is an explicit edit.
+ */
+const TRUTH_SURFACES = [
+  'README.md',
+  'README-DIST.md',
+  'readme-international/README.fr.md',
+  'readme-international/README.es.md',
+  'readme-international/README.de.md',
+  'src/bmad-plus/module.yaml',
+  'src/bmad-plus/packs/pack-shield/README.md',
+  'src/bmad-plus/packs/pack-shield/SKILL.md',
+  'src/bmad-plus/packs/pack-shield/shield-orchestrator.md',
+  'tools/cli/lib/ide-config.js',
+  'tools/build/adapters.config.js',
+];
+
+/**
+ * NOT scanned, deliberately:
+ *   - CHANGELOG.md, audit/**, docs/research/** — historical records. They
+ *     legitimately quote past and *wrong* numbers ("the advertised 38 agents")
+ *     verbatim; gating them would force rewriting history to satisfy a linter.
+ *   - .agents/** — gitignored local install output, not a source.
+ *   - upstream/** — third-party clone.
+ * Release-history table rows inside a scanned README are skipped for the same
+ * reason (see isFrozenHistoryRow): v0.6.0 really did ship 30 workflows and
+ * v0.12.0 really did ship 333 tests. Those are true statements about the past.
+ */
+const HISTORY_ROW_RE = /^\|\s*\*\*\d+\.\d+\.\d+\*\*\s*\|/;
+
+function isFrozenHistoryRow(line) {
+  return HISTORY_ROW_RE.test(line);
+}
+
+/* ── Derivation ─────────────────────────────────────────────────────────── */
+
+/** Sum of list lengths for a given key across a pack's categories. */
+function sumCategories(pack, key) {
+  if (!Array.isArray(pack.categories)) return 0;
+  return pack.categories.reduce((n, c) => n + (Array.isArray(c[key]) ? c[key].length : 0), 0);
+}
+
+/** Count *.md agent files on disk for a packaged pack's categories/ tree. */
+function countAgentFilesOnDisk(packDir) {
+  const root = path.join(REPO_ROOT, 'src', 'bmad-plus', 'packs', packDir, 'categories');
+  if (!fs.existsSync(root)) return null;
+  let n = 0;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    // `workflows/` sits under categories/ but is NOT an agent category — it is
+    // the directory whose 11 files got summed into the agent total to make 38.
+    if (!entry.isDirectory() || entry.name === 'workflows') continue;
+    n += fs.readdirSync(path.join(root, entry.name)).filter((f) => f.endsWith('.md')).length;
+  }
+  return n;
+}
+
+/** Count *.md workflow files on disk for a packaged pack. */
+function countWorkflowFilesOnDisk(packDir) {
+  const dir = path.join(REPO_ROOT, 'src', 'bmad-plus', 'packs', packDir, 'categories', 'workflows');
+  if (!fs.existsSync(dir)) return null;
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+}
+
+/** Installer languages, read from the CLI's own i18n module (its SSOT). */
+function deriveLanguages() {
+  const { LANGUAGES } = require(path.join(REPO_ROOT, 'tools', 'cli', 'i18n.js'));
+  return Object.keys(LANGUAGES);
+}
+
+/**
+ * Derive every count this gate enforces, from registry.yaml + the filesystem.
+ * Cross-checks the registry against the files on disk: if they disagree, the
+ * derivation itself is untrustworthy and that is reported as a drift.
+ */
+function deriveTruth(registryPath = DEFAULT_REGISTRY_PATH) {
+  const registry = loadRegistry(registryPath);
+  const packs = registry.packs;
+  const shield = packs.shield;
+  const devStudio = packs['dev-studio'];
+
+  const shieldAgents = sumCategories(shield, 'agents');
+  const shieldWorkflows = (shield.workflows || []).length;
+  const shieldCategories = (shield.categories || []).length;
+  const shieldFrameworks = (shield.compliance_tags || []).length;
+
+  const installerAgents = Object.values(packs).reduce((n, p) => n + p.agents.length, 0);
+  const devStudioSubAgents = (devStudio.sub_agents || []).length;
+  const devStudioWorkflows =
+    (devStudio.workflows || []).length + sumCategories(devStudio, 'workflows');
+
+  const mismatches = [];
+  const onDiskAgents = countAgentFilesOnDisk(shield.pack_dir);
+  const onDiskWorkflows = countWorkflowFilesOnDisk(shield.pack_dir);
+  if (onDiskAgents !== null && onDiskAgents !== shieldAgents) {
+    mismatches.push(
+      `registry.yaml declares ${shieldAgents} shield category agents but ${onDiskAgents} agent files exist on disk`
+    );
+  }
+  if (onDiskWorkflows !== null && onDiskWorkflows !== shieldWorkflows) {
+    mismatches.push(
+      `registry.yaml declares ${shieldWorkflows} shield workflows but ${onDiskWorkflows} workflow files exist on disk`
+    );
+  }
+
+  // Every distinct agent a user can talk to: the installer entry points plus
+  // the specialists the two packaged orchestrators route to.
+  const totalAgents = installerAgents + shieldAgents + devStudioSubAgents;
+  // Sizes of the declared per-category agent groups ("5 agents", "6 agents"…),
+  // which are legitimate claims wherever a category is described.
+  const perCategorySizes = new Set((shield.categories || []).map((c) => (c.agents || []).length));
+  // Sizes of the per-pack installer rosters ("3 agents (Scout, Chief, Judge)").
+  const perPackInstallerSizes = new Set(Object.values(packs).map((p) => p.agents.length));
+
+  return {
+    packCount: Object.keys(packs).length,
+    installerAgents,
+    shieldAgents,
+    shieldWorkflows,
+    shieldCategories,
+    shieldFrameworks,
+    devStudioSubAgents,
+    devStudioWorkflows,
+    totalAgents,
+    languages: deriveLanguages(),
+    perCategorySizes,
+    // The COMPLETE vocabulary of numbers that may legitimately precede "agents"
+    // anywhere in the product's own copy. Default-deny: a value outside this set
+    // is a number nobody can derive, so it is drift by definition. This is what
+    // gates the 47s — "47 agents" stays green only while 47 is still derivable,
+    // and every occurrence turns red the day the roster changes.
+    agentCounts: new Set([
+      installerAgents,
+      shieldAgents,
+      devStudioSubAgents,
+      totalAgents,
+      ...perCategorySizes,
+      ...perPackInstallerSizes,
+    ]),
+    // Same idea for the workflow dimension. Anchored lines get graded against
+    // the one pack they name; unanchored ones must still be *some* real total.
+    workflowCounts: new Set([shieldWorkflows, devStudioWorkflows]),
+    derivationMismatches: mismatches,
+  };
+}
+
+/* ── Rules ──────────────────────────────────────────────────────────────── */
+
+const SHIELD_ANCHOR =
+  /shield|\bGRC\b|compliance[- ]agent|agents? de conformité|agentes de cumplimiento|Compliance-Agenten/i;
+const DEV_STUDIO_ANCHOR = /dev[- ]studio/i;
+
+/**
+ * Lines whose agent count describes the UPSTREAM project, not this one:
+ * "BMAD-METHOD ... 9 specialized agents" is a true statement about a different
+ * product, so the roster rule must not grade it. Scoped to the agent dimension
+ * only — a line may name BMAD-METHOD and still make a claim of its own
+ * ("Fork of BMAD-METHOD — ... CLI installer in 10 languages"), and that claim
+ * stays gated.
+ */
+const FOREIGN_SUBJECT_ANCHOR = /BMAD-METHOD/i;
+
+/**
+ * `| BMAD-METHOD | BMAD+ |` opens the upstream comparison table, whose rows
+ * carry a foreign count in the left column and ours in the right ("| 9
+ * specialized agents | **47 agents** across 9 packs |") without repeating the
+ * marker. The rows are recognised positionally, like isFrozenHistoryRow.
+ */
+const FOREIGN_TABLE_HEADER_RE = /^\s*\|\s*BMAD-METHOD\s*\|/i;
+
+/* A claim is `<number> <qualifiers…> <dimension noun>`. The three constants
+ * below define what may sit between the number and the noun; every rule is
+ * built from them by claimRe(), so a fix to the CLASS lands on every dimension
+ * at once instead of on one hand-listed adjective. */
+
+/**
+ * What may SEPARATE the pieces of a claim: whitespace and markdown
+ * emphasis/code markers — "**38** agents", "`38` agents", "**38 agents**".
+ * `\s` already covers U+00A0/U+202F, which the French copy uses before
+ * punctuation.
+ *
+ * `-` and `_` are deliberately NOT separators. This repo is full of agent
+ * IDENTIFIERS — `iso27001-agent`, `nist-800-53-agent`, `section508-agent`,
+ * `iso42001-agent` — and a hyphen-tolerant gap would read every one of them as
+ * a claim of "27001 agents". A qualifier may still *contain* a hyphen
+ * ("multi-role", "GRC-Compliance-"); it just may not START with one.
+ */
+const GAP = '[\\s*`]*';
+
+/** One qualifier word: hyphenated and accented forms included. */
+const WORD = '[A-Za-zÀ-ÖØ-öø-ÿ][A-Za-zÀ-ÖØ-öø-ÿ-]*';
+
+/**
+ * How many qualifiers a claim may carry. The bound is load-bearing: it is what
+ * stops a match from walking across a whole sentence and inventing a claim
+ * ("5 reasons why you should hire agents").
+ */
+const MAX_QUALIFIERS = 4;
+
+/**
+ * Words that TERMINATE a qualifier run instead of decorating it:
+ *  - dimension nouns — the number belongs to THAT dimension, not to the one
+ *    further right. "11 workflow agents" is a *workflow* count (graded by the
+ *    workflows rule), and summing it into the agent dimension is precisely how
+ *    27 + 11 became 38.
+ *  - connectives and articles — without them a single match could span two
+ *    independent claims ("9 packs and 27 agents").
+ */
+const NOT_A_QUALIFIER = new Set(
+  `agent agents agente agentes agenten workflow workflows pack packs test tests
+   category categories catégorie catégories categoría categorías kategorie kategorien
+   framework frameworks language languages langue langues idioma idiomas sprache sprachen
+   skill skills phase phases level levels
+   and or plus with across of in on for to the a an
+   et ou des les la le du dans sur pour avec y con de en und oder mit für`.split(/\s+/)
+);
+
+/**
+ * Quantity approximators sitting in front of the number. "over 47 agents" is
+ * the same marketing hedge as "47+ agents" and must die the same way — the
+ * roster is an exact, derivable integer. Deliberately excludes "about" and
+ * "around", which read as "on the subject of" far too often to be safe.
+ */
+const APPROX_PREFIX_RE = new RegExp(
+  `(?:over|more than|nearly|almost|approximately|approx\\.?|up to|~|≈` +
+    `|plus de|environ|más de|mehr als)${GAP}$`,
+  'i'
+);
+
+/**
+ * Build a /g/ claim regex for one dimension's noun alternatives.
+ *
+ * The leading `\b` is load-bearing: it forbids the number from starting inside
+ * a word. Without it a qualifier run happily bridges the stray digit in "E2E
+ * tests" into a claim of "2 tests", and reads `section508-agent` as a count.
+ * A claim's number is always a whole token.
+ */
+function claimRe(noun) {
+  return new RegExp(
+    `\\b(\\d+)${GAP}(\\+)?${GAP}((?:${WORD}${GAP}){0,${MAX_QUALIFIERS}}?)(?:${noun})\\b`,
+    'gi'
+  );
+}
+
+const AGENTS_RE = claimRe('agents?|agentes|agenten');
+const WORKFLOWS_RE = claimRe('workflows?');
+const CATEGORIES_RE = claimRe('categories|catégories|categorías|Kategorien');
+const PACKS_RE = claimRe('packs?');
+const TESTS_RE = claimRe('tests?');
+const FRAMEWORKS_RE = claimRe('frameworks?');
+const LANGUAGES_RE = claimRe('languages?|langues?|idiomas?|Sprachen?');
+
+/**
+ * Collect every claim `re` finds on `line`.
+ * `re` must be a /g/ regex; it is reset before use so it is safe to reuse.
+ * Matches whose qualifier run crosses a NOT_A_QUALIFIER word are dropped: the
+ * number belongs to a different dimension (or a different sentence).
+ * @returns {{value:number, plus:boolean, approx:boolean, text:string}[]}
+ */
+function matchAll(re, line) {
+  re.lastIndex = 0;
+  const out = [];
+  let m;
+  while ((m = re.exec(line)) !== null) {
+    const qualifiers = (m[3] || '').split(/[^A-Za-zÀ-ÖØ-öø-ÿ]+/).filter(Boolean);
+    if (qualifiers.some((w) => NOT_A_QUALIFIER.has(w.toLowerCase()))) continue;
+    out.push({
+      value: Number(m[1]),
+      plus: m[2] === '+',
+      approx: APPROX_PREFIX_RE.test(line.slice(0, m.index)),
+      // Markers are dropped from the echoed text so a bolded claim reports as
+      // `38 compliance agents`, not `38** compliance agents`. file:line locates it.
+      text: m[0].replace(/[*`]+/g, ' ').replace(/\s+/g, ' ').trim(),
+    });
+  }
+  return out;
+}
+
+/**
+ * Check one line against the derived truth.
+ * @param {string} line
+ * @param {object} truth  output of deriveTruth()
+ * @param {{foreignSubject?: boolean}} [opts]  foreignSubject suppresses the
+ *   product-roster rule only (the line counts a DIFFERENT product's agents).
+ * @returns {string[]} human-readable drift descriptions (empty when the line is fine)
+ */
+function checkLine(line, truth, { foreignSubject = false } = {}) {
+  const problems = [];
+  const shieldLine = SHIELD_ANCHOR.test(line);
+  const devStudioLine = DEV_STUDIO_ANCHOR.test(line);
+
+  if (shieldLine) {
+    for (const { value, text } of matchAll(AGENTS_RE, line)) {
+      // Per-category headings ("5 agents") are legitimate; only reject the
+      // values that misstate the pack-wide total. Anything that is not a
+      // declared per-category size and not 27 is a conflation.
+      if (value !== truth.shieldAgents && !isPerCategorySize(value, truth)) {
+        problems.push(
+          `"${text.trim()}" — Shield has ${truth.shieldAgents} compliance agents` +
+            (value === truth.shieldAgents + truth.shieldWorkflows
+              ? ` (${truth.shieldAgents} agents + ${truth.shieldWorkflows} workflows conflated into one "agents" figure)`
+              : '')
+        );
+      }
+    }
+    for (const { value, text } of matchAll(WORKFLOWS_RE, line)) {
+      if (value !== truth.shieldWorkflows) {
+        problems.push(`"${text.trim()}" — Shield has ${truth.shieldWorkflows} workflows`);
+      }
+    }
+    for (const { value, text } of matchAll(CATEGORIES_RE, line)) {
+      if (value !== truth.shieldCategories) {
+        problems.push(
+          `"${text.trim()}" — Shield has ${truth.shieldCategories} agent categories` +
+            (value === truth.shieldCategories + 1
+              ? ' (the workflows/ directory is not a category)'
+              : '')
+        );
+      }
+    }
+  }
+
+  if (devStudioLine) {
+    for (const { value, text } of matchAll(WORKFLOWS_RE, line)) {
+      if (value !== truth.devStudioWorkflows) {
+        problems.push(`"${text.trim()}" — Dev Studio has ${truth.devStudioWorkflows} workflows`);
+      }
+    }
+  }
+
+  // A "+" (or an "over"/"more than") on an agent total is always a marketing
+  // approximation: the roster is an exact, derivable integer. This is the rule
+  // that kills "56+ agents" — and "over 56 agents", which is the same hedge
+  // wearing a different hat.
+  for (const { plus, approx, text } of matchAll(AGENTS_RE, line)) {
+    if (!plus && !approx) continue;
+    problems.push(
+      `"${text.trim()}" — agent totals are exact and derivable, not approximate` +
+        ` (the roster is ${truth.totalAgents}; "56+" came from Dev Studio's *skills* count)`
+    );
+  }
+
+  // The roster rule. Shield-anchored lines are graded by the stricter rule
+  // above; everywhere else, any number attached to "agents" must be one this
+  // repo can actually derive. Default-deny is the point: it is what makes the
+  // tracked "47 agents" claims fail the day the roster stops being 47, and what
+  // catches a number ("999") that corresponds to nothing at all.
+  if (!shieldLine && !foreignSubject) {
+    for (const { value, plus, approx, text } of matchAll(AGENTS_RE, line)) {
+      if (plus || approx) continue; // already reported as an approximation
+      if (!truth.agentCounts.has(value)) {
+        problems.push(
+          `"${text.trim()}" — no derived agent count equals ${value} (roster: ` +
+            `${truth.totalAgents} total = ${truth.installerAgents} installer + ` +
+            `${truth.shieldAgents} shield + ${truth.devStudioSubAgents} dev-studio sub-agents)`
+        );
+      }
+    }
+  }
+
+  // Same default-deny for the workflow dimension. Anchored lines are graded
+  // against the one pack they name; an unanchored line must still quote a real
+  // total (this is what catches a pack description whose own name sits on the
+  // line above it).
+  if (!shieldLine && !devStudioLine) {
+    for (const { value, text } of matchAll(WORKFLOWS_RE, line)) {
+      if (!truth.workflowCounts.has(value)) {
+        problems.push(
+          `"${text.trim()}" — no pack has ${value} workflows (Shield ${truth.shieldWorkflows},` +
+            ` Dev Studio ${truth.devStudioWorkflows})`
+        );
+      }
+    }
+  }
+
+  // Packs and languages are exact derivable integers, so — like the agent
+  // roster — they get no hedge. Modelling each hedge's arithmetic instead would
+  // mean conceding that "10+ languages" (>= 10, true) and "more than 10
+  // languages" (> 10, false) are different claims about the same 10; the honest
+  // rule is that a number you can derive is simply stated.
+  for (const { value, plus, approx, text } of matchAll(PACKS_RE, line)) {
+    if (plus || approx) {
+      problems.push(
+        `"${text.trim()}" — the pack count is exact and derivable, not approximate` +
+          ` (the registry declares ${truth.packCount})`
+      );
+    } else if (value !== truth.packCount) {
+      problems.push(`"${text.trim()}" — the registry declares ${truth.packCount} packs`);
+    }
+  }
+
+  for (const { value, plus, approx, text } of matchAll(LANGUAGES_RE, line)) {
+    if (plus || approx) {
+      problems.push(
+        `"${text.trim()}" — the language count is exact and derivable, not approximate` +
+          ` (tools/cli/i18n.js declares ${truth.languages.length})`
+      );
+    } else if (value !== truth.languages.length) {
+      problems.push(
+        `"${text.trim()}" — tools/cli/i18n.js declares ${truth.languages.length} languages` +
+          ` (${truth.languages.join(', ')})`
+      );
+    }
+  }
+
+  // Frameworks are the one dimension gated as a LOWER BOUND. Unlike the rosters
+  // above, the exact claims are per-category groupings ("AI Governance (3
+  // frameworks)") that are NOT derivable — registry categories carry agents,
+  // not compliance_tags — so an equality rule would fire on true statements.
+  // The defect that remains checkable is the overclaim: promising more
+  // frameworks than the pack actually tags. "25+" stays honest while 26 exist.
+  for (const { value, text } of matchAll(FRAMEWORKS_RE, line)) {
+    if (value > truth.shieldFrameworks) {
+      problems.push(
+        `"${text.trim()}" — Shield tags ${truth.shieldFrameworks} compliance frameworks`
+      );
+    }
+  }
+
+  return problems;
+}
+
+/** Per-category agent-group sizes that may legitimately appear near "agents". */
+function isPerCategorySize(value, truth) {
+  return truth.perCategorySizes.has(value);
+}
+
+/* ── Scan ───────────────────────────────────────────────────────────────── */
+
+/** Files tracked by git, restricted to the declared truth surfaces. */
+function trackedTruthSurfaces() {
+  let tracked;
+  try {
+    tracked = new Set(
+      execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean)
+    );
+  } catch {
+    tracked = null; // not a git checkout (e.g. an npm tarball) → scan what exists
+  }
+  return TRUTH_SURFACES.filter((f) => {
+    if (tracked && !tracked.has(f)) return false;
+    return fs.existsSync(path.join(REPO_ROOT, f));
+  });
+}
+
+/**
+ * Scan the truth surfaces.
+ * @returns {{ ok: boolean, drifts: string[], unverified: string[], truth: object }}
+ */
+function check({ registryPath = DEFAULT_REGISTRY_PATH, testCount = null } = {}) {
+  const truth = deriveTruth(registryPath);
+  const drifts = [...truth.derivationMismatches];
+  const unverified = [];
+
+  for (const file of trackedTruthSurfaces()) {
+    const lines = fs.readFileSync(path.join(REPO_ROOT, file), 'utf8').split(/\r?\n/);
+    let inForeignTable = false;
+    lines.forEach((line, i) => {
+      if (isFrozenHistoryRow(line)) return;
+      if (FOREIGN_TABLE_HEADER_RE.test(line)) {
+        inForeignTable = true;
+        return;
+      }
+      if (inForeignTable && !line.trimStart().startsWith('|')) inForeignTable = false;
+
+      const foreignSubject = inForeignTable || FOREIGN_SUBJECT_ANCHOR.test(line);
+      for (const problem of checkLine(line, truth, { foreignSubject })) {
+        drifts.push(`${file}:${i + 1}: ${problem}`);
+      }
+      for (const { value, text } of matchAll(TESTS_RE, line)) {
+        if (testCount === null) {
+          unverified.push(`${file}:${i + 1}: "${text.trim()}"`);
+        } else if (value !== testCount) {
+          drifts.push(`${file}:${i + 1}: "${text.trim()}" — the suite reports ${testCount} tests`);
+        }
+      }
+    });
+  }
+
+  return { ok: drifts.length === 0, drifts, unverified, truth };
+}
+
+/**
+ * Read the test-count rule's arming variable.
+ * Unset/empty means "not armed" (never a failure). Anything else must be a
+ * plain non-negative integer: `Number(" ")` is 0 and `Number("-1")` is an
+ * integer, so a bare Number()+isInteger check would silently gate against a
+ * garbage total.
+ * @returns {{armed: boolean, testCount: number|null, error: string|null}}
+ */
+function readTestCountEnv(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    return { armed: false, testCount: null, error: null };
+  }
+  if (!/^\d+$/.test(raw.trim())) {
+    return {
+      armed: true,
+      testCount: null,
+      error: `BMAD_PLUS_TEST_COUNT must be a non-negative integer (got "${raw}")`,
+    };
+  }
+  return { armed: true, testCount: Number(raw.trim()), error: null };
+}
+
+/* ── CLI ────────────────────────────────────────────────────────────────── */
+
+function main(argv) {
+  const args = argv.slice(2);
+  const { armed, testCount, error } = readTestCountEnv(process.env.BMAD_PLUS_TEST_COUNT);
+  if (error) {
+    console.error(error);
+    return 1;
+  }
+
+  const result = check({ testCount });
+
+  if (args.includes('--print')) {
+    const { derivationMismatches, ...facts } = result.truth;
+    void derivationMismatches;
+    const asArray = (_k, v) => (v instanceof Set ? [...v].sort((a, b) => a - b) : v);
+    console.log(JSON.stringify(facts, asArray, 2));
+    return 0;
+  }
+
+  const partial = result.unverified.length > 0;
+
+  if (result.ok) {
+    console.log(
+      `${partial ? 'OK (PARTIAL)' : 'OK'} — no count drift. Derived from registry.yaml + files on disk: ` +
+        `${result.truth.shieldAgents} shield agents + ${result.truth.shieldWorkflows} shield workflows, ` +
+        `${result.truth.devStudioWorkflows} dev-studio workflows, ${result.truth.totalAgents} agents total, ` +
+        `${result.truth.packCount} packs, ${result.truth.languages.length} languages.`
+    );
+  } else {
+    console.error('COUNT DRIFT DETECTED — hand-typed numbers contradict registry.yaml:');
+    for (const d of result.drifts) console.error(`  - ${d}`);
+    console.error(
+      'Fix the claim (or registry.yaml if the registry is what is wrong), then re-run:'
+    );
+    console.error('  node tools/build/check-counts.js');
+  }
+
+  // Reported on BOTH paths, on purpose. A green run with the variable unset
+  // must not read as full coverage — and a red run must not bury the fact that
+  // the test claims went unchecked on top of whatever else broke.
+  if (partial) {
+    console.warn('');
+    console.warn(
+      `!! NOT GATED — ${result.unverified.length} test-count claim(s) were NOT checked ` +
+        `(BMAD_PLUS_TEST_COUNT unset):`
+    );
+    for (const u of result.unverified) console.warn(`     ${u}`);
+    console.warn('   This run does not cover those numbers. To gate them, pass the');
+    console.warn('   Jest-reported total:');
+    console.warn('     BMAD_PLUS_TEST_COUNT=<total> node tools/build/check-counts.js');
+  } else if (armed) {
+    console.log(`Test-count claims gated against BMAD_PLUS_TEST_COUNT=${testCount}.`);
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv);
+}
+
+module.exports = {
+  REPO_ROOT,
+  TRUTH_SURFACES,
+  deriveTruth,
+  checkLine,
+  isFrozenHistoryRow,
+  readTestCountEnv,
+  trackedTruthSurfaces,
+  check,
+  main,
+};

package/tools/build/generated-adapters/.codex/AGENTS.md

@@ -100,7 +100,7 @@ Agents MUST follow these behavioral principles:
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.12.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.12.2 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/.cursor/rules/bmad-plus.mdc

@@ -105,7 +105,7 @@ Agents MUST follow these behavioral principles:
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.12.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.12.2 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/.opencode/AGENTS.md

@@ -100,7 +100,7 @@ Agents MUST follow these behavioral principles:
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.12.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.12.2 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/AGENTS.md

@@ -98,7 +98,7 @@ Agents MUST follow these behavioral principles:
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.12.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.12.2 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):

package/tools/build/generated-adapters/CLAUDE.md

@@ -101,7 +101,7 @@ Agents MUST follow these behavioral principles:
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.12.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.12.2 (derived from BMAD-METHOD v6.6.0)
 - Models supported: claude, gpt, gemini, local (model-agnostic by contract)
 - Packs (9): Core, OSINT, Maker, Shield, SEO, Memory, Dev Studio, Backup, Animated
 - Installer agents (14 across all packs):