codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-ship/reference/testflight-internal-vs-external.md

@@ -0,0 +1,69 @@
+# TestFlight — Internal vs External Testers
+
+When `/cbp-ship` lands a build on TestFlight, the orchestrator must decide which tester population to target. The two paths have different latency, audit, and access semantics. Pick the wrong one and either (a) the right people don't get the build, or (b) you wait 24+ hours on a Beta Review you didn't need.
+
+## The Core Trade-off
+
+| Dimension | Internal | External |
+|---|---|---|
+| Tester ceiling | 100 | 10,000 |
+| Identity | Apple ID on your App Store Connect team | Any email address |
+| Beta App Review | **Not required** | **Required** for first build of each version |
+| Time to availability after `VALID` | Minutes (push notification) | 24–48 hours typical (review queue) |
+| Public link | No | Yes (self-enrolment up to group cap) |
+| Tester role required | App Store Connect role: Account Holder, Admin, App Manager, Developer, or Marketing | None (no ASC account needed) |
+| Devices per tester | 30 | 30 |
+| Build expiry | 90 days | 90 days |
+| Auto-distribute on new build | Yes (per-group toggle) | Yes (per-group toggle), but each build still passes through review unless minor-change exemption applies |
+| Crash + feedback collection | Yes | Yes |
+| Cost | Free (within team) | Free |
+
+## Decision Table
+
+| Checkpoint scenario | Choose | Why |
+|---|---|---|
+| Engineering smoke-test before any external eyes | Internal | No review wait; team already has ASC accounts |
+| Daily / per-PR builds during active development | Internal | Review queue would block iteration speed |
+| Designer or PM previewing a feature pre-merge | Internal (add them as App Manager / Marketing role) | Avoids review delay for trusted reviewers |
+| Closed beta with a named friends-and-family list (≤100 people, all willing to be added to ASC) | Internal | Faster, simpler, no review |
+| Closed beta with >100 testers OR testers unwilling/unable to join ASC | External | Internal cap exceeded; ASC role not appropriate |
+| Public beta with a shareable signup link | External | Only external supports public links |
+| Marketing-driven preview to press / influencers | External | Don't grant ASC roles to non-employees |
+| Final pre-release rehearsal mirroring real-world install | External | Mirrors the post-launch update mechanic; flushes out review-time issues before App Store submission |
+| Region-restricted or audience-segmented rollouts | External (multiple groups) | Group-scoped distribution is the segmentation primitive |
+
+## Operational Notes
+
+### Internal-only fast-path
+
+If a checkpoint declares `testflight.audience: internal`, `/cbp-ship` should:
+
+1. `eas submit --platform ios` and wait for `VALID`.
+2. Verify the build is auto-assigned to the internal group(s) configured on the app (or assign explicitly via App Store Connect API `POST /v1/betaGroups/{id}/relationships/builds`).
+3. Stop. Skip the Beta Review submission step entirely. Surface the TestFlight install link to the user.
+
+### External path
+
+If `testflight.audience: external`:
+
+1. Run the internal-fast-path first (so the team gets the build immediately).
+2. Then submit for Beta App Review: `POST /v1/betaAppReviewSubmissions` with the build ID.
+3. Poll `betaAppReviewSubmissions/{id}` for state transitions (`WAITING_FOR_REVIEW` → `IN_REVIEW` → `APPROVED` / `REJECTED`).
+4. On approval, the build auto-distributes to assigned external groups (if the group's auto-notify is on).
+
+### Hybrid
+
+Most production checkpoints want both: internal testers get the build immediately for smoke-testing, then the same build goes to external review for the broader beta. This is the default unless the checkpoint explicitly opts out.
+
+## Common Mistakes
+
+- **Adding non-employees as internal testers.** They get an ASC role, which exposes more than intended. Use external groups instead.
+- **Submitting for Beta Review when only internal distribution is needed.** Wastes 24–48 hours and an Apple review slot.
+- **Assuming "external review approved" persists across versions.** It is per-version (technically per-`CFBundleShortVersionString`). A new marketing version requires a fresh review.
+- **Missing the encryption-export declaration.** External review will reject builds without `ITSAppUsesNonExemptEncryption` resolved. Internal builds are also blocked from distribution until resolved, even though no review is required.
+
+## References
+
+- [Add internal testers — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/add-internal-testers/)
+- [Invite external testers — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers/)
+- [TestFlight overview — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/testflight-overview/)

package/templates/skills/cbp-ship/reference/testflight-overview.md

@@ -0,0 +1,98 @@
+# TestFlight Overview
+
+TestFlight is Apple's first-party beta-distribution service for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS apps. It is the **only** sanctioned path for distributing pre-release builds of an Expo / React Native iOS app to testers without going through the public App Store. For the `expo-mobile` surface of `/cbp-ship`, TestFlight is the terminal hop after `eas build --platform ios` produces a signed `.ipa`.
+
+## What TestFlight Is
+
+- A subsystem of App Store Connect — every TestFlight build is a real App Store Connect build record, with the same processing pipeline, export-compliance metadata, and version/build-number rules.
+- A separate iOS app (`TestFlight.app`) that testers install from the App Store; they receive a public link or email invitation to redeem.
+- The pre-flight gate for App Store review: the same binary uploaded to TestFlight is the one promoted to production. There is no separate "production-only" upload step — you promote the existing TestFlight build.
+
+Reference: [TestFlight overview — App Store Connect Help](https://developer.apple.com/help/app-store-connect/test-a-beta-version/testflight-overview/) and [developer.apple.com/testflight](https://developer.apple.com/testflight/).
+
+## Tester Categories
+
+TestFlight has two distinct tester populations with very different rules:
+
+### Internal Testers
+
+- Up to **100 internal testers** per app.
+- Must be App Store Connect users on your team with one of these roles: Account Holder, Admin, App Manager, Developer, or Marketing.
+- **No Beta App Review required** — builds are available to internal testers as soon as Apple finishes processing the upload (typically 10–15 minutes).
+- Identified by Apple ID (the address tied to their App Store Connect account).
+
+Reference: [Add internal testers](https://developer.apple.com/help/app-store-connect/test-a-beta-version/add-internal-testers/).
+
+### External Testers
+
+- Up to **10,000 external testers** per app, organised into groups (max 100 groups, up to 10,000 testers per group, with the 10K cap shared across the app).
+- Anyone with a valid email address — no App Store Connect account required.
+- **First build per version requires Beta App Review** by Apple (typically 24–48 hours, sometimes same-day, occasionally several days).
+- Subsequent builds with the same version may auto-pass review if the changes are minor (Apple's discretion).
+- Public link distribution is supported — anyone with the link can self-enrol up to the group cap.
+
+Reference: [Invite external testers](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers/).
+
+## Processing Pipeline
+
+After `eas submit --platform ios` (or any upload tool) hands the `.ipa` to App Store Connect:
+
+1. **Upload** — Transporter / `altool` / EAS streams the `.ipa` to App Store Connect. Returns immediately with a build record in `PROCESSING` state.
+2. **Apple processing** — Apple validates the binary, extracts dSYMs, scans for export-compliance and missing-Info.plist keys, and re-signs as needed. Usually 10–15 minutes; can stretch to an hour during peak windows. State transitions: `PROCESSING` → `VALID` (or `INVALID` with ITMS error).
+3. **Compliance gate** — Build must declare encryption-export compliance. Set `ITSAppUsesNonExemptEncryption = false` in `Info.plist` (or `app.config` `ios.config.usesNonExemptEncryption`) for the auto-pass on standard HTTPS-only apps; otherwise App Store Connect will block distribution until you answer the encryption questionnaire.
+4. **Internal availability** — Once `VALID`, the build appears in TestFlight for any internal-tester group it's been assigned to. Manual assignment is required unless auto-distribute is enabled on the group.
+5. **External submission** — To distribute externally, submit the build for Beta App Review (separate from internal availability). On approval, the build is pushed to assigned external groups.
+
+## Build Expiration — the 90-Day Rule
+
+Every TestFlight build expires **90 days after upload**, regardless of tester activity. Expired builds:
+
+- Cannot be installed by new testers.
+- Existing installs continue to work but receive no updates.
+- Must be replaced by uploading a fresh build (incremented build number).
+
+Implication for `/cbp-ship`: a checkpoint that ships to TestFlight on day 0 will be unavailable to new testers on day 91. If the cadence between TestFlight ship and App Store promotion exceeds 90 days, plan for a refresh build.
+
+## Version and Build Number Rules
+
+App Store Connect enforces:
+
+- `CFBundleShortVersionString` (marketing version, e.g. `1.4.2`) — must match or exceed the latest version of this app.
+- `CFBundleVersion` (build number, e.g. `42`) — must be **strictly greater** than every previous build for the same `CFBundleShortVersionString`. Once a build number is uploaded, it can never be reused for that version, even if the upload was rejected.
+- EAS auto-increments build numbers when `cli.appVersionSource = remote` in `eas.json` and `autoIncrement = true` in the build profile. Verify before assuming.
+
+## Device Limits per Tester
+
+A single tester (Apple ID) can install TestFlight builds on up to **30 devices**. This is per-tester, not per-app. Not to be confused with the 100-device limit on the Apple Developer Program account (which applies to ad-hoc / development provisioning, NOT TestFlight).
+
+## Relationship to App Store Connect API
+
+The App Store Connect API exposes TestFlight as a set of REST resources:
+
+- `/v1/builds` — list / query builds, including processing state and expiry date.
+- `/v1/betaGroups` — internal and external group CRUD.
+- `/v1/betaTesters` — invite / remove individual testers.
+- `/v1/buildBetaDetails` and `/v1/betaAppReviewSubmissions` — submit a build for external review.
+- `/v1/preReleaseVersions` — query version groupings.
+
+Authentication uses an issuer-scoped JWT signed with a `.p8` private key. See [testflight-automation.md](./testflight-automation.md) for the full automation contract.
+
+Reference: [App Store Connect API — Get started](https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/).
+
+## Where TestFlight Fits in `/cbp-ship` (expo-mobile)
+
+```
+eas build --platform ios          → produces signed .ipa
+eas submit --platform ios         → uploads to App Store Connect (TestFlight)
+                                    [10–15 min processing]
+internal group auto-distribute    → testers get push notification
+[optional] beta review submission → 24–48h, then external groups receive build
+```
+
+The `/cbp-ship` orchestrator owns the trigger (`eas submit`) and the wait-loop (poll build state until `VALID`). It does NOT own the Beta Review submission decision — that is gated on whether the checkpoint targets external testers, which is metadata on the checkpoint itself.
+
+## See also
+
+- [testflight-internal-vs-external.md](./testflight-internal-vs-external.md) — picking the right tester population per checkpoint
+- [testflight-automation.md](./testflight-automation.md) — ASC API key + EAS Submit + ITMS error catalogue + beta groups via API
+- [surface-expo-eas.md](./surface-expo-eas.md) — the `/cbp-ship` deploy steps that consume this content

package/templates/skills/cbp-ship/reference/versioning.md

@@ -0,0 +1,116 @@
+# Versioning Rules
+
+How `/cbp-ship` decides which version a surface ships at.
+
+## Three modes (per surface, configured per-package)
+
+| Mode | Trigger | Best for |
+|---|---|---|
+| `manual` | User bumps `package.json` / `tauri.conf.json` / `app.json` version themselves before checkpoint shipment | Apps with infrequent releases; small teams |
+| `release-please` | GH Actions opens version-bump PRs based on conventional commit messages on the watched branch; merge the PR before shipment | npm packages with frequent releases; multi-contributor repos |
+| `changesets` | Devs add `.changeset/*.md` entries in feature branches; an aggregator PR collects them | Monorepos with many independent packages |
+
+Mode is set per-surface in `.codebyplan/shipment.json`:
+
+```json
+{
+  "surfaces": {
+    "npm-package": {
+      "packages/codebyplan-package": { "versioning": "release-please" }
+    },
+    "tauri-desktop": { "versioning": "manual" },
+    "expo-mobile": { "versioning": "auto-build-number" }
+  }
+}
+```
+
+## Auto-bumping where possible
+
+These bumps happen automatically — never user-prompted:
+
+| Surface | Field | Bump rule |
+|---|---|---|
+| `expo-mobile` | `expo.ios.buildNumber` | `eas.json` `autoIncrement: "buildNumber"` — handled by EAS |
+| `expo-mobile` | `expo.android.versionCode` | `eas.json` `autoIncrement: "versionCode"` — handled by EAS |
+| `vercel-web` | n/a | Vercel uses commit SHA; no semver bump needed |
+
+## Semver bump rules (manual or release-please modes)
+
+When the orchestrator detects a version change is needed but mode is `manual`, it suggests a bump based on commit messages since the last release:
+
+| Commit message pattern | Suggested bump |
+|---|---|
+| Has `BREAKING CHANGE:` in footer OR `feat!:`/`fix!:` prefix | major |
+| Any `feat:` prefix | minor |
+| Otherwise | patch |
+
+The user can override the suggestion. The orchestrator NEVER auto-bumps without confirmation in `manual` mode.
+
+## release-please conventions
+
+Conventional Commits are the trigger:
+
+| Prefix | Action |
+|---|---|
+| `feat:` | Minor bump in next release-please PR |
+| `fix:` | Patch bump |
+| `feat!:` / `fix!:` / `BREAKING CHANGE:` | Major bump |
+| `chore:`, `docs:`, `refactor:`, `test:`, `style:`, `perf:`, `ci:` | No bump |
+
+The release-please workflow lives at `.github/workflows/release-please.yml` (scaffolded by `/cbp-ship-configure`).
+
+## changesets conventions
+
+A changeset is a markdown file describing the change:
+
+```markdown
+---
+"@scope/pkg-a": minor
+"@scope/pkg-b": patch
+---
+
+Add new export `foo` and fix bug in `bar`.
+```
+
+Changesets are committed alongside feature work. The aggregator PR (`changeset-release/main`) collects pending changesets and bumps versions when merged.
+
+`/cbp-ship-configure` scaffolds `.changeset/config.json` and the GH Actions workflow.
+
+## Pre-release versions
+
+When the version contains a pre-release identifier (`-alpha.N`, `-beta.N`, `-rc.N`), the surface deploy uses the appropriate dist-tag:
+
+| Surface | Pre-release handling |
+|---|---|
+| `npm-package` | `npm publish --tag <pre-id>` (never promotes to `latest`) |
+| `vscode-ext` | `vsce publish --pre-release` |
+| `tauri-desktop` | Tag pushed normally; users opt into pre-release via Tauri config |
+| `expo-mobile` | TestFlight internal/external groups handle pre-release semantics naturally |
+| `vercel-web` | Use Vercel preview branches for pre-release URLs |
+
+## Coordinated bumps in monorepos
+
+When multiple surfaces ship together, bumps may need to coordinate:
+
+- **Tauri desktop bump → updater manifest** — desktop bump triggers a `latest.json` update; users get prompted at next launch. Only push tauri tag at planned release boundaries.
+- **npm package bump → consumer apps' `pnpm.overrides`** — if a sibling package consumes the bumped one, decide if you want apps pinned to the prior version (no override change) or rolled forward (override updated).
+- **Mobile build number auto-increment** — EAS bumps independently; the user-facing `expo.version` (semver) is bumped only when the user explicitly changes it.
+
+## What NOT to do
+
+- Don't manually edit `package.json` version inside `/cbp-ship` — versioning happens before shipment, not during
+- Don't auto-bump in `manual` mode without confirmation — the user owns the bump
+- Don't squash changeset commits — release-please / changesets need each conventional commit visible
+- Don't tag a Tauri release before the version commit is on PRODUCTION branch — the tag locks the shipped version
+
+## Decision: which mode to pick when configuring a new surface
+
+| Question | If yes |
+|---|---|
+| Is this an npm package with multiple authors? | release-please |
+| Is this a monorepo with 3+ published packages? | changesets |
+| Is this a single app with infrequent releases? | manual |
+| Is this a mobile app? | manual for semver + auto for build numbers |
+| Is this Tauri desktop? | manual (tags drive the release) |
+| Is this VS Code extension? | manual |
+| Is this Vercel web? | n/a — Vercel uses SHA not semver |

package/templates/skills/cbp-ship/scripts/detect-surfaces.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# Detect shipment surfaces in the current repo.
+# Emits JSON to stdout: { "surfaces": [ { id, instance, configured, reason } ] }
+# Usage: detect-surfaces.sh [--filter=<id>]
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$REPO_ROOT"
+
+FILTER=""
+for arg in "$@"; do
+  case "$arg" in
+    --filter=*) FILTER="${arg#--filter=}" ;;
+  esac
+done
+
+# Load shipment config from .codebyplan/shipment.json (if present)
+DISABLED_JSON="[]"
+SURFACES_JSON="{}"
+if [ -f .codebyplan/shipment.json ]; then
+  DISABLED_JSON=$(jq -r '.disabled // [] | tostring' .codebyplan/shipment.json 2>/dev/null || echo "[]")
+  SURFACES_JSON=$(jq -r '.surfaces // {} | tostring' .codebyplan/shipment.json 2>/dev/null || echo "{}")
+fi
+
+is_disabled() {
+  local id="$1"
+  echo "$DISABLED_JSON" | jq -e --arg id "$id" 'index($id)' >/dev/null 2>&1
+}
+
+emit() {
+  # Emit one JSON line per surface; we'll wrap in array at end
+  local id="$1" instance="$2" configured="$3" reason="$4"
+  if [ -n "$FILTER" ] && [ "$FILTER" != "$id" ]; then
+    return
+  fi
+  if is_disabled "$id"; then
+    return
+  fi
+  jq -nc \
+    --arg id "$id" --arg instance "$instance" \
+    --argjson configured "$configured" --arg reason "$reason" \
+    '{id: $id, instance: $instance, configured: $configured, reason: $reason}'
+}
+
+# ============ vercel-web ============
+detect_vercel() {
+  # Look at every package.json and decide if it's a web app
+  while IFS= read -r pkg; do
+    local app_path
+    app_path=$(dirname "$pkg")
+    [ "$app_path" = "." ] && continue
+    [[ "$app_path" =~ /node_modules/ ]] && continue
+
+    # Has Next or is explicitly Vercel-flagged?
+    local has_next has_vercel_json has_vercel_link
+    has_next=$(jq -e '.dependencies.next // .devDependencies.next' "$pkg" >/dev/null 2>&1 && echo y || echo n)
+    has_vercel_json=$([ -f "$app_path/vercel.json" ] && echo y || echo n)
+    has_vercel_link=$([ -f "$app_path/.vercel/project.json" ] && echo y || echo n)
+
+    if [ "$has_next" = "y" ] || [ "$has_vercel_json" = "y" ] || [ "$has_vercel_link" = "y" ]; then
+      if [ "$has_vercel_link" = "y" ]; then
+        emit "vercel-web" "$app_path" true "vercel.json + .vercel/project.json present"
+      else
+        emit "vercel-web" "$app_path" false "Next.js detected but .vercel/project.json missing — run /cbp-ship-configure"
+      fi
+    fi
+  done < <(find apps -maxdepth 3 -name package.json 2>/dev/null; [ -f package.json ] && echo "./package.json")
+}
+
+# ============ expo-mobile ============
+detect_expo() {
+  while IFS= read -r app; do
+    local app_path
+    app_path=$(dirname "$app")
+    [[ "$app_path" =~ /node_modules/ ]] && continue
+
+    local has_eas
+    has_eas=$([ -f "$app_path/eas.json" ] && echo y || echo n)
+
+    if [ "$has_eas" = "y" ]; then
+      emit "expo-mobile" "$app_path" true "app.json + eas.json present"
+    else
+      emit "expo-mobile" "$app_path" false "app.json present but eas.json missing — run /cbp-ship-configure"
+    fi
+  done < <(find . -maxdepth 4 -name "app.json" -not -path "*/node_modules/*" 2>/dev/null \
+    | xargs -I{} sh -c 'jq -e ".expo" "{}" >/dev/null 2>&1 && echo "{}"' 2>/dev/null)
+}
+
+# ============ tauri-desktop ============
+detect_tauri() {
+  while IFS= read -r conf; do
+    local app_path
+    app_path=$(dirname "$(dirname "$conf")")
+    [[ "$app_path" =~ /node_modules/ ]] && continue
+
+    local has_workflow
+    has_workflow=$(find .github/workflows -maxdepth 1 -name "*.yml" 2>/dev/null \
+      | xargs grep -l "tauri-action" 2>/dev/null | head -1)
+
+    if [ -n "$has_workflow" ]; then
+      emit "tauri-desktop" "$app_path" true "src-tauri/ + tauri-action workflow present"
+    else
+      emit "tauri-desktop" "$app_path" false "src-tauri/ present but no release workflow — run /cbp-ship-configure"
+    fi
+  done < <(find . -maxdepth 4 -name "tauri.conf.json" -not -path "*/node_modules/*" -not -path "*/target/*" 2>/dev/null)
+}
+
+# ============ npm-package ============
+detect_npm() {
+  while IFS= read -r pkg; do
+    local pkg_path
+    pkg_path=$(dirname "$pkg")
+    [ "$pkg_path" = "." ] && continue
+    [[ "$pkg_path" =~ /node_modules/ ]] && continue
+    [[ "$pkg_path" =~ ^./apps/ ]] && continue  # apps don't publish
+
+    local is_private name
+    is_private=$(jq -r '.private // false' "$pkg")
+    name=$(jq -r '.name // ""' "$pkg")
+
+    [ "$is_private" = "true" ] && continue
+    [ -z "$name" ] && continue
+
+    emit "npm-package" "$pkg_path" true "publishable package: $name"
+  done < <(find packages -maxdepth 2 -name package.json 2>/dev/null)
+}
+
+# ============ vscode-ext ============
+detect_vscode() {
+  while IFS= read -r pkg; do
+    local pkg_path
+    pkg_path=$(dirname "$pkg")
+    [[ "$pkg_path" =~ /node_modules/ ]] && continue
+
+    local has_engine has_publisher
+    has_engine=$(jq -e '.engines.vscode' "$pkg" >/dev/null 2>&1 && echo y || echo n)
+    has_publisher=$(jq -e '.publisher' "$pkg" >/dev/null 2>&1 && echo y || echo n)
+
+    if [ "$has_engine" = "y" ] && [ "$has_publisher" = "y" ]; then
+      emit "vscode-ext" "$pkg_path" true "engines.vscode + publisher set"
+    elif [ "$has_engine" = "y" ]; then
+      emit "vscode-ext" "$pkg_path" false "engines.vscode set but publisher missing — run /cbp-ship-configure"
+    fi
+  done < <(find apps packages -maxdepth 3 -name package.json 2>/dev/null)
+}
+
+# ============ railway-backend ============
+detect_railway() {
+  # Direct signal: railway config
+  while IFS= read -r conf; do
+    local app_path
+    app_path=$(dirname "$conf")
+    [[ "$app_path" =~ /node_modules/ ]] && continue
+    emit "railway-backend" "$app_path" true "railway.toml/json present"
+  done < <(find . -maxdepth 4 \( -name "railway.toml" -o -name "railway.json" \) -not -path "*/node_modules/*" 2>/dev/null)
+
+  # Indirect: Dockerfile + non-frontend package.json
+  while IFS= read -r dockerfile; do
+    local app_path
+    app_path=$(dirname "$dockerfile")
+    [[ "$app_path" =~ /node_modules/ ]] && continue
+    [ -f "$app_path/railway.toml" ] || [ -f "$app_path/railway.json" ] && continue  # already emitted above
+
+    local pkg="$app_path/package.json"
+    [ -f "$pkg" ] || continue
+    local is_frontend
+    is_frontend=$(jq -e '.dependencies.next // .dependencies."react-native" // .dependencies.expo' "$pkg" >/dev/null 2>&1 && echo y || echo n)
+    [ "$is_frontend" = "y" ] && continue
+
+    emit "railway-backend" "$app_path" false "Dockerfile present but Railway not linked — run /cbp-ship-configure"
+  done < <(find . -maxdepth 3 -name "Dockerfile" -not -path "*/node_modules/*" 2>/dev/null)
+}
+
+# ============ supabase ============
+detect_supabase() {
+  if [ -d supabase/migrations ] || find apps -maxdepth 3 -type d -name "supabase" 2>/dev/null | head -1 | grep -q .; then
+    local migration_dir
+    if [ -d supabase/migrations ]; then
+      migration_dir="supabase/migrations"
+    else
+      migration_dir=$(find apps -maxdepth 3 -type d -path "*/supabase/migrations" | head -1)
+    fi
+
+    [ -z "$migration_dir" ] && return
+
+    # Pending count = files newer than last_shipped_migration_version
+    local last_version pending_count
+    last_version=$(echo "$SURFACES_JSON" | jq -r '."supabase".last_shipped_migration_version // ""' 2>/dev/null)
+    if [ -n "$last_version" ]; then
+      pending_count=$(find "$migration_dir" -name "*.sql" -newer "$migration_dir/$last_version" 2>/dev/null | wc -l | tr -d ' ')
+    else
+      pending_count=$(find "$migration_dir" -name "*.sql" 2>/dev/null | wc -l | tr -d ' ')
+    fi
+
+    if [ "$pending_count" -gt 0 ]; then
+      local has_link
+      has_link=$([ -f supabase/.temp/project-ref ] && echo y || echo n)
+      if [ "$has_link" = "y" ]; then
+        emit "supabase" "$migration_dir" true "$pending_count migrations pending"
+      else
+        emit "supabase" "$migration_dir" false "$pending_count migrations but project not linked — run /cbp-ship-configure"
+      fi
+    fi
+  fi
+}
+
+# ============ Run all detectors and wrap in array ============
+{
+  detect_vercel
+  detect_expo
+  detect_tauri
+  detect_npm
+  detect_vscode
+  detect_railway
+  detect_supabase
+} | jq -s '{surfaces: .}'

package/templates/skills/cbp-ship/scripts/verify-expo-eas.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Verify an EAS build + submission landed.
+# Usage: verify-expo-eas.sh <build-id> [<submission-platform>]
+# Exit: 0 ok, 1 fail, 2 verification_pending
+
+set -euo pipefail
+BUILD_ID="$1"
+PLATFORM="${2:-ios}"
+
+STATUS=$(eas build:view "$BUILD_ID" --json 2>/dev/null | jq -r '.status // "UNKNOWN"')
+
+case "$STATUS" in
+  FINISHED)
+    SUBMISSION=$(eas submit:list --status finished --json 2>/dev/null \
+      | jq -r --arg b "$BUILD_ID" '.[] | select(.buildId == $b) | .status' | head -1)
+    if [ "$SUBMISSION" = "finished" ]; then
+      echo "OK build=$BUILD_ID submission=finished"
+      exit 0
+    fi
+    echo "PENDING: build done; submission=$SUBMISSION (TestFlight/Play processing)"
+    exit 2
+    ;;
+  IN_QUEUE|IN_PROGRESS)
+    echo "PENDING: $STATUS"
+    exit 2
+    ;;
+  ERRORED|CANCELED)
+    echo "FAIL: build $STATUS"
+    exit 1
+    ;;
+  *)
+    echo "PENDING: unknown state $STATUS"
+    exit 2
+    ;;
+esac

