@qaping/cli 0.1.1 → 0.1.2

package/bin/qaping

@@ -44,7 +44,8 @@ const RULE_BODY = `This machine has qaping: automatic QA for games — real huma
 Whenever the user asks to set up QA for a game, run QA on a patch, check whether a change broke anything, or playtest a game or build, load the qaping skill and follow it — it owns authoring/maintaining QA-PLAN.md in the game repo and the per-patch run.
 Builds ship with \`qaping publish-build <game.zip> --platform windows|macos\`; the printed /b/<slug> URL is what a round is filed against (store-delivered games file with their Steam/TestFlight/App Store URL instead).
 The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a finished round, free) and qaping_wait (continue a pending round — whenever a filing or wait returns pending, call qaping_wait again immediately; never report pending as the answer).
-Playtests are duration-billed at 2 credits per minute of play per playtester — state the estimated cost before filing. Windows rounds return a recording + questionnaire and no transcript; never promise one.
+Playtests are duration-billed at 2 credits per minute of play per playtester — state the estimated cost before filing. Windows rounds return a recording and no transcript; web rounds return answers only (no recording, no transcript) — never promise evidence a platform does not ship.
+QA memory: whenever the developer mentions — in ANY conversation, not just QA runs — something that should always be tested, a fragile area, or a QA lesson learned, offer to record it as a check (or a note on an existing check) in QA-PLAN.md so it is tested from then on.
 `;
 
 // The wrapper object harness/setup.js's opts.wrapper API takes; also the one

package/docs/QA-PLAN-FORMAT.md

@@ -12,15 +12,16 @@ YAML at the very top of the file:
 ---
 game: Solar Drift
 build_command: ./scripts/package.sh --release   # the ONE command that produces a shippable build
-platforms: [windows]                            # windows | macos | ios
+platforms: [windows]                            # windows | macos | ios | web
 input: XInput gamepad                           # optional; default keyboard+mouse
 ---
 ```
 
 `build_command` is recorded once at setup so every future run can build without
-asking. `input` declares the hardware the first-15-minutes check (and any check
-that needs it) is played on — rounds must ask playtesters to confirm what they
-actually used.
+asking. `platforms: [web]` means a browser-playable game — its "build" is a
+static directory, not a zip. `input` declares the hardware the
+first-15-minutes check (and any check that needs it) is played on — rounds
+must ask playtesters to confirm what they actually used.
 
 ## Checks
 
@@ -30,19 +31,38 @@ opens with a fenced yaml block, then the steps as prose:
 ```yaml
 id: save-loads            # stable slug — never reused, never renamed
 rung: human               # human | code
+state: unverified         # unverified | passed | ambiguous | failing
 origin: authored          # "authored", or the round id that minted/last changed it
 last_verified: 2026-08-25 # date or build tag of the last passing verification
+setup: "?save=campaign-mid"  # optional: the link/flag that forces this check's precondition
 ```
 
 - **Steps are prose for a person**: numbered, imperative, written so a
-  playtester who has never seen the game can follow them — they become the
-  round's instructions verbatim.
+  playtester who has never seen the game can follow them. At filing time each
+  check becomes ONE id-tagged step with typed verdict options, so end the
+  steps in an observation ask ("describe what you saw"), never a
+  confirmation ("confirm it appears").
+- **`state` is the check's verdict history**: `unverified` (never verified on
+  the current behavior), `passed` (last verified answer was Pass),
+  `ambiguous` (a fail that could be dirty state or tester noise — refiles
+  alone as a targeted round), `failing` (a fail backed by hard evidence or a
+  targeted round). Blocked/VOID outcomes change nothing here.
+- **`setup` names the test affordance** that forces the check's precondition —
+  a URL param (`?fresh=1`, `?state=<checkpoint>`), a flag, a bundled-fixture
+  load control. The filed step then starts with "open <exact link>". A check
+  whose precondition can be neither forced nor verified is testimony-only —
+  say so in its prose.
+- **Fixtures are provisioned by the dev's repo**: a previous-version save
+  ships inside the build (or seeds via URL param on web) and is named in the
+  check's steps — an anonymous playtester in a fresh browser cannot possess
+  it.
 - **Order the file critical-path first**: boots to menu, previous-version save
   loads, first 15 minutes on the declared input hardware, core loop, settings
   persist — then game-specific checks.
 - A `rung: code` check keeps its prose (it documents intent) and adds one
   `test:` line naming the repo test that now asserts it, e.g.
-  `` test: `tests/save_compat.test.ts` ``.
+  `` test: `tests/save_compat.test.ts` ``. Mechanically-assertable checks
+  enter at `rung: code` on day one — human rounds are for judgment.
 
 ## Example section
 
@@ -52,20 +72,51 @@ last_verified: 2026-08-25 # date or build tag of the last passing verification
 ```yaml
 id: save-loads
 rung: human
