The design language that makes your AI harness better at design.
JavaScript
Write decision comp prompts in reading order and check each render once per round (#955)
Paul Bakausf3132ffe7e8a
diff --git a/crates/context/src/serve_question.rs b/crates/context/src/serve_question.rsindex 4119dd1de..345091b94 100644--- a/crates/context/src/serve_question.rs+++ b/crates/context/src/serve_question.rs@@ -50,6 +50,12 @@ fn flip_file(qdir: &str, key: &str) -> String {fn next_file(qdir: &str, key: &str) -> String {jsp::join(&[qdir, &format!("{}.next.json", key)])}+/// `<key>.render-check`: the id of the hand whose render-check line `--wait`+/// already printed, so the line prints once per round, not once per poll. A+/// new hand carries a new id, so the next round prints it again.+fn render_check_file(qdir: &str, key: &str) -> String {+ jsp::join(&[qdir, &format!("{}.render-check", key)])+}/// `process.kill(pid, 0)`: Ok(()) alive, Err(true) EPERM (alive but unsignalable), Err(false) dead.fn pid_probe(pid: i64) -> Result<(), bool> {@@ -476,6 +482,34 @@ fn sidecar_missing_line(env: &Env, cwd: &str, missing: &[String]) -> String {)}+/// This hand's landed decision comps that carry their prompt sidecar: the+/// renders the agent owes visualize.md's post-render checks. Comp-round comps+/// sit outside this: the decision round is where the checks go unrun.+fn landed_decision_comps(cwd: &str, comps: &[String], hand: Option<&Map<String, Value>>) -> bool {+ comps.iter().any(|c| !is_comp_round_comp(c) && comp_is_this_hands(cwd, c, hand) && exists(&format!("{}.json", jsp::resolve(cwd, &[c.as_str()]))))+}++/// The `--wait` render-check directive: once per hand, the first poll that+/// finds a landed decision comp with its sidecar while the user is deciding.+fn render_check_line(env: &Env, cwd: &str) -> String {+ format!(+ "NEXT open each decision comp once and run {}'s render checks (shipped screen, one dominant move); regenerate any that fail before the user answers.\n",+ visualize_ref(env, cwd)+ )+}++/// Whether this poll owes the render-check line, recording that it was owed+/// so the next poll of the same hand stays quiet.+fn render_check_due(qdir: &str, key: &str, hand: Option<&Map<String, Value>>) -> bool {+ let id = hand.map(hand_marker_id).unwrap_or_default();+ let marker = render_check_file(qdir, key);+ if safe_read(&marker).as_deref() == Some(id.as_str()) {+ return false;+ }+ let _ = std::fs::write(&marker, &id);+ true+}+/// The comps recorded for the live round in `<key>.state.json`.fn state_comps(state: &Map<String, Value>) -> Vec<String> {state.get("comps").and_then(Value::as_array).map(|a| a.iter().filter_map(|v| v.as_str().map(str::to_string)).collect()).unwrap_or_default()@@ -610,10 +644,10 @@ pub fn run(argv: &[String], io: &mut Io) -> i32 {return 4;}// Read before the answer path may delete the state file.- let (missing, stale) = {- let hand = read_hand(&qdir, &key);+ let hand = read_hand(&qdir, &key);+ let (missing, stale, landed) = {let comps = round_comps(hand.as_ref(), read_state(&qdir, &key).as_ref());- (comps_missing_sidecar(&cwd, &comps, hand.as_ref()), stale_comps(&cwd, &comps, hand.as_ref()))+ (comps_missing_sidecar(&cwd, &comps, hand.as_ref()), stale_comps(&cwd, &comps, hand.as_ref()), landed_decision_comps(&cwd, &comps, hand.as_ref()))};if !answered() {io.out(&format!("WAITING: no answer yet after {}s; run --wait --key {} again\n", crate::util::js_number_to_string(poll_sec), key));@@ -625,6 +659,9 @@ pub fn run(argv: &[String], io: &mut Io) -> i32 {if !stale.is_empty() {io.out(&stale_comps_line(&env, &cwd, &stale));}+ if landed && render_check_due(&qdir, &key, hand.as_ref()) {+ io.out(&render_check_line(&env, &cwd));+ }return 3;}let collected = safe_read(&answer_file(&qdir, &key)).unwrap_or_default();@@ -641,6 +678,7 @@ pub fn run(argv: &[String], io: &mut Io) -> i32 {if !keeps_open {let _ = std::fs::remove_file(state_file(&qdir, &key));let _ = std::fs::remove_file(hand_file(&qdir, &key));+ let _ = std::fs::remove_file(render_check_file(&qdir, &key));let _ = std::fs::remove_dir_all(generated_dir(&qdir, &key));}return 0;@@ -659,7 +697,8 @@ pub fn run(argv: &[String], io: &mut Io) -> i32 {let _ = std::fs::remove_file(answer_file(&qdir, &key));let _ = std::fs::remove_file(state_file(&qdir, &key));let _ = std::fs::remove_file(hand_file(&qdir, &key));- let _ = std::fs::remove_dir_all(generated_dir(&qdir, &key));+ let _ = std::fs::remove_file(render_check_file(&qdir, &key));+ let _ = std::fs::remove_dir_all(generated_dir(&qdir, &key));io.out("stopped\n");return 0;}@@ -2171,6 +2210,91 @@ mod tests {let _ = std::fs::remove_dir_all(&dir);}+ #[test]+ fn wait_prints_the_render_check_once_per_hand() {+ const LINE: &str = "NEXT open each decision comp once and run ";+ let dir = temp_project("wait-render-check");+ let cwd = dir.to_string_lossy().into_owned();+ let qdir = jsp::join(&[&cwd, ".impeccable", "questions"]);+ let comps = [".impeccable/mocks/decision/a.png", ".impeccable/mocks/decision/b.png"];+ let payload = json!({ "options": comps.iter().map(|c| json!({ "comp": c })).collect::<Vec<_>>() });+ let state = json!({ "pid": std::process::id(), "port": 1, "url": "http://127.0.0.1:1/", "comps": comps });+ std::fs::write(dir.join(".impeccable/questions/k1.state.json"), state.to_string()).unwrap();+ write_hand(&qdir, "k1", &new_hand(&cwd, &payload)).unwrap();+ let wait = || {+ let (code, out) = run_captured(&dir, &["--wait", "--key", "k1", "--poll", "0"]);+ assert_eq!(code, 3);+ out.replace('\\', "/")+ };++ // Nothing landed yet: no line.+ assert!(!wait().contains(LINE));+ // A comp landed without its sidecar is not ready to be checked.+ std::fs::write(dir.join(comps[0]), b"png").unwrap();+ assert!(!wait().contains(LINE));++ // The first wait after a comp lands with its sidecar prints it once.+ std::fs::write(dir.join(format!("{}.json", comps[0])), r#"{"prompt":"p"}"#).unwrap();+ let out = wait();+ // Windows resolves the skill dir with a drive letter, so match from the path on.+ assert!(out.contains("/skill/reference/visualize.md's render checks (shipped screen, one dominant move); regenerate any that fail before the user answers.\n"), "{out}");+ assert_eq!(out.matches(LINE).count(), 1, "{out}");+ // Later polls of the same hand stay quiet, even as more comps land.+ assert!(!wait().contains(LINE));+ std::fs::write(dir.join(comps[1]), b"png").unwrap();+ std::fs::write(dir.join(format!("{}.json", comps[1])), r#"{"prompt":"p"}"#).unwrap();+ assert!(!wait().contains(LINE));++ // A new hand (an --update round) prints it again once its comps land.+ std::fs::remove_file(dir.join(comps[0])).unwrap();+ std::fs::remove_file(dir.join(comps[1])).unwrap();+ write_hand(&qdir, "k1", &new_hand(&cwd, &payload)).unwrap();+ assert!(!wait().contains(LINE));+ std::fs::write(dir.join(comps[0]), b"png2").unwrap();+ assert!(wait().contains(LINE));+ assert!(!wait().contains(LINE));++ // Never after the pick: the answer is the user's, not a poll.+ write_hand(&qdir, "k1", &new_hand(&cwd, &payload)).unwrap();+ std::fs::write(dir.join(comps[0]), b"png3").unwrap();+ std::fs::write(dir.join(".impeccable/questions/k1.answer.json"), r#"{"optionId":"a"}"#).unwrap();+ let (code, out) = run_captured(&dir, &["--wait", "--key", "k1", "--poll", "2"]);+ assert_eq!(code, 0);+ assert!(!out.contains(LINE), "{out}");+ assert!(!dir.join(".impeccable/questions/k1.render-check").exists());+ let _ = std::fs::remove_dir_all(&dir);+ }++ #[test]+ fn wait_skips_the_render_check_for_code_led_and_comp_round_comps() {+ const LINE: &str = "NEXT open each decision comp once and run ";+ let dir = temp_project("wait-render-check-skip");+ let cwd = dir.to_string_lossy().into_owned();+ let qdir = jsp::join(&[&cwd, ".impeccable", "questions"]);+ // Code-led: the slots are a flip reserve. A file there predates the+ // hand (an earlier round's), so it is not this hand's comp.+ let slot = ".impeccable/mocks/decision/a.png";+ std::fs::write(dir.join(slot), b"old").unwrap();+ std::fs::write(dir.join(format!("{}.json", slot)), r#"{"prompt":"p"}"#).unwrap();+ let payload = json!({ "options": [{ "comp": slot }], "buildPath": { "value": "code", "toggle": true } });+ let state = json!({ "pid": std::process::id(), "port": 1, "url": "http://127.0.0.1:1/", "comps": [slot] });+ std::fs::write(dir.join(".impeccable/questions/k1.state.json"), state.to_string()).unwrap();+ write_hand(&qdir, "k1", &new_hand(&cwd, &payload)).unwrap();+ let (_, out) = run_captured(&dir, &["--wait", "--key", "k1", "--poll", "0"]);+ assert!(!out.contains(LINE), "{out}");++ // The comp round's own comps are not decision comps.+ let comp = ".impeccable/mocks/comp-b.png";+ std::fs::write(dir.join(comp), b"png").unwrap();+ std::fs::write(dir.join(format!("{}.json", comp)), r#"{"prompt":"p"}"#).unwrap();+ let state = json!({ "pid": std::process::id(), "port": 1, "url": "http://127.0.0.1:1/", "comps": [comp] });+ std::fs::write(dir.join(".impeccable/questions/k2.state.json"), state.to_string()).unwrap();+ write_hand(&qdir, "k2", &new_hand(&cwd, &json!({ "options": [{ "comp": comp }] }))).unwrap();+ let (_, out) = run_captured(&dir, &["--wait", "--key", "k2", "--poll", "0"]);+ assert!(!out.contains(LINE), "{out}");+ let _ = std::fs::remove_dir_all(&dir);+ }+#[test]fn update_prints_the_visualize_directive_only_when_comps_are_due() {let dir = temp_project("update-next");diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex f702e9083..2800d367b 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -441,10 +441,11 @@ retain their local-development trust behavior. See [bundle signing](BUNDLE-SIGNI- default (blocking): loads payload (error → stderr `serve-question: payload needs an options array` exit 1), listens on `127.0.0.1:${port}`, `stdout> QUESTION URL: http://127.0.0.1:${port}/` and `Waiting for the user to choose in the browser (Ctrl-C aborts)...`, opens browser unless `--no-open`; on answer prints via `printAnswer` and exits 0 after 150 ms. Detached mode writes state instead of printing.- **Decision comps** (engine addition, not in the JS): a round's declared comps are the local paths in each option's `comp` (or legacy `sketch`) and `canonCard.comp`, in card order, deduplicated; URLs are left out. The detached server writes them to the state file as `comps` (omitted when empty) and rewrites them when it claims a `--update` round.- **Hands and provenance.** Each served hand's provenance lives in `<key>.hand.json`, `{"id": "<per-hand id>", "digest": "<first 16 hex of sha256 over the compact JSON of the whole payload>", "comps": [<declared comps>], "pre": {"<slot>": "<sha256 hex of the file bytes>"}}`. Only `--start` and `--update` write it, atomically (a temp file beside it, then a rename), and a failed write fails the command: `--start` prints `serve-question: could not record the hand (<file>: <error>); the page was not served. Make .impeccable/questions/ writable and rerun --start.` on stderr and exits 1 before spawning the server or touching the old state; `--update` prints `serve-question: could not record the hand (<file>: <error>); nothing was delivered. Make .impeccable/questions/ writable and rerun --update on the same key.` and exits 1 before copying `<key>.next.json`, so the page keeps the previous round with its hand file intact; the server never does, so its heartbeat and claim rewrites of the state file cannot drop a hand. `--update` always starts a new hand. `--start` keeps the recorded hand when the key's hand file carries the same digest (a restart) and otherwise starts a new one. A new hand fingerprints every declared slot that already holds a file into `pre`. The digest covers the whole payload, not only the slot paths, because a re-roll often reuses the previous hand's paths. `impeccable generate-image`, after writing `--out`, scans `.impeccable/questions/*.hand.json` for a hand that declares that path (resolved against the cwd; compared case-insensitively on Windows) and marks it generated during that hand with a marker file `<key>.generated/<16 hex of sha256 over the JSON string of the slot>-<hand tag>.json` = `{"slot", "hand"}` (the hand's `id`), written atomically. The hand tag is the hand's `id` (a hand file without an `id` uses its `digest`) when that is 1 to 64 characters of `[a-z0-9_]`, else the first 16 hex of sha256 over its JSON string (lowercase only, so ids that differ in case never share a path on a case-insensitive file system). Markers are one file per slot rather than a list inside the hand file because parallel generators (one subagent per card) would race a shared read-modify-write, and the tag in the name keeps one hand's markers off every path another hand writes. A marker counts only while its name carries the hand file's tag, so a re-roll that repeats a payload never inherits the previous hand's markers. Writing a new hand writes the hand file first and only then prunes, deciding from the file name alone: it deletes only markers (and their temp files) tagged with another hand, so a failed write leaves the live hand and its markers intact and a parallel generation's marker for the new hand is never touched, even when it regenerates a reused slot while the prune runs (#886). A legacy untagged marker `<16 hex>.json` (written before names carried the hand) counts, and survives a prune, only while its content's `hand` (else `digest`) matches the hand's `id` (else `digest`); the engine never writes that name again. `--stop` and a closing answer remove `<key>.generated/` with the hand file. A failed marker write prints `generate-image: could not mark <out> as generated for its decision page (<file>: <error>); a --wait may report it stale` on stderr and leaves the exit at 0, since the image itself was written. Readers merge the valid markers into the hand as `generated: [<slot>, ...]`. A declared comp is **this hand's** when its file exists and its slot is in `generated`, has no `pre` entry, or its current bytes hash differently from `pre`; timestamps play no part, so an old file rewritten unchanged in the same second is still not this hand's, while a deterministic generator's identical regeneration still counts through `generated`. Rewriting a comp's prompt sidecar never counts on its own: only new bytes or an engine generation do. Two exceptions: a comp directly in `.impeccable/mocks/` is the comp round's, generated before that round serves, and counts whenever it exists; with no hand file, existence decides. `--wait` judges the hand file's `comps`, else the state's. A declared comp that exists but is not this hand's is **stale**. The page itself still shows whatever file sits at a slot; hiding stale files there is out of scope.- - Three directives follow:+ - Four directives follow:- `NEXT read ${skillDir}/reference/visualize.md now, before writing any decision comp prompt; it and the MODE RULES block concept-seed printed for this surface govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar, the image's full file name plus .json (a.png gets a.png.json).` The path is the provider's skill dir (`IMPECCABLE_SKILL_DIR`, else the one found beside the binary); with neither it reads `reference/visualize.md`. Printed by `--start` between the `Open the URL` line and the `Then collect` line, and by `--update` after `next round delivered`, when `buildPath.value` is not `code` (a code-led round's slots are a flip reserve) and some declared comp is not this hand's yet; and by `--wait` right after `BUILD PATH FLIPPED`, when the state has no `comps` or one of them is not this hand's. The engine cannot see a harness-native image tool, so a slot without this hand's comp is the signal that comps are about to be written. So a fresh decision round (serve first, generate after) gets the line even when an earlier round left files at its slots; a restart of the same hand after its comps landed does not; a re-roll through `--update` that reuses slot paths does, and so does a restart of that re-roll before its comps land; the comp round, whose comps sit directly in `mocks/`, does not.- `COMP SIDECAR MISSING: ${paths joined by ", "} landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in its sidecar, the image's full file name plus .json (a.png gets a.png.json), as {"prompt": "..."} (generate-image writes it itself, a harness image tool does not), and that prompt is written under the comp rules in ${visualize path}. Write each missing sidecar now, and read that file before the next comp prompt if you have not.` Printed by `--wait` as the last line of a WAITING (exit 3) or answered (exit 0) return when a state `comps` path is this hand's comp and has no `<path>.json`. Comps that have not landed, and stale files, are skipped. It is a warning: exit codes and the answer are unchanged, because the user is mid-decision in the browser and blocking `--wait` would strand their answer.- `COMP STALE: files left from an earlier round sit at this hand's slots, and the page is showing them: ${paths joined by ", "}. Regenerate each into its slot now under the comp rules in ${visualize path}, with its prompt sidecar, before the user decides.` Printed by `--wait` as the last line of a WAITING return (after `COMP SIDECAR MISSING` when both apply) when a state `comps` path is stale. Never on an answered return: once the user picks, the image they saw is the one they chose.+ - `NEXT open each decision comp once and run ${visualize path}'s render checks (shipped screen, one dominant move); regenerate any that fail before the user answers.` Printed by `--wait` as the last line of a WAITING return (after `COMP SIDECAR MISSING` and `COMP STALE` when they apply) when at least one state `comps` path outside `.impeccable/mocks/` itself (a decision comp, not a comp-round comp) is this hand's comp and has its `<path>.json` sidecar. Once per hand: the first such return writes the hand's `id` (else its `digest`, else the empty string with no hand file) to `<key>.render-check`, and a later return finds that id there and stays quiet; a new hand carries a new id, so its round prints the line again. A code-led round's slots stay empty or stale until a flip to comp, so it gets no line. Never on an answered return. `--stop` and a closing answer remove `<key>.render-check` with the hand file.- **Payload processing** (`loadRound`): options decorated with `heroSrc`/`boardSrc` (http(s) URL passthrough; local path must exist → `/img/<i>`), `compSrc` (`comp` or legacy `sketch`; local path registered even if missing); `verdict==='declined'` cards moved to the end; `canonCard` appended as `{...card, id:'canon', isCanon:true}` before declined; `buildPath` `{value:'comp'|'code', toggle:bool}`.- **HTTP routes**: `GET /` → HTML page (claims `<key>.next.json` if present, stamps `claimedAt`); `POST /heartbeat` → 204, updates `lastBeat` in state at most every 4 s; `GET /next-status` → `{"ready":bool}`; `GET /img/<n>` → local file stream (content-type by ext: webp/png/svg+xml/gif, else jpeg; 404 if missing); `POST /build-path` `{value}` → `{"ok":true}`, writes `<key>.flip.json` `{"buildPath":"comp"}` on a flip to comp; `POST /answer` `{optionId, steer, register?}` → `{"ok":true}` and answer JSON `{optionId, steer, [register], [followup:true], [hero, board], [comp], [buildPath, buildPathFlipped]}` written to answer file (detached) or printed; process exits 150 ms later unless reroll/followup in detached mode; else 404.- **Page** (server-rendered HTML; `<title>${payload.title || 'impeccable · decision'}</title>`, `<h1>` payload.title or `Choose a direction`): cards with kicker, media (comp with shimmer + polling until `/img/<n>` returns 200; hero/board inspiration; wireframe grid), thesis, palette swatches (≤6), material tags (≤4), raise lines, facts, `Build this` / `Adopt anyway` (declined) / `Play it straight` (canon) buttons; optional `#steer` input (placeholder `Optional steer: what should be different or kept?`), `Re-roll` button with optional safer/bolder register buttons, `#canon` footer button when `canon && !canonCard`, build-path toggle. Client heartbeats every 5000 ms via `navigator.sendBeacon('/heartbeat')`; posts `/answer`; after reroll/followup polls `/next-status` and reloads.diff --git a/skill/reference/visualize.md b/skill/reference/visualize.mdindex 13afa6d6a..458018bb0 100644--- a/skill/reference/visualize.md+++ b/skill/reference/visualize.md@@ -10,7 +10,7 @@ The comp round runs inside the build's phase state: `impeccable build-phase starRender three distinct high-fidelity north-star comps of the requested surface, saved under `.impeccable/mocks/` so they survive the session. Comp at the surface's own viewport: portrait at device size for a native app or mobile-first surface, desktop landscape otherwise; a phone screen comped landscape misstates the composition before anything is built against it. Comps are the build thread's own work, never delegated: the thread that writes the prompts holds the direction's full context and has seen every comp when the build starts. Open every image by its workspace-relative path; sandboxed viewers reject absolute paths, and everything under the project root has a relative one. Base the comps on real content and the surface concepts already developed with the user. On an established world, anchor every comp on the real identity: capture a screenshot of a representative existing page and pass it as a reference image (the harness image tool's input image, or `impeccable generate-image --ref`); the prompt leads with the new surface's structure while the reference carries palette, type, and component character, because DESIGN.md words alone drift where a pixel reference does not. Name what the reference contributes and what it must not: chrome, palette, type, and component character carry over; the reference page's own content does not, and a banner, hero, or card lifted verbatim is the reference leaking, not fidelity. Three is the number: one comp invites rubber-stamping; the spread between three surfaces the composition worth building. The chosen card's decision comp is the first of the three: it already renders this direction at full fidelity under this discipline, so generate two more that vary what the first held fixed, from the direction in words rather than with the first comp as an input image (a reference image anchors the layout, and three comps collapse into one composition). How comps two and three vary from the first is the mode's call, in its COMPS rules. A variant that simplifies the first into a tidier version of itself adds no choice to the round. Send all three to the approval point together. Only a round arriving with no decision comp (a degraded roll, an identity-mode page, a direction pinned without the decision round) renders all three here.-- A comp is a designed surface, not a picture of the subject. Lead the prompt with the surface's own structure: the regions this design has, named in order with their scale relationships; a page with no navigation says so instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. How far the world reaches into the page, and what it may carry, is the mode's call, in its COMPS rules. Render the page itself edge to edge: no browser window, address bar, device or desk around it, so prompt it as the page, never as a screenshot of a browser. Self-check every render: if it could hang as a poster, or reads as a photograph with some text on it, it is not a comp; regenerate with the dealt composition's regions named and its parts working in place.+- A comp is a designed surface, not a picture of the subject. Lead the prompt with the surface's own structure: the regions this design has, named in order with their scale relationships. Write it in the order the visitor reads it: the headline in its own words and the primary action first, then the one focal move in full detail, then each remaining region in a phrase; the image model fills whatever the prompt describes in detail, so a region you inventory renders as a second focal move. A page with no navigation says so instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. How far the world reaches into the page, and what it may carry, is the mode's call, in its COMPS rules. Render the page itself edge to edge: no browser window, address bar, device or desk around it, so prompt it as the page, never as a screenshot of a browser. Self-check every render: if it could hang as a poster, or reads as a photograph with some text on it, it is not a comp; regenerate with the dealt composition's regions named and its parts working in place.- The inverse is also a failure: a surface with none of its subject in it. The subject appears as the content the regions hold; the world dresses the frame and never displaces what the frame shows. The deletion usually rides in on the prompt's exclusion list, so exclusions bind invented claims, and a medium ban belongs to the committed imagery stance, never to caution. Before accepting a render, point at the subject; a render that depicts everything about the world and nothing of the subject fails however faithful its atmosphere. Regenerate with the subject's content named region by region.- Judge a comp as the shipped screen: the visitor's job must be readable from the image alone. Name the surface's mode from the render with no caption; a render whose mode cannot be read back is art direction without a surface. Regenerate with the visitor's job as the prompt's spine.- Commitment is depth, not performance spread across regions. The world enters through one dominant move plus the material, type, and spacing that support it; the remaining regions hold still in that material so the move can be read. A region that simply does its job in the world's grammar carries the direction further than a region performing the concept. The check cuts competition, never content: a quieted region keeps its information and stops performing, and the page still carries its content (a way to navigate, the offer, its supporting copy, an action, a glimpse of what follows) at real reading size (body text near 16px on a 1440px-wide page). That is a list of content, not a layout: where each piece sits is the composition's call. A second element competing with the named focal moment at the same scale means the comp is shouting; with no named focal moment, several regions performing the concept at once is the same shout. Regenerate keeping the strongest move and quieting the rest. Busy is louder, not bolder.diff --git a/tests/oracle/DELTAS.md b/tests/oracle/DELTAS.mdindex 72525cba3..13cc1555b 100644--- a/tests/oracle/DELTAS.md+++ b/tests/oracle/DELTAS.md@@ -368,3 +368,13 @@ Codex-harness runs read new-work.md through a shell that cut the middle of the f- Every seed golden that prints a roll (`seed-direction-local`, `-reroll`, `-reroll-bolder`, `-reroll-safer`, `-unscoped`, `-count-5`, `-operate`, `seed-direction-env-key`, `seed-mode-rules-*`, `seed-surface-local`, `-default-scope`, `-grain-flow`, `-compositions`, `-card-base`, `seed-degraded-direction`, `-surface`, `-safer`, `-bolder`): the block appended after the last line, reviewed by hand. Everything before it is byte-identical; exit status, stderr and files are unchanged. Validation errors, the PRODUCT.md gate and the telemetry pings print no block.New cases, recorded from the binary and reviewed by hand: `seed-presentation-build-path-code` (direction roll with `.impeccable/config.json` `code`: the code-led flip-reserve comp line and `recorded default code (from .impeccable/config.json)`) and `seed-presentation-build-path-local` (surface roll where `config.local.json` `code` beats `config.json` `comp`: the code-led wireframe line and `(from .impeccable/config.local.json)`).++## Recorded 2026-10-05: decision comps get their render checks once per round++A Gemini run wrote decision comp prompts that inventoried every region and never opened the rendered comps, so visualize.md's post-render checks never ran. `serve-question --wait` now prints `NEXT open each decision comp once and run ${visualize path}'s render checks (shipped screen, one dominant move); regenerate any that fail before the user answers.` as the last line of a WAITING return, once per hand, when a decision comp of this hand has landed with its sidecar. It records the hand's id in `<key>.render-check` so later polls of the same hand stay quiet.++- `question-wait-comp-sidecar-missing`: b landed with its sidecar, so the new NEXT line follows `COMP SIDECAR MISSING`, and the files now include `.impeccable/questions/k1.render-check` with the empty id (the case has no hand file). Exit status and stderr are unchanged.++New case, recorded from the binary and reviewed by hand:++- `question-wait-render-check-once`: `k1.render-check` already holds the hand's id `h1`, so a poll with a landed, sidecar-carrying decision comp prints only the WAITING line and leaves the marker as it was.diff --git a/tests/oracle/cases/context.mjs b/tests/oracle/cases/context.mjsindex c3e8c98de..716306c45 100644--- a/tests/oracle/cases/context.mjs+++ b/tests/oracle/cases/context.mjs@@ -732,6 +732,8 @@ const cases = [{ id: 'question-wait-answer-comp-sidecar-missing', verb: 'serve-question', workspace: 'ctx-empty', setup: (ws) => { write(ws, '.impeccable/questions/k1.state.json', JSON.stringify({ pid: 1, port: 1, url: 'http://127.0.0.1:1/', comps: ['.impeccable/mocks/decision/a.png', '.impeccable/mocks/decision/b.png'] })); write(ws, '.impeccable/mocks/decision/a.png', 'png'); write(ws, '.impeccable/mocks/decision/b.png', 'png'); write(ws, '.impeccable/questions/k1.answer.json', JSON.stringify({ optionId: 'a', steer: '', comp: '.impeccable/mocks/decision/a.png', buildPath: 'comp', buildPathFlipped: false })); }, args: ['--wait', '--key', 'k1', '--poll', '2'], env: env(), files: ['.impeccable/questions/**'] },// Provenance: a declared comp counts for the hand only when its bytes differ from the file that sat at the slot when the hand began (the hand file's `pre` fingerprints). a is still those bytes (sha256 of "png"), so it is named COMP STALE, not a missing sidecar; b never landed.{ id: 'question-wait-comp-stale', verb: 'serve-question', workspace: 'ctx-empty', setup: (ws) => { write(ws, '.impeccable/questions/k1.state.json', JSON.stringify({ pid: 1, port: 1, url: 'http://127.0.0.1:1/', comps: ['.impeccable/mocks/decision/a.png', '.impeccable/mocks/decision/b.png'] })); write(ws, '.impeccable/questions/k1.hand.json', JSON.stringify({ digest: '0000000000000000', comps: ['.impeccable/mocks/decision/a.png', '.impeccable/mocks/decision/b.png'], pre: { '.impeccable/mocks/decision/a.png': '8f8cbb7dcf46e0bc7d53265749a6c17d116093a6ba95e442764060c76fd4a86c' } })); write(ws, '.impeccable/mocks/decision/a.png', 'png'); }, args: ['--wait', '--key', 'k1', '--poll', '0'], env: env(), files: ['.impeccable/questions/**'] },+ // The render-check NEXT line prints once per hand: k1.render-check already holds this hand's id, so a later poll with a landed, sidecar-carrying decision comp stays quiet.+ { id: 'question-wait-render-check-once', verb: 'serve-question', workspace: 'ctx-empty', setup: (ws) => { write(ws, '.impeccable/questions/k1.state.json', JSON.stringify({ pid: 1, port: 1, url: 'http://127.0.0.1:1/', comps: ['.impeccable/mocks/decision/a.png'] })); write(ws, '.impeccable/questions/k1.hand.json', JSON.stringify({ id: 'h1', digest: '0000000000000000', comps: ['.impeccable/mocks/decision/a.png'], pre: {} })); write(ws, '.impeccable/questions/k1.render-check', 'h1'); write(ws, '.impeccable/mocks/decision/a.png', 'png'); write(ws, '.impeccable/mocks/decision/a.png.json', JSON.stringify({ prompt: 'a' })); }, args: ['--wait', '--key', 'k1', '--poll', '0'], env: env(), files: ['.impeccable/questions/**'] },// --update with a round that declares comps prints the NEXT visualize.md line; a code-led round (comp slots as flip reserve) does not.{ id: 'question-update-comps-next', verb: 'serve-question', workspace: 'ctx-empty', setup: (ws) => { write(ws, '.impeccable/questions/k1.state.json', JSON.stringify({ pid: 1, port: 1, url: 'http://127.0.0.1:1/' })); write(ws, 'payload.json', JSON.stringify({ title: 'Pick', options: [{ id: 'a', label: 'A', thesis: 'One.', comp: '.impeccable/mocks/decision/a.png' }, { id: 'b', label: 'B', thesis: 'Two.', comp: '.impeccable/mocks/decision/b.png' }], buildPath: { value: 'comp', toggle: true } })); }, args: ['--update', '--key', 'k1', '--payload', 'payload.json'], env: env(), files: ['.impeccable/questions/*.hand.json'],// The per-hand id mixes the clock and the pid, so it is masked.diff --git a/tests/oracle/golden/question-wait-comp-sidecar-missing.json b/tests/oracle/golden/question-wait-comp-sidecar-missing.jsonindex 020de65ac..582c782d1 100644--- a/tests/oracle/golden/question-wait-comp-sidecar-missing.json+++ b/tests/oracle/golden/question-wait-comp-sidecar-missing.json@@ -1,9 +1,10 @@{- "stdout": "WAITING: no answer yet after 0s; run --wait --key k1 again\nCOMP SIDECAR MISSING: .impeccable/mocks/decision/a.png landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in its sidecar, the image's full file name plus .json (a.png gets a.png.json), as {\"prompt\": \"...\"} (generate-image writes it itself, a harness image tool does not), and that prompt is written under the comp rules in <REPO>/skill/reference/visualize.md. Write each missing sidecar now, and read that file before the next comp prompt if you have not.\n",+ "stdout": "WAITING: no answer yet after 0s; run --wait --key k1 again\nCOMP SIDECAR MISSING: .impeccable/mocks/decision/a.png landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in its sidecar, the image's full file name plus .json (a.png gets a.png.json), as {\"prompt\": \"...\"} (generate-image writes it itself, a harness image tool does not), and that prompt is written under the comp rules in <REPO>/skill/reference/visualize.md. Write each missing sidecar now, and read that file before the next comp prompt if you have not.\nNEXT open each decision comp once and run <REPO>/skill/reference/visualize.md's render checks (shipped screen, one dominant move); regenerate any that fail before the user answers.\n","stderr": "","exit": 3,"signal": null,"files": {+ ".impeccable/questions/k1.render-check": "",".impeccable/questions/k1.state.json": "{\"pid\":<PID>,\"port\":1,\"url\":\"http://127.0.0.1:1/\",\"comps\":[\".impeccable/mocks/decision/a.png\",\".impeccable/mocks/decision/b.png\",\".impeccable/mocks/decision/c.png\"]}"}}diff --git a/tests/oracle/golden/question-wait-render-check-once.json b/tests/oracle/golden/question-wait-render-check-once.jsonnew file mode 100644index 000000000..da5783a08--- /dev/null+++ b/tests/oracle/golden/question-wait-render-check-once.json@@ -0,0 +1,11 @@+{+ "stdout": "WAITING: no answer yet after 0s; run --wait --key k1 again\n",+ "stderr": "",+ "exit": 3,+ "signal": null,+ "files": {+ ".impeccable/questions/k1.hand.json": "{\"id\":\"h1\",\"digest\":\"0000000000000000\",\"comps\":[\".impeccable/mocks/decision/a.png\"],\"pre\":{}}",+ ".impeccable/questions/k1.render-check": "h1",+ ".impeccable/questions/k1.state.json": "{\"pid\":<PID>,\"port\":1,\"url\":\"http://127.0.0.1:1/\",\"comps\":[\".impeccable/mocks/decision/a.png\"]}"+ }+}