# reviewer review

```
shadcn-maestro reviewer review --input <file|-> [--cwd <path>] [--json]
```

A review is a verdict on one exact annotation revision, written by a different agent execution than the author. In the plugins, `shadcn-maestro review` opens that separate session (`claude -p` or `codex exec`) for you; see [The design-apply flow](/agent/flow).

## Input

The JSON must match the [review schema](/cli/schemas#review):

| Field | What to put |
| --- | --- |
| `annotationId` | The id returned by `annotate`, e.g. `annotation:screen:src/pages/Customers.tsx` |
| `annotationRevision` | The revision being reviewed |
| `reviewer` | `host` and `session` of the reviewing execution; it must not be the author's |
| `verdict` | `confirmed`, `disputed` or `insufficient_evidence` |
| `rationale` | What the reviewer checked and found |
| `checkedRefs` | The source references the reviewer read |
| `sourceHashes` | The same file hashes the annotation was written against |

```json
{
  "annotationId": "annotation:screen:src/pages/Customers.tsx",
  "annotationRevision": 1,
  "reviewer": {
    "host": "claude-code",
    "session": "reviewer-session-2"
  },
  "verdict": "confirmed",
  "rationale": "Customers.tsx lines 17-44 render PageHeader, the filter input and the customers table, as the annotation says.",
  "checkedRefs": [
    {
      "end": {
        "column": 12,
        "line": 44
      },
      "fileHash": "e5044cd33fec21c42e7c2e33329cc1c4ba37009361a821a7b7e9cb1fb0675899",
      "relativePath": "src/pages/Customers.tsx",
      "start": {
        "column": 5,
        "line": 17
      },
      "symbolId": "src/pages/Customers.tsx#Customers"
    }
  ],
  "sourceHashes": {
    "src/components/PageHeader.tsx": "9a5d7415b1cf0c729f88df5a07e6d9854e736ceb967b741f01deab214e5bd567",
    "src/pages/Customers.tsx": "e5044cd33fec21c42e7c2e33329cc1c4ba37009361a821a7b7e9cb1fb0675899"
  }
}
```

## Result

```json
{
  "schemaVersion": 1,
  "command": "reviewer review",
  "status": "ok",
  "data": {
    "annotationId": "annotation:screen:src/pages/Customers.tsx",
    "revision": 1,
    "verdict": "confirmed",
    "annotationStatus": "reviewed",
    "identity": "observed",
    "schemaValidation": "passed"
  },
  "issues": [],
  "nextAction": null
}
```

| Verdict | Annotation becomes | Status | Next action |
| --- | --- | --- | --- |
| `confirmed` | `reviewed` | `ok` | None; `reviewer` stops listing the subject as missing |
| `disputed` | `disputed` | `pending`, issue `disputed` | Ask the user: present both readings with their sources, then submit a corrected annotation for a new review |
| `insufficient_evidence` | `pending` | `pending`, issue `insufficient_evidence` | Gather more evidence (source, then the page in a browser) and resubmit the annotation |

## Errors

All return `status: "error"` (exit `2`) and nothing is saved.

| Issue | Cause |
| --- | --- |
| `invalid_input` | The file or stdin is not readable JSON |
| `invalid_review` | The JSON does not match the schema; a reviewer identity and a verdict are required |
| `identity_mismatch` | `reviewer.session` differs from the session the host exposes |
| `no_map` | There is no map yet |
| `unknown_annotation` | `annotationId` is not in the current map |
| `stale_review` | The annotation is at another revision, or its source changed since it was written |
| `self_review` | The reviewer is the author of the annotation |
| `stale_source` | The source hashes no longer match the annotated files |
| `invalid_reference` | A checked ref does not point to a mapped file at its current hash |
| `map_update_failed` | The map could not be written |

A self-review, for example, is rejected like this:

```txt
Reviewer claude-code/author-session-1 is the author of annotation:screen:src/pages/Customers.tsx; an independent execution must review it
Next: Request the review from a different agent execution
```