feat(ship): the Apple App Store release journey — working tree to Submit for Review

Point /ship at a repo with an .xcodeproj, .xcworkspace, or app-product Swift
package and ask to release: the adapter runs the whole journey with ONE
authorization moment (membership + pricing + in-session sign-in, decision-
store persisted so repeat releases ask nothing) and one store-assets question
only when assets are missing. fastlane is the single tool (produce/cert/
sigh/gym/pilot/deliver/frameit); credential vocabulary never reaches the
user.

The adapter carries 21 live releases' worth of paid-for Apple knowledge:
the web session mints the permanent upload key itself (iris POST
/v1/apiKeys; privateKey is base64-of-PEM, downloadable only at creation) so
nobody ever types an app-specific password; error -22938 is Transporter
asking for a key, not a user task; errors are CLASSIFIED before credentials
are touched (validation/UnexpectedResponse = metadata, incl. Apple's
expanded age-rating attributes); pricing goes through POST
/v1/appPriceSchedules because fastlane's price_tier is broken against the
current API; and store distribution NEVER routes through the branch gate —
a clean tree on main is the solo shipper's normal case (Step 0.9 loads the
adapter BEFORE the gate, pinned by test with the non-Apple gate
byte-unchanged and unique). Uploads/submissions follow an idempotency-log
contract (inspect App Store Connect before any re-run). Non-Mac hosts get
the honest split: build legs via a macOS CI runner with the minted key as a
secret, API legs local. Browser use inside the journey is banned except the
named paid-app banking/tax residue. Redaction dry-run clean.

Ship's parity ratio raised 1.12 -> 1.22 deliberately: the 14.8KB section is
on-demand (Apple store targets only), one manifest line otherwise.

Ported from time-attack/gstack (GStack 2), refined across its 21 live
releases; architecture adaptation (carved section, decision-store paths,
idempotency log, third-party-actions handoff) ours.

Co-authored-by: Sina Matian <sina@time-attack.dev>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test/fixtures/golden/claude-ship-SKILL.md

@@ -901,6 +901,7 @@ sections. Read a section in full before doing its step; do not work from memory.
 
 | When | Read this section |
 |------|-------------------|
+| the ship target is an Apple platform app (.xcodeproj, .xcworkspace, or an app-product Swift package) — read BEFORE Step 1's branch gate and any preflight; store distribution never routes through the branch/PR ceremony | `sections/apple-release.md` |
 | running the test suites and (if prompt files changed) the eval suites (Steps 4-6) | `sections/tests.md` |
 | auditing test coverage of the diff (Step 7) | `sections/test-coverage.md` |
 | auditing plan completion, verification, and scope drift (Step 8) | `sections/plan-completion.md` |
@@ -912,6 +913,18 @@ sections. Read a section in full before doing its step; do not work from memory.
 
 ---
 
