@qaping/cli 0.2.0 → 0.3.0

package/bin/qaping

@@ -15,6 +15,7 @@
 //   qaping wait <ping_id> [--timeout <seconds>]
 //   qaping results <ping_id>                           one passive fetch, no blocking
 //   qaping rounds [add|rm]                             the parked rounds this repo is owed
+//   qaping issues <game>                               the game's issue board, read-only
 //   qaping whoami | version | help
 "use strict";
 const fs = require("fs");
@@ -50,11 +51,12 @@ function resolveKitDir() {
 // writes it to ~/.claude/rules/qaping.md and ~/.cursor/rules/qaping.mdc.
 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). Hosted builds are temporary and capped per account — if a publish is refused for that cap, \`qaping builds\` lists them and \`qaping builds rm <slug>\` frees a slot; free one and carry on rather than stopping to ask, taking the ones marked as never-finished uploads first and never deleting a build a round you filed is still running against.
-The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a round, free) and qaping_wait (continue a pending round).
+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). Hosted builds are kept until you delete them (pass \`--expires-in-hours <n>\` to have one reaped instead) and capped per account — if a publish is refused for that cap, \`qaping builds\` lists them and \`qaping builds rm <slug>\` frees a slot; free one and carry on rather than stopping to ask, taking the ones marked as never-finished uploads first and never deleting a build a round you filed is still running against.
+The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a round, free), qaping_wait (continue a pending round) and qaping_issues (the game's issue board — file a bug, claim a fix, close or reopen; free).
+Bugs live on that board, not in chat or in a report nobody re-reads: file EVERY playtest with \`game\` set to the QA plan's game_slug, so the game's open and claimed-fixed issues ride the round as the playtester's checklist. You can only ever CLAIM a fix (qaping_issues action:'fixed', with the exact build URL the next round will play, claimed BEFORE that round is filed) — only a playtester answering "Gone" on a later round marks one verified, and a "Still here" on a claimed fix regresses it. \`qaping issues <game>\` reads the same board from the shell.
 Decide at filing time how the round ends: a short round waits in place — the moment filing returns pending, spawn a background task that loops qaping_wait and keep working (foreground polling is the fallback); a long or overnight round is PARKED — file it with an explicit long deadline_seconds, record it immediately with \`qaping rounds add <ping_id>\` (it writes qa-open-rounds.json beside QA-PLAN.md), tell the user exactly what is pending, and end the turn; a later session collects it (\`qaping rounds\` lists them with live status, qaping_results fetches one).
 A recorded parked round is an honest pending end — never report pending as the answer without one, and never 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.
+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 a transcript only when the tester recorded with our recorder app (read transcript_status on each result — a Game Bar session has no transcript); web rounds return answers only (no recording, no transcript) — never promise evidence a session 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.
 `;
 
@@ -255,13 +257,18 @@ const ROUNDS_FILE = "qa-open-rounds.json";
 // what `qaping rounds` costs in requests.
 const MAX_OPEN_ROUNDS = 20;
 const PING_ID_RE = /^[0-9a-f-]{36}$/i;
