Release

ADE Release Skill

Use this skill when the user wants to release ADE, automate releases from a cron/agent, decide whether a release is needed, publish a desktop release, ship a TestFlight build, or reconcile the hosted Cloudflare surfaces.

ADE ships three independent tiers, and a release conductor owns all three:

• desktop — GitHub Actions release workflow, macOS + Windows assets
• iOS — local ASC archive/export/upload to TestFlight
• Cloudflare web tier — the ade-web-client Pages project and four Workers, plus the account-side state they depend on (D1 databases and their applied migrations, R2 buckets and their lifecycle rules, Durable Object migration tags, cron triggers, vars, secrets). Phase 5.5 owns this. Neither the desktop workflow nor TestFlight touches it, and most of its failure modes are invisible to every test in the repository because they live in account state, not code.

This is a GitHub desktop + local ASC iOS release flow. Desktop releases must use the repository GitHub Actions release workflow for both platforms: macOS updater assets are produced reproducibly as per-arch ZIP/DMG artifacts on a macOS runner, and the signed Windows installer is produced on a Windows runner. Neither is built from the release host, whatever that host is — macOS and Windows are peers here, not a primary and a follow-up.

The release host runs checks, creates release docs/tags, and monitors and recovers the workflow. The only host-dependent phase is iOS: building and uploading TestFlight releases through ASC requires a macOS host. On a Windows host, run the desktop release normally and stop before the mobile phase, stating that iOS needs a macOS host — do not report a desktop-only release as complete when iOS was also in scope.

A preflight is a cheap check that runs before expensive build/upload work. Use preflights to catch release blockers while fixes can still be committed without burning a notarization, TestFlight upload, or build number.

Hard Rules

• No-op is valid. If no relevant product code changed, do not create a release just to bump numbers.
• Desktop and iOS are independent. Release desktop without iOS when only desktop changed; release iOS without desktop when only iOS changed.
• Desktop version bumps the patch segment only unless the user explicitly asks otherwise: v1.2.14 -> v1.2.15.
• iOS marketing version does not change unless the user explicitly asks. Only bump the TestFlight build number by one, using App Store Connect as the source of truth.
• Do not omit App Clip in normal releases. The v1.1.10 build 16 omission was an emergency unblock. Normal mobile releases must include the app, widgets, and App Clip after signing is fixed.
• Desktop release uses GitHub Actions only. Do not build, sign, notarize, or upload desktop release assets from the release host unless the user explicitly asks for a one-off manual recovery.
• No universal updater ZIPs. latest-mac.yml must reference per-arch arm64 and x64 ZIPs. Never publish a latest-mac.yml that points to ADE-*-universal.zip; v1.2.16 proved that giant universal updater ZIPs can crash Squirrel.Mac during in-app update.
• Do not publish broken updater metadata. Before making a desktop release public/latest, verify latest-mac.yml references assets that exist and that the expected arm64/x64 DMGs and ZIPs are present. When Windows is enabled, apply the same rule to latest.yml and the Windows installer.
• Do not publish a half-platform release. The Windows gate and the Windows assets must agree. If ADE_WINDOWS_PUBLIC_RELEASE_ENABLED is 1 the draft must carry Windows assets; if it is not 1 the draft must carry none. Either mismatch means the workflow did not do what you think it did, so keep the release draft/private and investigate before publishing.
• Do not discover obvious release blockers after upload. Preflight iOS App Clip packaging metadata before starting the expensive mobile phase.
• Do not wait forever. If GitHub notarization or TestFlight processing exceeds its normal window by a lot, preserve state, retry only the failed phase when possible, or stop with a clear recovery command.
• Do not serialize independent tiers. Desktop GitHub Actions, iOS TestFlight, and Cloudflare are independent once the shared docs/ci-pass gate is behind you. Numbered phases are a catalog, not a queue. Follow Parallel schedule below whenever more than one is in scope.

Parallel schedule

This overrides the Phase 4 → 5 → 5.5 order when more than one tier is in scope. Exclusive gh run watch is forbidden while another leg can make progress — poll the run and keep working.

Stay serial only for:

1. Docs merge → green ci-pass on that SHA → desktop v* tag. Tagging before ci-pass fails verify.
2. Draft asset verification → --draft=false. npm versions are immutable.
3. iOS IPA inspect / altool --validate-app → upload → asc builds wait → group attach.
4. A Windows release host cannot archive iOS. Keep desktop and Cloudflare in flight and say iOS needs a macOS host. Do not call the release done.

During the ci-pass wait (docs PR just landed)

• Cloudflare: deploy-web.yml is already running for that SHA. Start Phase 5.5 verification. Do not wait for a desktop tag.
• iOS: asc doctor and the App Clip preflight. Do not archive yet — a red ci-pass would burn a build number.

After the desktop tag (or immediately if desktop is out of scope)

Start every in-scope leg:

• Desktop: poll release.yml until the draft exists. If iOS or Cloudflare is also in scope, do not sit in gh run watch.
• iOS (macOS host): archive, export, inspect, validate, upload against RELEASE_SHA. TestFlight does not need the GitHub draft.
• Cloudflare: finish any remaining reconcile or manual deploy.

Join before undraft

