Module ratchet 

Betterer-style committed quality snapshot for codelore check --ratchet.

The snapshot file .codelore-ratchet.toml lives in the target repo and is committed by the user. Three semantics:

1. No snapshot → measure current values, write the file, exit 0. Print “ratchet initialized”.
2. Snapshot exists, any metric WORSE → exit 1 listing regressions. The file is NOT rewritten on failure (preserve the committed baseline).
3. Snapshot exists, all same-or-better → rewrite the file with the improved values (tighten the ratchet), exit 0, print which keys tightened.

The design follows the Betterer pattern: the ratchet file is the contract and git history is the audit trail — commit the file; your gate history is then minable from git.

The file also carries a ratchet_schema key (see [RATCHET_SCHEMA]) so a baseline written under one definition of a gated metric is never silently compared against a later, redefined one — a schema mismatch (including a pre-fix file with no key at all) is treated as case 1, with a one-time warning explaining the reset.

Structs

RatchetMetrics

Observed values for the three ratchet metrics, extracted from gate outputs.

RatchetRegression

A single metric that regressed.

RatchetSnapshot

Persisted snapshot TOML structure.

RatchetTable

The [ratchet] TOML table.

Enums

Direction

Per-metric direction: which direction is “better”?

RatchetOutcome

Outcome of evaluate_ratchet.

Constants

RATCHET_FILENAME

Filename of the ratchet snapshot, written to the repo root.

RATCHET_METRICS

Canonical ratchet metrics with their improvement directions.

Functions

evaluate_ratchet

Compare current metrics against the snapshot and determine the outcome.

format_ratchet_outcome

Format the ratchet outcome as a human-readable message for stdout/stderr.

ratchet_path

Path of the ratchet snapshot file.

read_snapshot

Read the ratchet snapshot from disk.

snapshot_from_metrics

Derive a RatchetSnapshot from the current observed metrics.

write_snapshot

Write the ratchet snapshot to disk, overwriting any existing file.