[DESIGN] Work review — session changeset + verify flow (unblocks #41 #44)

[farmhutsoftwareteam]

Why this matters

"What did the agent change, and can I trust it?" gets two engineering answers (session changeset #41, verify-this #44) that must feel like ONE surface: review the work, then press verify on it. Without a design, the changeset risks becoming a bare file list and the verdict a wall of text.

The user

"Munya, back after a 20-minute run" — opens the session's Changes surface: 7 files, +214/−90, one flagged clay because it's outside the project. He skims two diffs, hits Verify, watches a fresh read-only reviewer run, and gets a verdict card: one serious finding on cursor.ts. Fixes, re-verifies, sees the pass state, commits.

What exists today (design system)

• Agent vocabulary.dc.html — the git section: status-letter valence, ± counts, EDIT diff hunk with done-bg/need-bg lines; the verdict table (safe/watch).
• Atelier project home.dc.html — the Changes tab layout (file list left, diff right) whose rhythm this surface should echo at session scope.
• Subagent delegation design (sibling issue) — the running-reviewer presentation should reuse the delegation card's running state.
• Eng grounding: entries = path token + op badge + ± counts; out-of-tree files flagged clay and listed first; verify runs a FRESH read-only reviewer badged "fresh reviewer · read-only"; verdict = per-finding file token + severity + one-liner; truncation is stated honestly ([VERIFY] Session changeset — every agent edit rolled into one reviewable diff #41, [VERIFY] Verify-this button — fresh read-only reviewer against the changeset #44).

Deliverable

Work review.dc.html in the design project — the session changeset surface + the verify flow's three states, light + dark, try-it controls.

Paste-ready brief for the designer agent

DESIGN BRIEF — "Work review.dc.html" (Atelier design system project)

WHAT IT IS
The trust surface for a session's work: a CHANGESET (every file the agent
edited this session, with diffs) plus VERIFY — one button that runs a fresh
read-only reviewer against that changeset and renders a verdict. Companion
to Agent vocabulary.dc.html's git section, at session scope.

CONVENTIONS
Same system: tokens, valence (--done/--need + soft bgs), IBM Plex Mono +
Helvetica Neue, 1180 canvas, light + dark themeVars, hubflo-workflow content.

ANATOMY — CHANGESET
- Header strip: "Changes this session" + rollup "7 files · +214 −90" +
  the VERIFY button (primary chip, ink border).
- File list (left, ~300px, echo project home's Changes tab):
  · row = op letter with valence (M --done / A --done / D --need) + path as
    token chip + ±counts
  · OUT-OF-TREE row pinned first: clay path token + "outside project" tag —
    the row that must be impossible to miss
  · untracked-new row: "A" + full-content-as-additions hint
- Diff pane (right): reuse the EDIT hunk language exactly (hunk header
  --faint, del rows need-bg, add rows done-bg).
- Empty state: "No files changed this session." quiet, dovetail mark.

ANATOMY — VERIFY FLOW (three states)
1. RUNNING: a slim card under the header — "fresh reviewer · read-only"
  badge, spinner + elapsed, cancel ×; visually kin to the delegation card's
  running state (Subagent delegation.dc.html).
2. VERDICT — FINDINGS: card listing findings, each: severity square
  (--need serious / --mute minor) + file token + one-line issue; header
  "2 findings · reviewed 7 files"; a footnote line when diffs were truncated
  ("3 files truncated for review — findings may be incomplete").
3. VERDICT — PASS: an explicit pass state (--done ✓ "no findings · reviewed
  7 files · fresh context"), not an empty box. Re-run affordance.

DEMO CONTROLS
Buttons: changeset / changeset-with-outside-file / empty / verifying /
verdict-findings / verdict-pass. Theme toggle.

NAME IT: Work review.dc.html

Out of scope

• Commit/staging UI (project home's Changes tab owns it).
• Multi-reviewer vote panels (v2 of verify).
• Per-turn grouping visuals.

Dependencies

• Unblocks: [VERIFY] Session changeset — every agent edit rolled into one reviewable diff #41, [VERIFY] Verify-this button — fresh read-only reviewer against the changeset #44.
• Pairs with: Subagent delegation design (running-reviewer card kinship).