Confidence and enforcement

Not every pattern deserves to be enforced. Here is exactly how a convention earns it.

The tiers

The two numbers

0.95 — the confidence floor. At or above this score a derived convention is confirmed; below it, merely detected.

0.75 — the enforcement threshold. Below this score, a convention is recorded but never enforced. It is visible, it is evidence, and it stays out of your pull requests.

Both are named constants in the source rather than magic numbers, because a threshold that decides whether a pattern can be enforced at all should be greppable — and because it is quoted on this page, it is also pinned in docs.lock, so changing it fails the build until this page is updated too.

Derivation can never promote itself to pinned

This is the important one.

A deriver can produce detected or confirmed. It can never produce pinned. Pinning is a human decision, and a function that could return it would let derivation grant itself enforcement — which is exactly the boundary invariant 3 exists to hold: model and machine output stay out of the authoritative layer.

So the ladder only ever goes: the parser observes, a human decides.

What a convention is allowed to do

A convention finding is a warn, and it is advisory. It cannot block a merge.

That asymmetry is deliberate and permanent. A convention is an inference. A strong one — evidence-linked, support-counted, thresholded — but still something we worked out rather than something you declared. Blocking a merge on an inference is how a tool loses an argument it should have won.

If you want a pattern to block, that is a decision you make: pin it, or adopt the equivalent catalog rule.

Decay

A convention whose findings are repeatedly dismissed loses confidence. So does one the repository stops following. This is why dismissal requires a reason — the reason is not paperwork, it is the input to decay.

A convention that decays below the enforcement threshold stops appearing in reviews on its own, without anyone having to remember to remove it. Standards that quietly stopped being standards stop being enforced.

A NaN would be invisible, so there are none

A small implementation detail with an outsized consequence: a ratio with an empty denominator returns 0, never NaN. A convention with a NaN score compares false against every threshold and simply never appears — the hardest kind of absence to notice. It is worth knowing that the failure mode was considered, because “the convention silently did not exist” is not something you could have debugged from the outside.