bmad-plus 0.16.0 → 0.17.0

package/src/bmad-plus/skills/bmad-plus-uat/templates/uat-release-gate.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Gate G3 — production waits for a human run that was read and classified.
+ *
+ * Resolves the recipe covering the version in package.json, then runs
+ * `bmad-plus uat gate` on it. Exit 0 only when the gate passes: a finished run,
+ * answering the current revision of the recipe, with every failure classified and
+ * every writing step confirmed read-only.
+ *
+ *   node scripts/uat-release-gate.mjs
+ *   node scripts/uat-release-gate.mjs --id myproduct-1.4.0
+ *   node scripts/uat-release-gate.mjs --cli node_modules/bmad-plus/tools/cli/bmad-plus-cli.js
+ *   BMAD_PLUS_CLI=/path/to/bmad-plus-cli.js node scripts/uat-release-gate.mjs
+ *
+ * Exit codes mirror the command: 0 passed · 1 failed · 2 awaiting a run ·
+ * 3 the run answered another revision · 4 the gate could not be run at all.
+ *
+ * The gate establishes that the run is complete, current and classified. It never
+ * establishes that the tester looked at the right place: that stays human-observed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+const root = path.resolve(option('project', process.cwd()));
+const directory = option('dir', '_bmad-output/uat');
+const specs = path.join(root, directory, 'specs');
+
+function resolveId() {
+  const explicit = option('id', null);
+  if (explicit) return explicit;
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) throw new Error(`no package.json in ${root}; pass --id <recipe>`);
+  const version = JSON.parse(fs.readFileSync(file, 'utf8')).version;
+  if (!fs.existsSync(specs)) throw new Error(`no recipe folder at ${specs}`);
+  const covering = fs
+    .readdirSync(specs)
+    .filter((name) => name.endsWith('.json'))
+    .filter((name) => {
+      try {
+        const spec = JSON.parse(fs.readFileSync(path.join(specs, name), 'utf8'));
+        return Array.isArray(spec.versions) && spec.versions.includes(version);
+      } catch {
+        return false;
+      }
+    });
+  if (covering.length !== 1) {
+    throw new Error(
+      covering.length
+        ? `${covering.length} recipes name ${version}; pass --id to choose one`
+        : `no recipe names ${version}; write it before deploying`
+    );
+  }
+  return covering[0].replace(/\.json$/, '');
+}
+
+/**
+ * The CLI's own entry point, run by this Node: an explicit one, or the copy
+ * installed in the project. Never a shell, never `npx` — a `.cmd` shim cannot be
+ * spawned without a shell on Windows, and a gate must not depend on a download.
+ */
+function command() {
+  const candidates = [
+    option('cli', null),
+    process.env.BMAD_PLUS_CLI,
+    path.join(root, 'node_modules', 'bmad-plus', 'tools', 'cli', 'bmad-plus-cli.js'),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    const resolved = path.resolve(root, candidate);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  throw new Error(
+    'no BMAD+ CLI to run the gate with. Install bmad-plus in this project ' +
+      '(npm install --save-dev bmad-plus) or set BMAD_PLUS_CLI to its bmad-plus-cli.js. ' +
+      'A missing gate is not a passing gate.'
+  );
+}
+
+try {
+  const id = resolveId();
+  const cli = command();
+  const child = spawnSync(
+    process.execPath,
+    [cli, 'uat', 'gate', id, '--directory', root, '--dir', directory, '--json'],
+    { encoding: 'utf8', timeout: 120000, windowsHide: true }
+  );
+
+  // The verdict is read from the gate's own answer, not guessed from an exit code:
+  // a CLI that never ran also exits non-zero, and that is a different problem.
+  let verdict = null;
+  try {
+    const parsed = JSON.parse(child.stdout);
+    if (parsed && typeof parsed.status === 'string') verdict = parsed;
+  } catch {
+    verdict = null;
+  }
+  if (!verdict) {
+    console.error(
+      `uat: the gate could not be run for ${id}` +
+        `${child.error ? ` (${child.error.message})` : ''}.\n` +
+        `${(child.stdout || '').trim()}${(child.stderr || '').trim()}\n` +
+        'Install the CLI in this project, or set BMAD_PLUS_CLI to its path. ' +
+        'A missing gate is not a passing gate.'
+    );
+    process.exit(4);
+  }
+
+  const explanation = {
+    passed: `${id}: human-observed, complete, current and triaged.`,
+    failed: `${id} did not pass its gate — production stays where it is.`,
+    awaiting: `${id} has no finished run yet — someone still has to play it.`,
+    stale: `${id} was answered on another revision of the recipe — replay the affected steps.`,
+  };
+  const code = { passed: 0, failed: 1, awaiting: 2, stale: 3 }[verdict.status] ?? 4;
+  const report = code === 0 ? console.log : console.error;
+  report(explanation[verdict.status] || `${id}: unexpected gate status "${verdict.status}".`);
+  for (const reason of verdict.reasons || []) report(`  - ${reason}`);
+  process.exit(code);
+} catch (error) {
+  console.error(`uat: ${error.message}`);
+  process.exit(4);
+}

package/src/bmad-plus/skills/bmad-plus-uat/templates/uat-spec-present.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Gate G1 — a version does not leave without saying what a person must check.
+ *
+ * Fails when no acceptance recipe covers the version in package.json. Copy this
+ * file into your project and run it wherever your other checks run: a pre-push
+ * hook, a test script, a CI step. It needs nothing but Node.
+ *
+ *   node scripts/uat-spec-present.mjs
+ *   node scripts/uat-spec-present.mjs --version 1.4.0 --dir _bmad-output/uat --json
+ *
+ * Exit 0 when a recipe covers the version, 1 otherwise. A reminder printed after
+ * a deployment protects nothing; this one runs before.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+const json = args.includes('--json');
+const root = path.resolve(option('project', process.cwd()));
+const directory = path.resolve(root, option('dir', '_bmad-output/uat'));
+
+function projectVersion() {
+  const explicit = option('version', null);
+  if (explicit) return explicit;
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(`no package.json in ${root}; pass --version <x.y.z>`);
+  }
+  const version = JSON.parse(fs.readFileSync(file, 'utf8')).version;
+  if (!version) throw new Error('package.json declares no version');
+  return version;
+}
+
+/** Recipes that name this version, whether they cover one version or a campaign. */
+function covering(version) {
+  const specs = path.join(directory, 'specs');
+  if (!fs.existsSync(specs)) return [];
+  return fs
+    .readdirSync(specs)
+    .filter((name) => name.endsWith('.json'))
+    .filter((name) => {
+      try {
+        const spec = JSON.parse(fs.readFileSync(path.join(specs, name), 'utf8'));
+        // A grouped recipe covers a version because it NAMES it, never because its
+        // file name suggests a range.
+        return Array.isArray(spec.versions) && spec.versions.includes(version);
+      } catch {
+        return false;
+      }
+    })
+    .map((name) => name.replace(/\.json$/, ''));
+}
+
+try {
+  const version = projectVersion();
+  const found = covering(version);
+  if (json) {
+    console.log(JSON.stringify({ version, directory, covering: found, ok: found.length > 0 }, null, 2));
+  } else if (found.length) {
+    console.log(`uat: ${version} is covered by ${found.join(', ')}`);
+  } else {
+    console.error(
+      `uat: no acceptance recipe covers ${version}.\n` +
+        `Write ${path.relative(root, path.join(directory, 'specs'))}/<product>-${version}.json before shipping,\n` +
+        `or add ${version} to the versions of a grouped recipe. Ask your agent: "write the recette for this delivery".`
+    );
+  }
+  process.exit(found.length ? 0 : 1);
+} catch (error) {
+  console.error(`uat: ${error.message}`);
+  process.exit(1);
+}

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

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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

