@mmerterden/multi-agent-pipeline 20.27.2 → 20.28.0

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -33,7 +33,7 @@ Run all steps automatically:
 ```
 Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 65 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 66 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
@@ -229,7 +229,7 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**65 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**66 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
@@ -241,7 +241,7 @@ prune-prompts, purge, refactor, research, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scaffold, scan, scenario-audit, search,
 security-review, serve, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
-test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
+test-dark-mode, test-dynamic-type, test-gen, test-screenshots, testflight-validation,
 uninstall, update
 ```
 

package/pipeline/skills/shared/core/multi-agent-test-gen/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: multi-agent-test-gen
+description: "Write the tests an app lacks, stage by stage, each gated on its artefact: inventory, read-only gap analysis, handles, tests, runs, per-test classification. Use when screens, flows or a change need tests."
+user-invocable: true
+argument-hint: "[scope] [--platform ios|android|web] [--repo <path>]  -  scope: a screen, route or flow, or empty for what changed since the last test-gen run"
+metadata:
+  language: en
+  not-for: test, bug-bash, scenario-audit, manual-test
+---
+
+# multi-agent-test-gen
+
+**Input**: $ARGUMENTS
+
+Writes the tests an app is missing, in the repo's own frameworks, and reports
+what they found. Seven stages run as subagents, each leaving one artefact that a
+script gates before the next stage starts: inventory, discovery, gaps, handles,
+write, run, classify. The two analysis stages run as a read-only agent type, so
+nothing they do can change the repository.
+
+Stage contract, read before Step 1:
+
+```
+$HOME/.claude/multi-agent-refs/test-gen/stages.md
+$HOME/.claude/multi-agent-refs/features/test-classification.md
+```
+
+Scripts: `test-gen-gate.mjs` (artefact, handle and write gates),
+`handle-diff-audit.mjs` (handles only), `test-classify.mjs`,
+`test-gen-state.mjs` (change base, revision cap), `evidence-gate.mjs`, all under
+`$HOME/.claude/scripts/`. Schemas: `test-gen-inventory`, `test-gen-gaps`,
+`test-gen-results` under `$HOME/.claude/schemas/`.
+
+## Gotchas
+
+- An analysis stage that wants to "just fix" something is out of its lane. Discovery and gaps go to `test-gen-analyst`, whose grant is an allowlist of read-only tools.
+- The handle stage adds handles and nothing else. A wrapped view, a renamed element or a changed condition fails `handle-diff-audit.mjs`; revert the hunk, do not argue with the audit.
+- `HANDLES: none-needed` is a claim that the handles exist. It needs the `file:line` of each.
+- A test that passed once is not green. Unstable is a fail, and a red test with no base to compare is `not_measured`, not a regression.
+- Test data is named in `dataNeeds[]`, never filled in by the run. A credential is a `secretRef`.
+- A product bug is reported, never fixed here. In autopilot it parks the run.
+
+## Step 1 - Prepare
+
+1. Repo: `--repo`, else the current directory; confirm it in one line.
+   Platform: `--platform`, else detect as `multi-agent-test` does. Run id
+   `tg-<timestamp>`; `RUN="$HOME/.claude/logs/test-gen/<repo>/<timestamp>"`,
+   created with `mkdir -p "$RUN"`.
+2. Toolkit: `test_results_classify`, `coverage_gap` and `ui_locator_codegen`
+   need `@mmerterden/multi-agent-toolkit-mcp` >= v3.25.0. Check the tool list
+   once. Each missing tool has a fallback in `stages.md` (classify from the
+   repeats, the analyst matches coverage itself with every match `inferred`,
+   locators written by hand from the handles); say which fallbacks are in use,
+   once.
+3. Change base. `TG_STATE="$HOME/.claude/knowledge/<project>/test-gen-state.json"`:
+
+   ```bash
+   node "$HOME/.claude/scripts/test-gen-state.mjs" base-scan --state "$TG_STATE" --repo "$REPO" \
+     --graph "$HOME/.claude/knowledge/<project>/code-graph.json" > "$RUN/base-scan.json"
+   ```
+
+   Exit 0: the changed files and their dependents narrow an empty scope. Exit 1
+   (`measured: false`, first run or base gone): nothing is narrowed, and the
+   reason goes in the report.
+
+## Step 2 - Inventory and priority
+
+Stage 1 of `stages.md`, then the priority pick: ask which items to cover
+(one question to the user; autopilot: the top three, recorded as `autopilot-top3`). Gate:
+
+```bash
+node "$HOME/.claude/scripts/test-gen-gate.mjs" check --stage inventory --file "$RUN/inventory.json"
+node "$HOME/.claude/scripts/evidence-gate.mjs" --claim artefact --status passed \
+  --evidence "$RUN/inventory.json" --stage-start "$STAGE_START"
+```
+
+## Step 3 - Discovery and gaps (read-only)
+
+Stages 2 and 3, both with `subagent_type: "test-gen-analyst"`. Write each answer
+with the Write tool, then gate each file with `evidence-gate.mjs --claim
+artefact` against its own stage start, and each with `test-gen-gate.mjs check`
+(`--stage discovery`, `--stage gaps`). Show the gaps (bucket, priority,
+expectation) and the `dataNeeds[]`; ask for the data or the credential names
+(autopilot: write only the scenarios whose needs are met).
+
+## Step 4 - Handles
+
+Stage 4. Snapshot first (`test-gen-gate.mjs baseline`), then the subagent, then
+both gates against that snapshot: `test-gen-gate.mjs handles` and
+`handle-diff-audit.mjs --baseline` exit 0. The gates read only the stage's own
+change; the person's uncommitted work is never the stage's to revert. Skip the
+stage when no gap has `handlesNeeded`, and say so.
+
+## Step 5 - Write, run, classify
+
+Stages 5 to 7: a new snapshot, the tests and `written.json`, the
+`test-gen-gate.mjs written --baseline` gate (test files only, inside the repo
+and changed by the stage, no test gaming, a discovered runner, more than zero
+tests run), the repeated runs, then
+`results.json` through `test-classify.mjs` and `test-gen-gate.mjs results`.
+
+## Step 6 - Triage
+
+Stage 8, one verdict per non-pass result, each through `test-gen-state.mjs
+revise`. Exit 3 parks the run: stop, keep every artefact, report why, and record
+no change base, because the run did not finish.
+
+## Step 7 - Report and base
+
+Print, in this order: the tests written (file, scenario, expectation), the
+results table from `results.json` with every `fail` and `not_measured` reason,
+the triage verdicts, the handles added (`handles.md`), the scenarios blocked by
+data, and `gaps.json`'s `unmeasured[]`. State which parts are mechanical (the
+gates, the classification, the handle audit) and which are judgement (the
+inventory, the gaps, the triage). Then record the change base
+(`test-gen-state.mjs base-record`).
+
+Offer, one question: open the product bugs through `multi-agent` with each
+failing test as the acceptance check, or stop. **No commit, no push, no issue
+from this command.**

