diff --git a/packages/mosaic/framework/guides/WAKE-DOCTRINE.md b/packages/mosaic/framework/guides/WAKE-DOCTRINE.md new file mode 100644 index 00000000..9be44cd2 --- /dev/null +++ b/packages/mosaic/framework/guides/WAKE-DOCTRINE.md @@ -0,0 +1,31 @@ +# 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.