bmad-plus 0.14.0 → 0.16.0

package/src/bmad-plus/skills/bmad-plus-uat/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: bmad-plus-uat
+description: Turn a delivery into a human acceptance recipe (recette) — a self-contained page a non-technical tester plays step by step, whose ticks become a JSON run the agent reads, triages and gates on. Use when a version goes to a test environment, when someone asks "what should I check", or when a run's results appear.
+---
+
+# Human acceptance recipe (recette)
+
+## Overview
+
+Automated tests prove that the pieces behave. A recipe proves that **a person saw the chain
+work on screen**: writer → reader → screen → gesture. This skill turns a delivery into a
+protocol anyone can run, and turns the tester's ticks into evidence the agent reads without
+an intermediary.
+
+Three gestures: **write the spec**, **build and deliver the page**, **read the run and triage it**.
+Everything else is the `bmad-plus uat` command (alias `bmad-plus recette`), which is deterministic
+and identical for every host and model.
+
+```
+delivery ─► spec JSON ─► build page ─► deploy to test env ─► a person plays it ─► run JSON
+   ▲                                                                                  │
+   └─── fix, or amended spec ◄─── triage: product / recipe / data / undecided ◄────────┘
+```
+
+## When to activate
+
+- A version is ready for DEMO / PREPROD, before production — **always**.
+- A visible feature was implemented and someone must confirm it on screen.
+- Someone asks for "the recette", "the UAT", "what should I check".
+- A results file appears, or the user says "read the run".
+
+Read `recette.mode` from `_bmad/config.yaml`: `advisory` (default — build and offer the page,
+never block), `gate` (the delivery waits for a passing gate), `off` (no recipe; say so in the
+delivery report). A delivery with no human-observable change states that fact rather than
+skipping in silence.
+
+## 1. Write the spec — `_bmad-output/uat/specs/<product>-<version>.json`
+
+Schema: `bmad-plus/uat-spec/2` (`ref/uat-spec.schema.json`). Sources: the story's acceptance
+criteria, the changelog, and **the screen itself** — read the component, do not recall it.
+
+1. **A real sequence.** Steps follow one human pass: preparation → nominal case → control →
+   gesture → end. Numbered because it is an order, not decoration.
+2. **Where / Do / Expect** for every step. One click per `do` line. **One verifiable fact per
+   expectation** — two facts are two lines, because the tester may see one and not the other.
+3. **On-screen labels word for word**, inside `<span class="ecran">…</span>`, copied from the
+   code. `uat lint --src <dir>` fails on a label that exists in no source file; run it before
+   anyone opens the page.
+4. **Name the witness and prove its state.** Every `witnesses[]` entry carries the read-only
+   query that establishes it. A recipe placed on a witness that is not in the assumed state is
+   unplayable, and the measurement must be re-run before publishing, not remembered.
+5. **A positive control per changed behaviour**: the case that must stay as it was.
+6. **`writes: true` on every step that persists something**, with `verify` — the read-only check
+   (query, endpoint, command) you will run afterwards. When the step *attempts* something the
+   product must refuse, keep `writes: true` and use `warning` to say what happens if the refusal
+   does not come, and that the tester should stop and answer *not seen*.
+7. **Numbers in `intro`**: what the measurement showed before the delivery, production included.
+   "0" is a number and gets said.
+8. Never an expectation no writer produces: if the data does not exist, the expectation is false
+   before the tester starts. Never an expectation that quotes the defect it replaces — write what
+   the screen shows now.
+9. `closing.text`: what did not change, what still waits for a decision, the gesture you left out.
+10. Keep a page under the configured budget (15 steps / 30 minutes by default). Beyond it, split
+    into ordered pages and declare the order with `after` — a step meant "for later" inside
+    another page gets played at once.
+
+## 2. Build and deliver
+
+```bash
+bmad-plus uat lint <id> --src src          # labels, markup, budget, witnesses
+bmad-plus uat build <id>                   # → _bmad-output/uat/pages/uat-<id>.html
+```
+
+The page is self-contained and carries the spec's SHA-256, so a run always says which revision
+it answered. It opens in the recipe's language, otherwise the project's `communication_language`,
+otherwise English, and the tester can switch to any of the installed languages on the page itself.
+
+Deliver in the way the host allows, and say so plainly:
+
+| Host | Delivery | Where the answers go |
+|---|---|---|
+| Claude Code / claude.ai | publish the page as an artifact with `capabilities: {db: {}, downloads: true}` | saved on every tick in the artifact database; read it with `ArtifactData list` on collection `recettes`, then `bmad-plus uat import` so the evidence lands in the repository |
+| Any host, tester on this machine | `bmad-plus uat serve <id>` (loopback only) | written straight into `_bmad-output/uat/results/<id>/` at every tick |
+| Any host, tester elsewhere | send `pages/uat-<id>.html` | the tester saves or copies the JSON; `bmad-plus uat import <id> --input <file>` |
+
+Then tell the tester four things: the link or file, how long it takes, **which steps write for
+real**, and the play order when several recipes share an environment (`bmad-plus uat order`).
+
+## 3. Read, triage, gate
+
+```bash
+bmad-plus uat read <id>                    # every failure with its text and the tester's note
+bmad-plus uat gate <id> [--emit-check]     # 0 pass · 1 fail · 2 awaiting · 3 stale
+```
+
+Classify **every** failed or blocked expectation in `_bmad-output/uat/triage/<id>.json` before
+anything becomes a fix. A "not seen" is not automatically a bug — on the eight runs that shaped
+this skill, eleven of seventeen were defects of the recipe itself.
+
+| Class | Sign | What follows |
+|---|---|---|
+| `product` | the screen differs from what the code was meant to render | fix task on the story, and a replay step in the next version's recipe |
+| `recipe` | the screen shows the intended result, the expectation described it wrongly | amend the spec, rebuild (new fingerprint), replay the affected steps, and say no product change was needed |
+| `data` | the witness is no longer in the assumed state | re-run the witness query, reset or rename it, replay |
+| `undecided` | no note, or not attributable | ask the tester what they saw — never guess. The gate stays red |
+
+**A tick on a writing step is not a write.** Run each `verify` read-only and record the result in
+`writeChecks`. This is not ceremony: a step ticked nine times out of nine once turned out to have
+written nothing, and three correct steps were nearly rewritten on that false premise.
+
+Then write the verdict where the project records deliveries — changelog or delivery report —
+with the figures, the tester's name, and what stays open. The evidence is labelled
+**human-observed**: the gate establishes that the run is complete, current and triaged, never
+that the tester looked at the right place.
+
+## Gating a delivery with Nexus
+
+```bash
+bmad-plus uat gate <id> --emit-check        # writes checks/gate-<id>.cjs, self-contained
+```
+
+Create a task whose scope is the results and triage folders, whose resources include the spec and
+that verifier, and whose check runs it. `start` it with a host backend for the tester, record
+`blocked` while the person plays, then `completed`, then `verify` and `accept`. A failing gate
+keeps acceptance out of reach; the fix task carries the run and the triage entry as resources.
+
+## What this skill does not do
+
+- It does not replace automated tests or adversarial review. It is the human proof no test gives.
+- It does not invent expectations: what the spec announces comes from the code and the
+  measurement, never from the plan alone.
+- It does not play the recipe. An agent that "plays" it in a headless browser has written a test,
+  not a recipe.
+
+## Pitfalls already paid for
+
+- A witness chosen without checking its state ("4 reds" were 2).
+- A label with accents in the spec when the screen has none — the tester searches for the exact word.
+- "the tiles" when two components render different tiles: name the card that carries the fact **and**
+  the neighbouring card that looks like it.
+- "go back to the folder" without saying how (browser back ≠ another tab plus refresh).
+- One step reading two screens: totals were hunted on a page that only shows subtotals. One step, one screen.
+- Two recipes on one environment destroying each other's witnesses through indirect writes — a save
+  that triggers a recomputation. Declare witnesses, run `uat order`, and re-measure after each pass.