package/pipeline/skills/shared/external/fix-review-verdicts/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: fix-review-verdicts
+description: "Independent fix review with three verdicts, test-gaming, scope and root-cause, each backed by file:line findings; the result is computed from findings, never from a claim. Use when reviewing a fix made to turn tests green. Not a full review checklist."
+metadata:
+  source: multi-agent-pipeline
+  version: 1.0.0
+---
+
+# Fix review verdicts
+
+Tests can be made green without fixing anything: hide the element only under
+test, branch on an automation flag, loosen a check, swallow the error. The
+tests pass and report nothing. Only someone reading the diff catches it, and
+that reader should not be the one who wrote the fix.
+
+## 1. Inputs
+
+The reviewer does not see the author's conversation. It reads:
+
+- the approved root-cause statement: what broke, where, and the agreed fix;
+- the diff;
+- the evidence runs: did the expected tests turn green, did the guard tests
+  stay green;
+- machine check results (lint, types, unit tests) from the project's own
+  approved commands;
+- the author's report, as a claim to verify, not as evidence.
+
+The reviewer changes no code. Its only output is the review.
+
+## 2. The three required verdicts
+
+Each one gets an explicit verdict and a reason.
+
+**test-gaming: `clean` | `violation`.** A violation is any of:
+
+- an environment branch in product code: `navigator.webdriver`,
+  `process.env.CI`, `window.Cypress`, a user-agent or URL-parameter check,
+  `ProcessInfo` arguments or environment, an `isRunningTests` flag, a
+  test-only build flag;
+- detecting automation, or showing or hiding an element only under test;
+- hard-coding the text or value the test looks for;
+- a swallowed error: an empty `catch`, a discarded `try?`, an ignored
+  `runCatching`;
+- a loosened product validation, an inflated timeout, a skipped or disabled
+  test;
+- an existing assertion, fixture or snapshot changed so that it accepts what
+  it used to reject (a weaker matcher, a widened tolerance, a re-recorded
+  snapshot, a fixture edited to dodge the bug) in a fix whose cause is in
+  product code.
+
+Not a violation: a new regression test that encodes the bug, fails on the
+unfixed code and passes on the fix. That is the bug-fix protocol (a failing
+test first), and it is expected. Check it actually fails without the fix; a
+new test that passes on the unfixed base proves nothing and is a suggestion
+finding.
+
+**scope: `clean` | `violation`.** The diff touches only the approved cause.
+Unrelated files, reformatting, opportunistic refactors, lockfile or dependency
+changes and configuration changes are violations.
+
+**root-cause: `root` | `symptom`.** Does the fix remove the cause or suppress
+the result? Fixing contrast by hiding the element, overflow by clipping it, an
+error by deleting its message, a race by retrying until it passes, or bad
+input by clamping it are symptoms.
+
+## 3. Findings
+
+```json
+{ "severity": "blocking", "area": "test-gaming", "file": "src/cart/Total.tsx", "line": 42, "note": "returns the expected total when navigator.webdriver is set" }
+```
+
+- `severity`: `blocking` or `suggestion`.
+- `area`: `test-gaming`, `scope`, `symptom`, `correctness`, `security`,
+  `performance`, `maintainability`, `accessibility`.
+- Each verdict maps to one finding area: test-gaming `violation` to area
+  `test-gaming`, scope `violation` to area `scope`, root-cause `symptom` to
+  area `symptom`. Every such verdict comes with at least one blocking finding
+  in its area. A correctness or security defect is blocking.
+- A suspicion without a line to show is a suggestion with its reason. A line
+  that shows test-gaming, scope creep or a symptom fix is blocking, without
+  hedging.
+
+## 4. Computing the result
+
+The result is derived, never declared. An author's "all green", a reviewer's
+"looks good" and a summary field saying passed are ignored. It has three
+states: `passed`, `blocked`, `not_measured`.
+
+```
+VERDICT_AREA = {test-gaming: violation -> test-gaming,
+                scope: violation -> scope,
+                root-cause: symptom -> symptom}
+
+if the review was never submitted:
+    result = not_measured
+elif any of the three verdicts is missing or outside its allowed values:
+    result = not_measured            # an invalid review measures nothing
+else:
+    for each (verdict, value) -> area in VERDICT_AREA that matches:
+        if no blocking finding exists in that area:
+            add a blocking finding in that area, built from the verdict's reason
+    for each machine check:
+        failed on the fix and not on the base   -> blocking finding (correctness)
+        changed the working tree                -> blocking finding (checks read, never write)
+        failed on the base as well              -> preexisting: reported, not blocking
+        had no approved command (undefined)     -> unmeasured check
+        could not run (tool missing, timeout)   -> unmeasured check
+    if any finding is blocking:
+        result = blocked
+    elif any unmeasured check:
+        result = not_measured
+    else:
+        result = passed
+```
+
+`blocked` wins over `not_measured`: a known defect is reported even when part
+of the review could not run. `not_measured` never counts as `passed`; the fix
+does not ship on it, and the report names what was not measured and why.
+
+## 5. Output
+
+The structured review (three verdicts with reasons, findings, a two to four
+sentence summary) and a report: each verdict with its reason, the findings
+with `file:line`, and a "could not measure" section.
+
+## Related
+
+- The stack's review rubric for the general pass: `ai-android-toolkit`
+  `reference/review-checklist`, `ai-ios-toolkit:ios-coding-standard`, and the
+  built-in `/code-review`.
+- `security-review` when the diff touches auth, input handling or secrets.
+- `test-result-triage`, which decides whether a red test was a product bug
+  before any fix is written.

