stack/packages/mosaic/framework/guides/WAKE-DOCTRINE.md

Wake Doctrine

This is the canonical fleet wake/heartbeat doctrine, extracted verbatim from the ratified converged wake/heartbeat design (docs/scratchpads/heartbeat-planning/CONVERGED-DESIGN.md). It governs when agents wake and how a wake is delivered, consumed, and retired.

Wake only on a real, un-consumed, lane-relevant obligation. Fixed-interval heartbeats are forbidden as the primary wake mechanism; they survive only as a per-class fallback cadence bounded by urgency SLO, never as the steady state.

A digest is cumulative state since the last CONSUMED ack, not an event delta. It is self-orienting (who / lane / board-head) and decides the no-op case with zero tool calls. Actionable facts are claims-to-verify carrying a hard locator (repo/issue#/SHA/file); self-sufficiency never exempts a consequential action from its live gate.

Consumption is a consumer act, not a delivery act. Split RECEIVED (delivery; wake_id-deduped) from CONSUMED (durable capture of a contiguous prefix). Never ack-then-crash-before-capture. Acks are local-write-only and cumulative; a turn never blocks on the network to ack.

Durability is unconditional; coalescing is optional. Every delivered class is durably stored and acked; only machine digest wakes coalesce. A parked or absent pane must never lose a human or peer message.

Park is two-phase: flush-and-checkpoint (recording the CONSUMED cursor) before /clear.

Liveness is independent of work-triggering: an off-host dead-man beacon, alarming on absence — never a same-host sibling, never a pane scrape.

Retire the old net LAST: run new alongside old, compare ledgers, and cut over only when the per-host safety vector (no-op-rate ↓ AND canary-FN=0 AND source-parity-inventory-complete AND reconcile=0 AND p95 event→CONSUMED≤SLO AND p95 event→qualified-action≤SLO) passes.