Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / design-context-and-critique

Design context and critique artifacts

Impeccable keeps product truth, visual rules, surface intent, creative choices, standing taste, and review evidence in separate records. The native context runtime resolves these records for a project or workspace, serves them to workflows, persists decision and review state, and warns when they may no longer describe the current work.

Context record boundaries

Each record answers a different question. This separation lets a workflow reuse durable truth without treating a route-specific choice or an old review as a new product rule.

RecordPurposeReuse by workflows
PRODUCT.mdProduct purpose, users, constraints, platform, and commitmentsProject setup and every task that must preserve product truth
DESIGN.mdDurable visual language and system rulesNew surfaces, extensions, live editing, and design-system views
.impeccable/design.jsonStructured design-system data that supports rendered viewsLive design-system panels and component examples
Surface briefStrategy for one route, file, or artifactTargeted work on that surface
Direction contractThe selected surface idea and its finish promiseBuilding and finish review
Critique snapshotArchived review evidence and an open improvement backlogPolish and later review work

PRODUCT.md remains the product authority. DESIGN.md remains the visual authority when it exists, while a coherent visual system in code can act as incumbent evidence until it is documented. A surface brief adds local intent; it does not copy global product or design rules.

References: skill/…/init.md• L1-3 skill/…/init.md• L43-58 skill/…/new-work.md• L1-16

Design system records

The design system record captures the visual language that should remain stable across surfaces. DESIGN.md explains the system for people, while the sidecar supports structured readers that need richer token, motion, shadow, breakpoint, and component data.

The sidecar extends DESIGN.md; it is not a second visual authority. The document workflow regenerates it from the built surface so later workflows can use the shipped system rather than an intended system that never reached the product. The native runtime checks its location, schema, and age, and doctor can report when the sidecar no longer agrees with the document.

When code already shows a coherent visual identity, a missing DESIGN.md is a documentation gap for an extension. A redesign can replace that identity only when the user asks for a new visual world.

References: skill/…/document.md• L1-3 skill/…/document.md• L43-78 skill/…/new-work.md• L7-16 crates/…/staleness.rs• L229-288 crates/…/doctor.rs• L96-104

Design maps and detail lookup

Large design records need a short form so context directives leave room for workflow instructions. The runtime carries a bounded design map with the main guardrails, scales, named files, and a pointer to the full record; it carries a short DESIGN.md whole.

design-compact is a human-approved conversion, not an automatic rewrite. It proposes a map first. With approval, it keeps the full record at .impeccable/design-full.md and changes DESIGN.md into a map that points to it. design-lookup then retrieves a bounded set of matching tokens, components, named token-file values, or full-record sections without making the workflow read every design file.

This keeps the design system usable at two levels: the context directive gives the agent the rules it needs to stay in the visual world, while lookup provides exact detail when a build needs a token or a rule that the map does not include. doctor reports long DESIGN.md files as sprawl and directs the person to review the proposed conversion.

References: crates/…/design_map.rs• L10-16 crates/…/design_compact.rs• L1-26 crates/…/design_compact.rs• L83-113 crates/…/design_lookup.rs• L1-31 crates/…/design_lookup.rs• L236-323 crates/…/context_cli.rs• L1003-1025 crates/…/doctor.rs• L96-100

Concept and composition records

Concepts and compositions provide controlled options for open design work. A concept supplies a visual world and its system grammar. A composition supplies structure for attention, sequence, hierarchy, or interaction without replacing the chosen world.

The seed workflow filters these options by the work's scope, visitor mode, scale, and platform. It only treats reviewed entries as usable, and it carries review state with the selected options. A decision page then presents the dealt options, records the user's choice, and passes the selected direction or composition to the next workflow.

Mode rules travel with a roll when a mode is selected. They give the decision round the directions and composition rules for persuade, operate, read, or experience; experience uses the persuade guidance. If the matching reference is missing or incomplete, the roll continues but tells the workflow to read that guidance before it writes or judges the surface.

Concept rolls create a local seed reference. A seed reference lets a later page or workflow recover the roll behind a committed decision without putting the raw seed key in project files. The local runtime ledger keeps the reference usable on that machine and records choice data only when telemetry is enabled.

SignalMeaning
World conceptA visual identity and its reusable rules
CompositionA structure for content, attention, or interaction
Modepersuade, operate, read, or experience
GrainProduct, flow, view, or region scale
PlatformWeb, iOS, Android, or adaptive work
Review hashProof that approval still matches the entry

