// docs · v1.x

Policy gate — guard

A declarative merge gate that caps how many findings of each severity a change may carry, via an opt-in .commitbrief/policy.yml. Richer than a single --fail-on threshold; aimed at gating high-volume, often AI-authored, pull requests.

Updated October 20, 2026

commitbrief guard is a declarative merge gate. Instead of one severity cutoff, it evaluates a review’s actionable findings against a .commitbrief/policy.yml and exits non-zero when the policy is breached. Think of it as a per-severity budget rather than the single --fail-on=<severity> threshold — useful when you’re gating high-volume, often AI-authored, pull requests.

The policy file

The gate is opt-in in the sense that nothing runs it until you call commitbrief guard. Once you do, a .commitbrief/policy.yml must exist: with no policy file guard fails with exit code 1 instead of passing. Create one to declare the budget:

# .commitbrief/policy.yml
version: 1
thresholds:        # max findings allowed per severity (omit or ~ = unlimited)
  critical: 0
  high: 0
  medium: 5
  low: ~
total: 20          # optional overall cap across all severities

A severity you omit (or set to ~) is unlimited. total is an optional cap on the combined count.

rules — deny and allow by rule

Requires v1.19.0 or later. Every finding carries a rule id from a closed list of 30. The optional rules block turns a class of finding into a hard stop, or waives one from the budget:

version: 1
thresholds:
  high: 0
  medium: 5
rules:
  deny:
    - sec.*              # any security finding blocks the merge
    - test.flaky
  allow:
    - style.*            # style findings never count toward the budget
ListEffect
denyEach matching finding is a violation named rule:<id>, with allowed 0 and actual 1, regardless of thresholds.
allowMatching findings are waived: they leave the per-severity counts and total, and are reported as waived.

Deny wins over allow: a finding matching both is denied. Entries are a taxonomy id (sec.injection) or a whole category (sec.*). Nothing else is accepted. A bare category (sec), a partial glob (sec.in*), an unknown id, the same id in both lists, or an unknown key under rules is a hard error and the gate fails, in line with the rule that a gate which cannot read its policy does not pass.

A finding with no rule id, such as JSON from an older binary read with --from-json, counts as general.other. A policy without a rules block behaves exactly as before.

allow removes a finding from the gate, not from the review. It still appears in the review output; only the verdict ignores it. Unlike a baseline, which is user-private, the policy file is committed and reviewed with the code.

Two ways to run it

Run-mode — review, then evaluate

Run-mode reviews the diff (reusing the standard pipeline) and judges the result against the policy:

commitbrief guard                     # staged diff
commitbrief guard --unstaged
commitbrief guard --diff main...HEAD

Consume-mode — evaluate an existing review

--from-json evaluates a review you already produced, with no provider call — so an agent’s MCP self-review or a prior commitbrief --json run can be gated cheaply:

commitbrief --json --staged > review.json
commitbrief guard --from-json review.json

--from-json - reads the review from stdin — which is also how a credential audit gets gated, since leaks --json emits the same schema-v1 document:

commitbrief leaks --json --fail-on none | commitbrief guard --from-json -

There was no model call in that pipeline (meta.provider is "builtin", cost_usd is 0), and guard neither knows nor cares.

What it evaluates

guard judges the findings that survive baseline + suppression (signal control) — exactly the set --json shows. Baselined and inline-suppressed findings are already gone before the policy sees them.

Exit codes

The exit code is 0 (pass) or non-zero (blocked). Critically, a load or parse failure also blocks: a missing or malformed policy, or an unparseable review, fails the gate rather than passing it — a merge gate must not pass when it cannot prove the change is within policy.

The same holds when the model response could not be parsed into structured findings, whether the review ran live, was replayed from the cache, or arrives through --from-json. guard then exits 1 with a “policy cannot be verified” error, prints no verdict, and --json writes no verdict document; re-run the review, or add --no-cache if a cached result was replayed. A healthy review with no findings still passes. Requires v1.21.1 or later; earlier versions passed in that case unless --sarif was set.

--json emits a machine-readable verdict:

{
  "passed": false,
  "counts": { "critical": 0, "high": 2, "info": 0, "low": 0, "medium": 1 },
  "total": 3,
  "violations": [
    { "severity": "high", "allowed": 0, "actual": 2 }
  ],
  "waived": 0
}

counts always carries all five severities. Each entry in violations names the breached severity (or total for the overall cap), the allowed maximum, and the observed count; severity violations come in critical to info order, with total last, then any rule:<id> violations in alphabetical order. waived (Requires v1.19.0 or later) counts findings removed by rules.allow.

On the terminal, the verdict adds one line per denied rule and a waiver summary:

rule sec.injection: denied by policy (2 findings)
Waived by policy rules.allow: 3 finding(s)

A single denied finding prints rule X: denied by policy without the count. In run-mode, signal-control warnings (for example an unknown inline marker token) go to stderr and respect --quiet.

SARIF output

Requires v1.21.0 or later. guard --sarif writes a SARIF 2.1.0 log under the commitbrief/guard/ category for GitHub Code Scanning. Use -o to write a file; the verdict goes to stderr and the exit code is unchanged.

commitbrief guard --sarif -o guard.sarif

The log holds only the findings that cause a violation. It is built from the same set the verdict is computed from, so the log and the exit code cannot disagree. A passing run writes a valid log with results: [].

It fails closed. When the model response could not be parsed into structured findings, in run-mode or in a --from-json input, no file is written and the command exits 1; re-run the review. Upload it with category: commitbrief/guard. See SARIF and Code Scanning.

guard vs. --fail-on

--fail-on=<severity> is the simple one-threshold gate — “fail if any finding meets or exceeds this severity.” guard is the per-severity budget — “allow up to N of each.” They complement each other; use either or both. A repo might run --fail-on=critical on a developer’s pre-commit hook and the richer guard policy on the CI merge gate.

Flags

FlagNotes
--policy <path>Policy file location. Default .commitbrief/policy.yml, resolved relative to the repo root. An explicit --policy path is used as given, relative to the current working directory.
--from-json <file|->Consume-mode: evaluate a prior schema-v1 review (no provider call). - reads stdin.
--unstagedRun-mode: review the working tree instead of the staged diff.
--diff <range>Run-mode: review an arbitrary git diff range.
--jsonEmit the machine-readable verdict.
--sarifWrite the findings that breach the policy as a SARIF 2.1.0 log. Requires v1.21.0 or later. See SARIF output. Not with --json, --markdown, --suggest-commit, --cli or --show-prompt.

--provider / --model / --no-flaky carry over from the persistent flags in run-mode, as do the path filters (--file, --dir, --exclude-file, --exclude-dir) and the commit filters (--author, --committer, --start-date, --end-date, --text, --max-commits, --merges).

Sandbox-rerun never runs under guard. Even with review.sandbox_command configured, the gate will not execute your repository’s tests — unconditionally, with no toggle. Its flaky findings stay at the static-only confidence level. See Flaky-test detector.

See also