package/src/bmad-plus/skills/bmad-plus-uat/ref/uat-results.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "bmad-plus/uat-results/2",
+  "title": "Human acceptance recipe — one run",
+  "description": "What the page writes: one document per run, never modified afterwards. A second pass is a second document. States use the evidence vocabulary of the framework: passed, failed, blocked (unavailable to the tester), skipped (optional step), null (unanswered).",
+  "type": "object",
+  "required": ["schema", "specId", "runId", "tester", "startedAt", "steps", "summary"],
+  "properties": {
+    "schema": { "const": "bmad-plus/uat-results/2" },
+    "specId": { "type": "string" },
+    "specSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Fingerprint of the spec the page was built from. Says WHICH revision the tester answered: if the spec was amended since, the run is stale and the affected steps are replayed."
+    },
+    "runId": { "type": "string", "pattern": "^[0-9a-z][0-9a-z-]{0,63}$", "description": "<YYYYMMDD>-<tester>-<4 chars>." },
+    "tester": { "type": "string" },
+    "observedVersion": { "type": "string", "description": "Version the tester actually saw on screen." },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "overallNote": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "required": ["passed", "failed", "blocked", "skipped", "unanswered"],
+      "properties": {
+        "passed": { "type": "integer" },
+        "failed": { "type": "integer" },
+        "blocked": { "type": "integer" },
+        "skipped": { "type": "integer" },
+        "unanswered": { "type": "integer" }
+      }
+    },
+    "steps": {
+      "type": "object",
+      "description": "Key = step id from the spec.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["expect"],
+        "properties": {
+          "title": { "type": "string" },
+          "state": { "enum": ["passed", "failed", "blocked", "skipped", null] },
+          "note": { "type": "string", "description": "Free remark for the whole step." },
+          "expect": {
+            "type": "object",
+            "description": "Key = expectation letter.",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "text": { "type": "string", "description": "Snapshot of the expectation as the tester read it." },
+                "state": { "enum": ["passed", "failed", "blocked", "skipped", null] },
+                "note": { "type": "string", "description": "What the tester saw instead, word for word — the most useful material there is." }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/bmad-plus/skills/bmad-plus-uat/ref/uat-spec.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "bmad-plus/uat-spec/2",
+  "title": "Human acceptance recipe (recette) — specification",
+  "description": "What an agent writes to describe a human acceptance run step by step. `bmad-plus uat build` turns it into a self-contained HTML page. Validation is performed by tools/cli/lib/uat.js; this file documents the contract.",
+  "type": "object",
+  "required": ["schema", "id", "product", "versions", "title", "environment", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema": { "const": "bmad-plus/uat-spec/2" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9.-]{2,80}$",
+      "description": "Stable identifier, lowercase: <product>-<versions>. Used as file name and storage key."
+    },
+    "product": { "type": "string", "minLength": 1 },
+    "versions": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+    "date": { "type": "string", "description": "ISO date the recipe was written." },
+    "language": { "enum": ["en", "fr"], "description": "Page strings. Defaults to English." },
+    "title": { "type": "string", "minLength": 1, "description": "What this delivery changes, in one sentence." },
+    "subtitle": { "type": "string" },
+    "environment": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "description": "DEMO, STAGING, PREPROD…" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "estimate": { "type": "string", "description": "e.g. \"25 min\". Over the configured budget, lint asks for a split." },
+    "intro": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted inline markup: what the measurement showed, with its numbers." },
+    "warnings": { "type": "array", "items": { "type": "string" }, "description": "Shown in orange: real writes, play order, prerequisites." },
+    "notes": { "type": "array", "items": { "type": "string" } },
+    "witnesses": {
+      "type": "array",
+      "description": "Named test records. `proof` is the read-only query that establishes the state; `reads`/`writes` list the steps. Two recipes sharing a witness get an order.",
+      "items": {
+        "type": "object",
+        "required": ["id", "proof"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "proof": { "type": "string", "minLength": 1 },
+          "reads": { "type": "array", "items": { "type": "string" } },
+          "writes": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "after": { "type": "array", "items": { "type": "string" }, "description": "Recipe ids that must be played before this one." },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "where", "do", "expect"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,60}$" },
+          "title": { "type": "string", "minLength": 1 },
+          "duration": { "type": "string" },
+          "writes": { "type": "boolean", "description": "True when the step persists something. Requires `verify`." },
+          "warning": { "type": "string", "description": "Replaces the default orange sentence; use it when the product must REFUSE the attempted action." },
+          "optional": { "type": "boolean", "description": "The tester may skip it; a skipped expectation never blocks the gate." },
+          "stories": {
+            "type": "array",
+            "description": "Traceability to the delivery's acceptance criteria.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "ref": { "type": "string" },
+                "criteria": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          },
+          "verify": {
+            "type": "object",
+            "required": ["kind", "text"],
+            "additionalProperties": false,
+            "description": "The read-only confirmation run AFTER the tester: a tick on a writing step is not a write.",
+            "properties": {
+              "kind": { "enum": ["sql", "http", "command", "manual"] },
+              "text": { "type": "string", "minLength": 1 }
+            }
+          },
+          "where": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "do": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "One click per line." },
+          "expect": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["id", "text"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "pattern": "^[a-z]$" },
+                "text": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "ONE verifiable observation, on-screen labels quoted word for word inside <span class=\"ecran\">…</span>. Lint refuses a label that exists in no source file."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "closing": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "text": { "type": "array", "items": { "type": "string" } } }
+    },
+    "authorNotes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The author's doubts (unverified witness, label to confirm). Ignored by the page, read by the reviewer."
+    }
+  }
+}

