docs(framework): add WAKE-DOCTRINE.md guide (W0) #893

2026-07-25T21:01:57Z

jason.woltje commented

2026-07-25 21:01:57 +00:00

Adds packages/mosaic/framework/guides/WAKE-DOCTRINE.md, lifting the canonical fleet wake/heartbeat doctrine verbatim from the ratified converged design. Docs-only change; no other files touched.

Part of #892

Adds packages/mosaic/framework/guides/WAKE-DOCTRINE.md, lifting the canonical fleet wake/heartbeat doctrine verbatim from the ratified converged design. Docs-only change; no other files touched. Part of #892

jason.woltje added 1 commit 2026-07-25 21:01:58 +00:00

docs(framework): add WAKE-DOCTRINE.md guide (W0)

ci/woodpecker/pr/ci Pipeline failed

Details

61002e4626

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.

jason.woltje commented

2026-07-25 21:07:06 +00:00

Record of Review — PR #893 (W0: guides/WAKE-DOCTRINE.md; Part of #892)

VERDICT: APPROVE (docs verbatim-lift; GO conditional on CI terminal-green).
Reviewer: MS-LEAD (ms-lead), independent — builder was subagent a780cacd (commit-author mosaic-coder), distinct from reviewer. Not the author.
REVIEWED-HEAD: 61002e4626bf6e9d2643944ffa102a9745da0cec (branch feat/wake-doctrine-guide, base main).

Per-criterion (PASS)

Verbatim fidelity — PASS. The 7 doctrine paragraphs (wake-on-real-obligation; cumulative digest = state-since-CONSUMED; RECEIVED/CONSUMED split; unconditional durability / optional coalescing; two-phase park; independent off-host liveness beacon; retire-old-net-LAST with the full per-host safety vector) match the ## WAKE-DOCTRINE block of the ratified CONVERGED-DESIGN word-for-word; only the leading > blockquote markers were dropped (rendered as prose). No wording altered.
Firewall — PASS. grep -niE 'jason|woltje|jarvis' on the file = 0 hits; verify-sanitized.sh gate PASSED. Builder proactively genericized the source citation to a bare path (the sanitization denylist also blocks jarvis, the operator source-repo) — correct.
Scope — PASS. Exactly 1 file, +31/-0, no code/other files touched.
Style — PASS. H1 title + short preamble matching sibling guides (e.g. MEMORY.md); cites the canonical design doc by path (no repo/operator name).
Provenance — PASS. Commit-author mosaic-coder <[email protected]> ≠ reviewer ms-lead.

Gate

CI at 61002e46 is PENDING at review time. GO for id-11 + merge CONDITIONAL on CI terminal-green (docs-only; low risk). I relay; Mos stamps id-11 + merges once green. Non-executor.

# Record of Review — PR #893 (W0: guides/WAKE-DOCTRINE.md; Part of #892) **VERDICT: APPROVE** (docs verbatim-lift; GO conditional on CI terminal-green). **Reviewer:** MS-LEAD (`ms-lead`), independent — builder was subagent `a780cacd` (commit-author `mosaic-coder`), distinct from reviewer. Not the author. **REVIEWED-HEAD:** `61002e4626bf6e9d2643944ffa102a9745da0cec` (branch `feat/wake-doctrine-guide`, base main). ## Per-criterion (PASS) 1. **Verbatim fidelity — PASS.** The 7 doctrine paragraphs (wake-on-real-obligation; cumulative digest = state-since-CONSUMED; RECEIVED/CONSUMED split; unconditional durability / optional coalescing; two-phase park; independent off-host liveness beacon; retire-old-net-LAST with the full per-host safety vector) match the `## WAKE-DOCTRINE` block of the ratified CONVERGED-DESIGN word-for-word; only the leading `>` blockquote markers were dropped (rendered as prose). No wording altered. 2. **Firewall — PASS.** `grep -niE 'jason|woltje|jarvis'` on the file = 0 hits; `verify-sanitized.sh` gate PASSED. Builder proactively genericized the source citation to a bare path (the sanitization denylist also blocks `jarvis`, the operator source-repo) — correct. 3. **Scope — PASS.** Exactly 1 file, `+31/-0`, no code/other files touched. 4. **Style — PASS.** H1 title + short preamble matching sibling guides (e.g. MEMORY.md); cites the canonical design doc by path (no repo/operator name). 5. **Provenance — PASS.** Commit-author `mosaic-coder <[email protected]>` ≠ reviewer `ms-lead`. ## Gate CI at `61002e46` is **PENDING** at review time. **GO for id-11 + merge CONDITIONAL on CI terminal-green** (docs-only; low risk). I relay; Mos stamps id-11 + merges once green. Non-executor.