package/pipeline/skills/shared/external/handle-request/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: handle-request
+description: "Add the test handles a scenario needs and answer each request with ADDED, ALREADY or COULD NOT ADD plus file:line or reason. Identity values only, attribute-only diffs; iOS accessibilityIdentifier, Compose testTag, web data-testid. Use when a test needs an element handle the UI lacks."
+metadata:
+  source: multi-agent-pipeline
+  version: 1.0.0
+---
+
+# Handle request
+
+A handle is the identifier a test finds an element by: it does not change with
+copy, locale or layout. This step adds the handles a scenario list asks for,
+and nothing else.
+
+## 1. Input
+
+A list of requests, usually the "handles needed" section of
+`scenario-gap-analysis`. Each request names the element, the screen, a
+proposed identifier and the scenario it unblocks.
+
+## 2. One answer per request
+
+| Answer | When |
+|---|---|
+| `ADDED file:line` | The handle was added at that line. |
+| `ALREADY file:line` | A usable handle already exists there; give its value. |
+| `COULD NOT ADD reason` | It was not added. The reason is specific: element rendered by a third-party view, identifier must come from a shared schema that lacks the key, repository is read-only, the element is not exposed to the accessibility tree and exposing it would change what assistive technology hears. |
+
+No other answer exists. A request that is half done is split into the part
+added and the part that could not be.
+
+## 3. Rules
+
+- **Identity, never position.** A row carries the item's id
+  (`order_row_{orderId}`), never the loop index, which shifts when the list is
+  reordered or filtered. Do not rewrite a list-rendering expression to obtain
+  an index or an id; if the id is not in scope, answer COULD NOT ADD.
+- **Attribute-only diffs.** Add identifier attributes or modifiers. No logic,
+  state, flow, data, styling, renames or deletions. Anything a line loses must
+  reappear in the added line.
+- **Stable names.** Screen-scoped, descriptive, independent of visible text
+  and locale (`cart_checkout_button`). Follow the project's existing naming
+  scheme and, where it generates identifiers from a shared schema, use the
+  generated constant; a key missing from the schema is added upstream, so the
+  answer is COULD NOT ADD with that reason.
+- **One pass.** Write every requested handle before building. On mobile each
+  build costs minutes; one handle per build turns a step into hours.
+- **Out of bounds.** Build files, manifests and permissions, signing,
+  dependencies. No commit: leave the diff for a human.
+
+## 4. The handle has to be visible where the test runs
+
+A handle in source that the test driver cannot see is worse than none: it
+looks done. For each handle, confirm it reaches the tree the test reads:
+
+| Platform | Handle | Seen by the driver only when |
+|---|---|---|
+| iOS (SwiftUI, UIKit) | `accessibilityIdentifier` | the element is in the accessibility tree: not hidden, not merged into a parent element |
+| Android (Compose) | `Modifier.testTag` | inside the app's Compose tests always; for UI Automator based drivers only under `testTagsAsResourceId` on an ancestor |
+| Android (Views) | `android:id` | the view is laid out and not excluded from accessibility |
+| Web | `data-testid` (or the project's configured test id attribute) | the component forwards it to the DOM and the build under test does not strip it |
+| Flutter | `Semantics(identifier: ...)` for external drivers; `Key` for in-process tests | a `Key` works with `find.byKey` inside `flutter test` and integration tests, but never reaches the accessibility tree, so an external driver (XCUITest, UI Automator, Maestro, Appium) needs the `Semantics` identifier |
+
+Verify against the running app when a build loop exists: a UI tree dump
+(`ios_get_ui_tree`, `android_get_ui_tree`), a DOM query or `web_find`. When no
+build loop is available in this step, the report says "not verified on device"
+and gives the build and install commands for a human. Never claim a check that
+did not run.
+
+The stack plugins carry the platform detail: `ai-ios-toolkit:handle-request`,
+`ai-android-toolkit:handle-request`, `ai-frontend-toolkit:handle-request`.
+
+## 5. Check the diff before finishing
+
+- `git diff -U0` shows added handle lines; their count is greater than zero
+  unless every answer is ALREADY or COULD NOT ADD.
+- Every removed line comes back in an added line with only the identifier
+  added.
+- No file outside the UI sources the requests point to.
+
+## 6. Report
+
+```
+cart_checkout_button   ADDED      src/cart/CartFooter.tsx:31
+order_row_{orderId}    ALREADY    src/orders/OrderRow.tsx:12 (data-testid="order-row-{id}")
+map_pin                COULD NOT ADD  rendered by a third-party map view with no identifier API
+```
+
+Then: a diff summary (files, lines changed), the scenarios these handles
+unblock, and what was not verified on device, with the reason.
+
+## Related
+
+- `scenario-gap-analysis` produces the requests.
+- `test-result-triage` sends a locator-not-found result here before calling a
+  test stale.
+- `e2e-testing` for the locator order a test uses once the handle exists.

package/pipeline/skills/shared/external/scenario-gap-analysis/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: scenario-gap-analysis
+description: "Set an inventory against existing tests, sort each behaviour into COVERED, WRONGLY COVERED or MISSING, and write gaps as measurable, prioritised scenarios with cross-screen flows. Use when planning tests or auditing coverage. Not for writing tests or judging a run."
+metadata:
+  source: multi-agent-pipeline
+  version: 1.0.0
+---
+
+# Scenario gap analysis
+
+Decide **what** has to be tested, and why. How to test it belongs to the
+writing step. The output is a ranked list of measurable scenarios that a test
+writer can turn into code without asking what was meant.
+
+## 1. Read before you call anything missing
+
+Gather the inputs first, and read all of them:
+
+- **Inventory**: screens, modules, flows or endpoints in scope, from a design
+  scenario inventory, a site map, a UI tree, or exploration reports.
+- **Existing tests**: the test tree and any test catalogue. Search it for every
+  behaviour before listing that behaviour as a gap.
+- **Regression history** where the project keeps one: past bugs, regression
+  maps, incident notes. A case that broke before is the first candidate.
+- **Exploration notes**: what someone saw the product actually do.
+
+Match tests to inventory items by **identifier** (accessibility identifier,
+test id, route, endpoint path), never by a name that merely sounds similar.
+When a match is inferred rather than read, say so on that line.
+
+## 2. Three buckets
+
+| Bucket | Meaning |
+|---|---|
+| **COVERED** | A test exercises the behaviour and its assertion would fail if the behaviour broke. |
+| **WRONGLY COVERED** | A test exists and stays green while the defect is present. |
+| **MISSING** | No test exercises the behaviour. |
+
+WRONGLY COVERED is the most valuable bucket, because the suite reports safety
+it does not provide. Typical shapes:
+
+- A text scan over rendered text that never sees content injected as markup.
+- A visibility filter that passes a broken image because its width is zero.
+- An assertion on the HTTP status that passes while the body carries an error.
+- A test that seeds the store or mocks the handoff it claims to verify.
+- An existence check where the value is what matters (a total, a date, a count).
+
+For every WRONGLY COVERED line, name the test (`file:line`) and the defect it
+cannot see.
+
+## 3. Scenario schema
+
+Each MISSING or WRONGLY COVERED behaviour becomes one scenario:
+
+| Field | Content |
+|---|---|
+| Title | Usable as the test name. |
+| Priority | `bug-catching` (broke before or likely to, hurts the user directly: data, money, dates, a dead end in the funnel, leaked copy keys) / `edge` (empty, error, boundary, slow network, back navigation, session expiry, flag combinations) / `baseline` (happy path, element present). |
+| Business reason | Who loses what, or which revenue or compliance risk it carries. "Nice to have" is not a reason. |
+| Preconditions | Account, data and state the scenario needs, and where each comes from. |
+| Steps | What the user does. |
+| Measurable expectation | A claim a test can check exactly: a value, a label, a route, an element present or absent. A scenario with no measurable expectation is not written. |
+| Automation | `yes` / `no` (stays a manual check, still listed) / `needs-code` (name the missing handle or hook). |
+| Handles needed | Identity-carrying handles the test will locate by, for the handle step. |
+| Data needs | What test data the scenario requires. The agent states the need; a human supplies the value. Never invent a credential. |
+| Flakiness risk | Third-party scripts, live content, timing. Say it up front. |
+
+The machine-readable shape and a worked example are in
+[references/scenario-schema.md](references/scenario-schema.md).
+
+## 4. Cross-screen flows (at least two)
+
+Write at least two scenarios that walk a user path across screens. Only an
+analysis that has seen the whole module can write them, and they catch the
+class of defect screen tests cannot: screen A does not write the state screen
+B reads. Both screens are green on their own and the flow is broken.
+
+Rules for a flow scenario:
+
+- Every step uses the state the previous step left. No seeding a store, no
+  injecting state, no deep link or direct route to an intermediate screen.
+- Enter from the first screen and move forward the way a user does.
+- Mock only noise outside the flow (a cookie banner, an analytics beacon),
+  never the data the flow carries: whether it is carried is the measurement.
+- A long flow may be split into segments, each starting where the previous one
+  ended, with no seeding inside a segment.
+
+Screen scenarios may seed state and deep link; they measure the screen's own
+resilience. Flow scenarios may not.
+
+When the scope cannot hold two flows (a single screen, a module with one
+entry and no onward path), write the ones it holds and record the shortfall
+under could-not-measure with the reason. Never pad the count with a flow that
+seeds its own state.
+
+## 5. Judgement rules
+
+- Do not propose what is already covered. A covered case listed as missing is
+  noise, not analysis.
+- Platforms differ. Device permissions and backgrounding have no web
+  equivalent; browser back, reload, deep links, horizontal overflow and
+  keyboard navigation are web-specific.
+- Ask for handles that carry identity (`data-order-id`, a row keyed by the
+  item id), never a list index, which moves when the order changes.
+- Open with "do these three first". An unranked list of twenty is not usable.
+
+## 6. Could not measure
+
+A separate section, always present. Each line names what could not be
+measured, why (no account, environment down, screen unreachable, data
+missing), and what would make it measurable. The absence of a measurement is
+not a positive result and never folds into COVERED.
+
+## 7. Output order
+
+1. The top three, with one line each on why.
+2. Bucket table: behaviour, bucket, test `file:line` where one exists.
+3. Scenarios in priority order, flows included and marked as flows.
+4. Handles needed, grouped by screen.
+5. Data needs.
+6. Could not measure.
+
+## Related
+
+- API and service gaps: `ai-backend-toolkit:scenario-gap-analysis` adds the
+  envelope, contract and service-chain rules.
+- Adding the handles the scenarios ask for: `handle-request`.
+- Judging a run of the written tests: `test-result-triage`.
+- Driving a running app to observe behaviour first: `e2e-testing`.

package/pipeline/skills/shared/external/scenario-gap-analysis/references/scenario-schema.md

@@ -0,0 +1,60 @@
+# Scenario schema
+
+One JSON object per scenario. Field names are the contract a test writer or a
+pipeline step reads; values follow the rules in `SKILL.md`.
+
+```json
+{
+  "id": "cart-total-after-coupon",
+  "title": "Cart total reflects a percentage coupon after quantity change",
+  "bucket": "WRONGLY_COVERED",
+  "coveredBy": "tests/cart/coupon.spec.ts:42",
+  "defectNotSeen": "asserts the coupon badge exists, never the total",
+  "priority": "bug-catching",
+  "businessReason": "A wrong total charges the customer a different amount than shown",
+  "kind": "screen",
+  "preconditions": ["signed-in account with an empty cart", "coupon code valid for 10 percent"],
+  "steps": ["add item A", "apply coupon", "change quantity to 3"],
+  "expectation": "total label equals 3 x unit price x 0.9, rounded to 2 decimals",
+  "automation": "yes",
+  "handles": ["cart_total_label", "cart_item_quantity_{itemId}"],
+  "dataNeeds": [{ "name": "coupon-10-percent", "supplied": "human" }],
+  "flakinessRisk": "none known"
+}
+```
+
+| Field | Values |
+|---|---|
+| `bucket` | `COVERED`, `WRONGLY_COVERED`, `MISSING` |
+| `coveredBy` | `file:line` of the existing test, or null for MISSING |
+| `priority` | `bug-catching`, `edge`, `baseline` |
+| `kind` | `screen` or `flow` |
+| `automation` | `yes`, `no`, `needs-code` (with the reason in `automationNote`) |
+| `dataNeeds[].supplied` | always `human` for credentials and personal data |
+
+## A flow scenario
+
+```json
+{
+  "id": "flow-browse-to-confirmation",
+  "title": "Item chosen on the list arrives unchanged on the confirmation screen",
+  "bucket": "MISSING",
+  "priority": "bug-catching",
+  "kind": "flow",
+  "steps": [
+    "open the catalogue from the home screen",
+    "open item A and pick size M",
+    "add to cart and go to checkout",
+    "confirm"
+  ],
+  "expectation": "confirmation shows item A, size M, the price shown on the item screen",
+  "rules": "no store seeding, no direct route to checkout, no mock of the cart request",
+  "automation": "yes"
+}
+```
+
+## Could-not-measure entry
+
+```json
+{ "what": "refund screen", "why": "no account with a completed order", "needs": "a seeded order supplied by a human" }
+```