package/src/bmad-plus/skills/bmad-plus-uat/ref/uat-triage.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "bmad-plus/uat-triage/1",
+  "title": "Human acceptance recipe — triage of one or more runs",
+  "description": "Written by the agent after reading a run. Every failed or blocked expectation is classified and decided before it becomes a fix, and every passed writing step gets its read-only confirmation. The gate reads this file; an unclassified failure keeps it red.",
+  "type": "object",
+  "required": ["schema", "specId", "runs"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "bmad-plus/uat-triage/1" },
+    "specId": { "type": "string" },
+    "runs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["runId"],
+        "additionalProperties": false,
+        "properties": {
+          "runId": { "type": "string" },
+          "specSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "failures": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["step", "expect", "class", "decision"],
+              "additionalProperties": false,
+              "properties": {
+                "step": { "type": "string" },
+                "expect": { "type": "string", "pattern": "^[a-z]$" },
+                "class": {
+                  "enum": ["product", "recipe", "data", "undecided"],
+                  "description": "product: the screen differs from what the code was meant to render. recipe: the screen is right, the expectation described it wrongly. data: the witness is no longer in the assumed state. undecided: no note — ask the tester, never guess (keeps the gate red)."
+                },
+                "evidence": { "type": "string", "description": "What establishes the class: code path, query result, screenshot reference." },
+                "decision": { "enum": ["fix", "amend-spec", "remeasure", "accept-risk", "ask-tester"] },
+                "decidedBy": { "type": "string", "description": "Required for accept-risk: who took the risk." },
+                "fixRef": { "type": "string", "description": "Story, task or commit that carries the fix." },
+                "replayIn": { "type": "string", "description": "Recipe id where this step is played again." }
+              }
+            }
+          },
+          "writeChecks": {
+            "type": "array",
+            "description": "One entry per step with writes: true that the tester passed. A tick is an observation; this is the proof.",
+            "items": {
+              "type": "object",
+              "required": ["step", "verified"],
+              "additionalProperties": false,
+              "properties": {
+                "step": { "type": "string" },
+                "verified": { "type": "boolean" },
+                "evidence": { "type": "string", "description": "Read-only result: row timestamp, event, response." }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}