docs(homesonspec): wire offload-preflight as mandatory step-0 GO/NO-GO in the runbook — toolkit now turnkey (TK-10809)

7fd3d9fe38b1e92b677202b1ea294b182f5950b1 · 2026-08-30 23:18:03 -0700 · Steve Abrams

Files touched

M ops/OFFLOAD-RUNBOOK.md

Diff

commit 7fd3d9fe38b1e92b677202b1ea294b182f5950b1
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Sun Aug 30 23:18:03 2026 -0700

    docs(homesonspec): wire offload-preflight as mandatory step-0 GO/NO-GO in the runbook — toolkit now turnkey (TK-10809)
---
 ops/OFFLOAD-RUNBOOK.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/ops/OFFLOAD-RUNBOOK.md b/ops/OFFLOAD-RUNBOOK.md
index 394df71b..f5eae006 100644
--- a/ops/OFFLOAD-RUNBOOK.md
+++ b/ops/OFFLOAD-RUNBOOK.md
@@ -2,8 +2,12 @@
 
 The raw-snapshot store is ~155G split across two prod dirs. This runbook offloads it
 to a dedicated volume **without ever deleting evidence**. Every prod step below is
-**Steve-gated**. The tooling here (`ops/offload-snapshots.mjs`) is copy-only + verify;
-it NEVER unlinks, prunes, moves, or rewrites the source.
+**Steve-gated**. The tooling is copy-only + verify; it NEVER unlinks, prunes, moves,
+or rewrites the source:
+- `ops/offload-preflight.mjs` — READ-ONLY GO/NO-GO run **before** any copy (dest capacity,
+  live-crawl guard, DB scope). Exit 0 = GO, exit 1 = NO-GO.
+- `ops/offload-snapshots.mjs` — copy-only rsync (`-a`, no `--delete`) + sha256 verify.
+- `ops/verify-snapshots.mjs` — read-only post-move integrity canary.
 
 ## Facts to confirm ON THE BOX before you start
 
@@ -19,6 +23,16 @@ it NEVER unlinks, prunes, moves, or rewrites the source.
 
 ## Ordering (SAFE — do not reorder; old copies stay until a separate approval)
 
+0. **PREFLIGHT (read-only GO/NO-GO) — run first, require GO.**
+   ```
+   node ops/offload-preflight.mjs --src <REAL_SNAPSHOT_DIR> --dest <vol>
+   ```
+   Requires exit 0 (`=== PREFLIGHT GO ===`). NO-GO (exit 1) means a blocking precondition:
+   dest can't hold SRC (+5% margin), a live crawl is mid-write (torn-snapshot risk), SRC
+   missing/empty, or dest==src. Clear the ❌ items before copying. **Re-run this after the
+   step-2 quiesce** (before the final rsync) to confirm no crawl is still writing and dest
+   still has room.
+
 1. **Initial rsync copy-only.** Bulk-copy while ingestion keeps running. This is not
    the source of truth for completeness — it just moves most bytes ahead of the freeze.
    ```

← c3626f01 docs(homesonspec): record completed 13-brand CPG roster + co · back to Homesonspec · fix(homesonspec): correct dead Oakwood seed domain oakwoodho 57212c91 →