bmad-plus 0.17.1 → 0.19.0

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

@@ -87,6 +87,60 @@ Deliver in the way the host allows, and say so plainly:
 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`).
 
+### What the page guarantees — and what you check before a person opens it
+
+A run takes tens of minutes. The tester answers in passing, opens the product in another
+tab, comes back, reloads. On 2026-09-25 a page built outside this command showed its steps
+before any run existed: every tick was displayed and none was kept, a reload emptied the
+form, and the status read "saved" on nobody's word. What follows exists so that this
+cannot happen again, on any project.
+
+**The page is built, never written.** Persistence lives in one place, the template that
+`bmad-plus uat build` fills. Do not hand-write an acceptance page, do not re-implement
+saving in a project, do not edit the produced HTML. A page that needs something the
+template lacks is a change to the template, made in BMAD+ with its tests.
+
+**What every built page guarantees, by construction** (`uat build --json` lists them under
+`guarantees`, and the build refuses a template that lost one):
+
+| Guarantee | What the tester gets |
+|---|---|
+| `hidden-before-start` · `no-answer-before-run` | no answer field before a run exists, whatever a stylesheet says; a tick before that is refused and explained, never dropped |
+| `verified-local-write` · `honest-save-status` | a write counts only once it reads back; the status names a refused save ("Could not save in this browser — save or copy the JSON") and never says "saved" otherwise |
+| `save-on-every-change` | every tick and every keystroke in a note is kept at once, no blur needed, and the cursor never moves |
+| `restore-before-capabilities` · `newer-copy-wins` | the browser's copy comes back synchronously on reload, before any optional capability answers; an older remote copy never overwrites a newer local one |
+| `revision-guard` | a run that answered another revision of the recipe is offered, not poured in: identical lines keep their answers, changed lines are asked again, the earlier run stays untouched and exportable (`carriedFrom` in the results) |
+| `other-tab-notice` | two tabs on one run converge on the latest change, and the page says so |
+| `unreadable-draft-kept` | a saved run that cannot be read is reported and exportable, never deleted |
+| `progress-accessible` | the share of lines *answered* — not passed — as a `progressbar` with its value, next to the seen / not seen / blocked counts |
+| `storage-explained` | where the answers live and what makes them disappear (site data cleared, private window closed), and that nobody receives them until the JSON is handed over |
+| `finished-is-not-accepted` · `unload-guard` | unanswered lines are said on the page before finishing (a second click finishes anyway); finishing keeps the date and says it is not an acceptance; leaving with an unsaved run is questioned |
+| `utf8-and-escaped-diacritics` · `export-is-the-run` | UTF-8 declared, diacritics handled as escapes, and the exported JSON is the run as answered |
+
+**Before a person opens the page**, in this order, and say in the delivery which ones ran:
+
+1. `bmad-plus uat lint <id> --src <dir>` passes.
+2. `bmad-plus uat build <id>` writes the page and lists its guarantees.
+3. Open the built page in a real browser and play the essential pass yourself: no answer
+   field before starting → enter a name and start → tick one *Seen* → tick one *Not seen* →
+   type a remark without leaving the field → type an overall remark → **reload at once,
+   without clicking anywhere** → everything is back and the progress says two lines are
+   answered. `tools/qa/uat-page-browser-check.js` in the BMAD+ repository is this pass,
+   automated; the framework's own suite (`tests/unit/uat-page.test.js`) replays every
+   scenario of the incident, storage refusal and revision change included.
+4. Run these where the project's execution policy allows: if tests do not run on this
+   machine, run them on the project's remote environment. Never skip them to save time.
+
+If any of these fail, the page is **not ready** — say so, and do not hand it over. A page
+handed over without step 3 is handed over with that fact written next to it.
+
+**Tell the tester where the answers live**, in one sentence, before the link: in the artifact
+database (saved on every tick, nothing to send), in the project through `uat serve`, or in
+their browser — on that device only, until they save the JSON. The page says it too.
+
+**When the recipe is amended** after a run started, tell the tester their earlier run will be
+offered on the new page and that only unchanged lines keep their answers.
+
 ## 3. Read, triage, gate
 
 ```bash
@@ -144,7 +198,10 @@ keeps acceptance out of reach; the fix task carries the run and the triage entry
 - 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.
+  not a recipe. Checking that the *page* keeps answers (the pass above) is not playing the recipe:
+  it proves the form, not the product.
+- It does not write pages by hand. Persistence is the template's, tested in BMAD+; a project that
+  needs more changes the template, not its copy of the page.
 
 ## Pitfalls already paid for
 
@@ -156,3 +213,6 @@ keeps acceptance out of reach; the fix task carries the run and the triage entry
 - 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.
+- A page written outside `uat build`, with its own persistence: the steps showed before the run
+  existed, ticks were dropped, a reload lost everything, and "saved" was printed unverified
+  (FormaPro, 2026-09-25). Build the page; check it in a browser; say which checks ran.

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

@@ -20,6 +20,17 @@
     "updatedAt": { "type": "string", "format": "date-time" },
     "finishedAt": { "type": ["string", "null"], "format": "date-time" },
     "overallNote": { "type": "string" },
+    "carriedFrom": {
+      "type": "object",
+      "description": "Present when the page continued a run that answered another revision of the recipe. The rule is fixed: an answer travelled only when its line was identical (same step, same letter, same text); every other line was asked again. The earlier run is left untouched.",
+      "required": ["runId", "kept", "toAnswer"],
+      "properties": {
+        "runId": { "type": "string", "description": "The run the answers came from." },
+        "specSha256": { "type": ["string", "null"], "description": "The revision that run answered; null when it carried no fingerprint." },
+        "kept": { "type": "integer", "description": "Answers that travelled." },
+        "toAnswer": { "type": "integer", "description": "Lines of this revision left unanswered by the carry." }
+      }
+    },
     "summary": {
       "type": "object",
       "required": ["passed", "failed", "blocked", "skipped", "unanswered"],