From 9e95a7e362b4904a48bcbd3ccd7c1c489ca8b2f9 Mon Sep 17 00:00:00 2001
From: garrytan <garrytan@gmail.com>
Date: Tue, 3 Nov 2026 06:32:27 +0000
Subject: [PATCH] ship: name the pre-push guards in Step 17 and the early push
 (moved from #3923 per GSTA-258)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---
 bin/gstack-doctor-components.sh                   | 1 +
 ship/SKILL.md                                     | 2 +-
 ship/SKILL.md.tmpl                                | 2 +-
 ship/sections/tests.md                            | 2 +-
 ship/sections/tests.md.tmpl                       | 2 +-
 test/fixtures/golden/agy-ship-SKILL.md            | 2 +-
 test/fixtures/golden/claude-ship-SKILL.md         | 2 +-
 test/fixtures/golden/codex-ship-SKILL.md          | 2 +-
 test/fixtures/golden/factory-ship-SKILL.md        | 2 +-
 test/size-ledger/ship/gsta258-l6-guard-carry.json | 4 ++++
 10 files changed, 13 insertions(+), 8 deletions(-)
 create mode 100644 test/size-ledger/ship/gsta258-l6-guard-carry.json

diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh
index 23db8f80d..4ec7b9a61 100644
--- a/bin/gstack-doctor-components.sh
+++ b/bin/gstack-doctor-components.sh
@@ -258,6 +258,7 @@ gstack_result_anchor() {
     DX_CAPTURE_REDACTION_FAILED) printf '%s' 'dx-capture-redaction-failed' ;;
     DX_CAPTURE_INTERNAL) printf '%s' 'dx-capture-internal' ;;
     POLICY_GSTACK_TOO_OLD) printf '%s' 'policy-gstack-too-old' ;;
+    PREGATE_GSTACK_TOO_OLD) printf '%s' 'pregate-gstack-too-old' ;;
     QUEUE_NOT_READY) printf '%s' 'queue-not-ready' ;;
     QUEUE_PROOF_MISSING) printf '%s' 'queue-proof-missing' ;;
     QUEUE_STAMP_NOT_STAMP_ONLY) printf '%s' 'queue-stamp-not-stamp-only' ;;