+// The issue board's game slug. Mirrors lib/qa-issues.ts's GAME_SLUG_RE and
+// migration 066's column check exactly — a slug this refuses is a slug the
+// service refuses, and finding that out before the network is the point.
+const GAME_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 const DEFAULT_APP_URL = "https://pingfusi.com";
 
 const ROUNDS_USAGE = `usage:
   qaping rounds [--json] [--offline] [--file <path>]
   qaping rounds add <ping_id> [--platform windows|macos|ios] [--build <url>]
                               [--minutes N] [--deadline-seconds N]
-                              [--checks a,b,c] [--note "<patch>"] [--json]
+                              [--game <slug>] [--checks a,b,c]
+                              [--note "<patch>"] [--json]
   qaping rounds rm <ping_id> [--json]`;
 
 function flagValue(argv, name) {
@@ -440,6 +447,9 @@ function renderRounds(entries, opts) {
     lines.push("");
     lines.push(`  ${record.ping_id}${facts ? ` — ${facts}` : ""}`);
     if (record.build) lines.push(`    build: ${record.build}`);
+    // Which board's issues rode this round — the later session that collects
+    // it needs the slug to read what moved (`qaping issues <game>`).
+    if (record.game) lines.push(`    game: ${record.game}`);
     if (Array.isArray(record.checks) && record.checks.length) lines.push(`    checks: ${record.checks.join(", ")}`);
     if (record.note) lines.push(`    patch: ${record.note}`);
     if (live) lines.push(`    ${roundStatusLine(record, live)}`);
@@ -493,13 +503,14 @@ function resolveTokenFromClientConfigs(kitDir) {
   return null;
 }
 
-// One passive tools/call against the qaping mount — the same transport and the
-// same JSON-or-SSE parse the kit's `wait` leg uses, with the mount read from the
-// ONE wrapper object every other command is driven by. Passive: it never renews
-// the round's lease, which is exactly why a parked round needs its own explicit
-// deadline. Failures are TYPED for the caller: `authRejected` and `perRound`
-// separate "this login is dead" from "the service refused this one id".
-async function callResultsTool(pingId) {
+// One passive tools/call against the qaping mount, for ANY tool it registers —
+// the same transport and the same JSON-or-SSE parse the kit's `wait` leg uses,
+// with the mount read from the ONE wrapper object every other command is driven
+// by. Passive: it never renews a round's lease, which is exactly why a parked
+// round needs its own explicit deadline. Failures are TYPED for the caller:
+// `authRejected` and `perRound` separate "this login is dead" from "the service
+// refused this one call".
+async function callQapingTool(name, args) {
   const w = qapingWrapper();
   const kitDir = resolveKitDir();
   const { resolveToken } = require(path.join(kitDir, "packages", "core", "wire.js"));
@@ -518,7 +529,7 @@ async function callResultsTool(pingId) {
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
-        params: { name: "qaping_results", arguments: { ping_id: pingId } },
+        params: { name, arguments: args },
       }),
       signal: AbortSignal.timeout(20_000),
     });
@@ -551,10 +562,18 @@ async function callResultsTool(pingId) {
     status: structured.status || "pending",
     structured,
     result,
+    // A tool that refuses inside a successful JSON-RPC result (the board at
+    // its cap, a seq that is not there) answers with isError + the same text.
+    isError: result.isError === true,
     text: (result.content && result.content[0] && result.content[0].text) || "",
   };
 }
 
