---
name: ship-release
description: Merge a verified OpenIAP PR, release every affected stable package one at a time, verify each public registry, verify the release note the PR carried, stabilize any correction with review-self, and deploy production docs. Use when the user explicitly asks for this full post-review shipping workflow.
---

# Ship an OpenIAP Release

Complete a verified OpenIAP change from merge through public package and docs
delivery. This skill coordinates existing repository workflows; their detailed
rules remain the SSOT.

## Authority and required reading

This workflow performs public and irreversible actions. Use it only when the
user explicitly authorizes the requested merge, package publication, docs
deployment, and any direct `main` push. Missing authority for one stage stops
that stage without broadening the others.

New PRs follow `knowledge/internal/06-git-deployment.md#opening-pull-requests`;
shipping an existing PR does not authorize opening a recovery PR.

Before acting, read:

- `AGENTS.md`
- `.codex/skills/openiap-workflows/SKILL.md`
- `.claude/commands/release.md`
- `.codex/skills/generate-doc/SKILL.md`
- `.codex/skills/review-self/SKILL.md`
- `.claude/commands/commit.md`

Load every convention file and specialized E2E skill required by the changed
paths. Never mutate production Convex data.

## 1. Establish the exact release scope

1. Confirm the PR is approved, required CI is successful on its exact head,
   review threads are clear, and any required device gate has passed or has an
   explicit recorded waiver. Apply
   `knowledge/internal/05-docs-patterns.md#release-note-completeness-gate`
   before merging; fix missing coverage in that PR and revalidate its head.
2. Merge with the repository-supported method, then fast-forward local `main`.
3. Require a clean worktree and verify `HEAD` equals `origin/main`.
4. Classify affected packages from the merged diff. Release only packages with
   a user-visible or contract-relevant change; do not bump unaffected packages
   for symmetry.
5. Select stable SemVer bumps from the actual compatibility impact and run all
   preflight audits required by `.claude/commands/release.md`. The in-tree
   `specs/client/package.json` version is released with `version=current` when
   a feature PR already set it.

## 2. Publish packages sequentially

Release one affected package at a time in the canonical dependency order in
`.claude/commands/release.md#stable-release`, including the affected protocol
and CLI packages. Reapply the completeness gate if the release scope changes.

For each package:

1. Dispatch the stable release workflow from the exact current `main`.
2. Wait for every validation and publication job to finish successfully.
3. Fast-forward local `main` and fetch the new tag.
4. Confirm package metadata, the release tag, and the release commit agree.
5. Verify the artifact through its public registry or distribution endpoint,
   including provenance or consumer smoke checks when the workflow supplies
   them. Registry propagation can lag; poll until the public endpoint returns
   the new version before starting the next package.

Do not run package releases concurrently. Stop on the first failed gate and
report the exact workflow job and package state. If the user requests docs
before package publication, use the explicit flag documented in
`knowledge/internal/06-git-deployment.md#deploying-documentation`. If the train
will not resume, trim the card to the packages that published through §4.

Godot releases also require the authenticated Godot Asset Library listing to be
updated. Prepare the edit when possible, request action-time confirmation before
the public form submission, and report it as an explicit remaining manual step
when authentication is unavailable. Never reuse credentials supplied for a
different service.

## 3. Verify the release note

The merged PR carried the consolidated release card in
`packages/docs/src/pages/docs/updates/releases.tsx` (see `generate-doc`). After
every package version and public URL is known:

- Compare each version and link on the card with current package metadata and
  the published tags, and correct any that differ.
- Missing package or behavior coverage must have been fixed before publication
  through the completeness gate; this step verifies the published results.
- Lead with user-visible behavior, include required migration or platform
  caveats once, and omit version-bump mechanics.
- Add no versioned IAPKit entry; it is a service.

If nothing differs, go to §5.

## 4. Stabilize and commit a correction

When §3 changed the card, run `review-self` against the docs diff until two
consecutive full snapshots are clean at least five minutes apart. A material
change resets the clean count. Run all path-specific validation, including the
docs build, docs and release-state audits, skill validation, and
`git diff --check`.

Commit and push through `.claude/commands/commit.md`. An explicit invocation of
this full shipping workflow authorizes the release-note and release-process
documentation commit directly on `main`; do not open a PR for that post-release
docs-only commit. Immediately before committing, fast-forward from `origin/main`
and revalidate that the intended files are the only changes. Product-code fixes
still return to the normal PR loop.

## 5. Deploy and verify docs

From a clean local `main` equal to `origin/main`:

1. Run `bun run audit:commerce-evidence`. If it reports drift, re-record the
   IAPKit interop per `packages/kit/scripts/docs/commerce-interop.md` before
   deploying; the guide page shows the recorded revision either way.
2. Wait for Vercel's production deployment of main's head. Use the manual
   deploy only when the automatic path cannot complete.
3. Fetch the production release page and generated LLM documents with a cache
   buster. Confirm the new release title, API name, versions, and generated
   timestamp are present.
4. Recheck required CI for the final `main` head and report any still-pending
   external listing or registry state separately.

## 6. Leave the shipped comment

After verifying public delivery, leave one short English completion comment on
the originating PR and each linked issue resolved by this release, within the
user-authorized GitHub follow-up scope. Check existing comments first and avoid
duplicates, including on already-closed issues. If no issue is linked, comment
on the PR only. A single sentence is enough: `Shipped in <package> <version>.`
Link the verified release or deployment when useful. A merge alone is not proof
of shipment. Confirm the posted comment and include its URL in the final report.

## Completion report

Report the merged PR and commit, every published version with its public
verification, docs commit and deployment result, review-self clean snapshots,
the docs release, and any explicitly incomplete external marketplace update.