Skip to content

The design language that makes your AI harness better at design.

JavaScript

Tag generated markers with their hand so the prune cannot race generate-image (#890)

Paul Bakauseda1daebb571
diff --git a/crates/context/src/serve_question.rs b/crates/context/src/serve_question.rs
index 0b905c4d6..3403b270d 100644
--- a/crates/context/src/serve_question.rs
+++ b/crates/context/src/serve_question.rs
@@ -107,7 +107,7 @@ fn print_answer(io: &mut Io, raw: &str) {
io.out("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.\n");
}
if truthy("comp") && is_comp_round_comp(&a.get("comp").map(js_str).unwrap_or_default()) {
- io.out("APPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set \"approved\": true in its prompt sidecar (<comp>.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.\n");
+ io.out("APPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set \"approved\": true in its prompt sidecar, the image's full file name plus .json (a.png gets a.png.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.\n");
} else if truthy("comp") {
io.out("CHOSEN COMP: the decision comp at that path is compositional option one. On a comp-led build the comp round adds two variations beside it; on a code-led build it returns at the finish review as the critique reference. Never regenerate it from scratch.\n");
}
@@ -188,23 +188,69 @@ fn file_fingerprint(abs: &str) -> Option<String> {
}
/// `<key>.generated/`: one marker per slot `impeccable generate-image` wrote
-/// during the hand, `<sha16 of slot>.json` = `{"slot", "digest"}`. A marker
-/// 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.
+/// during the hand, `<sha16 of slot>-<hand tag>.json` = `{"slot", "hand"}`.
+/// A marker 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. The hand tag in the name keeps one hand's markers off
+/// every path another hand writes, so pruning decides from the name alone.
fn generated_dir(qdir: &str, key: &str) -> String {
jsp::join(&[qdir, &format!("{}.generated", key)])
}
+/// The hand id as it appears in a marker file name: the id itself when it is
+/// a short run of `[a-z0-9_]` (every id and digest this engine writes), else
+/// its hash, so a hand-edited id can never smuggle a separator or a dot, and
+/// two ids that differ only in case never share a path on a case-insensitive
+/// file system (Windows, default macOS).
+fn marker_tag(id: &str) -> String {
+ if !id.is_empty() && id.len() <= 64 && id.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_') {
+ id.to_string()
+ } else {
+ hand_digest(&Value::String(id.to_string()))
+ }
+}
+
+/// The marker file name for `slot` in the hand tagged `tag`.
+fn marker_name(slot: &str, tag: &str) -> String {
+ format!("{}-{}.json", hand_digest(&Value::String(slot.to_string())), tag)
+}
+
+/// The hand tag a marker file name carries: `Some(tag)` for
+/// `<16 hex>-<tag>.json` (or its `.json.tmp-<pid>` temp file), `None` for a
+/// legacy `<16 hex>.json` name, whose owner lives only in its content.
+fn marker_name_tag(name: &str) -> Option<&str> {
+ let stem = &name[..name.find(".json")?];
+ let (slot, tag) = (stem.get(..16)?, stem.get(16..)?);
+ let tag = tag.strip_prefix('-')?;
+ (slot.bytes().all(|b| b.is_ascii_hexdigit()) && !tag.is_empty()).then_some(tag)
+}
+
+/// The owner a legacy marker's content names (`hand`, else `digest`).
+fn legacy_marker_owner(path: &std::path::Path) -> Option<String> {
+ safe_read(&path.to_string_lossy())
+ .and_then(|t| serde_json::from_str::<Value>(&t).ok())
+ .and_then(|m| m.get("hand").or_else(|| m.get("digest")).and_then(Value::as_str).map(str::to_string))
+}
+
/// The recorded hand, with the slots generated during it merged in as
/// `generated` (markers from another digest are ignored).
fn read_hand(qdir: &str, key: &str) -> Option<Map<String, Value>> {
let mut hand = safe_read(&hand_file(qdir, key)).and_then(|t| serde_json::from_str::<Value>(&t).ok()).and_then(|v| v.as_object().cloned())?;
let id = hand_marker_id(&hand);
+ let tag = marker_tag(&id);
let mut generated: Vec<String> = Vec::new();
if let Ok(entries) = std::fs::read_dir(generated_dir(qdir, key)) {
for e in entries.flatten() {
+ let name = e.file_name().to_string_lossy().into_owned();
+ if !name.ends_with(".json") {
+ continue;
+ }
let Some(m) = safe_read(&e.path().to_string_lossy()).and_then(|t| serde_json::from_str::<Value>(&t).ok()) else { continue };
- if m.get("hand").or_else(|| m.get("digest")).and_then(Value::as_str) == Some(id.as_str()) {
+ let ours = match marker_name_tag(&name) {
+ Some(t) => t == tag,
+ None => m.get("hand").or_else(|| m.get("digest")).and_then(Value::as_str) == Some(id.as_str()),
+ };
+ if ours {
if let Some(slot) = m.get("slot").and_then(Value::as_str) {
generated.push(slot.to_string());
}
@@ -212,6 +258,7 @@ fn read_hand(qdir: &str, key: &str) -> Option<Map<String, Value>> {
}
}
generated.sort();
+ generated.dedup();
if !generated.is_empty() {
hand.insert("generated".into(), json!(generated));
}
@@ -259,7 +306,7 @@ pub fn record_generated(cwd: &str, out: &str) -> Result<Vec<String>, String> {
continue;
}
let dir = generated_dir(&qdir, &key);
- let marker = jsp::join(&[&dir, &format!("{}.json", hand_digest(&Value::String(slot.clone())))]);
+ let marker = jsp::join(&[&dir, &marker_name(&slot, &marker_tag(&id))]);
std::fs::create_dir_all(&dir)
.and_then(|_| write_atomic(&marker, &json_compact(&json!({ "slot": slot, "hand": id }))))
.map_err(|e| format!("{}: {}", marker, e))?;
@@ -293,19 +340,25 @@ fn new_hand(cwd: &str, payload: &Value) -> Map<String, Value> {
/// Records a new hand atomically (temp file then rename, so a reader never
/// sees half a hand), then prunes generated markers that belong to another
/// hand. Pruning waits for a successful write, so a failed write leaves the
-/// live hand and its markers intact, and it spares this hand's own markers,
-/// which a parallel generate-image may already have written. The error names
-/// the file.
+/// live hand and its markers intact. It decides from the file name alone and
+/// deletes only names tagged with another hand, so it never touches a path a
+/// parallel generate-image for this hand may be writing. A legacy untagged
+/// marker (written before names carried the hand) is judged by its content;
+/// this engine never writes that name again, so no new marker can land there.
+/// The error names the file.
fn write_hand(qdir: &str, key: &str, hand: &Map<String, Value>) -> Result<(), String> {
let target = hand_file(qdir, key);
write_atomic(&target, &json_compact(&Value::Object(hand.clone()))).map_err(|e| format!("{}: {}", target, e))?;
let id = hand_marker_id(hand);
+ let tag = marker_tag(&id);
if let Ok(entries) = std::fs::read_dir(generated_dir(qdir, key)) {
for e in entries.flatten() {
- let owner = safe_read(&e.path().to_string_lossy())
- .and_then(|t| serde_json::from_str::<Value>(&t).ok())
- .and_then(|m| m.get("hand").or_else(|| m.get("digest")).and_then(Value::as_str).map(str::to_string));
- if owner.as_deref() != Some(id.as_str()) {
+ let name = e.file_name().to_string_lossy().into_owned();
+ let prune = match marker_name_tag(&name) {
+ Some(t) => t != tag,
+ None => legacy_marker_owner(&e.path()).as_deref() != Some(id.as_str()),
+ };
+ if prune {
let _ = std::fs::remove_file(e.path());
}
}
@@ -391,12 +444,12 @@ fn visualize_ref(env: &Env, cwd: &str) -> String {
/// the decision round's comps are about to be written.
fn visualize_next_line(env: &Env, cwd: &str) -> String {
format!(
- "NEXT read {} now, before writing any decision comp prompt; its comp rules govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar (<comp>.json).\n",
+ "NEXT read {} now, before writing any decision comp prompt; its comp rules 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).\n",
visualize_ref(env, cwd)
)
}
-/// This hand's landed comps without a `<comp>.json` prompt sidecar.
+/// This hand's landed comps without a prompt sidecar (`a.png` -> `a.png.json`).
fn comps_missing_sidecar(cwd: &str, comps: &[String], hand: Option<&Map<String, Value>>) -> Vec<String> {
comps
.iter()
@@ -417,7 +470,7 @@ fn stale_comps_line(env: &Env, cwd: &str, stale: &[String]) -> String {
/// The `--wait` backstop: names every landed decision comp with no sidecar.
fn sidecar_missing_line(env: &Env, cwd: &str, missing: &[String]) -> String {
format!(
- "COMP SIDECAR MISSING: {} landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in <comp>.json ({{\"prompt\": \"...\"}}; generate-image writes it itself, a harness image tool does not), and that prompt is written under the comp rules in {}. Write each missing sidecar now, and read that file before the next comp prompt if you have not.\n",
+ "COMP SIDECAR MISSING: {} 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 {}. Write each missing sidecar now, and read that file before the next comp prompt if you have not.\n",
missing.join(", "),
visualize_ref(env, cwd)
)
@@ -1931,6 +1984,105 @@ mod tests {
let _ = std::fs::remove_dir_all(&dir);
}
+ #[test]
+ fn marker_names_carry_the_hand_tag() {
+ let slot = ".impeccable/mocks/decision/a.png";
+ let name = marker_name(slot, "abc123");
+ assert_eq!(name, format!("{}-abc123.json", hand_digest(&Value::String(slot.into()))));
+ assert_eq!(marker_name_tag(&name), Some("abc123"));
+ assert_eq!(marker_name_tag(&format!("{}.tmp-42", name)), Some("abc123"));
+ // A legacy name carries no tag; neither does a stray file.
+ assert_eq!(marker_name_tag(&format!("{}.json", hand_digest(&Value::String(slot.into())))), None);
+ assert_eq!(marker_name_tag("notes.txt"), None);
+ assert_eq!(marker_name_tag("zzzzzzzzzzzzzzzz-abc.json"), None);
+ // An id that could not sit in a file name safely is hashed.
+ assert_eq!(marker_tag("0123456789abcdef"), "0123456789abcdef");
+ let odd = marker_tag("..\\x/y.json");
+ assert_eq!(odd.len(), 16);
+ assert!(odd.bytes().all(|b| b.is_ascii_hexdigit()));
+ assert_eq!(marker_tag(""), hand_digest(&Value::String(String::new())));
+ // Ids that differ only in case get distinct, all-lowercase tags, so
+ // they never share a path on a case-insensitive file system.
+ let (lower, upper) = (marker_tag("abc"), marker_tag("ABC"));
+ assert_eq!(lower, "abc");
+ assert_ne!(lower.to_lowercase(), upper.to_lowercase());
+ assert_eq!(upper, upper.to_lowercase());
+ }
+
+ // Issue #886: the prune used to read a marker's owner and then delete the
+ // file, so a parallel generate-image for the new hand that replaced a
+ // reused slot's marker between the read and the delete lost its marker.
+ // Markers now carry the hand in their name: the new hand writes a path the
+ // old hand never used, and the prune decides from names alone.
+ #[test]
+ fn prune_spares_a_parallel_marker_for_the_new_hand_in_a_reused_slot() {
+ let dir = temp_project("marker-race");
+ let cwd = dir.to_string_lossy().into_owned();
+ let qdir = jsp::join(&[&cwd, ".impeccable", "questions"]);
+ let slot = ".impeccable/mocks/decision/a.png";
+ let payload = json!({ "options": [{ "id": "a", "comp": slot }] });
+ std::fs::create_dir_all(dir.join(".impeccable/mocks/decision")).unwrap();
+ std::fs::write(dir.join(slot), b"png").unwrap();
+
+ // The old hand generated into the slot.
+ let old = new_hand(&cwd, &payload);
+ write_hand(&qdir, "k1", &old).unwrap();
+ record_generated(&cwd, slot).unwrap();
+ let old_marker = jsp::join(&[&generated_dir(&qdir, "k1"), &marker_name(slot, &marker_tag(&hand_marker_id(&old)))]);
+ assert!(std::path::Path::new(&old_marker).exists());
+
+ // --update: the new hand file lands, then (before its prune runs) a
+ // parallel generate-image regenerates the reused slot for it.
+ let mut new = new_hand(&cwd, &payload);
+ new.insert("id".into(), json!("feedfacecafebeef"));
+ let target = hand_file(&qdir, "k1");
+ write_atomic(&target, &json_compact(&Value::Object(new.clone()))).unwrap();
+ assert_eq!(record_generated(&cwd, slot).unwrap(), vec!["k1".to_string()]);
+ let new_marker = jsp::join(&[&generated_dir(&qdir, "k1"), &marker_name(slot, "feedfacecafebeef")]);
+ assert!(!same_path(&old_marker, &new_marker), "one hand's marker must never share a path with another's");
+ // The old hand's marker is still there when the prune starts.
+ assert!(std::path::Path::new(&old_marker).exists());
+
+ // The prune half of write_hand: it removes the old hand's marker and
+ // keeps the new one.
+ write_hand(&qdir, "k1", &new).unwrap();
+ assert!(!std::path::Path::new(&old_marker).exists());
+ assert!(std::path::Path::new(&new_marker).exists());
+ assert_eq!(read_hand(&qdir, "k1").unwrap().get("generated"), Some(&json!([slot])));
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn legacy_untagged_markers_are_judged_by_content() {
+ let dir = temp_project("marker-legacy");
+ let cwd = dir.to_string_lossy().into_owned();
+ let qdir = jsp::join(&[&cwd, ".impeccable", "questions"]);
+ let (a, b) = (".impeccable/mocks/decision/a.png", ".impeccable/mocks/decision/b.png");
+ let mut hand = new_hand(&cwd, &json!({ "options": [{ "id": "a", "comp": a }, { "id": "b", "comp": b }] }));
+ hand.insert("id".into(), json!("0011223344556677"));
+ write_hand(&qdir, "k1", &hand).unwrap();
+ let gdir = generated_dir(&qdir, "k1");
+ std::fs::create_dir_all(&gdir).unwrap();
+ let legacy = |slot: &str| jsp::join(&[&gdir, &format!("{}.json", hand_digest(&Value::String(slot.into())))]);
+ std::fs::write(legacy(a), json!({ "slot": a, "hand": "0011223344556677" }).to_string()).unwrap();
+ std::fs::write(legacy(b), json!({ "slot": b, "hand": "ffffffffffffffff" }).to_string()).unwrap();
+ // The legacy marker whose content names this hand counts; the other does not.
+ assert_eq!(read_hand(&qdir, "k1").unwrap().get("generated"), Some(&json!([a])));
+ // Rewriting the same hand keeps its legacy marker and prunes the other's.
+ write_hand(&qdir, "k1", &hand).unwrap();
+ assert!(std::path::Path::new(&legacy(a)).exists());
+ assert!(!std::path::Path::new(&legacy(b)).exists());
+ // A legacy hand file (no id) matches legacy markers on its digest.
+ let mut old = hand.clone();
+ old.remove("id");
+ let digest = old.get("digest").and_then(Value::as_str).unwrap().to_string();
+ write_hand(&qdir, "k1", &old).unwrap();
+ assert!(!std::path::Path::new(&legacy(a)).exists());
+ std::fs::write(legacy(b), json!({ "slot": b, "digest": digest }).to_string()).unwrap();
+ assert_eq!(read_hand(&qdir, "k1").unwrap().get("generated"), Some(&json!([b])));
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+
#[test]
fn comp_round_comps_sit_directly_in_mocks() {
assert!(is_comp_round_comp(".impeccable/mocks/comp-b-open-book.png"));
@@ -1965,7 +2117,7 @@ mod tests {
let env = Env::from([("IMPECCABLE_SKILL_DIR".into(), "/skill".into())]);
let line = visualize_next_line(&env, "/proj").replace('\\', "/");
assert!(line.starts_with("NEXT read /skill/reference/visualize.md now, before writing any decision comp prompt;"), "{line}");
- assert!(line.ends_with("(<comp>.json).\n"));
+ assert!(line.ends_with("the image's full file name plus .json (a.png gets a.png.json).\n"));
}
#[test]
diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.md
index 58b319528..d26bec646 100644
--- a/docs/CLI-CONTRACT.md
+++ b/docs/CLI-CONTRACT.md
@@ -430,15 +430,15 @@ retain their local-development trust behavior. See [bundle signing](BUNDLE-SIGNI
- `--start --payload F [--key K] [--open] [--timeout] [--idle-grace]`: validates JSON, decides the hand and writes `<key>.hand.json` when it is new (**Decision comps**), removes the key's previous state file without signalling its pid, spawns detached child `node serve-question.mjs --payload F --detached-serve --key K --timeout T [--idle-grace G] [--no-open unless --open]` with stdio to `<key>.log`; waits ≤8 s for state file; failure → stderr `serve-question: server failed to start` + last 4 log lines + `serve-question: log at <rel>. A sandboxed exec that cannot listen on localhost causes exactly this; rerun this command once through the harness's network-enabled or unsandboxed command tool before falling back.` exit 1; success stdout: `QUESTION URL: ${url}`, `QUESTION KEY: ${key}`, `Open the URL for the user now: in-app browser when the harness has one, otherwise the system opener (macOS \`open\`, Linux \`xdg-open\`), otherwise show the URL.`, the `NEXT` visualize line when the payload's comps are due (**Decision comps**), `Then collect the answer with: node <abs script> --wait --key ${key}`; exit 0. Key default `Math.random().toString(16).slice(2,10)`.
- 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>.json` = `{"slot", "hand"}` (the hand's `id`), written atomically. 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. A marker counts only while its `hand` matches the hand file's `id` (a hand file without an `id` matches on `digest`), 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 markers that belong to another hand, so a failed write leaves the live hand and its markers intact and a parallel generation's marker for the new hand survives. `--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.
+ - **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:
- - `NEXT read ${skillDir}/reference/visualize.md now, before writing any decision comp prompt; its comp rules govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar (<comp>.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 <comp>.json ({"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.
+ - `NEXT read ${skillDir}/reference/visualize.md now, before writing any decision comp prompt; its comp rules 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.
- **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.
-- **printAnswer**: `ANSWER: ${raw}` then conditional directive lines `CHOSEN CARD: ...`, `CHOSEN COMP: ...` (or, engine addition, `APPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set "approved": true in its prompt sidecar (<comp>.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.` in its place when the answer's `comp` sits directly in `.impeccable/mocks/`, where the comp round writes; decision comps under `.impeccable/mocks/decision/` and any other path keep `CHOSEN COMP`), `CANON CHOSEN: ...`, `REGISTER: ...`, `FOLLOWUP OPEN: ...`, `BUILD PATH: ${value} (${origin}). ...` (verbatim in source lines 152-190).
+- **printAnswer**: `ANSWER: ${raw}` then conditional directive lines `CHOSEN CARD: ...`, `CHOSEN COMP: ...` (or, engine addition, `APPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set "approved": true in its prompt sidecar, the image's full file name plus .json (a.png gets a.png.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.` in its place when the answer's `comp` sits directly in `.impeccable/mocks/`, where the comp round writes; decision comps under `.impeccable/mocks/decision/` and any other path keep `CHOSEN COMP`), `CANON CHOSEN: ...`, `REGISTER: ...`, `FOLLOWUP OPEN: ...`, `BUILD PATH: ${value} (${origin}). ...` (verbatim in source lines 152-190).
- **Lifetime**: no page ever beat → exit 2 `serve-question: timed out with no answer` after `--timeout` (unless 0); after beats, silence > idle-grace (with 10 s claim window for a delivered next hand) → exit 2 `serve-question: the page stopped beating and never came back; exiting`.
- **Browser opener** (`lib/open-system-browser.mjs`): darwin `open <url>`; win32 `${ComSpec||COMSPEC||'cmd.exe'} /c start "" <url>`; else `xdg-open <url>`; spawned `detached, stdio:'ignore'`, `unref`, errors swallowed; returns true/false.
- Tests: `tests/serve-question.test.mjs` (opener commands, blocking answer, reroll, start/wait cycle, headless gating, empty payload, heartbeat/timeouts, refresh semantics, --update, comps streaming), `tests/new-work-e2e.test.mjs`.
diff --git a/skill/reference/new-work.md b/skill/reference/new-work.md
index c11977550..e5a847d0f 100644
--- a/skill/reference/new-work.md
+++ b/skill/reference/new-work.md
@@ -50,7 +50,7 @@ The script deals three of your structures; the dice pick which three reach the u
The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it (the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path), convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. Record a standing preference as a brand commitment in PRODUCT.md. <!-- rule:skill-canon-standing-exit --> Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. Re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Resolve collisions field by field: preserve every user- or brief-pinned constraint. In dimensions the brief leaves open, the assignment still binds through its topology, controls, state vocabulary, and ritual; when only its materials conflict with a pinned visual direction or PRODUCT.md brand commitment, translate that material expression and name the translation in the presented direction. A look mismatch is not grounds to re-roll. <!-- rule:skill-assigned-plus-reroll --> Present the decision visually: write an options payload with the assigned direction leading, its raised lines included; the pick card when one exists; the dealt challengers as alternates with their QUALITY BAR cards, verdicts, and kept lines; re-roll with its safer and bolder registers; steer; canon enabled; and `buildPath` carrying the recorded default with `toggle: true` whenever image generation exists (details in the build-path paragraph below). A degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Give every card the same anatomy: thesis, palette, materials, first viewport, honest risk, and the challengers' case lines (`--schema` prints the exact shape); the page renders identity from these fields, demotes declined challengers to their row on its own, and a challenger's catalog image rides as labeled inspiration, never the promise of the build. Author `canonCard` too: the category standard as one honest card, same anatomy; the page keeps it subordinate, and the counterweights still bind you. Run `{{scripts_path}}/impeccable serve-question --start --payload <file>` (`--schema` first for the payload shape). It daemonizes, prints the page URL and a key, and exits; open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. An ANSWER of `{"optionId":"reroll"}` keeps the server alive and the page open on a loading hand: rerun concept-seed with the same `--scope` and `--mode` plus `--from <seed-key> --reroll <n>` (1 on the first re-roll, counting up), build the next payload, deliver it with `--update --key <same key> --payload <file>`, then return to `--wait` on that key. Never `--start` a second server or fall back to chat here: either strands the open tab on a hand that never arrives. Exit 4 means the page closed unanswered: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may run the script without `--start` and let it auto-open and block. Never predict the fallback: run the script, and only exit code 2 from starting it routes the decision to the structured tool; that exit is the fallback, never an error to retry. <!-- rule:skill-visual-decision-page -->
-When image generation exists, every card also declares a `comp` path under `.impeccable/mocks/decision/`, the canon card included. Where the harness sandboxes its shell, start the page through the least-sandboxed command path it offers: a sandboxed shell cannot bind the board's port, and the first-attempt failure costs a retry every session. Serve the page first, then produce the comps; the page shimmer-waits per slot and the user may answer before they land. Load [visualize.md](visualize.md) before writing the first decision comp prompt, not at the comp round: each card's image is that direction's north-star comp at full fidelity under its comp discipline, and a prompt written before reading it misses every rule there: the requested surface as the real page, its first viewport and the start of the section below it, held like every comp to visualize.md's rule that a template skeleton stays the template whatever world paints it (your own pick included: a safe layout under a world skin is the template), structure-led prompt, real product name and real content, no invented commercial claims, in that card's own palette, type character, and material world, committed all the way. Once a round declares comps it has not generated yet, `impeccable serve-question --start` (and `--update`, and a flip to comp) prints a `NEXT read <path>/visualize.md` line; read that file then, before the first prompt. `--wait` prints `COMP SIDECAR MISSING` for any landed decision comp with no prompt sidecar; write the missing sidecar before you continue. `COMP STALE` names a file an earlier round left at one of this hand's slots; regenerate it there. Generation takes the same time at any fidelity, so an unfinished draft pays comp cost for draft quality; fairness between cards is equal fidelity in each card's own grammar, one surface, one aspect, never shared unfinishedness. The frame's aspect is the surface's own: portrait at device viewport for a native app or mobile-first surface, landscape for desktop web; the decision page adapts to either, and a phone screen comped landscape is a broken frame, not a neutral default. Produce in reading order, the assigned card, then the pick, then the full-card hand, then canon, each file written with its prompt sidecar the moment it is done, so a re-roll's spend front-loads onto the cards read first; declined challengers get no comp, their catalog thumb is their face. With parallel subagents, fan out one agent per card: each spawn is the shipped asset producer with a single-comp packet, that card's fields, PRODUCT.md, the shared frame, the path to visualize.md for its comp discipline, and the card's declared path, up to four in flight. Regenerate inline any slot still empty when its agent returns; drop without ceremony any slot still empty when the user answers. No other supervision is owed. Without parallel subagents, generate in the main thread after serving, same order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. The chosen card's comp is not spent by the choice: comp-led, it enters the comp round as compositional option one; code-led, it returns at the finish review as the critique reference, what the image dared that the build did not. Unchosen comps stay in `.impeccable/mocks/decision/` as the round's spent hand; they carry no approval and imply none. With no image generation, cards carry their identity in palette chips and facts, and that page is complete, not a lesser version; the page then also demotes every challenger's catalog art to a labeled thumbnail on its own, because salience must encode the verdict, never the accident of which cards have images. <!-- rule:skill-decision-comps-full-fidelity --> <!-- rule:skill-salience-parity -->
+When image generation exists, every card also declares a `comp` path under `.impeccable/mocks/decision/`, the canon card included. Where the harness sandboxes its shell, start the page through the least-sandboxed command path it offers: a sandboxed shell cannot bind the board's port, and the first-attempt failure costs a retry every session. Serve the page first, then produce the comps; the page shimmer-waits per slot and the user may answer before they land. Load [visualize.md](visualize.md) before writing the first decision comp prompt, not at the comp round: each card's image is that direction's north-star comp at full fidelity under its comp discipline, and a prompt written before reading it misses every rule there: the requested surface as the real page, its first viewport and the start of the section below it, held like every comp to visualize.md's rule that a template skeleton stays the template whatever world paints it (your own pick included: a safe layout under a world skin is the template), structure-led prompt, real product name and real content, no invented commercial claims, in that card's own palette, type character, and material world, committed all the way. Once a round declares comps it has not generated yet, `impeccable serve-question --start` (and `--update`, and a flip to comp) prints a `NEXT read <path>/visualize.md` line; read that file then, before the first prompt. `--wait` prints `COMP SIDECAR MISSING` for any landed decision comp with no prompt sidecar (the image's full file name plus `.json`: `a.png` gets `a.png.json`); write the missing sidecar before you continue. `COMP STALE` names a file an earlier round left at one of this hand's slots; regenerate it there. Generation takes the same time at any fidelity, so an unfinished draft pays comp cost for draft quality; fairness between cards is equal fidelity in each card's own grammar, one surface, one aspect, never shared unfinishedness. The frame's aspect is the surface's own: portrait at device viewport for a native app or mobile-first surface, landscape for desktop web; the decision page adapts to either, and a phone screen comped landscape is a broken frame, not a neutral default. Produce in reading order, the assigned card, then the pick, then the full-card hand, then canon, each file written with its prompt sidecar the moment it is done, so a re-roll's spend front-loads onto the cards read first; declined challengers get no comp, their catalog thumb is their face. With parallel subagents, fan out one agent per card: each spawn is the shipped asset producer with a single-comp packet, that card's fields, PRODUCT.md, the shared frame, the path to visualize.md for its comp discipline, and the card's declared path, up to four in flight. Regenerate inline any slot still empty when its agent returns; drop without ceremony any slot still empty when the user answers. No other supervision is owed. Without parallel subagents, generate in the main thread after serving, same order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. The chosen card's comp is not spent by the choice: comp-led, it enters the comp round as compositional option one; code-led, it returns at the finish review as the critique reference, what the image dared that the build did not. Unchosen comps stay in `.impeccable/mocks/decision/` as the round's spent hand; they carry no approval and imply none. With no image generation, cards carry their identity in palette chips and facts, and that page is complete, not a lesser version; the page then also demotes every challenger's catalog art to a labeled thumbnail on its own, because salience must encode the verdict, never the accident of which cards have images. <!-- rule:skill-decision-comps-full-fidelity --> <!-- rule:skill-salience-parity -->
The execution contract, comp-led or code-led, is a workflow preference, not a per-surface decision; no round asks it. The recorded default rides every round and the page's toggle handles the exception. Read the default from `.impeccable/config.json` (`buildPath`), the gitignored `.impeccable/config.local.json` winning where one machine differs from the team's committed value; with neither, comp-led is the default whenever image generation exists. Author every direction and surface payload with `buildPath: { "value": <default>, "toggle": true }`; the page renders a footer toggle with the trade stated beside it, and the ANSWER returns `buildPath` plus `buildPathFlipped`. A flipped value binds that session only and is never written back, with one exception, the only question this preference ever earns inside a round (init records it up front on projects that get the chance): when `buildPathFlipped` comes back true on a project that records no `buildPath` at all, ask once after the round closes whether to keep it as the standing default. Either answer writes `.impeccable/config.json`; the answer picks the value, never whether to record one. Yes writes the flipped value; "no, just this once" writes the value they flipped away from, the standing default they just confirmed by declining. Ask on the flip, never on the untouched default: a user who left the toggle alone told you nothing. A declined offer nothing writes down is an offer the next session makes again. When the user asks in words to change the standing default, update the file without asking. **Comp-led**: the chosen card's comp is law, generated before building when it does not yet exist, and the finish review audits the build against it; boldest composition on the table, fix rounds expected, and the comp is non-optional, no silent skipping. **Code-led**: no comp of this page and no apology for it; the QUALITY BAR boards still calibrate finish, and the ambition moves into the written contract, the FIRST VIEWPORT block plus a named signature interaction and motion grammar, which the finish reviewer audits in behavior; code-led is not a discount on commitment. A code-led round still declares each card's comp path as a flip reserve: when the user flips the toggle to comp mid-round, `--wait` returns once with BUILD PATH FLIPPED while the page shimmers the slots; generate each open card's comp into its declared path then, lead first, and wait again. The flip back is free, and a comp that already rendered rides at the finish review as the critique reference. Without image generation there is no toggle and no choice: code-led is the only path, stated in one line rather than asked. The old two-card execution-contract round is retired; `followup: true` remains the general mechanism for delivering any later round over the same table via `--update`. <!-- rule:skill-build-path-round -->
diff --git a/skill/reference/visualize.md b/skill/reference/visualize.md
index 4f006d4a5..352c19b3a 100644
--- a/skill/reference/visualize.md
+++ b/skill/reference/visualize.md
@@ -30,7 +30,7 @@ Do not begin code until the user approves a direction or explicitly delegates th
This approval point has no substitute and no skip condition. When the structured question tool errors, fall back to the decision page; only after both fail may you treat the choice as delegated, and a delegated pick is recorded exactly as an approval is and disclosed in your first reply, not your last. The finish reviewer treats comp-round comps with no recorded approval as a material finding; decision comps under `.impeccable/mocks/decision/` are the direction round's hand, not comp-round output, and imply no approval on their own.
-After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and its `.json` prompt sidecar gains `"approved": true` (every comp generated through `impeccable generate-image` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief, and it is what `impeccable build-phase advance` reads to close the comps phase. Summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved concept, and build.
+After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and its prompt sidecar (the image's full file name plus `.json`: `a.png` gets `a.png.json`) gains `"approved": true` (every comp generated through `impeccable generate-image` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief, and it is what `impeccable build-phase advance` reads to close the comps phase. Summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved concept, and build.
## After approval: the comp becomes a spec
diff --git a/tests/oracle/DELTAS.md b/tests/oracle/DELTAS.md
index 2aca83c03..bfc1ae236 100644
--- a/tests/oracle/DELTAS.md
+++ b/tests/oracle/DELTAS.md
@@ -269,3 +269,19 @@ Hand file and content fingerprints (same branch, supersedes the `handAt` rule ab
- `question-update-comps-next`: now snapshots `.impeccable/questions/k1.hand.json`, the new hand `--update` writes (`pre` is empty because neither slot holds a file). Stdout and exit are unchanged.
Generated slots and hand-write failures (same branch): a deterministic generator returns identical bytes for an unchanged prompt, so a re-roll regenerating into a reused slot failed the fingerprint rule forever. `impeccable generate-image` now marks a written `--out` that a recorded hand declares with a marker file in `<key>.generated/`, and such a slot counts as this hand's. A failed hand write now fails `--start` (before spawning) and `--update` (before delivering) with exit 1. No existing golden changed. New case `genimg-fake-marks-hand-slot`: the fake generator writes a declared slot and the snapshot shows the marker beside the untouched hand file. The failure path is covered by Rust tests, not the oracle, because its stderr carries the OS error text, which differs per platform. Follow-up: markers name their hand by `hand` (the hand's per-hand `id`, falling back to `digest` for a hand file without one) instead of `digest`, so `genimg-fake-marks-hand-slot` now shows `"hand":"0123456789abcdef"` where it showed `"digest"`; a new hand prunes other hands' markers only after its own write succeeds, and `--stop` and a closing answer remove the marker folder. `question-update-comps-next` now snapshots the hand file with its per-hand `id`, which mixes the clock and the pid, so that case masks it as `<HAND_ID>` with a case-scoped normalizer.
+
+## Recorded 2026-09-30: hand-tagged generated markers (#886)
+
+`--update` wrote the new hand and then pruned `<key>.generated/` by reading each marker's `hand` and deleting the file, so a parallel `impeccable generate-image` for the new hand that replaced a reused slot's marker between the read and the delete lost its marker, and a byte-identical regeneration then read as stale. Markers now carry the hand in their name, `<16 hex of the slot>-<hand id>.json`, so one hand's markers never share a path with another's, and the prune decides from the name alone: it deletes only names tagged with another hand. Legacy untagged `<16 hex>.json` markers are still read and pruned by their content `hand` (or `digest`).
+
+- `genimg-fake-marks-hand-slot`: the marker file is now `k1.generated/bc804e5cae3cb360-0123456789abcdef.json` where it was `k1.generated/bc804e5cae3cb360.json`. Its content, stdout, stderr and exit are unchanged.
+
+The interleaving itself is covered by Rust tests in `crates/context/src/serve_question.rs`, not the oracle, since it needs two writers.
+
+## Recorded 2026-09-30: sidecar name spelled out
+
+The decision-comp directives said a comp's prompt goes in `<comp>.json`, which an agent read as the comp's name without its extension (`assigned.json`). The engine checks the image's full file name plus `.json` (`a.png.json`), so the wording now says so: `its sidecar, the image's full file name plus .json (a.png gets a.png.json)`. Only that phrase moved in each golden; exit status, files and every other line are unchanged.
+
+- `question-update-comps-next`, `question-wait-flip`: the `NEXT read ... visualize.md` line ends with the new phrase in place of `(<comp>.json)`.
+- `question-wait-comp-sidecar-missing`, `question-wait-answer-comp-sidecar-missing`: `COMP SIDECAR MISSING` names the sidecar the same way, followed by `as {"prompt": "..."} (generate-image writes it itself, a harness image tool does not)`.
+- `question-wait-answer-comp-round`: `APPROVED COMP` says `Set "approved": true in its prompt sidecar, the image's full file name plus .json (a.png gets a.png.json)`.
diff --git a/tests/oracle/golden/genimg-fake-marks-hand-slot.json b/tests/oracle/golden/genimg-fake-marks-hand-slot.json
index 574705902..8265f7068 100644
--- a/tests/oracle/golden/genimg-fake-marks-hand-slot.json
+++ b/tests/oracle/golden/genimg-fake-marks-hand-slot.json
@@ -4,7 +4,7 @@
"exit": 0,
"signal": null,
"files": {
- ".impeccable/questions/k1.generated/bc804e5cae3cb360.json": "{\"slot\":\".impeccable/mocks/decision/a.png\",\"hand\":\"0123456789abcdef\"}",
+ ".impeccable/questions/k1.generated/bc804e5cae3cb360-0123456789abcdef.json": "{\"slot\":\".impeccable/mocks/decision/a.png\",\"hand\":\"0123456789abcdef\"}",
".impeccable/questions/k1.hand.json": "{\"digest\":\"0123456789abcdef\",\"comps\":[\".impeccable/mocks/decision/a.png\",\".impeccable/mocks/decision/b.png\"],\"pre\":{}}"
}
}
diff --git a/tests/oracle/golden/question-update-comps-next.json b/tests/oracle/golden/question-update-comps-next.json
index 130cd0c19..9366261b8 100644
--- a/tests/oracle/golden/question-update-comps-next.json
+++ b/tests/oracle/golden/question-update-comps-next.json
@@ -1,5 +1,5 @@
{
- "stdout": "next round delivered; the page reloads itself\nNEXT read <REPO>/skill/reference/visualize.md now, before writing any decision comp prompt; its comp rules govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar (<comp>.json).\n",
+ "stdout": "next round delivered; the page reloads itself\nNEXT read <REPO>/skill/reference/visualize.md now, before writing any decision comp prompt; its comp rules 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).\n",
"stderr": "",
"exit": 0,
"signal": null,
diff --git a/tests/oracle/golden/question-wait-answer-comp-round.json b/tests/oracle/golden/question-wait-answer-comp-round.json
index 8c00aa55a..4fdab618c 100644
--- a/tests/oracle/golden/question-wait-answer-comp-round.json
+++ b/tests/oracle/golden/question-wait-answer-comp-round.json
@@ -1,5 +1,5 @@
{
- "stdout": "ANSWER: {\"optionId\":\"b\",\"steer\":\"\",\"comp\":\".impeccable/mocks/comp-b-open-book.png\"}\nAPPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set \"approved\": true in its prompt sidecar (<comp>.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.\n",
+ "stdout": "ANSWER: {\"optionId\":\"b\",\"steer\":\"\",\"comp\":\".impeccable/mocks/comp-b-open-book.png\"}\nAPPROVED COMP: the user picked this composition in the comp round, so it is the approved comp. Set \"approved\": true in its prompt sidecar, the image's full file name plus .json (a.png gets a.png.json), record its path in the surface brief, then close the comps phase with build-phase advance. Build from it as it stands; never regenerate it.\n",
"stderr": "",
"exit": 0,
"signal": null,
diff --git a/tests/oracle/golden/question-wait-answer-comp-sidecar-missing.json b/tests/oracle/golden/question-wait-answer-comp-sidecar-missing.json
index 42c94a1b7..ddbee336d 100644
--- a/tests/oracle/golden/question-wait-answer-comp-sidecar-missing.json
+++ b/tests/oracle/golden/question-wait-answer-comp-sidecar-missing.json
@@ -1,5 +1,5 @@
{
- "stdout": "ANSWER: {\"optionId\":\"a\",\"steer\":\"\",\"comp\":\".impeccable/mocks/decision/a.png\",\"buildPath\":\"comp\",\"buildPathFlipped\":false}\nCHOSEN COMP: the decision comp at that path is compositional option one. On a comp-led build the comp round adds two variations beside it; on a code-led build it returns at the finish review as the critique reference. Never regenerate it from scratch.\nBUILD PATH: comp (the round’s recorded default). Comp-led: the chosen card’s comp is law; generate it before building when it does not exist yet, and the finish review audits the build against it.\nCOMP SIDECAR MISSING: .impeccable/mocks/decision/a.png, .impeccable/mocks/decision/b.png landed with no prompt sidecar. Every decision comp records the exact prompt that produced it in <comp>.json ({\"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": "ANSWER: {\"optionId\":\"a\",\"steer\":\"\",\"comp\":\".impeccable/mocks/decision/a.png\",\"buildPath\":\"comp\",\"buildPathFlipped\":false}\nCHOSEN COMP: the decision comp at that path is compositional option one. On a comp-led build the comp round adds two variations beside it; on a code-led build it returns at the finish review as the critique reference. Never regenerate it from scratch.\nBUILD PATH: comp (the round’s recorded default). Comp-led: the chosen card’s comp is law; generate it before building when it does not exist yet, and the finish review audits the build against it.\nCOMP SIDECAR MISSING: .impeccable/mocks/decision/a.png, .impeccable/mocks/decision/b.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",
"stderr": "",
"exit": 0,
"signal": null,
diff --git a/tests/oracle/golden/question-wait-comp-sidecar-missing.json b/tests/oracle/golden/question-wait-comp-sidecar-missing.json
index a5a3bf7d2..020de65ac 100644
--- a/tests/oracle/golden/question-wait-comp-sidecar-missing.json
+++ b/tests/oracle/golden/question-wait-comp-sidecar-missing.json
@@ -1,5 +1,5 @@
{
- "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 <comp>.json ({\"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.\n",
"stderr": "",
"exit": 3,
"signal": null,
diff --git a/tests/oracle/golden/question-wait-flip.json b/tests/oracle/golden/question-wait-flip.json
index e1e4b3aa9..fbb446c1a 100644
--- a/tests/oracle/golden/question-wait-flip.json
+++ b/tests/oracle/golden/question-wait-flip.json
@@ -1,5 +1,5 @@
{
- "stdout": "BUILD PATH FLIPPED: comp (for this session only; never write it to settings). The table is still open and the page shows shimmer where the images will land: generate each open card’s comp into its declared path now, lead first, then collect the answer with --wait again. A card whose comp already exists needs nothing.\nNEXT read <REPO>/skill/reference/visualize.md now, before writing any decision comp prompt; its comp rules govern every card's image. Then generate each declared comp into its slot, lead first, and record the exact prompt in its sidecar (<comp>.json).\n",
+ "stdout": "BUILD PATH FLIPPED: comp (for this session only; never write it to settings). The table is still open and the page shows shimmer where the images will land: generate each open card’s comp into its declared path now, lead first, then collect the answer with --wait again. A card whose comp already exists needs nothing.\nNEXT read <REPO>/skill/reference/visualize.md now, before writing any decision comp prompt; its comp rules 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).\n",
"stderr": "",
"exit": 0,
"signal": null,