Review a pull request

Your first vouch walks one unit end to end. This is the repeat loop: find the work, read it, record a verdict, and confirm the gate agrees.

The loop

$ git diff --name-only main...HEAD          # what the PR touched
$ vidi explain <file>                        # what vidi wants there
$ vidi vouch "<unit address>"                # record your verdict
$ vidi verify                                # confirm the gate agrees

Counts in the examples below move as the repo changes, including when someone edits documentation, so read them as shapes, not values to match.

What scopes to a change, and what doesn’t

Vidi’s readers are repo-wide. queue ranks every unit in the repository and verify gates all of them; neither takes a branch, a commit range, or a diff. Two of the four pieces scope to a change:

The gap is on the finding side: there is no vidi queue --since main. Bridge it with git, as the next section does.

Finding what the PR touched

Ask git for the changed files, then ask vidi about each one:

$ git diff --name-only main...HEAD
crates/vidi-core/src/crypto/keyid.rs
crates/vidi-core/src/policy/schema.rs

$ vidi explain crates/vidi-core/src/crypto/keyid.rs
explain: gate FAILS · stale 0 · orphans 0 · requirement failures 174 · default shortfalls 0 · rejected ledger lines 0 · crates/vidi-core/src/crypto/keyid.rs

gating   requirement-unmet crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:parse_hex
  what: the unit is fresh but falls short of an explicit `[[cover]]`/`[[scope]]` review requirement (e.g. a required reviewer standing or a second axis). This fails the gate.
  why:
    - The matching policy row demands a stronger review than is present (a higher reviewer rank, or a second review axis).
  fix:
    → Add the missing review(s) at the required standing; `vidi report` lists the exact gap for the unit.
    → If the requirement is wrong, adjust the `[[cover]]`/`[[scope]]` block in `.vidi/policy.toml`.

Scoping explain to a path is what keeps this readable. Unscoped, it narrates every failing unit in the repository.

Read requirement-unmet carefully. The wording says “the unit is fresh but falls short”. It says that whether the unit carries a review that is not strong enough or no review at all. If you are hunting a rank problem that does not seem to exist, check whether anything has reviewed the unit first: vidi show <unit address> lists every statement against it, and prints nothing when there are none.

Working the queue

When you are not reviewing a specific PR, take the queue from the top. It shows the top 20 by default:

$ vidi queue
re-review queue: top 20 of 5752 below the bar · gating first, then significance × severity
   1. gating   · sig 100 · unreviewed       crates/vidi-core/src/crypto/assurance.rs::enum:AssuranceScalar
   2. gating   · sig 100 · unreviewed       crates/vidi-core/src/crypto/assurance.rs::struct:Assurance
   3. gating   · sig 100 · unreviewed       crates/vidi-core/src/crypto/entrypoint.rs::enum:SignRefusal
   …
  20. gating   · sig  96 · unreviewed       crates/vidi-core/src/crypto/entrypoint.rs::const:AGENT_ENV_MARKERS
  … 5732 more · `vidi queue --all` shows everything, `--top N` widens the cut

The ordering is two-tier, and the first column names the tier. gating means a [[cover]] or [[scope]] requires review there, those fail the build and sort first. advisory is reported but not gating. sig orders within each tier and never affects whether a unit passes; see Unit states.

So the top of the queue is what is breaking the gate, most significant first. Everything below the gating block is backlog.

Reading the unit

vidi show does not print source code. It prints the ledger statements recorded against a unit. The review history, not the thing under review:

$ vidi show "crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:of_public_key"
content_id 8384bb1382675eb3dd0b7d3e9d858c5f
  subject   crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:of_public_key
  kind      review · by [email protected] · at 2026-08-06T19:59:01Z
  add --json for the exact bare-statement bytes.

That is worth running before you review as it answers “has anyone looked at this already, and who?” However, it is not the code. To read the code, open the file in your editor. No vidi command displays a unit’s source.

The machine report knows the exact lines if you want them:

$ vidi json | python -c "import sys,json; [print(u['file'], u['lineStart'], u['lineEnd']) for u in json.load(sys.stdin)['units'] if u['address'].endswith('fn:of_public_key')]"
crates/vidi-core/src/crypto/keyid.rs 30 32

Recording a verdict

For a straightforward approval, vouch:

$ vidi vouch "crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:of_public_key"
vouched crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:of_public_key as [email protected] (maintainer)
  content_id 8384bb1382675eb3dd0b7d3e9d858c5f · appended to .vidi/ (bare line, diff-visible)

The (maintainer) is your standing at this moment, read from [reviewers] and stamped into the record as roleAtReview. It is not decoration: a later promotion will not retroactively strengthen this vouch, and a later demotion weakens it immediately. See the policy.toml reference.

If no role appears, your identity is not in [reviewers] — read the last section of this page before going further.

Rigor

--rigor records how hard you looked:

$ vidi vouch --rigor ran-tests "<unit>"

Rejecting, and other verdicts

vouch is approval only. For a verdict you have to think about, including rejection, use the interactive form which prompts for rigor and verdict:

$ vidi review "crates/vidi-core/src/crypto/keyid.rs::impl:KeyId::fn:parse_hex"

A rejection is a real, recorded position: someone read exactly these bytes and declined them. It does not gate on its own, but it is visible in show, and it is not the same as silence.

Approving a whole commit

$ vidi vouch --commit <ref>

This vouches every unit the commit touches. Convenient for a small, focused PR. Consider what you are claiming on a large one. It records the same rigor claim against every unit in the change.

Confirming

$ vidi status
FAILURE: 2/5752 reviewed · stale 0 · orphans 0 · requirement failures 173 · default shortfalls 0

requirement failures dropped by one, from the 174 the explain above reported: that unit’s obligation is now satisfied. vidi verify is the command that actually gates, and it exits non-zero while any requirement is unmet.

Your reviews are now lines in .vidi/reviews.jsonl. Commit them with the code, they are meant to travel with the branch, and they cannot cause a merge conflict (vidi init sets merge=union, so git keeps every line from both sides). See Why review files never conflict.

When your reviews do not count

Your [reviewers] key is compared as a literal string against the identity stored in each review. If they differ by even one character, every vouch you make is silently ignored, and nothing warns you.

This is easy to hit because the two logins write different identities: vidi login --local writes your git email, the hosted login writes a vidi:p:<guid>. Key the policy one way, write the ledger the other, and coverage you know you recorded reads as missing.

Those reviews are not lost, they land in an unverified bucket that only the machine report mentions. If vidi json shows a non-zero summary.unverified, this is what happened. The by … line in vidi show <unit address> prints the string your [reviewers] key has to match.

Next

Revoke an approval