Changing the content covered by a review changes its hash. The old review then stops being current instead of silently approving changed material.

References: crates/…/catalog.rs• L12-18 crates/…/catalog.rs• L172-184 crates/…/catalog.rs• L346-373 crates/…/concept_seed.rs• L24-67 crates/…/concept_seed.rs• L501-536 crates/…/telemetry.rs• L162-211 crates/…/telemetry.rs• L397-438 crates/…/serve_question.rs• L394-445

Palette and type assets

Palette guidance turns a seed color into a usable color strategy for the product and surface. The seed supplies a hue, mood, and example direction; the workflow still chooses the full role set from product truth, surface mode, and visual context.

This keeps a color seed from becoming a fixed four-color answer. The same seed can support different light levels, materials, and product needs while the surface still receives a complete and purposeful palette.

Typography is treated as a usable project asset when a workflow needs a sourced face. The native font command can fetch the requested Google font weights and styles into a project-local directory, then prints the rules that connect the local files to the stylesheet.

References: crates/…/palette.rs• L82-127 skill/…/new-work.md• L63-69 crates/…/font_fetch.rs• L1-25 crates/…/font_fetch.rs• L156-212

Personal taste guidance

Personal taste guidance is an optional set of standing design preferences from the person's Impeccable account. The native context runtime adds it to context output when a recent local cache is ready and belongs to the configured account.

Taste is guidance, not project authority. PRODUCT.md and DESIGN.md win when they disagree. The runtime accepts only safe, short preference rules and places them before the project records so workflows can apply them while still seeing the stronger project context.

References: crates/…/taste.rs• L7-95 crates/…/context_cli.rs• L1093-1107

Surface brief identity

The surface brief stores strategy that belongs to one concrete target. It keeps the audience, job, action or task, proof or content, constraints, chosen direction, memorable moment, and unresolved decisions available across sessions without duplicating global context.

The runtime normalizes target identity before it reads or writes a brief. Project files use project-relative paths. Routes become route: identities. URLs lose query strings and fragments. The resulting stable slug gives a target a durable history, while related targets can share one primary brief.

The command interface supports four uses of this identity: find a path, list briefs, read a selected brief, or write a brief with related targets. A target must resolve to one brief before context can serve its strategy. If several briefs match, the runtime returns candidates and requires a concrete target instead of choosing a strategy by guess. Older long-slug briefs remain usable only when their metadata proves the target match.

Writing a brief also marks local surface captures as runtime output. This keeps generated work products out of source control while leaving the brief itself available as shared strategy.

References: crates/…/surface_briefs.rs• L11-89 crates/…/surface_briefs.rs• L239-307 crates/…/surface_briefs.rs• L318-351 crates/…/surface_brief_cli.rs• L20-88 crates/…/target_slug.rs• L7-16

Pinned decisions

Pinned decisions preserve a choice that the user or the surface brief has already settled. A later round may explore unfinished parts of the work, but it must not reopen a pinned world, composition, or direction as if no decision existed.

The direction contract records the selected idea before implementation. It gives the build and finish review a shared target through its thesis, own-world, visitor story, first viewport, form, and finish condition. A local extension inherits the surrounding world and composition instead of starting a new identity exercise.

Pinned workflow shortcuts also preserve access to a chosen command across supported agent harnesses. The native pin command uses command metadata to create a marked shortcut in each detected harness. Unpin removes only marked shortcuts, so an existing user-owned command is not overwritten or deleted.

The native runtime resolves its provider at run time. It can use an explicit skill directory or locate the skill near the executable, then derives the provider identity, command prefix, and self-command form used in workflow directives. This keeps the same context records and commands usable across harnesses.

References: skill/…/new-work.md• L29-41 skill/…/new-work.md• L75-89 crates/…/serve_question.rs• L191-234 crates/…/pin.rs• L62-87 crates/…/pin.rs• L90-117 crates/…/pin.rs• L200-211 crates/…/provider.rs• L8-19 crates/…/provider.rs• L94-130

Image and decision provenance

Generated compositions are tied to the decision hand that declares their slots. The native image command marks a written image as generated for the active hand, so the wait and review flow can distinguish current work from an older file.