+/** The results tool, by name — every caller below reads the same shape. */
+function callResultsTool(pingId) {
+  return callQapingTool("qaping_results", { ping_id: pingId });
+}
+
 async function cmdResults(argv) {
   const json = argv.includes("--json");
   // Flags in any position: `qaping results --json <id>` is the natural thing to
@@ -584,6 +603,52 @@ async function cmdResults(argv) {
   process.exit(0);
 }
 
+const ISSUES_USAGE = "usage: qaping issues <game> [--json] [--status open|fixed|verified|closed]";
+const ISSUE_STATUSES = ["open", "fixed", "verified", "closed"];
+
+/** argv after the command, minus flags and the values they consume — so a
+ *  slug that happens to equal a flag's value is still the positional. */
+function positionalArgs(argv, valueFlags) {
+  const out = [];
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) {
+      if (valueFlags.includes(argv[i])) i++;
+      continue;
+    }
+    out.push(argv[i]);
+  }
+  return out;
+}
+
+/**
+ * The game's issue board, read-only. The agent moves issues through the MCP
+ * tool; this is the human's window on the same board — and it prints the
+ * SERVICE's own rendering rather than a second one, so the board a developer
+ * reads in the shell and the board an agent reads mid-run cannot disagree.
+ */
+async function cmdIssues(argv) {
+  const json = argv.includes("--json");
+  const game = positionalArgs(argv, ["--status"])[0];
+  if (!game || !GAME_SLUG_RE.test(game)) {
+    console.error(`✗ not a game slug: ${game || "(missing)"} — lowercase letters, digits and hyphens.\n${ISSUES_USAGE}`);
+    // 1, like `results`: a typo must never reach the network, and 2 is
+    // reserved by the round verbs for "still pending".
+    process.exit(1);
+  }
+  const status = flagValue(argv, "--status");
+  if (status !== undefined && !ISSUE_STATUSES.includes(status)) {
+    console.error(`✗ --status must be one of ${ISSUE_STATUSES.join(", ")}.\n${ISSUES_USAGE}`);
+    process.exit(1);
+  }
+  const args = { game, action: "list" };
+  if (status) args.status_filter = status;
+  const r = await callQapingTool("qaping_issues", args);
+  console.log(json
+    ? JSON.stringify(Object.keys(r.structured).length ? r.structured : r.result, null, 2)
+    : (r.text || JSON.stringify(r.result, null, 2)));
+  process.exit(r.isError ? 1 : 0);
+}
+
 async function cmdRoundsList(argv) {
   const json = argv.includes("--json");
   const state = readRoundsFile(roundsFilePath(argv));
@@ -650,6 +715,13 @@ function cmdRoundsAdd(argv) {
     console.error(`✗ --platform must be windows, macos or ios — a web round has none, so omit it.\n${ROUNDS_USAGE}`);
     process.exit(2);
   }
+  // Validated here, not just recorded: a slug the service would refuse is a
+  // board the collecting session could never read.
+  const game = flagValue(argv, "--game");
+  if (game !== undefined && !GAME_SLUG_RE.test(game)) {
+    console.error(`✗ --game must be a slug: lowercase letters, digits and hyphens (the QA plan's game_slug).\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
   const file = roundsFilePath(argv);
   const minutes = intFlag(argv, "--minutes");
   const deadline = intFlag(argv, "--deadline-seconds");
@@ -658,6 +730,7 @@ function cmdRoundsAdd(argv) {
   const build = flagValue(argv, "--build");
   const patch = {};
   if (platform) patch.platform = platform;
+  if (game) patch.game = game;
   if (build) patch.build = build;
   if (minutes != null) patch.est_minutes = minutes;
   if (deadline != null) patch.deadline_seconds = deadline;
@@ -741,6 +814,7 @@ usage:
   qaping rounds                       the parked rounds this repo is owed, with live status
   qaping rounds add <ping_id> …       record a parked round so a later session collects it
   qaping rounds rm <ping_id>          forget one, once it is collected or expired
+  qaping issues <game>                the game's issue board (read-only; the agent moves it)
   qaping whoami
   qaping version
 
@@ -757,6 +831,7 @@ function route(cmd) {
   if (cmd === "publish") return "publish";
   if (cmd === "rounds") return "rounds";
   if (cmd === "results") return "results";
+  if (cmd === "issues") return "issues";
   return "unknown";
 }
 
@@ -783,6 +858,7 @@ function main() {
       case "publish": return void cmdPublish(argv);
       case "rounds": return void cmdRounds(argv).catch(die);
       case "results": return void cmdResults(argv).catch(die);
+      case "issues": return void cmdIssues(argv).catch(die);
       default:
         console.error(HELP);
         process.exit(1);
@@ -798,5 +874,6 @@ function main() {
 if (require.main === module) main();
 module.exports = {
   route, resolveKitDir, qapingWrapper, vendorFlags, isSourceCheckout, RULE_BODY, HELP,
-  ROUNDS_FILE, MAX_OPEN_ROUNDS, parseRounds, upsertRound, removeRound, visibleUntil, renderRounds,
+  ROUNDS_FILE, MAX_OPEN_ROUNDS, GAME_SLUG_RE,
+  parseRounds, upsertRound, removeRound, visibleUntil, renderRounds,
 };

package/docs/COMMANDS.md

@@ -0,0 +1,122 @@
+# qaping — CLI commands
+
+Everything the `qaping` binary does. Your agent runs most of these for you;
+`setup`, `builds` and `rounds` are the ones you will type yourself.
+
+```
+qaping setup [claude-code|cursor|codex] [--force]
+qaping remove [--client <c>]
+qaping publish-build <game.zip> --platform windows|macos
+qaping builds
+qaping builds rm <slug>
+qaping publish <built-dir>
+qaping wait <ping_id> [--timeout <seconds>]
+qaping results <ping_id> [--json]
+qaping rounds [--json] [--offline] [--file <path>]
+qaping rounds add <ping_id> [--platform windows|macos|ios] [--build <url>]
+                            [--minutes N] [--deadline-seconds N]
+                            [--game <slug>] [--checks a,b,c]
+                            [--note "<patch>"] [--json]
+qaping rounds rm <ping_id> [--json]
+qaping issues <game> [--json] [--status open|fixed|verified|closed]
+qaping whoami
+qaping version
+```
+
+## Getting in and out
+
+### `qaping setup [claude-code|cursor|codex] [--force]`
+
+Registers the qaping MCP server with your coding agent, installs the `qaping`
+skill and its rule, and signs you in (a browser window opens once). With no
+client name it detects what is installed. `--force` rewrites an existing
+entry.
+
+### `qaping remove [--client <c>]`
+
+Removes qaping's MCP entry, skill and rule from the client. It touches only
+qaping's own state — nothing else you have installed, and not your login.
+
+### `qaping whoami`
+
+Which account this machine is signed in as. Results are scoped to the account
+that filed the round, so check this before deciding a round is gone.
+
+### `qaping version`
+
+Prints the installed version.
+
+## Hosting a build
+
+### `qaping publish-build <game.zip> --platform windows|macos`
+
+Uploads a zipped native build and prints the `/b/<slug>` URL a round is filed
+against. You hold a small number of hosted builds at a time; the oldest is
+listed first by `qaping builds`.
+
+### `qaping builds` / `qaping builds rm <slug>`
+
+Lists the hosted builds you hold, or deletes one now to free its slot.
+
+### `qaping publish <built-dir>`
+
+Hosts a browser-playable game's built output and prints the public URL. Web
+rounds are filed with that URL and no platform.
+
+## Rounds
+
+### `qaping wait <ping_id> [--timeout <seconds>]`
+
+Waits on a filed round, renewing the lease that keeps it visible to new
+playtesters, and prints the results when they land. The agent normally runs
+this in a background task.
+
+### `qaping results <ping_id> [--json]`
+
+One passive fetch, no waiting. Exit code `0` means results are in, `2` means
+still pending, `1` anything else (expired, not yours, unreachable).
+
+### `qaping rounds`
+
+The parked rounds this repo is owed, read from `qa-open-rounds.json` at the
+repo root, each with its live status. `--offline` skips the status lookup;
+`--file` points at another ledger.
+
+### `qaping rounds add <ping_id> …`
+
+Records a round the agent chose to park — an overnight run, a slow native
+claim — so a later session collects it instead of filing a duplicate. Add
+`--build`, `--minutes`, `--deadline-seconds`, `--game`, `--checks` and
+`--note` so the record explains itself; `--game` is the QA plan's
+`game_slug`, so the session that collects the round knows which issue board
+it moved.
+
+### `qaping rounds rm <ping_id>`
+
+Forgets a parked round once it is collected or expired.
+
+## The issue board
+
+### `qaping issues <game> [--json]`
+
+Prints the game's issue board: every bug that outlived a round, with its
+status — open, fixed (you claim it is fixed), verified (a playtester
+confirmed it is gone), closed. `--status` prints one status only; `--json`
+prints the machine-readable rows.
+
+Read-only, on purpose. Your agent files, claims, closes and reopens issues
+through the `qaping_issues` MCP tool while it runs the loop; this is the
+window you read it through. Nothing on the board costs credits — only rounds
+do — and nothing turns *verified* except a playtester answering "Gone" on a
+round filed after the fix was claimed.
+
+## Files qaping leaves in your repo
+
+| file | what it is | commit it? |
+|---|---|---|
+| `QA-PLAN.md` | the checks this game must pass; the agent authors, you own | yes — see [the format](QA-PLAN-FORMAT.md) |
+| `qa-rounds.jsonl` | append-only history, one line per finished round | yes |
+| `qa-open-rounds.json` | rounds filed and not yet collected | no — gitignore it |
+
+The issue board is not a file: it lives on the service, one board per game,
+and `qaping issues <game>` reads it. The plan's `game_slug` is what names it.

package/docs/QA-PLAN-FORMAT.md

@@ -11,12 +11,19 @@ YAML at the very top of the file:
 ```yaml
 ---
 game: Solar Drift
+game_slug: solar-drift                          # the issue board's id — minted ONCE, never renamed
 build_command: ./scripts/package.sh --release   # the ONE command that produces a shippable build
 platforms: [windows]                            # windows | macos | ios | web
 input: XInput gamepad                           # optional; default keyboard+mouse
 ---
 ```
 
+`game_slug` is minted once from the game name — lowercase, every run of
+non-alphanumerics collapsed to a single `-`, no leading or trailing `-`, ≤64
+characters — and is then permanent, exactly like a check id: it names the
+game's issue board, and renaming it orphans every issue filed under the old
+one. Every playtest round is filed with it as `game`.
+
 `build_command` is recorded once at setup so every future run can build without
 asking. `platforms: [web]` means a browser-playable game — its "build" is a
 static directory, not a zip. `input` declares the hardware the
@@ -88,6 +95,26 @@ setup: "?save=campaign-mid"
    anything missing, corrupted, or visually wrong.
 ````
 
+## Bugs live on the issue board; checks live here
+
+A check is what the game must ALWAYS do — it belongs in this file, forever. A
+bug is what the game does wrong right now — it belongs on the game's issue
+board (`qaping issues <game_slug>`, moved by the agent through the
+`qaping_issues` tool), where it is numbered, carried across rounds, and
+retired when it is gone. Do not write bugs into `QA-PLAN.md`: a check written
+to describe one bug ("the shop does not close when you press B twice") ages
+into a puzzle the moment the bug is fixed.
+
+The board is what makes a fix provable. The agent may CLAIM a fix (with the
+exact build URL the next round will play); only a playtester answering
+"Gone" on a round filed after that claim turns the issue *verified*, and a
+"Still here" on a claimed fix regresses it. Because every round is filed with
+`game`, the board's open and claimed-fixed issues ride it as the playtester's
+checklist — no step budget spent, no bug forgotten between patches.
+
+A check and the bug that came from it stay linked through the issue's
+`check_id`: the same id this file gives the check.
+
 ## The round ledger — qa-rounds.jsonl
 
 Beside the plan, at the game repo root, sits `qa-rounds.jsonl`: one JSON line
@@ -96,6 +123,8 @@ appended per round, committed alongside the plan updates —
 ```json
 {"round_id": "…", "report_url": "…", "build": "<sha or hosted url>",
  "evidence_grade": "…", "checks": [{"id": "…", "outcome": "…"}],
+ "issues": {"game": "solar-drift", "verified": [3], "regressed": [5],
+  "new": [7], "still_open": [2]},
  "verdict": "…", "credits": 20, "follow_ups": ["…"]}
 ```
 
@@ -106,8 +135,11 @@ 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.
+stay the dev-readable contract. `issues` is what this round did to the issue
+board, by number (omitted when the round carried no `game`). `follow_ups` is
+NON-BUG follow-ups only — a check to add, a build affordance to write, a
+question to settle; bugs go on the board, where they are numbered and
+re-checked. Open `follow_ups` are what the next filing must carry forward.
 
 ## Rounds still open — qa-open-rounds.json
 
@@ -118,12 +150,13 @@ PARKED: filed with an explicit long deadline, then recorded in
 ```json
 {"rounds": [{"ping_id": "<uuid>", "filed_at": "<ISO>", "platform": "windows",
   "build": "<the hosted or store URL>", "est_minutes": 10,
-  "deadline_seconds": 86400, "checks": ["<check ids>"],
-  "note": "<the patch this round covers>"}]}
+  "deadline_seconds": 86400, "game": "solar-drift",
+  "checks": ["<check ids>"], "note": "<the patch this round covers>"}]}
 ```
 
 `qaping rounds` lists it with each round's live status, `qaping rounds add`
-records one, `qaping rounds rm` drops it once collected. This file is the
+(with `--game` for the board this round carries) records one,
+`qaping rounds rm` drops it once collected. This file is the
 opposite of the ledger and never merges with it: mutable OPEN state, one entry
 per round still owed, emptied as rounds land. It is not history — gitignore it.
 

package/docs/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64"><rect x="4" y="4" width="56" height="56" rx="14" fill="#FF7A45"/><path d="M20 33.5l8 8 16-17" fill="none" stroke="#fff" stroke-width="6.5" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaping/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "homepage": "https://qaping.dev",
   "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": [
@@ -25,7 +25,7 @@
     "node": "^20.17.0 || ^22.13.0 || >=23.5.0"
   },
   "dependencies": {
-    "pingfusi": "^0.16.1"
+    "pingfusi": "^0.17.1"
   },
   "publishConfig": {
     "access": "public"

package/skill/SHIPPED-HASHES.json

@@ -0,0 +1,19 @@
+{
+  "note": "sha256 of every SKILL.md version this package has shipped (LF-normalized). setup refreshes an installed skill whose hash is listed here — it is ours — and preserves anything else as a local edit. APPEND-ONLY; regenerate with: node scripts/gen-skill-hashes.js [<skill-root>...]",
+  "skills": {
+    "qaping": [
+      "184aa97ba0d529eea36be3c6eb4a5f4c1db8e2a65a0230e03814276a18a92354",
+      "217ffcc582e068424eefbb69376825ac71433fa92f34e3546bd02d8521ef008c",
+      "2fe5cafeef48146d8c9cc263ae1aaef764720027d17c0af3ab879e6853cf4a26",
+      "38cdc3289db6a544bc0cc828f4981a3f4ed6b39036ce81eebbaf4cbe9c47a5d0",
+      "490ff02895fdc6a2eb3a0b671628a8d4eee3efd906782eb45d99eac40bf59846",
+      "5462b858f58d183a020a5b2fa214dd1da6856e71a238316641f13d70eb0f0df4",
+      "5d0751c023af0a1cf69f152ba587b10c34087c7d5299f2d4b0e782f1ad0d66b0",
+      "6d0a5a1b430a8a0fd1c7c06b726de657e7fe82ac37ce69c9446539065d2ce751",
+      "71e64cd2b58996236c7fd3375a324ca2ae7b3e4028f7b358a389c562464c8bf3",
+      "8d817af568154734cd893122ce2e40ef2cd20cb725abbf318f134318157e5b6c",
+      "966bd642f1ee052691c7974a186e9f8f50644bce0ea010b6f0b444931879dbad",
+      "b9d08318e69290759bf31e149d64207b9d186faac9ccd01bc1db3ffcff29506c"
+    ]
+  }
+}

package/skill/qaping/SKILL.md

@@ -11,9 +11,12 @@ 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.
+cheaper. Checks are what the game must always do; BUGS are what it does wrong
+right now, and they live on the game's issue board, where a fix you claim
+turns verified only when a playtester says it is gone. All service contact
+goes through four MCP tools — `qaping_playtest`, `qaping_results`,
+`qaping_wait`, `qaping_issues` — plus `qaping publish-build` for hosting the
+build.
 
 ## Ground rules (read before filing anything)
 
@@ -55,9 +58,12 @@ cheaper. All service contact goes through three MCP tools —
   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
+  [mm:ss] think-aloud transcript. Windows rounds return a recording, and a
+  transcript only when the tester recorded with our recorder app — read
+  `transcript_status` on each result: `'ok'` means an inline transcript,
+  `'unavailable'` means a Game Bar session with NO transcript. It is a
+  per-session fact, never promise one for a Windows round; plan to watch an
+  `'unavailable'` 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.
@@ -101,6 +107,60 @@ once per recorded `ping_id`. The file is this, and nothing else:
 `qa-open-rounds.json` is mutable OPEN state; `qa-rounds.jsonl` is append-only
 history written after results land. Never merge the two.
 
+## The issue board — bugs live here
+
+Checks are the standing contract; bugs are what is wrong today, and they live
+on the game's issue board — one board per `game_slug`, numbered `#1, #2, …`
+for the life of the game, read and moved with `qaping_issues`. The board is
+what carries a bug across rounds: the checklist a round hands the playtester
+is built from it, and it is the only place a fix can ever be confirmed.
+
+| status | who moves it there | how |
+|---|---|---|
+| `open` | you (`action:'create'`), or a playtester filing a bug from inside a round | the live state, and where a regression lands |
+| `fixed` | YOU only (`action:'fixed'`, `build` REQUIRED) | a CLAIM, not a verification |
+| `verified` | a PLAYTESTER only — a "Gone" on a round filed AFTER your claim | there is no verify action and there never will be |
+| `closed` | you only (`action:'close'` + reason wontfix / invalid / duplicate / cannot_reproduce) | leaves the checklist; never turns green |
+
+A "Still here" on a `fixed` or `verified` issue REGRESSES it back to `open`
+and counts the regression. A "Gone" on an issue nobody claimed fixed changes
+nothing — it may simply not have reproduced this session, and the board
+records that as a not-seen streak for you to act on (close it
+`cannot_reproduce` once you believe it).
+
+- **The board is the source of truth for bugs; the dev's GitHub issues are
+  the mirror (MUST).** File it on the board first, then `gh issue create` for
+  the dev's own triage, then put that URL back on the board with
+  `action:'edit'` + `external_ref`. A bug that lives only in GitHub is never
+  re-checked by anyone, because only the board rides a round.
+- **Issue titles and bodies speak player language (MUST)** — the same rule
+  the steps live under, for the same reason: a stranger reads them
+  mid-session on their own machine. "The shop closes when you press B twice",
+  never "NRE in ShopController.OnClose". No file paths, no stack traces, no
+  ticket ids. Title ≤120 chars, body ≤1000.
+- **No build, no claim (MUST).** `action:'fixed'` takes the exact build URL
+  the NEXT round will play, and the claim happens BEFORE that round is filed.
+  A fix claimed after the round exists was not in the build that playtester
+  ran, so their answer cannot confirm it — the board leaves it amber and says
+  why.
+- **`game` on every playtest filing (MUST).** The board's open and
+  claimed-fixed issues — up to 12, claimed-fixed first — ride the round as
+  the playtester's checklist after free play. It costs no step budget, adds
+  ~30 seconds per issue inside est_minutes, and is the ONLY path to
+  `verified`. Omit it and the round has no memory.
+- **Never leave a playtester-filed issue untriaged (MUST).** A bug reported
+  from inside a round lands `open` with origin `reviewer`, and answering it
+  is part of reporting that round — accept it, or close it duplicate /
+  invalid / cannot_reproduce.
+- **Where the checklist is answered today, honestly.** The Windows browser
+  runner renders it. Rounds answered in the reviewer app (macOS, iOS) and web
+  rounds carry the board but do not show it yet, so their issues come back
+  unanswered — which is not evidence about the bug. An issue nobody answered
+  never moves; never report an unanswered checklist as "no longer
+  reproducing".
+- Nothing on the board costs credits — only rounds do. `qaping issues <game>`
+  reads the same board from the shell.
+
 ## The review interface (know your tester)
 
 <!-- Distilled from QAPING_REVIEWER_INTERFACE.md (monorepo root, INTERNAL,
@@ -151,10 +211,15 @@ that assumes they read your repo.
    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).
