Concepts

Moments

Choose when Verity reviews. By default it reviews every agent turn, every commit and every push, so a change has to pass at each boundary before it lands.

A moment is a point in your agent's lifecycle where Verity attaches and runs a review. The same two-layer review described in How it works fires at each one — what changes is when it runs, what diff it judges, and how much it is allowed to spend on it. Pick the moments that match how your team ships; they are not mutually exclusive.

The three moments

MomentFires when…ReviewsCan block?
On stop stopyour agent finishes a turnwhat the agent wrote this turn, minus what was already judgedYes — a FAIL sends the agent back to fix, within the self-healing limits
Before commit pre-committhe agent runs git committhe staged diff, wholeYes — holds the commit until it passes
Before push / PR pre-pushthe agent runs git push or gh pr createthe commits about to be pushed, wholeYes — holds the push until it passes

Alongside these, Verity always captures your prompts and specs as intent — infrastructure, not a gate. It is how the review knows what you were trying to do, at every moment.

Choosing your moments

  • On stop + before commit + before push (the default) — continuous feedback and a hard stop at each boundary.
  • On stop only — fast feedback while you work. Problems surface seconds after they are written, before you have moved on.
  • Before commit + before push only — many teams turn on stop off and gate only the boundaries, so the agent iterates freely and is checked when work actually lands. Routine turns cost nothing.

The git moment is a different kind of review

A commit or push is the moment closest to code landing. It tolerates more latency, and the whole change must arrive — a 45-file commit reviewed as its first 40 files is a review of a different change. So the commit and push gates run on their own profile:

  • The whole change ships for review. Up to 120 files, 96 KB per file and ~570 KB in total, against 40 files and 190 KB on a stop turn.
  • A stronger reviewer, on a longer budget. Git moments run on a more capable model with a three-minute budget; interactive turns stay on the fast one. Overridable per project with process_constraints.git_moment_model and git_moment_reasoning_effort in the Standard.
  • Intent is what the change contains. The commit message, or the PR title and body, is read as the stated purpose, and only documents that are part of the push ride along as plans. A months-old plan file that happens to be committed cannot gate an unrelated push, and “the plan is not fully implemented” is never a finding — it informs the intent check only.
  • It reviews the tree the command targets. The gate resolves which repository, which worktree and which commit range from the command itself — cd chains, git -C, remotes and refspecs — with ranges anchored at the merge-base. Pushing from a linked worktree reviews that worktree, not the main checkout.
  • Named refusals over guesses. When the target cannot be resolved — --git-dir, GIT_WORK_TREE=, two pushes to two targets in one command — the gate allows the command without a review and says so loudly. It never issues a verdict about a tree it guessed.
  • The reviewer sees which lines the change wrote. From CLI 0.36.0, the CLI sends the line numbers of the change with the files: numbers only, never extra code. The reviewer sees each changed line marked, and each place where the change removed lines. A file over 300 lines shows its first 20 lines and the lines around each change.
  • Coverage is printed on every run: the moment, tree, branch, range, the files reviewed, what was excluded and why, and how long the review took.

A blocked commit looks like this from the agent's side:

verity · pre-commit gate
› git commit -m "add login route"
› verity pre-commit · main @ feature/login · staged · 2 files reviewed, 0 excluded
  auth/login.ts:42  string-built SQL query → SQL injection (CWE-89)  [parameterized-queries]
✗ FAIL · 1 critical finding — commit held
› agent self-healing (iteration 1/2)…
✓ verity pre-commit: PASS — commit proceeding (52s)

What blocks, and what does not

  • Blocks — a critical or high-severity quality or security finding about a file in the change. The agent receives the findings, fixes them, and re-runs the commit or push.
  • Warns, never blocks — a WARN verdict, or an intent mismatch with no severe finding (the diff does not match its message, but nothing is unsafe). Surfaced inline; the command proceeds.
  • Cannot block on a file it did not review. A finding about a file outside the change — a leftover from a previous run, a stale pending item — is downgraded to pre-existing. Stale carry-overs can no longer hold a clean push.
  • A finding far from the change does not block it. A finding more than 3 lines away from every changed line is marked pre-existing. It is still shown, but it does not block. Your own problems still block:
    • a finding that a static tool reports keeps its scope;
    • a problem that a removed line causes stays with the change;
    • a file that a merge combined is reviewed as before;
    • when the CLI cannot prove that the line numbers fit the code it sent, that file is reviewed as before.
    This applies at a commit and a push only, with CLI 0.36.0 or later. A stop turn is reviewed as before.
  • Never traps the agent — each gate is capped at two blocks per command, counted separately for commit and push. After that the command is allowed through with the findings still reported.
  • Fails open, out loud — if the service is unreachable or the repository is not configured, the command is allowed, and the skipped review is named rather than letting an unreviewed commit look like a passing one.
  • A formal counterexample blocks only when it reproduces. When formal verification is on (the default for a new project), the push may also get a Lean model of one risky function; a failing trace holds the push only after it has been replayed on the real code, and most pushes get no model at all. See Formal verification.
  • A human can accept a risk. A finding your reviewers have deliberately accepted is recorded with verity waive and stops blocking, until the file changes. See Findings & verdicts.
Claude Code hooks — not git hooks
The commit and push gates fire when your agent runs git commit or git push inside Claude Code. There are no .git/hooks scripts, no GitHub App on the push path, and no CI to set up — and removing Verity removes them cleanly. Run the same commands yourself in a terminal and nothing is gated.

Changing your moments

All three moments are on for a new project. verity init does not ask. It prints “Verity reviews every turn, every commit and every push”. Change them at any time from the CLI, or ask Claude to do it:

verity config moments turn,commit,push   # all three (the default)
verity config moments commit,push        # boundaries only
verity config moments none               # review nothing
verity config moments                    # print the current setting
verity hooks check                       # see what's wired
  • Give any of turn, commit and push, comma-separated, or none. An unknown word is refused, so a typo cannot remove a gate.
  • The command sets exactly the moments you give. On the npm path it rewires Verity's hooks in .claude/settings.json and leaves every other hook alone. Intent capture and the session hooks stay on regardless.
  • Your choice survives a re-run of verity init. A re-run without --moments keeps it.
  • On the npm path, the change applies from the next Claude Code session. Under the plugin, it applies from the next turn.
Next
What a verdict means and how to answer one — fix, dispute, waive, exclude — is in Findings & verdicts.