The command can create a new image or edit one with local or remote reference images. It records a prompt sidecar with the prompt, model, background choice, and references. Remote references must be real PNG, WebP, or JPEG data within the request limit; a failed reference stops generation without writing an output. A fake mode supports local synthetic output without an API call.

Decision-page state also records the files that existed before a hand began. A new hand has its own identity, slot list, and generated markers. The wait flow keeps showing missing prompt sidecars, stale compositions, and stale sketches as pending work instead of treating an old file as the current decision.

Transparent and opaque background choices apply to PNG output. This preserves the visual asset's intended use while keeping the generation details available for later critique.

References: crates/…/generate_image.rs• L239-310 crates/…/generate_image.rs• L320-384 crates/…/generate_image.rs• L386-549 crates/…/generate_image.rs• L552-560 crates/…/serve_question.rs• L798-829 crates/…/serve_question.rs• L920-951 crates/…/serve_question.rs• L1033-1111 crates/…/serve_question.rs• L1165-1189

Critique storage

Critique combines human design judgment with mechanical and browser evidence, then presents the report as the immediate user deliverable. The stored snapshot is an archive of that run, not a replacement for the current surface or its brief.

Snapshots are grouped by a stable target slug and also carry a target identity. Local file targets carry a content fingerprint. When the target changes, the latest snapshot is marked closed or rejected for reuse rather than being presented as current. URLs use their normalized identity because a local file fingerprint is not available.

The storage service writes time-stamped history without replacing an earlier snapshot when two reports share a timestamp. The latest and trend views use target identity and legacy compatibility rules. The close operation requires the resolved target to own the snapshot. These checks prevent a short slug or an old long-target name from exposing another surface's review.

Critique metadata is written as safe frontmatter. Values that contain line breaks are quoted as one serialized value. This keeps report headers readable by the storage reader and prevents multi-line metadata from changing the meaning of later fields.

The same report store can save project or surface audit output under .impeccable/audit/. Audit history is write-only for this runtime; critique lookup remains the path that supplies an open review backlog to polish.

Component review adds a focused, opt-in form of critique for a captured composition or first viewport. It lets a reviewer inspect each listed component against its reference, approve it, request changes with feedback, or mark a missing item. The native review session keeps the captured files and review packets tied to a revision, so later rounds can carry valid approvals while reopening changed components. Related instances can share a review while still allowing a separate check when one instance needs different attention. This focused review does not replace the build-phase gates.

The review page serves the current or historical packet and its pinned files. A submitted round is immutable for later inspection. A newer capture makes an older unsubmitted page out of date, while source or capture changes prevent an approval from being treated as current. In unattended or headless sessions, the review stays pending rather than becoming approval without a reviewer.

Critique snapshots are local runtime output by default. Project report settings can disable saved reports or explicitly make reports committable. The storage command preserves a small hand-edited exception for shared ignore guidance, while target identity and fingerprint checks protect history from being reused for the wrong surface.

The polish workflow can use a matching open critique as its fix backlog. Other workflows may use a critique as evidence or a staleness signal, but they must preserve the snapshot's target scope and must not treat old findings as permission to redesign.

References: skill/…/critique.md• L1-30 skill/…/critique.md• L102-106 crates/…/critique_storage.rs• L34-60 crates/…/critique_storage.rs• L182-237 crates/…/critique_storage.rs• L274-347 crates/…/critique_storage.rs• L457-607 crates/…/critique_storage.rs• L656-675 crates/…/critique_storage.rs• L678-865 crates/…/mod.rs• L45-175 crates/…/server.rs• L52-80 crates/…/server.rs• L91-124 skill/…/polish.md• L20-35

Context runtime

The native context runtime is the shared resolver and storage service for these artifacts. It identifies the active project, loads product and design records, selects a surface brief, detects a visual implementation, and emits a context directive that downstream workflows can consume.

It supports ordinary projects and monorepos. A monorepo can expose child targets with their own records, inherited root records, fallback records, or missing records. Target selection favors workspaces with a UI signal, while an explicit target can cross into its own project boundary without borrowing context from the caller. If the runtime cannot select one target safely, it returns a selection request instead of mixing context from sibling apps.

The runtime resolves the installed skill and provider at run time. It can use an explicit skill directory or locate the skill from the executable, then derives the harness identity and the command form for printed workflow instructions. It uses that same identity to load platform references and SKILL.md. Large documents and candidate lists are compacted to keep directives visible; the compact form tells the agent to read the source file instead of hiding the record.

