Ui evaluator

ui-evaluator

Evaluator contract: turn declarations into checks. Do not invent new taste standards. Every issue points back to a declaration.

Steps

1. Bind declarations

Identify which of these apply to this surface (repo files, prior turns, or design-playbook defaults):
spec · domain · craft · design · components · template.

When a verified .scratch/<run>/design-baseline/state.json binds a baseline (status: ready, path from baseline.path), include it as the project-specific visual declaration. It can support design-drift findings but is never L6 runtime proof by itself. An explicit status: waived disables baseline-drift checks for that run; it does not waive spec, accessibility, or craft checks.

When .scratch/<run>/reference/contract.md exists (ADR-0011), you may use it as supporting context for findings about copied brand chrome, distinctive illustration, or other Do not copy breaches (source = reference or the owning declaration). It is never L6 proof and never a Pass/Fail gate by itself.

Done when: the check set is named; if spec L6 exists, every criterion and its required proof are on the list.

2. Run checks

Walk every applicable row (exhaustive for bound declarations):

Check	Source
Empty / loading / error / permission	spec
Risk color, secrets, dangerous ops	domain
AI slop, hierarchy, purposeless motion	craft
New surface drifts from confirmed project visual roles/patterns	bound <binding.path>
Raw hex / px / ms (unlogged)	design
Badge/Tag, Dialog/Drawer, …	components
Shell matches scene	template
Each L6 acceptance item	spec
Required proof exists for each L6 item	spec

Dimension selection, 回流示例, the preview-seam health check (required when the run produced preview/ artifacts), and the observe* mirror-surface finding (required when any manifest capture notes surface: mirror): references/rubric.md.

When .scratch/<run>/craft-guard.md exists, consume all eight CRAFT-01 through CRAFT-08 rows as supporting craft input. Detector rows are advisory: verify their rendered/source evidence and exception checks, then use the authoritative recirculate map below to choose declaration source and assign severity. A detector never decides source, severity, or verdict. Carry every blocked row into evaluation as a craft proof gap. Implemented UI cannot claim complete craft Pass while required rendered or source proof is blocked; planning-only work may record an explicit N/A rationale without claiming rendered inspection. Keep craft detector rows out of the G6 manifest and L6 evidence ledger: they are craft-stage audit records, not runtime artifacts or criterion results.

Record an evidence ledger before writing findings. Every L6 criterion has exactly one row:

criterion: L6.<n>
required:  <declared proof>
observed:  <artifact path, interaction, check result, or missing>
result:    pass|fail|blocked|N/A

observed is either an artifact path (relative to the run root, e.g. evidence/L6.3-error.png) when a runtime capture was bound by a manifest, or free-text describing a manual observation. Both are legitimate; the machine seam (G6) only validates artifact-path references. When using an artifact path, keep the path as the leading token of the line (e.g. observed: evidence/L6.3-error.png); trailing commentary is tolerated by G6 — it reads the leading token, breaking on whitespace, ( / （, or , / ， / : / ：. Other punctuation (em dash, slashes, etc.) will be treated as part of the path, so put elaboration on a separate note: line for clarity when unsure.

Evidence is captured, not judged. A manifest entry records that an artifact was collected at a state — it does not say the criterion passed. pass/fail is this evaluator's verdict against required vs observed; a screenshot can prove a criterion false. Three ledgers, each one authority: spec L6 names what to prove; the manifest records what happened; this ledger decides what it means. Providers produce artifacts; the manifest binds them to criteria; the evaluator decides.

For implemented UI, visible-state proof is a rendered inspection at the declared target viewport; behavior proof is an interaction trace or automated check; code-health proof is the relevant available test, type/lint, or affected build result. Planning-only proof is declaration coverage and must not claim a render or test occurred. Non-L6 declaration checks may be supporting observations or findings; they do not enter the machine ledger.

Done when: every bound row was considered; every L6 criterion has exactly one non-empty criterion / required / observed / result row keyed as L6.<n>; results use only pass|fail|blocked|N/A; unavailable required proof is blocked, not skipped.

3. Emit point-back findings

issue:    <observable>
source:   <declaration>
fix:      <next edit>
severity: high (blocking)|high|med|low

Order: blocking first (broken L5/L6, unsafe dangerous ops, removed focus rings), then polish.

Done when: every finding has all four fields; no “generally improve the design” lines.

4. Verdict

• Emit exactly one ## Verdict section containing exactly one anchored verdict: Pass or Recirculate.
• Pass: zero blocking; every L6 criterion has exactly one evidence row; every required evidence row passes (every evidence result is pass); token gaps are logged or fixed.
• Recirculate: each blocking source names the step/declaration to reopen in design-playbook; fail or blocked evidence remains visible.

For a repaired blocker, record exactly one closure line whose issue text is identical to the finding:

- closes: <exact issue value> -> recirculate -> fix -> re-eval -> 0 blocking

Done when: the explicit verdict is structurally unique; blocking sources are non-empty; every blocking finding has exactly one matching closure before Pass. A blocking finding cannot be waived inside a Pass artifact. Without a user in the loop, blocking findings remain in recirculate and the run requests a decision; only after an explicit user decision that updates the owning declaration or severity — recorded against the user's statement or decision record — may the evaluator re-evaluate; the final Pass artifact contains no blocking severity.

The artifact shape behind this verdict is machine-checkable: scripts/validate_run.py gates L1-L6, ordered Given -> When -> Then in every top-level L6 item, one non-empty four-field evidence row per L6.<n>, allowed evidence results, all-pass evidence for Pass, four non-empty finding fields, one explicit verdict, and one exact issue-linked closure per blocking finding. These checks are the completion criteria above, not extra prose.

Recirculate map (authoritative)

Single source of truth for the observable -> declaration routing. The orchestrator and other skills point here; do not duplicate it.

Observable	Declaration
Happy path only; empty/fail/auth missing	spec
Wrong business meaning / risk / secrets	domain
AI slop, flat hierarchy, purposeless motion	craft
New UI visually conflicts with confirmed existing-product baseline	bound <binding.path>
Scattered hex/px/ms	design
Badge↔Tag, Dialog↔Drawer mixups	components
Wrong page shell (e.g. list as card wall)	template
Desktop app feels like a web page / wrong seam	native-craft
Copied third-party brand / Do not copy breach	reference (supporting) → fix in Fill / re-intake
Critique with no owner	re-run ui-evaluator

Fix only the owning layer, then resume from the pipeline step that consumes it.

Guard

Prefer positive fixes in fix. Reserve bans for non-negotiables (e.g. open dangerous action without confirm) and always pair with the required behavior.