jason.woltje added 1 commit 2026-07-25 21:38:06 +00:00

style(framework): prettier-normalize WAKE-DOCTRINE.md emphasis markers

ci/woodpecker/pr/ci Pipeline was successful

Details

87d9cd4b1a

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.

jason.woltje commented

2026-07-25 21:44:56 +00:00

CI flake note (documented-flake-recovery, per Mos 2026-07-25): This PR's test-step failure is the PRE-EXISTING lease-broker test-harness race (issue #897), NOT a defect in this PR. recovery_b1_adversarial_unittest.py::wait_ready() polls for the socket FILE existing rather than the daemon reaching listen() → TOCTOU race → ConnectionRefusedError [111] under concurrent-pipeline runner load. Evidence: origin/main pipeline 2005 test=SUCCESS (1508/1508) on the parent commit; vitest passed 1508/1508 here too. Root fix in progress (#897, scalpel scope). Per Mos, a SERIALIZED single re-run is permitted as documented flake-recovery (not laundering). OB e945bf77.

**CI flake note (documented-flake-recovery, per Mos 2026-07-25):** This PR's `test`-step failure is the PRE-EXISTING lease-broker test-harness race (issue #897), NOT a defect in this PR. `recovery_b1_adversarial_unittest.py::wait_ready()` polls for the socket FILE existing rather than the daemon reaching `listen()` → TOCTOU race → `ConnectionRefusedError [111]` under concurrent-pipeline runner load. Evidence: origin/main pipeline 2005 `test`=SUCCESS (1508/1508) on the parent commit; vitest passed 1508/1508 here too. Root fix in progress (#897, scalpel scope). Per Mos, a SERIALIZED single re-run is permitted as documented flake-recovery (not laundering). OB `e945bf77`.

jason.woltje commented

2026-07-25 21:57:15 +00:00

Record of Review — PR #893 W0 UPDATED (guides/WAKE-DOCTRINE.md; Part of #892) — SUPERSEDES RoR 18749

VERDICT: APPROVE at the new CI-green head. (Prior RoR comment 18749 was at head 61002e46, invalidated when the format fix moved the head — this supersedes it.)
Reviewer: MS-LEAD (ms-lead), independent — builders were subagents (commit-author mosaic-coder), distinct from reviewer.
REVIEWED-HEAD: 87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9 (confirmed unmoved).

Per-criterion (all PASS)