@@ -118,7 +118,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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

@@ -111,7 +111,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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

@@ -114,7 +114,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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/CONVENTIONS.md

@@ -113,7 +113,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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/GEMINI.md

@@ -118,7 +118,7 @@ After a successful update, reread the project spine and relevant installed skill
 
 ## Registry facts (computed from registry.yaml — never hand-typed)
 
-- Product: BMAD+ v0.16.0 (derived from BMAD-METHOD v6.6.0)
+- Product: BMAD+ v0.17.0 (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/cli/commands/autoconfig.js

@@ -87,7 +87,9 @@ function calculateHealth(structure) {
   return { pct, checks };
 }
 
-function recommendPacks(stack, structure, health) {
+// `health` is measured elsewhere and does not change the recommendation: a project
+// with failing checks needs the same packs as a healthy one.
+function recommendPacks(stack, structure) {
   const packs = ['core', 'memory']; // Always
   const reasons = {
     core: 'Essential multi-role agents (Atlas, Forge, Sentinel, Nexus)',
@@ -215,7 +217,7 @@ module.exports = {
       const stack = detectStack(projectDir);
       const structure = analyzeStructure(projectDir);
       const health = calculateHealth(structure);
-      const { packs, reasons } = recommendPacks(stack, structure, health);
+      const { packs, reasons } = recommendPacks(stack, structure);
       const recs = generateRecommendations(stack, structure, health);
 
       spinner.stop('Analysis complete');

package/tools/cli/commands/uat.js

@@ -17,11 +17,27 @@ function fail(message) {
 
 function resolveSpec(target, paths) {
   if (!target) fail('an id or a spec file is required');
-  const file = target.endsWith('.json')
-    ? path.resolve(target)
-    : path.join(paths.specs, `${target}.json`);
-  if (!fs.existsSync(file)) fail(`no spec at ${file}`);
-  return uat.loadSpec(file);
+  if (target.endsWith('.json')) {
+    const file = path.resolve(target);
+    if (!fs.existsSync(file)) fail(`no spec at ${file}`);
+    return uat.loadSpec(file);
+  }
+  const direct = path.join(paths.specs, `${target}.json`);
+  if (fs.existsSync(direct)) return uat.loadSpec(direct);
+  // A recipe is named by its id, not by its file: a copied template keeps its own name
+  // (the shipped example-uat-spec.json holds the id example-1.0.0).
+  if (fs.existsSync(paths.specs)) {
+    for (const name of fs.readdirSync(paths.specs).filter((entry) => entry.endsWith('.json'))) {
+      try {
+        const loaded = uat.loadSpec(path.join(paths.specs, name));
+        if (loaded.spec.id === target) return loaded;
+      } catch {
+        // an unreadable file cannot be the recipe asked for
+      }
+    }
+  }
+  fail(`no spec with the id "${target}" in ${paths.specs}`);
+  return null;
 }
 
 function readStdin() {

package/tools/cli/i18n.js

@@ -21,6 +21,7 @@ const LANGUAGES = {
     selected_packs: 'Selected packs',
     enter_name: 'Your first name (agents use it to greet you)',
     comm_language: 'Communication language',
+    uat_environment: 'Test environment for human acceptance recipes (URL, blank if none)',
     exec_mode: 'Execution mode',
     exec_manual: 'Manual — You call agents yourself',
     exec_autopilot: 'Autopilot — Nexus manages the full pipeline',
@@ -109,6 +110,7 @@ const LANGUAGES = {
     selected_packs: 'Packs sélectionnés',
     enter_name: 'Ton prénom (les agents l\'utilisent pour te saluer)',
     comm_language: 'Langue de communication',
+    uat_environment: 'Environnement de test pour les recettes humaines (URL, vide si aucun)',
     exec_mode: 'Mode d\'exécution',
     exec_manual: 'Manuel — Tu appelles les agents toi-même',
     exec_autopilot: 'Autopilot — Nexus gère tout le pipeline',
@@ -195,6 +197,7 @@ const LANGUAGES = {
     selected_packs: 'Packs seleccionados',
     enter_name: 'Tu nombre (los agentes lo usan para saludarte)',
     comm_language: 'Idioma de comunicación',
+    uat_environment: 'Entorno de pruebas para las recetas de aceptación (URL, vacío si no hay)',
     exec_mode: 'Modo de ejecución',
     exec_manual: 'Manual — Tú llamas a los agentes',
     exec_autopilot: 'Autopilot — Nexus gestiona todo el pipeline',
@@ -281,6 +284,7 @@ const LANGUAGES = {
     selected_packs: 'Ausgewählte Packs',
     enter_name: 'Dein Vorname (Agenten verwenden ihn zur Begrüßung)',
     comm_language: 'Kommunikationssprache',
+    uat_environment: 'Testumgebung für menschliche Abnahmen (URL, leer wenn keine)',
     exec_mode: 'Ausführungsmodus',
     exec_manual: 'Manuell — Du rufst Agenten selbst auf',
     exec_autopilot: 'Autopilot — Nexus verwaltet die gesamte Pipeline',
@@ -367,6 +371,7 @@ const LANGUAGES = {
     selected_packs: 'Packs selecionados',
     enter_name: 'Seu nome (os agentes usam para te cumprimentar)',
     comm_language: 'Idioma de comunicação',
+    uat_environment: 'Ambiente de teste para receitas de aceitação humana (URL, vazio se não houver)',
     exec_mode: 'Modo de execução',
     exec_manual: 'Manual — Você chama os agentes',
     exec_autopilot: 'Autopilot — Nexus gerencia todo o pipeline',
@@ -453,6 +458,7 @@ const LANGUAGES = {
     selected_packs: 'Выбранные пакеты',
     enter_name: 'Ваше имя (агенты используют его для приветствия)',
     comm_language: 'Язык общения',
+    uat_environment: 'Тестовая среда для ручной приёмки (URL, пусто если нет)',
     exec_mode: 'Режим выполнения',
     exec_manual: 'Ручной — Вы вызываете агентов сами',
     exec_autopilot: 'Автопилот — Nexus управляет всем конвейером',
@@ -539,6 +545,7 @@ const LANGUAGES = {
     selected_packs: '已选择的包',
     enter_name: '您的名字（代理会用它来问候您）',
     comm_language: '沟通语言',
+    uat_environment: '人工验收的测试环境（URL，没有则留空）',
     exec_mode: '执行模式',
     exec_manual: '手动 — 您自己调用代理',
     exec_autopilot: '自动驾驶 — Nexus 管理整个流程',
@@ -625,6 +632,7 @@ const LANGUAGES = {
     selected_packs: 'חבילות שנבחרו',
     enter_name: 'השם שלך (הסוכנים משתמשים בו לברכך)',
     comm_language: 'שפת תקשורת',
+    uat_environment: 'סביבת בדיקה לבדיקות קבלה אנושיות (כתובת URL, ריק אם אין)',
     exec_mode: 'מצב ביצוע',
     exec_manual: 'ידני — אתה קורא לסוכנים בעצמך',
     exec_autopilot: 'טייס אוטומטי — Nexus מנהל את כל הצינור',
@@ -711,6 +719,7 @@ const LANGUAGES = {
     selected_packs: '選択されたパック',
     enter_name: 'あなたの名前（エージェントが挨拶に使います）',
     comm_language: 'コミュニケーション言語',
+    uat_environment: '人による受け入れ確認のテスト環境（URL、なければ空欄）',
     exec_mode: '実行モード',
     exec_manual: '手動 — 自分でエージェントを呼び出す',
     exec_autopilot: 'オートパイロット — Nexusがパイプライン全体を管理',
@@ -797,6 +806,7 @@ const LANGUAGES = {
     selected_packs: 'Pack selezionati',
     enter_name: 'Il tuo nome (gli agenti lo usano per salutarti)',
     comm_language: 'Lingua di comunicazione',
+    uat_environment: 'Ambiente di test per le verifiche di accettazione umana (URL, vuoto se nessuno)',
     exec_mode: 'Modalità di esecuzione',
     exec_manual: 'Manuale — Chiami tu gli agenti',
     exec_autopilot: 'Autopilot — Nexus gestisce l\'intera pipeline',

package/tools/cli/lib/packs.js

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

package/tools/cli/lib/uat.js

@@ -247,6 +247,15 @@ function validateSpec(spec, options = {}) {
         `${at}: writes: true requires verify {kind: ${VERIFY_KINDS.join('|')}, text} — the read-only check run after the tester`
       );
     }
+    for (const [line, text] of (step.do || []).entries()) {
+      // A tester copies "doctor." from "Run <code>…doctor</code>." into the terminal —
+      // it happened on the first human run of BMAD+'s own recipe.
+      if (/<\/code>\s*[.,;:!?](?:\s|$)/.test(String(text))) {
+        warnings.push(
+          `${at}: "do" line ${line + 1} puts punctuation right after a command — testers copy it into the terminal`
+        );
+      }
+    }
     const letters = new Set();
     for (const expect of step.expect || []) {
       for (const key of unknownKeys(expect, EXPECT_KEYS))
@@ -706,6 +715,13 @@ function gate({ spec, runs, triage }) {
       );
     } else if (entry.decision === 'accept-risk' && !String(entry.decidedBy || '').trim()) {
       reasons.push(`${failure.step}/${failure.expect}: accept-risk requires decidedBy`);
+    } else if (failure.state === 'blocked' && entry.decision !== 'accept-risk') {
+      // A blocked expectation was never observed. Classifying why does not establish
+      // anything about the product: replay it, or have someone accept the risk by name.
+      // (First run of BMAD+'s own recipe: 17 of 21 blocked would otherwise have passed.)
+      reasons.push(
+        `${failure.step}/${failure.expect} was blocked: nothing was observed — replay it, or record accept-risk with decidedBy`
+      );
     }
   }
   // A tick on a step that writes is not a write: the read-only proof settles it.
@@ -815,6 +831,8 @@ for (const [stepId, step] of Object.entries(run.steps || {})) {
     if (!entry) problems.push(stepId + '/' + letter + ' ' + expect.state + ', not triaged');
     else if (!entry.class || entry.class === 'undecided' || !entry.decision) {
       problems.push(stepId + '/' + letter + ' triaged without a class and a decision');
+    } else if (expect.state === 'blocked' && (entry.decision !== 'accept-risk' || !entry.decidedBy)) {
+      problems.push(stepId + '/' + letter + ' was blocked and never observed; replay it or accept the risk by name');
     }
   }
 }

package/tools/release/publication-content.js

@@ -38,6 +38,7 @@ const CANDIDATE_WEBSITE_FILES = Object.freeze([
   'docs-page.js',
   'docs-markdown.js',
   'page-shell.js',
+  'public-links.js',
   'styles.css',
   'site.js',
   'favicon.svg',