// docs · v1.x

Signal control — baseline and suppression

Cut repeat noise without hiding findings from review — a user-private baseline that accepts a brownfield repo's existing findings, plus inline commitbrief-ignore comments with a visible reason.

Updated October 20, 2026

A reviewer that re-reports the same pre-existing findings on every run is a reviewer you start ignoring. Signal control gives you two ways to drop findings you’ve already triaged — a baseline for “accept everything this brownfield repo already has” and an inline // commitbrief-ignore comment for “this one specific finding is fine” — without ever hiding a finding from the next reviewer.

Both are true removals, not display filters: a dropped finding no longer counts toward --fail-on and no longer appears in --json findings[]. That makes them stronger than --min-severity — see How this differs from --min-severity below. And neither is silent: every removal is counted and reported.

Baseline

A baseline records the findings already present in your repo so that subsequent runs show only new ones. It’s the answer to “I just pointed CommitBrief at a 200k-line legacy repo and got 90 findings I already know about.”

Recording a baseline

commitbrief --update-baseline

This runs a review and writes the current findings to .commitbrief/baseline.json instead of failing on them. From the next run on, anything in the baseline is dropped from the output, and only findings not in the baseline surface.

It’s user-private — it cannot hide a bug from review

.commitbrief/baseline.json is per-developer and gitignored (commitbrief setup --local and the review cache add .commitbrief/ to .gitignore; writing the baseline does not, so with --no-cache on a repo that never ran setup --local the file is not ignored until one of them runs). Once ignored, it is never committed and never propagates:

  • CI still sees everything. A CI runner has no baseline file, so it reviews the full diff — the baseline can’t weaken the gate.
  • The next reviewer still sees everything. Their checkout has no baseline either, or has their own.

So a baseline is local convenience only. A teammate cannot bake a bug into a shared baseline to slip it past review, because there is no shared baseline to bake it into. It quiets repeat noise for you without lowering the bar for anyone else.

Fingerprinting — survives code drift

Requires v1.19.0 or later. A baselined finding is identified by its fingerprint: a SHA-256 of file + rule id + enclosing symbol. Line number, title and severity are deliberately not part of it. Adding ten lines above a baselined finding shifts its line but not its fingerprint, and a model rewording the title between runs does not resurrect it. The symbol is the function or method the finding sits in, taken from git’s funcname rule for the hunk.

The file is .commitbrief/baseline.json, shape {"version":2,"fingerprints":[...]}, sorted. --update-baseline always writes this form and replaces the file rather than merging.

The identity is coarse by design. It ignores the title, so baselining one finding also hides a later, different finding with the same file, rule and symbol. A finding with no symbol (typically general.other) hides every finding of that rule in that file. If that is too wide, fix the finding or use an inline marker on the one line.

Upgrading a v1 baseline

A baseline written by an older binary ("version": 1) is still read, using the old file + severity + title formula, and CommitBrief prints a one-time warning. The migration is lossy: the old entries carry no rule id or symbol, so they cannot be converted. Re-run --update-baseline over the same range to write a v2 file. Any other version value is a hard error.

Turning it off

# Per-run: ignore the baseline for this invocation (review everything).
commitbrief --staged --no-baseline
# Per-config: disable baseline reads entirely.
review:
  baseline: false   # default true; --no-baseline is the per-run equivalent
commitbrief config set review.baseline false

With review.baseline: false the file is ignored on read; it still exists on disk until you remove it.

Inline suppression

When a single finding is a known false positive — or an accepted trade-off you don’t want re-flagged — drop a comment on the same line (or on the line directly above it):

const id = items[0].id; // commitbrief-ignore: list is guaranteed non-empty here

That line’s findings are removed from the output. Scope the suppression to one severity with a bracket:

eval(userInput); // commitbrief-ignore[high]: sandboxed; tracked in TICKET-123

commitbrief-ignore[high]: … drops only high-severity findings on that line; a critical finding on the same line still surfaces. A bare commitbrief-ignore: … drops findings of any severity.

Scoping to a rule

Requires v1.19.0 or later. A token with a dot is a rule id or a category glob:

query := "SELECT * FROM t WHERE id=" + id // commitbrief-ignore[sec.injection]: id is an int from our own router
// commitbrief-ignore[perf.*]: hot path measured, see TICKET-456
TokenDrops
noneEvery finding on the line
high (no dot)That severity only
sec.injectionThat rule id only
perf.*Every rule in that category

An unrecognised token does not fail the run. The marker falls back to unscoped, which drops everything on the line, and CommitBrief prints a warning so a typo is visible. Any commitbrief-ignore[token]: line counts as a marker, including [todo-1].

Markers are read from the added lines of the diff and keyed by file and line. Older versions let a marker leak across files; findings that were wrongly suppressed that way reappear after upgrading.

In remote pr

Requires v1.21.0 or later. remote pr applies inline suppression too, including the --no-post preview. A suppressed finding posts no comment and its open thread is resolved on the next run; --fail-on under --no-post judges the findings that remain. The baseline is not applied there, because it is user-private and absent in CI.

The : reason is part of the documented syntax (an empty reason still suppresses, but write one) and lands in the diff the next reviewer reads — so a suppression is never a silent override. It’s a note to the human reviewer explaining why this is fine, sitting right next to the code, reviewable like any other line. A suppression with no justification is one a reviewer can push back on in the same PR.

How this differs from --min-severity

It’s easy to confuse three things that all “make a finding go away.” They are not the same:

MechanismRemoves the finding?Affects --fail-on / --json?Scope
--min-severityNo — display onlyNo (the finding still counts and still appears in --json)Per run
BaselineYes — true removalYesUser-private, persists across runs
Inline commitbrief-ignoreYes — true removalYesOne line, lives in the code

--min-severity only hides lower-severity findings from the rendered view; they still count toward CI gating and still show up in JSON. Signal control genuinely removes the finding from the result. Reach for the baseline or a commitbrief-ignore comment when you want a finding gone from the gate, not just out of sight.

Removals are reported, never silent

Whatever you drop, CommitBrief tells you it dropped it:

  • A one-line stderr footer summarizes the run:

    3 baselined · 1 suppressed
  • The --json payload carries additive optional meta.baselined and meta.suppressed counts. These are additive — the JSON schema stays v1, so existing consumers are unaffected and new ones can read the counts:

    {
      "meta": { "baselined": 3, "suppressed": 1 },
      "findings": [ ... ]
    }

You always know how many findings were held back, even though the findings themselves are gone from the list. That visibility is the point: signal control trims noise loudly.

See also