Adopting CommitBrief on an existing codebase

Everything on this page assumes you already have a codebase CommitBrief has never reviewed — not a fresh repo. Point a gate (--fail-on or guard) at it and the first run can surface every pre-existing issue in the diff you feed it, none of which have anything to do with the change you’re actually trying to land. That’s what signal control — baselining and inline suppression — exists to fix.

Step 1: record a baseline

--update-baseline records the findings from whatever diff you point it at — not “the codebase,” since CommitBrief only ever reviews a diff. --staged is empty on a clean tree, so it won’t capture anything; to baseline the codebase’s existing history, review a wide range with commitbrief diff instead, picking a starting point from before you adopted CommitBrief (the repo’s first commit, or a tag that predates it):

commitbrief diff <first-commit-or-tag>...HEAD --update-baseline

This writes .commitbrief/baseline.json — the findings that review call returns, fingerprinted by file path, severity, and title (not line number, so the fingerprint survives a later reformat or an unrelated edit nearby). From this point on, any finding that matches something already in the baseline is dropped before it reaches you or a local gate — it’s still real, just not new. Anything outside the range you picked was never recorded, and will still surface as new. Each --update-baseline run replaces the file wholesale rather than merging into it — running it again on a different range discards whatever the previous run recorded, it doesn’t add to it.

On a genuinely large repo, reviewing the whole history in one call can overflow the provider’s context window. CommitBrief doesn’t check for that by default — it’s an opt-in guard (guard.token_preflight, off by default); turn it on and an oversized prompt asks you to confirm (TTY) or aborts outright (no TTY) instead of going straight to the provider and coming back as a raw error. Either way, if a single range doesn’t fit, the options are a model with a bigger context window or a narrower range — not baselining in slices: because each run replaces the file, running --update-baseline once per slice leaves only the last slice’s findings recorded, and whatever a narrower range excludes keeps surfacing as new on every later run, same as any other unbaselined range. See Token preflight for the full behavior.

The baseline file is meant to be per-developer and gitignored, not committed and shared — each contributor’s local baseline reflects what they’ve already chosen to defer, not a team-wide amnesty list.

Step 2: turn the gate on locally

With the baseline in place, wire up a pre-commit hook. Because the baseline lives in your local, gitignored .commitbrief/, only a gate running on your machine sees it — only new findings (not in your baseline) can trip the hook now.

CI doesn’t see your baseline

A CI runner checks out a fresh clone with no .commitbrief/baseline.json — baselining is user-private by design, so --fail-on in CI or guard still sees every pre-existing finding in whatever diff it’s pointed at, not just what’s new. Two ways to keep CI from repeating the noise you already baselined locally, without either mechanism seeing your local file:

• Scope the CI diff to the pull request itself (main...feature, not the repo’s full history) — a gate that only reviews the PR’s own diff never touches pre-existing findings that live outside it. This is the mechanism that actually holds up over time in CI.
• Suppress one specific, deliberate finding inline (Step 3 below) — but only in the PR that touches that line, since a marker only suppresses on the diff’s added lines.

Step 3 (optional): suppress specific findings inline

If you want to silence one specific, deliberate finding — say, a pattern you’ve decided is intentional — annotate it in the code itself, in the same change that introduces or edits that line:

// commitbrief-ignore: intentional — see the design doc linked in the PR
// commitbrief-ignore[high]: only suppresses high-severity findings at this line

This only works because the marker sits on a line the diff is adding: suppression is scanned off added lines only, not context or untouched code. So it silences the finding in the review that introduces the marker — including a CI gate on that same PR — but it is not a standing, permanent exemption. A later PR that edits nearby code without touching the marker line, or that reintroduces the same pattern elsewhere, will surface the finding again; you’d need a fresh marker on whatever line changed. Unlike the baseline, this requires a visible reason in the diff, so a reviewer sees why something was silenced, not just that it was. Both mechanisms are explained in full — the exact fingerprinting rule, how to turn baselining off per run (--no-baseline) or by default (review.baseline: false), and the bracket-scoped suppression syntax — in Signal control.

Removals are never silent

Both mechanisms report what they removed rather than hiding it: the terminal footer shows a count (3 baselined · 1 suppressed), and --json carries the same numbers in meta.baselined / meta.suppressed. If a gate is passing and you’re not sure why, that footer — or those two fields — is where to look before assuming nothing was found.

See also

• Signal control — the full baseline and suppression reference: fingerprinting, config keys, exact JSON fields.
• Review before you commit — installing a hook once the baseline is in place.
• Gate CI on review findings — --fail-on and guard; neither sees your local baseline, only inline suppressions and whatever diff range the gate is pointed at.