+   very top): `game`, `game_slug`, `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).
+   **Mint `game_slug` ONCE**, from the game name: lowercase, every run of
+   non-alphanumerics collapsed to a single `-`, no leading or trailing `-`,
+   ≤64 chars ("Solar Drift" → `solar-drift`). It is the issue board's id and
+   is NEVER renamed — the same rule check ids live under, for the same reason:
+   a renamed slug orphans every issue filed under the old one.
    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`
@@ -217,6 +282,10 @@ checks testimony-only — mark that in the plan and report at that grade.
 
 ## RUN — per patch
 
+0. **Read the board.** `qaping_issues` with the plan's `game_slug` (action
+   `list`): what is open, what you claimed fixed and is still waiting on a
+   playtester, what came back REGRESSED. This is the bug half of "what
+   happened since last time"; the ledger's last line is the check half.
 1. **Select.** Read the diff (or PR). Pick the checks it can plausibly affect,
    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
@@ -252,11 +321,19 @@ checks testimony-only — mark that in the plan and report at that grade.
    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
+5. **Claim fixes (MUST, before filing).** For every board issue this patch
+   fixes: `qaping_issues` `action:'fixed'` with its `seq`, `build` set to the
+   exact URL this round will play, and a `note` written for the playtester
+   ("the shop stays open now"). Claim first, file second — a claim recorded
+   after the round exists cannot be confirmed by it, and the results say so
+   instead of turning it green. No build URL, no claim.
+6. **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
+   default — and always with `game` set to the plan's `game_slug` (MUST), so
+   the board's live issues ride the round as the playtester's checklist.
+   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
@@ -282,11 +359,14 @@ checks testimony-only — mark that in the plan and report at that grade.
      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 recheck of a known bug is NEVER a step.** The board rides the
