git-agent-verdict

Verifies that a commit message carries an attested review verdict, and blocks on any declared blocker. It is blind to what the standards say: the reviewer reads the standard, the gate reads a verdict.

Built for repos where commits are written by agents. No human is expected to write a trailer.

Why it exists: so a repo can stay about its own code. Every repo that wants agent-written commits reviewed ends up growing the same few hundred lines of bash to demand and check an attestation, and every copy drifts from the others. That machinery is not what any of those repos are for. This is that machinery, once, outside them.

Install

cargo install git-agent-verdict

Installs as git agent-verdict. --help is the flag reference; this file is not.

Wiring it into a repo

.githooks/commit-msg, enabled per clone with git config core.hooksPath .githooks:

#!/usr/bin/env bash
set -euo pipefail
git agent-verdict --check-min-version 0.3.0
git agent-verdict --rubric-guard \
  --doc docs/repo-standards.md --doc docs/annotation-guide.md --doc docs/communication-style.md
git agent-verdict "$1" standards   --doc docs/repo-standards.md --path .
git agent-verdict "$1" annotations --per-file --simple --doc docs/annotation-guide.md --path .
git agent-verdict "$1" prose       --simple --doc docs/communication-style.md --path README.md

Gate names are repo-chosen labels, not keywords. Line order is review order, and set -e stops at the first unattested gate on purpose: a later gate must never be judged against content an earlier one is still changing.

Each line is the whole declaration of its gate, which is what lets --reviewer-prompt <gate> hand back exactly the brief that gate will judge by — it re-runs this hook to read the declaration rather than keeping a second copy in a config file.

A version floor, not an equality: what must not arrive silently is a different reviewer brief, and that only happens when the floor is raised deliberately, so an additive release passes. One line in the hook, rather than a shell version-compare beside every gate.

Most gates are --simple above, and that is the usual shape: one gate holds the bar the work has to clear, and the rest report. A repo that blocks on every dimension it cares about spends its review budget on the ones that were never going to sink the change.

How it goes

The agent is never briefed on the review process. It is told to do the work, it does it, and it tries to commit. The commit fails by design, and the gate prints what it wants — the missing trailer first, then the reviewer prompt that earns it, so the target and the remedy arrive in one turn.

$ git commit
git-agent-verdict: my-code-review: REVIEW GATE FAILED

MISSING — the message needs this trailer and has none

  Reviewed-my-code-review: reviewer=<id> major=0 moderate=<n> minor=<n>

── FORWARD BELOW THIS LINE ──
NEUTRAL REVIEW — gate: my-code-review
...

The agent spawns a reviewer in a fresh context, hands it that block with the INTENT filled in, fixes what comes back, writes down what the reviewer reported, and commits again.

$ git agent-verdict --reviewer-prompt my-code-review | claude -p \
    "INTENT: the commit-msg hook delegates verdict verification to an external CLI
             and keeps only the gate declarations."

Nothing in that pass was configured, and claude -p is one runtime among many: the gate never sees the reviewer, only the trailer it produces. The requirement is printed at the moment it is wanted, which is what keeps the process out of the agent's briefing and out of the repo's docs.

The trailer

Reviewed-standards: reviewer=claude-opus-5 major=0 moderate=1 minor=3
Reviewed-annotations: reviewer=claude-opus-5 major=0 moderate=0 minor=1 file=src/trailer.rs

Named fields, so a per-file gate adds one instead of changing the arity. Trailers must be the message's last paragraph — that is what git interpret-trailers --parse reads.

The counts are the whole verdict, and asking for three numbers rather than a verdict is deliberate: a reviewer that reports major=0 has committed to a number it can be held to, which matters precisely because the writer is an LLM. moderate=1 on a passing commit is not an outstanding defect. It was fixed, and the count records that the review found it.

Trust model. The gate verifies that an attestation is PRESENT and WELL-FORMED. It cannot verify that a review happened. What it buys is attribution, not enforcement: a false attestation passes, but it is then a claim on the record with a name on it.

The ladder

Three rungs, graded by what is wrong, not by what the fix costs:

• MAJOR: the work is wrong, or carries a severe flaw. Not the author's to patch: the fix is re-planned by an agent that did not write it, then implemented and reviewed afresh. The only rung that blocks.
• MODERATE: the outcome is right, the execution is not. The author fixes it and does not go back for a second opinion on the fix.
• MINOR: the author's discretion — fixed, or consciously left. Recorded either way.

The review runs once. A review-and-fix loop fails in two directions, and the band between them is narrow. Too tight and nothing ever settles: every nit blocks, so no round comes back clean. Too loose and the reviewer rubber-stamps. The loop itself was most of the cost — a full second review to confirm fixes the same reviewer had already specified — and MODERATE is what buys it away: real enough to have to fix, small enough that the fix does not need looking at. MAJOR is the one case where another review is genuinely cheaper than the alternative, and even it re-reviews nothing.

MINOR is what keeps the count honest. A finding can be recorded without obliging anyone to act on it, so nothing is suppressed and no reviewer is asked to pretend the code is clean. Findings are declassified, never hidden, which keeps the pressure on the code rather than on the report.

The brief carries one thing: intent. What the change set out to do, stated flatly, as a spec would state it. A reviewer handed a case for the change grades the case, and that is most of what stands between a review and a rubber stamp. Scope is not a reviewer's question either: it was settled before a plan existed, and a scope observation comes back as one MINOR line.

A severity, not a score. It says what is wrong and what that costs, where a number lets a weak dimension hide behind strong ones and invites argument that cannot change the outcome. Two shapes tried before this one, both of which never settled:

Two behaviours worth knowing

It refuses a commit that stages its own rubric. Judging a change to the measure against that same measure is circular, so a --doc file lands alone via --no-verify. This is the one place the tool refuses rather than verifies, and it lives here because the list of rubrics IS the list of --doc paths — a copy in bash would be free to drift from it.

It removes a Co-authored-by: trailer whose address is @anthropic.com. Every commit in a repo gated this way is agent-written, so a fixed attribution line is constant and carries nothing, while reviewer= already records who did the work. The match is on the address, so a human co-author called Claude keeps their credit. This is the only case where the tool writes to the message.

Developing this repo

The two linters the pre-commit hook calls are pinned at install time, so the hook stays a flat list of commands with no wrapper script holding a version:

npm i -g annotated-tree@0.6.0
cargo install --git https://github.com/fredrikolis/cargo-lint-extra \
  --rev 7a232179e45414108d28047acd6315d9a2c4946b --locked cargo-lint-extra
git config core.hooksPath .githooks