The design language that makes your AI harness better at design.
JavaScript
Stop hosted builds from waiting on a plan review that cannot exist (#937)
Paul Bakaus7abffec18460
diff --git a/crates/cli/src/capture_service.rs b/crates/cli/src/capture_service.rsindex 54b5e836a..61334adf9 100644--- a/crates/cli/src/capture_service.rs+++ b/crates/cli/src/capture_service.rs@@ -11,7 +11,7 @@ use std::{collections::HashMap,io::{BufRead, BufReader, Read, Write},net::{TcpListener, TcpStream},- path::PathBuf,+ path::{Path, PathBuf},time::{Duration, Instant},};@@ -164,7 +164,8 @@ pub fn serve(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {let text = |k: &str| body[k].as_str().ok_or_else(|| format!("missing {k}"));match route.as_str() {"/capture" => {- require_component_review(component_review_pending, &review_tool)?;+ require_component_review(component_review_pending+ && capture_owes_review(&root, text("spec")?), &review_tool)?;if active.len() >= 2 {return Err("active capture limit".into());}@@ -357,6 +358,12 @@ pub struct RemoteEntryRenderer {key: String,}+/// Pending binds only while the spec being captured owes a kit review: a spec with+/// nothing to decide never produces a kit to approve. The requested spec, not the+/// default path, so a capture cannot borrow another file's exemption.+fn capture_owes_review(root: &Path, spec: &str) -> bool {+ impeccable_context::component_review::plan::spec_file_needs_review(&root.join(spec))+}fn require_component_review(pending: bool, tool: &str) -> Result<(), String> {if pending {return Err(format!("Component kit approval is pending. Call {tool} with the component manifest's manifest_path and wait for the user's decisions before assembled-page comparison. No page comparison was performed."));@@ -705,6 +712,22 @@ mod component_boundary_tests {assert!(error.contains("No page comparison was performed"));assert!(require_component_review(false, "component_review").is_ok());}+ #[test]+ fn pending_binds_only_while_the_captured_spec_owes_a_review() {+ let root = std::env::temp_dir().join(format!("impeccable-capture-owed-{}", std::process::id()));+ std::fs::create_dir_all(root.join("specs")).unwrap();+ let write = |name: &str, body: &str| std::fs::write(root.join("specs").join(name), body).unwrap();+ write("text.json", r#"{"regions":[{"id":"copy","kind":"text","box":{"x":0,"y":0,"w":1,"h":1}}]}"#);+ write("plate.json", r#"{"regions":[{"id":"art","kind":"plate","box":{"x":0,"y":0,"w":1,"h":1}}]}"#);+ write("invalid.json", "{}");+ assert!(!capture_owes_review(&root, "specs/text.json"));+ assert!(capture_owes_review(&root, "specs/plate.json"));+ assert!(capture_owes_review(&root, "specs/invalid.json"), "no regions array is not a measured spec");+ assert!(capture_owes_review(&root, "specs/missing.json"));+ assert!(require_component_review(true && capture_owes_review(&root, "specs/plate.json"), "component_review").is_err());+ assert!(require_component_review(true && capture_owes_review(&root, "specs/text.json"), "component_review").is_ok());+ let _ = std::fs::remove_dir_all(&root);+ }}#[cfg(test)]diff --git a/crates/comp-verbs/src/build_phase.rs b/crates/comp-verbs/src/build_phase.rsindex 2ec18d2d1..824b7dcbc 100644--- a/crates/comp-verbs/src/build_phase.rs+++ b/crates/comp-verbs/src/build_phase.rs@@ -2644,6 +2644,12 @@ fn run_gate(io: &Io, state: &mut Value, phase: &str, opts: &GateOpts, organic_sc/// current spec. A hosted review lives in the host's store: the host names its trusted/// session directories, and the gate fails closed without them.fn plan_review_refusal(io: &Io) -> Option<String> {+ // A spec with no plate and no code region to decide on has nothing to review;+ // `component-review plan` says so and writes no packet, so demanding an+ // acceptance here would deadlock the build on a review that cannot exist.+ if !impeccable_context::component_review::plan::spec_needs_review(&io.cwd) {+ return None;+ }let s = self_cmd(io);if let Some(tool) = io.env("IMPECCABLE_COMPONENT_REVIEW_TOOL") {let Some(named) = io.env("IMPECCABLE_COMPONENT_REVIEW_SESSIONS") else {diff --git a/crates/comp-verbs/src/build_phase/integrity_tests.rs b/crates/comp-verbs/src/build_phase/integrity_tests.rsindex 5ad518472..e5cf844c5 100644--- a/crates/comp-verbs/src/build_phase/integrity_tests.rs+++ b/crates/comp-verbs/src/build_phase/integrity_tests.rs@@ -942,6 +942,12 @@ fn page_work_waits_for_the_plan_and_asset_review_of_the_current_spec() {// A spec with nothing to decide has no review to wait for.write(SPEC_PATH, br#"{"comp":"comp.png","regions":[{"id":"copy","kind":"text","note":"Body","box":{"x":0,"y":0,"w":1,"h":1}}]}"#);assert!(plan_review_refusal(&io_with(&[]).0).is_none());+ // The hosted gate reads the same spec: no host acceptance is demanded for a review+ // `component-review plan` refuses to write, with the sessions empty or unnamed.+ let (hosted, _) = io_with(&[("IMPECCABLE_COMPONENT_REVIEW_TOOL", "component_review"), ("IMPECCABLE_COMPONENT_REVIEW_SESSIONS", "")]);+ assert!(plan_review_refusal(&hosted).is_none());+ let (hosted, _) = io_with(&[("IMPECCABLE_COMPONENT_REVIEW_TOOL", "component_review")]);+ assert!(plan_review_refusal(&hosted).is_none());}struct ReviewedCapture(crate::entry_capture::EntryEvidence, Option<crate::entry_capture::ApprovedReference>);diff --git a/crates/context/src/component_review/mod.rs b/crates/context/src/component_review/mod.rsindex 99f8dccc3..1512d21c3 100644--- a/crates/context/src/component_review/mod.rs+++ b/crates/context/src/component_review/mod.rs@@ -12,7 +12,7 @@ pub mod verify;mod visual_approval;use impeccable_common::Io;use serde_json::json;-use std::path::PathBuf;+use std::path::{Path, PathBuf};fn arg(args: &[String], name: &str) -> Option<String> {args.iter().position(|v| v == name)@@ -59,8 +59,15 @@ pub fn run_with_capturer(Some("lifecycle") => {let sessions: Vec<PathBuf> = args.windows(2).filter(|w| w[0] == "--session-dir").map(|w| PathBuf::from(&w[1])).collect();- let required: Vec<String> = args.windows(2).filter(|w| w[0] == "--require")+ let mut required: Vec<String> = args.windows(2).filter(|w| w[0] == "--require").map(|w| w[1].clone()).collect();+ // A host names the builder project so the components stage is read+ // against its spec: nothing to decide means no kit review is owed.+ if let Some(project) = arg(args, "--project") {+ if !plan::spec_needs_review(Path::new(&project)) {+ required.retain(|stage| stage != "components");+ }+ }let sessions = if sessions.is_empty() && !args.iter().any(|a| a == "--hosted") {let project = io.cwd.canonicalize().map_err(|e| e.to_string())?;lifecycle::project_sessions(&store, &project)?diff --git a/crates/context/src/component_review/plan.rs b/crates/context/src/component_review/plan.rsindex 84a6f5230..a569832e2 100644--- a/crates/context/src/component_review/plan.rs+++ b/crates/context/src/component_review/plan.rs@@ -29,6 +29,21 @@ pub fn needs_review(spec: &Value) -> bool {rs.iter().any(|r| raster(r["kind"].as_str().unwrap_or("")) || plan_item(r))})}+/// Whether the project's measured spec owes a plan and asset review. A missing or+/// unreadable spec owes one, so every gate keeps failing closed; only a spec that was+/// measured and holds nothing to decide releases the review, the same reading+/// `component-review plan` reports when it refuses to write an empty packet.+pub fn spec_needs_review(project: &Path) -> bool {+ spec_file_needs_review(&project.join(SPEC))+}+/// `spec_needs_review` for a spec at an explicit path. A spec without a `regions`+/// array is not a measured spec (`plan` refuses it), so it owes the review too.+pub fn spec_file_needs_review(path: &Path) -> bool {+ std::fs::read(path).ok()+ .and_then(|bytes| serde_json::from_slice::<Value>(&bytes).ok())+ .filter(|spec| spec["regions"].is_array())+ .is_none_or(|spec| needs_review(&spec))+}fn name(id: &str) -> String {let words = id.replace(['-', '_'], " ");let mut chars = words.trim().chars();@@ -206,19 +221,26 @@ fn decide(sessions: &[std::path::PathBuf], project: &Path, s: &str, steps: &str)let steps = format!("{steps} Write no page code before it is accepted.");let mut plans = Vec::new();let mut stale = None;+ let mut unreadable = None;for dir in sessions {let state = super::store::read(&dir.join("current.json"))?;if state["packet"]["schemaVersion"] == 3 && state["packet"]["stage"] == "components" {if super::lifecycle::accepted_in(dir, &state) && state["packet"]["specSha256"] == sha.as_str() {// The user judged these plate bytes; a plate replaced since is unreviewed.- match super::store::sources_current(&state) {+ match super::store::sources_current_in(&state, project) {Ok(()) => return Ok(()),- Err(why) => stale = Some(why),+ Err(why) if why.starts_with("review is stale") => stale = Some(why),+ // Not a changed plate; keep looking, a later session may still satisfy the gate.+ Err(why) => unreadable = Some(why),}}plans.push(state);}}+ if let Some(why) = unreadable {+ // Asking the user to approve the same bytes again cannot help.+ return Err(format!("The accepted plan and asset review could not be checked against this project ({why}). This is a harness or filesystem problem, not a changed plate: stop and report it; do not request the same review again."));+ }if let Some(why) = stale {let why = why.strip_prefix("review is stale: ").unwrap_or(&why).trim_end_matches("; prepare a new round");return Err(format!("A reviewed plate changed after the user accepted the plan and asset review ({why}). Present a new round; unchanged decisions carry over. {steps}"));diff --git a/crates/context/src/component_review/store.rs b/crates/context/src/component_review/store.rsindex 033c13b0c..275a9bc3b 100644--- a/crates/context/src/component_review/store.rs+++ b/crates/context/src/component_review/store.rs@@ -283,7 +283,13 @@ fn prepare_bound(Ok(dir)}pub fn sources_current(state: &Value) -> Result<(), String> {- let project = Path::new(string(state, "project")?);+ sources_current_in(state, Path::new(string(state, "project")?))+}+/// `sources_current` against an explicit project. A hosted session records the+/// host's snapshot of the project, which the builder's shell may not be able to+/// read and which never changes; the gate checks the builder's own files instead.+/// A file that exists but cannot be read is reported as unreadable, never as changed.+pub fn sources_current_in(state: &Value, project: &Path) -> Result<(), String> {for (path, hash) in state.get("sources").unwrap_or(&state["files"])@@ -293,9 +299,10 @@ pub fn sources_current(state: &Value) -> Result<(), String> {let full = project.join(relative(path)?).canonicalize()- .map_err(|_| format!("review is stale: {path} disappeared"))?;+ .map_err(|e| if e.kind() == std::io::ErrorKind::NotFound { format!("review is stale: {path} disappeared") }+ else { format!("reviewed source unreadable: {path}: {e}") })?;if !full.starts_with(project)- || digest(&fs::read(full).map_err(|e| e.to_string())?) != hash.as_str().unwrap_or("")+ || digest(&fs::read(&full).map_err(|e| format!("reviewed source unreadable: {path}: {e}"))?) != hash.as_str().unwrap_or(""){return Err(format!("review is stale: {path} changed; prepare a new round"diff --git a/crates/context/src/component_review/tests.rs b/crates/context/src/component_review/tests.rsindex 951656ad1..151c0b8bf 100644--- a/crates/context/src/component_review/tests.rs+++ b/crates/context/src/component_review/tests.rs@@ -105,6 +105,33 @@ fn hosted_capture_routes_to_the_review_tool_before_browser_or_store_access() {assert!(error.contains("Call component_review with manifest_path=\"review.json\""), "{error}");assert!(!f.root.join(".impeccable").exists());}+#[test]+fn hosted_lifecycle_owes_no_components_review_for_a_spec_with_nothing_to_decide() {+ let f = Fixture::new();+ let lifecycle = |project: Option<&std::path::Path>| {+ let (mut io, captured) = impeccable_common::Io::captured("", f.project.clone(),+ std::collections::HashMap::from([("HOME".into(), f.root.to_string_lossy().into_owned())]));+ let mut args: Vec<String> = ["lifecycle", "--hosted", "--require", "components", "--require", "hero"].map(String::from).to_vec();+ if let Some(project) = project { args.extend(["--project".into(), project.to_string_lossy().into_owned()]); }+ assert_eq!(super::run(&args, &mut io), 0);+ let out = captured.stdout.borrow().clone();+ serde_json::from_slice::<Value>(&out).unwrap()+ };+ // No spec yet: the components stage stays owed, with or without the project named.+ assert_eq!(lifecycle(Some(&f.project))["stage"], "components");+ fs::create_dir_all(f.project.join(".impeccable/build")).unwrap();+ // A spec without a regions array is not a measured spec: still owed.+ fs::write(f.project.join(super::plan::SPEC), b"{}").unwrap();+ assert_eq!(lifecycle(Some(&f.project))["stage"], "components");+ fs::write(f.project.join(super::plan::SPEC), br#"{"regions":[{"id":"copy","kind":"text","box":{"x":0,"y":0,"w":1,"h":1}}]}"#).unwrap();+ assert_eq!(lifecycle(None)["stage"], "components");+ // Named, a spec with nothing to decide releases the kit review; the hero review still binds.+ let named = lifecycle(Some(&f.project));+ assert_eq!((named["status"].as_str(), named["stage"].as_str()), (Some("pending"), Some("hero")), "{named}");+ // A spec with a raster region owes the kit review again.+ fs::write(f.project.join(super::plan::SPEC), br#"{"regions":[{"id":"art","kind":"plate","box":{"x":0,"y":0,"w":1,"h":1}}]}"#).unwrap();+ assert_eq!(lifecycle(Some(&f.project))["stage"], "components");+}struct Fixture {root: PathBuf,project: PathBuf,@@ -1222,6 +1249,53 @@ fn hosted_gate_requires_an_accepted_intact_review_in_the_named_sessions() {assert!(hosted(&[f.root.join("nowhere")]).is_err());}+#[test]+fn hosted_gate_checks_the_builders_files_not_the_hosts_snapshot() {+ // gallery-20261004-c-sol-08: the host recorded its review-project snapshot as the+ // session's project, the builder's sandbox could not read it, and the gate called+ // the EPERM "a reviewed plate changed" three rounds running.+ let f = Fixture::new();+ f.plan_project();+ f.plates();+ let dir = f.plan_round();+ let state = store::read(&dir.join("current.json")).unwrap();+ store::submit(&dir, &approve(&state)).unwrap();+ let mut snapshot = store::read(&dir.join("current.json")).unwrap();+ snapshot["project"] = json!(f.root.join("host-snapshot-unreadable").to_string_lossy());+ store::write(&dir.join("current.json"), &snapshot).unwrap();+ let hosted = || super::plan::gate_hosted(std::slice::from_ref(&dir), &f.project, "impeccable", "component_review");+ hosted().unwrap();+ fs::write(f.project.join("assets/art.png"), b"a different art plate").unwrap();+ let err = hosted().unwrap_err();+ assert!(err.contains("A reviewed plate changed") && err.contains("assets/art.png changed"), "{err}");+}++#[cfg(unix)]+#[test]+fn an_unreadable_reviewed_file_is_reported_as_unreadable_not_changed() {+ use std::os::unix::fs::PermissionsExt;+ let f = Fixture::new();+ f.plan_project();+ f.plates();+ let dir = f.plan_round();+ let state = store::read(&dir.join("current.json")).unwrap();+ store::submit(&dir, &approve(&state)).unwrap();+ let art = f.project.join("assets/art.png");+ fs::set_permissions(&art, fs::Permissions::from_mode(0o000)).unwrap();+ let result = f.gate();+ fs::set_permissions(&art, fs::Permissions::from_mode(0o644)).unwrap();+ if result.is_ok() { return; } // root reads through mode bits+ let err = result.unwrap_err();+ assert!(err.contains("could not be checked") && err.contains("not a changed plate") && !err.contains("A reviewed plate changed"), "{err}");+ // A directory the builder cannot traverse is unreadable too, not a vanished plate.+ let assets = f.project.join("assets");+ fs::set_permissions(&assets, fs::Permissions::from_mode(0o000)).unwrap();+ let result = f.gate();+ fs::set_permissions(&assets, fs::Permissions::from_mode(0o755)).unwrap();+ let err = result.unwrap_err();+ assert!(err.contains("could not be checked") && !err.contains("disappeared"), "{err}");+}+#[test]fn plan_leaves_bare_grounds_and_straight_rules_to_code_unless_flagged() {let f = Fixture::new();diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 4103b3b0d..897ab05b3 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -1959,11 +1959,11 @@ documented in [`ui/component-review/README.md`](../ui/component-review/README.md`impeccable component-review verify --manifest <project-relative JSON>` reads the native capture and user receipt. Before assembly acceptance, it requires an approved, natively captured round with unchanged manifest and dependencies. It does not trust the stored `captureVerified` flag: it recomputes capture integrity from the session's pinned blobs (every blob matches its hash, non-capture files match the pinned sources, the evidence covers every component in the manifest and packet, raster previews match their `raster-source` proof, and code views are `_review_captures/<sha256>.png` files whose hash equals the proof's `screenshotSha256`). The accepted-assembly path applies the same integrity check. After the assembled first viewport is accepted, it returns that original receipt: it does not claim later bytes were reviewed. It neither creates nor submits approvals.-`component-review lifecycle [--session-dir <private directory>] [--require components|hero] [--hosted]` reports the native review decision. Both options may repeat. With `--hosted`, only the supplied private sessions are considered; ordinary sessions resolve acceptance from the project in the local store. The result has `schemaVersion: 1`, `status` (`pending`, `approved`, or `accepted`), `reviewClosed`, and nullable `completionFeedback`. Accepted assembly returns `scope: "first-viewport"` and the original request/revision. Hosts transport that result without adding file-hash approval policy.+`component-review lifecycle [--session-dir <private directory>] [--require components|hero] [--hosted] [--project <dir>]` reports the native review decision. Both repeatable options may repeat. With `--project`, a `components` requirement is dropped when that project's `.impeccable/build/spec.json` exists, carries a `regions` array, and holds nothing to review (the same reading `component-review plan` refuses on); a missing, unreadable, or region-less spec keeps it. With `--hosted`, only the supplied private sessions are considered; ordinary sessions resolve acceptance from the project in the local store. The result has `schemaVersion: 1`, `status` (`pending`, `approved`, or `accepted`), `reviewClosed`, and nullable `completionFeedback`. Accepted assembly returns `scope: "first-viewport"` and the original request/revision. Hosts transport that result without adding file-hash approval policy.For a v3 round, `verify`, `lifecycle` and the gate below apply the same integrity check with the plan proofs: assets need their `raster-source` proof, plan items a `comp-crop` proof whose box equals the component's and whose comp path and hash equal the pinned comp, and the packet's `specSha256` must equal the pinned `.impeccable/build/spec.json` source.-`build-phase advance` from `plates` or `hero`, and `build-phase record hero`, wait for the plan and asset review. They pass when the first viewport is already accepted for this journey, when the spec has nothing to review, or when a v3 component session of the current journey is accepted (intact capture, approved receipt), its `specSha256` equals the current spec's SHA-256, and every file it pinned (plates, comp, spec, manifest) still has its reviewed bytes. Otherwise `advance` fails the plates or hero gate with one added reason and `record hero` exits 1 with `build-phase: record hero refused. <reason>` on stderr. The reason is one of: not accepted for this build; accepted for an earlier spec.json; a reviewed plate changed after acceptance (names the file; present a new round, unchanged decisions carry over); or the user requested changes (read the receipt with `component-review status`). Each names `component-review plan`, `capture --manifest .impeccable/review/components.json` and `serve --session <session>`. The review store is `~/.impeccable/component-reviews`. When `IMPECCABLE_COMPONENT_REVIEW_TOOL` is set the review lives in the host, and the host must name its trusted session directories in `IMPECCABLE_COMPONENT_REVIEW_SESSIONS` (an OS path list, as `lifecycle --hosted --session-dir` takes them). The gate then applies the same rules to those directories (accepted first viewport, or accepted intact v3 review with the current `specSha256`) and names the tool in its refusal; an unreadable directory refuses. Without the variable a hosted session is refused: the message calls it a harness configuration problem to stop and report, and deliberately does not name the variable, so the agent is not invited to set it. `IMPECCABLE_COMPONENT_REVIEW_PENDING` is not read by this gate (only by the hosted capture service). A quoted `--force --reason` that satisfies the existing plates rule waives this reason together with the plate readings and is recorded the same way; the hero phase then does not ask for the review again. `record hero` has no force.+`build-phase advance` from `plates` or `hero`, and `build-phase record hero`, wait for the plan and asset review. They pass when the first viewport is already accepted for this journey, when the spec has nothing to review, or when a v3 component session of the current journey is accepted (intact capture, approved receipt), its `specSha256` equals the current spec's SHA-256, and every file it pinned (plates, comp, spec, manifest) still has its reviewed bytes. Otherwise `advance` fails the plates or hero gate with one added reason and `record hero` exits 1 with `build-phase: record hero refused. <reason>` on stderr. The reason is one of: not accepted for this build; accepted for an earlier spec.json; a reviewed plate changed after acceptance (names the file; present a new round, unchanged decisions carry over); or the user requested changes (read the receipt with `component-review status`). Each names `component-review plan`, `capture --manifest .impeccable/review/components.json` and `serve --session <session>`. The review store is `~/.impeccable/component-reviews`. When `IMPECCABLE_COMPONENT_REVIEW_TOOL` is set the review lives in the host, and the host must name its trusted session directories in `IMPECCABLE_COMPONENT_REVIEW_SESSIONS` (an OS path list, as `lifecycle --hosted --session-dir` takes them). A spec with nothing to review passes before any of this is read, hosted or not. The gate then applies the same rules to those directories, checking the pinned bytes against the builder's own project rather than the host snapshot a hosted session records, and a pinned file that exists but cannot be read is refused as unreadable (a harness problem), never as a changed plate (accepted first viewport, or accepted intact v3 review with the current `specSha256`) and names the tool in its refusal; an unreadable directory refuses. Without the variable a hosted session is refused: the message calls it a harness configuration problem to stop and report, and deliberately does not name the variable, so the agent is not invited to set it. `IMPECCABLE_COMPONENT_REVIEW_PENDING` is not read by this gate (only by the hosted capture service, which ignores it while the spec being captured holds nothing to review). A quoted `--force --reason` that satisfies the existing plates rule waives this reason together with the plate readings and is recorded the same way; the hero phase then does not ask for the review again. `record hero` has no force.Assembly acceptance closes component and assembly reviews for this journey. The agent completes the rest of the page using the accepted direction, without reopening review for shared CSS, responsive changes, finish checks, or new manifest IDs. Needs-work rounds remain possible before acceptance. Original receipts and captures remain immutable. A separately requested new design journey uses a fresh review store; changing a manifest alone never starts one. Source-bound metric evidence below remains separate from this lifecycle.diff --git a/skill/reference/new-work.md b/skill/reference/new-work.mdindex 476cc0b74..334b37fea 100644--- a/skill/reference/new-work.md+++ b/skill/reference/new-work.md@@ -48,11 +48,11 @@ The script deals three of your structures; the dice pick which three reach the u4. Run `{{scripts_path}}/impeccable concept-seed --scope direction --mode <mode>` and follow what it prints. No substitute, no skip: on a new or replacement world, writing artifact code before this script has run and its assignment is acknowledged is a contract violation, whatever the harness, the model, or the time pressure; the roll is what keeps every run from converging on the category default. The script assigns the direction to build and deals catalog challengers. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, clarity wins conflicts. Weigh fused challengers against the assigned direction on exactly two axes, audience identification and product clarity. Losing to strong grounded material is a valid outcome; beating a thin or tool-monoculture list is the point. Close with a verdict per challenger, decided before any borrowing: wins (beats the assigned direction on both axes; becomes the build candidate), competitive (holds one axis; stays a full alternate), or declined (loses both). A declined challenger is not spent: name the one discipline of its system the assigned direction lacks, and raise the assigned direction to match before presenting it. A donation transfers ambition and system discipline (a palette's total commitment, a grid's density courage, a form's structural honesty), never the challenger's clothes. A component treatment, such as a button's shadow or a display face, is clothes, not discipline; a lifted motif is a costume note, not a raise, and one world owns the page. Write each raise into the presented direction as its own line, named for its donor; a raise nobody can read did not happen. <!-- rule:skill-concept-procedure --> <!-- rule:skill-verdict-and-donation -->5. Present one direction, fully committed and already raised by the hand it beat, raises visible as named lines: world, first viewport, visitor path, signature interaction, cross-surface reach, honest risk. Route each challenger by verdict: winning and competitive challengers are full alternates with their QUALITY BAR cards and one-line case; declined challengers render demoted, compact and quiet, each carrying its verdict and what the direction kept from it, never full-size, never silently dropped, still adoptable on request. The verdict informs the user's choice, never pre-empts it; the demoted row is the hand's proof of judgment. A hand holds at most three full-card challengers: when the roll deals more, the three strongest join and the rest wait in the re-roll pool, noted in one line; dropping a challenger from the hand itself takes a named product-truth failure, disclosed. Add one card for your own top-ranked grounded candidate when it is not the assigned direction, kicker IMPECCABLE’S PICK, same anatomy as every card, with an honest risk line naming its familiarity when true: the strongest grounded direction is often where most runs in this category land, and the user deciding that trade is the point of showing it. Familiar and effective is a legitimate destination, not a failure of nerve; the pick card and the standing exit serve it at two depths. One pick card, never two, never a ranked list: a lineup of your candidates hands selection back to a taste function and invites the safest card. The pick never takes the lead position; when the dice assign your top candidate there is no pick card, and the assigned card notes it topped your list. Add re-roll with an optional one-line steer, in three registers: plain (a fresh hand, same spread), safer (your remaining conventional grounded candidates plus the canon against named competitors), bolder (foreign forms only, at full commitment). The register is the user's steering on the familiar-to-bold axis, never yours to pre-select; when the answer carries one, re-run the seed with `--register <value>` and the next `--reroll` round, and follow what it prints. A user saying "bolder" or "safer" while a direction round is open means these registers, never the bolder or harden commands. The two channels share this structure and differ only in richness: cards and boards on the decision page, names and one-liners through the structured tool, whose option list carries the assigned direction, the pick, the winning and competitive challengers, and the standing exit last; declined challengers fold into the assigned option's description as their kept lines, so the raise survives the text channel. <!-- rule:skill-pick-card-one-only -->-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. A harness that cannot hold a blocking `--wait` (it backgrounds long-running commands, or reaps a backgrounded child) takes the structured tool without starting the page and discloses the substitution in the first reply, so the tab is never left unanswered. Never predict any other fallback: run the script, and only exit code 2 from starting it, or that wait check before starting, routes the decision to the structured tool; those are the fallback, never an error to retry. <!-- rule:skill-visual-decision-page -->+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. A harness that cannot hold a blocking `--wait` (it detaches long-running commands without ever returning their output, or reaps a backgrounded child) takes the structured tool without starting the page and discloses the substitution in the first reply, so the tab is never left unanswered. A shell that hands back a still-running command as a session you can poll holds the wait: poll that session until it exits, and rerun `--wait` only after it exits without an answer. Never predict any other fallback: run the script, and only exit code 2 from starting it, or that wait check before starting, routes the decision to the structured tool; those are 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 the MODE RULES block concept-seed printed, and a prompt written before reading them 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, the COMPS section of the MODE RULES block copied verbatim (the subagent never sees the roll's output), 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 -->+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 structured-tool fallback has no toggle either: it builds on the recorded default and asks nothing about the build path. 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 -->Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product, as far as the surface's mode allows. How far a source that is itself an interface language may carry its grammar is the mode's call, in the MODE RULES block. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.diff --git a/tests/skill-reference.test.mjs b/tests/skill-reference.test.mjsindex 2cb980d15..83a3704fb 100644--- a/tests/skill-reference.test.mjs+++ b/tests/skill-reference.test.mjs@@ -80,6 +80,10 @@ describe('skill reference authoring contracts', () => {assert.match(visualDecisionPage, /first reply/);assert.match(visualDecisionPage, /exit code 2 from starting it/);assert.match(visualDecisionPage, /wait check before starting/);+ // Codex's exec_command returns a still-running --wait as a pollable session;+ // that is not a harness that backgrounds the command away (astra/sol, 2026-10-04).+ assert.match(visualDecisionPage, /session you can poll holds the wait/);+ assert.match(visualDecisionPage, /rerun `--wait` only after it exits without an answer/);assert.doesNotMatch(visualDecisionPage,/only exit code 2 from starting it routes the decision to the structured tool; that exit is the fallback/,