# Differential lint baselines

The lint workflow retains complete `clang-tidy.txt` and `shellcheck.txt` logs,
then uses `scripts/compare_lint_baseline.py` to block only diagnostic identities
that are not in the reviewed baselines in this directory.

An identity consists of the project-relative path, severity, rule, and message.
Line and column are retained as evidence but excluded from identity so unrelated
line movement does not turn reviewed debt into a new warning. Duplicate header
diagnostics emitted through several translation units collapse to one identity.

Baseline entries are not blanket suppressions. Every entry must have status
`accepted-risk` and either a non-empty inline `rationale` or a `rationale_ref`
into the baseline's reviewed `rationales` map. To update a baseline:

1. Download and inspect the complete lint artifact from CI.
2. Fix actionable diagnostics where practical.
3. Add only intentionally deferred identities with a concrete rationale.
4. Record the reviewer and review timestamp.
5. Run the comparator locally and confirm that a synthetic new diagnostic still
   exits with status 1.

Vendored dependencies and downloaded benchmark corpora are outside the
first-party ShellCheck scope. The clang-tidy lane analyzes production `src/*.cpp`
translation units using the checked-in `.clang-tidy` configuration.