The local question service persists decision-page state, roll records, answers, build-path choices, and short-lived session state so a workflow can continue after a page reload or a detached server restart. A roll binds one fresh concept hand to the next decision page. Each hand records its declared compositions and sketches plus the files that existed before the hand, so an older asset cannot masquerade as the current choice. Generated assets are tied to that hand, and stale sketches, compositions, or missing prompt sidecars remain visible as pending work.

Seed references use a local ledger to resolve a committed reference back to the key that made the roll. The ledger always keeps the key needed for local resolution. When telemetry is enabled, it also records API-dealt rounds and coordinates the decision page and agent so one choice is not sent twice. Telemetry opt-out keeps the roll feature active but tells the service not to record the roll and sends no choice report.

Runtime question, capture, and critique data is kept out of source control when possible. If a repository already tracks local runtime files, the runtime reports that fact and uses a local fallback for future roll state instead of assuming that a later ignore rule removed the exposure.

The native runtime uses one shared network path for roll, image, and design asset requests. It combines the machine certificate store with bundled roots and honors HTTP, HTTPS, SOCKS, and NO_PROXY settings. Localhost live-mode HTTP remains direct.

The command line exposes the same runtime through the native impeccable binary. The main context verbs are:

  • context resolves and prints the active context and workflow directives.
  • surface-brief path|list|read|write manages surface intent by target.
  • critique-storage slug|write|latest|trend|close manages review history.
  • audit-storage slug|write stores project or surface audit output.
  • design-compact proposes or applies a human-approved short design map.
  • design-lookup retrieves design detail by term without reading a whole record.
  • font-fetch brings a selected web font into the project as a local asset.
  • concept-seed supplies reviewed creative options and records the roll needed for a decision.
  • palette supplies a repeatable or new color seed.
  • doctor reports wider drift and can apply mechanical repairs.
  • Component review commands plan, prepare, capture, serve, verify, and inspect focused review sessions for captured work.

The native review server serves the review page, packet, pinned files, and same-origin decision endpoint from a short-lived local session. It exposes historical packets as read-only evidence and removes its service record when the session ends. A hosted human-review path can take ownership of capture and decisions when the environment provides it.

Hook wiring is part of the runtime contract. Supported harnesses use generated launcher entries for post-edit checks and, where supported, a stop-time deep pass. The runtime recognizes both legacy script entries and current launcher entries for repair, but counts coverage only when the active launcher or provider plugin is present and enabled. Stale script entries, missing launchers, disabled hooks, and unsupported detector paths fall back to an explicit manual-detector directive. Cursor's retired pre-edit gate can be migrated to the post-edit hook.

This diagram shows how a workflow moves from a target to resolved context and then to stored or served design evidence.

flowchart LR
    T[Target or workspace] --> R[Context resolver]
    R --> P[Product and design records]
    R --> B[Surface brief selection]
    R --> D[Workflow directive]
    D --> W[Design or live workflow]
    W --> Q[Decision page or component review]
    Q --> C[Critique report]
    C --> S[Critique snapshot]
    S --> F[Later polish and review]
    R --> G[Staleness findings]
    G --> D

References: crates/…/lib.rs• L1-65 crates/…/context_cli.rs• L15-20 crates/…/context_cli.rs• L485-570 crates/…/context_cli.rs• L851-999 crates/…/context_cli.rs• L1003-1163 crates/…/provider.rs• L94-130 crates/…/hook_markers.rs• L63-121 crates/…/hook_wiring.rs• L85-123 crates/…/http.rs• L36-85 crates/…/serve_question.rs• L447-581 crates/…/serve_question.rs• L1274-1591 crates/…/telemetry.rs• L162-224 crates/…/mod.rs• L45-175 crates/…/server.rs• L14-19 crates/…/server.rs• L91-124 crates/…/main.rs• L52-70

Workflow reuse

Workflows combine records by scope. Product truth constrains the work. The design system constrains durable visual expression. The brief narrows the target. The direction contract makes the chosen idea auditable. Personal taste can guide choices when it does not conflict with those records. Critique then supplies evidence for refinement without silently changing those authorities.