package/templates/skills/cbp-ship/scripts/verify-npm.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Verify an npm package version is published.
+# Usage: verify-npm.sh <package-name> <version>
+# Exit: 0 ok, 1 fail
+
+set -euo pipefail
+PKG="$1"
+VERSION="$2"
+
+RESOLVED=$(npm view "$PKG@$VERSION" version 2>/dev/null || echo "")
+[ "$RESOLVED" = "$VERSION" ] || { echo "FAIL: $PKG@$VERSION not on registry"; exit 1; }
+
+# Provenance attestation (bonus check)
+ATT=$(npm view "$PKG@$VERSION" --json 2>/dev/null | jq -r '.dist.attestations // empty')
+[ -n "$ATT" ] && PROV="yes" || PROV="no"
+
+# Tarball SRI
+SRI=$(npm view "$PKG@$VERSION" dist.integrity 2>/dev/null || echo "")
+[ -n "$SRI" ] || echo "WARN: no integrity hash"
+
+echo "OK $PKG@$VERSION provenance=$PROV"

package/templates/skills/cbp-ship/scripts/verify-railway.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Verify a Railway deployment is SUCCESS and the service responds.
+# Usage: verify-railway.sh <deployment-id> [<url>]
+# Exit: 0 ok, 1 fail, 2 pending
+
+set -euo pipefail
+DEPLOY_ID="$1"
+URL="${2:-}"
+
+STATUS=$(railway deployment status "$DEPLOY_ID" --json 2>/dev/null | jq -r '.status // "UNKNOWN"')
+
+case "$STATUS" in
+  SUCCESS|DEPLOYED)
+    if [ -n "$URL" ]; then
+      HEALTH=$(curl -sIm 10 "https://$URL/health" 2>/dev/null | head -1 | awk '{print $2}' || echo "")
+      if [ "$HEALTH" = "200" ]; then
+        echo "OK deploy=$DEPLOY_ID health=200"
+        exit 0
+      fi
+      ROOT=$(curl -sIm 10 "https://$URL" 2>/dev/null | head -1 | awk '{print $2}' || echo "")
+      case "$ROOT" in
+        2*|3*) echo "OK deploy=$DEPLOY_ID root=$ROOT (no /health endpoint)"; exit 0 ;;
+        *) echo "FAIL: deploy succeeded but service unreachable ($ROOT)"; exit 1 ;;
+      esac
+    fi
+    echo "OK deploy=$DEPLOY_ID (no URL to probe)"
+    exit 0
+    ;;
+  BUILDING|DEPLOYING|QUEUED|WAITING)
+    echo "PENDING: $STATUS"
+    exit 2
+    ;;
+  FAILED|CRASHED)
+    echo "FAIL: deploy $STATUS"
+    exit 1
+    ;;
+  *)
+    echo "PENDING: unknown state $STATUS"
+    exit 2
+    ;;
+esac