+state: unverified
 origin: authored
-last_verified: 2026-08-25
+last_verified: never
+setup: "?save=campaign-mid"
 ```
 
-1. From the main menu, choose Continue.
-2. Load the provided save "campaign-mid.sav" (made on the previous release).
-3. Confirm the game resumes in the desert outpost with the inventory intact.
-4. Play for one minute; note anything missing, corrupted, or visually wrong.
+1. Open the game with the provided link (it loads the save "campaign-mid.sav",
+   made on the previous release, from the build's bundled fixtures).
+2. Play for one minute in the desert outpost.
+3. Describe what you saw: where you resumed, what the inventory held, and
+   anything missing, corrupted, or visually wrong.
 ````
 
+## The round ledger — qa-rounds.jsonl
+
+Beside the plan, at the game repo root, sits `qa-rounds.jsonl`: one JSON line
+appended per round, committed alongside the plan updates —
+
+```json
+{"round_id": "…", "report_url": "…", "build": "<sha or hosted url>",
+ "evidence_grade": "…", "checks": [{"id": "…", "outcome": "…"}],
+ "verdict": "…", "credits": 20, "follow_ups": ["…"]}
+```
+
+Outcomes are `Pass | Fail | Blocked | NOT-ASKED` — a VOID (precondition
+unverified/disproven) is recorded as `Blocked` with a "VOID: …" note in the
+report, never its own enum value. `report_url` is the round's service report
+page (what the results tool returns), never a PR or issue link. There is no
+evidence-link field, deliberately: signed recording URLs expire in days.
+The ledger is the machine truth of what was asked and answered, per check,
+per round; the plan's `last_verified` and `state` are derived from it and
+stay the dev-readable contract. Open `follow_ups` are what the next filing
+must carry forward.
+
 ## Maintenance rules
 
-- Every run updates the run checks' `last_verified`; findings-driven edits
-  record the round id as `origin`.
-- New checks start `rung: human`, `origin: authored`.
+- Every run updates the run checks' `state` and `last_verified` from typed
+  outcomes (Pass stamps both; Blocked/VOID/NOT-ASKED touch neither);
+  findings-driven edits record the round id as `origin`.
+- New checks start `rung: human` (unless mechanically assertable — then
+  `rung: code` with a repo test written at entry), `state: unverified`,
+  `origin: authored`.
 - Promotion (human → code) and any deletion/demotion happen only with the
   developer's explicit agreement.
+- **QA memory**: the plan accretes from conversation, not just QA runs — when
+  the developer mentions something that should always be tested, a fragile
+  area, or a lesson learned, the agent offers to record it as a check (or a
+  note on an existing check) right then.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaping/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "qaping: automatic QA for your game. Your coding agent authors and maintains the QA plan, ships each patch's build to real human playtesters, and reports what broke.",
   "keywords": [
     "qaping",

package/skill/qaping/SKILL.md

@@ -6,31 +6,56 @@ description: Run automatic QA for a game repo through qaping — real human play
 # qaping — the QA loop for a game repo
 
 Two jobs, one file. SETUP authors `QA-PLAN.md` — the committed list of checks
-this game must pass. RUN executes it per patch: pick the affected checks, build,
-ship the build to real human playtesters, report what they found. Over patches,
-checks migrate from human rounds to repo code tests, so QA gets cheaper. All
-service contact goes through three MCP tools — `qaping_playtest`,
-`qaping_results`, `qaping_wait` — plus `qaping publish-build` for hosting
-the build.
+this game must pass. RUN executes it per patch: pick the affected checks,
+build, ship the build to real human playtesters, and report ONE typed outcome
+per check — never a vibe. The check is the unit of value: its id rides from
+the plan onto the wire, into the report, and into the round ledger. Over
+patches, checks migrate from human rounds to repo code tests, so QA gets
+cheaper. All service contact goes through three MCP tools —
+`qaping_playtest`, `qaping_results`, `qaping_wait` — plus
+`qaping publish-build` for hosting the build.
 
 ## Ground rules (read before filing anything)
 
 - **Playtesters are real people.** A session takes real minutes to be claimed
   and played. File, then `qaping_wait`; whenever a filing or wait returns
-  pending, immediately call `qaping_wait` again with the same ping_id. Never
-  report pending as the final answer, never file a duplicate round.
+  pending, immediately call `qaping_wait` again with the same ping_id — keep
+  polling, or the round goes invisible to new claimants when the lease lapses.
+  Never report pending as the final answer, never file a duplicate round.
 - **Costs are duration-billed**: 2 credits per minute of play, per playtester
-  (`est_minutes × 2 × players`). State the estimate to the user BEFORE filing.
-- **Windows rounds return a recording + questionnaire and NO transcript**
-  (`transcript_status:'unavailable'`) — never promise one; plan to watch the
-  recording for timestamps. macOS and iOS rounds include an inline [mm:ss]
-  think-aloud transcript.
-- **Machine replay is not self-serve yet.** Never claim an automated replay ran.
-  The only automated rung you can run today is a `rung: code` test in the
-  dev's own repo/CI.
+  (`est_minutes × 2 × players`). State the estimate to the user BEFORE filing,
+  and set the wait expectation honestly in the same message: claim time is
+  unbounded on a small pool — "push now or wait for QA" is their call, made
+  informed.
+- **Evidence varies by platform — never promise what a platform does not
+  ship.** macOS and iOS rounds return a screen+voice recording plus an inline
+  [mm:ss] think-aloud transcript. Windows rounds return a recording and NO
+  transcript (`transcript_status:'unavailable'`) — never promise one; plan to
+  watch the recording for timestamps. WEB rounds return answers only — no
+  recording, no transcript: the tester's option picks and free text are the
+  entire deliverable, which is why every check rides an option step.
+- **Pay is flat per session, never per bug.** Never offer or imply a bounty.
+  Never steer a tester's OS-security decision (stopping at a warning is their
+  penalty-free call); steering their PLAY — steps, links, forced states — is
+  the job.
+- **Machine replay is not self-serve yet.** Never claim an automated replay
+  ran. The only automated rung you can run today is a `rung: code` test in
+  the dev's own repo/CI.
 - **QA-PLAN.md is the dev's file.** Commit it only with their approval; never
   delete or demote a human check without them agreeing.
 
+## Know your tester
+
+The person who claims your round is on their phone, scrolling a feed. They
+read `instructions` BEFORE claiming — front-load hardware and requirements
+there so the wrong tester never claims. They play with your steps visible on
+the same small screen, with zero context and no dev tools; attention is
+highest in the first minutes; setup friction is unpaid time. So: one action
+per step, exact UI labels (the button says "Continue", not "the resume
+option"), the most important check first, state-sensitive checks forced by a
+link (see "Make the build testable"), and never a step that assumes they read
+your repo.
+
 ## SETUP — author QA-PLAN.md (first run in a repo)
 
 1. Read the game repo: engine, how a shippable build is produced, save system,
@@ -39,92 +64,230 @@ the build.
    shippable build) and which platforms they ship; record both in the plan's
    frontmatter so every future run can build without asking again.
 3. Author `QA-PLAN.md` at the repo root in EXACTLY this format (self-contained
-   here — do not go looking for other docs). Plan frontmatter (YAML at the very
-   top): `game`, `build_command` (the ONE shippable-build command), `platforms:
-   [windows|macos|ios|web]` (`web` = a browser-playable game — its "build" is a
-   static directory, not a zip), optional `input` (hardware; default
-   keyboard+mouse, or touch for a mobile-web game).
+   here — do not go looking for other docs). Plan frontmatter (YAML at the
+   very top): `game`, `build_command` (the ONE shippable-build command),
+   `platforms: [windows|macos|ios|web]` (`web` = a browser-playable game — its
+   "build" is a static directory, not a zip), optional `input` (hardware;
+   default keyboard+mouse, or touch for a mobile-web game).
    Then one `##` section per check — the heading is the check's short name —