Live editing resolves the same product and design context for its session and serves design-system data through its protected design-system endpoints. New-work reads the brief before building. Decision pages capture a selected direction, composition, sketch, or build path. Image generation records the provenance needed by those decision pages. Component review captures focused approval and repair feedback. Critique writes evidence after assessment. Polish reads only the matching open backlog. See agent design workflows, agent hook workflow, live editing sessions, skill commands and references, and AI provider integration.

References: skill/…/new-work.md• L1-3 skill/…/new-work.md• L75-93 skill/…/critique.md• L18-30 skill/…/polish.md• L20-35 crates/…/serve_question.rs• L191-234 crates/…/server.rs• L149-231 crates/…/server_state.rs• L1653-1696 crates/…/live_server.rs• L782-824

Staleness signals

Staleness checks warn when Impeccable's records may no longer agree with the project. Boot checks stay bounded and best effort. The deeper doctor pass adds repository drift, design coverage, design map sprawl, detector ignores, hook state, retired live state, spent build artifacts, and workspace checks.

The runtime groups findings into one directive. Mechanical migrations can wait for doctor --fix, which applies only findings marked safe to repair. User-facing findings are throttled per project. A user can disable the check with IMPECCABLE_NO_STALENESS_CHECK=1 or stalenessCheck: false in project configuration.

Hook coverage is part of the signal. The runtime recognizes old script-form entries for diagnosis and cleanup, but only a current launcher-form design hook counts as automatic coverage. Hermes coverage depends on its global plugin being present and enabled. A Cursor pre-edit gate is reported for migration to the post-edit hook. A missing launcher or script, or a disabled project hook, means edits can go unscanned even when a manifest exists.

Important signals include:

  • An old or misplaced design sidecar can disagree with DESIGN.md, or its schema can no longer match the current record.
  • A long DESIGN.md can consume the context budget and need a reviewed map conversion.
  • A named design token file can be deleted, or its colors can drift from the declared palette.
  • A brief can remain attached to a deleted file.
  • A changed concept can keep an approval whose hash no longer matches.
  • A missing build-path choice can make visual rounds use an unchosen default.
  • A project-root pattern can match no workspace and make the repository root appear active.
  • Native project evidence can conflict with a web platform declaration.
  • Design code can change long enough after DESIGN.md that the document needs review.
  • DESIGN.md can lack the sections that give new screens normative guidance.
  • A detector ignore can name a removed rule or file and silently stop covering the intended target.
  • A design hook can point to a missing launcher or be disabled by project configuration, leaving edits unscanned.
  • Retired live-session state or spent build captures can remain after the active workflow has moved on.
  • A component review can become stale when its packet revision, source files, measured inventory, or native capture no longer matches the submitted decision.
  • A historical review can remain useful as evidence while its current source or capture is no longer safe to reuse.
  • A decision hand can become stale when its composition or sketch slot still contains bytes from an earlier hand.
  • A landed decision composition can lack its prompt sidecar, so the review cannot recover the exact generation instruction.
  • Tracked runtime files can expose local seed keys, dealt hands, or choices even when a later .gitignore exists.
  • A Hermes plugin can be installed but disabled or unreadable, so the design hook is not active.
  • A remote image reference can be unavailable or not be an image, so generation must stop instead of producing unsupported evidence.

The doctor report also shows workspace product and design status. It can identify inherited product context that may not describe every child app, and it can stamp an unversioned product record or repair other safe migrations without deciding user-owned changes.

References: crates/…/staleness.rs• L61-68 crates/…/staleness.rs• L229-288 crates/…/staleness.rs• L375-461 crates/…/staleness_deep.rs• L59-178 crates/…/staleness_deep.rs• L193-247 crates/…/staleness_deep.rs• L301-416 crates/…/doctor.rs• L66-117 crates/…/doctor.rs• L126-190 crates/…/hook_markers.rs• L63-121 crates/…/hook_markers.rs• L182-265 crates/…/context_cli.rs• L133-179 crates/…/context_cli.rs• L485-503 crates/…/serve_question.rs• L1339-1388 crates/…/generate_image.rs• L277-310

Change checklist