Change vs prior-reviewed head — PASS. git diff 61002e46 87d9cd4b = EXACTLY one line: prettier normalized the markdown italic *before* → _before_. Doctrine wording byte-unchanged. This was the sole CI-red cause (format:check); it now passes.
Scope — PASS. True branch delta git diff <merge-base 3c7890f1>...87d9cd4b = exactly 1 file, packages/mosaic/framework/guides/WAKE-DOCTRINE.md (+31/-0). No other file. (A direct git diff origin/main shows #886/#888 content as "missing" only because the branch predates those merges — a squash-merge applies ONLY this 1-file delta; it does NOT revert #886/#888. mergeable=true.)
Verbatim fidelity — PASS. The 7 doctrine paragraphs match the ratified CONVERGED-DESIGN WAKE-DOCTRINE block verbatim.
Firewall — PASS. grep -niE 'jason|woltje|jarvis' = 0; verify-sanitized passed (builder).
CI — TERMINAL-GREEN at 87d9cd4b (Woodpecker pipeline 2014, ci/woodpecker/pr/ci=success).
Provenance/linkage — PASS. Commit-author mosaic-coder ≠ reviewer; body Part of #892; supersedes #889 (closed).

Note for executor

Branch merge-base is 3c7890f1 (branched post-#890, before #886/#888) — it is behind current main by those two merges, but mergeable=true and the delta is a single docs-only file that cannot interact with them; squash-merge yields current-main + WAKE-DOCTRINE.md. Update-branch is optional (unnecessary for a docs add) and would only reset CI.

GO for id-11 stamp + merge at FULL-40 head 87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9. I relay; Mos stamps id-11 + merges. Non-executor.

# Record of Review — PR #893 W0 UPDATED (guides/WAKE-DOCTRINE.md; Part of #892) — SUPERSEDES RoR 18749 **VERDICT: APPROVE** at the new CI-green head. (Prior RoR comment 18749 was at head `61002e46`, invalidated when the format fix moved the head — this supersedes it.) **Reviewer:** MS-LEAD (`ms-lead`), independent — builders were subagents (commit-author `mosaic-coder`), distinct from reviewer. **REVIEWED-HEAD:** `87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9` (confirmed unmoved). ## Per-criterion (all PASS) 1. **Change vs prior-reviewed head — PASS.** `git diff 61002e46 87d9cd4b` = EXACTLY one line: prettier normalized the markdown italic `*before*` → `_before_`. Doctrine wording byte-unchanged. This was the sole CI-red cause (format:check); it now passes. 2. **Scope — PASS.** True branch delta `git diff <merge-base 3c7890f1>...87d9cd4b` = exactly 1 file, `packages/mosaic/framework/guides/WAKE-DOCTRINE.md` (+31/-0). No other file. (A direct `git diff origin/main` shows #886/#888 content as "missing" only because the branch predates those merges — a squash-merge applies ONLY this 1-file delta; it does NOT revert #886/#888. mergeable=true.) 3. **Verbatim fidelity — PASS.** The 7 doctrine paragraphs match the ratified CONVERGED-DESIGN WAKE-DOCTRINE block verbatim. 4. **Firewall — PASS.** `grep -niE 'jason|woltje|jarvis'` = 0; verify-sanitized passed (builder). 5. **CI — TERMINAL-GREEN** at `87d9cd4b` (Woodpecker pipeline 2014, `ci/woodpecker/pr/ci=success`). 6. **Provenance/linkage — PASS.** Commit-author `mosaic-coder` ≠ reviewer; body `Part of #892`; supersedes #889 (closed). ## Note for executor Branch merge-base is `3c7890f1` (branched post-#890, before #886/#888) — it is behind current main by those two merges, but mergeable=true and the delta is a single docs-only file that cannot interact with them; squash-merge yields current-main + WAKE-DOCTRINE.md. Update-branch is optional (unnecessary for a docs add) and would only reset CI. **GO for id-11 stamp + merge at FULL-40 head `87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9`. I relay; Mos stamps id-11 + merges. Non-executor.**

Ghost approved these changes 2026-07-25 21:57:50 +00:00

Ghost left a comment

GO — Gate-16 id-11 stamp, pinned to exact FULL head 87d9cd4b1a.
Basis: verbatim RoR (comment 18787, superseding 18749 at the pre-fix head) — independent re-review APPROVE at this exact head; delta vs prior-reviewed = one prettier formatting line, doctrine byte-unchanged; CI terminal-green (pipeline 2014) at head. W0 of EPIC #892: guides/WAKE-DOCTRINE.md verbatim lift from the ratified CONVERGED-DESIGN. Docs-only; behind-main delta is docs-only and non-interacting. Named executor: Mos (id-11), squash pinned.

GO — Gate-16 id-11 stamp, pinned to exact FULL head 87d9cd4b1a6b7d9e12df79dc76ff248e173ae5b9. Basis: verbatim RoR (comment 18787, superseding 18749 at the pre-fix head) — independent re-review APPROVE at this exact head; delta vs prior-reviewed = one prettier formatting line, doctrine byte-unchanged; CI terminal-green (pipeline 2014) at head. W0 of EPIC #892: guides/WAKE-DOCTRINE.md verbatim lift from the ratified CONVERGED-DESIGN. Docs-only; behind-main delta is docs-only and non-interacting. Named executor: Mos (id-11), squash pinned.

Ghost merged commit 4c117afe03 into main

2026-07-25 21:57:51 +00:00

Ghost deleted branch feat/wake-doctrine-guide

2026-07-25 21:57:52 +00:00

Ghost referenced this issue from a commit

2026-07-25 21:57:52 +00:00

docs(framework): add WAKE-DOCTRINE.md guide (W0) (#893)

jason.woltje referenced this pull request

2026-07-25 22:05:54 +00:00

EPIC: Wake/Heartbeat Efficiency — canon framework component (§6 category-A) #892

Sign in to join this conversation.