Ship Release

Ship a KeeForge release

Read the shared release contract and soak guidance, then follow this workflow.

Use this skill when the user decides to ship, after the soak guidance signals have been reported to them.

Do not re-check the CI gates here. All cloud gates and local gates were read and adjudicated in candidate gates, and accepting them is what allowed the build to reach external testers in the first place (invariant 3). That verdict is release preparation's job and it is final: do not poll Xcode Cloud or GitHub Actions check runs for the RC commit, do not reopen gate-adjudication.md, and do not treat a test action that was red but accepted as a flake — or a later re-run of either workflow — as a reason to stop. The soaked binary already carries the verdict. If it turns out a gate was never accepted, you are not in production shipping; go back to candidate gates.

Confirm what you are shipping

Record explicitly, and state it back to the user before proceeding:

• The marketing version, repo build, and both TestFlight build numbers of the soaked builds.
• Its rc/{version}-b{repoBuild} tag and commit SHA. The tag identifies the commit; each platform-specific TestFlight number identifies its binary, and neither is required to equal the repo build.
• The direct Mac CFBundleVersion, zip hash, and notarization ID.
• Both distribution timestamps, elapsed soak times, unique-install/crash counts, and direct install/update results.
• Which soak guidance signals, if any, are short of target.

Each TestFlight build number here is the build you will select for its platform in App Store Connect. If either does not match the build distributed and soaked, stop — something is out of sync. Do not substitute a newer build.

Correct the changelog date if the soak crossed a day

If CHANGELOG.md's ## v{version} ({date}) no longer matches the actual ship date, fix it on the release branch now. This is a documentation-only change and does not require a new build — the changelog is not compiled into the binary. Merge that correction to main before the audit below.

Audit that main has every fix

Because backports and the date correction are merges, this is an exact check rather than a judgement call:

git fetch origin --tags
git merge-base --is-ancestor origin/release/{major}.{minor} origin/main \
  && echo "main contains the release branch" \
  || git log --oneline origin/main..origin/release/{major}.{minor}

If the check fails, the listed commits are on the release branch and not on main. Run merge-back guidance to merge them before shipping. Do not ship with an unmerged fix.

Stage both App Store submissions; do not create the shipped tag yet

Invoke publish-app-store-version once for iOS and once for macOS. Attach the exact soaked TestFlight build numbers from the manifest, save the platform-specific metadata/screenshots, and stage each platform independently through Ready for Review, then stop. Do not submit either platform yet. If the user later requests submission, obtain separate explicit action-time confirmation immediately before each platform's API submission request; confirmation for one platform does not authorize the other. Configure both records for manual release and leave approved versions held. v{version} does not exist yet.

If Apple requests a metadata-only correction, fix only that platform's record. If Apple requests a code change, return to candidate respin and respin all three artifacts. Never substitute a newer unsoaked build.

Create the shipped tag after review approval and final go

Wait until both App Store submissions have code approval and the user gives the final coordinated go decision. Record that non-secret decision/evidence and completed soak observations in the manifest: set each platform's appStoreReviewState, preserve the separate beta reviewState, and record each soak's accepted verdict/evidence, metrics, or owner-accepted exceptions. Then validate the ship evidence. Then create v{version} on the accepted RC commit; it triggers no build and records the code that actually shipped. Include any accepted soak exception in the tag message.

ci_scripts/candidate_manifest.py validate \
  --manifest scratch/release-manifests/{version}-b{repoBuild}.json --mode ship

git fetch origin --tags
rc_tag='rc/{version}-b{repoBuild}'
rc_commit=$(git rev-list -n1 "$rc_tag")
git tag -a 'v{version}' -m 'Release v{version} — shipped RC '"$rc_tag" "$rc_commit"
git push origin 'refs/tags/v{version}'

Keep every rc/* tag. They are the audit trail of the candidates, including the ones that were replaced.

If git fetch origin --tags reports ! [rejected] ... (would clobber existing tag), a local tag has drifted from the remote. The remote is authoritative for released tags: inspect both sides, then realign with git fetch origin --tags --force.