diff --git a/ship/SKILL.md b/ship/SKILL.md
index 125947cba..59687eaab 100644
--- a/ship/SKILL.md
+++ b/ship/SKILL.md
@@ -871,7 +871,7 @@ A new PR or an existing draft needs no question: Step 19 creates or keeps the dr
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl
index 1dc0ce129..1f1418e90 100644
--- a/ship/SKILL.md.tmpl
+++ b/ship/SKILL.md.tmpl
@@ -592,7 +592,7 @@ A new PR or an existing draft needs no question: Step 19 creates or keeps the dr
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/ship/sections/tests.md b/ship/sections/tests.md
index bccb51df2..55262a6f2 100644
--- a/ship/sections/tests.md
+++ b/ship/sections/tests.md
@@ -229,7 +229,7 @@ at this exact, clean tree instead of running here: `LANE: <label> carried run=<i
 Before the first push run only targeted tests and the repro (the full suite too when the diff touches
 merge-check code: `lib/ship-*`, `lib/pregate/*`, the ship and pregate bins,
 `scripts/lib/shard-engine.ts`). Push early so CI runs beside the review: commit, `gstack-ship-release push
---branch <branch> --early` (sealed and secrets scans first), open a draft PR, then `gstack-ci-carry wait` in
+--branch <branch> --early` (sealed, secrets and guards first), open a draft PR, then `gstack-ci-carry wait` in
 the background; once it prints `CI_WAIT: green`, rerun `--tests-only` and the mapped lane is carried. A red
 run is a failed lane: triage it below. Batch review fixes into one commit and one push. `CI_CARRY: none
 label=<l> (<reason>)` names why a mapped lane ran here (a dirty tree, no green run at HEAD yet, a fork or stale
diff --git a/ship/sections/tests.md.tmpl b/ship/sections/tests.md.tmpl
index ccaf4c537..c408effa6 100644
--- a/ship/sections/tests.md.tmpl
+++ b/ship/sections/tests.md.tmpl
@@ -25,7 +25,7 @@ at this exact, clean tree instead of running here: `LANE: <label> carried run=<i
 Before the first push run only targeted tests and the repro (the full suite too when the diff touches
 merge-check code: `lib/ship-*`, `lib/pregate/*`, the ship and pregate bins,
 `scripts/lib/shard-engine.ts`). Push early so CI runs beside the review: commit, `gstack-ship-release push
---branch <branch> --early` (sealed and secrets scans first), open a draft PR, then `gstack-ci-carry wait` in
+--branch <branch> --early` (sealed, secrets and guards first), open a draft PR, then `gstack-ci-carry wait` in
 the background; once it prints `CI_WAIT: green`, rerun `--tests-only` and the mapped lane is carried. A red
 run is a failed lane: triage it below. Batch review fixes into one commit and one push. `CI_CARRY: none
 label=<l> (<reason>)` names why a mapped lane ran here (a dirty tree, no green run at HEAD yet, a fork or stale
diff --git a/test/fixtures/golden/agy-ship-SKILL.md b/test/fixtures/golden/agy-ship-SKILL.md
index 45130e661..77c525e2f 100644
--- a/test/fixtures/golden/agy-ship-SKILL.md
+++ b/test/fixtures/golden/agy-ship-SKILL.md
@@ -872,7 +872,7 @@ A new PR or an existing draft needs no question: Step 19 creates or keeps the dr
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/test/fixtures/golden/claude-ship-SKILL.md b/test/fixtures/golden/claude-ship-SKILL.md
index 125947cba..59687eaab 100644
--- a/test/fixtures/golden/claude-ship-SKILL.md
+++ b/test/fixtures/golden/claude-ship-SKILL.md
@@ -871,7 +871,7 @@ A new PR or an existing draft needs no question: Step 19 creates or keeps the dr
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md
index bf8e4ddcc..1eab7dfd5 100644
--- a/test/fixtures/golden/codex-ship-SKILL.md
+++ b/test/fixtures/golden/codex-ship-SKILL.md
@@ -878,7 +878,7 @@ $GSTACK_ROOT/bin/gstack-ship-release push --branch <branch-name>
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md
index a34726a90..ec398b188 100644
--- a/test/fixtures/golden/factory-ship-SKILL.md
+++ b/test/fixtures/golden/factory-ship-SKILL.md
@@ -880,7 +880,7 @@ $GSTACK_ROOT/bin/gstack-ship-release push --branch <branch-name>
 ```
 
 It checks the branch, the offer, the gate above (`--gate-open <n>`; `--gate-open-approved` is B)
-and `gstack-pregate sealed`, then `git ls-remote --heads origin refs/heads/<branch-name>` against HEAD: a failed lookup STOPs, a match prints
+`gstack-pregate sealed` and the guards (`GUARDS:`), then `git ls-remote` of `<branch-name>` against HEAD: a failed lookup STOPs, a match prints
 `PUSH: ALREADY_PUSHED` (go to Step 18), else it runs `git push -u origin <branch-name>`.
 
 **If the push fails, STOP.** No Step 19 or publication claim. Report the error:
diff --git a/test/size-ledger/ship/gsta258-l6-guard-carry.json b/test/size-ledger/ship/gsta258-l6-guard-carry.json
new file mode 100644
index 000000000..884e23450
--- /dev/null
+++ b/test/size-ledger/ship/gsta258-l6-guard-carry.json
@@ -0,0 +1,4 @@
+{
+  "bytes": 4,
+  "why": "GST-1138: ship names the pre-push guards in Step 17 and the early push (GUARDS:), with the ls-remote line shortened to fit"
+}