chore(self-scan): a baseline entry goes stale silently when a metric decreases

[dekobon]

Summary

A .bca-baseline.toml entry goes stale silently whenever a change lowers
a baselined metric. The filter suppresses a violation only while the live
value stays at or below the recorded one, so a decrease never reddens the
gate and nothing forces a refresh. The recorded value then describes a tree
that no longer exists, and the gate is looser than intended until someone
regenerates for an unrelated reason.

Concrete instance

src/spaces/compute.rs::metrics_inner, halstead.effort:

• recorded on main: 119147.7514530567
• live measurement: 116715.6053686016

Traced to d4479cdf ("fix: address the PR #1446 review findings",
2026-09-13), which changed compute.rs after the last baseline refresh
(bcd62812). Because the value fell, make self-scan stayed green and the
baseline-refresh discipline in AGENTS.md was never triggered.

It surfaced only because #1407 on fix/batch-2026-09-13 refreshed the
baseline for an unrelated Kotlin entry, and
make self-scan-write-baseline-headroom regenerates the file wholesale, so
the stale line came along as a rider.

Why it matters

The gap between recorded and live is headroom nobody chose. Between
d4479cdf and the next regeneration, metrics_inner could have grown by
~2400 halstead.effort — a real regression — without the gate noticing,
because it would still have measured below the stale recorded value.

The looser the entry, the longer it stays stale, so the failure compounds
quietly.

Options

1. Fail the gate on a decrease too, requiring a refresh in the same
   change. Strictest, and symmetrical with the increase rule already in
   AGENTS.md. Cost: a refresh commit on changes that improved a metric,
   which is friction for the good case.
2. Warn on a decrease without failing, so the drift is visible in CI
   output and someone can batch the refresh.
3. Periodic regeneration — a scheduled job that regenerates and opens a
   PR when the file moves, the way the quarterly mutation and benchmark jobs
   already work.

Option 2 is probably the cheapest honest fix; option 3 catches it without
any per-change friction.

Related

• fix(metrics): six ABC and cyclomatic fixes #1459 — the PR where it surfaced; the corrected value rides in ef20b2ca
  and is named in that commit's message.
• AGENTS.md, "Baseline-refresh discipline" — currently written entirely in
  terms of a metric moving past its recorded value.

Resolution

Option 2 — warn on a decrease, do not fail the gate. Implemented in
aa649899 (branch fix/issue-1465).

filter_by_baseline folds every Coverage::Covered classification into
a baseline::StaleTally, which counts entries whose live value has
moved past the recorded one in the improving direction and emits one
aggregated stderr warning per run, naming the count and the worst entry
by relative drift. Direction is decided by breaches_limit(recorded, value, lower_is_worse) — the ratchet's own predicate with its arguments
swapped — so both polarities are handled and the two cannot disagree. An
entry sitting exactly on its record stays silent. Exit codes and the
kept violation set are unchanged.

The fix covers only half the class. A function that stopped
breaching its threshold entirely produces no Violation, so it never
reaches classify and its stale entry remains invisible to this code
path by construction. Option 3 — a scheduled make self-scan-write-baseline-headroom plus git diff --exit-code .bca-baseline.toml, opening a PR when the file moves — is what closes
the remainder, and is deliberately left for a follow-up issue.

Documented in CHANGELOG.md, in AGENTS.md's "Baseline-refresh
discipline" (which now carries the decrease direction), and in a new
"The stale-entry warning" section of recipes/baselines.md. The
improved bucket description in that recipe no longer calls the state
"harmless".

[dekobon]

Implemented option 2 (warn, do not fail) in 08b2bb4e on
fix/issue-1465.

What changed

filter_by_baseline folds every Coverage::Covered classification into
a new baseline::StaleTally. An entry counts as stale when the live
value has moved past the recorded one in the improving direction —
below it for a higher-is-worse metric, above it for the lower-is-worse
mi.* family. The direction test is breaches_limit(recorded, value, lower_is_worse): the same predicate classify's ratchet uses, with its
arguments swapped, so the two cannot drift apart on metric direction.
Equality breaches neither way, so a freshly written baseline never warns
about itself.

The run emits one aggregated stderr line, naming the count and the
single worst entry by relative drift:

warning: 3 baseline entries improved past the recorded value (worst:
src/spaces/compute.rs::metrics_inner halstead.effort 119147.75 →
116715.61); that gap is gate headroom nobody chose, so refresh with
`--write-baseline`. …

One line rather than one per entry because this repository's own
baseline carries 241 of them and the response to any number is the same
wholesale refresh. Exit codes, the kept set, and the bca: filtered N violations via baseline count are unchanged — this is a diagnostic
only.

No new flag. The warning is a single line on a stream that already
carries the provenance warning and the filter count, so there is nothing
to suppress; a flag would have been public CLI surface bought for
nothing.

What this does not fix

A function that stopped breaching its threshold entirely never
produces a Violation, so it never reaches classify and cannot be
counted here. Its entry stays in the file, inert and invisible. This
fix covers only decreases that remain above the limit. That limitation
is stated in the emitted text itself, in the CHANGELOG entry, in
AGENTS.md, and in a new "The stale-entry warning" section of
recipes/baselines.md, so nothing reads as if the class were closed.

Option 3 is the follow-up that closes the rest and is worth filing
separately: a scheduled job running make self-scan-write-baseline-headroom
followed by git diff --exit-code .bca-baseline.toml, opening a PR when
the file moves. That catches both directions and the fully-resolved
entries, with no per-change friction, the way the quarterly mutation and
benchmark jobs already work. It is deliberately not implemented here.

Verification

Eight unit tests in baseline_tests.rs and two integration tests in
tests/check/check_baseline.rs (improved_function_still_passes
extended; unchanged_function_at_its_recorded_value_warns_nothing
added). Each was verified by perturbing the production line rather than
by passing alone — swapping breaches_limit's arguments, dropping the
lower_is_worse flag, removing the guard, inverting the
worst-tracking comparison, and ranking by absolute instead of relative
drift. Every perturbation is caught, and the parsed failure list agreed
with the process exit status in all ten runs.

make pre-commit reports BCA_GATE: pass. The repo's own 241-entry
baseline emits no warning at either tier — make self-scan and make self-scan-headroom are byte-unchanged — which is the expected reading
now that 333e258b corrected the metrics_inner entry this issue was
filed against.

[dekobon]

Correction to the hash above: the commit is aa649899 (amended after a review pass replaced relative_drift's zero-record special case with a single delta / max(|recorded|, |value|) ratio — bounded in [0, 1], comparable across metric scales, and with no branch to leave untested).