bmad-plus 0.16.0 → 0.17.1

package/src/bmad-plus/skills/bmad-plus-uat/templates/example-uat-spec.json

@@ -0,0 +1,95 @@
+{
+  "schema": "bmad-plus/uat-spec/2",
+  "id": "example-1.0.0",
+  "product": "Example",
+  "versions": ["1.0.0"],
+  "date": "2026-09-16",
+  "language": "en",
+  "title": "What this delivery changes, in one sentence — this becomes the page title",
+  "subtitle": "Example · TEST environment · version 1.0.0 · 2026-09-16",
+  "environment": { "name": "TEST", "url": "https://test.example.com" },
+  "estimate": "5 min",
+  "intro": [
+    "<b>What the measurement showed.</b> The numbers taken before the delivery: how many cases change, where, production included. \"0\" is a number and gets said."
+  ],
+  "warnings": [
+    "<b>Step 2 writes for real on TEST</b> (a button that persists). It is intended."
+  ],
+  "witnesses": [
+    {
+      "id": "TEST-001",
+      "proof": "select updated_at, funder from folder where reference = 'TEST-001'",
+      "reads": ["1-nominal"],
+      "writes": ["2-the-gesture"]
+    }
+  ],
+  "steps": [
+    {
+      "id": "0-setup",
+      "title": "Setup",
+      "duration": "1 min",
+      "where": [
+        "Open <a href=\"https://test.example.com\" target=\"_blank\" rel=\"noopener\">test.example.com</a> and sign in."
+      ],
+      "do": ["Find the <span class=\"ecran\">Folders</span> menu."],
+      "expect": [{ "id": "a", "text": "I am signed in and I can see the list." }]
+    },
+    {
+      "id": "1-nominal",
+      "title": "The nominal case (TEST-001)",
+      "duration": "2 min",
+      "stories": [{ "ref": "story-12", "criteria": ["AC-3"] }],
+      "where": [
+        "Folder <code>TEST-001</code> → tab <span class=\"ecran\">Technical</span> → the card named exactly as on screen."
+      ],
+      "do": [
+        "One click per line: click <span class=\"ecran\">Analyse</span>.",
+        "Wait until the button reads <span class=\"ecran\">Analyse</span> again."
+      ],
+      "expect": [
+        {
+          "id": "a",
+          "text": "The line reads exactly: <span class=\"ecran\">Label copied from the code, accents included or not</span>."
+        },
+        {
+          "id": "b",
+          "text": "One fact per line: the <span class=\"ecran\">My box</span> checkbox is <b>ticked</b>."
+        }
+      ]
+    },
+    {
+      "id": "2-the-gesture",
+      "title": "The gesture that lifts the red",
+      "duration": "2 min",
+      "writes": true,
+      "verify": {
+        "kind": "sql",
+        "text": "select updated_at, funder from folder where reference = 'TEST-001' — updated_at must be later than the run"
+      },
+      "where": ["Same folder, same card."],
+      "do": [
+        "Click <span class=\"ecran\">Confirm</span>. <b>This writes for real.</b>",
+        "Come back to the folder with the browser's back button."
+      ],
+      "expect": [
+        {
+          "id": "a",
+          "text": "The <span class=\"ecran\">My box</span> checkbox is now <b>ticked</b>."
+        },
+        {
+          "id": "b",
+          "text": "Positive control: <code>TEST-002</code> is <b>unchanged</b> — its box was already ticked and no link appeared."
+        }
+      ]
+    }
+  ],
+  "closing": {
+    "text": [
+      "<b>What did not change</b>: no migration, and the deployment touched no data.",
+      "<b>What waits for a decision</b>: name it here, or say there is none."
+    ]
+  },
+  "authorNotes": [
+    "Free field for the agent who wrote this: doubts, witnesses not yet measured, labels to confirm. The page ignores it; the reviewer reads it."
+  ]
+}

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/adapters.config.js

@@ -105,7 +105,7 @@ const PROJECT_INSTRUCTIONS = [
   '',
   '## Repository Maintenance Rule',
   '',
-  'When updating the main README.md (English), you MUST synchronously update all translations in the readme-international/ directory (fr, es, de).',
+  'The public README is README-DIST.md, generated by tools/release/publication-content.js. When it changes, you MUST synchronously update all translations in the readme-international/ directory (fr, es, de), which mirror it section by section.',
   '',
   ...MEMORY_INSTRUCTIONS,
   '',