# Baseline

When adopting skillsaw on an existing project, you may have many
pre-existing violations. The **baseline** feature lets you snapshot
current violations so that `skillsaw lint` only reports *new* ones —
existing violations are accepted and won't cause failures.

## Creating a Baseline

Generate a `.skillsaw-baseline.json` from the current violations:

```bash
skillsaw baseline
```

By default, the baseline captures warnings and errors. A configured
`fail-on: info` also includes INFO findings, so the baseline accepts the
findings that fail that threshold. If you set the threshold only on the
lint command line, opt in when creating or refreshing the baseline:

```bash
skillsaw baseline --include-info
skillsaw lint --fail-on info
```

The baseline file should be committed to your repository so that all
contributors share the same accepted set of violations.

Before creating a baseline, take a moment to triage large scans by rule.
If many findings share a common repository convention (like a generated
data folder or custom terminology), configuring the rule in
[`.skillsaw.yaml`](configuration.md#rule-options) is usually better than
baselining — it handles future files automatically and keeps your baseline
clean.

## How It Works

Once a `.skillsaw-baseline.json` file exists (next to `.skillsaw.yaml` or
in the repo root), `skillsaw lint` automatically loads it and subtracts
matching violations from the output. Only new violations are reported.
Fatal infrastructure violations such as `repository-path-error` are not
written to the baseline and can never be suppressed by one. The same
goes for advisory `deprecated-rule` notices: baselining one would
permanently hide the warning that a rule is going away, so they are
never written and never suppressed — remove the deprecated rule from
your config to clear the notice instead.

Violations are matched by a **content hash** — a fingerprint built from
the rule ID, file path, and the content of the source line (not the line
number). This means the baseline survives line drift: if you add lines
above a baselined violation, the fingerprint still matches because the
content hasn't changed.

If you reformat or rewrite a line, the fingerprint changes and the
violation resurfaces for a fresh look — which is the correct behavior.

## Ratchet Rules

Some rules measure a numeric value (token count, instruction count,
actionability score) rather than flagging a specific line. These rules
use **ratchet** behavior: the baseline records the value at the time it
was created and only suppresses violations that are equal to or *better*
than the baseline. If the value gets worse, the violation is reported.

For example, if `context-budget` records 5,000 tokens at baseline time:

- Shrink the file to 4,800 tokens → **suppressed** (improvement)
- Grow the file to 5,200 tokens → **reported** (regression)
- Get under the limit entirely → violation disappears, baseline entry becomes stale

Rules with ratchet behavior:

| Rule | Metric | Baseline acts as |
|------|--------|-----------------|
| `context-budget` | token count | ceiling (can't increase) |
| `content-instruction-budget` | instruction count | ceiling (can't increase) |
| `content-actionability-score` | actionability score | floor (can't decrease) |
| `agentskill-unreferenced-files` | unreferenced files in a collapsed directory | ceiling (can't increase) |

Every other finding, including that rule's per-file ones, uses fingerprint
matching — the violation is suppressed as long as the source line content
hasn't changed. A directory finding and the per-file findings it stands in
for cover each other: a baseline that lists the files keeps suppressing the
directory, and one that lists the directory keeps suppressing the files
while they stay under its count.

## Ignoring the Baseline

Run lint without baseline filtering:

```bash
skillsaw lint --no-baseline
```

## Stale Entries

When you fix a baselined violation, its baseline entry becomes **stale**.
Skillsaw reports stale entries so you know the baseline can be refreshed:

```
Baseline: 3 stale entries (violations resolved since baseline was set)
  Run `skillsaw baseline` to update.
```

Run `skillsaw baseline` again to regenerate the file without the
resolved violations.

## Baseline and Fix

The `skillsaw fix` command ignores the baseline. The baseline only affects
`lint` reporting and exit codes — if you explicitly ask to fix, baselined
findings are eligible too.

## Workflow Example

A typical adoption workflow:

```bash
# 1. Set up skillsaw
skillsaw init

# 2. See what violations exist
skillsaw lint

# 3. Accept them as the baseline
skillsaw baseline

# 4. Lint now passes — only new violations will fail
skillsaw lint  # exit 0

# 5. Over time, fix violations and re-baseline
skillsaw baseline  # updates the file with fewer entries
```

## Baseline File Format

The `.skillsaw-baseline.json` file is a JSON document:

```json
{
  "version": "1",
  "generated_by": "skillsaw 0.10.1",
  "generated_at": "2025-05-27T12:00:00+00:00",
  "violations": [
    {
      "fingerprint": "a1b2c3d4e5f6g7h8",
      "rule_id": "content-weak-language",
      "file_path": "CLAUDE.md",
      "line": 42,
      "message": "Weak language: 'try to'",
      "severity": "warning"
    }
  ]
}
```

The `fingerprint` field is the content hash used for matching. The
`line` field is stored for human readability but is not part of the
match key — violations are matched by content, not position.