From 93ea53217ed487ef1cbd8490ba641c7c41935a15 Mon Sep 17 00:00:00 2001
From: Drew T <50529377+Druthulu@users.noreply.github.com>
Date: Mon, 31 Aug 2026 15:17:27 -0600
Subject: [PATCH] =?UTF-8?q?docs(playbook):=20a=20carve=20writes=20THREE=20?=
 =?UTF-8?q?outputs=20=E2=80=94=20merge=20all=20three,=20splice=20overlays.?=
 =?UTF-8?q?mk=20per=20block,=20gate=20jtbl=20with=20--r22?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/wave-playbook.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/wave-playbook.md b/docs/wave-playbook.md
index 0b1e00a119..771bd98992 100644
--- a/docs/wave-playbook.md
+++ b/docs/wave-playbook.md
@@ -122,6 +122,15 @@ per-binary symlinks plus a real copy of the single binary it carves (~5 MB/worke
 PER JOB because worker slots are reused, and gated by the same jtbl predicate `harvest_verify`
 carves on.
 
+**A CARVE WRITES THREE THINGS AND THE MERGE MUST CARRY ALL THREE** — `src/<bin>/*.c`,
+`config/splat.<bin>.yaml`, and this binary's BLOCK of the shared `config/overlays.mk`. Carrying only
+the first gives a green worker and a red fleet: measured S67, 13 of 213 red, every one a jtbl binary
+from that run (reverted, then fixed with `ovl_block()`/`splice_ovl_block()`). Never blanket-adopt
+`overlays.mk` — splice the one block, with the same pinned-baseline refusal as a file adopt.
+
+**RUN A jtbl GATE WITH `--r22`.** It aborts on a non-green fleet and leaves the files in the tree for
+inspection instead of committing red binaries — the guard that would have caught the above at once.
+
 **If you are writing `for b in binaries: gate_stage ...`, STOP.** That loop is the hour-long mistake
 this section exists to prevent.