Turn on the gate

So far vidi has only reported. This page makes review coverage a merge requirement.

Before: nothing is enforced

$ vidi verify
no policy file: .vidi/policy.toml absent
NEUTRAL: unconfigured (counts as passing for branch protection)
opt in with `vidi init`, then add a [[cover]] or [[scope]] block.

NEUTRAL means no rules exist, so nothing can fail. A repository opts into gating by adding exactly one file: .vidi/policy.toml.

Write a policy

Start narrow. A policy that gates the whole repository on day one just fails every build.

# .vidi/policy.toml
schema = "1.0"

# Paths matched by no gating [[scope]] are report-only.
default = "advisory"

# The reviewer ladder, lowest rank first.
[axes]
human.order = ["contributor", "reviewer", "maintainer"]

# The reviewer directory. Only people listed here have a standing that can
# satisfy a rank requirement.
[reviewers]
"[email protected]" = { role = "maintainer", name = "Your Name" }

# One gated path: the crypto core needs a maintainer's review.
[[scope]]
path = "crates/vidi-core/src/crypto/**"
accept = [ { human = "maintainer" } ]

Four things are doing work here:

Key	Effect
`default = "advisory"`	everything outside a `[[scope]]` is reported, never gate-failing
`[axes] human.order`	the rank ladder; later entries outrank earlier ones
`[reviewers]`	who has a standing. A vouch from someone not listed cannot satisfy a requirement
`[[scope]]`	a path glob plus the accept rows a review must meet

A [[scope]] with an empty accept = [] is a load error, not a silent no-op. A rule that could never be satisfied is rejected when the policy loads rather than quietly passing everything.

After: the gate bites

$ vidi verify
FAIL: stale 0 · orphans 0 · requirement failures 175 · default shortfalls 0 · rejected ledger lines 0
  unmet      crates/vidi-core/src/crypto/assurance.rs::enum:AssuranceScalar
  unmet      crates/vidi-core/src/crypto/assurance.rs::enum:Identity
  unmet      crates/vidi-core/src/crypto/assurance.rs::enum:Presence
  unmet      crates/vidi-core/src/crypto/entrypoint.rs::enum:SignRefusal
  ...

175 units under crypto/** now require a maintainer’s review and have none. Everything outside that glob is untouched, that is default = "advisory" working.

The exit code is the gate

$ vidi verify > /dev/null; echo $?
1

That non-zero exit is the entire enforcement mechanism. CI sees a failing command and blocks the merge. See Block merges in CI.

vidi status is not a gate. It prints the same verdict word but always exits 0:
$ vidi status
FAILURE: 0/5489 reviewed · stale 0 · orphans 0 · requirement failures 175 · default shortfalls 0
$ echo $?
0
A CI job running vidi status prints FAILURE on every build and passes anyway. Use vidi verify.

Three verdicts

Verdict	Exit	When
`FAILURE`	1	anything stale, orphaned, or unmet, evaluated before policy presence
`PASS`	0	a policy exists and every requirement is met
`NEUTRAL`	0	no policy, and nothing broken

Staleness fails even with no policy at all, because it is an integrity property rather than a rule you configure. See Watch a review go stale.

Standing

A vouch recorded before a policy existed does not retroactively satisfy one:

note: this repo has no .vidi/policy.toml: this vouch is recorded without a
standing and will never satisfy a rank requirement. To count toward one: add a
policy with a [reviewers] entry, then vouch again.

The same applies to anyone missing from [reviewers]. Their reviews are recorded and visible, but carry no rank, so they cannot clear a requirement.

Why start narrow

Turning on a repo-wide gate against an unreviewed codebase means every build fails until the whole backlog is cleared, and the usual outcome is that somebody disables the check.

Gate one directory that genuinely matters, clear it, then widen. Everything outside your scopes stays visible in vidi status and vidi queue the whole time — you lose no information by gating gradually.

Keyboard shortcuts

vidi