Baselines

A baseline records the diagnostics a project already has, so rigor check can stay silent about them and surface only what is new. It is the pragmatic on-ramp for adopting Rigor on an existing codebase: you do not have to reach zero diagnostics before the check becomes useful in CI.

The baseline file

A baseline is a YAML file — .rigor-baseline.yml by convention — listing buckets of known diagnostics:

version: 1
ignored:
  - file: app/models/user.rb
    rule: call.undefined-method
    count: 3
  - file: app/lib/legacy.rb
    rule: call.argument-type-mismatch
    count: 1

Each row is a bucket keyed by (file, rule), with a count of how many diagnostics of that rule the file is allowed. An optional message: field (a regular-expression source) narrows a bucket to call sites whose message matches.

You do not hand-write this file — rigor baseline generate produces it.

Turning a baseline on

A baseline file sitting in the project is dormant until something activates it — presence alone does nothing. Activate it with the config key:

baseline: .rigor-baseline.yml

or per run with rigor check --baseline=PATH. --no-baseline ignores a configured one for a single run, and baseline: false in a config file disables a baseline inherited through includes:.

All-or-nothing per bucket

When a baseline is active, each bucket is matched whole:

• current count ≤ recorded count — every diagnostic in the bucket is silenced.
• current count > recorded count — every diagnostic in the bucket surfaces, not just the excess.

The reasoning: line numbers drift as a file is edited, so a partial match cannot reliably point at which diagnostic is the new one. Surfacing the whole bucket asks you to review that rule × file together.

The baseline filter runs last — after # rigor:disable comments and the severity profile. A baseline never resurrects a diagnostic another layer has already suppressed.

The rigor baseline commands

Command	Use
rigor baseline generate	Write a fresh baseline from the current diagnostics. Refuses to clobber an existing file without --force.
rigor baseline regenerate	Rewrite unconditionally — run it after fixing diagnostics so the file shrinks.
rigor baseline dump	Print the baseline, filterable with --rule and --file.
rigor baseline drift	Show how buckets have moved — --only=over for buckets that grew, reducible for ones you have already improved past, cleared for empty ones.
rigor baseline prune	Drop buckets that match nothing any more. --dry-run previews.

generate and regenerate take --match-mode=rule (the default — one bucket per file × rule) or --match-mode=message (a bucket per distinct message: more precise, more churn).

Working a baseline down

rigor triage summarises a diagnostic stream — rule distribution, the files with the most diagnostics, and heuristic hints about likely causes — so you can decide what to tackle first:

rigor triage

It is advisory and always exits 0. The intended loop is triage to prioritise → fix or suppress a rule → rigor baseline regenerate to shrink the file. The rigor-baseline-reduce skill walks this loop interactively.

To make CI fail when the baseline grows, add --baseline-strict to rigor check.