From 61002e4626bf6e9d2643944ffa102a9745da0cec Mon Sep 17 00:00:00 2001 From: mosaic-coder Date: Sat, 25 Jul 2026 16:01:47 -0500 Subject: [PATCH 1/2] docs(framework): add WAKE-DOCTRINE.md guide (W0) Adds packages/mosaic/framework/guides/WAKE-DOCTRINE.md, lifting the canonical wake/heartbeat doctrine verbatim from the ratified converged design (docs/scratchpads/heartbeat-planning/CONVERGED-DESIGN.md). Docs-only. Part of #892. --- .../mosaic/framework/guides/WAKE-DOCTRINE.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 packages/mosaic/framework/guides/WAKE-DOCTRINE.md 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. -- 2.49.1 From 87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9 Mon Sep 17 00:00:00 2001 From: mosaic-coder Date: Sat, 25 Jul 2026 16:36:21 -0500 Subject: [PATCH 2/2] style(framework): prettier-normalize WAKE-DOCTRINE.md emphasis markers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI pipeline 2006 failed the format step: prettier --check flagged packages/mosaic/framework/guides/WAKE-DOCTRINE.md for using *asterisk* italic delimiters instead of the project's _underscore_ style. Ran prettier --write on the single file; the only change is the emphasis delimiter around "before" (*before* -> _before_) — no wording changed. The CI test-step failure on the same pipeline is unrelated: a docs-only .md cannot affect Python daemon socket tests. Verified against origin/main pipeline 2005 (parent commit 3c7890f), where recovery_b1_adversarial_unittest.py passed cleanly; on this branch's pipeline 2006 the same file errored with ConnectionRefusedError connecting to the lease-broker unix socket in setUp — a pre-existing/ flaky test-harness race, not introduced by this change. --- packages/mosaic/framework/guides/WAKE-DOCTRINE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/mosaic/framework/guides/WAKE-DOCTRINE.md b/packages/mosaic/framework/guides/WAKE-DOCTRINE.md index 9be44cd2..d95c2d60 100644 --- a/packages/mosaic/framework/guides/WAKE-DOCTRINE.md +++ b/packages/mosaic/framework/guides/WAKE-DOCTRINE.md @@ -21,7 +21,7 @@ are local-write-only and cumulative; a turn never blocks on the network to ack. 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`. +**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. -- 2.49.1