# Review / ChangeSet Page UI **Status:** **FINAL TARGET BEHAVIOR + OWNER-APPROVED I1 U4/U5/U6 VISUAL AUTHORITY** **First realization:** I1. ## Page Job Let a human understand and act on an exact candidate change without leaving AWP: ```text What changed and from what base? Who/what produced it? What evidence exists? What did the reviewer find? Is this exact candidate ready to merge? If not, what must happen next? ``` ## Header ChangeSet identity/revision, Project/Plan/Task breadcrumbs, base -> candidate identity, publication/PR link, status and primary action appropriate to gate. ## Main Layout Desktop: ```text Changed files / diff Review & evidence ┌──────────────────────────────┬──────────────────────────────┐ │ file tree │ reviewer disposition │ │ diff viewer │ findings │ │ source context │ verification/check receipts │ │ │ provenance / Attempt │ └──────────────────────────────┴──────────────────────────────┘ MergeGate / next action summary ``` Evidence/review panel follows selected file/finding where useful but does not obscure exact candidate identity. U4 -> U5 -> U6 are the **same page identity** advanced through lifecycle states. They are not separate unrelated page designs. ## Findings Structured by severity/category/file/location/status. Clicking finding scrolls/highlights relevant diff. Reviewer rationale and whether blocking is policy-derived are visible. The approved U4 fixture contains a real blocking finding tied to exact diff location and a non-blocking recommendation. Merge is unavailable while the blocking finding remains. ## Verification Evidence Show expected/current evidence, passed/failed/stale/reused, provider/check link and exact source identity. I1 may be compact; I5 gains deeper why-ran/why-invalidated information. Evidence always binds to the exact candidate. A new candidate revision invalidates/re-evaluates prior Review/evidence according to policy. ## Changes Requested — U4 Primary action is `Start correction` or view active correction, not Merge. Owner-approved U4 shows: ```text exact base -> candidate identity changed-file tree real source diff blocking finding at a concrete location verification evidence producer provenance MergeGate: NOT READY one primary correction action ``` The page must explain that correction creates a new candidate requiring fresh gate evaluation where applicable. ## Ready to Merge — U5 A focused MergeGate summarizes: ```text candidate + base review approved required evidence/checks current publication fidelity verified required Approval/policy satisfied merge strategy/target ``` Then one clear `Merge` action with risk-appropriate confirmation. No competing giant buttons. The owner-approved U5 also makes the authority boundary explicit: ```text AgentRun cannot merge trusted control plane owns publication credential expected-head/TOCTOU recheck occurs immediately before mutation ``` ## Merged — U6 Read-only outcome shows: ```text resulting commit/merge identity target branch trusted merge authority time Task completion Goal/Plan advancement dependency re-evaluation newly READY next work Workspace cleanup eligibility ``` Release/Deployment are not implied by Merge; they activate later. ## States candidate collecting/publishing, reviewing, changes requested, verification failed/stale, ready-to-merge, merge conflict/stale base, merged, cancelled/superseded, provider degraded. ## Responsive / Accessibility Diff viewer supports keyboard file navigation and semantic line context. Small screens use file list -> diff -> review/evidence drill-in with sticky candidate/action summary, not side-by-side squeezed columns. Status/finding severity cannot rely on color alone. Exact candidate identity remains visible during navigation. ## URL Truth Stable ChangeSet/Review route; selected revision/file/finding encoded. Historical candidate revisions are read-only and clearly labeled. ## Increment Realization I1 U4 Review/ChangeSet, U5 ready-to-merge, U6 merged. I3 adds generic Approval context; I5 richer VerificationAuthority; I6 release links. ## High-Fidelity Requirements I1 requires realistic multi-file diff/evidence/review, changes-requested state, ready-to-merge and merged outcome. U4/U5/U6 are now owner-approved/final. ## Target State Review/ChangeSet is the exact-candidate inspection and trusted merge-gate surface. It binds diffs, producer/reviewer provenance and current evidence to one immutable candidate revision so review/verification can never silently slide onto changed code. ## Primary Users / Jobs - human reviewer/owner: understand candidate impact and decide protected merge where policy requires; - engineering lead: see independent review/evidence status and blockers; - developer/debugger: inspect findings and exact changed files, then follow correction work. ## Entry / Exit Points Entry: FactoryRun/Task ChangeSet link, Review queue, CI evidence, Attention/Approval, search or provider PR deep link. Exit: file/finding context, FactoryRun/Agent, correction Task/Agent, CIExecution, Approval, merged commit/Release or provider PR for secondary raw detail. ## User Journeys ### J1 — Review exact candidate ```text open ChangeSet -> confirm base + candidate + revision -> inspect changed files/diff -> inspect reviewer findings + current evidence -> navigate finding to exact location -> determine changes-requested vs ready-to-merge state ``` ### J2 — Correction loop ```text changes requested -> blocking findings visible -> Start/View correction -> correction AgentRun produces new ChangeSet revision -> old Review/evidence marked historical/stale where applicable -> new exact candidate receives fresh review/gate evaluation ``` ### J3 — Merge safely ```text Ready to merge -> review compact MergeGate brief -> confirm exact candidate/base/strategy/policy -> one Merge command -> immediate acknowledgement + trusted control-plane merge -> resulting merge identity recorded -> U6 read-only outcome + next Plan/Task action ``` ### J4 — Stale base/provider conflict ```text base/candidate/provider changes -> page marks gate stale/conflicted -> Merge disabled -> reconcile/rebase/correction path shown -> new exact candidate identity created/reverified ``` ## Data / Source of Truth ChangeSet revision/base/candidate identity and Review disposition are AWP domain truth. Diffs/source come from collected candidate content/VCS mapping. VerificationEvidence is authoritative only when admitted/current for this exact candidate. GitHub PR/check IDs are provider mappings; provider UI is not merge-gate truth. ## Actions / Authorization Reviewer disposition follows Review role/policy. Merge is executed only by trusted control-plane publication authority after MergeGate/Approval checks; AgentRuns never receive reusable merge credentials. Correction requests use Work/Factory application commands. Historical/superseded revisions are read-only. ## Async / Duplicate-Mutation Safety Merge/correction/retry actions use candidate revision + idempotency protection, acknowledge immediately and expose durable operation/result. Double-click cannot merge twice. If candidate/base/policy changed after render, stale command is rejected and the page refreshes the exact gate context. ## Invariants From Day 1 - every Review binds to one exact ChangeSet revision; - diff, findings and evidence always identify the same candidate; - new candidate revision invalidates/re-evaluates old evidence/Approval according to policy; - agents cannot publish/merge directly; - provider status cannot override AWP MergeGate authority; - historical candidate revisions are immutable/read-only; - U4/U5/U6 retain one page identity while lifecycle state changes. ## Current Implementation State Target behavior and U4/U5/U6 visual authority are final. Production implementation has not yet started. ## Deferred Realization I3 adds generic Approval context; I5 deep VerificationAuthority/invalidation explanations; I6 Release links. The exact-candidate Review/ChangeSet identity is final from I1. ## Temporary Dogfood Behavior I1 uses the approved focused two-pane diff/review/evidence implementation and may link to GitHub provider UI for deep logs. It must not treat the GitHub PR page as the AWP Review domain or skip trusted publication/fidelity checks. ## Related Contracts / Decisions - [`../domains/changes.md`](../domains/changes.md) - [`../domains/reviews.md`](../domains/reviews.md) - [`../domains/verification.md`](../domains/verification.md) - [`../workflows/task-to-merge.md`](../workflows/task-to-merge.md) - [`factory-run.md`](factory-run.md), [`ci.md`](ci.md), [`approval.md`](approval.md) ## Visual Mockup Authority Owner-approved final authorities: ```text U4 ../../mockups/i1/u4-review.html U5 ../../mockups/i1/u5-ready-to-merge.html U6 ../../mockups/i1/u6-completed.html CSS ../../mockups/i1/awp-i1-final.css JS ../../mockups/i1/awp-i1-final.js ``` U4/U5/U6 are **APPROVED / FINAL** as of 2026-08-20. No raw GitHub PR screenshot or exploratory diff frame substitutes for these AWP states. Material page relocation, candidate-authority change or MergeGate-semantic change requires an explicit design/spec amendment. ## Acceptance A user can verify the exact candidate and why it can/cannot merge without opening raw GitHub/CI provider pages, while direct provider links remain available.