# Reviews Domain

**Status:** Approved target-state baseline  
**First realization:** I1.

## Target State

`Review` records independent evaluation of an exact `ChangeSet` revision. Review is distinct from Approval and from code mutation.

```text
ChangeSet revision
  + existing VerificationEvidence
  -> reviewer (agent and/or human)
  -> Review findings + disposition
       approve | changes-requested | blocked/commentary
  -> correction creates new ChangeSet revision
  -> re-review
```

## Identity and Ownership

Review fields include reviewer Principal/agent identity, exact candidate revision/digest, evidence consumed, findings, severity/category/location references, disposition, timestamps and supersession/review-round relationship.

Review does not own merge authority, policy approval or candidate edits.

## Invariants From Day 1

- reviewer cannot silently edit candidate and approve its own edit in the same step;
- reviewer has no merge credential/authority by default;
- review binds to exact ChangeSet revision;
- valid existing evidence is consumed rather than rerun without reason;
- candidate change makes prior approval non-current unless policy proves unaffected scope;
- findings have structured status and location/context when possible;
- human inspection remains available even when agent reviewer is default dogfood path.

## Reviewer Types

```text
Agent reviewer
Human reviewer
System/mechanical review result (only for deterministic policy checks, not semantic code review)
```

Independent reviewer selection avoids using the same logical coding agent as sole approver. Account/model may differ by policy.

## Findings

Finding types may include correctness, architecture, security, tests/evidence, maintainability, UX/spec conformance and policy. Severity and blocking behavior are policy, not reviewer discretion alone.

## Lifecycle

```text
requested -> reviewing -> submitted
submitted disposition:
  approved
  changes-requested
  blocked
  superseded by newer candidate/review
```

## Correction Loop

`changes-requested` returns work to Task/AgentRun correction. A new Attempt may resume WIP/checkpoint or start fresh. New candidate revision gets focused re-verification based on what changed.

## Increment Realization

| Increment | Review realization |
|---|---|
| I1 | independent agent/human review, findings, disposition, correction loop. |
| I3 | generic policy/Approval/HITL relationships. |
| I5 | richer VerificationAuthority evidence integration and affected-scope invalidation. |
| I8 | resolver-generated changes use normal Review path. |

## Current Implementation State

Target spec. Default dogfood path uses independent reviewer agent with human view available.

## Deferred Realization

Rich collaborative inline comments, review teams and enterprise code-owner mapping are later UX/provider enhancements, not required for I1 identity.

## Temporary Dogfood Behavior

One reviewer may be enough in I1; policy can later require multiple/security/owner reviewers without changing Review identity.

## Failure / Recovery

Reviewer failure creates retry/new review attempt without mutating candidate. Provider review/PR posting failure is reconcilable; AWP Review result remains durable.

## UI Implications

Review page combines diff/changed files, existing evidence and structured findings. Primary action follows current authority: request correction, approve/review disposition or merge when gate is separately satisfied.

## Decisions / ADRs

Review vs Approval separation is binding. Security/policy may require Approval in addition to Review.