The alert ledger you shipped on Jul 21Review

A week after shipping the alert dedup + auto-resolve layer (commit d9b37fc), the ledger is doing its job: one live incident tracked in alert-state.json instead of ~170 duplicate 🚨 tasks. Today you review how to read it — and why resolved incidents vanish from it.

The ledger (PDB/data/alert-state.json) is a statement of CURRENT reality, not a history log. Each entry is one open incident, keyed by a stable dedup_key like 'jobhunt-sweep'. When the same failure fires again, raise_alert() bumps that entry's count and last_seen instead of creating a second Things task. When the watcher sees recovery, resolve_alert() completes the 🚨 task and deletes the entry entirely.

That deletion is the subtle part. Last week plan-day failed five mornings in a row — the ledger held a plan-day incident with count climbing to 5. Open the file today and it's not there. That's not data loss; that's the design: the incident closed itself when Jul 27's run came back green. If you want history, it's in git — the ledger file is committed, so 'git log -p data/alert-state.json' replays every incident's lifecycle.

The fail-safe bias is worth remembering: if the ledger or Things API errors mid-raise, the code falls back to firing a fresh task anyway. The system is allowed to duplicate in a crash; it is never allowed to stay silent. That's why a stray duplicate is a curiosity, not an emergency.

Worked example

Read the live ledger, then replay the plan-day incident's whole life from git:

cat ~/Claude/PDB/data/alert-state.json | python3 -m json.tool

cd ~/Claude/PDB && git log --oneline -p -- data/alert-state.json | grep -A3 'plan-day'

• Pretty-prints the current ledger. Right now: one entry, 'jobhunt-sweep', count 1, opened Jul 27 — the only genuinely live incident on your board.
• Walks the file's git history and pulls the plan-day entries — you'll see the incident appear, its count tick up each failed morning, then the whole entry deleted in the commit where it auto-resolved.

Gotchas

• An empty ledger does NOT mean the alert system is off — it means nothing is currently broken. Absence of entries is the healthy state.
• Don't hand-edit alert-state.json to 'clear' an alert — complete the Things task or let the watcher resolve it. A hand-deleted entry with its Things task still open desyncs the two.
• count=1 with an old opened_at means a failure fired once and never recurred — different from a high count (chronic). Read count before deciding how much to care.