bmad-plus 0.14.0 → 0.17.0

package/src/bmad-plus/skills/bmad-plus-uat/template/strings.json

@@ -0,0 +1,442 @@
+{
+  "en": {
+    "name": "English",
+    "dir": "ltr",
+    "uiLanguage": "Page language",
+    "before": "Before you start",
+    "tester": "Your first name — it signs this run",
+    "start": "Start a new run",
+    "resume": "Or resume a run already started",
+    "stepsLabel": "steps",
+    "seen": "Seen",
+    "notSeen": "Not seen",
+    "blocked": "Blocked",
+    "skip": "Skip this optional step",
+    "optional": "Optional step",
+    "where": "Where",
+    "doIt": "Do",
+    "expect": "What you must see — tick every line",
+    "note": "What you see instead, or any remark (word for word if you can)",
+    "whyNot": "What did you see instead?",
+    "todo": "to do",
+    "finish": "Finish",
+    "finishRun": "Finish this run",
+    "finished": "Run finished",
+    "overall": "Overall remarks",
+    "saveJson": "Save the JSON on my device",
+    "copyJson": "Copy the JSON",
+    "copied": "JSON copied.",
+    "confirmUnanswered": "{n} line(s) are not ticked. Finish anyway?",
+    "writesWarning": "This step writes for real on",
+    "intended": "It is intended.",
+    "savedLocal": "Saved in this browser — remember to save the JSON at the end",
+    "savedRemote": "Saved ·",
+    "localMode": "This page is a local file: at the end, save the JSON and hand the file over — that is what the agent reads.",
+    "dbMode": "Your answers are saved as you go; the agent reads them directly, you have nothing to send.",
+    "serveMode": "Your answers are saved straight into the project as you tick; you have nothing to send.",
+    "startFirst": "Enter your first name and start a run first — nothing is recorded before that.",
+    "copyCommand": "Click to copy",
+    "commandCopied": "Copied",
+    "runBy": "Run by {tester}",
+    "finishedOn": "finished on {date}",
+    "countSeen": "seen",
+    "countNotSeen": "not seen",
+    "countBlocked": "blocked"
+  },
+  "fr": {
+    "name": "Français",
+    "dir": "ltr",
+    "uiLanguage": "Langue de la page",
+    "before": "Avant de commencer",
+    "tester": "Ton prénom — il signe la recette",
+    "start": "Commencer une nouvelle recette",
+    "resume": "Ou reprendre une recette déjà commencée",
+    "stepsLabel": "étapes",
+    "seen": "Vu",
+    "notSeen": "Pas vu",
+    "blocked": "Bloqué",
+    "skip": "Sauter cette étape facultative",
+    "optional": "Étape facultative",
+    "where": "Où",
+    "doIt": "Fais",
+    "expect": "Ce que tu dois voir — coche chaque ligne",
+    "note": "Ce que tu vois à la place, ou toute remarque (mot pour mot si possible)",
+    "whyNot": "Qu'est-ce que tu vois à la place ?",
+    "todo": "à faire",
+    "finish": "Terminer",
+    "finishRun": "Terminer la recette",
+    "finished": "Recette terminée",
+    "overall": "Remarques d'ensemble",
+    "saveJson": "Enregistrer le JSON sur mon appareil",
+    "copyJson": "Copier le JSON",
+    "copied": "JSON copié.",
+    "confirmUnanswered": "{n} ligne(s) ne sont pas cochées. Terminer quand même ?",
+    "writesWarning": "Cette étape écrit pour de vrai sur",
+    "intended": "C'est voulu.",
+    "savedLocal": "Enregistré dans ce navigateur — pense à « Enregistrer le JSON » à la fin",
+    "savedRemote": "Enregistré ·",
+    "localMode": "Cette page est un fichier local : à la fin, enregistre le JSON et transmets le fichier — c'est lui que l'agent lit.",
+    "dbMode": "Tes réponses sont enregistrées au fur et à mesure : l'agent les lit directement, tu n'as rien à envoyer.",
+    "serveMode": "Tes réponses sont enregistrées directement dans le projet à chaque coche ; tu n'as rien à envoyer.",
+    "startFirst": "Écris ton prénom et commence la recette d’abord — rien n’est enregistré avant.",
+    "copyCommand": "Cliquer pour copier",
+    "commandCopied": "Copié",
+    "runBy": "Recette de {tester}",
+    "finishedOn": "terminée le {date}",
+    "countSeen": "vus",
+    "countNotSeen": "pas vus",
+    "countBlocked": "bloqués"
+  },
+  "es": {
+    "name": "Español",
+    "dir": "ltr",
+    "uiLanguage": "Idioma de la página",
+    "before": "Antes de empezar",
+    "tester": "Tu nombre — firma esta prueba",
+    "start": "Empezar una nueva prueba",
+    "resume": "O retomar una prueba ya empezada",
+    "stepsLabel": "pasos",
+    "seen": "Visto",
+    "notSeen": "No visto",
+    "blocked": "Bloqueado",
+    "skip": "Omitir este paso opcional",
+    "optional": "Paso opcional",
+    "where": "Dónde",
+    "doIt": "Haz",
+    "expect": "Lo que debes ver — marca cada línea",
+    "note": "Lo que ves en su lugar, o cualquier observación (palabra por palabra si puedes)",
+    "whyNot": "¿Qué ves en su lugar?",
+    "todo": "por hacer",
+    "finish": "Terminar",
+    "finishRun": "Terminar la prueba",
+    "finished": "Prueba terminada",
+    "overall": "Observaciones generales",
+    "saveJson": "Guardar el JSON en mi dispositivo",
+    "copyJson": "Copiar el JSON",
+    "copied": "JSON copiado.",
+    "confirmUnanswered": "{n} línea(s) sin marcar. ¿Terminar de todos modos?",
+    "writesWarning": "Este paso escribe de verdad en",
+    "intended": "Es intencionado.",
+    "savedLocal": "Guardado en este navegador — acuérdate de guardar el JSON al final",
+    "savedRemote": "Guardado ·",
+    "localMode": "Esta página es un archivo local: al final, guarda el JSON y entrega el archivo — es lo que lee el agente.",
+    "dbMode": "Tus respuestas se guardan sobre la marcha; el agente las lee directamente, no tienes que enviar nada.",
+    "serveMode": "Tus respuestas se guardan directamente en el proyecto con cada marca; no tienes que enviar nada.",
+    "startFirst": "Escribe tu nombre y empieza la prueba primero: nada se guarda antes.",
+    "copyCommand": "Clic para copiar",
+    "commandCopied": "Copiado",
+    "runBy": "Prueba de {tester}",
+    "finishedOn": "terminada el {date}",
+    "countSeen": "vistos",
+    "countNotSeen": "no vistos",
+    "countBlocked": "bloqueados"
+  },
+  "de": {
+    "name": "Deutsch",
+    "dir": "ltr",
+    "uiLanguage": "Sprache der Seite",
+    "before": "Bevor du beginnst",
+    "tester": "Dein Vorname — er unterschreibt diesen Durchlauf",
+    "start": "Neuen Durchlauf starten",
+    "resume": "Oder einen begonnenen Durchlauf fortsetzen",
+    "stepsLabel": "Schritte",
+    "seen": "Gesehen",
+    "notSeen": "Nicht gesehen",
+    "blocked": "Blockiert",
+    "skip": "Diesen optionalen Schritt überspringen",
+    "optional": "Optionaler Schritt",
+    "where": "Wo",
+    "doIt": "Tu",
+    "expect": "Was du sehen musst — jede Zeile abhaken",
+    "note": "Was du stattdessen siehst, oder eine Bemerkung (wörtlich, wenn möglich)",
+    "whyNot": "Was hast du stattdessen gesehen?",
+    "todo": "offen",
+    "finish": "Abschließen",
+    "finishRun": "Durchlauf abschließen",
+    "finished": "Durchlauf abgeschlossen",
+    "overall": "Allgemeine Bemerkungen",
+    "saveJson": "JSON auf meinem Gerät speichern",
+    "copyJson": "JSON kopieren",
+    "copied": "JSON kopiert.",
+    "confirmUnanswered": "{n} Zeile(n) sind nicht abgehakt. Trotzdem abschließen?",
+    "writesWarning": "Dieser Schritt schreibt wirklich auf",
+    "intended": "Das ist so gewollt.",
+    "savedLocal": "In diesem Browser gespeichert — denk am Ende an „JSON speichern“",
+    "savedRemote": "Gespeichert ·",
+    "localMode": "Diese Seite ist eine lokale Datei: speichere am Ende das JSON und gib die Datei weiter — sie ist es, die der Agent liest.",
+    "dbMode": "Deine Antworten werden laufend gespeichert; der Agent liest sie direkt, du musst nichts senden.",
+    "serveMode": "Deine Antworten werden bei jedem Klick direkt im Projekt gespeichert; du musst nichts senden.",
+    "startFirst": "Gib zuerst deinen Vornamen ein und starte den Durchlauf — vorher wird nichts gespeichert.",
+    "copyCommand": "Zum Kopieren klicken",
+    "commandCopied": "Kopiert",
+    "runBy": "Durchlauf von {tester}",
+    "finishedOn": "abgeschlossen am {date}",
+    "countSeen": "gesehen",
+    "countNotSeen": "nicht gesehen",
+    "countBlocked": "blockiert"
+  },
+  "pt-br": {
+    "name": "Português (Brasil)",
+    "dir": "ltr",
+    "uiLanguage": "Idioma da página",
+    "before": "Antes de começar",
+    "tester": "Seu primeiro nome — ele assina esta rodada",
+    "start": "Começar uma nova rodada",
+    "resume": "Ou retomar uma rodada já iniciada",
+    "stepsLabel": "etapas",
+    "seen": "Visto",
+    "notSeen": "Não visto",
+    "blocked": "Bloqueado",
+    "skip": "Pular esta etapa opcional",
+    "optional": "Etapa opcional",
+    "where": "Onde",
+    "doIt": "Faça",
+    "expect": "O que você deve ver — marque cada linha",
+    "note": "O que você vê no lugar, ou qualquer observação (palavra por palavra, se possível)",
+    "whyNot": "O que você viu no lugar?",
+    "todo": "a fazer",
+    "finish": "Encerrar",
+    "finishRun": "Encerrar a rodada",
+    "finished": "Rodada encerrada",
+    "overall": "Observações gerais",
+    "saveJson": "Salvar o JSON no meu dispositivo",
+    "copyJson": "Copiar o JSON",
+    "copied": "JSON copiado.",
+    "confirmUnanswered": "{n} linha(s) sem marcação. Encerrar mesmo assim?",
+    "writesWarning": "Esta etapa grava de verdade em",
+    "intended": "É intencional.",
+    "savedLocal": "Salvo neste navegador — lembre-se de salvar o JSON no final",
+    "savedRemote": "Salvo ·",
+    "localMode": "Esta página é um arquivo local: no final, salve o JSON e entregue o arquivo — é ele que o agente lê.",
+    "dbMode": "Suas respostas são salvas conforme você avança; o agente as lê diretamente, você não precisa enviar nada.",
+    "serveMode": "Suas respostas são salvas direto no projeto a cada marcação; você não precisa enviar nada.",
+    "startFirst": "Digite seu nome e comece a rodada primeiro — nada é salvo antes disso.",
+    "copyCommand": "Clique para copiar",
+    "commandCopied": "Copiado",
+    "runBy": "Rodada de {tester}",
+    "finishedOn": "encerrada em {date}",
+    "countSeen": "vistos",
+    "countNotSeen": "não vistos",
+    "countBlocked": "bloqueados"
+  },
+  "ru": {
+    "name": "Русский",
+    "dir": "ltr",
+    "uiLanguage": "Язык страницы",
+    "before": "Перед началом",
+    "tester": "Ваше имя — оно подписывает этот прогон",
+    "start": "Начать новый прогон",
+    "resume": "Или продолжить начатый прогон",
+    "stepsLabel": "шагов",
+    "seen": "Видно",
+    "notSeen": "Не видно",
+    "blocked": "Недоступно",
+    "skip": "Пропустить этот необязательный шаг",
+    "optional": "Необязательный шаг",
+    "where": "Где",
+    "doIt": "Сделайте",
+    "expect": "Что вы должны увидеть — отметьте каждую строку",
+    "note": "Что вы видите вместо этого, или любое замечание (дословно, если можно)",
+    "whyNot": "Что вы увидели вместо этого?",
+    "todo": "осталось",
+    "finish": "Завершить",
+    "finishRun": "Завершить прогон",
+    "finished": "Прогон завершён",
+    "overall": "Общие замечания",
+    "saveJson": "Сохранить JSON на устройство",
+    "copyJson": "Скопировать JSON",
+    "copied": "JSON скопирован.",
+    "confirmUnanswered": "Строк без отметки: {n}. Всё равно завершить?",
+    "writesWarning": "Этот шаг реально пишет в",
+    "intended": "Так задумано.",
+    "savedLocal": "Сохранено в этом браузере — в конце не забудьте сохранить JSON",
+    "savedRemote": "Сохранено ·",
+    "localMode": "Эта страница — локальный файл: в конце сохраните JSON и передайте файл — именно его читает агент.",
+    "dbMode": "Ваши ответы сохраняются по ходу; агент читает их напрямую, отправлять ничего не нужно.",
+    "serveMode": "Ваши ответы сохраняются прямо в проект при каждой отметке; отправлять ничего не нужно.",
+    "startFirst": "Сначала введите имя и начните прогон — до этого ничего не сохраняется.",
+    "copyCommand": "Нажмите, чтобы скопировать",
+    "commandCopied": "Скопировано",
+    "runBy": "Прогон: {tester}",
+    "finishedOn": "завершён {date}",
+    "countSeen": "видно",
+    "countNotSeen": "не видно",
+    "countBlocked": "недоступно"
+  },
+  "zh": {
+    "name": "中文 (简体)",
+    "dir": "ltr",
+    "uiLanguage": "页面语言",
+    "before": "开始之前",
+    "tester": "你的名字 — 它为这次验收签名",
+    "start": "开始一次新的验收",
+    "resume": "或继续已开始的验收",
+    "stepsLabel": "个步骤",
+    "seen": "看到了",
+    "notSeen": "没看到",
+    "blocked": "无法进行",
+    "skip": "跳过这个可选步骤",
+    "optional": "可选步骤",
+    "where": "在哪里",
+    "doIt": "怎么做",
+    "expect": "你应该看到什么 — 请逐行勾选",
+    "note": "你实际看到的内容，或任何备注（尽量逐字记录）",
+    "whyNot": "你实际看到了什么？",
+    "todo": "待办",
+    "finish": "结束",
+    "finishRun": "结束这次验收",
+    "finished": "验收已结束",
+    "overall": "总体备注",
+    "saveJson": "把 JSON 保存到我的设备",
+    "copyJson": "复制 JSON",
+    "copied": "JSON 已复制。",
+    "confirmUnanswered": "还有 {n} 行没有勾选。仍然结束吗？",
+    "writesWarning": "这一步会真实写入",
+    "intended": "这是有意为之。",
+    "savedLocal": "已保存在此浏览器 — 结束时记得保存 JSON",
+    "savedRemote": "已保存 ·",
+    "localMode": "本页是本地文件：结束时请保存 JSON 并把文件交出去 — 代理读取的正是这个文件。",
+    "dbMode": "你的回答会即时保存，代理直接读取，你无需发送任何东西。",
+    "serveMode": "你的每次勾选都会直接保存到项目中，你无需发送任何东西。",
+    "startFirst": "请先输入名字并开始验收——在此之前不会保存任何内容。",
+    "copyCommand": "点击复制",
+    "commandCopied": "已复制",
+    "runBy": "{tester} 的验收",
+    "finishedOn": "完成于 {date}",
+    "countSeen": "看到",
+    "countNotSeen": "没看到",
+    "countBlocked": "无法进行"
+  },
+  "he": {
+    "name": "עברית",
+    "dir": "rtl",
+    "uiLanguage": "שפת הדף",
+    "before": "לפני שמתחילים",
+    "tester": "השם שלך — הוא חותם על ההרצה הזאת",
+    "start": "להתחיל הרצה חדשה",
+    "resume": "או להמשיך הרצה שכבר התחילה",
+    "stepsLabel": "שלבים",
+    "seen": "נראה",
+    "notSeen": "לא נראה",
+    "blocked": "חסום",
+    "skip": "לדלג על השלב הרשות הזה",
+    "optional": "שלב רשות",
+    "where": "איפה",
+    "doIt": "מה לעשות",
+    "expect": "מה צריך לראות — סמן כל שורה",
+    "note": "מה ראית במקום, או כל הערה (מילה במילה אם אפשר)",
+    "whyNot": "מה ראית במקום?",
+    "todo": "נותר",
+    "finish": "לסיים",
+    "finishRun": "לסיים את ההרצה",
+    "finished": "ההרצה הסתיימה",
+    "overall": "הערות כלליות",
+    "saveJson": "לשמור את ה‑JSON במכשיר שלי",
+    "copyJson": "להעתיק את ה‑JSON",
+    "copied": "ה‑JSON הועתק.",
+    "confirmUnanswered": "{n} שורות לא סומנו. לסיים בכל זאת?",
+    "writesWarning": "השלב הזה כותב באמת אל",
+    "intended": "זה מכוון.",
+    "savedLocal": "נשמר בדפדפן הזה — זכור לשמור את ה‑JSON בסוף",
+    "savedRemote": "נשמר ·",
+    "localMode": "הדף הזה הוא קובץ מקומי: בסוף שמור את ה‑JSON והעבר את הקובץ — זה מה שהסוכן קורא.",
+    "dbMode": "התשובות נשמרות תוך כדי, והסוכן קורא אותן ישירות. אין מה לשלוח.",
+    "serveMode": "כל סימון נשמר ישירות בפרויקט. אין מה לשלוח.",
+    "startFirst": "קודם כתוב את שמך והתחל הרצה — לפני כן שום דבר לא נשמר.",
+    "copyCommand": "לחץ להעתקה",
+    "commandCopied": "הועתק",
+    "runBy": "הרצה של {tester}",
+    "finishedOn": "הסתיימה ב-{date}",
+    "countSeen": "נראו",
+    "countNotSeen": "לא נראו",
+    "countBlocked": "חסומים"
+  },
+  "ja": {
+    "name": "日本語",
+    "dir": "ltr",
+    "uiLanguage": "ページの言語",
+    "before": "はじめる前に",
+    "tester": "あなたの名前 — この実施に署名します",
+    "start": "新しい実施を始める",
+    "resume": "または開始済みの実施を再開する",
+    "stepsLabel": "ステップ",
+    "seen": "見えた",
+    "notSeen": "見えない",
+    "blocked": "実施できない",
+    "skip": "この任意ステップを飛ばす",
+    "optional": "任意のステップ",
+    "where": "どこで",
+    "doIt": "何をする",
+    "expect": "見えるはずのこと — 各行にチェック",
+    "note": "代わりに見えたもの、または気づいたこと（できれば一字一句）",
+    "whyNot": "代わりに何が見えましたか？",
+    "todo": "未実施",
+    "finish": "終了",
+    "finishRun": "この実施を終了する",
+    "finished": "実施を終了しました",
+    "overall": "全体の所見",
+    "saveJson": "JSON を端末に保存する",
+    "copyJson": "JSON をコピーする",
+    "copied": "JSON をコピーしました。",
+    "confirmUnanswered": "未チェックの行が {n} 件あります。それでも終了しますか？",
+    "writesWarning": "このステップは実際に書き込みます：",
+    "intended": "意図した動作です。",
+    "savedLocal": "このブラウザに保存しました — 最後に JSON の保存を忘れずに",
+    "savedRemote": "保存済み ·",
+    "localMode": "このページはローカルファイルです。最後に JSON を保存してファイルを渡してください — エージェントが読むのはそれです。",
+    "dbMode": "回答は随時保存され、エージェントが直接読みます。送信は不要です。",
+    "serveMode": "チェックするたびに回答がプロジェクトへ直接保存されます。送信は不要です。",
+    "startFirst": "まず名前を入力して実施を開始してください。それまでは何も保存されません。",
+    "copyCommand": "クリックしてコピー",
+    "commandCopied": "コピーしました",
+    "runBy": "{tester} の実施",
+    "finishedOn": "{date} に終了",
+    "countSeen": "見えた",
+    "countNotSeen": "見えない",
+    "countBlocked": "実施不可"
+  },
+  "it": {
+    "name": "Italiano",
+    "dir": "ltr",
+    "uiLanguage": "Lingua della pagina",
+    "before": "Prima di iniziare",
+    "tester": "Il tuo nome — firma questa sessione",
+    "start": "Iniziare una nuova sessione",
+    "resume": "Oppure riprendere una sessione già iniziata",
+    "stepsLabel": "passaggi",
+    "seen": "Visto",
+    "notSeen": "Non visto",
+    "blocked": "Bloccato",
+    "skip": "Saltare questo passaggio facoltativo",
+    "optional": "Passaggio facoltativo",
+    "where": "Dove",
+    "doIt": "Fai",
+    "expect": "Ciò che devi vedere — spunta ogni riga",
+    "note": "Ciò che vedi al suo posto, o qualsiasi osservazione (parola per parola se puoi)",
+    "whyNot": "Che cosa hai visto al suo posto?",
+    "todo": "da fare",
+    "finish": "Terminare",
+    "finishRun": "Terminare la sessione",
+    "finished": "Sessione terminata",
+    "overall": "Osservazioni generali",
+    "saveJson": "Salvare il JSON sul mio dispositivo",
+    "copyJson": "Copiare il JSON",
+    "copied": "JSON copiato.",
+    "confirmUnanswered": "{n} riga/righe non spuntate. Terminare comunque?",
+    "writesWarning": "Questo passaggio scrive davvero su",
+    "intended": "È voluto.",
+    "savedLocal": "Salvato in questo browser — ricordati di salvare il JSON alla fine",
+    "savedRemote": "Salvato ·",
+    "localMode": "Questa pagina è un file locale: alla fine salva il JSON e consegna il file — è quello che legge l'agente.",
+    "dbMode": "Le tue risposte vengono salvate man mano; l'agente le legge direttamente, non devi inviare nulla.",
+    "serveMode": "Le tue risposte vengono salvate direttamente nel progetto a ogni spunta; non devi inviare nulla.",
+    "startFirst": "Scrivi il tuo nome e inizia prima la sessione: prima non viene salvato nulla.",
+    "copyCommand": "Clic per copiare",
+    "commandCopied": "Copiato",
+    "runBy": "Sessione di {tester}",
+    "finishedOn": "terminata il {date}",
+    "countSeen": "visti",
+    "countNotSeen": "non visti",
+    "countBlocked": "bloccati"
+  }
+}

