State the rule that decides how a new AG measure gets handled (#991)

[erikdarlingdata]

Last one on this thread. Doc-only, no logic change.

The gap

The AG sync doc block ended up carrying two superficially similar measures with opposite prescriptions — gate drain-time (#1703), never use commit deltas (#1708) — and no stated reason for the difference. That is the setup for someone adding a new AG measure and picking whichever precedent they happened to read first.

The discriminator

ag-fixture-builder named it while closing out their own evidence file, and it is the right one: the failure direction, not the column.

the reading…	do this	why
fails in one direction (drain-time: reassuring, and only while suspended)	gate it	the may-fire-never-clear rule suppresses exactly the direction that would wrongly clear an alarm
fails in both directions under different conditions (commit deltas: silent while suspended, loud on a quiet healthy replica)	don't use it	no directional gate helps — suppressing the reassuring half leaves the false-alarm half, so gating converts a silent failure into a noisy one rather than a correct one

That is why drain-time got gated and commit deltas got banned. The file now says so, instead of leaving two special cases to be pattern-matched.

The transferable part

Every measured value in this area moved at least once during the work — MS Learn's documented lag behavior, the latch timing, the drain estimate, the lag baseline under load versus idle — while the direction-based rules never moved once. When the underlying behavior is documented wrong and the measurements are load-dependent, reason about which way a reading can lie rather than about its magnitude. Direction is what survives the numbers being wrong, and in this file the numbers were wrong repeatedly, mine included.

Testing

Darling suite green: 3252 passed, 0 failed.

🤖 Generated with Claude Code