+     checklist: `game` on the filing attaches the open and claimed-fixed
+     issues, the playtester answers them (Still here / Gone / Couldn't test)
+     after free play, and that costs none of the step budget. Never author a
+     step that re-asks an issue already on the board — a step and a checklist
+     row about the same bug buy one answer twice — 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."
@@ -307,18 +387,24 @@ checks testimony-only — mark that in the plan and report at that grade.
    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 or park — decide now** (ground rule 1). WAIT: spawn a background
+   session or state the deferral out loud — never silently truncate. Then
+   print `issues: <seqs attached>` from the filing's own result (it names the
+   checklist it built, and anything the 12-issue cap left off), or
+   `issues: none` on an empty board — so what this round RE-CHECKS is on the
+   record beside what it covers.
+7. **Wait or park — decide now** (ground rule 1). WAIT: spawn a background
    task looping `qaping_wait` and keep working — foreground polling is the
    fallback. PARK: the filing already carried an explicit `deadline_seconds`
    sized to the span, so record it — `qaping rounds add <ping_id> --build
    <url> --minutes N --checks <ids> --note "<patch>"` — tell the user what is
    pending, and end the turn; a later session collects it. A promise to check
    later is never a wait, and never a substitute for the record.
-7. **Report** from `qaping_results`:
+8. **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)`.
+     `Evidence: recording + transcript` (macOS/iOS, or a Windows result with
+     `transcript_status:'ok'`) / `Evidence: recording only` (a Windows result
+     with `transcript_status:'unavailable'` — a Game Bar session) /
+     `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>)`
@@ -326,16 +412,23 @@ checks testimony-only — mark that in the plan and report at that grade.
      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.)
+   - **Issues line (MUST), under the headline.** One line read off the
+     results' issue block: `issues: #3 verified, #5 REGRESSED, 2 new` —
+     verified first, regressions next, then how many bugs playtesters filed
+     from inside the session. `issues: none moved` when the board rode along
+     and nothing changed; nothing at all when the round carried no `game`. A
+     REGRESSED issue is a failure of a fix you claimed: say so in words, in
+     the same breath as the headline.
    - **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
