pixel-perfect-kit 0.1.0

package/WORKFLOW.md

@@ -0,0 +1,257 @@
+# WORKFLOW — the enforced pixel-perfect pipeline (`ppk`)
+
+The PLAYBOOK describes the method. This describes the **enforcement**: a hard-gated state
+machine that makes an agent (or you) walk the phases **in order**, and **refuses to let a
+clone claim "pixel-perfect" until every gate has exited 0.** The method was prose the agent
+was *asked* to follow; this is a machine that *won't advance* until the objective condition
+is met.
+
+It's modeled on [gajae-code](https://github.com/Yeachan-Heo/gajae-code)'s `gjc` workflow
+(`deep-interview → ralplan → ultragoal`), reimplemented natively with zero dependencies —
+see **Benchmark vs gajae-code** below for what we borrowed and what we deliberately didn't.
+
+> The kit's one rule holds here too: **a phase is done because its gate exited 0, never
+> because prose says so.**
+
+---
+
+## The phases (in order)
+
+| # | phase      | gate — the objective condition that must hold | kind |
+|---|------------|-----------------------------------------------|------|
+| 1 | `target`   | `target.json` has a url + a fixed width | machine |
+| 2 | `assets`   | any shipped `.woff2` has real `wOF2` magic bytes; icons/logo attested captured, not redrawn | attested |
+| 3 | `measure`  | `live.json` exists, is valid, has elements, measured **at the fixed width** | machine |
+| 4 | `build`    | `clone/index.html` built (no scaffold TODO) + a valid `clone.json` captured | machine |
+| 5 | `visual`   | `pixel-diff --visual` is green (0 pixel-determining fails, matching widths) | machine |
+| 6 | `coverage` | every painted leaf in `coverage.json` has a measured target on **both** pages | machine |
+| 7 | `strict`   | strict deltas are **0**, or every *structural* one is documented in `deviations.json` — a **paint** delta (one that also fails `--visual`) can never be documented away | machine |
+| 8 | `behavior` | every JS-driven dynamic discovered on the LIVE page (animation, rotation, reveal, marquee, counter, hover-mounted content) either reproduces on the clone within a documented tolerance, or is explicitly excused in `behavior-deviations.json` — an empty/absent discovery pass is never a free pass (see "The `behavior` phase" below) | machine |
+| 9 | `human`    | the **latest** PingHumans side-by-side round is human-approved — the verdict is re-fetched from the API on every check (a cached approval is never trusted); a rejection surfaces the human's flags as the fix list | machine |
+| 10 | `done`     | **default-FAIL final verification:** every earlier gate is **re-run** against the current artifacts (a recorded pass is not trusted — it must still hold), in order, and no phase may be forced | machine |
+
+**machine** = the gate fully proves it (exit 0 is a fact). **attested** = it can't be fully
+machine-checked ("this icon is the real one, not hand-drawn"), so the gate does what light
+checks it can and then requires an `--evidence` string, recorded in the audit log and flagged
+`attested` so nobody mistakes an assertion for a proof.
+
+The gates are **build-strategy agnostic** — they verify the artifacts, not how you made
+them. The **default** way to satisfy `build` is `ppk capture-build <name>`: build the clone
+*from the captured live DOM* (self-hosted CSS/fonts, doctype preserved byte-for-byte), which
+eliminates the technique-mismatch defect class the gates are structurally blind to
+(LEARNINGS #19). Hand-rebuild only when the deliverable is a component in your own stack.
+
+---
+
+## Commands
+
+```sh
+node harness/workflow.js status  <name>            # phase table + the next required action
+node harness/workflow.js gate    <name> <phase>    # run ONE gate read-only (exit 0/1) — no state change
+node harness/workflow.js advance <name> <phase> [--evidence "…"] [--force]
+node harness/workflow.js ledger  <name>            # the audit trail (receipts)
+node harness/capture-build.js    <name> [domFile]  # the default build step: clone FROM the captured DOM
+node harness/human-qa.js file    <name> --draft <public-url> [--region "the header"]   # file the human round
+```
+
+### The `behavior` phase (tools/behavior-capture.js + the gate in harness/workflow.js)
+Statics are proven by `visual`/`coverage`/`strict` before this phase runs; `behavior` proves
+the clone's JS-driven dynamics — animations, rotations, reveals, marquees, counters,
+hover-mounted content — reproduce the live page's actual measured behavior, not just its
+static end-state. Method ported verbatim from `lovable_dupe_html/CLONE_PLAYBOOK.md` §8/§8a —
+see `PLAYBOOK.md`'s behavior section for the full technique writeup. In short:
+
+1. **Discover on LIVE** with `tools/behavior-capture.js` (`pxBehaviorDiscover()` /
+   `pxBehaviorSend(url)` / `pxBehaviorStash()` — same injection + delivery rules as
+   `browser-capture.js`, RUNBOOK.md "Golden rules"): a static pass greps `@keyframes` +
+   class/data-attribute markers for CANDIDATES, then a dynamic differential pass (a
+   `MutationObserver` + per-element opacity/transform/filter snapshots across a scripted
+   scroll sweep and hover probes) confirms which candidates actually fire and MEASURES them
+   (marquee px/sec, reveal end-states, hover-mount deltas). Save the result as
+   `targets/<name>/behaviors-live.json`.
+2. **Reproduce** in one vanilla `clone/fixes.js` (no framework — `harness/capture-build.js
+   --fixes` wires `<script src="fixes.js" defer>` before `</body>` and scaffolds a starter
+   file the first time; it never overwrites one you've already written). Each behavior gets
+   its own guarded `try` block, per the playbook.
+3. **Discover on the CLONE** the same way (with `fixes.js` loaded, captured AFTER the same
+   settle procedure as live — scroll sweep + dwell — so end-states match) →
+   `targets/<name>/behaviors-clone.json`.
+4. The gate (`harness/workflow.js`, phase `behavior`) compares every live behavior against
+   the clone's inventory by KEY (see "Behavior keys" below) and MEASURED value, within the
+   tolerances below. A behavior that's genuinely irreproducible statically (e.g. a WebGL
+   generative background) is documented in `targets/<name>/behavior-deviations.json` —
+   `{ "<key>": { "reason": "WebGL generative — irreproducible statically" } }` — the same
+   escape hatch `strict`'s `deviations.json` uses, with the same rule: a behavior that ALSO
+   changes what `--visual` would see (a frozen, still-mid-transition end state) is a paint
+   delta in spirit and should be fixed, not excused.
+
+**"Discovery ran" is itself evidenced**, not inferred from an empty inventory (a
+`behaviors-live.json` with `behaviors: {}` and no `discovery` metadata is indistinguishable
+from a script that silently no-oped, so the gate refuses it as a paint-over). Every capture
+records its own discovery pass metadata — `elementsScanned`, `scrollSweep: {from,to,steps}`,
+`observeMs`, `keyframesFound`, which hover triggers/marquee selectors were probed — and a
+page with genuinely zero dynamic behaviors passes with that metadata cited as the reason.
+
+**Behavior keys.** Each discovered behavior gets a stable string key so live and clone
+inventories compare by identity, not by set overlap: `<prefix>:<descriptor>` where prefix is
+`reveal` (scroll/class-toggle reconciled against a static candidate), `mutation` (an observed
+change with no static marker — pure-JS timed rotations), `marquee` (an explicitly-probed
+translating belt), or `hover` (an explicitly-probed hover-mounted panel/menu); descriptor
+prefers `id`/`data-testid`/`aria-label`, falling back to `tag.class1.class2`, falling back to
+a shallow structural path. Stability matters more than prettiness — the gate does an exact
+key match between live and clone.
+
+**Tolerances** (documented here so a failure message is self-explanatory, the same way
+`--visual`'s 0.5px is):
+- **speed (`pxPerSec`, marquees/scroll-linked motion): ±15% relative.** Two independent
+  1-second `transform` samples carry timer/paint-scheduling jitter (~3–8% observed on a quiet
+  machine); 15% absorbs that while a genuinely wrong speed — the common miss is copying the
+  wrong keyframe duration or belt width, landing at exactly 2x or 0.5x — still fails by a wide
+  margin.
+- **duration (`durationMs`): ±25% relative, 150ms floor.** Wall-clock durations are measured
+  across a network+paint round-trip on BOTH captures (more jitter than a same-machine
+  transform sample); the floor keeps that noise from flagging very short (<600ms)
+  transitions, where 25% would be under a frame's worth of time.
+- **opacity: ±0.05 absolute.** Absorbs float-rounding differences across engines; a
+  fully-revealed `1.0` reproduced as a stuck `0.92` is still a real, visible miss.
+- **transform: matrix-aware compare — ±0.5px on the translation components, ±0.001 on the
+  linear part; non-matrix strings exact.** Computed `transform` normalizes to
+  `none|matrix(...)`, and matrix *translation* inherits layout subpixel rounding — exact
+  string equality would flake on jitter `--visual` itself tolerates, while a genuinely wrong
+  end-state (`-2125px` reproduced as `-1000px`) still fails by three orders of magnitude.
+- **filter / trigger: exact string match.** Not measurements with sampling noise; `trigger`
+  (load/scroll/hover/mutation) records the reproduction TECHNIQUE, which the playbook
+  requires to match, not just land on the right pixels by luck.
+- **`observed-mutation` behaviors (interval rotations) compare by KEY PRESENCE + trigger
+  only.** A continuously-mutating element's snapshot is whatever frame it was on — end-state
+  floats from two independent captures can never agree, so comparing them would be fiction
+  dressed as measurement. The contract is: the clone rotates too (key present, same trigger);
+  its per-frame states are for the human round to judge.
+
+### The `human` phase (harness/human-qa.js)
+Two providers, one contract (an explicit human verdict + pins, machine-checkably
+recorded): **marketplace** (PingHumans, the default — independent reviewers over a
+verified public tunnel) and **local** (`file --local` — the kit's own serve hosts the
+review page at `/__review`: the clone in a same-origin iframe with click-to-pin, the
+same generated step list, the same mandatory verdict buttons; no account, no tunnel).
+The trust model is explicit and travels in the receipts: local rounds record
+`provider:"local"` and verify prints "operator-trusted" — an agent with browser control
+*could* forge a local submission, which is exactly why marketplace review exists and why
+agents are forbidden from ever opening or submitting `/__review` themselves.
+
+The gates prove what the tool measures; a human proves the measured set is what a person
+actually *sees* (LEARNINGS "the gate vs your eyes"). The verdict is machine-checkable, so
+this is a **machine** gate: `human-qa.js verify` re-fetches the latest round's verdict from
+the PingHumans API (same authenticated JSON-RPC transport as `npx cpyany wait`; the
+designer's existing cpyany login is reused) and exits 0 only on approval. The generated
+test is **scope-pinned** — the reviewer judges only the cloned region, per-leaf compare
+steps come from `coverage.json`, and JS behavior is marked *informational* in the human
+template (the `behavior` phase gate is what PROVES dynamics now; the informational step is a
+human backstop for taste/feel and anything intentionally excused in `behavior-deviations.json`,
+not a substitute for the gate) — encoding the lessons stripe's 8 unconverged rounds paid for.
+A rejection prints the human's notes as the fix list (PLAYBOOK Phase 6), and after fixing you
+**refile**; verify always judges the latest round, so a stale approval can't carry a
+regressed clone. Rounds and verdicts live in `targets/<name>/human-qa.json` — the receipt
+pins ping_id + verdict content.
+
+Or via the shim: `./bin/ppk status <name>` (symlink `bin/ppk` onto your PATH for `ppk status <name>`).
+
+`new-target.js` seeds the workflow automatically, so a fresh target starts at phase 1.
+
+### What `advance` enforces
+- **In order.** Advancing phase N is refused while any earlier phase is still pending.
+- **On a passing gate only.** If the gate fails, the advance is refused with the exact reason.
+- **Attestation needs evidence.** An attested phase refuses to advance without `--evidence`
+  (and the evidence value must be real text, never a flag).
+- **`--force` is the escape hatch — and it's never silent.** *Any* enforcement it bypasses —
+  ordering, missing attestation evidence, or a failing gate — records `forced:true` plus an
+  `overrode:[…]` list naming exactly what was skipped. The `done` gate refuses a workflow
+  containing any forced phase until it is cleanly re-advanced.
+- **Refusals are receipted too.** A rejected advance (out of order, missing evidence, failing
+  gate) appends a `gate:"refused"` line to the ledger, so probing the gates leaves a trace.
+
+### Receipts / audit trail
+Every advance appends one line to `targets/<name>/workflow.jsonl`:
+
+```json
+{"ts":"…","phase":"visual","runId":"a1b2c3d4e5","gate":"pass","forced":false,"overrode":[],"sha256":"…","artifact":"targets/x/clone.json","evidence":null,"reason":"--visual PASS — 128 comparisons, 0 fails"}
+```
+
+The `sha256` pins the exact artifact that was verified — a file's bytes, or for a directory
+artifact every file's relative name **and contents** (so a same-named swap changes the hash).
+The receipt proves *what* passed, not just *that* something did. And because `done` re-runs
+every gate, a receipt going stale (artifact edited after certification) is caught before the
+workflow can complete.
+
+### State corruption & recovery
+`workflow.json` is validated on every load. If it's truncated/corrupt/invalid-shape, every
+command fails with the recovery instruction instead of a stack trace: re-seed with
+`ppk init <name> --force`. A forced re-seed **appends a `reset` receipt to the ledger** (the
+ledger itself is append-only and survives), then each phase re-advances by re-running its
+gate against the artifacts on disk — nothing green can be claimed that isn't re-proven.
+
+---
+
+## Files the workflow reads/writes (per target)
+
+- `target.json` — url + fixed width (written by `new-target.js`).
+- `workflow.json` — phase state (status / runId / sha256 / evidence per phase).
+- `workflow.jsonl` — the append-only audit trail.
+- `live.json` / `clone.json` — the measured snapshots (from the RUNBOOK).
+- `coverage.json` — **you create this**: the enumerated painted leaves in the region, e.g.
+  `["logo","nav_first","cart_icon",…]`. The coverage gate checks each has a measured target.
+- `deviations.json` — **you create this** to document accepted structural deltas, e.g.
+  `{ "nav_first": { "layout.display": "flex vs inline-block — identical pixels" } }`.
+- `behaviors-live.json` / `behaviors-clone.json` — the discovered + measured JS-driven
+  dynamics on each page (from `tools/behavior-capture.js`'s `pxBehaviorDiscover()`), each
+  including the discovery pass's own metadata (scroll sweep range, observer duration,
+  elements scanned) as evidence the pass actually ran.
+- `behavior-deviations.json` — **you create this** to document behaviors that are
+  genuinely irreproducible statically, e.g.
+  `{ "mutation:div.hero-canvas": { "reason": "WebGL generative — irreproducible statically" } }`.
+- `human-qa.json` — the human QA rounds (ping_id, approve verdicts, latest fetched
+  result per round), written by `harness/human-qa.js`.
+- `tunnel.json` — the public draft url (`harness/tunnel.js` records it only after
+  byte-verifying it serves `clone/index.html`); `human-qa.js file` uses it as the
+  default `--draft` and re-verifies at file time.
+- `sink-tunnel.json` (workspace-level, not per-target) — a public url in front of the
+  snapshot sink (`harness/tunnel.js --sink`, verified by the sink's own empty-POST
+  signature), so live pages deliver captures with one `pxSend` call even when the
+  automation environment blocks page→localhost fetch.
+- **Merged snapshots**: `tools/merge-snapshot.js` folds a partial re-capture into
+  `live.json`/`clone.json` for fast fix-loop iteration, stamping `merged:{at,keys}`.
+  The `done` gate refuses stamped snapshots — a fix can displace elements outside the
+  re-captured subset, so one final full capture is always required.
+- **Micro-polls**: `human-qa.js poll` puts a ~$0.05 single question in front of a human
+  mid-round (recorded under `polls` in `human-qa.json`). Advisory only — the `human`
+  gate never reads polls; it requires an approving verdict on a full round.
+
+---
+
+## Benchmark vs gajae-code (`gjc`)
+
+gajae-code is the closest existing reference for "an enforced coding-agent workflow." We
+studied its skills (`deep-interview`, `ralplan`, `ultragoal`) as a **pattern reference only** —
+no runtime dependency on `gjc`. How the kit's workflow compares:
+
+| dimension | gajae-code (`gjc`) | pixel-perfect-kit (`ppk`) |
+|---|---|---|
+| Gated pipeline | `deep-interview → ralplan → ultragoal → execute` | `target → assets → measure → build → visual → coverage → strict → behavior → human → done` |
+| Refuses to advance | ambiguity must drop below a resolved threshold; mutation blocked pre-approval | each phase gate must exit 0; advances refused out-of-order or on a failing gate |
+| Definition of done | checkpoint with `--evidence` + `--quality-gate-json` | a gate command that exits 0 (`--visual` green, coverage closed, strict documented) |
+| Audit trail | `index.jsonl` with `run_id` / `path` / `sha256` per stage | `workflow.jsonl` with `runId` / `artifact` / content-`sha256` per advance — including **refused** advances and forced **resets** |
+| Override | explicit force override, recorded | `--force` records `forced:true` + `overrode:[order\|evidence\|gate]`; `done` refuses forced phases until cleanly re-advanced |
+| State corruption recovery | `gjc state clear --force --mode <skill>` re-seeds scoped state | corrupt `workflow.json` → self-describing error + `ppk init <name> --force` (receipted reset; ledger survives) |
+| Objectivity | mathematical ambiguity score (partly heuristic) | **fully numeric** — the "done" signal is a pixel diff exiting 0, not a heuristic score |
+
+**What we borrowed:** the gated-pipeline shape, receipt-based audit trail, and the
+"can't-advance-until-the-gate-passes" discipline.
+
+**What we deliberately didn't:** `gjc`'s multi-agent consensus roles (Planner/Architect/Critic)
+and the mathematical ambiguity scorer. This domain has something `gjc`'s general workflow can't:
+a **fully objective** done-signal (the pixel diff). We don't need a panel to argue about whether
+the clone is right — the numbers decide. The one place human/vision judgment stays in the loop
+is *detection* (PLAYBOOK Phase 6), and that already feeds the DEVELOP meta-loop.
+
+**Possible future step (not built):** run the kit as a `gjc` skill so it becomes a domain
+plugin on top of gajae-code's harness. Left out on purpose to keep the kit zero-dependency.

package/bin/ppk

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// ppk — thin shim so the enforced workflow reads like a real tool: `ppk status aloyoga`.
+// Delegates to harness/workflow.js. Run from the repo, or symlink onto your PATH.
+require("../harness/workflow.js").main();

package/harness/adopt.js

@@ -0,0 +1,52 @@
+// harness/adopt.js — `ppk adopt <name> <url> [width]`: register an EXTERNALLY-BUILT
+// draft for the kit's human-review loop.
+//
+// WHY: the human loop (scope-pinned compare rounds, changelogs on refiles, mandatory
+// verdicts, deviations disclosure, the fix-loop discipline) is useful to ANY builder —
+// ditto's capture-to-code output, a Lovable build, a hand-written recreation. Those
+// builders get you most of the way; the loop with a real human closes the gap. Adopt
+// creates just enough target state for `ppk tunnel` + `ppk human <name> …` to run,
+// WITHOUT the pixel pipeline (no workflow gates — there's no captured live.json/clone.json
+// pair to verify; the human's verdict is the whole check).
+//
+// USAGE:  ppk adopt <name> <url> [width=1512]
+//   then: ppk tunnel <name> --url http://localhost:3000     (your dev server)
+//         ppk human <name> file [--region "…"]              (the loop begins)
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const WORK = process.cwd();
+
+function main() {
+  const [name, url, widthArg] = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  if (!name || !url) { console.error("usage: ppk adopt <name> <url> [width=1512]"); process.exit(2); }
+  let parsed;
+  try { parsed = new URL(url); } catch (e) { console.error(`"${url}" is not a valid url`); process.exit(2); }
+  const dir = path.join(WORK, "targets", name);
+  if (fs.existsSync(path.join(dir, "target.json"))) {
+    console.error(`targets/${name} already exists — pick another name, or continue its loop: ppk human ${name} verify`);
+    process.exit(1);
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "target.json"), JSON.stringify({ name, url: parsed.href, width: +(widthArg || 1512), adopted: true }, null, 2) + "\n");
+  fs.writeFileSync(path.join(dir, "NOTES.md"), `# ${name} — ${parsed.href} (ADOPTED external build — human loop only)
+
+Built by an external tool (ditto / other); the kit runs the human-review loop, not the
+pixel gates. Record each round: what the human flagged, the root cause, the fix.
+
+| round | flagged | root cause | fix |
+|-------|---------|------------|-----|
+|       |         |            |     |
+`);
+  console.log(`✓ adopted targets/${name}  (original: ${parsed.href})
+
+next:
+  1. run your build's dev server (e.g. ditto output: npm i && npm run dev)
+  2. ppk tunnel ${name} --url http://localhost:3000     # public, reachability-verified
+  3. ppk human ${name} file [--region "…"]              # first review round
+  loop: fix what the human pins → refile with --changelog "…" → until the verdict approves.`);
+}
+
+main();

package/harness/agent-setup.js

@@ -0,0 +1,55 @@
+// harness/agent-setup.js — `ppk agent-setup`: teach the user's AI agent to use the kit.
+//
+// The kit's entire new-user experience is "install, then ask your agent to clone a
+// site" — this is the command that makes the second half true. It installs the kit's
+// clone-site skill into the user's agent skill directory (~/.claude/skills/), where
+// Claude Code auto-discovers it: from then on, "clone https://example.com" in any
+// session triggers the skill, which drives the full ppk pipeline and treats the user
+// as the reviewer.
+//
+// USAGE:  ppk agent-setup [--force]     (--force overwrites an existing install)
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const PKG = path.resolve(__dirname, "..");
+
+function install(homeDir, force) {
+  // Every skill the kit ships lives in PKG/skill/<skill-name>/SKILL.md — install them
+  // all (pixel-perfect-clone: the full gated pipeline; ditto-finish: bring-your-own
+  // builder + the human loop). One kit, several front doors.
+  const skillRoot = path.join(PKG, "skill");
+  if (!fs.existsSync(skillRoot)) return { ok: false, message: `kit skills missing at ${skillRoot} — broken install; reinstall pixel-perfect-kit`, installed: [] };
+  const names = fs.readdirSync(skillRoot, { withFileTypes: true }).filter((e) => e.isDirectory() && fs.existsSync(path.join(skillRoot, e.name, "SKILL.md"))).map((e) => e.name);
+  if (!names.length) return { ok: false, message: `no skills found under ${skillRoot} — broken install; reinstall pixel-perfect-kit`, installed: [] };
+
+  const installed = [], skipped = [];
+  for (const n of names) {
+    const dest = path.join(homeDir, ".claude", "skills", n, "SKILL.md");
+    if (fs.existsSync(dest) && !force) { skipped.push(n); continue; }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(skillRoot, n, "SKILL.md"), dest);
+    installed.push(n);
+  }
+  if (!installed.length) {
+    return { ok: false, message: `already installed (${skipped.join(", ")}) — re-run with --force to overwrite with this kit version's copies`, installed };
+  }
+  return { ok: true, installed, message: `✓ installed skill(s): ${installed.join(", ")}${skipped.length ? `  (kept existing: ${skipped.join(", ")} — --force to refresh)` : ""}
+  → ${path.join(homeDir, ".claude", "skills")}
+  Your agent picks them up on its next session. Then just ask it:
+    "Clone https://example.com pixel-perfect."            (the full gated pipeline)
+    "Clone https://example.com with ditto and polish it." (ditto build + human rounds)
+  (You'll be the reviewer: answer the pings — pin what looks wrong, always pick a verdict button.)` };
+}
+
+function main() {
+  const force = process.argv.includes("--force");
+  const r = install(os.homedir(), force);
+  console.log(r.message);
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (require.main === module) main();
+module.exports = { install };

package/harness/behavior-selftest.js

@@ -0,0 +1,243 @@
+// harness/behavior-selftest.js — guards the `behavior` phase gate (harness/workflow.js's
+// behaviorGate). Offline, socket-free: drives the gate purely through
+// targets/<name>/behaviors-live.json / behaviors-clone.json / behavior-deviations.json
+// fixtures on disk (no browser, no network) — the same file-fixture pattern
+// workflow-selftest.js uses for live.json/clone.json.
+//
+// Asserts the contracts the design contract calls out explicitly:
+//   - blocks on missing inventory (live, then clone)
+//   - blocks on a live behavior absent from the clone inventory, NAMED in the reason
+//   - blocks on out-of-tolerance values (speed, opacity, transform mismatch)
+//   - passes on within-tolerance reproduction
+//   - passes on a documented deviation
+//   - fails a paint-over of "no discovery ran" (empty behaviors + no discovery metadata)
+//   - passes when discovery legitimately found nothing (metadata present, behaviors empty)
+"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}`); } };
+
+const run = (args) => { const r = cp.spawnSync(process.execPath, [WF, ...args], { encoding: "utf8", cwd: KIT }); return { code: r.status, out: (r.stdout || "") + (r.stderr || "") }; };
+
+const NAME = "behaviorselftest_" + 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);
+cleanup();
+fs.mkdirSync(path.join(dir, "clone", "assets"), { recursive: true });
+
+const writeJson = (f, o) => fs.writeFileSync(path.join(dir, f), JSON.stringify(o, null, 2));
+
+// discovery metadata that COUNTS as "discovery actually ran" — mirrors the shape
+// tools/behavior-capture.js's discover() emits
+const discoveryMeta = (extra) => Object.assign({
+  startedAt: "2026-07-02T00:00:00.000Z", endedAt: "2026-07-02T00:00:03.000Z", durationMs: 3000,
+  scrollSweep: { from: 0, to: 4000, steps: 6 },
+  observeMs: 1500,
+  elementsScanned: 812,
+  staticCandidateCount: 5,
+  keyframesFound: ["logo-belt"],
+  hoverTriggersProbed: [],
+  marqueeSelectorsProbed: [],
+}, extra || {});
+
+console.log("behavior-selftest — the `behavior` phase gate");
+run(["init", NAME]); // seed workflow.json (harmless if it errors on a fresh dir — ignored)
+
+// ── missing live inventory blocks ────────────────────────────────────────────
+ok(run(["gate", NAME, "behavior"]).code === 1, "blocks with no behaviors-live.json");
+const missLive = run(["gate", NAME, "behavior"]);
+ok(/behaviors-live\.json missing/.test(missLive.out), "reason names the missing live inventory file");
+
+// ── a paint-over of "no discovery ran" fails: empty behaviors, NO discovery metadata ──
+writeJson("behaviors-live.json", { url: "https://example.com/", behaviors: {} });
+const paintOver = run(["gate", NAME, "behavior"]);
+ok(paintOver.code === 1, "blocks when behaviors-live.json has an empty inventory but NO discovery metadata (paint-over)");
+ok(/discovery pass metadata|paint-over/i.test(paintOver.out), "reason calls out the missing discovery evidence, not just 'no behaviors'");
+
+// ── legitimate "discovery ran, found nothing" passes and cites the evidence ──
+writeJson("behaviors-live.json", { url: "https://example.com/", discovery: discoveryMeta(), behaviors: {} });
+const noneFound = run(["gate", NAME, "behavior"]);
+ok(noneFound.code === 0, "passes when discovery metadata is present and genuinely found zero behaviors");
+ok(/elements scanned/.test(noneFound.out) && /scroll swept 0.4000px/.test(noneFound.out.replace(/→/, ".")), "pass reason cites discovery metadata (elements scanned, scroll sweep) as evidence discovery ran");
+
+// ── a live behavior with no clone inventory at all blocks ───────────────────
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "marquee:logo_belt": { trigger: "load", kind: "marquee", measured: { pxPerSec: 35.4 } } },
+});
+const noClone = run(["gate", NAME, "behavior"]);
+ok(noClone.code === 1 && /behaviors-clone\.json missing/.test(noClone.out) && /marquee:logo_belt/.test(noClone.out), "blocks when clone inventory is entirely absent, names the live behavior waiting on it");
+
+// ── a live behavior absent from the clone inventory blocks, NAMED ───────────
+writeJson("behaviors-clone.json", { url: "http://localhost:8080/", discovery: discoveryMeta(), behaviors: {} });
+const missingOne = run(["gate", NAME, "behavior"]);
+ok(missingOne.code === 1 && /MISSING/.test(missingOne.out) && /marquee:logo_belt/.test(missingOne.out), "blocks when a live behavior is silently missing from the clone, and names it");
+
+// ── out-of-tolerance speed blocks (2x speed marquee must not slip through) ──
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "marquee:logo_belt": { trigger: "load", kind: "marquee", measured: { pxPerSec: 70.8 } } }, // exactly 2x live
+});
+const tooFast = run(["gate", NAME, "behavior"]);
+ok(tooFast.code === 1 && /pxPerSec/.test(tooFast.out) && /marquee:logo_belt/.test(tooFast.out), "blocks a 2x-speed marquee (out of the ±15% pxPerSec tolerance)");
+
+// ── within-tolerance speed passes (absorbs sampling noise) ───────────────────
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "marquee:logo_belt": { trigger: "load", kind: "marquee", measured: { pxPerSec: 36.9 } } }, // ~4% off — within ±15%
+});
+const closeEnough = run(["gate", NAME, "behavior"]);
+ok(closeEnough.code === 0, "passes a marquee sampled ~4% off live speed (within the documented ±15% tolerance)");
+
+// ── trigger technique mismatch blocks even if the numbers happen to line up ──
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { before: { opacity: 0, transform: "translateY(20px)", filter: "none" }, after: { opacity: 1, transform: "none", filter: "none" } } } },
+});
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "load", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "none", filter: "none" } } } },
+});
+const wrongTrigger = run(["gate", NAME, "behavior"]);
+ok(wrongTrigger.code === 1 && /trigger/.test(wrongTrigger.out) && /reveal:hero_heading/.test(wrongTrigger.out), "blocks when the reproduction technique (trigger) differs from live, even with matching end-state numbers");
+
+// ── out-of-tolerance end-state opacity blocks (clone frozen short of live's reveal) ──
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 0.4, transform: "none", filter: "none" } } } },
+});
+const frozen = run(["gate", NAME, "behavior"]);
+ok(frozen.code === 1 && /opacity/.test(frozen.out) && /hero_heading/.test(frozen.out), "blocks a reveal frozen short of live's end-state opacity");
+
+// ── out-of-tolerance end-state transform blocks (live fully translates away, clone doesn't) ──
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "translateY(-40px)", filter: "none" } } } },
+});
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "translateY(-10px)", filter: "none" } } } },
+});
+const wrongTransform = run(["gate", NAME, "behavior"]);
+ok(wrongTransform.code === 1 && /transform/.test(wrongTransform.out) && /hero_heading/.test(wrongTransform.out), "blocks when the reproduced end-state transform string doesn't match live's exactly");
+
+// ── matrix translation jitter passes (computed transforms are matrices; layout rounds them) ──
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "matrix(1, 0, 0, 1, 0, -40.003)", filter: "none" } } } },
+});
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "matrix(1, 0, 0, 1, 0, -40.2)", filter: "none" } } } },
+});
+ok(run(["gate", NAME, "behavior"]).code === 0, "passes matrix transforms whose translation differs by sub-0.5px layout rounding (matrix-aware compare, not string equality)");
+
+// ── observed-mutation (interval rotations) compare by PRESENCE, not frame snapshots ──
+// A rotating hero's transform at snapshot time is whatever frame it was on — two captures of
+// a continuously-mutating element can never agree on end-state floats. Presence + trigger
+// match are the contract; a clone that ALSO rotates passes, one missing the key blocks.
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "mutation:div.hero-rotator": { trigger: "mutation", kind: "observed-mutation", measured: { after: { opacity: 1, transform: "matrix(1, 0, 0, 1, 0, -333.2)", filter: "none" } } } },
+});
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "mutation:div.hero-rotator": { trigger: "mutation", kind: "observed-mutation", measured: { after: { opacity: 0.4, transform: "matrix(1, 0, 0, 1, 0, -80)", filter: "none" } } } },
+});
+ok(run(["gate", NAME, "behavior"]).code === 0, "passes an interval rotation whose frame snapshots differ (observed-mutation: presence+trigger are the contract, frames are nondeterministic)");
+writeJson("behaviors-clone.json", { url: "http://localhost:8080/", discovery: discoveryMeta(), behaviors: {} });
+ok(run(["gate", NAME, "behavior"]).code === 1, "an observed-mutation key missing from the clone still blocks (the clone must rotate at all)");
+
+// reset live back to the simple opacity-reveal case used by the remaining assertions below
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { before: { opacity: 0, transform: "translateY(20px)", filter: "none" }, after: { opacity: 1, transform: "none", filter: "none" } } } },
+});
+
+// ── within-tolerance reproduction passes ─────────────────────────────────────
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 0.98, transform: "none", filter: "none" } } } }, // opacity 0.02 off — within ±0.05
+});
+ok(run(["gate", NAME, "behavior"]).code === 0, "passes a reveal that lands within the ±0.05 opacity tolerance with matching transform/trigger");
+
+// ── multiple live behaviors: one within tolerance, one documented deviation ─
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: {
+    "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "none", filter: "none" } } },
+    "generative:webgl_bg": { trigger: "load", kind: "canvas-generative", measured: { after: { opacity: 1 } } },
+  },
+});
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:hero_heading": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "none", filter: "none" } } } },
+});
+const undocumented = run(["gate", NAME, "behavior"]);
+ok(undocumented.code === 1 && /generative:webgl_bg/.test(undocumented.out) && /MISSING/.test(undocumented.out), "an undocumented missing behavior still blocks even when other behaviors reproduce cleanly");
+writeJson("behavior-deviations.json", { "generative:webgl_bg": { reason: "WebGL generative canvas — irreproducible statically, per-frame noise procedurally generated" } });
+const withDeviation = run(["gate", NAME, "behavior"]);
+ok(withDeviation.code === 0 && /documented deviation/.test(withDeviation.out) && /generative:webgl_bg/.test(withDeviation.out), "passes once the irreproducible behavior is documented in behavior-deviations.json, and says so");
+
+// a deviation entry with an empty/missing reason doesn't count as documented (never a free pass)
+writeJson("behavior-deviations.json", { "generative:webgl_bg": { reason: "" } });
+ok(run(["gate", NAME, "behavior"]).code === 1, "an empty-reason deviation entry does NOT count as documented — still blocks");
+fs.rmSync(path.join(dir, "behavior-deviations.json"));
+
+// ── DECLARED rows (environment-inverted runs): every supposed-to-move element needs a
+//    disposition — reproduced (descriptor observed firing on the clone) or excused.
+//    Silently dropping one is how a single invented animation replaces two real ones. ──
+writeJson("behaviors-live.json", {
+  url: "https://example.com/", discovery: discoveryMeta(),
+  behaviors: {},
+  declared: {
+    "declared:video#intro-video": { hints: ["video:scripted:none", "attr:data-video-load-kf"], startState: { opacity: 1, transform: "none", filter: "none" }, text: null },
+    "declared:span.gradient-headline": { hints: ["transition-from-start-state"], startState: { opacity: 0, transform: "none", filter: "none" }, text: "18MP Center Stage front" },
+  },
+});
+writeJson("behaviors-clone.json", { url: "http://localhost:8080/", discovery: discoveryMeta(), behaviors: {} });
+const undisposed = run(["gate", NAME, "behavior"]);
+ok(undisposed.code === 1 && /DECLARED/.test(undisposed.out) && /behavior-worksheet/.test(undisposed.out), "undisposed declared rows block, pointing at the worksheet");
+ok(/intro-video/.test(undisposed.out), "the blocked reason names the undisposed declared row");
+
+// reproduced via descriptor match: the clone observed the same element firing under an
+// observed prefix (reveal:) — declared:span.gradient-headline ↔ reveal:span.gradient-headline
+writeJson("behaviors-clone.json", {
+  url: "http://localhost:8080/", discovery: discoveryMeta(),
+  behaviors: { "reveal:span.gradient-headline": { trigger: "scroll", kind: "class-toggle-or-style-mutation", measured: { after: { opacity: 1, transform: "none", filter: "none" } } } },
+});
+writeJson("behavior-deviations.json", { "declared:video#intro-video": { reason: "phone-screen video asset not shipped in the captured DOM — awaiting reviewer description of live playback" } });
+const disposed = run(["gate", NAME, "behavior"]);
+ok(disposed.code === 0 && /2 declared row\(s\) disposed \(1 reproduced, 1 excused\)/.test(disposed.out), "declared rows pass once each is reproduced (descriptor match) or excused, and the receipt counts them");
+
+// worksheet CLI mirrors the same disposition logic + prints poll questions for unresolved
+{
+  const cpx = require("child_process");
+  fs.rmSync(path.join(dir, "behavior-deviations.json"));
+  const w1 = cpx.spawnSync(process.execPath, [path.join(KIT, "tools", "behavior-worksheet.js"), NAME], { encoding: "utf8", cwd: KIT });
+  ok(w1.status === 1 && /UNRESOLVED/.test(w1.stdout + w1.stderr) && /human-qa\.js poll/.test(w1.stdout + w1.stderr), "worksheet exits 1 on unresolved rows and prints a ready-to-send one-sided poll question");
+  writeJson("behavior-deviations.json", { "declared:video#intro-video": { reason: "awaiting reviewer description" } });
+  const w2 = cpx.spawnSync(process.execPath, [path.join(KIT, "tools", "behavior-worksheet.js"), NAME], { encoding: "utf8", cwd: KIT });
+  ok(w2.status === 0 && /worksheet clean/.test(w2.stdout), "worksheet exits 0 once every row is disposed");
+}
+fs.rmSync(path.join(dir, "behavior-deviations.json"), { force: true });
+fs.rmSync(path.join(dir, "behaviors-live.json"), { force: true });
+fs.rmSync(path.join(dir, "behaviors-clone.json"), { force: true });
+
+// ── advance wiring: behavior sits between strict and human in phaseOrder ────
+{
+  const { PHASES } = require(WF);
+  const keys = PHASES.map((p) => p.key);
+  ok(keys.indexOf("behavior") === keys.indexOf("strict") + 1, "behavior phase immediately follows strict");
+  ok(keys.indexOf("human") === keys.indexOf("behavior") + 1, "human phase immediately follows behavior");
+}
+
+console.log(failed ? `\n❌ behavior-selftest: ${failed} assertion(s) failed.` : "\n✓ behavior-selftest: all assertions pass — the gate blocks when unmet and passes when met.");
+process.exit(failed ? 1 : 0);