---
phase: 03-heartbeat-telemetry-overhaul
plan: 01
subsystem: monitoring
tags: [stathera, heartbeat, telegram, clickhouse, telemetry]

requires:
  - phase: 02-midnight-preflight-verification
    provides: "Midnight crossover trade ID verification for sidecar anchoring"
provides:
  - "Unified per-symbol Stathera check (no intra-day/adjacent-day classification)"
  - "LOUD Telegram alert on new today gaps with exact trade ID details"
  - "stathera_per_symbol result key for per-symbol gap/overlap counts"
affects: [03-02-PLAN, heartbeat-formatter, heartbeat-stathera]

tech-stack:
  added: []
  patterns:
    ["Unified per-symbol Stathera query replacing classification-based split"]

key-files:
  created:
    - tests/test_heartbeat_stathera.py
  modified:
    - scripts/heartbeat/checks/stathera.py
    - scripts/heartbeat/formatter.py

key-decisions:
  - "Removed intra-day/adjacent-day/backfill gap classification entirely -- a gap is a gap (TELEM-01)"
  - "Today-gap LOUD alert suppressed when kintsugi is actively healing (prevents noise during repairs)"
  - "Per-symbol breakdown shows top 5 pairs sorted by gaps DESC then overlaps DESC"

patterns-established:
  - "stathera_per_symbol dict maps SYMBOL@THRESHOLD to {gaps, overlaps} for downstream consumers"

requirements-completed: [TELEM-01, TELEM-04]

duration: 5min
completed: 2026-03-21
---

# Phase 3 Plan 1: Unified Stathera Check Summary

**Unified per-symbol Stathera continuity check replacing intra-day/adjacent-day classification, with LOUD Telegram alert on new today gaps**

## Performance

- **Duration:** 5 min
- **Started:** 2026-03-21T14:50:24Z
- **Completed:** 2026-03-21T14:55:09Z
- **Tasks:** 2
- **Files modified:** 3 (+ 1 created)

## Accomplishments

- Replaced confusing 3-category gap classification (intra-day, adjacent-day, backfill) with unified per-symbol results
- Added LOUD Telegram alert (TELEM-04) that fires within 5 min when new gaps appear in today's bars, with exact (symbol, threshold, tid_delta, trade ID range)
- Alert automatically suppressed when kintsugi is actively healing (prevents noise)
- Formatter updated to show top 5 per-symbol anomaly pairs with clean summary

## Task Commits

Each task was committed atomically:

1. **Task 1: Unify Stathera check to per-symbol results and add today-gap LOUD alert** - `5104165` (test: TDD RED) -> `534d506` (feat: TDD GREEN)
2. **Task 2: Update formatter for unified per-symbol Stathera display** - `bc71947` (feat)

## Files Created/Modified

- `scripts/heartbeat/checks/stathera.py` - Unified per-symbol Stathera query, today-gap LOUD alert via send_telegram
- `scripts/heartbeat/formatter.py` - Per-symbol breakdown display replacing 3-category classification
- `tests/test_heartbeat_stathera.py` - 5 tests covering unified output, LOUD alert, kintsugi suppression, alert details

## Decisions Made

- Removed all gap classification (intra-day, adjacent-day, backfill) -- a gap is a gap regardless of location (TELEM-01)
- Today-gap LOUD alert requires both gap_delta > 0 AND not kintsugi_healing to fire
- Per-symbol breakdown sorted by gaps DESC, overlaps DESC with top-5 cap

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- stathera_per_symbol result key available for Plan 2 (yesterday completion + junction telemetry)
- LOUD alert infrastructure in place for reuse by future checks
- All backward-compat aggregate keys (stathera_gap_count, stathera_overlap_count, deltas) preserved

---

_Phase: 03-heartbeat-telemetry-overhaul_
_Completed: 2026-03-21_
