@qaping/cli 0.1.1 → 0.1.4

package/bin/qaping

@@ -43,8 +43,9 @@ function resolveKitDir() {
 const RULE_BODY = `This machine has qaping: automatic QA for games — real human playtesters play the developer's builds on their own hardware and report back, and the coding agent runs the whole loop.
 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.
+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 — on pending, spawn a background task that loops qaping_wait and keep working; foreground polling is the fallback, and never report pending as the answer or end with an unbacked promise to check later).
+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,41 @@ 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. At filing time the hook rides the ROUND's `url` — the review
+  interface loads it itself; testers cannot open links or type URLs — and
+  the filed step states only the player-visible expectation, never the
+  mechanism. 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 +75,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. The game opens already loaded into the save "campaign-mid.sav" (made on
+   the previous release; the round's link forces it — no action needed).
+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.4",
   "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,92 @@ 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.
+- **Playtesters are real people, and waiting is background work.** A session
+  takes real minutes to be claimed and played, and the wait chain matters: each
+  `qaping_wait` renews the lease that keeps the round visible to new claimants.
+  The moment a filing returns pending, SPAWN A BACKGROUND TASK that loops
+  `qaping_wait` with the ping_id until results arrive, and keep working on
+  other things — that is the intended shape, the same as every pingfusi round.
+  Only if your harness has no background tasks: keep polling in the foreground.
+  Only in a one-shot print mode where neither is possible: say plainly that the
+  round is pending, give the ping_id, and ask to be re-invoked to continue —
+  never promise polling you cannot do (an ended session cannot poll; a round
+  went invisible and expired unclaimed exactly this way, live). 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.
 
+## The review interface (know your tester)
+
+<!-- Distilled from QAPING_REVIEWER_INTERFACE.md (monorepo root, INTERNAL,
+     code-cited). Re-derive there when a reviewer surface changes. -->
+
+Binding, derived from the review interfaces' code. The person who claims a
+web 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. On claim the game auto-loads into an embedded browser
+view with your steps beside it on the same small screen, with zero context;
+attention is highest in the first minutes; setup friction is unpaid time.
+
+The tester CAN: play the already-loaded game (touch, scroll, type); go
+Back; Reload — which KEEPS storage, so a reload is never a fresh state; see
+all steps at once and answer in any order; tap ONE option per option step;
+type a note on any question step; pin a comment to a page element and draw
+on it; pick one verdict; bail out with a reason.
+
+The tester CANNOT:
+- open tabs or windows — window.open and target=_blank links are dead
+  INSIDE the game too, so a game whose Play button opens a new window is
+  broken-for-review: flag it to the dev instead of filing;
+- type or edit a URL: the round's `url` is the only page-load there is, and
+  links in step text are inert on the phone — never put links in steps;
+- clear storage or go incognito: fresh state comes ONLY from a setup URL
+  param the round's `url` already carries;
+- use devtools, attach files, or record — web rounds return answers only;
+- use a second device;
+- see `instructions` or `expected` once inside the review — EVERYTHING the
+  tester needs at answer time lives in the step text (≤300 chars each).
+
+**Steps speak player language (MUST).** Things to tap and see in the game —
+never flags, URL parameters, storage, or code concepts. A test hook is
+exercised by the ROUND's `url` carrying it; the step describes only the
+player-visible expectation ("the How to play option should be offered
+first"), never the mechanism. Never ask to close/reopen anything or "start
+fresh" — that state is a separate round whose `url` forces it. And as
+always: one action per step, exact UI labels (the button says "Continue",
+not "the resume option"), the most important check first, 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 +100,261 @@ 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; at filing time the hook
+rides the ROUND's `url` — the game loads it itself, so the tester never
+sees or types it — and the filed step states only the player-visible
+expectation. 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. A session has ONE state: its round
+   `url` (carrying the forcing setup param) is the only state control that
+   exists — testers cannot clear storage or start fresh themselves — so
+   checks needing different forced states never share a 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. A WEB session additionally files `require_evidence:'none'`
+   (MUST) — left at its default, the finish silently demands a pinned
+   screenshot-comment no step asked for. 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. EXCEPTION: when the check asks the
+     tester to DISCRIMINATE between named states ("which difficulty did the
+     bot play like?", "which screen did you land on?"), the options are the
+     NAMED candidates themselves ("rookie-level" / "harder than that") plus
+     "Couldn't tell — say why" — generic Pass/Fail on a discrimination
+     yields contradictions instead of a signal (measured live);
+   - option labels ≤40 chars, 2–4 options per step; never author a final
+     step whose options duplicate the verdict options — the phone hides it
+     as a duplicate of the verdict control;
+   - a check with a `setup` hook is forced by filing the session's `url`
+     WITH the hook — the game loads it itself; the step states only the
+     player-visible expectation. One whose precondition cannot be forced
+     opens with a verifying option step ("Before this session: 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."
+     Abuse ideas target PLAYER-VISIBLE behaviors the diff changed — things a
+     player can tap, see, or provoke — never internal mechanisms (a flag, a
+     cache, a storage key means nothing to a player).
+     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. The wire keeps only
+   the FIRST 20 steps_result rows and a play directive is prepended, so with
+   `questionnaire:'none'` budget at most 19 authored steps per session (8 if
+   the standard questionnaire rides) — rows past 20 are answered by the
+   tester and silently dropped at finish, which is why this gate exists. A
+   mismatch (the budget forcing cuts) fails loudly PRE-SPEND: batch another
+   session or state the deferral out loud — never silently truncate.
+6. **Wait, in the background:** spawn a background task looping `qaping_wait`
+   and keep working (see ground rules) — foreground polling is the fallback,
+   and a promise to check later is never a wait.
+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 that reached the wire as more
+     than one row (a precondition step, a VERIFY FIX pair) takes its outcome
+     from the WORST row: any Fail → Fail; else any Blocked or unanswered row
+     leaves the check unverified and the headline counts it ("PASS — N
+     unverified") — never plain Pass over a Blocked sub-step. 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.
+
+## Paired rounds (two-state comparisons)
+
+A feel/physics/balance regression judged absolute buys little — a stranger
+answers "did spin feel right" in a vacuum. But a comparison never rides one
+round: never two links in one round — links in step text are inert on the
+phone and `instructions` go unread in-review, so a second URL simply never
+gets opened. When a check needs TWO states compared (with/without a hook,
+old build vs new), file TWO paired rounds with the SAME steps, one per
+state, each state forced by its own round `url` (the ledger's `build` field
+keeps the old build recoverable), and compare the answers yourself in the
+report. Caveat it: different testers played each side, and a tester told to
+hunt changes reports noise as change. Native builds pair the same way, one
+build per round — re-publish the previous zip if its /b/<slug> expired.
+
+## 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.