Skip to content

The ratchet

A pawl is the part of a ratchet that stops it slipping backward. Pawl does the same for a codebase: the findings a repo has when it adopts the standard are recorded once, and from then on quality can only move forward.

The ratchet over eleven commitsThe number of findings the baseline allows starts at 24 and steps down to 20, 16 and 11 as the code improves. It never goes back up. Findings stay at or under it. At commit 8 a change would have raised findings to 19, above the 16 allowed, so the check failed and it did not land.01020New findings: check failspawl baselinecommits →
Allowed by the baselineFindingsBlocked change

.pawl/baseline.json records how many findings of each rule each file had when the repo adopted the standard. pawl init writes it. Commit it.

.pawl/baseline.json
{
"version": 1,
"findings": {
"src/legacy.ts": {
"@typescript-eslint/no-explicit-any": 1,
"@typescript-eslint/prefer-for-of": 1,
"biome:correctness/noInnerDeclarations": 1,
"no-var": 2
},
"src/server.ts": {
"eqeqeq": 1
}
},
"suppressions": {}
}
  • Findings within those counts are allowed.
  • Anything beyond them fails the check.
  • A file that gains a disable comment (biome-ignore, eslint-disable, @ts-ignore, @ts-expect-error, @ts-nocheck) fails with pawl/no-new-disable.

That last rule matters most when an agent writes the code: switching a check off is not a way past it.

When the code improves, pawl check says so:

No new findings.
2 existing findings allowed by the baseline.
The code has fewer findings than the baseline allows. Run "pawl baseline" to lock that in.

Run pawl baseline to record the lower counts, and commit the file. From then on the repo cannot slip back past the improvement.

pawl baseline records whatever the code has at that moment. A team can also use it to accept findings on purpose, and that shows up in review as a change to .pawl/baseline.json.

Counts are per file and rule, not per line, so moving code around does not break the baseline, and neither do edits or merges.

The cost is that when a file goes over its count, every finding of that rule in the file is shown, because pawl cannot tell which one is new.

MIT licensed. Made by santi020k.