mosaicstack/stack
1
0
Fork 0
Code Issues 85 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

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

Merged
Mos merged 2 commits from feat/wake-doctrine-guide into main 2026-07-25 21:57:51 +00:00
Conversation 4 Commits 2 Files Changed 1 +31
jason.woltje commented 2026-07-25 21:01:57 +00:00
Owner
Copy Link

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)
Some checks failed
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
Author
Owner
Copy Link

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 <coder@fleet.mosaicstack.dev> ≠ 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 <coder@fleet.mosaicstack.dev>` ≠ 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
All checks were successful
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
Author
Owner
Copy Link

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
Author
Owner
Copy Link

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.

# 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.**
Mos approved these changes 2026-07-25 21:57:50 +00:00
Mos left a comment
First-time contributor
Copy Link

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.
Mos merged commit 4c117afe03 into main 2026-07-25 21:57:51 +00:00
Mos deleted branch feat/wake-doctrine-guide 2026-07-25 21:57:52 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Mos
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#893
Delete Branch "feat/wake-doctrine-guide"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?