[jayminwest]

Seed warren-a694 (plan pl-10db, step 15). Adds .github/workflows/ui-design-review.yml, which runs the ui-design-review evaluator on PRs that touch src/ui. It reports the result as a design-review check run on the PR head and as one sticky PR comment.

What it does

Job	Trigger	Token	Role
gate	pull_request_target	checks: write, PRs: read	Sets the first check on every PR head into main. A PR with no rendered src/ui change gets success ("Skipped: no src/ui changes") at once. Any other PR gets a queued "Waiting for ui-visual" check, so a required check never hangs.
prepare	workflow_run of UI visual, or dispatch	actions: read, checks: write	Trusts the artifact's PR number only when that PR's head is the run's head sha (the warren-70d9 pattern). Maps changed files to manifest pages and stages only the in-scope screenshots plus the src/ui diff. Sets the check to in_progress.
evaluate	needs prepare (mode == review)	contents: read only	anthropics/claude-code-action pinned to 6fed3ca (v1.0.245). The prompt is fixed and carries no PR text: page ids come from the manifest and the sha from the API. Allowed tools are Read(./**), Glob, Grep, Skill, Edit(./.design-review/verdict.json) and Bash(bun run scripts/design-review/verdict.ts:*). There are no web tools.
report	always, after prepare	checks: write, PRs: write	Re-validates the verdict in a fresh checkout against the head sha from the API. It fails closed on a missing or invalid verdict, sets the check, and upserts the comment with the auto-merge App token.

All logic lives in pure, unit-tested modules under scripts/design-review/ (scope, outcome, github, gate, prepare, report, usage). Every job runs only the default branch's code. Model text in the comment is escaped, with mentions, links, HTML and table breaks neutralized and credential-shaped strings redacted.

Cost guardrails are repo variables, all optional:

• DESIGN_REVIEW_MODEL (default claude-opus-5-5)
• DESIGN_REVIEW_MAX_TURNS (default 60)
• DESIGN_REVIEW_MAX_BUDGET_USD (default 5)

The evaluator also gets only the in-scope screenshots. It falls back to every page when a shared file changes or GitHub caps the file list.

Contract for warren-dbef

The contract is documented in docs/design/ui-design-review.md section 7 and in the workflow header.

• The check is named exactly design-review. Its source app is GitHub Actions, because it is created through the Checks API with the workflow's GITHUB_TOKEN.
• It is success only on a valid PASS or a skip.
• It is failure on FAIL, on an invalid or missing verdict, or when ui-visual failed.
• A finished check is never reopened: a re-run creates a new one.
• Manual re-run: gh workflow run ui-design-review.yml -f run_id=<ui-visual run id>.

Deviation

The sticky marker is <!-- design-review -->, from stickyMarker("design-review"). The seed text says <!-- ui-design-review -->.

Validation

• bun run check:all --bail: 12/12 gates green on the final head (via the pre-commit hook). 81 new tests in scripts/design-review/. actionlint is clean.
• End-to-end runs. These came from this branch, registered via a temporary push trigger that has since been removed. allow_closed=true was used because process(ui-visual): repro-first convention for UI bugs, worked example red->green for the outcomes histogram (warren-9fd7, warren-e9cd) #1357 is merged.
  • Run 37812610358, against process(ui-visual): repro-first convention for UI bugs, worked example red->green for the outcomes histogram (warren-9fd7, warren-e9cd) #1357's ui-visual run: the evaluator wrote no verdict, so the check failed closed with an explanatory comment, as designed. Cost $0.52, 35 turns, one permission denial.
  • Run 37813430942, the same input: PASS. Check run design-review success on bf5c594f. The comment on #1357 was updated in place and lists 2 pre-existing findings. Cost $0.54, 38 turns.
  • Run 37813812217, feat(ui-visual): human-only approval for golden baseline changes; auto-merge refuses without it (warren-4780) #1356's ui-visual run: mode=skip, check success "Skipped: no src/ui changes", and the evaluator was not run.
  • The prompt now says to write the verdict with the Write tool and to run the validator unchained. The first run's single denial was most likely a shell-redirect write.
• The gate job (pull_request_target) and the workflow_run trigger only run once this is on main. They are unit-tested.

Follow-ups

• warren-dbef: require design-review and pin its source to GitHub Actions.
• A PR whose pusher lacks write access is refused by claude-code-action and fails closed until a maintainer dispatches a re-run.
• Consider keeping the evaluator transcript, for example as a short-retention artifact. A failed review is currently opaque, because the action hides its output.
• The prepare job can crash before it outputs the PR number. In that case a queued check stays queued.