From e3f732e99cffc7d6b49fca1c40b2b9261c6a836e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 00:10:01 +0000 Subject: [PATCH] Sync generated provider output --- .../agents/impeccable_documenter.toml | 24 +++++++++++++++++ .../agents/impeccable_finish_reviewer.toml | 17 +++++++----- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .claude/agents/impeccable-documenter.md | 26 +++++++++++++++++++ .claude/agents/impeccable-finish-reviewer.md | 17 +++++++----- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .grok/agents/impeccable-documenter.md | 26 +++++++++++++++++++ .grok/agents/impeccable-finish-reviewer.md | 17 +++++++----- .grok/skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .kiro/skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .pi/skills/impeccable/reference/new-work.md | 10 +++---- .pi/skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .trae/skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- .vibe/skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- plugin/.claude-plugin/plugin.json | 1 + plugin/agents/impeccable-documenter.md | 26 +++++++++++++++++++ plugin/agents/impeccable-finish-reviewer.md | 17 +++++++----- .../skills/impeccable/reference/new-work.md | 10 +++---- .../skills/impeccable/reference/visualize.md | 4 +-- .../impeccable/scripts/concept-seed.mjs | 4 ++- 54 files changed, 293 insertions(+), 148 deletions(-) create mode 100644 .agents/skills/impeccable/agents/impeccable_documenter.toml create mode 100644 .claude/agents/impeccable-documenter.md create mode 100644 .grok/agents/impeccable-documenter.md create mode 100644 plugin/agents/impeccable-documenter.md diff --git a/.agents/skills/impeccable/agents/impeccable_documenter.toml b/.agents/skills/impeccable/agents/impeccable_documenter.toml new file mode 100644 index 000000000..78b6d9d68 --- /dev/null +++ b/.agents/skills/impeccable/agents/impeccable_documenter.toml @@ -0,0 +1,24 @@ +name = "impeccable_documenter" +description = "Records DESIGN.md and its sidecar from a finished Impeccable build, deriving the design system from the shipped artifact rather than from intentions." +model_reasoning_effort = "medium" +nickname_candidates = ["System Scribe", "Token Surveyor", "Ground Truth"] +developer_instructions = ''' +# Impeccable Documenter + +You record a project's design system after the build is done. Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned. Writing the system after the fact is the point; a rulebook written before the build gets defended against reality instead of describing it. + +## Input Contract + +Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; and the boundary to write at (project or app root). An existing DESIGN.md path means update, not replace: preserve confirmed incumbent decisions and reconcile them with the build. + +## Workflow + +1. Read `reference/document.md` in full; it is the operating spec for DESIGN.md's format, token schema, sidecar, and section order. Follow it exactly. +2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence. +3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system. +4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear. + +## Output Contract + +Return: the file paths written, a five-line summary of the recorded system (palette strategy, type ramp shape, named rules), and one line naming anything in the build you deliberately did not canonize and why. No other prose. +''' diff --git a/.agents/skills/impeccable/agents/impeccable_finish_reviewer.toml b/.agents/skills/impeccable/agents/impeccable_finish_reviewer.toml index 6f80d9b31..e336188bc 100644 --- a/.agents/skills/impeccable/agents/impeccable_finish_reviewer.toml +++ b/.agents/skills/impeccable/agents/impeccable_finish_reviewer.toml @@ -1,5 +1,5 @@ name = "impeccable_finish_reviewer" -description = "Reviews a finished Impeccable build against its direction contract, persistence requirements, and the chosen world's quality bar, returning an ordered list of material fixes." +description = "Reviews a finished Impeccable build against its direction contract, the approved comp, and the chosen world's quality bar, returning an ordered list of material fixes." model_reasoning_effort = "high" nickname_candidates = ["Finishing Eye", "Contract Judge", "Ceiling Check"] developer_instructions = ''' @@ -7,20 +7,23 @@ developer_instructions = ''' You are the finishing reviewer for an Impeccable build: fresh eyes on a done artifact, outside the build thread's attention gravity. You do not edit anything; the parent agent applies your fixes. +You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable. + ## Input Contract -Expect: the original request; the confirmed user answers; the artifact path(s); the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md and DESIGN.md paths; existing hook or detector findings; the chosen world's QUALITY BAR card paths and approved comp paths when they exist; screenshot path(s) when available. When the harness can view images, open the card, the comp, and the screenshot before judging. +Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card before judging. ## Checks, in order -1. **Persistence.** On a new or replacement world: PRODUCT.md and DESIGN.md exist, and DESIGN.md matches the built world. A missing or mismatched file is the first material fix, ahead of any craft point. -2. **Ceiling.** Against the QUALITY BAR card and the approved comp, name the world's native devices the build left unused: frame, depth, lettering treatment, ornament density, motion. Compare commitment and finish, never composition; the card is a bar, not a layout. -3. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport: what would a visitor describe an hour later, and is it the thesis or a mood? -4. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. +1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. +2. **Fidelity.** Against the approved comp: topology, reading order, focal scale, overlaps and z-order, density, signature geometry. Name every drift and classify it intentional or defect. The comp governs composition; it is not a pixel spec for semantics, accessibility, or responsive behavior. +3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition. +4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport. +5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one. Do not run a second detector pass; mechanical findings belong to the parent's hooks. ## Output Contract -Return exactly four sections: `persistence` (pass/fail with specifics), `ceiling` (the unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). No praise, no summary prose. +Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (drift list with intentional/defect per item, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose. ''' diff --git a/.agents/skills/impeccable/reference/new-work.md b/.agents/skills/impeccable/reference/new-work.md index 122fb1fb1..6c5835d41 100644 --- a/.agents/skills/impeccable/reference/new-work.md +++ b/.agents/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.agents/skills/impeccable/reference/visualize.md b/.agents/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.agents/skills/impeccable/reference/visualize.md +++ b/.agents/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.agents/skills/impeccable/scripts/concept-seed.mjs b/.agents/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.agents/skills/impeccable/scripts/concept-seed.mjs +++ b/.agents/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.claude/agents/impeccable-documenter.md b/.claude/agents/impeccable-documenter.md new file mode 100644 index 000000000..bac1c874a --- /dev/null +++ b/.claude/agents/impeccable-documenter.md @@ -0,0 +1,26 @@ +--- +name: impeccable-documenter +description: Records DESIGN.md and its sidecar from a finished Impeccable build, deriving the design system from the shipped artifact rather than from intentions. +tools: Read, Write, Bash, Glob, Grep +model: inherit +effort: medium +maxTurns: 12 +--- +# Impeccable Documenter + +You record a project's design system after the build is done. Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned. Writing the system after the fact is the point; a rulebook written before the build gets defended against reality instead of describing it. + +## Input Contract + +Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; and the boundary to write at (project or app root). An existing DESIGN.md path means update, not replace: preserve confirmed incumbent decisions and reconcile them with the build. + +## Workflow + +1. Read `reference/document.md` in full; it is the operating spec for DESIGN.md's format, token schema, sidecar, and section order. Follow it exactly. +2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence. +3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system. +4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear. + +## Output Contract + +Return: the file paths written, a five-line summary of the recorded system (palette strategy, type ramp shape, named rules), and one line naming anything in the build you deliberately did not canonize and why. No other prose. diff --git a/.claude/agents/impeccable-finish-reviewer.md b/.claude/agents/impeccable-finish-reviewer.md index e4aa15c3a..540d2435e 100644 --- a/.claude/agents/impeccable-finish-reviewer.md +++ b/.claude/agents/impeccable-finish-reviewer.md @@ -1,6 +1,6 @@ --- name: impeccable-finish-reviewer -description: Reviews a finished Impeccable build against its direction contract, persistence requirements, and the chosen world's quality bar, returning an ordered list of material fixes. +description: Reviews a finished Impeccable build against its direction contract, the approved comp, and the chosen world's quality bar, returning an ordered list of material fixes. tools: Read, Bash, Glob, Grep model: inherit effort: high @@ -10,19 +10,22 @@ maxTurns: 12 You are the finishing reviewer for an Impeccable build: fresh eyes on a done artifact, outside the build thread's attention gravity. You do not edit anything; the parent agent applies your fixes. +You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable. + ## Input Contract -Expect: the original request; the confirmed user answers; the artifact path(s); the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md and DESIGN.md paths; existing hook or detector findings; the chosen world's QUALITY BAR card paths and approved comp paths when they exist; screenshot path(s) when available. When the harness can view images, open the card, the comp, and the screenshot before judging. +Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card before judging. ## Checks, in order -1. **Persistence.** On a new or replacement world: PRODUCT.md and DESIGN.md exist, and DESIGN.md matches the built world. A missing or mismatched file is the first material fix, ahead of any craft point. -2. **Ceiling.** Against the QUALITY BAR card and the approved comp, name the world's native devices the build left unused: frame, depth, lettering treatment, ornament density, motion. Compare commitment and finish, never composition; the card is a bar, not a layout. -3. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport: what would a visitor describe an hour later, and is it the thesis or a mood? -4. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. +1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. +2. **Fidelity.** Against the approved comp: topology, reading order, focal scale, overlaps and z-order, density, signature geometry. Name every drift and classify it intentional or defect. The comp governs composition; it is not a pixel spec for semantics, accessibility, or responsive behavior. +3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition. +4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport. +5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one. Do not run a second detector pass; mechanical findings belong to the parent's hooks. ## Output Contract -Return exactly four sections: `persistence` (pass/fail with specifics), `ceiling` (the unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). No praise, no summary prose. +Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (drift list with intentional/defect per item, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose. diff --git a/.claude/skills/impeccable/reference/new-work.md b/.claude/skills/impeccable/reference/new-work.md index 77bf971c4..d397a6635 100644 --- a/.claude/skills/impeccable/reference/new-work.md +++ b/.claude/skills/impeccable/reference/new-work.md @@ -68,9 +68,7 @@ Your measured rendition prior: warm, bookish, family, and child-facing subjects Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -100,6 +98,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.claude/skills/impeccable/reference/visualize.md b/.claude/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.claude/skills/impeccable/reference/visualize.md +++ b/.claude/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.claude/skills/impeccable/scripts/concept-seed.mjs b/.claude/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.claude/skills/impeccable/scripts/concept-seed.mjs +++ b/.claude/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.cursor/skills/impeccable/reference/new-work.md b/.cursor/skills/impeccable/reference/new-work.md index 0f534722c..9e2879eaf 100644 --- a/.cursor/skills/impeccable/reference/new-work.md +++ b/.cursor/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.cursor/skills/impeccable/reference/visualize.md b/.cursor/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.cursor/skills/impeccable/reference/visualize.md +++ b/.cursor/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.cursor/skills/impeccable/scripts/concept-seed.mjs b/.cursor/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.cursor/skills/impeccable/scripts/concept-seed.mjs +++ b/.cursor/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.gemini/skills/impeccable/reference/new-work.md b/.gemini/skills/impeccable/reference/new-work.md index ecc3915d2..e7dde7925 100644 --- a/.gemini/skills/impeccable/reference/new-work.md +++ b/.gemini/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.gemini/skills/impeccable/reference/visualize.md b/.gemini/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.gemini/skills/impeccable/reference/visualize.md +++ b/.gemini/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.gemini/skills/impeccable/scripts/concept-seed.mjs b/.gemini/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.gemini/skills/impeccable/scripts/concept-seed.mjs +++ b/.gemini/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.github/skills/impeccable/reference/new-work.md b/.github/skills/impeccable/reference/new-work.md index 2bdc70209..54e9e493c 100644 --- a/.github/skills/impeccable/reference/new-work.md +++ b/.github/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.github/skills/impeccable/reference/visualize.md b/.github/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.github/skills/impeccable/reference/visualize.md +++ b/.github/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.github/skills/impeccable/scripts/concept-seed.mjs b/.github/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.github/skills/impeccable/scripts/concept-seed.mjs +++ b/.github/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.grok/agents/impeccable-documenter.md b/.grok/agents/impeccable-documenter.md new file mode 100644 index 000000000..bac1c874a --- /dev/null +++ b/.grok/agents/impeccable-documenter.md @@ -0,0 +1,26 @@ +--- +name: impeccable-documenter +description: Records DESIGN.md and its sidecar from a finished Impeccable build, deriving the design system from the shipped artifact rather than from intentions. +tools: Read, Write, Bash, Glob, Grep +model: inherit +effort: medium +maxTurns: 12 +--- +# Impeccable Documenter + +You record a project's design system after the build is done. Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned. Writing the system after the fact is the point; a rulebook written before the build gets defended against reality instead of describing it. + +## Input Contract + +Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; and the boundary to write at (project or app root). An existing DESIGN.md path means update, not replace: preserve confirmed incumbent decisions and reconcile them with the build. + +## Workflow + +1. Read `reference/document.md` in full; it is the operating spec for DESIGN.md's format, token schema, sidecar, and section order. Follow it exactly. +2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence. +3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system. +4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear. + +## Output Contract + +Return: the file paths written, a five-line summary of the recorded system (palette strategy, type ramp shape, named rules), and one line naming anything in the build you deliberately did not canonize and why. No other prose. diff --git a/.grok/agents/impeccable-finish-reviewer.md b/.grok/agents/impeccable-finish-reviewer.md index e4aa15c3a..540d2435e 100644 --- a/.grok/agents/impeccable-finish-reviewer.md +++ b/.grok/agents/impeccable-finish-reviewer.md @@ -1,6 +1,6 @@ --- name: impeccable-finish-reviewer -description: Reviews a finished Impeccable build against its direction contract, persistence requirements, and the chosen world's quality bar, returning an ordered list of material fixes. +description: Reviews a finished Impeccable build against its direction contract, the approved comp, and the chosen world's quality bar, returning an ordered list of material fixes. tools: Read, Bash, Glob, Grep model: inherit effort: high @@ -10,19 +10,22 @@ maxTurns: 12 You are the finishing reviewer for an Impeccable build: fresh eyes on a done artifact, outside the build thread's attention gravity. You do not edit anything; the parent agent applies your fixes. +You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable. + ## Input Contract -Expect: the original request; the confirmed user answers; the artifact path(s); the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md and DESIGN.md paths; existing hook or detector findings; the chosen world's QUALITY BAR card paths and approved comp paths when they exist; screenshot path(s) when available. When the harness can view images, open the card, the comp, and the screenshot before judging. +Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card before judging. ## Checks, in order -1. **Persistence.** On a new or replacement world: PRODUCT.md and DESIGN.md exist, and DESIGN.md matches the built world. A missing or mismatched file is the first material fix, ahead of any craft point. -2. **Ceiling.** Against the QUALITY BAR card and the approved comp, name the world's native devices the build left unused: frame, depth, lettering treatment, ornament density, motion. Compare commitment and finish, never composition; the card is a bar, not a layout. -3. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport: what would a visitor describe an hour later, and is it the thesis or a mood? -4. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. +1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. +2. **Fidelity.** Against the approved comp: topology, reading order, focal scale, overlaps and z-order, density, signature geometry. Name every drift and classify it intentional or defect. The comp governs composition; it is not a pixel spec for semantics, accessibility, or responsive behavior. +3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition. +4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport. +5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one. Do not run a second detector pass; mechanical findings belong to the parent's hooks. ## Output Contract -Return exactly four sections: `persistence` (pass/fail with specifics), `ceiling` (the unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). No praise, no summary prose. +Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (drift list with intentional/defect per item, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose. diff --git a/.grok/skills/impeccable/reference/new-work.md b/.grok/skills/impeccable/reference/new-work.md index f367e3d0f..cc9bc9293 100644 --- a/.grok/skills/impeccable/reference/new-work.md +++ b/.grok/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.grok/skills/impeccable/reference/visualize.md b/.grok/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.grok/skills/impeccable/reference/visualize.md +++ b/.grok/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.grok/skills/impeccable/scripts/concept-seed.mjs b/.grok/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.grok/skills/impeccable/scripts/concept-seed.mjs +++ b/.grok/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.kiro/skills/impeccable/reference/new-work.md b/.kiro/skills/impeccable/reference/new-work.md index 58d9e03b3..e43658168 100644 --- a/.kiro/skills/impeccable/reference/new-work.md +++ b/.kiro/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.kiro/skills/impeccable/reference/visualize.md b/.kiro/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.kiro/skills/impeccable/reference/visualize.md +++ b/.kiro/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.kiro/skills/impeccable/scripts/concept-seed.mjs b/.kiro/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.kiro/skills/impeccable/scripts/concept-seed.mjs +++ b/.kiro/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.opencode/skills/impeccable/reference/new-work.md b/.opencode/skills/impeccable/reference/new-work.md index 9e5744c41..2d615d2e1 100644 --- a/.opencode/skills/impeccable/reference/new-work.md +++ b/.opencode/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.opencode/skills/impeccable/reference/visualize.md b/.opencode/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.opencode/skills/impeccable/reference/visualize.md +++ b/.opencode/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.opencode/skills/impeccable/scripts/concept-seed.mjs b/.opencode/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.opencode/skills/impeccable/scripts/concept-seed.mjs +++ b/.opencode/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.pi/skills/impeccable/reference/new-work.md b/.pi/skills/impeccable/reference/new-work.md index 80004ea3c..db2da8dd0 100644 --- a/.pi/skills/impeccable/reference/new-work.md +++ b/.pi/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.pi/skills/impeccable/reference/visualize.md b/.pi/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.pi/skills/impeccable/reference/visualize.md +++ b/.pi/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.pi/skills/impeccable/scripts/concept-seed.mjs b/.pi/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.pi/skills/impeccable/scripts/concept-seed.mjs +++ b/.pi/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.qoder/skills/impeccable/reference/new-work.md b/.qoder/skills/impeccable/reference/new-work.md index 0e71bf09b..abc1ee7ac 100644 --- a/.qoder/skills/impeccable/reference/new-work.md +++ b/.qoder/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.qoder/skills/impeccable/reference/visualize.md b/.qoder/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.qoder/skills/impeccable/reference/visualize.md +++ b/.qoder/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.qoder/skills/impeccable/scripts/concept-seed.mjs b/.qoder/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.qoder/skills/impeccable/scripts/concept-seed.mjs +++ b/.qoder/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.rovodev/skills/impeccable/reference/new-work.md b/.rovodev/skills/impeccable/reference/new-work.md index ef8a4bb7d..a756deb6f 100644 --- a/.rovodev/skills/impeccable/reference/new-work.md +++ b/.rovodev/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.rovodev/skills/impeccable/reference/visualize.md b/.rovodev/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.rovodev/skills/impeccable/reference/visualize.md +++ b/.rovodev/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.rovodev/skills/impeccable/scripts/concept-seed.mjs b/.rovodev/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.rovodev/skills/impeccable/scripts/concept-seed.mjs +++ b/.rovodev/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.trae-cn/skills/impeccable/reference/new-work.md b/.trae-cn/skills/impeccable/reference/new-work.md index 69c045cd9..1a5106abe 100644 --- a/.trae-cn/skills/impeccable/reference/new-work.md +++ b/.trae-cn/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.trae-cn/skills/impeccable/reference/visualize.md b/.trae-cn/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.trae-cn/skills/impeccable/reference/visualize.md +++ b/.trae-cn/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.trae-cn/skills/impeccable/scripts/concept-seed.mjs b/.trae-cn/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.trae-cn/skills/impeccable/scripts/concept-seed.mjs +++ b/.trae-cn/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.trae/skills/impeccable/reference/new-work.md b/.trae/skills/impeccable/reference/new-work.md index 98c22da4c..e6639b58f 100644 --- a/.trae/skills/impeccable/reference/new-work.md +++ b/.trae/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.trae/skills/impeccable/reference/visualize.md b/.trae/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.trae/skills/impeccable/reference/visualize.md +++ b/.trae/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.trae/skills/impeccable/scripts/concept-seed.mjs b/.trae/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.trae/skills/impeccable/scripts/concept-seed.mjs +++ b/.trae/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/.vibe/skills/impeccable/reference/new-work.md b/.vibe/skills/impeccable/reference/new-work.md index c691ed5cb..6f0baaa57 100644 --- a/.vibe/skills/impeccable/reference/new-work.md +++ b/.vibe/skills/impeccable/reference/new-work.md @@ -66,9 +66,7 @@ Calibration: AI-generated interfaces cluster around a few looks regardless of su Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -98,6 +96,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/.vibe/skills/impeccable/reference/visualize.md b/.vibe/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/.vibe/skills/impeccable/reference/visualize.md +++ b/.vibe/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/.vibe/skills/impeccable/scripts/concept-seed.mjs b/.vibe/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/.vibe/skills/impeccable/scripts/concept-seed.mjs +++ b/.vibe/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index fcb8b36a8..729452ec5 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -11,6 +11,7 @@ "skills": "./skills/", "agents": [ "./agents/impeccable-asset-producer.md", + "./agents/impeccable-documenter.md", "./agents/impeccable-finish-reviewer.md", "./agents/impeccable-manual-edit-applier.md" ] diff --git a/plugin/agents/impeccable-documenter.md b/plugin/agents/impeccable-documenter.md new file mode 100644 index 000000000..bac1c874a --- /dev/null +++ b/plugin/agents/impeccable-documenter.md @@ -0,0 +1,26 @@ +--- +name: impeccable-documenter +description: Records DESIGN.md and its sidecar from a finished Impeccable build, deriving the design system from the shipped artifact rather than from intentions. +tools: Read, Write, Bash, Glob, Grep +model: inherit +effort: medium +maxTurns: 12 +--- +# Impeccable Documenter + +You record a project's design system after the build is done. Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned. Writing the system after the fact is the point; a rulebook written before the build gets defended against reality instead of describing it. + +## Input Contract + +Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; and the boundary to write at (project or app root). An existing DESIGN.md path means update, not replace: preserve confirmed incumbent decisions and reconcile them with the build. + +## Workflow + +1. Read `reference/document.md` in full; it is the operating spec for DESIGN.md's format, token schema, sidecar, and section order. Follow it exactly. +2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence. +3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system. +4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear. + +## Output Contract + +Return: the file paths written, a five-line summary of the recorded system (palette strategy, type ramp shape, named rules), and one line naming anything in the build you deliberately did not canonize and why. No other prose. diff --git a/plugin/agents/impeccable-finish-reviewer.md b/plugin/agents/impeccable-finish-reviewer.md index e4aa15c3a..540d2435e 100644 --- a/plugin/agents/impeccable-finish-reviewer.md +++ b/plugin/agents/impeccable-finish-reviewer.md @@ -1,6 +1,6 @@ --- name: impeccable-finish-reviewer -description: Reviews a finished Impeccable build against its direction contract, persistence requirements, and the chosen world's quality bar, returning an ordered list of material fixes. +description: Reviews a finished Impeccable build against its direction contract, the approved comp, and the chosen world's quality bar, returning an ordered list of material fixes. tools: Read, Bash, Glob, Grep model: inherit effort: high @@ -10,19 +10,22 @@ maxTurns: 12 You are the finishing reviewer for an Impeccable build: fresh eyes on a done artifact, outside the build thread's attention gravity. You do not edit anything; the parent agent applies your fixes. +You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable. + ## Input Contract -Expect: the original request; the confirmed user answers; the artifact path(s); the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md and DESIGN.md paths; existing hook or detector findings; the chosen world's QUALITY BAR card paths and approved comp paths when they exist; screenshot path(s) when available. When the harness can view images, open the card, the comp, and the screenshot before judging. +Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card before judging. ## Checks, in order -1. **Persistence.** On a new or replacement world: PRODUCT.md and DESIGN.md exist, and DESIGN.md matches the built world. A missing or mismatched file is the first material fix, ahead of any craft point. -2. **Ceiling.** Against the QUALITY BAR card and the approved comp, name the world's native devices the build left unused: frame, depth, lettering treatment, ornament density, motion. Compare commitment and finish, never composition; the card is a bar, not a layout. -3. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport: what would a visitor describe an hour later, and is it the thesis or a mood? -4. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. +1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. +2. **Fidelity.** Against the approved comp: topology, reading order, focal scale, overlaps and z-order, density, signature geometry. Name every drift and classify it intentional or defect. The comp governs composition; it is not a pixel spec for semantics, accessibility, or responsive behavior. +3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition. +4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport. +5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one. Do not run a second detector pass; mechanical findings belong to the parent's hooks. ## Output Contract -Return exactly four sections: `persistence` (pass/fail with specifics), `ceiling` (the unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). No praise, no summary prose. +Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (drift list with intentional/defect per item, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose. diff --git a/plugin/skills/impeccable/reference/new-work.md b/plugin/skills/impeccable/reference/new-work.md index 77bf971c4..d397a6635 100644 --- a/plugin/skills/impeccable/reference/new-work.md +++ b/plugin/skills/impeccable/reference/new-work.md @@ -68,9 +68,7 @@ Your measured rendition prior: warm, bookish, family, and child-facing subjects Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract. -When a new or replacement world is chosen, DESIGN.md is part of recording the decision, not an aftercare step: write it at the appropriate project or app boundary using [document.md](document.md) before the first build edit lands, in the same working stretch as the direction contract. Record only durable system rules; exact tokens may remain provisional until the first build establishes them, and you update the file when the build settles them. A new world shipped with no DESIGN.md is an incomplete run, exactly as a missing PRODUCT.md is; the finishing review checks the file exists and matches the built world. An ordinary extension does not rewrite DESIGN.md. - -Two observed ways a DESIGN.md rule goes wrong: a prohibition that bans a device the world itself uses natively (arcade lettering lives on its offset shadow), and a token added so a hook finding stops firing. Check every prohibition against the world's own materials; a value earns its place by the world and by legibility, never by silencing a check. +On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md. If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it: @@ -100,6 +98,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi ## 7. Inspect and finish -Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build. +Inspect desktop and mobile, critique the render against the user's request and the direction contract, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. -Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector. +Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes, promise by promise against the contract. Do not run a second detector. + +Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention. A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded. diff --git a/plugin/skills/impeccable/reference/visualize.md b/plugin/skills/impeccable/reference/visualize.md index cfb6ea399..5c7adc2fd 100644 --- a/plugin/skills/impeccable/reference/visualize.md +++ b/plugin/skills/impeccable/reference/visualize.md @@ -6,7 +6,7 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo ## Generate three compositional options -Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. +Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. - When the user shortlisted multiple concepts, spread the three across them. - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing. @@ -25,7 +25,7 @@ After approval, summarize the composition and the parts of the comp that must no ## Inventory implementation fidelity -Before building, inventory the approved comp's major visible ingredients and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. +Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped. Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery. diff --git a/plugin/skills/impeccable/scripts/concept-seed.mjs b/plugin/skills/impeccable/scripts/concept-seed.mjs index f4c12d4bb..2f9e16af3 100644 --- a/plugin/skills/impeccable/scripts/concept-seed.mjs +++ b/plugin/skills/impeccable/scripts/concept-seed.mjs @@ -458,7 +458,9 @@ ASSIGNED INDEX: ${buildIndex} The assignment exists to refuse the model's ranking rut, never to outrank the user or the brief. Never expose assignment metadata in user-facing labels. No challengers this run: the roll service was unreachable and no local -catalog exists. A sandboxed shell without network egress is the most common +catalog exists. A sandboxed exec tool with no network access causes exactly +this; before accepting degradation, rerun this command once through the +harness's network-enabled command tool. A sandboxed shell without network egress is the most common cause: if this harness can rerun the command with network access granted, do that once before proceeding. Otherwise proceed with the grounded candidates alone; the assignment