-   opening with a fenced yaml block of exactly `id` (stable slug, never
-   renamed), `rung: human | code`, `origin` ("authored" or the round id that
-   last changed it), `last_verified` (date or build tag), followed by the steps
-   as numbered prose a playtester who has never seen the game can follow (they
-   become the round's instructions verbatim). A `rung: code` check keeps its
-   prose and adds one `test:` line naming the repo test that asserts it. Order
-   checks critical-path first, then game-specific ones:
+   opening with a fenced yaml block of `id` (stable slug, never renamed),
+   `rung: human | code`, `state` (`unverified | passed | ambiguous | failing`
+   — new checks start `unverified`), `origin` ("authored" or the round id that
+   last changed it), `last_verified` (date or build tag), and optionally
+   `setup` (the link or flag that forces this check's precondition — see
+   "Make the build testable"), followed by the steps as numbered prose a
+   playtester who has never seen the game can follow. Author each check to
+   end in an observation ask, with its precondition stated as a verifiable
+   step-zero fact (forced by `setup`, else verified by an opening question).
+   A `rung: code` check keeps its prose and adds one `test:` line naming the
+   repo test that asserts it. Order checks critical-path first, then
+   game-specific ones:
    1. the game boots to the main menu
    2. a previous-version save loads
    3. the first 15 minutes play clean on the declared input hardware
    4. the core loop works (name it concretely — the thing this game is)
    5. settings persist across a restart
-   Every check carries `{id, rung, origin, last_verified}`. New checks start
-   `rung: human`, `origin: authored`.
-4. Tell the dev how runs get triggered, honestly: for now the loop runs from
+4. **Enter each check at the right rung.** A check that is mechanically
+   assertable — a save file loads, a config parses, an asset path resolves —
+   enters at `rung: code` from day one: write the repo test then and there,
+   never "start it human and promote later". Human rounds are reserved for
+   what only a human can judge. Where a save must still be human-tested, the
+   dev provides the fixture: the previous release's save ships inside the
+   build (or seeds via URL param on web), named in the check's steps — a
+   stranger in a fresh browser cannot possess your old save.
+5. **Gyms**: for a mechanic worth isolating, you may build a tiny
+   deterministic test scene or page in the dev's repo — one mechanic,
+   machine-readable pass/fail. Ordinary dev work; offer it, never force it.
+6. Tell the dev how runs get triggered, honestly: for now the loop runs from
    their own machine or agent — after a patch lands, they say "run QA on this
-   patch" and the RUN half below executes. Do NOT offer to wire a CI workflow
-   file: a plain CI runner has no qaping MCP connection and no login, so a
-   committed workflow could not run this loop today. A CI-triggered recipe is
-   a documented follow-up; until it ships, per-patch QA is an ask-your-agent
-   step.
-5. Show the dev the plan and commit only on their approval.
+   patch". Do NOT offer to wire a CI workflow file: a plain CI runner has no
+   qaping MCP connection and no login, so a committed workflow could not run
+   this loop today; a CI-triggered recipe is a documented follow-up. Until it
+   ships, per-patch QA is an ask-your-agent step.
+7. Show the dev the plan and commit only on their approval.
+
+## Make the build testable
+
+Before publishing a test build, you SHOULD add test affordances to the dev's
+own code — ordinary dev work that turns self-reported state into forced,
+verifiable state:
+
+- URL params or flags that force states: `?fresh=1` (a true first visit),
+  `?difficulty=medium`, `?state=<checkpoint>` (start at a checkpoint).
+- Bundled save fixtures plus a load control (the previous release's save,
+  shipped in the build).
+- Seeded randomness, so a reported oddity reproduces.
+- A corner build stamp (build hash + first-run/save-state flag; a `?qa=1`
+  overlay on web) with a step asking the tester to read it back — a read-back
+  fact is verified; self-report is not.
+
+Record each check's hook in its `setup` field; that check's filed step then
+STARTS with "open <exact link>". The unreviewed-developer-build disclosure
+already covers shipping these; the no-steering rule forbids steering SAFETY
+decisions only. A store-delivered build that cannot surface state keeps its
+checks testimony-only — mark that in the plan and report at that grade.
 
 ## RUN — per patch
 
 1. **Select.** Read the diff (or PR). Pick the checks it can plausibly affect,
-   plus the always-run criticals (the critical-path block above). Tell the user
-   which checks run and why.
-2. **Build** via the recorded build command; zip the result (native) or keep
-   the built static directory (web).
-3. **Ship**, by delivery: NATIVE uploads — `qaping publish-build <game.zip>
+   plus the always-run criticals (the critical-path block above) and every
+   check the ledger left NOT-ASKED or Blocked last round. Tell the user which
+   checks run and why.
+2. **Compose sessions.** Partition the selected checks by required state —
+   fresh-install / progression / settings-mutating — and put state-mutating
+   checks LAST within their session. Budget play content: sum the checks'
+   directed play time; if it exceeds est_minutes, split into parallel
+   5-minute rounds (credit-neutral: two focused 5-minute rounds cost one
+   diluted 10-minute round) or raise est_minutes within the cap, and state
+   the trade beside the cost estimate. Depth beyond the budget rotates across
+   patches; note in the plan which slice ran last.
+3. **Build** via the recorded build command, with each selected check's
+   `setup` affordance in place; zip the result (native) or keep the built
+   static directory (web).
+4. **Ship**, by delivery: NATIVE uploads — `qaping publish-build <game.zip>
    --platform windows|macos` → prints a `/b/<slug>` URL (temporary hosting;
    filing a playtest extends the build through the round; each publish mints a
    NEW URL). Store-delivered games file with their Steam store page, TestFlight
    public link, or App Store page as `url`. WEB games — host the built output
    at a public URL: the dev's own hosting if they have it, else
    `qaping publish <built-dir>` prints a hosted URL. Localhost never works —
-   players open the link on their own devices.
-   When filing a WEB game: send `url` + `est_minutes` and OMIT `platform`
-   entirely (platform values are for native builds; a web round is claimed by
-   players in their own browser, phones included).
-4. **File** ONE `qaping_playtest` per batch of human checks a single session
-   can cover, `est_minutes` an honest sum of the steps — the service accepts
-   5–30 minutes (10 is the standard session; outside that range the filing is
-   refused, not clamped), and the clock is play time: download/install happens
-   before it starts. The authored
-   `instructions` + `steps` must embed:
-   - the selected checks' steps, in play order (the plan's prose, verbatim
-     where possible);
-   - the previous round's findings as context — "last round reported X —
-     recheck" — so regressions get re-examined on every patch;
-   - the hardware-verification convention: when the game needs more than
-     keyboard+mouse, say so up front in `instructions` (playtesters self-select
-     before claiming) AND add an explicit step asking which input device was
-     actually used, with options — the answer comes back verified in
-     `steps_result`.
-   For a regression batch that knows exactly what it is testing, send
-   `questionnaire:'none'` so your steps are the only questions; leave the
-   standard questionnaire on for a first baseline round.
-5. **Wait:** `qaping_wait` until results arrive (see ground rules).
-6. **Report** from `qaping_results`:
-   - PR comment via `gh pr comment`: ONE verdict sentence first, then one line
-     per check — ✅/❌ with a recording timestamp ([mm:ss] from the transcript
-     where present; from watching the recording on Windows) — then credits
-     spent.
-   - One `gh issue create` per CONFIRMED bug: title, repro steps rebuilt from
-     the playtester's answers, a timestamp link into the recording. Issues are
-     drafts for the dev's own triage — never near-duplicates, never one issue
-     per symptom of the same bug.
-   - Update `QA-PLAN.md`: each run check's `last_verified` becomes this
-     build/date; a check changed because of this round records the round id as
-     `origin`.
+   players open the link on their own devices. When filing a WEB game: send
+   `url` + `est_minutes` and OMIT `platform` entirely — a web round is claimed
+   by players in their own browser, phones included.
+5. **File** ONE `qaping_playtest` per composed session, always with
+   `questionnaire:'none'` — on a QA-PLAN round your checks are the questions;
+   the standard instrument is a separate experience round (below), never a
+   default. est_minutes is an honest sum of the steps' directed play — the
+   service accepts 5–30 minutes (10 is the standard session; outside that
+   range the filing is refused, not clamped), and the clock is play time:
+   download/install happens before it starts. The authored steps MUST be:
+   - **one step per selected check**, its text opening with the id token —
+     `[spin-readable] …` — the plan prose rewritten as an observation
+     question ("describe what the start menu showed and what you tapped
+     first", never "confirm the menu appears"), with options exactly
+     ["Pass — as described", "Fail — describe exactly what you saw",
+     "Couldn't test — say why", "Didn't reach this part"] — the pick comes
+     back verified in steps_result;
+   - a check with a `setup` hook opens "open <exact link>"; one whose
+     precondition cannot be forced opens with a verifying option step
+     ("Before opening: had you ever played this game before?" — yes / no /
+     not sure);
+   - a recheck of a prior finding is a clearly-labeled step at its natural
+     play-order point (first when its required state demands it, last
+     otherwise) — "VERIFY FIX: last round saw X — does it still happen?" —
+     and prior findings stay OUT of `instructions` entirely, so the rest of
+     the pass is an independent look;
+   - a closing **break-it slice** (~2–3 minutes) authored from the diff:
+     "this patch changed X — try to break it: <concrete abuse ideas from the
+     diff>. Report the weirdest thing you saw AND list what you tried."
+     Finding nothing is a fine answer when we know what was attempted; frame
+     it in `instructions` as "these checks are the territory — break anything
+     near them";
+   - hardware verification where it matters: needs beyond keyboard+mouse go
+     up front in `instructions` AND an explicit step asks which input device
+     was actually used, with options.
+   **Filing gate (MUST):** print `this round covers: <ids>` per session and
+   assert the ids — unioned across every session this run files — equal the
+   Select step's list BEFORE calling qaping_playtest. A mismatch (e.g. the
+   20-step cap forcing cuts) fails loudly PRE-SPEND: batch another session or
+   state the deferral out loud — never silently truncate.
+6. **Wait:** `qaping_wait` until results arrive (see ground rules).
+7. **Report** from `qaping_results`:
+   - **Evidence line first (MUST).** Every report opens with its grade:
+     `Evidence: recording + transcript` (macOS/iOS) / `Evidence: recording
+     only` (Windows) / `Evidence: testimony only (web round)`.
+   - **Computed headline (MUST).** Derive the one verdict sentence from the
+     per-check outcomes, never from the tester's own verdict: `PASS` only
+     when every selected check returned Pass; `PASS — N unverified (<ids>)`
+     when nothing failed but any check is Blocked or NOT-ASKED; `FAIL: <id>`
+     on any Fail. Quote the tester's global verdict beneath it as one input —
+     it is never the headline. (The iterate rule already says unresolved
+     findings mean fix and refile — unresolved never headlines as PASS.)
+   - **One row per SELECTED check (MUST)**, keyed by id, outcome from
+     {Pass, Fail, Blocked, NOT-ASKED}. "Couldn't test" and "Didn't reach this
+     part" are Blocked, with the why. A check whose precondition came back
+     unverified or disproven is VOID — report it as Blocked ("VOID:
+     precondition unverified"), never as a pass or fail, and leave
+     `last_verified` untouched. A selected check that never made the wire or
+     never came back is NOT-ASKED and carries forward into the next filing
+     automatically. Cite [mm:ss] where a transcript or recording exists; on a
+     web round cite the step answers — there are no timestamps to cite.
+   - PR comment via `gh pr comment`: evidence line, the computed verdict
+     sentence first, then the per-check rows, then credits spent.
+   - **Ledger append (MUST).** Append ONE JSON line to `qa-rounds.jsonl` at
+     the game repo root, committed alongside the plan updates:
+     `{"round_id": …, "report_url": …, "build": "<sha or hosted url>",
+     "evidence_grade": …, "checks": [{"id": …, "outcome": …}], "verdict": …,
+     "credits": …, "follow_ups": […]}`. `report_url` is the round's service
+     report page (the `report_url` the results tool returns — never a PR or
+     issue link). No evidence-link field, deliberately: signed recording URLs
+     expire in days, so durable evidence pointers live in the report/issues,
+     not the ledger. The ledger is machine truth;
+     `last_verified` stays in QA-PLAN.md as the dev-readable contract derived
+     from it, and "carry findings forward" is a read of the last line's
+     follow_ups, not prose archaeology.
+   - Update `QA-PLAN.md` from the outcomes: Pass → `state: passed` and
+     `last_verified` this build/date; a Fail with hard evidence → `failing`;
+     a Fail that could be dirty state or tester noise → `ambiguous`;
+     Blocked/NOT-ASKED touch nothing. A check changed because of this round
+     records the round id as `origin`.
+   - **QA memory (standing rule, not just here)**: whenever the developer
+     mentions — in any conversation — something that should always be tested,
+     a fragile area, or a QA lesson learned, offer to record it as a check
+     (or a note on an existing check) in `QA-PLAN.md` right then, so the plan
+     accretes knowledge instead of losing it to chat scrollback.
+   - Issues: one `gh issue create` per finding — drafts for the dev's own
+     triage, never near-duplicates, never one issue per symptom of the same
+     bug. Before reproduction the body carries "observed once, unreproduced"
+     plus a proposed severity from consequence (blocks progress / degrades /
+     cosmetic). The label CONFIRMED is reserved for a targeted round or
+     unambiguous in-round evidence; a CONFIRMED issue carries repro steps
+     rebuilt from the tester's answers and a timestamp link into the
+     recording where one exists (web rounds have none — cite answers).
+
+## The ambiguity ladder
+
+An `ambiguous` or first-time-failing check never re-runs inside the next
+batch — it refiles ALONE as a targeted ~5-minute round: one check, its
+precondition forced via `setup` (or verified by the opening option step),
+plus the disambiguation steps. That round settles it: Pass → `passed` (note
+the fluke); Fail → `failing`, and the issue upgrades to CONFIRMED. Never
+resolve an ambiguity by re-buying the whole batch, and never label a
+once-seen fail CONFIRMED without that round or hard evidence.
+
+## Differential rounds (web feel checks)
+
+A feel/physics/balance regression judged absolute buys little — a stranger
+answers "did spin feel right" in a vacuum. On WEB builds, where switching
+costs seconds, such a check MAY file as ONE session carrying BOTH builds:
+publish the previous build alongside the current one (the ledger's `build`
+field makes it recoverable), put the second URL in `instructions`, and author
+the steps as "play 2 minutes on build A, then build B — name anything that
+changed and where". est_minutes honestly covers both halves. Caveat the
+report: a tester told to hunt changes reports noise as change, and order
+effects apply. Store-delivered and uploaded native builds stay single-build —
+no second-URL surface exists for them.
+
+## The experience round (opt-in, never a default)
+
+The standard 11-item player-experience questionnaire never rides a QA-PLAN
+round. Offer it separately, at milestones, as an experience round: no checks
+attached, questionnaire left on, n_target up to 3 players, priced
+transparently (est_minutes × 2 × players — state it first). Single-tester
+scores are trend data — meaningful only after 3+ rounds on the same game,
+never compared across testers or builds at n=1. If 8 or more of the 11 scale
+answers are identical, report "low-differentiation response — treat scores as
+unreliable" and never average them into a comparison.
 
 ## PROMOTE — make the suite cheaper
 
 When a check has passed and is mechanically assertable — a save file loads, a
 config parses, an asset path resolves — offer to write a normal test in the
-repo's own test suite. On the dev's yes: write the test, flip the check's
+repo's own test suite; the ledger's per-check pass history is the evidence
+that justifies the offer. On the dev's yes: write the test, flip the check's
 `rung` to `code`, keep the prose (it documents intent) and add a `test:` line
 naming the test file. `rung: code` checks then run in the dev's own CI for
-free — that is the point: every check starts human and gets cheaper over time.
-Checks about feel, difficulty, or ambiguous visuals stay `rung: human`
-permanently. Never delete or demote a human check without the dev agreeing.
+free — that is the point: every check starts as human as it must and gets
+cheaper over time. Checks about feel, difficulty, or ambiguous visuals stay
+`rung: human` permanently. Never delete or demote a human check without the
+dev agreeing.