package/src/bmad-plus/skills/bmad-plus-uat/templates/README.md

@@ -0,0 +1,63 @@
+# Project gates for human acceptance
+
+BMAD+ installs no lifecycle hook, so an instruction can be skipped and a Nexus task
+can be bypassed. These two scripts are the layer that cannot: they run inside your
+own checks and fail the command that calls them. Copy the ones you want into your
+project — for example under `scripts/` — and wire them where they bite.
+
+Both need nothing but Node 20 and are safe to read before you run them.
+
+## G1 — a version does not leave without its recipe
+
+`uat-spec-present.mjs` fails when no recipe names the version in `package.json`.
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "uat:spec": "node scripts/uat-spec-present.mjs",
+    "pretest": "npm run uat:spec"          // or call it from your CI step
+  }
+}
+```
+
+A grouped recipe covers a version because it **names** it in `versions`, never
+because its file name suggests a range. That is deliberate: deducing coverage from
+a range makes a version look checked when nobody wrote anything about it.
+
+Where to run it: the same place your tests run, and before the push, not after the
+deployment. A reminder printed once the version is live only records the miss.
+
+## G3 — production waits for a run that was read
+
+`uat-release-gate.mjs` resolves the recipe covering the current version and runs
+`bmad-plus uat gate` on it. It exits 0 only when the latest run is finished, answers
+the current revision of the recipe, leaves no expectation unanswered, has every
+failure classified with a decision, and has every passed writing step confirmed
+read-only.
+
+```sh
+# deploy-production.sh
+node scripts/uat-release-gate.mjs || exit 1
+# … deploy only below this line
+```
+
+Exit codes: `0` passed · `1` failed · `2` no finished run yet · `3` the run answered
+another revision of the recipe · `4` the gate itself could not run. The last one is
+not a pass: a missing gate is a missing gate.
+
+The script runs the CLI's own entry point with the Node that started it: `BMAD_PLUS_CLI`
+if you set it, otherwise `node_modules/bmad-plus/` if the project installed it. No shell
+and no `npx`: a Windows `.cmd` shim cannot be spawned without a shell, and a release gate
+must not depend on a download. If neither exists it exits 4 and says so.
+
+## What these gates do and do not establish
+
+They establish that a recipe exists for the version, and that a human run covering
+it is complete, current and classified. They do not establish that the tester looked
+at the right place, and they do not judge the product. Every report says
+*human-observed* for that reason.
+
+A failure classified as a defect of the recipe is not a product fix: amend the spec,
+rebuild it, replay the affected steps, and say so. A failure nobody could classify
+keeps the gate red on purpose — ask the tester what they saw instead of guessing.

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."
+  ]
+}