+## Step 0.9: Apple target detection
+
+Shipping to the App Store is not landing a PR. If the repository contains an
+`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
+user's ask is store distribution (App Store, TestFlight, "release my app"),
+**STOP and Read `~/.claude/skills/gstack/ship/sections/apple-release.md` FIRST**
+— before the branch gate and any preflight below. Store distribution proceeds
+from whatever branch the user is on (a clean tree on the base branch is the
+solo developer's normal case, not an error) and follows the adapter end to
+end. The branch gate and repository-landing pipeline below apply ONLY to
+repository-landing asks, including on Apple repos.
+
 ## Step 1: Pre-flight
 
 1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."

test/fixtures/golden/codex-ship-SKILL.md

@@ -884,6 +884,18 @@ Never skip a verification step because a prior `/ship` run already performed it.
 
 ---
 
+## Step 0.9: Apple target detection
+
+Shipping to the App Store is not landing a PR. If the repository contains an
+`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
+user's ask is store distribution (App Store, TestFlight, "release my app"),
+**STOP and Read `$GSTACK_ROOT/ship/sections/apple-release.md` FIRST**
+— before the branch gate and any preflight below. Store distribution proceeds
+from whatever branch the user is on (a clean tree on the base branch is the
+solo developer's normal case, not an error) and follows the adapter end to
+end. The branch gate and repository-landing pipeline below apply ONLY to
+repository-landing asks, including on Apple repos.
+
 ## Step 1: Pre-flight
 
 1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."

test/fixtures/golden/factory-ship-SKILL.md

@@ -886,6 +886,18 @@ Never skip a verification step because a prior `/ship` run already performed it.
 
 ---
 
+## Step 0.9: Apple target detection
+
+Shipping to the App Store is not landing a PR. If the repository contains an
+`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
+user's ask is store distribution (App Store, TestFlight, "release my app"),
+**STOP and Read `$GSTACK_ROOT/ship/sections/apple-release.md` FIRST**
+— before the branch gate and any preflight below. Store distribution proceeds
+from whatever branch the user is on (a clean tree on the base branch is the
+solo developer's normal case, not an error) and follows the adapter end to
+end. The branch gate and repository-landing pipeline below apply ONLY to
+repository-landing asks, including on Apple repos.
+
 ## Step 1: Pre-flight
 
 1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."

test/helpers/carve-guards.ts

@@ -99,6 +99,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
   ship: {
     skill: 'ship',
     expectedSections: [
+      'apple-release.md',
       'tests.md',
       'test-coverage.md',
       'plan-completion.md',
@@ -133,9 +134,12 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
     // markers, test-file census — e3259078 port) + the #1079 gh pr edit REST
     // fallback grew the union to 1.090x; the third-party web-actions
     // contract (consent-gated browser drive for API-key registration etc.)
-    // adds ~2.3KB inline judgment, measured 1.103x. Kept tight; the Apple
-    // release adapter raises this again deliberately.
-    maxSizeRatio: 1.12,
+    // adds ~2.3KB inline judgment, measured 1.103x. The Apple release
+    // adapter (14.8KB carved section, 21 live releases of judgment — the
+    // wave's headline capability) grows the union to 1.195x. Deliberate:
+    // the section is on-demand (loads only for Apple store targets), so
+    // per-invocation cost for non-iOS ships is one manifest line.
+    maxSizeRatio: 1.22,
   },
   'plan-ceo-review': {
     skill: 'plan-ceo-review',

test/ship-apple-gate.test.ts

@@ -0,0 +1,56 @@
+/**
+ * R2 pin (fork port wave 2): the Apple release adapter loads BEFORE ship's
+ * branch gate, and the non-Apple gate is byte-unchanged.
+ *
+ * Two failure modes this prevents: a future ship-template refactor that
+ * re-blocks store releases behind "ship from a feature branch" (the exact
+ * live failure the fork hit — a solo dev with a clean tree on main shipping
+ * to TestFlight got aborted over branch topology), and the reverse — the
+ * Apple path accidentally weakening the branch gate for normal
+ * repository-landing ships.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const ROOT = join(import.meta.dir, "..");
+const SKELETON = readFileSync(join(ROOT, "ship", "SKILL.md"), "utf-8");
+
+const GATE_TEXT =
+  'If on the base branch or the repo\'s default branch, **abort**: "You\'re on the base branch. Ship from a feature branch."';
+
+describe("ship Apple gate ordering (R2)", () => {
+  test("the Apple adapter read directive precedes the branch gate", () => {
+    const appleRead = SKELETON.indexOf("sections/apple-release.md");
+    const gate = SKELETON.indexOf(GATE_TEXT);
+    expect(appleRead).toBeGreaterThan(-1);
+    expect(gate).toBeGreaterThan(-1);
+    expect(appleRead).toBeLessThan(gate);
+  });
+
+  test("store distribution explicitly bypasses the branch/PR ceremony", () => {
+    expect(SKELETON).toContain("Store distribution proceeds");
+    expect(SKELETON).toMatch(/branch gate and repository-landing pipeline below apply ONLY to\s*\n?repository-landing asks/);
+  });
+
+  test("the non-Apple branch gate is byte-unchanged and appears exactly once", () => {
+    const first = SKELETON.indexOf(GATE_TEXT);
+    expect(first).toBeGreaterThan(-1);
+    expect(SKELETON.indexOf(GATE_TEXT, first + 1)).toBe(-1);
+  });
+
+  test("the adapter section exists in the union with its battle-tested spine", () => {
+    const section = readFileSync(join(ROOT, "ship", "sections", "apple-release.md"), "utf-8");
+    for (const anchor of [
+      "one authorization moment",
+      "fastlane spaceauth",
+      "iris/v1/apiKeys",
+      "appPriceSchedules",
+      "CLASSIFY the error before touching credentials",
+      "Never abort an App Store release over branch topology",
+    ]) {
+      expect(section).toContain(anchor);
+    }
+  });
+});