pixel-perfect-kit 0.1.0

package/harness/human-qa.js

@@ -0,0 +1,406 @@
+// harness/human-qa.js — the HUMAN phase: PingHumans side-by-side QA as a workflow gate.
+//
+// WHY THIS EXISTS. The gates prove every property the tool measures; they cannot prove
+// the two things LEARNINGS reserves for eyes — that the *measured set* is what a person
+// actually sees, and that techniques rasterise identically (the gate-vs-eyes split). The
+// kit's end state is a clone the designer receives after "all the human iteration rounds"
+// — unattended — so the human round must be a PHASE with a machine-checkable gate, not an
+// operator ritual. A PingHumans verdict IS machine-checkable: this tool files the test,
+// polls the verdict over the same authenticated JSON-RPC endpoint the cpyany CLI uses,
+// and exits 0 only when the LATEST round is human-approved. Receipts pin ping_id+verdict.
+//
+// The test template encodes the lessons stripe's 8 unconverged rounds paid for:
+//   - SCOPE-PIN: the reviewer judges ONLY the cloned region (an open-ended side-by-side
+//     of a partial clone cannot converge — stripe lesson 1).
+//   - Behavior is INFORMATIONAL: a static clone strips JS; hover/animation differences
+//     are noted, never failed on (stripe lesson 2 — acceptance criteria for
+//     animated/generative content must be agreed up front).
+//   - Per-leaf compare steps are generated from coverage.json, so the human is pointed
+//     at exactly the marks the gates certified — detection stays human, scope stays pinned.
+//
+// USAGE
+//   node harness/human-qa.js template <name> --draft <public-url> [--region "the header"]
+//       print the test spec JSON (to file manually via the PingHumans MCP)
+//   node harness/human-qa.js file     <name> --draft <public-url> [--region "…"]
+//       generate the spec AND file it; records the round in targets/<name>/human-qa.json
+//   node harness/human-qa.js record   <name> <ping_id> [--approve "Verdict A,Verdict B"]
+//       adopt a test filed elsewhere (e.g. via the MCP) as the current round
+//   node harness/human-qa.js verify   <name>
+//       fetch the LATEST round's verdict; exit 0 = approved (the workflow gate runs this)
+//   node harness/human-qa.js poll     <name> "question" [--choices "A,B,C"]
+//       a MICRO-CHECK (~$0.05, blocks up to ~300s): put one small question in front of a
+//       human MID-ROUND — "do these 3 tiles look right now? <urls>" — before spending a
+//       full test round on it. With a responsive reviewer this collapses a whole
+//       flag→refile→wait cycle into minutes (astryx burned 4 rounds on one contested cell
+//       treatment). ADVISORY ONLY: polls never satisfy the human gate — the gate still
+//       requires an approving verdict on a full scope-pinned round. The draft/original
+//       urls are appended automatically when tunnel.json/target.json exist.
+//   node harness/human-qa.js poll-result <name> <ping_id>
+//       free re-fetch of a pending poll's answers
+//
+// AUTH: the designer's existing cpyany/PingHumans login — ~/.config/cpyany/credentials.json,
+// else the Bearer header in ~/.claude.json's cpyany/pinghumans MCP entry, else
+// PPK_PINGHUMANS_TOKEN. PPK_PINGHUMANS_URL overrides the API base; a file:// value serves
+// canned responses from disk (offline selftests; sandboxes that block sockets).
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { fileURLToPath } = require("url");
+
+const WORK = process.cwd();
+const targetDir = (name) => path.join(WORK, "targets", name);
+const hqPath = (name) => path.join(targetDir(name), "human-qa.json");
+const readJson = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
+const BASE = process.env.PPK_PINGHUMANS_URL || process.env.PINGHUMANS_APP_URL || "https://pinghumans.com";
+
+function resolveToken() {
+  if (process.env.PPK_PINGHUMANS_TOKEN) return process.env.PPK_PINGHUMANS_TOKEN;
+  try {
+    const t = readJson(path.join(os.homedir(), ".config", "cpyany", "credentials.json")).token;
+    if (t) return t;
+  } catch (e) {}
+  try {
+    const cfg = readJson(path.join(os.homedir(), ".claude.json"));
+    const entry = (cfg.mcpServers || {}).cpyany || (cfg.mcpServers || {}).pinghumans;
+    const m = /Bearer\s+(\S+)/.exec((entry && entry.headers && (entry.headers.Authorization || entry.headers.authorization)) || "");
+    if (m) return m[1];
+  } catch (e) {}
+  return null;
+}
+
+// One JSON-RPC tools/call against the PingHumans MCP-over-HTTP endpoint (the same
+// transport `npx cpyany wait` uses). file:// base → canned responses from disk:
+//   get_test_results-<ping_id>.json / request_human_test.json
+//
+// The LIVE api/mcp endpoint's tools/list exposes these under the "cpyany" namespace
+// (`cpyany_test`, `cpyany_test_results`), not the generic names this file uses
+// internally — confirmed empirically (astryx run): a live call with the generic name
+// fails with "Tool request_human_test not found" even with a valid token, while
+// `tools/list` on the same endpoint returns `cpyany_test`/`cpyany_test_results`/
+// `cpyany_wait`/`cpyany_poll`/`cpyany_poll_results`/`cpyany_check_source`. Kept the
+// internal names (and the file:// fixture filenames / selftest) unchanged — only the
+// wire method name sent to the LIVE endpoint is remapped, right before the fetch.
+const LIVE_TOOL_NAME = { request_human_test: "cpyany_test", get_test_results: "cpyany_test_results", ping_humans: "cpyany_poll", get_ping: "cpyany_poll_results" };
+async function rpc(name, args, timeoutMs) {
+  if (BASE.startsWith("file://")) {
+    const dir = fileURLToPath(BASE);
+    const f = name === "get_test_results" ? `get_test_results-${args.ping_id}.json`
+      : name === "get_ping" ? `get_ping-${args.ping_id}.json`
+      : `${name}.json`;
+    return readJson(path.join(dir, f));
+  }
+  const token = resolveToken();
+  if (!token) throw new Error("no PingHumans token — run `npx cpyany setup`, or set PPK_PINGHUMANS_TOKEN");
+  const wireName = LIVE_TOOL_NAME[name] || name;
+  const res = await fetch(`${BASE}/api/mcp`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: wireName, arguments: args } }),
+    // ping_humans blocks server-side while a human answers (up to ~300s) — callers pass a
+    // matching timeout; everything else keeps the snappy default.
+    signal: AbortSignal.timeout(timeoutMs || 20_000),
+  });
+  const raw = await res.text();
+  const m = raw.match(/data: (.*)/);
+  const payload = JSON.parse(m ? m[1] : raw);
+  if (payload.error) throw new Error(payload.error.message || "MCP error");
+  const r = payload.result || {};
+  if (r.isError) throw new Error((r.content && r.content[0] && r.content[0].text) || "PingHumans returned an error");
+  if (r.structuredContent) return r.structuredContent;
+  try { return JSON.parse(r.content[0].text); } catch (e) { throw new Error("unexpected RPC response shape"); }
+}
+
+// ── the scope-pinned test template ───────────────────────────────────────────
+const slugToWords = (s) => s.replace(/[_-]+/g, " ").trim();
+
+function buildSpec(name, draftUrl, region, changelog) {
+  const target = readJson(path.join(targetDir(name), "target.json"));
+  let leaves = [];
+  try {
+    const cov = readJson(path.join(targetDir(name), "coverage.json"));
+    leaves = (Array.isArray(cov) ? cov : cov.leaves || []).map(slugToWords);
+  } catch (e) {}
+  const R = region || "the cloned region";
+  const stripped = R.replace(/^the\s+/i, "");
+  const cap = stripped.charAt(0).toUpperCase() + stripped.slice(1);
+  const verdicts = [`${cap} identical`, `${cap} slightly off`, `${cap} clearly different`];
+  const steps = [
+    { text: `Open both pages at the same window size. This test is ONLY about ${R}. Everything outside it is out of scope — ignore it for your verdict.`, check: null },
+  ];
+  // Documented deviations are surfaced TO THE REVIEWER, or the gate's escape hatch and the
+  // human's expectations diverge forever: astryx round 3 re-flagged bento cells that
+  // behavior-deviations.json had honestly excused — the reviewer had no way to know.
+  let deviationNote = "";
+  try {
+    const dev = readJson(path.join(targetDir(name), "behavior-deviations.json"));
+    // Cross-reference entries ("See <other-key> — same phenomenon") exist for the GATE's
+    // key-by-key bookkeeping, not for humans: astryx round 5 surfaced 20 entries of which
+    // 14 were "See mutation:… same phenomenon" fragments, and the 300-char budget rendered
+    // the whole step as unreadable mush. Only PRIMARY entries face the reviewer.
+    const primary = Object.fromEntries(Object.entries(dev).filter(([, v]) => !/^\s*See\s/i.test(String((v && v.reason) || ""))));
+    const keys = Object.keys(primary);
+    if (keys.length) {
+      // PingHumans caps a step's `text` at 300 chars. As the number of documented
+      // deviations grows (astryx round 4: 5, up from round 3's 3), joining a per-entry
+      // reason snippet can blow past that even after truncating each one — the step
+      // silently failed to file (Zod "too_big") instead of degrading. Budget the PREFIX
+      // first, then divide what's left evenly across entries so this scales to any count
+      // instead of hard-failing past ~2-3 deviations (kit-change candidate — flagged here
+      // since human-qa.js is shared kit code, fixed minimally rather than reworked).
+      const PREFIX = "KNOWN, INTENTIONAL differences — do NOT flag these (documented exclusions): ";
+      const BUDGET = 300 - PREFIX.length;
+      const perEntry = Math.max(20, Math.floor((BUDGET - (keys.length - 1) * 3) / keys.length));
+      const lines = Object.entries(primary).map(([k, v]) => {
+        const label = k.replace(/^[a-z]+:/, "");
+        const reason = String((v && v.reason) || "");
+        const snippet = `${label} — ${reason}`;
+        return snippet.length > perEntry ? snippet.slice(0, Math.max(0, perEntry - 1)) + "…" : snippet;
+      });
+      steps.push({ text: (PREFIX + lines.join(" | ")).slice(0, 300), check: null });
+      // `instructions` is a SEPARATE field with its own hard cap (observed: 1000 chars
+      // total, shared with the fixed scope/verdict text below) — it is NOT the same budget
+      // as the step's 300-char cap. Duplicating the full per-entry list here (as an earlier
+      // version did) silently blew past 1000 once deviation count grew past ~15 (iphone17
+      // round 5: 34 entries -> 1152 chars -> PingHumans rejected the whole filing with a
+      // Zod "too_big" error, not a graceful truncation). Fix: `instructions` gets a SHORT,
+      // fixed-size pointer to the dedicated step above (which already carries the full,
+      // properly-budgeted list) instead of re-deriving its own copy from `keys.length`.
+      deviationNote = ` See the "KNOWN, INTENTIONAL differences" step below (${keys.length} documented) — you should NOT flag those; they're already excused.`;
+    }
+  } catch (e) {}
+  // one compare step per ~5 leaves, so the reviewer is pointed at exactly the
+  // certified marks without a 20-step checklist
+  for (let i = 0; i < leaves.length; i += 5) {
+    steps.push({
+      text: `Compare these elements between clone and original — position, size, color, font, spacing: ${leaves.slice(i, i + 5).join(", ")}.`,
+      options: ["Identical", "Slightly off", "Clearly different"],
+    });
+  }
+  steps.push(
+    { text: `Squint test: at a glance, could you tell which is the clone? Compare overall font weight/sharpness in ${R}.`, options: ["Could not tell apart", "Subtle difference", "Obvious difference"] },
+    { text: "INFORMATIONAL (does not affect your verdict): the clone is a static snapshot — hover menus and animations may not run. Note any such difference; do not fail the test for it.", options: ["Same on both", "Different", "Didn't check"] },
+    { text: `If anything in ${R} looked off, describe exactly what and where in your notes. Attach a screenshot showing both.`, check: null },
+    // Workers use the comment-pin flow and skip the verdict buttons unless told — 3 of the
+    // first 3 real responses were comment-only (choice:null), which the gate rightly refuses
+    // but which stalls the loop. The pick is therefore an explicit, REQUIRED final step.
+    { text: `FINAL REQUIRED STEP: pick one of the verdict buttons ("${verdicts[0]}" / "${verdicts[1]}" / "${verdicts[2]}"). A review without a verdict pick cannot be accepted — comments alone don't count.`, check: null }
+  );
+  // What changed since the reviewer's last round, stated UP FRONT — iphone17 round 10's
+  // verdict was literally "did you fix anything?": the round's substantive change was
+  // invisible without being told where to look. A refile that doesn't say what changed
+  // wastes the reviewer's pass.
+  let changeNote = "";
+  if (changelog && changelog.trim()) {
+    changeNote = ` CHANGED SINCE YOUR LAST REVIEW: ${changelog.trim().slice(0, 200)}`;
+    // step text caps at 300 chars API-side: budget = 300 − prefix, never prefix + 250
+    // (52 + 250 = 302 failed a live filing — iphone17 round 13)
+    const CHG_PREFIX = "Changed since the last review — check these first: ";
+    steps.splice(1, 0, { text: CHG_PREFIX + changelog.trim().slice(0, 300 - CHG_PREFIX.length), check: null });
+  }
+  return {
+    url: target.url,
+    draft_url: draftUrl,
+    title: `Compare ${R}: clone vs original`,
+    instructions: `Compare ONLY ${R} between the original site and the clone, side by side at the same width. Everything outside ${R} is out of scope.${changeNote}${deviationNote} When done, you MUST pick a verdict button — a comment-only review cannot be accepted.`,
+    steps,
+    verdict_options: verdicts,
+    approve_verdicts: [verdicts[0]],
+    n_target: 1,
+    deadline_seconds: 86400,
+    require_evidence: "screenshot",
+  };
+}
+
+// ── round state ───────────────────────────────────────────────────────────────
+const loadHq = (name) => (fs.existsSync(hqPath(name)) ? readJson(hqPath(name)) : { rounds: [] });
+const saveHq = (name, hq) => fs.writeFileSync(hqPath(name), JSON.stringify(hq, null, 2) + "\n");
+
+function pushRound(name, ping_id, spec, approve) {
+  const hq = loadHq(name);
+  hq.rounds.push({ ping_id, draft_url: (spec && spec.draft_url) || null, region: (spec && spec.title) || null, approve_verdicts: approve, filed_at: new Date().toISOString(), last: null, checked_at: null });
+  saveHq(name, hq);
+  return hq.rounds.length;
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+async function main() {
+  const args = process.argv.slice(2);
+  const opt = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : null; };
+  const [cmd, name, extra] = args.filter((a, i) => !a.startsWith("--") && (i === 0 || !args[i - 1].startsWith("--")));
+  if (!cmd || !name) { console.error("usage: human-qa.js template|file|record|verify <name> …  (see file header)"); process.exit(2); }
+  if (!fs.existsSync(path.join(targetDir(name), "target.json"))) { console.error(`targets/${name}/target.json missing`); process.exit(1); }
+
+  if (cmd === "template" || cmd === "file") {
+    // A test filed while earlier gates are still red reviews an UNFINISHED clone — the
+    // worker returns flags you already knew about and a credit is burned (paid for on
+    // astryx round 2: filed before the behavior phase ran, racing the worker's claim).
+    // Filing isn't a phase advance, so the state machine can't refuse it — this check is
+    // that refusal. Canonical phase list comes from workflow.js (a workflow.json seeded
+    // before a phase existed simply lacks its key — that phase is PENDING, not exempt);
+    // no workflow.json at all = standalone usage, guard skipped.
+    if (cmd === "file" && !args.includes("--anyway")) {
+      const wfPath = path.join(targetDir(name), "workflow.json");
+      if (fs.existsSync(wfPath)) {
+        const { PHASES } = require("./workflow.js");
+        const st = readJson(wfPath);
+        const beforeHuman = PHASES.slice(0, PHASES.findIndex((p) => p.key === "human")).map((p) => p.key);
+        const pending = beforeHuman.filter((k) => !(st.phases && st.phases[k] && st.phases[k].status === "pass"));
+        if (pending.length) {
+          console.error(`❌ refusing to file — earlier phase(s) not passed: ${pending.join(", ")}. A worker reviewing an unfinished clone returns flags you already know about and burns a credit.\n   finish the gates first (node harness/workflow.js status ${name}), or override with --anyway if this round is deliberately out-of-band.`);
+          process.exit(1);
+        }
+      }
+    } else if (cmd === "file" && args.includes("--anyway")) {
+      console.error("⚠ --anyway: filing without the pre-human gates all green — deliberate out-of-band round");
+    }
+    // LOCAL review mode (--local): no PingHumans account, no tunnel, no credits — the
+    // kit's own serve hosts the review page at /__review (clone in an iframe, click-to-
+    // pin, the SAME verdict-button contract), and the submission lands in human-qa.json
+    // where verify reads it. The trust model is explicit: a local verdict is
+    // OPERATOR-trusted (an agent with browser control could forge it — PingHumans is the
+    // independent option), so the round records provider:"local" and every receipt built
+    // on it says so. Agents must never open or submit /__review themselves.
+    const local = args.includes("--local");
+    let draft = opt("--draft");
+    if (!local) {
+      // Default --draft to the tunnel this target RECORDED (harness/tunnel.js writes it
+      // only after byte-verifying it serves the clone).
+      const tp = path.join(targetDir(name), "tunnel.json");
+      if (!draft && fs.existsSync(tp)) draft = readJson(tp).url;
+      if (!draft || /localhost|127\.0\.0\.1/.test(draft)) {
+        console.error("need a PUBLIC draft url — a remote human opens it. Start a verified tunnel first:\n  node harness/tunnel.js " + name + " [port]   (records targets/" + name + "/tunnel.json, used as the default)\nor pass --draft <url> explicitly.\n(no PingHumans account? review locally instead: node harness/human-qa.js file " + name + " --local)");
+        process.exit(1);
+      }
+    }
+    const spec = buildSpec(name, draft || "local review — served by ppk serve at /__review", opt("--region"), opt("--changelog"));
+    if (cmd === "template") { console.log(JSON.stringify(spec, null, 2)); return; }
+    if (local) {
+      const pingId = "local-" + require("crypto").randomBytes(6).toString("hex");
+      const hq = loadHq(name);
+      hq.rounds.push({ ping_id: pingId, provider: "local", draft_url: null, region: spec.title, approve_verdicts: spec.approve_verdicts, filed_at: new Date().toISOString(), spec: { title: spec.title, instructions: spec.instructions, steps: spec.steps, verdict_options: spec.verdict_options }, raw_response: null, last: null, checked_at: null });
+      saveHq(name, hq);
+      console.log(`✓ filed round ${hq.rounds.length} (LOCAL review) — ${pingId}\n  approve verdict: "${spec.approve_verdicts[0]}"\n  review it in a browser: http://localhost:8080/__review   (ppk serve ${name} must be running)\n  the reviewer pins what looks wrong and MUST pick a verdict button; then:\n  node harness/human-qa.js verify ${name}\n  ⚠ local verdicts are operator-trusted (recorded as provider:"local"); agents never open or submit /__review themselves.`);
+      return;
+    }
+    // A test filed against a dead/wrong tunnel burns the whole human round (hn round 1).
+    // Re-verify AT FILE TIME: reachable is required; byte-identical to clone/index.html is
+    // expected for a standalone clone (warn-only — a component served by an app dev server
+    // legitimately differs).
+    const idx = path.join(targetDir(name), "clone", "index.html");
+    if (fs.existsSync(idx)) {
+      const v = await require("./tunnel.js").verifyServes(draft, idx);
+      if (!v.ok && /unreachable|HTTP \d+/.test(v.reason)) { console.error(`❌ refusing to file — draft url is not serving: ${v.reason}`); process.exit(1); }
+      if (!v.ok) console.error(`⚠ ${v.reason} — filing anyway (expected only when the draft is not the standalone clone)`);
+      if (!/pinghumans\.com\/qa-toolbar\.js/.test(fs.readFileSync(idx, "utf8"))) console.error("⚠ clone/index.html has no PingHumans qa-toolbar <script> — workers can still review, but pinned comments/align data will be limited (capture-build --qa-toolbar adds it)");
+    }
+    const { approve_verdicts, ...toolArgs } = spec;
+    const r = await rpc("request_human_test", toolArgs);
+    if (!r.ping_id) throw new Error("filing returned no ping_id");
+    const round = pushRound(name, r.ping_id, spec, approve_verdicts);
+    console.log(`✓ filed round ${round} — ping ${r.ping_id}\n  approve verdict: "${approve_verdicts[0]}"\n  gate: node harness/workflow.js gate ${name} human   (or: node harness/human-qa.js verify ${name})\n  wake on result: npx cpyany wait ${r.ping_id}`);
+    return;
+  }
+
+  if (cmd === "record") {
+    if (!extra || !/^[0-9a-f-]{36}$/i.test(extra)) { console.error("usage: human-qa.js record <name> <ping_id> [--approve \"Verdict A,Verdict B\"]"); process.exit(2); }
+    const approve = (opt("--approve") || "").split(",").map((s) => s.trim()).filter(Boolean);
+    if (!approve.length) { console.error('record needs --approve "…" — the verdict string(s) that count as approval for the test you filed'); process.exit(2); }
+    const round = pushRound(name, extra, null, approve);
+    console.log(`✓ recorded round ${round} — ping ${extra} (approve: ${approve.join(" | ")})`);
+    return;
+  }
+
+  if (cmd === "verify") {
+    const hq = loadHq(name);
+    if (!hq.rounds.length) { console.error(`no human QA round recorded — file one: node harness/human-qa.js file ${name} --draft <public-url>`); process.exit(1); }
+    const round = hq.rounds[hq.rounds.length - 1];
+    // Local rounds: the review page's submission (written by serve.js's /__review/submit)
+    // IS the result — same shape the API returns, same classification below, and the
+    // provider travels into the receipt so a local verdict is never mistaken for an
+    // independent one.
+    const sc = round.provider === "local"
+      ? (round.raw_response || { status: "pending", n_received: 0, n_target: 1, responses: [] })
+      : await rpc("get_test_results", { ping_id: round.ping_id });
+    // Real response schema (verified empirically): the verdict pick is `choice`, prose is
+    // `free_text`; older/other shapes may use `verdict`/`notes` — accept both.
+    round.last = { status: sc.status, n_received: sc.n_received, n_target: sc.n_target, responses: (sc.responses || []).map((r) => ({ verdict: r.choice != null ? r.choice : (r.verdict != null ? r.verdict : null), notes: r.free_text || r.notes || r.comment || null })) };
+    round.checked_at = new Date().toISOString();
+    saveHq(name, hq);
+    const n = hq.rounds.length;
+    const resp = round.last.responses;
+    if (!resp.length) {
+      console.error(sc.status === "expired" ? `round ${n} EXPIRED unanswered (ping ${round.ping_id}) — refile` : `round ${n} pending — ${sc.n_received}/${sc.n_target} responses (ping ${round.ping_id})`);
+      process.exit(1);
+    }
+    // A response with NO verdict pick (comment-only) can never pass: inferring approval
+    // from prose is the exact hole the gates exist to close — "a pass is an explicit
+    // machine-checkable fact" applies to humans too. Surface what they wrote instead.
+    const unpicked = resp.filter((r) => r.verdict == null);
+    if (unpicked.length) {
+      console.error(`round ${n} has ${unpicked.length} response(s) with NO verdict pick — comments alone can't pass the gate${unpicked[0].notes ? `; reviewer wrote: "${unpicked[0].notes}"` : ""}\nask the reviewer to pick a verdict option, or refile: node harness/human-qa.js file ${name} --draft <url>`);
+      process.exit(1);
+    }
+    const rejected = resp.filter((r) => !round.approve_verdicts.includes(r.verdict));
+    if (rejected.length) {
+      console.error(`round ${n} NOT approved — ${rejected.map((r) => `"${r.verdict}"${r.notes ? ` — ${r.notes}` : ""}`).join("; ")}\nfix the flags (PLAYBOOK Phase 6: --inspect the flagged marks), redeploy, then refile: node harness/human-qa.js file ${name} --draft <url>`);
+      process.exit(1);
+    }
+    console.log(`round ${n} approved by ${resp.length} human(s): "${resp[0].verdict}" (${round.provider === "local" ? "LOCAL review — operator-trusted, " : ""}ping ${round.ping_id})`);
+    return;
+  }
+
+  if (cmd === "poll" || cmd === "poll-result") {
+    const hq = loadHq(name);
+    hq.polls = hq.polls || [];
+    // shared printer: exit 0 once ≥1 answer exists, 1 while pending/expired
+    const report = (sc, entry) => {
+      entry.last = { status: sc.status, n_received: sc.n_received, responses: (sc.responses || []).map((r) => ({ choice: r.choice != null ? r.choice : null, text: r.free_text || r.text || null })) };
+      entry.checked_at = new Date().toISOString();
+      saveHq(name, hq);
+      const resp = entry.last.responses;
+      if (resp.length) {
+        console.log(`poll answered (${resp.length}):` + resp.map((r) => `\n  ${r.choice != null ? `[${r.choice}] ` : ""}${r.text || ""}`).join(""));
+        return 0;
+      }
+      console.error(`poll ${entry.ping_id} ${sc.status || "pending"} — 0 answers yet; re-check (free): node harness/human-qa.js poll-result ${name} ${entry.ping_id}`);
+      return 1;
+    };
+    if (cmd === "poll-result") {
+      if (!extra) { console.error("usage: human-qa.js poll-result <name> <ping_id>"); process.exit(2); }
+      const entry = hq.polls.find((p) => p.ping_id === extra) || (() => { const e = { ping_id: extra, question: null, asked_at: null }; hq.polls.push(e); return e; })();
+      process.exit(report(await rpc("get_ping", { ping_id: extra }), entry));
+    }
+    const question = extra;
+    if (!question) { console.error('usage: human-qa.js poll <name> "question" [--choices "A,B,C"]'); process.exit(2); }
+    // A comparison-shaped question ("does the clone match the real page?") through the
+    // text-poll channel strips the reviewer of the side-by-side compare UI — flagged by
+    // the reviewer TWICE on the iphone17 run. Polls may reference ONE side; a question
+    // naming both sides is a comparison and belongs in a filed test (file --region "…"
+    // scopes a quick compare round). Refusal, not advice — prose rules kept being skipped.
+    const namesTheClone = /\b(clone|draft|replica|copy|ours?|our (page|site|version))\b/i.test(question);
+    const namesTheLive = /\b(original|real|live|reference|apple'?s?|actual)\b[^.]{0,40}\b(page|site|version|one)\b|\bthe (original|real thing)\b/i.test(question);
+    if (namesTheClone && namesTheLive && !args.includes("--allow-comparison")) {
+      console.error(`❌ refusing to poll — this question names BOTH the clone and the live page, which makes it a COMPARISON: the reviewer needs the side-by-side compare UI, not a text question.\n   file a scoped compare round instead: node harness/human-qa.js file ${name} --region "<the section>"\n   (or, if this genuinely isn't a comparison, re-run with --allow-comparison)`);
+      process.exit(1);
+    }
+    // context the human needs to answer a visual question: the verified draft + original
+    let ctx = "";
+    try { ctx += `\nDraft: ${readJson(path.join(targetDir(name), "tunnel.json")).url}`; } catch (e) {}
+    try { ctx += `\nOriginal: ${readJson(path.join(targetDir(name), "target.json")).url}`; } catch (e) {}
+    const choices = (opt("--choices") || "").split(",").map((s) => s.trim()).filter(Boolean);
+    const args_ = { question: question + ctx, n_target: 1, deadline_seconds: 3600 };
+    if (choices.length) args_.choices = choices;
+    const sc = await rpc("ping_humans", args_, 320_000); // server blocks up to ~300s while a human answers
+    const entry = { ping_id: sc.ping_id || null, question, asked_at: new Date().toISOString(), last: null, checked_at: null };
+    hq.polls.push(entry);
+    process.exit(report(sc, entry));
+  }
+
+  console.error(`unknown command "${cmd}" — template | file | record | verify | poll | poll-result`);
+  process.exit(2);
+}
+
+if (require.main === module) main().catch((e) => { console.error(`human-qa: ${e.message}`); process.exit(1); });
+module.exports = { buildSpec, resolveToken };

package/harness/merge-snapshot-selftest.js

@@ -0,0 +1,56 @@
+// harness/merge-snapshot-selftest.js — guards the incremental-capture merge
+// (tools/merge-snapshot.js) and its honesty contract with the done gate. Offline.
+//   - partial elements overwrite; untouched elements carry over; merged stamp accumulates keys
+//   - width / compat-mode mismatch refused (would poison x-positions / #18)
+//   - the done gate refuses a merged (stamped) snapshot; a full re-capture (no stamp) clears it
+// Run: node harness/merge-snapshot-selftest.js   (regression.js runs it too)
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const cp = require("child_process");
+const { mergeSnapshots } = require("../tools/merge-snapshot.js");
+
+const KIT = path.resolve(__dirname, "..");
+let failed = 0;
+const ok = (cond, msg) => { if (cond) console.log(`  ✓ ${msg}`); else { failed++; console.log(`  ✗ ${msg}`); } };
+
+console.log("merge-snapshot-selftest — incremental capture merge + done-gate honesty");
+
+// ── merge semantics (pure) ────────────────────────────────────────────────────
+const snap = (els, width, mode) => ({ viewport: { width }, mode: mode || "CSS1Compat", elements: els });
+{
+  const full = snap({ a: { present: true, v: 1 }, b: { present: true, v: 1 }, c: { present: true, v: 1 } }, 1512);
+  const r = mergeSnapshots(full, snap({ b: { present: true, v: 2 } }, 1512));
+  ok(!r.error && full.elements.b.v === 2 && full.elements.a.v === 1 && r.carried === 2, "partial overwrites its keys; others carry over");
+  ok(full.merged && full.merged.keys.join() === "b", "merge stamps merged:{at,keys}");
+  mergeSnapshots(full, snap({ c: { present: true, v: 2 } }, 1512));
+  ok(full.merged.keys.sort().join() === "b,c", "successive merges ACCUMULATE stamped keys");
+  ok(mergeSnapshots(full, snap({ a: {} }, 1280)).error.includes("width"), "viewport-width mismatch refused");
+  ok(mergeSnapshots(full, snap({ a: {} }, 1512, "BackCompat")).error.includes("modes differ"), "compat-mode mismatch refused (#18)");
+  ok(mergeSnapshots(full, snap({}, 1512)).error.includes("no elements"), "empty partial refused");
+}
+
+// ── done-gate refusal of merged snapshots (through the real workflow) ────────
+{
+  const run = (args) => { const r = cp.spawnSync(process.execPath, [path.join(KIT, "harness", "workflow.js"), ...args], { encoding: "utf8", cwd: KIT }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+  const NAME = "mergeselftest_" + process.pid;
+  const dir = path.join(KIT, "targets", NAME);
+  process.on("exit", () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) {} });
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(path.join(dir, "clone"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "target.json"), JSON.stringify({ name: NAME, url: "https://example.com/", width: 1512 }));
+  run(["init", NAME]);
+  const el = { present: true, rect: { x: 0, y: 0, w: 10, h: 10, top: 0, right: 10, bottom: 10, fromRight: 0 } };
+  const clean = snap({ logo: el }, 1512);
+  fs.writeFileSync(path.join(dir, "clone.json"), JSON.stringify(clean));
+  const stamped = { ...clean, merged: { at: "2026-07-05T00:00:00.000Z", keys: ["logo"] } };
+  fs.writeFileSync(path.join(dir, "live.json"), JSON.stringify(stamped));
+  const refused = run(["gate", NAME, "done"]);
+  ok(refused.code === 1 && /MERGED iteration snapshot/.test(refused.out) && /live\.json/.test(refused.out), "done gate refuses a merged-stamped snapshot, naming the file");
+  fs.writeFileSync(path.join(dir, "live.json"), JSON.stringify(clean));
+  const after = run(["gate", NAME, "done"]);
+  ok(!/MERGED iteration snapshot/.test(after.out), "a full re-capture (stamp gone) clears the refusal (done then blocks on ordinary pending phases only)");
+}
+
+console.log(failed ? `\n❌ merge-snapshot-selftest: ${failed} assertion(s) failed.` : "\n✓ merge-snapshot-selftest: all assertions pass.");
+process.exit(failed ? 1 : 0);

package/harness/new-target.js

@@ -0,0 +1,101 @@
+// harness/new-target.js <name> <url> [width=1728] — scaffold a fresh clone workspace.
+//
+// A "target" is a disposable instance under targets/<name>/. The KIT (tools + the .md
+// instructions) is the product; targets are where you exercise it on a real site. The
+// scaffold is plain HTML/CSS (no build step) so the pixel loop is instant: edit
+// clone/ → refresh → capture → `node harness/score.js <name>`.
+const fs = require("fs"), path = require("path");
+const [, , name, url, widthArg] = process.argv;
+if (!name || !url) { console.error("usage: node harness/new-target.js <name> <url> [width=1728]"); process.exit(1); }
+const width = +(widthArg || 1728);
+// targets/ live in the USER's current directory (WORK), not inside the installed kit (PKG).
+const WORK = process.cwd();
+const dir = path.join(WORK, "targets", name);
+if (fs.existsSync(dir)) { console.error(`targets/${name} already exists — delete it first or pick another name`); process.exit(1); }
+fs.mkdirSync(path.join(dir, "clone", "assets"), { recursive: true });
+
+fs.writeFileSync(path.join(dir, "target.json"), JSON.stringify({ name, url, width }, null, 2) + "\n");
+
+// Seed the ENFORCED workflow state machine (the kit's `gjc`). From here on the clone must
+// pass each phase gate IN ORDER — nothing can claim "pixel-perfect" without the receipts.
+require("./workflow.js").initWorkflow(name, url, width);
+
+fs.writeFileSync(path.join(dir, "clone", "index.html"), `<!doctype html>
+<!-- CHECK LIVE'S DOCTYPE FIRST: if the live page ships no doctype it renders in QUIRKS
+     mode (document.compatMode === "BackCompat") and this standards-mode doctype will
+     shift table-cell line boxes with every computed style identical — delete it to
+     match (LEARNINGS #18). The capture records \`mode\` and the gate fails a mismatch. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${name} — header clone</title>
+  <link rel="stylesheet" href="styles.css" />
+</head>
+<body>
+  <!-- DEFAULT BUILD STRATEGY: capture, don't reconstruct (LEARNINGS #19). Capture the
+       live page's post-hydration DOM (pxSendDom → dom.html) and run
+       \`ppk capture-build <name>\` — it REPLACES this whole scaffold with the captured
+       markup + self-hosted CSS/fonts, inheriting live's doctype and drawing techniques
+       by construction. Hand-rebuild here (to MEASUREMENTS, never guesses) only when the
+       deliverable is a component in your own stack. See ../../PLAYBOOK.md Phase 4. -->
+  <header class="site-header">
+    <!-- TODO: build to spec -->
+  </header>
+
+  <!-- Capture (with \`node tools/sink.js\` running on :7799):
+       const s = await fetch('/tools/browser-capture.js').then(r => r.text()); (0, eval)(s);
+       window.pxRegion = { maxY: 135 };
+       window.pxTargets = [ ["logo", () => document.querySelector('.logo'), false], ... ];
+       await pxSend('http://localhost:7799/clone.json'); -->
+</body>
+</html>
+`);
+
+fs.writeFileSync(path.join(dir, "clone", "styles.css"), `/* ${name} clone — build to measured values */
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  /* Learned default (LEARNINGS #13): most design systems ship antialiased smoothing —
+     matching it up front avoids a "looks thicker" miss the gate would otherwise flag. */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+`);
+
+fs.writeFileSync(path.join(dir, "scores.jsonl"), "");
+fs.writeFileSync(path.join(dir, "NOTES.md"), `# ${name} — ${url} @ ${width}px
+
+## Iteration log
+Record each loop: what a human/you flagged, whether the **gate** caught it, and the fix.
+A flag the gate MISSED is the valuable one — it becomes a tool check + fixture (see DEVELOP.md).
+
+| round | flagged | gate caught it? | fix | kit change (tool/fixture/instruction) |
+|-------|---------|-----------------|-----|----------------------------------------|
+|       |         |                 |     |                                        |
+
+## Site-specific findings
+(structure quirks, faux-bold, etc. — generalize the durable ones into LEARNINGS.md)
+`);
+
+// Print next steps that are RUNNABLE in the invoking context: `ppk …` when launched via the
+// installed ppk entrypoint (PPK_ENTRY set by its delegate), `node harness/…` when someone in
+// the repo ran this script directly (they have no ppk on PATH).
+const viaPpk = process.env.PPK_ENTRY === "1";
+const c = (ppkForm, nodeForm) => (viaPpk ? ppkForm : nodeForm);
+console.log(`created targets/${name}/  (url=${url}, width=${width})
+
+next:
+  ${c("ppk sink &", "node tools/sink.js &")}                 # snapshot receiver on :7799
+  ${c(`ppk serve ${name}`, `node harness/serve.js ${name}`)}          # serves clone + /tools on :8080
+  # 1. open the live site at ${width}px, measure it (RUNBOOK), POST live.json into targets/${name}/
+  # 2. build clone/index.html — DEFAULT: capture it (RUNBOOK "Build by capture"):
+  #      live tab: await pxSendDom('http://localhost:7799/dom.html')
+  #      then:     ${c(`ppk capture-build ${name}`, `node harness/capture-build.js ${name}`)}
+  #    (hand-rebuild to measurements only when the deliverable is a component in your stack)
+  # 3. capture clone.json, then:
+  ${c(`ppk score ${name}`, `node harness/score.js ${name}`)}          # scores this run vs the last (is it better?)
+
+the enforced workflow tracks your phases (target → assets → measure → build → visual → coverage → strict → done):
+  ${c(`ppk status ${name}`, `node harness/workflow.js status ${name}`)}                 # what's done, what's next, whether its gate passes
+  ${c(`ppk advance ${name} <phase>`, `node harness/workflow.js advance ${name} <phase>`)}        # record a phase — refuses unless its gate exits 0`);

package/harness/regression.js

@@ -0,0 +1,50 @@
+// harness/regression.js — the kit's guardrail. Runs the gate-guard (tools/selftest.js)
+// plus every harness/fixtures/*.js. Each class of miss found while cloning a real site
+// becomes a fixture here, so it can never silently come back (that's the whole point:
+// a lesson goes into the TOOL + a fixture, not into a human checklist). Exit nonzero if
+// any fail — wire this into CI or run it before shipping a pixel-diff.js change.
+const { execFileSync } = require("child_process");
+const fs = require("fs"), path = require("path");
+const KIT = path.resolve(__dirname, "..");
+
+const tests = [path.join(KIT, "tools", "selftest.js"), path.join(KIT, "tools", "cli-selftest.js"), path.join(KIT, "harness", "workflow-selftest.js"), path.join(KIT, "harness", "capture-build-selftest.js"), path.join(KIT, "harness", "human-qa-selftest.js"), path.join(KIT, "harness", "tunnel-selftest.js"), path.join(KIT, "harness", "behavior-selftest.js"), path.join(KIT, "harness", "merge-snapshot-selftest.js"), path.join(KIT, "harness", "doctor-selftest.js"), path.join(KIT, "harness", "setup-selftest.js")];
+const fixDir = path.join(__dirname, "fixtures");
+if (fs.existsSync(fixDir))
+  for (const f of fs.readdirSync(fixDir).filter((f) => f.endsWith(".js")).sort()) tests.push(path.join(fixDir, f));
+// the detection-power battery (absolute mode) — asserts the current gate catches every
+// known defect class and flags no control. A broader guard than the per-class fixtures.
+const bench = path.join(__dirname, "benchmarks", "detection-power.js");
+if (fs.existsSync(bench)) tests.push(bench);
+
+let failed = 0;
+
+// SYNTAX GUARD — a kit script that doesn't parse is a broken kit even when no test
+// imports it. Paid for: a template-literal typo in new-target.js shipped while this
+// suite was green, because the scaffold is only ever run by users, never by a test
+// (caught by an agent mid-clone when `ppk new` wouldn't start). `node --check` every
+// kit script so the whole surface at least parses.
+const syntaxFiles = [path.join(KIT, "bin", "ppk")];
+for (const root of ["tools", "harness"].map((d) => path.join(KIT, d))) {
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const fp = path.join(d, e.name);
+      if (e.isDirectory()) walk(fp);
+      else if (e.name.endsWith(".js")) syntaxFiles.push(fp);
+    }
+  };
+  if (fs.existsSync(root)) walk(root);
+}
+let syntaxFailed = 0;
+for (const f of syntaxFiles) {
+  try { execFileSync("node", ["--check", f], { stdio: "pipe" }); }
+  catch (e) { syntaxFailed++; failed++; console.log(`✗ syntax ${path.relative(KIT, f)}`); process.stdout.write((e.stderr || "").toString()); }
+}
+if (!syntaxFailed) console.log(`✓ syntax — all ${syntaxFiles.length} kit scripts parse (node --check)`);
+
+for (const t of tests) {
+  const label = path.relative(KIT, t);
+  try { execFileSync("node", [t], { stdio: "pipe" }); console.log(`✓ ${label}`); }
+  catch (e) { failed++; console.log(`✗ ${label}`); process.stdout.write((e.stdout || "").toString() + (e.stderr || "").toString()); }
+}
+console.log(failed ? `\n❌ regression: ${failed} of ${tests.length} file(s) failed.` : `\n✓ regression: all ${tests.length} file(s) pass — the gate still catches every known class of miss.`);
+process.exit(failed ? 1 : 0);