# Phase 12: Telemetry & Heartbeat - Context

**Gathered:** 2026-03-26
**Status:** Ready for planning
**Mode:** Auto-generated (infrastructure phase — discuss skipped)

<domain>
## Phase Boundary

Heartbeat reports checksum verification health per symbol with LOUD Telegram alerts on any integrity failure, and all checksum operations are logged locally for post-mortem analysis.

Requirements: TELEM-01, TELEM-02, TELEM-04

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

All implementation choices are at Claude's discretion — infrastructure phase.

Key context:

- Heartbeat runs every 5 min via systemd timer (`scripts/health_heartbeat.py`)
- Heartbeat checks are modular: each in `scripts/heartbeat/checks/` as a separate module
- Phase 7 established exception-only display pattern — clean symbols show single summary line
- ChecksumRegistry (Phase 9) stores verification records queryable by symbol
- Seeder (Phase 10) already writes checksum pass/fail/skip to state file and registry
- TELEM-02: LOUD alert = `disable_notification=False` in Telegram send
- TELEM-04: Local telemetry log = append-only file for all checksum operations
- Follow existing feedback memory: wire ALL TG telemetry to local log file (feedback-local-telemetry-log.md)

</decisions>

<code_context>

## Existing Code Insights

### Reusable Assets

- `scripts/heartbeat/checks/` — 14 existing check modules
- `scripts/heartbeat/checks/CLAUDE.md` — Documents shared results dict interface
- `python/opendeviationbar/checksum_registry.py` — ChecksumRegistry (Phase 9)
- `python/opendeviationbar/notify/telegram.py` — Telegram notifications
- `scripts/heartbeat/formatter.py` — Formats heartbeat message sections

### Established Patterns

- Each check module has `run_check(results: dict) -> None`
- Results dict shared across all checks, formatter reads it
- Exception-only display from Phase 7: clean = summary line, issues = expanded
- Heartbeat checks CLAUDE.md documents the interface

### Integration Points

- New check module: `scripts/heartbeat/checks/checksum.py`
- Formatter: add checksum health section to heartbeat message
- Local log: `~/.cache/opendeviationbar/checksum-telemetry.jsonl`

</code_context>

<specifics>
## Specific Ideas

No specific requirements beyond ROADMAP.

</specifics>

<deferred>
## Deferred Ideas

None.

</deferred>