+     than one row (a precondition step plus its observation step) 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.
@@ -344,8 +437,15 @@ checks testimony-only — mark that in the plan and report at that grade.
    - **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
+     "evidence_grade": …, "checks": [{"id": …, "outcome": …}],
+     "issues": {"game": "<game_slug>", "verified": [3], "regressed": [5],
+     "new": [7, 8], "still_open": [2]}, "verdict": …, "credits": …,
+     "follow_ups": […]}`. The `issues` object is the board's movement this
+     round, by seq (omit it entirely when the round carried no `game`), and
+     `follow_ups` is NON-BUG follow-ups only from now on — a check to add, a
+     build affordance to write, a question to settle. A bug goes on the
+     board, where it is numbered, re-checked and closable; free text nobody
+     re-reads is where bugs went to die. `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,
@@ -367,14 +467,33 @@ checks testimony-only — mark that in the plan and report at that grade.
      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).
+   - **Triage every new issue in THIS turn (MUST).** Each `NEW #n` in the
+     results is a bug a playtester filed from inside the session, and it is
+     answered before the report is finished: accept it (`gh issue create` for
+     the dev's triage, then `qaping_issues` `action:'edit'` with
+     `external_ref` set to that URL), or close it — `duplicate` with
+     `duplicate_of_seq`, `invalid`, or `cannot_reproduce`. Never leave one
+     sitting; an untriaged board stops being worth reading, and the next
+     round re-asks a bug nobody decided about.
+   - **A REGRESSED issue reopens its mirror (MUST).** The fix did not hold:
+     `gh issue reopen <n>` on the GitHub issue, name it in the PR comment,
+     and never claim `fixed` on it again without a new build to claim
+     against.
+   - **A verified issue closes its mirror.** An issue a playtester turned
+     `verified` is settled: close the GitHub issue citing the round. Leave
+     the board row green — never `action:'close'` a verified issue to tidy
+     up; closed is for what you decided about, not for what was confirmed.
+   - Findings YOU file: one board issue per finding (`action:'create'`, in
+     player language, severity from consequence — `blocker` cannot play past
+     it / `major` / `minor` / `cosmetic`), then one `gh issue create` per
+     finding as the dev's own draft — never near-duplicates, never one issue
+     per symptom of the same bug — and `action:'edit'` the board row with the
+     `external_ref` you just created. Before reproduction the body carries
+     "observed once, unreproduced" plus that proposed severity. 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
 
@@ -384,7 +503,11 @@ 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.
+once-seen fail CONFIRMED without that round or hard evidence. When the
+targeted round settles it as a real bug, the board issue for it carries
+`check_id: <the check's id>` — set at `create`, or with `action:'edit'` on a
+playtester-filed issue — so the check and the bug that made it ambiguous stay
+findable from each other.
 
 ## Paired rounds (two-state comparisons)