# HEARTBEAT.md

# Purpose

Heartbeat exists to maintain continuity,
not to demand attention.

The goal is:
- proactive awareness
- operational continuity
- timely escalation
- low-noise monitoring


---

# Core Principles

1. Silence is valid.
2. Usefulness beats visibility.
3. No proactive message without meaningful state change.
4. Do not interrupt unless interruption is valuable.


---

# Quiet Hours

Default quiet hours:
23:00 → 08:00

During quiet hours:
- suppress non-urgent proactive messages
- only escalate meaningful risks or deadlines


---

# Heartbeat Sources

Read:
- TODO.md
- CURRENT.md (if present)
- memory/heartbeat-state.json

Check:
- active tasks
- blocked tasks
- unresolved loops
- stale execution states
- upcoming deadlines


---

# Active Task Definition

Only these statuses are considered active:
- todo
- doing
- waiting
- blocked
- snoozed

Ignore:
- done
- cancelled


---

# Risk Evaluation

## P0
Immediate escalation:
- overdue critical tasks
- failed dependencies
- significant execution risk

## P1
Needs awareness:
- long inactivity
- waiting too long
- unclear next step
- pending user decision

## P2
Routine monitoring:
- no meaningful change
- no escalation needed

P2 should remain silent.


---

# Proactive Messaging Rules

Default mode:
Executive Secretary Mode

Limits:
- max 3 proactive messages/day
- minimum 1h between conversations
- minimum 4h between proactive messages
- no duplicate reminders within 4h


---

# Allowed Proactive Triggers

- blocked execution
- approaching deadlines
- unresolved open loops
- meaningful project updates
- external events requiring awareness
- critical system state changes


---

# Forbidden Proactive Behavior

Never:
- send messages for presence alone
- narrate heartbeat activity
- generate artificial check-ins
- force engagement
- repeatedly ask for attention


---

# Proactive Message Structure

When proactive messaging is necessary:

1. Situation
2. Current state / risk
3. Recommended action

Keep messages concise and actionable.


---

# Silent Behavior

If nothing meaningful requires escalation:
- remain silent
- or return `HEARTBEAT_OK`

Silence should feel calm,
not absent.