If desktop is in scope, the draft must be verified before it goes public. iOS may still be in asc builds wait. Cloudflare may still be verifying. That is expected — do not stall undraft on them.

After undraft

Poll publish-runtime-packages.yml and update-brew-tap.yml together and join both. Keep polling iOS processing and Cloudflare if those legs are not done. Desktop is not done until npm view @ade-dev/runtime version equals the tag.

Join before phase=done

Every in-scope leg is green. A green GitHub release with a missing npm package, a missing TestFlight build, or a drifted Worker is not a finished release.

Machine Notes

Detect the release host rather than assuming it (uname -s / process.platform) — this lane runs on Windows or on an Apple Silicon Mac. Either way, desktop release artifacts for both platforms are produced remotely by GitHub Actions; treat local desktop packaging scripts as diagnostic/recovery tools only. Host type affects exactly two things: shell syntax for the commands below, and whether the iOS/TestFlight phase can run at all (macOS only).

Desktop updater correctness requires, on macOS:

• latest-mac.yml
• one arm64 ZIP and one x64 ZIP referenced by that file
• one arm64 DMG and one x64 DMG
• no universal ZIP in the updater feed

and, when ADE_WINDOWS_PUBLIC_RELEASE_ENABLED is 1, additionally on Windows:

• latest.yml
• one ADE-<VERSION>-win-x64.exe installer referenced by that file
• the matching ADE-<VERSION>-win-x64.exe.blockmap

Windows builds fresh on the tag alongside macOS. There is one repository variable, ADE_WINDOWS_PUBLIC_RELEASE_ENABLED; it decides whether the release carries Windows at all. Read it before verifying assets, because it determines which of the two asset matrices below is correct.

State and Locking

Create a state file before mutating release state:

mkdir -p .ade/release

Use a path like:

.ade/release/release-YYYYMMDD-HHMMSS.json

Track:

{
  "desktop": { "needed": false, "version": null, "tag": null, "lastTag": null, "platforms": null },
  "ios": { "needed": false, "marketingVersion": null, "buildNumber": null, "lastTag": null },
  "cloudflare": {
    "needed": false,
    "driftPreflight": "pending|pass|blocked",
    "surfaces": {
      "ade-web-client": { "changed": false, "action": "skip|ci|manual", "status": "pending|deployed|verified|blocked", "note": null },
      "ade-account-directory-production": { "changed": false, "action": "skip|ci|manual", "status": "pending|deployed|verified|blocked", "migrationsApplied": null, "note": null },
      "ade-github-webhook-relay": { "changed": false, "action": "skip|ci|manual", "status": "pending|deployed|verified|blocked", "migrationsApplied": null, "note": null },
      "ade-tunnel-relay": { "changed": false, "action": "skip|ci|manual", "status": "pending|deployed|verified|blocked", "note": null },
      "ade-push-relay": { "changed": false, "action": "skip|ci|manual", "status": "pending|deployed|verified|blocked", "migrationsApplied": null, "note": null }
    },
    "accountState": {
      "r2": {
        "ade-diagnostics": { "exists": null, "lifecycle30d": null, "devUrlDisabled": null, "customDomains": null },
        "ade-diagnostics-production": { "exists": null, "lifecycle30d": null, "devUrlDisabled": null, "customDomains": null }
      },
      "d1": {
        "ade-account-directory-production": { "exists": null, "idMatchesConfig": null, "migrationsPending": null },
        "ade-github-relay": { "exists": null, "idMatchesConfig": null, "migrationsPending": null },
        "ade-push-relay": { "exists": null, "idMatchesConfig": null, "migrationsPending": null, "triggersPresent": null }
      },
      "config": {
        "ade-account-directory-production": { "secretsBound": null, "varsSet": null, "unverified": [] },
        "ade-push-relay": { "secretsBound": null, "varsSet": null, "unverified": [] }
      },
      "cronTriggers": { "ade-account-directory-production": null, "ade-push-relay": null },
      "durableObjectMigrations": { "ade-github-webhook-relay": null, "ade-tunnel-relay": null },
      "productEnablement": { "r2": null }
    },
    "rollbacks": []
  },
  "phase": "detect|docs|desktop|ios|cloudflare|verify|done|blocked",
  "notes": []
}

For cron mode, also use a lock file under .ade/release/ so two releases do not overlap. If the lock is held by a live process, exit cleanly.

Phase 0: Preflight

Keep this phase read-only except for the .ade/release state/lock files. Do not edit release docs, bump versions, create tags, or upload artifacts until the relevant preflights pass.

1. Sync repository state:

   git fetch origin --tags --prune
   git status --short
   git rev-parse --abbrev-ref HEAD

2. Release from main. If not on main, switch only after confirming the worktree is clean.

3. Do not proceed with uncommitted changes unless they are the release docs changes created by this skill.

4. Verify tools:

   gh auth status

   Do not block a desktop-only release on ASC auth. Run asc doctor after scope detection if iOS is in scope.

5. Verify the desktop GitHub release workflow exists:

   test -f .github/workflows/release.yml
   test -f .github/workflows/release-core.yml
   test -f .github/workflows/release-publish.yml
   gh workflow view release.yml --repo arul28/ADE