When these files or sections are changed, remember to consider these:

  • If target normalization or slug rules change, check surface-brief lookup, critique identity, legacy compatibility, and related-target mapping together.
  • If DESIGN.md or sidecar ownership changes, update document generation, design-map creation, lookup sources, live design-system readers, and sidecar staleness checks together.
  • If the design map budget or archive path changes, keep context output, design-compact, design-lookup, and the sprawl finding aligned.
  • If concept or composition content changes, update the review hash inputs and approval validation so old reviews cannot pass as current.
  • If mode guidance changes, keep mode selection, emitted roll instructions, fallback behavior, and the next decision page aligned.
  • If brief selection changes, keep monorepo target selection and orphan checks aligned with the same target identity.
  • If critique or audit metadata, frontmatter serialization, or fingerprint rules change, preserve exact-target matching, collision-safe history, close behavior, safe parsing, and report settings.
  • If native context resolution changes, check the CLI directive, provider reference lookup, live session context, and workspace inheritance behavior together.
  • If provider or hook discovery changes, keep printed commands, runtime reference lookup, automatic coverage, manifest migration, and doctor findings aligned.
  • If font asset handling changes, keep the fetched file paths, generated font rules, project confinement, and design-system typography records aligned.
  • If taste cache validation or insertion changes, keep account issuer checks, preference precedence, cache freshness, and context output ordering aligned.
  • If seed references or roll records change, keep committed references, local resolution, choice reporting, concurrency, pruning, and telemetry opt-out behavior aligned.
  • If image generation or decision-slot rules change, keep remote reference validation, prompt sidecars, generated markers, hand provenance, and wait behavior aligned.
  • If component review packet or capture rules change, keep source fingerprints, native capture proof, carried approvals, historical packets, hosted-review ownership, and verification gates aligned.
  • If the decision-page payload changes, keep roll ownership, build-path meaning, generated comparison files, answer output, and restart state aligned.
  • If the local review server changes, keep same-origin writes, packet revision checks, pinned-file confinement, integrity checks, and service cleanup aligned.
  • If hook recognition changes, keep legacy cleanup, launcher coverage, Cursor post-edit migration, user-scope manifests, Hermes plugin checks, and missing-launcher checks aligned.
  • If shared HTTP behavior changes, keep certificate fallback, proxy selection, redirect limits, and direct localhost behavior aligned for rolls, image references, and font downloads.
  • If command metadata or pin behavior changes, keep the embedded metadata, installed skill metadata, harness shortcut format, marker-safe cleanup, and provider-specific command spelling aligned.

Important failure modes

TriggerConsequenceGuard
A monorepo invocation has no unique targetContext from the wrong child app can guide the workSelect the child or rerun with an explicit target
DESIGN.md changes after its sidecarLive design views can show old structured valuesRegenerate the sidecar with document
A long design record is compacted without the person's agreementThe visible design authority changes without an explicit choiceUse design-compact as a proposal first and keep the full record in its archive
A lookup is run after the map or archive path changesAn agent can miss the requested token or sectionKeep the map pointer and lookup source paths in sync
A concept changes after approvalIts review no longer describes the entryCompare the content hash and review again
A brief points to a deleted fileOld surface strategy remains attached to a missing targetRepoint or remove the brief
A critique target changes after a local reviewThe old backlog can describe a different surfaceUse the target identity and fingerprint before reuse
A stale or colliding critique slug is used without an explicit targetA review can be read or closed for the wrong surfaceUse the resolved target identity and require a matching fingerprint
Native evidence conflicts with PRODUCT.mdWeb guidance can load for an iOS, Android, or adaptive projectCorrect the platform record and load native guidance
A project-root pattern matches nothingThe repository root can be treated as the active projectFix the pattern before relying on inherited context
A hook manifest contains only a retired script path or points to a missing launcherUI edits can go unscanned while the project appears coveredReinstall or enable the design hook and check doctor findings
Hermes lacks its plugin files or enabled configurationEdits can go unscanned while Hermes appears installedEnable the global plugin and check the manual detector directive
A Cursor hook remains on preToolUseThe retired write gate can block the current post-edit flowMigrate it with doctor --fix, hooks on, or the next update
A review packet or source changes after a decisionThe page can show a decision that no longer matches the workPrepare a new revision and review the changed scope
A native capture is missing, corrupt, or not covered by proofAn approval can look complete without trustworthy visual evidenceRe-capture and verify the pinned bytes and full component coverage
A review runs without a human or exceeds the request boundThe review can remain unresolved or accept unsafe inputKeep it pending in headless mode and require bounded, same-origin requests
A decision roll is consumed by the wrong page or expiresThe page can claim a direction that is not tied to the dealt optionsBind fresh rolls to one decision page and keep the local record short-lived
A decision hand reuses an old composition or sketch fileThe page can present stale artwork as the current roundRewrite the slot after serving the hand and let the runtime verify its provenance
A landed composition has no prompt sidecarLater review cannot recover the instruction that made the imageWrite the sidecar before the user decides
A remote reference is missing, too large, or returns non-image contentNo trustworthy edited comparison is producedValidate the response bytes before sending the generation request
Runtime files are already tracked by gitSeed keys, dealt hands, or choices can be publishedRemove them from the index and let the runtime use its local fallback
A taste cache is stale, malformed, or tied to another account URLStanding preferences are silently omitted from contextRefresh the account cache and keep project records as the authority
A report has unquoted line breaks in its metadataLater frontmatter fields can be read as part of the metadata valueSerialize multi-line values as one quoted value before saving
Reports are disabled in project settingsA workflow has no saved critique or audit historyRead the explicit REPORTS OFF result and keep the report in the current workflow
A requested font is not available or its output path leaves the projectTypography setup can fail or write outside the intended projectUse a valid family and keep output inside a project-relative directory
Command metadata is stale or a pinned shortcut uses the wrong harness formA shortcut can show the wrong help or fail to invoke the intended workflowLoad current metadata and use marker-guarded provider-specific pinning
The runtime cannot find the skill or self commandDirectives can omit usable reference paths or print a command the harness cannot runSet the skill, provider, and self-command inputs or run from a valid installed skill

