@qaping/cli 0.1.0 → 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
@@ -183,12 +184,21 @@ function cmdPublishBuild(argv) {
     .main(argv.slice(1), { brandCommand: "qaping publish-build", nextStepToolName: "qaping_playtest" });
 }
 
+function cmdPublish(argv) {
+  // WEB games: their "build" is a static directory, hosted (not zipped) — the
+  // kit's hosted-draft publisher, brand-seamed like publish-build above. The
+  // printed URL files as `url` on qaping_playtest with NO platform field.
+  return require(path.join(resolveKitDir(), "harness", "publish.js"))
+    .main(argv.slice(1), { brandCommand: "qaping publish" });
+}
+
 const HELP = `qaping — automatic QA for your game: real human playtesters, driven by your coding agent
 
 usage:
   qaping setup [claude-code|cursor|codex] [--force]
   qaping remove [--client <c>]        remove qaping's MCP entries, skill and rule
   qaping publish-build <game.zip> --platform windows|macos
+  qaping publish <built-dir>          host a WEB game's built output (prints the URL to file with)
   qaping wait <ping_id> [--timeout <seconds>]
   qaping whoami
   qaping version
@@ -202,6 +212,7 @@ function route(cmd) {
   if (cmd === "remove" || cmd === "uninstall") return "remove";
   if (cmd === "wait" || cmd === "whoami") return "vendor";
   if (cmd === "publish-build") return "publish-build";
+  if (cmd === "publish") return "publish";
   return "unknown";
 }
 
@@ -217,6 +228,7 @@ function main() {
       // vendored default (the stock mount's wait) is not on /api/mcp/qaping.
       case "vendor": return process.exit(spawnVendor(argv[0] === "wait" ? [...argv, "--wait-tool", "qaping_wait"] : argv));
       case "publish-build": return void cmdPublishBuild(argv);
+      case "publish": return void cmdPublish(argv);
       default:
         console.error(HELP);
         process.exit(1);

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.0",
+  "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

@@ -1,36 +1,61 @@
 ---
 name: qaping
-description: Run automatic QA for a game repo through qaping — real human playtesters play the developer's builds on their own hardware, and the agent runs the whole loop. Use when the user says "set up QA for my game", "run QA on this patch", "did this patch break anything", "playtest my game" or "playtest this build", or asks for regression checks, patch verification, or human playtesting of a game. Covers both halves of the product - authoring and maintaining QA-PLAN.md in the game repo, and the per-patch run (read the diff, build, publish-build, file qaping_playtest rounds, report on the PR, file issues, promote settled checks into repo code tests). Do not use for web apps, websites, or UI review of anything that is not a game build — the qaping tools test game builds only.
+description: Run automatic QA for a game repo through qaping — real human playtesters play the developer's builds on their own hardware, and the agent runs the whole loop. Use when the user says "set up QA for my game", "run QA on this patch", "did this patch break anything", "playtest my game" or "playtest this build", or asks for regression checks, patch verification, or human playtesting of a game. Covers both halves of the product - authoring and maintaining QA-PLAN.md in the game repo, and the per-patch run (read the diff, build, publish-build, file qaping_playtest rounds, report on the PR, file issues, promote settled checks into repo code tests). Browser-playable web GAMES count as games (they file as web rounds — url only, no platform). Do not use for web apps, websites, or UI review of anything that is not a game — the qaping tools test games only.
 ---
 
 # 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,
@@ -38,75 +63,231 @@ the build.
 2. Ask the dev ONCE for their build command (the one command that produces a
    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, format per `docs/QA-PLAN-FORMAT.md`
-   (shipped with this package — read it first). Order checks critical-path
-   first, then game-specific ones:
+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).
+   Then one `##` section per check — the heading is the check's short name —
+   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.
-3. **Ship:** `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). A store-delivered
-   game files with its Steam store page, TestFlight public link, or App Store
-   page as `url` instead.
-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`.
+   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 — 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.