6. For desktop releases, verify the workflow path is the intended one before tagging:

   • .github/workflows/release-core.yml builds dist:mac:arm64:signed.
   • .github/workflows/release-core.yml builds dist:mac:x64:signed.
   • .github/workflows/release-core.yml builds dist:win:signed in build-win-release.
   • The publish job merges per-arch manifests into one latest-mac.yml.
   • The publish job attaches the Windows installer, its .blockmap, and latest.yml when the Windows gate is on.

   If the workflow has been changed to publish universal updater ZIPs, stop and fix the workflow before releasing.

7. For desktop releases, resolve the expected platform matrix before tagging. This decides what the draft must contain in Phase 4:

   gh variable get ADE_WINDOWS_PUBLIC_RELEASE_ENABLED --repo arul28/ADE 2>/dev/null || echo "unset"

   • 1 means the release must carry macOS and Windows assets. Record platforms=mac,win.
   • Anything else, including unset, means macOS only. Record platforms=mac.

   Windows signing is fail-closed: if the gate is 1 and the signing secrets are missing, the verify job stops the run in about a minute. Do not "fix" that by clearing the gate mid-release; fix the secrets or stop.

8. For iOS releases, preflight App Clip packaging metadata before archiving:

   xcodebuild -showBuildSettings \
     -project apps/ios/ADE.xcodeproj \
     -scheme ADE \
     -configuration Release \
     -json > .ade/tmp/ios-release-build-settings.json

   Confirm from the JSON/build settings:

   • ADE, ADEWidgets, and ADEClip targets are present in the ADE scheme.
   • ADEClip Release IPHONEOS_DEPLOYMENT_TARGET matches the parent app baseline when Apple requires it. Current known-good value is 26.0.
   • ADEClip has ASSETCATALOG_COMPILER_APPICON_NAME=AppIcon.
   • ADEClip/Info.plist includes valid App Clip store metadata, supported interface orientations, and device family values accepted by App Store validation.
   • apps/ios/ExportOptions.auto.plist exists; prefer it for local ASC-backed archive/export.

   If any of these fail, fix and commit before archiving. Do not upload an IPA produced from uncommitted project-signing or App Clip metadata changes.

Phase 1: Detect Release Scope

Do this separately for desktop and iOS.

Desktop scope

Find the latest public desktop release tag:

DESKTOP_LAST_TAG=$(git tag --list 'v*' --sort=-v:refname | head -n 1)
git diff --name-only "$DESKTOP_LAST_TAG..origin/main"

Desktop release is needed if any changed file matches:

• apps/desktop/**
• apps/ade-cli/**
• desktop/runtime release scripts under apps/desktop/scripts/**
• .github/workflows/release*.yml, .github/workflows/update-brew-tap.yml, .github/workflows/publish-runtime-packages.yml
• shared package files that desktop imports
• root package/build files that affect desktop packaging

Do not count these as product changes by themselves:

• changelog/**
• docs/**
• sdk/** (Mintlify SDK tab — handled under SDK / public docs scope)
• docs.json
• CHANGELOG.md
• pure website/docs assets

iOS scope

iOS needs its own shipped marker. Prefer tags of this shape:

ios-v<marketing-version>-build<build-number>

Find the latest one:

IOS_LAST_TAG=$(git tag --list 'ios-v*-build*' --sort=-creatordate | head -n 1)

If no iOS shipped tag exists, do not guess in cron mode. Ask once to bootstrap from the latest known TestFlight build and create the first tag at the current release commit after the next successful upload.

iOS release is needed if any changed file since IOS_LAST_TAG matches:

• apps/ios/**
• Swift/iOS-specific shared files
• iOS signing/export configuration

Do not use desktop tags to decide iOS scope once iOS shipped tags exist.

SDK / public docs scope

This does not trigger a desktop GitHub release by itself. npm publish is publish-sdk-packages.yml on merge to main (OIDC), not this conductor.

SDK Mintlify pages (sdk/*.mdx) and the two npm READMEs need an update if since $DESKTOP_LAST_TAG (when desktop is in scope) — or, when checking an SDK-only window, since the last commit that already shipped those docs — any of:

• packages/sdk/**
• packages/chat-ui/**
• apps/desktop/src/shared/callerMcpServers.ts (honesty table)
• apps/ade-cli embedded profile / parentDeathWatchdog
• sdk/*.mdx already in the diff (verify they still match the code)

Print SDK docs: <yes|no> with that decision. User-visible contract changes (install, threads, MCP residuals, chat-ui props, doctor() fields) are yes. Internal-only test or comment churn is no.

Scope outcomes

Print one concise decision:

Scope: desktop=<yes|no> ios=<yes|no> sdk-docs=<yes|no>
Desktop since: <DESKTOP_LAST_TAG>
iOS since: <IOS_LAST_TAG or bootstrap-needed>

If desktop and iOS are both no:

• If sdk-docs is yes, do not tag a desktop release. Land or require the Mintlify/README updates on the SDK PR (or a docs-only follow-up). This conductor does not npm publish.
• If sdk-docs is also no, write state phase=done and stop.

Phase 2: Resolve Versions

Desktop

If desktop is in scope:

1. Parse latest tag vMAJOR.MINOR.PATCH.
2. Increment only PATCH.
3. New tag is vMAJOR.MINOR.PATCH+1.
4. Verify the tag and GitHub Release do not already exist.

Example:

v1.2.14 -> v1.2.15

iOS

If iOS is in scope:

1. Read the current marketing version from the Xcode project or latest ASC pre-release version. Do not change it.

2. Ask ASC for the next build number:

   asc builds next-build-number --app 6762759870 --version "$MARKETING_VERSION" --platform IOS

3. Use that build number. Do not hand-increment from local files if ASC says a different number is next.

Phase 3: Release Notes and Docs

Only create public desktop changelog entries when desktop is in scope. A mobile-only TestFlight build does not need a public desktop changelog unless the user asks.

For desktop releases, update all release-doc surfaces:

• changelog/v<VERSION>.mdx
• docs.json (changelog page list)
• changelog/index.mdx
• root CHANGELOG.md

Additionally, when sdk-docs is yes (whether or not desktop is in scope):

• Update the Mintlify SDK tab: sdk/overview.mdx, sdk/install.mdx, sdk/quickstart.mdx, sdk/threads.mdx, sdk/mcp.mdx, sdk/chat-ui.mdx, sdk/runtime.mdx, sdk/reference.mdx, and the docs.json SDK tab / footer links if pages were added or renamed.
• Keep the MCP honesty table aligned across sdk/mcp.mdx, packages/sdk/README.md, and docs/features/sdk/README.md. Strict MCP is enforced only on Claude; never market it as uniform. mcpCapability (strictRequested first, then level === "enforced") is the honesty mechanism.
• Both npm READMEs (packages/sdk/README.md, packages/chat-ui/README.md) must link to https://www.ade-app.dev/docs/sdk/overview as the full docs. README edits publish on the next @ade-dev/sdk / @ade-dev/chat-ui version bump (publish-sdk-packages.yml). Do not npm publish from this skill.
• Register new Mintlify pages in docs.json before validating.

Then run:

node scripts/validate-docs.mjs

Commit and land the docs/release metadata on main before tagging. The desktop release tag must point at the final main commit that includes the changelog. An SDK-docs-only commit does not get a v* tag.

Phase 4: Desktop GitHub Workflow Release

Do this only if desktop scope is yes. If iOS or Cloudflare is also in scope, start those legs as soon as the tag exists — see Parallel schedule. This phase is the desktop leg, not a barrier in front of the others.

The desktop happy path is GitHub Actions. Do not run local desktop release commands such as release:mac:local, dist:mac:universal:signed, dist:mac:perarch:signed, or manual gh release upload from the release host.

Create the release tag

The tag must point at a commit that already has a green ci-pass check run. release-core.yml's verify job is fail-closed on it: it looks up the ci-pass check run for the tagged SHA and exits 1 with No ci-pass check run was found for <sha>. Run CI before releasing. when the check is absent, still running, or red. Merging the release-docs PR and tagging immediately is exactly how you hit this — the squash-merge creates a brand-new commit on main whose CI has not started yet.

Wait for it before tagging:

RELEASE_SHA=$(git rev-parse origin/main)
gh api "repos/arul28/ADE/commits/$RELEASE_SHA/check-runs" \
  --jq '.check_runs[] | select(.name=="ci-pass") | {status,conclusion,html_url}'

Tag only when that prints completed / success. An empty result means CI has not reported on the commit yet.

After release docs are committed on main and ci-pass is green:

git fetch origin --tags --prune
git status --short
RELEASE_SHA=$(git rev-parse origin/main)
git rev-parse --verify "v<VERSION>" >/dev/null && {
  echo "Tag v<VERSION> already exists"
  exit 1
}
git tag -a "v<VERSION>" "$RELEASE_SHA" -m "ADE v<VERSION>"
git push origin "v<VERSION>"

If you tagged early and verify failed, the tag is still correct and nothing was published — do not delete or move it. Wait for ci-pass to go green on the same SHA, then rerun only the failed job:

gh run rerun "$RUN_ID" --repo arul28/ADE --failed

The pushed tag triggers .github/workflows/release.yml, which calls .github/workflows/release-core.yml and creates a draft GitHub Release.

Find and poll the workflow run

Find the run for the pushed tag/SHA:

gh run list --repo arul28/ADE --workflow release.yml --event push \
  --json databaseId,headBranch,headSha,status,conclusion,createdAt,url \
  --limit 20

Choose the run whose headBranch is v<VERSION> or whose headSha matches RELEASE_SHA.

If this is a desktop-only release, gh run watch is fine:

gh run view "$RUN_ID" --repo arul28/ADE --json status,conclusion,url,jobs
gh run watch "$RUN_ID" --repo arul28/ADE --interval 60

If iOS or Cloudflare is also in scope, poll instead and keep those legs moving. gh run watch blocks the conductor for the whole notarization window.

gh run view "$RUN_ID" --repo arul28/ADE --json status,conclusion,url,jobs
# Poll on a timer between iOS/Cloudflare steps; do not exclusive-watch.

Expected shape:

• runtime/resource jobs run first
• arm64 mac release and x64 mac release build/sign/notarize independently
• build-win-release builds/signs/validates Windows independently, in parallel with the mac jobs, when platforms includes win. With the gate off it is skipped, and a skipped Windows job does not block the mac release.
• publish-release (in release-publish.yml, called by release.yml after run-release succeeds) merges the per-arch updater manifests and creates the draft
• update-brew-tap and Publish ADE runtime packages both run after the GitHub release is made public (release.published), not when the draft is created. After undraft, poll both runs together and join both. Do not finish the npm wait before starting the brew wait, or the reverse.

If platforms=mac,win and build-win-release did not run, stop. The gate and the run disagree, and publishing would ship a macOS-only release under a version that is supposed to carry Windows.

Retry policy

Do not start duplicate full release workflows.

If a job fails or is cancelled:

gh run rerun "$RUN_ID" --repo arul28/ADE --failed

If one mac notarization step sits far beyond recent normal history, treat it as stuck instead of waiting forever. Recent normal mac notarize/staple time has been about 6-8 minutes; use 12-15 minutes as the practical cutoff unless GitHub logs show useful progress. Cancel only the stuck run, then rerun failed jobs:

gh run cancel "$RUN_ID" --repo arul28/ADE
gh run rerun "$RUN_ID" --repo arul28/ADE --failed

If GitHub cannot recover after one narrow rerun, stop and report the failing job URL/log excerpt. Do not switch to local desktop publishing unless the user explicitly authorizes a manual recovery.

Draft release verification

When the workflow succeeds, the release should still be draft/private. Verify the draft before publishing:

gh release view "v<VERSION>" --repo arul28/ADE --json tagName,isDraft,url,assets
rm -rf ".ade/tmp/release-v<VERSION>-verify"
mkdir -p ".ade/tmp/release-v<VERSION>-verify"
gh release download "v<VERSION>" --repo arul28/ADE \
  --pattern latest-mac.yml \
  --dir ".ade/tmp/release-v<VERSION>-verify" \
  --clobber
cat ".ade/tmp/release-v<VERSION>-verify/latest-mac.yml"

When platforms includes win, also pull the Windows updater feed:

gh release download "v<VERSION>" --repo arul28/ADE \
  --pattern latest.yml \
  --dir ".ade/tmp/release-v<VERSION>-verify" \
  --clobber
cat ".ade/tmp/release-v<VERSION>-verify/latest.yml"

Required assets, always:

• ADE-<VERSION>-arm64.dmg
• ADE-<VERSION>-arm64.zip
• ADE-<VERSION>-x64.dmg
• ADE-<VERSION>-x64.zip
• latest-mac.yml
• install.sh
• SHA256SUMS
• ade-darwin-arm64, ade-darwin-x64, ade-linux-arm64, ade-linux-x64, and the matching .native.tar.gz for each

Required additionally when platforms includes win:

• ADE-<VERSION>-win-x64.exe
• ADE-<VERSION>-win-x64.exe.blockmap
• latest.yml
• install.ps1
• ade-win32-x64.exe
• ade-win32-x64.native.tar.gz

Gate/asset agreement is a hard check, in both directions:

WINDOWS_GATE="$(gh variable get ADE_WINDOWS_PUBLIC_RELEASE_ENABLED --repo arul28/ADE 2>/dev/null || echo unset)"
WINDOWS_ASSETS="$(gh release view "v<VERSION>" --repo arul28/ADE --json assets \
  --jq '[.assets[].name | select(test("win-x64|win32-x64|^latest\\.yml$|^install\\.ps1$"))] | length')"
echo "gate=$WINDOWS_GATE windows_assets=$WINDOWS_ASSETS"

• gate=1 and windows_assets=0 means the Windows build silently did not contribute. Stop; keep the release draft/private.
• gate not 1 and windows_assets greater than 0 means Windows assets reached a release that was not supposed to carry them. Stop; keep the release draft/private.

Also verify:

• latest-mac.yml references the uploaded arm64 and x64 ZIPs.
• latest-mac.yml does not reference universal.
• no updater ZIP is suspiciously huge; a ZIP over about 900 MB needs human review because Squirrel.Mac can crash while handling oversized updater ZIPs.
• every latest-mac.yml referenced ZIP exists in the release assets.
• when Windows is in scope, latest.yml references the uploaded ADE-<VERSION>-win-x64.exe, and that installer and its .blockmap both exist in the release assets.
• SHA256SUMS lists every published standalone runtime asset, including the ade-win32-x64 entries when Windows is in scope, and lists nothing that is not published.

Publish public/latest

Only after verification passes:

gh release edit "v<VERSION>" --repo arul28/ADE --draft=false --latest
gh api repos/arul28/ADE/releases/latest \
  --jq '{tag_name,draft,prerelease,html_url,asset_count:(.assets|length)}'

Undrafting publishes the GitHub release. That event starts publish-runtime-packages.yml and update-brew-tap.yml. Poll both. npm versions are immutable, which is why this waits for --draft=false instead of the tag push. Desktop is not done until the npm job succeeds and npm view @ade-dev/runtime version equals this tag.

Do not exclusive-watch either run if iOS processing or Cloudflare is still in flight. Keep the run IDs and poll them between those legs. gh run watch belongs only to a desktop-only release, or to the join after the other legs have finished.

set -euo pipefail
# The release event can take a few seconds to enqueue the runs.
find_run() {
  local workflow="$1"
  gh run list --repo arul28/ADE --workflow "$workflow" --event release \
    --json databaseId,headBranch,status,conclusion,url \
    --jq "[.[] | select(.headBranch==\"v<VERSION>\")][0].databaseId"
}
run_id_ready() {
  [ -n "${1:-}" ] && [ "$1" != "null" ]
}
BREW_EXPECTED=0
if [ "$(gh secret list --repo arul28/ADE --json name --jq 'any(.[]; .name == "HOMEBREW_TAP_DEPLOY_KEY")')" = "true" ]; then
  BREW_EXPECTED=1
fi
for _ in 1 2 3 4 5 6; do
  NPM_RUN_ID=$(find_run publish-runtime-packages.yml)
  BREW_RUN_ID=$(find_run update-brew-tap.yml)
  if run_id_ready "$NPM_RUN_ID"; then
    if [ "$BREW_EXPECTED" != "1" ] || run_id_ready "$BREW_RUN_ID"; then
      break
    fi
  fi
  sleep 10
done
if ! run_id_ready "${NPM_RUN_ID:-}"; then
  echo "Publish ADE runtime packages did not start for v<VERSION>"
  exit 1
fi
if [ "$BREW_EXPECTED" = "1" ] && ! run_id_ready "${BREW_RUN_ID:-}"; then
  echo "update-brew-tap did not start for v<VERSION>"
  exit 1
fi

While iOS or Cloudflare is still in flight, poll — do not wait yet:

gh run view "$NPM_RUN_ID" --repo arul28/ADE --json status,conclusion,url
if [ -n "${BREW_RUN_ID:-}" ] && [ "$BREW_RUN_ID" != "null" ]; then
  gh run view "$BREW_RUN_ID" --repo arul28/ADE --json status,conclusion,url
fi

Desktop-only, or joining after the other legs finished. Watch both in parallel so neither wait starts only after the other has already completed:

gh run watch "$NPM_RUN_ID" --repo arul28/ADE --interval 30 --exit-status &
NPM_WATCH=$!
if [ -n "${BREW_RUN_ID:-}" ] && [ "$BREW_RUN_ID" != "null" ]; then
  gh run watch "$BREW_RUN_ID" --repo arul28/ADE --interval 30 --exit-status &
  BREW_WATCH=$!
fi
wait "$NPM_WATCH"
[ -n "${BREW_WATCH:-}" ] && wait "$BREW_WATCH"
gh run view "$NPM_RUN_ID" --repo arul28/ADE --json conclusion,url --exit-status
if [ -n "${BREW_RUN_ID:-}" ] && [ "$BREW_RUN_ID" != "null" ]; then
  gh run view "$BREW_RUN_ID" --repo arul28/ADE --json conclusion,url --exit-status
fi
RUNTIME_VERSION=$(npm view @ade-dev/runtime version)
DARWIN_VERSION=$(npm view @ade-dev/runtime-darwin-arm64 version)
if [ "$RUNTIME_VERSION" != "<VERSION>" ] || [ "$DARWIN_VERSION" != "<VERSION>" ]; then
  echo "expected @ade-dev/runtime@<VERSION> and @ade-dev/runtime-darwin-arm64@<VERSION>, got $RUNTIME_VERSION / $DARWIN_VERSION"
  exit 1
fi

If the npm run fails because Trusted Publisher / RUNTIME_TRUSTED_PUBLISHING is not configured, that is a release blocker, not a skip. workflow_dispatch on the same workflow (tag + confirm publish) is recovery only.

A missing brew run is not a skip when HOMEBREW_TAP_DEPLOY_KEY is configured; treat a failed tap bump as a desktop-leg failure.

Phase 5: iOS TestFlight Build and Distribution

Do this only if iOS scope is yes. Start it after the shared ci-pass + tag gate (or immediately on an iOS-only release). Do not wait for the desktop draft, undraft, npm publish, or brew tap — see Parallel schedule.

Preflight:

asc doctor
asc testflight groups list --app 6762759870 --paginate

Normal build rule:

• Use current MARKETING_VERSION.
• Use ASC next build number.
• Include app, widgets, and App Clip.
• Do not omit App Clip unless the user explicitly accepts an emergency build.

Recommended explicit sequence:

OUT=.ade/tmp/ios-testflight-$MARKETING_VERSION-build$BUILD_NUMBER
mkdir -p "$OUT"

ASC_KEY_PATH=$(jq -r '.profiles.ade.keyPath // .keyPath // .privateKeyPath // .private_key_path // empty' ~/.asc/config.json)
ASC_KEY_ID=$(jq -r '.profiles.ade.keyId // .keyId // .key_id // empty' ~/.asc/config.json)
ASC_ISSUER_ID=$(jq -r '.profiles.ade.issuerId // .profiles.ade.issuer_id // .issuerId // .issuer_id // empty' ~/.asc/config.json)

asc xcode archive \
  --project apps/ios/ADE.xcodeproj --scheme ADE \
  --configuration Release --clean \
  --archive-path "$OUT/ADE.xcarchive" --overwrite --output json \
  --xcodebuild-flag=-destination --xcodebuild-flag=generic/platform=iOS \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --xcodebuild-flag=-authenticationKeyPath --xcodebuild-flag="$ASC_KEY_PATH" \
  --xcodebuild-flag=-authenticationKeyID --xcodebuild-flag="$ASC_KEY_ID" \
  --xcodebuild-flag=-authenticationKeyIssuerID --xcodebuild-flag="$ASC_ISSUER_ID" \
  --xcodebuild-flag=CURRENT_PROJECT_VERSION=$BUILD_NUMBER \
  --xcodebuild-flag=MARKETING_VERSION=$MARKETING_VERSION

asc xcode export \
  --archive-path "$OUT/ADE.xcarchive" \
  --export-options apps/ios/ExportOptions.auto.plist \
  --ipa-path "$OUT/ADE.ipa" --overwrite --output json \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --xcodebuild-flag=-authenticationKeyPath --xcodebuild-flag="$ASC_KEY_PATH" \
  --xcodebuild-flag=-authenticationKeyID --xcodebuild-flag="$ASC_KEY_ID" \
  --xcodebuild-flag=-authenticationKeyIssuerID --xcodebuild-flag="$ASC_ISSUER_ID"

Before upload, unpack and inspect the exported IPA. This is mandatory for App Clip releases:

TMP_IPA_CHECK="$OUT/ipa-check"
rm -rf "$TMP_IPA_CHECK"
mkdir -p "$TMP_IPA_CHECK"
ditto -x -k "$OUT/ADE.ipa" "$TMP_IPA_CHECK"
/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$TMP_IPA_CHECK/Payload/ADE.app/Info.plist"
/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$TMP_IPA_CHECK/Payload/ADE.app/Info.plist"
/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' "$TMP_IPA_CHECK/Payload/ADE.app/Info.plist"
find "$TMP_IPA_CHECK/Payload/ADE.app" -maxdepth 3 -name 'ADEClip.app' -print
find "$TMP_IPA_CHECK/Payload/ADE.app" -maxdepth 3 -name 'ADEWidgets.appex' -print

Before continuing, inspect ADEClip.app/Info.plist too. Continue only if the main app, widgets, and App Clip all use the intended marketing version/build number and the App Clip bundle has the expected icon/deployment metadata.

Use Apple package validation before upload so metadata errors surface before the final upload step:

xcrun altool --validate-app --type ios --file "$OUT/ADE.ipa" \
  --apiKey "$ASC_KEY_ID" --apiIssuer "$ASC_ISSUER_ID"

Upload only after validation passes:

asc builds upload --app 6762759870 --ipa "$OUT/ADE.ipa"

asc builds wait \
  --app 6762759870 \
  --build-number "$BUILD_NUMBER" \
  --version "$MARKETING_VERSION" \
  --platform IOS \
  --timeout 40m

When desktop is also in scope, do not park the whole conductor on this wait if the IPA is already uploaded. Poll asc builds list until processingState=VALID while undraft, npm, and brew proceed. asc builds wait is the iOS-only happy path.

If automatic export fails due signing, use the repo's signing gotchas in AGENTS.md and the asc-* skills. Fix signing/profiles; do not silently remove targets.

After processing:

BUILD_ID=$(asc builds list --app 6762759870 --version "$MARKETING_VERSION" --platform IOS --limit 10 \
  | jq -r --arg b "$BUILD_NUMBER" '.data[]|select(.attributes.version==$b)|.id' | head -n1)

asc builds update --build-id "$BUILD_ID" --uses-non-exempt-encryption=false

Attach all non-empty beta groups:

asc testflight groups list --app 6762759870 --paginate
asc builds add-groups --build-id "$BUILD_ID" --group "<group-id>" --submit --confirm

Use --submit --confirm for external groups. Internal groups may also be added explicitly if they do not automatically receive the build.

Verify every group:

asc builds info --build-id "$BUILD_ID"
asc builds build-beta-detail view --build-id "$BUILD_ID"
for gid in <all-group-ids>; do
  asc testflight groups links view --group-id "$gid" --type betaTesters
  asc testflight groups links view --group-id "$gid" --type builds
done

Success requires:

• build processingState=VALID
• usesNonExemptEncryption=false
• internalBuildState is READY_FOR_BETA_TESTING or IN_BETA_TESTING
• external groups are IN_BETA_TESTING or otherwise clearly submitted/approved
• each target group has at least one tester
• each target group contains the new build

After successful distribution, tag the shipped iOS build:

git tag -a "ios-v${MARKETING_VERSION}-build${BUILD_NUMBER}" "$RELEASE_SHA" \
  -m "iOS ${MARKETING_VERSION} build ${BUILD_NUMBER}"
git push origin "ios-v${MARKETING_VERSION}-build${BUILD_NUMBER}"

Phase 5.5: Cloudflare Surfaces (Pages + Workers + account state)

The GitHub desktop workflow and TestFlight do NOT touch the hosted web tier. Every release reconciles it, or production silently drifts (this bit v1.2.28 and v1.2.29: a rewritten web client and two changed Workers sat undeployed while the desktop shipped).

Start this phase as soon as the docs PR (or any in-scope main push) lands. deploy-web.yml runs on that push. Do not wait for the desktop tag, the draft, npm, or TestFlight — see Parallel schedule.

A Cloudflare surface has two halves, and only one of them is in git. The code half is wrangler.jsonc plus src/. The account half — whether the R2 bucket exists, whether it has a lifecycle rule, whether a D1 migration was actually applied, whether a secret is bound — lives in the Cloudflare account and in no repository file. No test in this repo can fail on it. Phase 5.5 exists to check the account half.

Hard rules for this phase

• Package-owned deploy entry points are mandatory. npm run deploy / npm run deploy:production for each app. They own the D1 migrations, the binding/secret preflights, and the post-deploy auth smokes. npx wrangler deploy is a bypass, not a workaround. If an entry point stops on a preflight, a missing migration, or a missing smoke credential, repair that blocker and rerun the entry point.
• Reconcile bindings against the account BEFORE deploying. A binding that names a resource which does not exist in the account is a deploy-time failure no code test catches.
• /health green is not verification. Know what each endpoint actually proves. ade-account-directory (apps/account-directory/src/directory.ts:1047) and ade-github-webhook-relay (apps/webhook-relay/src/relay.ts:2701) return a bare {"ok":true} from a handler that runs before any binding, migration, or secret is touched — those prove reachability and nothing else. ade-tunnel-relay reports its protocol version and deployed Worker version tag; ade-push-relay (apps/push-relay/src/relay.ts:1333) reports whether APNs and each Clerk issuer are configured — substantive, but still blind to D1 migration state. No /health in this repo checks migrations. Green /health with 500s on every authenticated route is a state this repo has actually shipped.
• A failed Cloudflare surface is a release blocker. Record it in the release state file with status: "blocked" and a note. Never silently skip a surface and report the release as complete.
• Deploy from the release commit on main, never from a lane.

Step 1: Scope

.github/workflows/deploy-web.yml already deploys these surfaces on push to main, path-filtered per surface. The normal case is therefore verification, not deployment: find the Deploy Web Surfaces run for the release SHA and confirm each in-scope job succeeded. Deploy by hand only when that run failed, was skipped, or the release commit predates it.

The Cloudflare baseline is not the desktop tag. This tier ships on merge, on its own cadence; a desktop tag says nothing about what is live on Cloudflare. If a web change landed before the last desktop tag and its deploy-web.yml job failed or never ran, a LAST_TAG..origin/main diff reports that surface unchanged forever. Derive each surface's baseline from what actually deployed — the newest run whose job for that surface concluded success. Job names are webclient, account-directory, webhook-relay, tunnel-relay, push-relay; a skipped job is not a success and does not appear in jobs at all.

runs="$(gh run list --repo arul28/ADE --workflow deploy-web.yml --branch main \
  --json databaseId --limit 20 --jq '.[].databaseId')"
for surface in webclient account-directory webhook-relay tunnel-relay push-relay; do
  base=""
  for id in $runs; do
    sha="$(gh run view "$id" --repo arul28/ADE --json headSha,jobs \
      --jq "if any(.jobs[]; .name==\"$surface\" and .conclusion==\"success\") then .headSha else empty end")"
    if [ -n "$sha" ]; then base="$sha"; break; fi
  done
  echo "$surface baseline=${base:-UNKNOWN}"
done

UNKNOWN means nothing in the last 20 runs proves that surface is current. Treat it as changed and reconcile it fully; never treat an unknown baseline as "unchanged". Run this in bash — zsh does not word-split $runs.

Then diff each surface against its own baseline ($base from above), using deploy-web.yml's paths-filter verbatim:

git log <base>..origin/main --oneline -- apps/account-directory   # account-directory
git log <base>..origin/main --oneline -- apps/webhook-relay       # webhook-relay
git log <base>..origin/main --oneline -- apps/tunnel-relay        # tunnel-relay
git log <base>..origin/main --oneline -- apps/push-relay          # push-relay
git log <base>..origin/main --oneline -- \
  apps/desktop/src/renderer apps/desktop/src/shared apps/desktop/vite.webclient.config.ts  # webclient

The desktop-tag diff (git log $LAST_TAG..origin/main -- apps/...) is a secondary signal only — useful for the release note, never for the deploy decision.

Now confirm the run for the release commit itself. Resolve RUN_ID from the release SHA and fail loudly when there is no match — no matching run means CI never deployed this commit, which is a manual-deploy case, not a pass:

RELEASE_SHA="$(git rev-parse origin/main)"
RUN_ID="$(gh run list --repo arul28/ADE --workflow deploy-web.yml \
  --json databaseId,headSha --limit 50 \
  --jq "[.[] | select(.headSha == \"$RELEASE_SHA\")] | .[0].databaseId // empty")"
[ -n "$RUN_ID" ] || echo "no deploy-web.yml run for $RELEASE_SHA — deploy by hand"
[ -n "$RUN_ID" ] && gh run view "$RUN_ID" --repo arul28/ADE --json status,conclusion,jobs

A workflow_dispatch run deploys every surface — use it as the manual full reconcile when the automatic run is untrustworthy:

gh workflow run deploy-web.yml --repo arul28/ADE

Any surface whose baseline came back UNKNOWN goes through that dispatch.

Record each surface's baseline SHA, changed, and action (skip / ci / manual) in the state file before doing anything else.