package/templates/skills/cbp-ship/scripts/verify-supabase.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Verify Supabase migrations applied successfully.
+# Usage: verify-supabase.sh <expected-last-migration-version>
+# Exit: 0 ok, 1 fail
+
+set -euo pipefail
+EXPECTED="$1"
+
+# Migration appears in remote-applied list
+APPLIED=$(supabase migration list --linked 2>/dev/null | grep -F "$EXPECTED" | wc -l | tr -d ' ')
+[ "$APPLIED" -gt 0 ] || { echo "FAIL: migration $EXPECTED not found on remote"; exit 1; }
+
+# No drift between local migrations and remote schema
+DRIFT_LINES=$(supabase db diff --use-migra 2>/dev/null | grep -v "^--" | grep -v "^$" | wc -l | tr -d ' ')
+if [ "$DRIFT_LINES" -gt 0 ]; then
+  echo "WARN: $DRIFT_LINES lines of drift detected (run: supabase db diff --use-migra)"
+fi
+
+echo "OK migration=$EXPECTED drift_lines=$DRIFT_LINES"

package/templates/skills/cbp-ship/scripts/verify-tauri.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Verify a Tauri desktop release was tagged + published with assets.
+# Usage: verify-tauri.sh <version-without-v-prefix>
+# Exit: 0 ok, 1 fail
+
+set -euo pipefail
+VERSION="$1"
+TAG="v$VERSION"
+
+git fetch origin --tags >/dev/null 2>&1
+git rev-parse "$TAG" >/dev/null 2>&1 || { echo "FAIL: tag $TAG missing locally"; exit 1; }
+git ls-remote --tags origin "$TAG" | grep -q . || { echo "FAIL: tag $TAG not pushed"; exit 1; }
+
+PUBLISHED=$(gh release view "$TAG" --json publishedAt -q .publishedAt 2>/dev/null || echo "")
+[ -n "$PUBLISHED" ] || { echo "FAIL: release $TAG not published"; exit 1; }
+
+ASSETS=$(gh release view "$TAG" --json assets -q '.assets | length' 2>/dev/null)
+[ "${ASSETS:-0}" -ge 1 ] || { echo "FAIL: release $TAG has no assets"; exit 1; }
+
+# Tauri auto-update needs latest.json
+HAS_MANIFEST=$(gh release view "$TAG" --json assets -q '.assets[].name' | grep -c "latest.json" || true)
+[ "$HAS_MANIFEST" -gt 0 ] || echo "WARN: latest.json missing — auto-update may not work"
+
+echo "OK tag=$TAG assets=$ASSETS published=$PUBLISHED"