Key files

FileWhy to read it
crates/…/context.rsDefines project, monorepo, product, design, and surface-brief resolution
crates/…/context_cli.rsDefines the context directive, provider-aware commands, design-map output, taste insertion, hook coverage, and bounded staleness notices
crates/…/design_map.rsDefines the short design map that keeps visual guardrails visible in context
crates/…/design_compact.rsDefines the person-approved conversion from a long design record to a map and archive
crates/…/design_lookup.rsDefines bounded detail lookup across design records, sidecar data, and named token files
crates/…/font_fetch.rsDefines the native path from a selected font family to local font files and stylesheet rules
crates/…/taste.rsDefines the optional account taste cache and its precedence-safe context block
crates/…/provider.rsDefines runtime skill, provider, platform-reference, and command resolution
crates/…/pin.rsDefines pinned command creation, provider-specific shortcut forms, and safe cleanup
crates/…/command-metadata.jsonDefines the descriptions and argument hints used by pinned workflow shortcuts
crates/…/hook_markers.rsDefines hook recognition, legacy compatibility, and Cursor migration rules
crates/…/hook_wiring.rsDefines current launcher manifests and the events that count as hook coverage
crates/…/http.rsDefines shared certificate, proxy, redirect, and local-network behavior
crates/…/surface_briefs.rsDefines target identity, brief storage, related targets, and selection
crates/…/surface_brief_cli.rsDefines the native surface-brief path, list, read, and write interface
crates/…/catalog.rsDefines reviewed concept data and stale-review protection
crates/…/concept_seed.rsConnects product context to creative rolls, mode guidance, and decision pages
crates/…/generate_image.rsDefines comparison image generation, reference validation, prompt sidecars, and hand markers
crates/…/critique_storage.rsDefines critique and audit snapshot identity, frontmatter safety, freshness, history, local output, and close behavior
crates/…/mod.rsDefines the focused review lifecycle, capture modes, headless behavior, and verification commands
crates/…/server.rsServes the focused review session and protects packet, file, and decision access
crates/…/serve_question.rsCoordinates decision-page state, roll binding, hand provenance, generated reference files, and freshness checks
crates/…/question_page.rsDefines the native decision-page shell used to present choices and collect answers
crates/…/staleness.rsDefines bounded boot checks for context artifacts and project selection
crates/…/staleness_deep.rsDefines doctor drift, design coverage, token drift, hook, live-state, spent-artifact, and workspace checks
crates/…/staleness_notice.rsDefines finding throttling, disable behavior, and workflow staleness directives
crates/…/doctor.rsDefines the full drift report and safe mechanical repair path
crates/…/lib.rsExposes the native context, design, font, review, and staleness verbs through one crate
crates/…/main.rsMaps native CLI verbs to the context runtime