Saphan StudioDocs
Working with git

The review verdict

What a reviewer writes, the words a verdict may carry, and the shape a real one takes.

_REVIEW_STATUS.md — the review verdict

What it is

A reviewer's judgement about a stream, filed under that stream's slug. It is a record fact, not a decision: it tells the human what the reviewer found; it does not advance the stream.

Who writes it, who reads it

Written by the reviewer, and it is the only file a reviewer writes. Read by the coordinator, by the review gate, and by the record. It must cross the delivery boundary — saphan return — before the review gate will look at it: see Working with git. A verdict nobody delivered gates nothing.

The complete key set

keyclasswhat it carries
statevocabularyone token from the review family's own dictionary — never borrowed from the status one
verdictvocabularyone writable verdict token, alone on the line. Mandatory for recommendation-ready. No parenthetical, and no conditions trailing it — the conditions belong in the review body the manifest names
refatomicthe review's returned artifact. Mandatory for recommendation-ready. It must be one of this document's own - artifacts: entries, verbatim — a name that is not a declared entry is refused at delivery. ⚠ It is not a git reference
abstractprosethe reviewer's own summary, at most five lines
artifactsmanifestthe paths this review returns. Mandatory for recommendation-ready, including an explicit empty list when nothing is returned
returnmanifestthe older spelling of the same manifest
updatedatomictimestamp

The words a reviewer may write

state:     spawned   ·   recommendation-ready
verdict:   accept    ·   accept-with-conditions   ·   reject

One older verdict spelling is ingested for existing documents and is refused in a new one.

⚠ A verdict is not a gate. accept-with-conditions records conditions; the human still decides. A named review is a debt recorded against the stream — the stream owes a verdict under its own slug — and the merge refuses until one exists. It is one debt for one stream, not one per round of work.

A verdict, in the shape a real one takes


- state: recommendation-ready
- verdict: accept-with-conditions
- ref: review-invoice-export-csv.md
- abstract: The eight columns are real and I re-proved each one by dropping it myself rather
  than by reading the report. Two conditions, neither of which makes a shipped sentence false.
  14 pass / 0 fail at the tip; the branch combines with its base cleanly.
- artifacts:
  - review-invoice-export-csv.md
- updated: 2026-09-02

## Anchors — measured, and they agree with the order

    git rev-parse --short=11 HEAD    → 4b19c7ae0f2   (order: 4b19c7ae0f2, agrees)
    git status --porcelain           → empty, before and after every mutation

## Conditions

1. The unknown-column refusal names the column but not the set it was checked against; a
   reader of the error cannot tell which columns were legal.
2. The ninth column the status names as absent deserves a line in the export's own
   documentation, so the next reader does not re-discover it.

Notice the anchor block: the reviewer re-measured the order's own numbers and said so. That is what makes a verdict evidence rather than a second opinion about a report.

The status an agent returns

The closed key set, the state words an agent may write, and the line that closes a return.

Checking a document before you rely on it

How to have a channel document validated rather than trusted, and the rules worth keeping after you close these pages.

On this page