From 9c51046c03bde4dbfa8fae7b9ca652e9012ae2ba Mon Sep 17 00:00:00 2001
From: j-langdon-alleato <j.langdon@alleato.com>
Date: Tue, 26 May 2026 17:46:57 +1000
Subject: [PATCH] feat(ship): write SHIP-RECEIPT.md to audited phase folder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds Step 19.5 between Step 19 (PR URL captured) and Step 20 (metrics).
The new block writes a 5-field markdown receipt — Branch, SHA, PR URL,
Timestamp (ISO-8601 UTC), Version — into the phase folder Step 8
already audits. This lets workflow-recipe systems (Dev OS et al.)
detect successful /ship completion without polling git or gh.

Non-GSD projects skip silently. If `.planning/phases/` does not exist
in cwd, Step 19.5 logs one debug line and proceeds to Step 20. No
behavior change for the majority of gstack users who don't run GSD.

Cross-phase branches: the receipt lands in the highest-numbered phase
folder Step 8 audited.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ship/SKILL.md.tmpl | 50 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl
index 5a7c34661..85738671e 100644
--- a/ship/SKILL.md.tmpl
+++ b/ship/SKILL.md.tmpl
@@ -916,6 +916,56 @@ Print the branch name, remote URL, and instruct the user to create the PR/MR man
 
 ---
 
+## Step 19.5: Write SHIP-RECEIPT.md (for recipe-runtime detection)
+
+Write a one-page ship receipt into the phase folder Step 8 audited. Recipe runners
+(e.g. Dev OS workflow recipes) watch for this file and use it to detect successful
+ship completion. Non-GSD projects skip this step silently.
+
+1. Identify the target phase folder. From Step 8's audit output, take the highest-numbered
+   phase under `.planning/phases/`. If Step 8 audited multiple phases (cross-phase branch),
+   pick the one with the largest leading number. If Step 8 found zero plan files, or
+   `.planning/phases/` does not exist in cwd, log `[ship] no .planning/phases/ found,
+   skipping SHIP-RECEIPT.md write` and proceed to Step 20.
+
+2. Gather the field values:
+
+   ```bash
+   BRANCH=$(git branch --show-current)
+   SHA=$(git rev-parse --short HEAD)
+   PR_URL=$(gh pr view --json url -q .url 2>/dev/null || glab mr view -F json 2>/dev/null | jq -r .web_url || echo "")
+   TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+   VERSION_VAL=$(cat VERSION 2>/dev/null | tr -d '\r\n[:space:]')
+   ```
+
+3. Write the receipt to `{cwd}/.planning/phases/<highest-phase>/SHIP-RECEIPT.md`,
+   overwriting any prior receipt:
+
+   ```bash
+   cat > ".planning/phases/$PHASE_DIR/SHIP-RECEIPT.md" <<EOF
+   ## Ship Receipt
+
+   | Field | Value |
+   |-------|-------|
+   | Branch | $BRANCH |
+   | SHA | $SHA |
+   | PR URL | $PR_URL |
+   | Timestamp | $TIMESTAMP |
+   | Version | $VERSION_VAL |
+   EOF
+   ```
+
+   Replace `$PHASE_DIR` with the phase folder name identified in step 1
+   (for example, `11-ship-patch-starter-library`).
+
+4. Confirm: `ls .planning/phases/$PHASE_DIR/SHIP-RECEIPT.md` shows the file exists.
+   If the file write fails for any reason, log the error and continue to Step 20.
+   The receipt is a downstream signal for recipe runners, not a /ship correctness gate.
+
+Then proceed to Step 20.
+
+---
+
 ## Step 20: Persist ship metrics
 
 Log coverage and plan completion data so `/retro` can track trends: