pixel-perfect-kit 0.1.0

package/harness/tunnel.js

@@ -0,0 +1,241 @@
+// harness/tunnel.js <name> [port=8080] [--check] — a public HTTPS tunnel for the clone,
+// VERIFIED to be serving it before it is ever handed to a human.
+//
+// WHY THIS EXISTS. The human phase needs a PUBLIC url (a remote PingHumans worker opens
+// it; localhost is unreachable), and a test filed against a dead or wrong tunnel burns a
+// whole human round — that was hn's QA round 1 verbatim: "(clone unreachable — tunnel
+// died)". So this tool treats "the tunnel serves the clone" as a gate-shaped fact, not an
+// assumption: it spawns cloudflared, parses the public url, FETCHES it, and byte-compares
+// the response to targets/<name>/clone/index.html. Only a verified tunnel is recorded to
+// targets/<name>/tunnel.json — which human-qa.js then uses as the default --draft, and
+// re-checks at file time (a tunnel verified once can still die before filing).
+//
+// USAGE
+//   node harness/tunnel.js <name> [port=8080]     spawn + verify + record; stays attached
+//                                                 (run it as a background task), Ctrl-C stops it
+//   node harness/tunnel.js <name> --check         re-verify the RECORDED tunnel (exit 0/1)
+//   node harness/tunnel.js --sink [port=7799]     tunnel the SINK: gives live-page captures a
+//                                                 public HTTPS target when the automation
+//                                                 environment blocks page→localhost fetch (the
+//                                                 ~4s abort, RUNBOOK Step 0) — pxSend/pxSendDom
+//                                                 straight through, no stash/chunk fallback.
+//                                                 Verified by the sink's own signature (an empty
+//                                                 POST provokes its distinctive 400 "empty body"
+//                                                 reply); records ./sink-tunnel.json.
+//
+// Needs `cloudflared` on PATH (brew install cloudflared). Quick tunnels need no account.
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { spawn } = require("child_process");
+
+const WORK = process.cwd();
+const targetDir = (name) => path.join(WORK, "targets", name);
+const tunnelPath = (name) => path.join(targetDir(name), "tunnel.json");
+const indexPath = (name) => path.join(targetDir(name), "clone", "index.html");
+const sha = (buf) => crypto.createHash("sha256").update(buf).digest("hex").slice(0, 16);
+
+// The quick-tunnel url is printed to cloudflared's stderr. Pure + exported for the selftest.
+function parseTunnelUrl(logText) {
+  const m = logText.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
+  return m ? m[0] : null;
+}
+
+// Does `url` serve exactly the bytes of `filePath`? file:// urls read from disk, so the
+// compare logic is testable offline (same pattern as capture-build's fetchTo).
+// Returns { ok, reason, sha256 }.
+async function verifyServes(url, filePath) {
+  const expected = fs.readFileSync(filePath);
+  let got;
+  try {
+    if (url.startsWith("file://")) got = fs.readFileSync(new URL(url));
+    else {
+      const r = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(15_000), headers: { "cache-control": "no-cache" } });
+      if (!r.ok) return { ok: false, reason: `HTTP ${r.status} from ${url}` };
+      got = Buffer.from(await r.arrayBuffer());
+    }
+  } catch (e) {
+    return { ok: false, reason: `unreachable: ${url} — ${e.message}` };
+  }
+  if (!got.equals(expected)) return { ok: false, reason: `${url} responds but the bytes are NOT clone/index.html (${got.length} vs ${expected.length} bytes) — wrong port, stale serve, or another app` };
+  return { ok: true, reason: `verified: ${url} serves clone/index.html byte-identically`, sha256: sha(expected) };
+}
+
+// Quick-tunnel hostnames take a while to become reachable: cloudflared prints the url
+// well before the *.trycloudflare.com DNS record propagates, and the lag is measured in
+// tens of seconds, not the ~20s a 10x2s loop allows (found live: the sink-tunnel probe
+// exhausted its retries on plain "fetch failed" DNS misses while the tunnel was fine).
+// 30 attempts x 3s = 90s budget, with a progress line so a long warm-up isn't silent.
+async function warmUp(probe) {
+  let v = { ok: false, reason: "unverified" };
+  for (let i = 0; i < 30 && !v.ok; i++) {
+    v = await probe();
+    if (!v.ok) {
+      if (i > 0 && i % 5 === 0) console.error(`  … still warming up (attempt ${i}/30): ${v.reason.slice(0, 100)}`);
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+  }
+  return v;
+}
+
+// The sink's signature: an empty POST always gets 400 + an "empty body" message
+// (tools/sink.js classifyBody). Proving THAT response comes back through a url proves the
+// real sink answers there — no filesystem coupling, works for local and tunneled checks.
+const looksLikeSink = (status, bodyText) => status === 400 && /empty body/.test(bodyText || "");
+async function probeSink(url) {
+  try {
+    const r = await fetch(url, { method: "POST", body: "", signal: AbortSignal.timeout(15_000) });
+    const text = await r.text();
+    if (looksLikeSink(r.status, text)) return { ok: true, reason: `sink answered at ${url}` };
+    return { ok: false, reason: `${url} answered (HTTP ${r.status}) but NOT like the sink — wrong port or another app: ${text.slice(0, 80)}` };
+  } catch (e) {
+    return { ok: false, reason: `unreachable: ${url} — ${e.message}` };
+  }
+}
+
+async function sinkMain(port) {
+  const local = await probeSink(`http://localhost:${port}/pxprobe.json`);
+  if (!local.ok) { console.error(`❌ no sink on :${port} before tunneling: ${local.reason}\n   start it first: node tools/sink.js  (PPK_SINK_PORT=${port} if non-default)`); process.exit(1); }
+
+  const child = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"], { stdio: ["ignore", "pipe", "pipe"] });
+  child.on("error", (e) => {
+    console.error(e.code === "ENOENT" ? "cloudflared not found — install it: brew install cloudflared" : `cloudflared failed: ${e.message}`);
+    process.exit(1);
+  });
+  let log = "", url = null;
+  const onChunk = (d) => { if (!url) { log += d; url = parseTunnelUrl(log); } };
+  child.stdout.on("data", onChunk);
+  child.stderr.on("data", onChunk);
+  const deadline = Date.now() + 30_000;
+  while (!url && Date.now() < deadline && child.exitCode === null) await new Promise((r) => setTimeout(r, 300));
+  if (!url) { console.error(`❌ no tunnel url within 30s — cloudflared output:\n${log.slice(-800)}`); child.kill(); process.exit(1); }
+
+  const v = await warmUp(() => probeSink(`${url}/pxprobe.json`));
+  if (!v.ok) { console.error(`❌ tunnel came up but the sink never answered through it: ${v.reason}`); child.kill(); process.exit(1); }
+
+  fs.writeFileSync(path.join(WORK, "sink-tunnel.json"), JSON.stringify({ url, port, startedAt: new Date().toISOString() }, null, 2) + "\n");
+  console.log(`✓ sink tunnel ready: ${url}\n  ${v.reason}\n  recorded → ./sink-tunnel.json\n  live-page delivery (no stash/chunk fallback needed):\n    await pxSend('${url}/live.json')\n    await pxSendDom('${url}/dom.html')`);
+
+  const stop = () => { child.kill(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  child.on("exit", (code) => { console.error(`cloudflared exited (${code}) — sink tunnel is DOWN`); process.exit(code || 1); });
+}
+
+// Can `url` serve a real page? For a LIVE DEV SERVER (an adopted external build — ditto's
+// next dev, vite, etc.) byte-identity against a file is meaningless: the check is
+// reachability + a non-trivial HTML body. Weaker than the clone-dir byte check, and the
+// record says so (verified:"reachable").
+async function probeUrl(url) {
+  try {
+    const r = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(15_000), headers: { "cache-control": "no-cache" } });
+    if (!r.ok) return { ok: false, reason: `HTTP ${r.status} from ${url}` };
+    const body = await r.text();
+    if (body.length < 200) return { ok: false, reason: `${url} answered but the body is ${body.length} bytes — not a page (dev server still starting?)` };
+    return { ok: true, reason: `reachable: ${url} serves a ${body.length}-byte page (byte-identity not checkable for a live dev server)` };
+  } catch (e) {
+    return { ok: false, reason: `unreachable: ${url} — ${e.message}` };
+  }
+}
+
+// Tunnel an arbitrary local server (adopted builds run on their OWN dev server, not the
+// kit's static serve). Records targets/<name>/tunnel.json so `ppk human <name> file`
+// picks the public url up as the default --draft, same as clone-dir tunnels.
+async function urlMain(name, localUrl) {
+  let parsed;
+  try { parsed = new URL(localUrl); } catch (e) { console.error(`--url "${localUrl}" is not a valid url`); process.exit(2); }
+  if (!fs.existsSync(targetDir(name))) { console.error(`targets/${name} missing — register the build first: ppk adopt ${name} <original-url>`); process.exit(1); }
+
+  const local = await probeUrl(parsed.href);
+  if (!local.ok) { console.error(`❌ local server check failed before tunneling: ${local.reason}\n   start your build's dev server first (e.g. npm run dev)`); process.exit(1); }
+
+  const child = spawn("cloudflared", ["tunnel", "--url", parsed.origin, "--no-autoupdate"], { stdio: ["ignore", "pipe", "pipe"] });
+  child.on("error", (e) => {
+    console.error(e.code === "ENOENT" ? "cloudflared not found — install it: brew install cloudflared" : `cloudflared failed: ${e.message}`);
+    process.exit(1);
+  });
+  let log = "", url = null;
+  const onChunk = (d) => { if (!url) { log += d; url = parseTunnelUrl(log); } };
+  child.stdout.on("data", onChunk);
+  child.stderr.on("data", onChunk);
+  const deadline = Date.now() + 30_000;
+  while (!url && Date.now() < deadline && child.exitCode === null) await new Promise((r) => setTimeout(r, 300));
+  if (!url) { console.error(`❌ no tunnel url within 30s — cloudflared output:\n${log.slice(-800)}`); child.kill(); process.exit(1); }
+
+  const v = await warmUp(() => probeUrl(url));
+  if (!v.ok) { console.error(`❌ tunnel came up but never served the page: ${v.reason}`); child.kill(); process.exit(1); }
+
+  fs.writeFileSync(tunnelPath(name), JSON.stringify({ url, localUrl: parsed.href, startedAt: new Date().toISOString(), verified: "reachable" }, null, 2) + "\n");
+  console.log(`✓ tunnel ready: ${url}\n  ${v.reason}\n  recorded → targets/${name}/tunnel.json (human-qa uses it as the default --draft)\n  next: node harness/human-qa.js file ${name}`);
+
+  const stop = () => { child.kill(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  child.on("exit", (code) => { console.error(`cloudflared exited (${code}) — tunnel is DOWN; restart before filing human rounds`); process.exit(code || 1); });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--sink")) {
+    const p = args.filter((a) => !a.startsWith("--"))[0];
+    return sinkMain(+(p || process.env.PPK_SINK_PORT || 7799));
+  }
+  const urlIdx = args.indexOf("--url");
+  if (urlIdx >= 0) {
+    const name = args.filter((a, i) => !a.startsWith("--") && i !== urlIdx + 1)[0];
+    if (!name || !args[urlIdx + 1]) { console.error("usage: node harness/tunnel.js <name> --url <http://localhost:3000>"); process.exit(2); }
+    return urlMain(name, args[urlIdx + 1]);
+  }
+  const [name, portArg] = args.filter((a) => !a.startsWith("--"));
+  if (!name) { console.error("usage: node harness/tunnel.js <name> [port=8080] [--check]  |  <name> --url <local-dev-url>  |  --sink [port=7799]"); process.exit(2); }
+
+  if (args.includes("--check")) {
+    if (!fs.existsSync(tunnelPath(name))) { console.error(`no tunnel recorded — start one: node harness/tunnel.js ${name} [port]`); process.exit(1); }
+    const t = JSON.parse(fs.readFileSync(tunnelPath(name), "utf8"));
+    // clone-dir tunnels re-verify byte-identity; adopted-build tunnels (live dev servers)
+    // re-verify reachability — the strongest check each mode supports.
+    const v = fs.existsSync(indexPath(name)) ? await verifyServes(t.url, indexPath(name)) : await probeUrl(t.url);
+    console.log(`${v.ok ? "✓" : "❌"} ${v.reason}`);
+    process.exit(v.ok ? 0 : 1);
+  }
+
+  if (!fs.existsSync(indexPath(name))) { console.error(`targets/${name}/clone/index.html missing — build the clone first (or tunnel an external build's dev server: node harness/tunnel.js ${name} --url <http://localhost:3000>)`); process.exit(1); }
+
+  const port = +(portArg || 8080);
+  // Fail fast if the local serve isn't up — a tunnel to a dead port "works" at the DNS
+  // level and still burns the human round.
+  const local = await verifyServes(`http://localhost:${port}/`, indexPath(name));
+  if (!local.ok) { console.error(`❌ local serve check failed before tunneling: ${local.reason}\n   start it: node harness/serve.js ${name} ${port}`); process.exit(1); }
+
+  const child = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"], { stdio: ["ignore", "pipe", "pipe"] });
+  child.on("error", (e) => {
+    console.error(e.code === "ENOENT" ? "cloudflared not found — install it: brew install cloudflared" : `cloudflared failed: ${e.message}`);
+    process.exit(1);
+  });
+
+  let log = "", url = null;
+  const onChunk = (d) => { if (!url) { log += d; url = parseTunnelUrl(log); } };
+  child.stdout.on("data", onChunk);
+  child.stderr.on("data", onChunk);
+
+  const deadline = Date.now() + 30_000;
+  while (!url && Date.now() < deadline && child.exitCode === null) await new Promise((r) => setTimeout(r, 300));
+  if (!url) { console.error(`❌ no tunnel url within 30s — cloudflared output:\n${log.slice(-800)}`); child.kill(); process.exit(1); }
+
+  // DNS/edge warm-up: retry the public fetch before declaring the tunnel usable.
+  const v = await warmUp(() => verifyServes(url, indexPath(name)));
+  if (!v.ok) { console.error(`❌ tunnel came up but never served the clone: ${v.reason}`); child.kill(); process.exit(1); }
+
+  fs.writeFileSync(tunnelPath(name), JSON.stringify({ url, port, startedAt: new Date().toISOString(), verifiedSha256: v.sha256 }, null, 2) + "\n");
+  console.log(`✓ tunnel ready: ${url}\n  ${v.reason}\n  recorded → targets/${name}/tunnel.json (human-qa.js uses it as the default --draft)\n  next: node harness/human-qa.js file ${name}`);
+
+  const stop = () => { child.kill(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  child.on("exit", (code) => { console.error(`cloudflared exited (${code}) — tunnel is DOWN; restart before filing human tests`); process.exit(code || 1); });
+}
+
+if (require.main === module) main();
+module.exports = { parseTunnelUrl, verifyServes, looksLikeSink, probeSink };

package/harness/workflow-selftest.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * workflow-selftest.js — guards the enforced-workflow state machine (harness/workflow.js).
+ *
+ * The kit's discipline (DEVELOP.md): a lesson goes into a TOOL + a test, never a human
+ * checklist. The workflow engine is now a tool, so it gets its own guard. This asserts the
+ * two properties that make enforcement real:
+ *   1. a gate BLOCKS while its objective condition is unmet, and
+ *   2. it PASSES once the condition is met — and out-of-order / undocumented advances are refused.
+ *
+ * Runs against uniquely-named scratch targets under the repo's targets/ (workflow.js roots
+ * targets/ at cwd, which run() pins to the repo), cleaned up on exit. Exit 0 = green.
+ */
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const cp = require("child_process");
+
+const KIT = path.resolve(__dirname, "..");
+const WF = path.join(KIT, "harness", "workflow.js");
+let failed = 0;
+const ok = (cond, msg) => { if (cond) console.log(`  ✓ ${msg}`); else { failed++; console.log(`  ✗ ${msg}`); } };
+
+// run workflow.js with cwd pinned to KIT, so its cwd-rooted targets/ land under the repo
+// (where `dir` below points) regardless of where regression.js was invoked from.
+// PPK_PINGHUMANS_URL points the human gate at a file:// mock (below) so no test ever
+// touches the network — a socket-blocking sandbox must still run this suite.
+const MOCK = fs.mkdtempSync(path.join(os.tmpdir(), "ppk-hqmock-"));
+process.on("exit", () => { try { fs.rmSync(MOCK, { recursive: true, force: true }); } catch (e) {} });
+const run = (args) => { const r = cp.spawnSync(process.execPath, [WF, ...args], { encoding: "utf8", cwd: KIT, env: { ...process.env, PPK_PINGHUMANS_URL: "file://" + MOCK } }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+const HQ = path.join(KIT, "harness", "human-qa.js");
+const runHq = (args) => { const r = cp.spawnSync(process.execPath, [HQ, ...args], { encoding: "utf8", cwd: KIT, env: { ...process.env, PPK_PINGHUMANS_URL: "file://" + MOCK } }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+
+// A uniquely-named scratch target under KIT/targets, cleaned up after. workflow.js resolves
+// targets/<name> from cwd, which we pin to KIT above.
+const NAME = "selftest_scratch_" + process.pid;
+const dir = path.join(KIT, "targets", NAME);
+const cleanup = () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) {} };
+process.on("exit", cleanup);
+
+const writeJson = (f, o) => fs.writeFileSync(path.join(dir, f), JSON.stringify(o, null, 2));
+const snap = (els, width) => ({ viewport: { width }, elements: els });
+const el = (present = true, extra = {}) => ({ present, rect: { x: 0, y: 0, w: 10, h: 10, top: 0, right: 10, bottom: 10, fromRight: 0 }, ...extra });
+
+cleanup();
+fs.mkdirSync(path.join(dir, "clone", "assets"), { recursive: true });
+writeJson("target.json", { name: NAME, url: "https://example.com/", width: 1728 });
+
+console.log("workflow-selftest — enforced-workflow state machine");
+
+// init
+ok(run(["init", NAME]).code === 0, "init creates workflow.json");
+ok(fs.existsSync(path.join(dir, "workflow.json")), "workflow.json written");
+
+// target gate should pass (target.json is valid)
+ok(run(["gate", NAME, "target"]).code === 0, "target gate passes with valid target.json");
+
+// measure gate BLOCKS before live.json exists
+ok(run(["gate", NAME, "measure"]).code === 1, "measure gate blocks with no live.json");
+
+// out-of-order advance is refused (can't advance measure before target/assets)
+ok(run(["advance", NAME, "measure"]).code === 1, "out-of-order advance (measure before target) refused");
+
+// advance target (machine phase)
+ok(run(["advance", NAME, "target"]).code === 0, "advance target succeeds");
+
+// assets: attested phase → refuses without --evidence
+ok(run(["advance", NAME, "assets"]).code === 1, "attested phase refuses without --evidence");
+// a hand-faked woff2 (wrong magic) must fail the light check even with evidence
+fs.writeFileSync(path.join(dir, "clone", "assets", "fake.woff2"), "NOTAWOFF2FILE");
+ok(run(["advance", NAME, "assets", "--evidence", "x"]).code === 1, "assets gate rejects a woff2 with bad magic bytes");
+fs.rmSync(path.join(dir, "clone", "assets", "fake.woff2"));
+ok(run(["advance", NAME, "assets", "--evidence", "icons+logo captured from live"]).code === 0, "assets advances with evidence + clean assets dir");
+
+// measure: width mismatch blocks, correct width passes
+writeJson("live.json", snap({ logo: el(), nav_first: el(true, { text: { x: 0, right: 5, top: 0, bottom: 5, w: 5, h: 5 }, font: { weight: "400", size: 14, line: 20, spacing: "normal", transform: "none", color: "rgb(0,0,0)", decoration: "none", smoothing: "auto" } }) }, 1440));
+ok(run(["gate", NAME, "measure"]).code === 1, "measure gate blocks on width mismatch (1440 vs 1728)");
+writeJson("live.json", snap({ logo: el(), nav_first: el(true, { text: { x: 0, right: 5, top: 0, bottom: 5, w: 5, h: 5 }, font: { weight: "400", size: 14, line: 20, spacing: "normal", transform: "none", color: "rgb(0,0,0)", decoration: "none", smoothing: "auto" } }) }, 1728));
+ok(run(["advance", NAME, "measure"]).code === 0, "measure advances at the fixed width");
+
+// build: scaffold TODO blocks; real clone.json passes
+fs.writeFileSync(path.join(dir, "clone", "index.html"), "<header><!-- TODO: build to spec --></header>");
+ok(run(["gate", NAME, "build"]).code === 1, "build gate blocks while scaffold TODO remains");
+fs.writeFileSync(path.join(dir, "clone", "index.html"), "<header><a class=logo></a><a>Shop</a></header>");
+writeJson("clone.json", snap({ logo: el(), nav_first: el(true, { text: { x: 0, right: 5, top: 0, bottom: 5, w: 5, h: 5 }, font: { weight: "400", size: 14, line: 20, spacing: "normal", transform: "none", color: "rgb(0,0,0)", decoration: "none", smoothing: "auto" } }) }, 1728));
+ok(run(["advance", NAME, "build"]).code === 0, "build advances with a real clone.json");
+
+// visual: identical snapshots → green
+ok(run(["advance", NAME, "visual"]).code === 0, "visual gate passes when clone matches live");
+
+// coverage: blocks without coverage.json, blocks on an uncovered leaf, passes when all covered
+ok(run(["gate", NAME, "coverage"]).code === 1, "coverage gate blocks with no coverage.json");
+writeJson("coverage.json", ["logo", "nav_first", "ghost_leaf"]);
+ok(run(["gate", NAME, "coverage"]).code === 1, "coverage gate blocks on an uncovered painted leaf");
+writeJson("coverage.json", ["logo", "nav_first"]);
+ok(run(["advance", NAME, "coverage"]).code === 0, "coverage advances when every enumerated leaf is targeted");
+
+// strict: identical snapshots → 0 deltas → passes
+ok(run(["advance", NAME, "strict"]).code === 0, "strict gate passes with 0 structural deltas");
+
+// ── behavior: blocks with no discovery evidence, passes once discovery ran and found nothing ──
+// (behaviorGate itself has a dedicated guard: harness/behavior-selftest.js. Here we only
+// prove the phase is correctly WIRED into the ordered advance sequence between strict/human.)
+ok(run(["gate", NAME, "behavior"]).code === 1, "behavior gate blocks with no behaviors-live.json");
+writeJson("behaviors-live.json", {
+  url: "https://example.com/",
+  discovery: { elementsScanned: 40, scrollSweep: { from: 0, to: 800, steps: 4 }, observeMs: 1200 },
+  behaviors: {},
+});
+ok(run(["advance", NAME, "behavior"]).code === 0, "behavior advances once discovery ran and found no dynamic behaviors");
+
+// ── human: blocks with no round, blocks while pending, blocks on rejection, passes on approval ──
+const PING = "00000000-0000-4000-8000-000000000001";
+ok(run(["gate", NAME, "human"]).code === 1, "human gate blocks with no QA round recorded");
+ok(run(["advance", NAME, "done"]).code === 1, "done refused while human phase is pending");
+ok(runHq(["record", NAME, PING, "--approve", "Region identical"]).code === 0, "human-qa record adopts a filed ping");
+fs.writeFileSync(path.join(MOCK, `get_test_results-${PING}.json`), JSON.stringify({ status: "pending", n_received: 0, n_target: 1, responses: [] }));
+ok(run(["gate", NAME, "human"]).code === 1, "human gate blocks while the round is pending");
+fs.writeFileSync(path.join(MOCK, `get_test_results-${PING}.json`), JSON.stringify({ status: "complete", n_received: 1, n_target: 1, responses: [{ verdict: "Region clearly different", notes: "logo sits low" }] }));
+const rej = run(["gate", NAME, "human"]);
+ok(rej.code === 1 && /logo sits low/.test(rej.out), "human gate blocks on rejection and surfaces the human's flag");
+fs.writeFileSync(path.join(MOCK, `get_test_results-${PING}.json`), JSON.stringify({ status: "complete", n_received: 1, n_target: 1, responses: [{ verdict: "Region identical" }] }));
+ok(run(["advance", NAME, "human"]).code === 0, "human advances on an approving verdict");
+
+ok(run(["advance", NAME, "done"]).code === 0, "done advances once every phase passed in order");
+
+// ledger records the run (refusals are receipted too, so count includes them)
+const readLedger = () => fs.readFileSync(path.join(dir, "workflow.jsonl"), "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+let ledger = readLedger();
+ok(ledger.length >= 7, `ledger recorded ${ledger.length} receipts`);
+ok(ledger.every((r) => r.runId && r.ts && (r.phase || r.event)), "every ledger receipt has runId + ts + phase/event");
+ok(ledger.some((r) => r.gate === "refused"), "refused advances are receipted in the ledger");
+
+// ── done is default-FAIL: a recorded pass must not survive edits to what it certified ──
+{
+  const clonePath = path.join(dir, "clone.json");
+  const original = fs.readFileSync(clonePath, "utf8");
+  const tampered = JSON.parse(original);
+  tampered.elements.nav_first.font.color = "rgb(255,0,0)"; // paint regression after visual passed
+  writeJson("clone.json", tampered);
+  ok(run(["gate", NAME, "done"]).code === 1, "done gate FAILS when a certified artifact was edited (stale visual pass)");
+  // a PAINT delta can never be documented away in deviations.json
+  writeJson("deviations.json", { nav_first: { "font.color": "attempt to excuse a visible mark" } });
+  ok(run(["gate", NAME, "strict"]).code === 1, "strict gate refuses to let deviations.json excuse a PAINT delta");
+  fs.rmSync(path.join(dir, "deviations.json"));
+  fs.writeFileSync(clonePath, original);
+  ok(run(["gate", NAME, "done"]).code === 0, "done gate passes again once the artifact is restored");
+}
+
+// ── --force is never silent: any bypassed enforcement is recorded, and done refuses it ──
+{
+  // assets gate itself passes, but --force bypasses the attestation-evidence requirement:
+  ok(run(["advance", NAME, "assets", "--force"]).code === 0, "--force advance with passing gate succeeds");
+  ledger = readLedger();
+  const last = ledger[ledger.length - 1];
+  ok(last.forced === true && Array.isArray(last.overrode) && last.overrode.includes("evidence"),
+    "forced advance with a PASSING gate still records forced:true + what it overrode");
+  ok(run(["gate", NAME, "done"]).code === 1, "done gate refuses a workflow containing a forced phase");
+  ok(run(["advance", NAME, "assets", "--evidence", "re-attested cleanly"]).code === 0, "clean re-advance clears the forced flag");
+  ok(run(["gate", NAME, "done"]).code === 0, "done gate passes again once no phase is forced");
+}
+
+// ── --evidence must carry a real value, never a flag ──
+ok(run(["advance", NAME, "assets", "--evidence", "--force"]).code === 2, "--evidence followed by a flag is rejected (exit 2)");
+
+// ── schema migration: a pre-`human` workflow.json hydrates as pending, never errors ──
+// (runs while the workflow is fully green, so restoring the saved state must pass done)
+{
+  const statePath = path.join(dir, "workflow.json");
+  const saved = fs.readFileSync(statePath, "utf8");
+  const st = JSON.parse(saved);
+  delete st.phases.human; // simulate a workflow seeded before the kit gained the phase
+  st.phaseOrder = st.phaseOrder.filter((k) => k !== "human");
+  fs.writeFileSync(statePath, JSON.stringify(st, null, 2));
+  const s = run(["status", NAME]);
+  ok(s.code === 0 && /human/.test(s.out), "old-schema workflow.json hydrates the new phase instead of erroring");
+  ok(run(["gate", NAME, "done"]).code === 1, "done gate honestly fails for a migrated workflow until human re-passes");
+  fs.writeFileSync(statePath, saved);
+  ok(run(["gate", NAME, "done"]).code === 0, "restored state passes done again");
+}
+
+// ── init never silently wipes state; resets are receipted; corruption recovers cleanly ──
+{
+  ok(run(["init", NAME]).code === 1, "re-init on recorded state is refused without --force");
+  const statePath = path.join(dir, "workflow.json");
+  fs.writeFileSync(statePath, "{ truncated"); // simulate a killed process / manual edit
+  const r = run(["status", NAME]);
+  ok(r.code === 1 && /corrupt/.test(r.out) && !/at Object\./.test(r.out), "corrupt workflow.json → self-describing error + recovery hint, no raw stack");
+  ok(run(["init", NAME, "--force"]).code === 0, "init --force re-seeds corrupt state");
+  ledger = readLedger();
+  ok(ledger.some((l) => l.event === "reset"), "the forced reset is receipted in the ledger");
+  ok(run(["status", NAME]).code === 0, "status works again after recovery");
+}
+
+// ── directory receipts pin CONTENTS, not just filenames ──
+{
+  const { PHASES: P } = require("./workflow.js");
+  void P; // (imported to assert the module exports cleanly)
+  const sha = require("./workflow.js").sha256OfFile;
+  const d = path.join(dir, "clone", "assets");
+  fs.writeFileSync(path.join(d, "font.woff2"), "wOF2-original-bytes");
+  const before = sha(path.join(dir, "clone"));
+  fs.writeFileSync(path.join(d, "font.woff2"), "wOF2-swapped--bytes"); // same name, different bytes
+  const after = sha(path.join(dir, "clone"));
+  ok(before !== after, "directory sha256 changes when a same-named file's contents change");
+  fs.rmSync(path.join(d, "font.woff2"));
+}
+
+console.log(failed ? `\n❌ workflow-selftest: ${failed} assertion(s) failed.` : `\n✓ workflow-selftest: all assertions pass — gates block when unmet and pass when met.`);
+process.exit(failed ? 1 : 0);