feat(calibration): notify devs when EWMA k hits the guardrail clamp

gabogg commented

2026-09-22 14:07:33 +00:00

Owner

Problem (low priority)

The EWMA calibration clamps the exit multiplier k to the guardrail [0.90, 1.35] (occupancy_service.py:753, 941). When a legitimately-computed empirical k lands outside that band and gets clamped, nothing tells anyone — the clamp silently absorbs it. A persistent clamp-hit is a signal that this site's true baseline differs from the guardrail band (the band is currently biased to the primary mall, see #36), which the devs would want to know for a new/foreign deployment.

Suggested behaviour

When the pre-clamp empirical k falls outside [0.90, 1.35], record a clamp-hit event (cycle id, raw k, clamped k, direction) and surface it — dev-facing log at minimum, optionally an admin-panel indicator.
Repeated clamp hits over several business cycles should raise a louder signal ("guardrail band may be wrong for this site").

Priority

Low. Not blocking any deck KPI; it's an operability/observability improvement for multi-site use.

Acceptance criteria

A pre-clamp k outside [0.90, 1.35] produces a recorded clamp-hit event with raw and clamped values.
Clamp hits are visible to devs (log or admin surface).
Sustained clamp hits across N business cycles escalate the signal.

Surfaced during the grilling session on #36.

Triage resolution — 2026-09-23

This resolution supersedes conflicting original acceptance criteria.

The canonical operational exit-multiplier guardrail is [0.90, 1.35].
The [0.80, 1.30] whole-cycle ratio trust bounds are a separate concept.
This issue monitors actual clipping of a proposed smoothed EWMA multiplier;
an empirical ratio outside the operational band alone is not a clamp hit.

Keep this work low priority. Deliver durable diagnostic records and logs;
an admin-panel indicator is outside the initial scope. Repeated clipping
prompts investigation and does not prove the site's guardrail is wrong.

Acceptance:

Record every actual clamp hit with business-cycle identity, empirical
ratio, pre-clamp EWMA value, applied multiplier and lower/upper bound hit.
Cover both direct calibration and history recomputation without changing
the calibration mathematics, guardrail or trust-rule thresholds.
Escalate after three consecutive completed, trusted, automatically
calibrated business cycles hit the same bound.
A non-clamped, untrusted, missing or manually calibrated cycle breaks the
streak. A hit at the opposite bound starts a new streak.
Emit one escalation warning when the streak reaches three; subsequent
hits remain recorded without repeating the escalation warning.
Reprocessing a business cycle cannot count it twice. Historical corrections
recompute the streak without duplicating previously emitted warnings.
Deterministic tests distinguish an empirical outlier without EWMA clipping
from an actual clamp, and cover threshold, reset, direction changes,
reprocessing and historical corrections.

## Problem (low priority) The EWMA calibration clamps the exit multiplier `k` to the guardrail `[0.90, 1.35]` (`occupancy_service.py:753, 941`). When a legitimately-computed empirical `k` lands **outside** that band and gets clamped, nothing tells anyone — the clamp silently absorbs it. A persistent clamp-hit is a signal that **this site's true baseline differs from the guardrail band** (the band is currently biased to the primary mall, see #36), which the devs would want to know for a new/foreign deployment. ## Suggested behaviour - When the pre-clamp empirical `k` falls outside `[0.90, 1.35]`, record a clamp-hit event (cycle id, raw `k`, clamped `k`, direction) and surface it — dev-facing log at minimum, optionally an admin-panel indicator. - Repeated clamp hits over several business cycles should raise a louder signal ("guardrail band may be wrong for this site"). ## Priority **Low.** Not blocking any deck KPI; it's an operability/observability improvement for multi-site use. ## Acceptance criteria - [ ] A pre-clamp `k` outside `[0.90, 1.35]` produces a recorded clamp-hit event with raw and clamped values. - [ ] Clamp hits are visible to devs (log or admin surface). - [ ] Sustained clamp hits across N business cycles escalate the signal. Surfaced during the grilling session on #36. --- ### Triage resolution — 2026-09-23 This resolution supersedes conflicting original acceptance criteria. The canonical operational exit-multiplier guardrail is **[0.90, 1.35]**. The **[0.80, 1.30]** whole-cycle ratio trust bounds are a separate concept. This issue monitors actual clipping of a proposed smoothed EWMA multiplier; an empirical ratio outside the operational band alone is not a clamp hit. Keep this work low priority. Deliver durable diagnostic records and logs; an admin-panel indicator is outside the initial scope. Repeated clipping prompts investigation and does not prove the site's guardrail is wrong. Acceptance: - [ ] Record every actual clamp hit with business-cycle identity, empirical ratio, pre-clamp EWMA value, applied multiplier and lower/upper bound hit. - [ ] Cover both direct calibration and history recomputation without changing the calibration mathematics, guardrail or trust-rule thresholds. - [ ] Escalate after three consecutive completed, trusted, automatically calibrated business cycles hit the same bound. - [ ] A non-clamped, untrusted, missing or manually calibrated cycle breaks the streak. A hit at the opposite bound starts a new streak. - [ ] Emit one escalation warning when the streak reaches three; subsequent hits remain recorded without repeating the escalation warning. - [ ] Reprocessing a business cycle cannot count it twice. Historical corrections recompute the streak without duplicating previously emitted warnings. - [ ] Deterministic tests distinguish an empirical outlier without EWMA clipping from an actual clamp, and cover threshold, reset, direction changes, reprocessing and historical corrections.

gabogg added the

needs-triage

label

2026-09-22 14:07:33 +00:00

gabogg added

ready-for-agent

and removed

needs-triage

labels

2026-09-23 14:20:53 +00:00

gabogg referenced this issue

2026-09-23 16:29:51 +00:00

docs: align calibration glossary and record triage decisions #63

gabogg referenced this issue from a commit

2026-09-23 18:00:28 +00:00

docs: address PR #63 review — policy-free glossary, current #58 dependency

gabogg referenced this issue

2026-09-23 18:01:23 +00:00

docs: align calibration glossary and record triage decisions #63

gabogg referenced this issue

2026-09-23 18:01:26 +00:00

docs: align calibration glossary and record triage decisions #63

gabogg referenced this issue from a commit

2026-09-23 18:02:38 +00:00

docs: align calibration glossary and record triage decisions (#63)

gabogg changed title from ~~feat(calibration): notify devs when EWMA k hits the guardrail clamp (low priority)~~ to feat(calibration): notify devs when EWMA k hits the guardrail clamp

2026-09-27 16:37:02 +00:00

gabogg added the

low-priority

label

2026-09-27 16:37:06 +00:00

Rows
Columns

feat(calibration): notify devs when EWMA k hits the guardrail clamp #50

Problem (low priority)

Suggested behaviour

Priority

Acceptance criteria

Triage resolution — 2026-09-23