From 043f86f00d71eadb80f6c0293278e9a44718b1a7 Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Sun, 1 Nov 2026 20:11:57 +0000
Subject: [PATCH] docs(ship): Step 5 says lanes run one at a time on 4 or fewer
 cores and names --lanes (GST-851 docs audit)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 ship/sections/tests.md                          | 5 +++--
 ship/sections/tests.md.tmpl                     | 5 +++--
 test/size-ledger/ship/gst-851-serial-lanes.json | 4 ++++
 3 files changed, 10 insertions(+), 4 deletions(-)
 create mode 100644 test/size-ledger/ship/gst-851-serial-lanes.json

diff --git a/ship/sections/tests.md b/ship/sections/tests.md
index 651562cfa..057f2477b 100644
--- a/ship/sections/tests.md
+++ b/ship/sections/tests.md
@@ -213,8 +213,9 @@ Only commit if there are changes. Stage the bootstrap's own files by name (confi
 **Run it:** `~/.claude/skills/gstack/bin/gstack-ship-preflight --tests-only --base <base> --lane <label>=<command>...`
 (or the Step 1 call with lanes). It runs the free pre-gate first, before any lane, eval or
 remote gate (`gstack-pregate --allow-repo-commands`: stage 1 regen, secrets, strays, literals;
-stage 2 the selected lanes under pipefail), then every lane in parallel inside the evidence
-ledger, and prints `PREGATE:` and one `LANE: <label> <state> exit= tests_ran= log=` line each.
+stage 2 the selected lanes under pipefail), then the lanes inside the evidence ledger (one at
+a time on 4 or fewer cores unless `--lanes serial|parallel`), and prints `PREGATE:`, `LANES:` and
+one `LANE: <label> <state> exit= tests_ran= log=` line each.
 `fail` or `incomplete` blocks: fix, rerun. `requires-remote` (other platforms; the remote gate under 8 cores) needs
 `gstack-pregate clear` or, under a user cap, `--remote --spend-cap <usd>`. Rerun
 after the final stamp (`gstack-ship-release finish` does); Step 18 refuses a stale one.
diff --git a/ship/sections/tests.md.tmpl b/ship/sections/tests.md.tmpl
index 02a2463cd..697c16099 100644
--- a/ship/sections/tests.md.tmpl
+++ b/ship/sections/tests.md.tmpl
@@ -9,8 +9,9 @@
 **Run it:** `~/.claude/skills/gstack/bin/gstack-ship-preflight --tests-only --base <base> --lane <label>=<command>...`
 (or the Step 1 call with lanes). It runs the free pre-gate first, before any lane, eval or
 remote gate (`gstack-pregate --allow-repo-commands`: stage 1 regen, secrets, strays, literals;
-stage 2 the selected lanes under pipefail), then every lane in parallel inside the evidence
-ledger, and prints `PREGATE:` and one `LANE: <label> <state> exit= tests_ran= log=` line each.
+stage 2 the selected lanes under pipefail), then the lanes inside the evidence ledger (one at
+a time on 4 or fewer cores unless `--lanes serial|parallel`), and prints `PREGATE:`, `LANES:` and
+one `LANE: <label> <state> exit= tests_ran= log=` line each.
 `fail` or `incomplete` blocks: fix, rerun. `requires-remote` (other platforms; the remote gate under 8 cores) needs
 `gstack-pregate clear` or, under a user cap, `--remote --spend-cap <usd>`. Rerun
 after the final stamp (`gstack-ship-release finish` does); Step 18 refuses a stale one.
diff --git a/test/size-ledger/ship/gst-851-serial-lanes.json b/test/size-ledger/ship/gst-851-serial-lanes.json
new file mode 100644
index 000000000..42e1e2c22
--- /dev/null
+++ b/test/size-ledger/ship/gst-851-serial-lanes.json
@@ -0,0 +1,4 @@
+{
+  "bytes": 66,
+  "why": "GST-851: Step 5 prose says lanes run one at a time on 4 or fewer cores, names --lanes serial|parallel and the LANES line"
+}