release-openclaw-maintainer

# OpenClaw Release Maintainer Use this skill for release and publish-time workflow, including preparing the approved backport set for an extended-stable maintenance release. Load `$release-private` if it exists before resolving Peter-owned credential locators or private host topology. Keep ordinary development changes and GHSA-specific advisory work outside this skill. ## Freeze the release state Before validation or publication, write one compact state record and keep it current: - goal and terminal success criteria - release version, tag, branch, cut SHA, Code SHA, Tooling SHA, and Release SHA - active Full Release Validation parent run id and attempt - npm preflight and publish parent run ids - completed phases and immutable child artifacts - approved backports or main changes - current phase, next action, and one precise blocker if stopped Use `references/release-handoff-template.md` when starting a release session, recovering after compaction, or handing the release to another operator. After compaction, resume, or new steering, the latest explicit operator instruction replaces the effective goal and phase; do not merge superseded scope back into the release. Completed phases stay complete. Reopen one only when a named event invalidates its evidence, such as a Code SHA change, a non-changelog Release SHA change, or a workflow fix that the existing parent run cannot consume. ## Respect release guardrails - Do not change version numbers without explicit operator approval. - When normal beta/stable release planning includes a backport audit, read `references/backport-discovery.md` before selecting commits. Freeze the release baseline and main SHA, complete the durable candidate ledger, and get approval for its categorized set before mutating the release branch. This audit is required for discovery; it does not authorize optional backports on an already-frozen candidate. - Backports are optional and operator-selected. When a backport is requested without a target, use the newest open `release/` branch. - Versions use `YYYY.M.PATCH`, where `PATCH` is the sequential release-train number within the month, not the calendar day. - Choose a new beta train from stable and beta releases only. Alpha-only tags do not consume or advance the beta/stable patch number. Continue the highest existing unpublished/published beta train with the next `beta.N` when appropriate; otherwise increment the highest stable/beta patch by one and start at `beta.1`. - Example: after stable `2026.6.5`, the next new beta train is `2026.6.6-beta.1`, even if automated alpha-only tags such as `2026.6.10-alpha.1` exist. - Obtain explicit operator approval before the first irreversible publish action. Instructions to cut, ship, publish, or get a named release out carry through that release's validated publish and verification steps; do not ask again at final dispatch. Reconfirm only if the target version, tag, channel, publish scope, or a material risk changes. - This skill should be sufficient to drive the normal release flow end-to-end. - Use the private maintainer release docs for credentials, recovery steps, and mac signing/notary specifics, and use `docs/reference/RELEASING.md` for public policy. - Core `openclaw` publish is manual `workflow_dispatch`; creating or pushing a tag does not publish by itself. - Do not edit the root `README.md` as release prep, release closeout, or a substitute for release notes. Package-root README validation is a hard packaging gate, but a release only changes README content when an actual user-facing documentation contract changed. - Normal release work happens on a branch cut from `main`, not directly on `main`. Use `release/YYYY.M.PATCH` for the branch name. - Hold release scope from cut-SHA selection through publish and verification. The active release is the work queue; moving `main` is only a trusted workflow and provenance source unless the operator explicitly requests main work. - Touch `main` during the active release only for an operator-requested change or a critical main-owned blocker that prevents this release and cannot be fixed or proven from the release branch. Examples include a live installer or trusted workflow that is sourced only from `main`. A red unrelated `main` check, baseline, refactor, cleanup, or later improvement is not a release blocker. - Do not broaden a release-critical main fix to make moving `main` green. Keep the change to the exact blocker, run focused proof, follow the required main landing policy, then return immediately to the release branch. If unrelated main health blocks that landing, report the blocker and continue independent release work instead of adopting the failure. - Defer normal forward-ports and main closeout until after publication. Forward-port before publish only when the operator requests it or `main` itself owns the exact release-critical runtime or workflow surface. - If the operator asks for a release without saying stable/full, default to beta only. Continue from beta to stable only when the operator explicitly asks for the full release or an automated beta-and-stable train. - Resolve the intended cut SHA once. If the operator supplies a SHA, use it exactly; do not pull, rebase, or advance it to newer `main`. Otherwise fetch `origin/main` once and record the selected full SHA plus its CI state. A red unrelated main check does not authorize healing main. - Create a clean release worktree and `release/YYYY.M.PATCH` from that selected SHA. Do not commit or absorb unrelated dirty files as release preparation. Finish version preparation plus any operator-selected backports, release-only fixes, and explicitly required pre-publish main changes. Backports are optional. Freeze this product-complete tree as the **Code SHA** without changing the release changelog. - Full product validation belongs to the Code SHA. If validation finds a code defect, fix it, freeze a new Code SHA, and validate that SHA. If the failure belongs to trusted workflow tooling, the harness, credentials, or infrastructure, repair the smallest owning surface and rerun against the same Code SHA. Touch `main` only under the active release scope lock above. Never mutate the release candidate to satisfy newer tooling or heal unrelated main. - Apply a release firebreak after the Code SHA is frozen. Admit only confirmed product defects, package/provenance defects in the bytes to publish, security defects, or failures that make publication impossible. Queue adjacent improvements and broad confidence findings for the next beta or postpublish work. - Operate with one release owner, one transition-only watcher, and at most one investigator for the current failed surface. One diagnosis, one fix when needed, and one narrow retry consume the failure budget; then reassess. - Generate `CHANGELOG.md` only after the Code SHA is green. The resulting **Release SHA** must be a descendant whose complete diff from the Code SHA is exactly `CHANGELOG.md`. Release-note checks, npm preflight/package bytes, install/update acceptance, tagging, and publication run against the Release SHA. Full product validation is reused through the `changelog-only-release-v1` evidence policy; any non-changelog source change returns to the Code SHA loop. - During release planning, inspect both `src/plugins/compat/registry.ts` and `src/commands/doctor/shared/deprecation-compat.ts` before branching and again before final publish. For every `deprecated` compatibility record whose `removeAfter` date is on or before the release date, either remove the compatibility path where safe and validate the affected tests, or change it to `removal-pending`, document the blocker, and get explicit maintainer approval. Revalidate every due `removal-pending` record's blocker and upgrade conditions before shipping; keep it only with explicit maintainer approval until those conditions are met. - When removing deprecated runtime/config compatibility, preserve any doctor migration, repair, or hint that is still needed by supported upgrade paths. Doctor-side compatibility should stay tracked in `src/commands/doctor/shared/deprecation-compat.ts` until maintainers confirm the repair is no longer needed. - Revalidate compatibility replacement text during release planning. The recommended replacement can shift as plugin ownership, externalization, and config footprint move, so do not blindly copy stale replacement annotations into release notes. - Do not delete or rewrite beta tags after their matching npm package has been published. If a pushed beta tag fails before npm publish, the version is not consumed: keep the same `-beta.N`, delete/recreate or force-move the git tag and prerelease to the fixed commit, and rerun preflight. Do not increment to the next beta number until the matching npm package has actually published. If a published beta needs a fix, commit the fix on the release branch and increment to the next `-beta.N`. - For a beta release train, keep Full Release Validation as a pre-publish Code SHA gate unless the operator explicitly waives it. Run independent validation lanes in parallel where safe, but do not start changelog or package finalization until the Code SHA is green. After the changelog-only Release SHA exists, its Full Release Validation run prepares and qualifies the final npm package and Docker artifacts while reusing product evidence. Run the package/install/update acceptance roster against those exact bytes. If a product defect appears, return to a new Code SHA; if a release-tooling or publication child fails, repair/resume that child without changing the candidate. After a published beta needs a code fix, increment the beta number and repeat. Defer its forward-port until after publication unless the operator requests it. Do not scan moving `main` for extra fixes during an active release unless the operator explicitly asks for that audit. Operators may authorize up to 4 autonomous beta attempts; after 4 failed beta attempts, stop and report. - An early standalone `OpenClaw Performance` run with `target_ref=<code-sha>` is optional beta confidence and may overlap other release work. Do not add a duplicate mandatory prepublish wait. Stable/full Full Release Validation retains its required blocking performance child. - Before publish/closeout, compare available product performance metrics with earlier releases: Kova agent-turn/resource metrics, gateway startup ready/listen/RSS/CPU metrics, and CLI startup metrics from release evidence or clawgrit reports. Report regressions explicitly. A major regression is a release blocker unless the operator waives it or the data clearly proves infrastructure noise. - Heal release-owned CI before changelog, tagging, or publishing. The exact Code SHA must have green `Full Release Validation`, including the root Dockerfile/install-smoke path. Treat a red Docker, package, or release workflow lane as a release-branch defect until the smallest correct fix is landed and proven; do not waive it because npm preflight or another sibling lane passed. Unrelated moving-main failures are not part of this gate. - Keep the canonical `scripts/pr` runner authoritative for prepare and merge artifacts. A release-gate policy change may use focused candidate tests and exact-SHA hosted CI for proof, but never route `prepare-*` or `merge-*` through PR-controlled scripts or synthesize prepare artifacts to bootstrap the change. If the current canonical gate cannot validate the new policy, stop for explicit maintainer direction rather than weakening that boundary. - In maintainer Testbox mode, use `OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR>` only after the exact PR head has passed `CI` and every scheduled hosted gate. For a workflow change, that means `Blacksmith Testbox`, `Blacksmith ARM Testbox`, `Blacksmith Build Artifacts Testbox`, and `Workflow Sanity`; only gates GitHub actually scheduled for that exact head are required. This preserves the canonical prepare artifacts while avoiding a redundant broad local suite. A literal `CHANGELOG.md`-only head gets a clean diff check instead because those workflows intentionally do not dispatch. Documentation and README changes still require CI. If `merge-run` requires a mainline sync, run `OPENCLAW_TESTBOX=1 scripts/pr prepare-sync-head <PR>`, wait for those hosted gates on the newly pushed SHA, then run `prepare-run` again. - If an exact PR-head CI run has no active jobs because Blacksmith capacity is stalled, a maintainer may dispatch the explicit GitHub-hosted fallback from the PR head branch. First verify its workflow carries the current schema with `gh api 'repos/openclaw/openclaw/contents/.github/workflows/ci.yml?ref=<pr-head-branch>' --jq .content | base64 --decode | rg -q 'pull_request_number:'`. If absent, refresh the PR head from `main`, use the new SHA, and let normal CI run before considering another fallback. Then dispatch: `gh workflow run ci.yml --repo openclaw/openclaw --ref <pr-head-branch> -f target_ref=<full-pr-sha> -f pull_request_number=<pr-number> -f include_android=true -f release_gate=true`. Use it only for an observed provider queue stall, never for failed CI or as a routine shortcut. The run must be named `CI release gate <full-pr-sha>` and pass on that exact SHA; the native hosted-gate verifier rejects generic manual CI runs. If `Blacksmith Build Artifacts Testbox` is the only remaining required gate and it is still queued without a runner, the same completed fallback CI may cover it because its `build-artifacts` job builds, packages, and smoke tests those artifacts. The verifier records that coverage. Never use this coverage when the artifact workflow has started, failed, been cancelled, or been skipped. Then rerun `OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR>`. - Generate the changelog once after the final Code SHA is fully green. Do not regenerate it for same-candidate tooling reruns, resumed publication, or promotion. If code changes, validate the replacement Code SHA first and then regenerate the release section once for that new history. Use `$openclaw-changelog-update` for the rewrite. Do not continue release prep if the target `CHANGELOG.md` section does not have `### Highlights`, `### Changes`, and `### Fixes`, grouped by user-facing surface while preserving every relevant PR/issue ref and every human `Thanks @...` attribution in the grouped bullet. - Changelog PR provenance follows `origin/main`, not the release integration PR. Cite the original merged main PR for equivalent backports. Keep a release-branch PR only when the change landed there first and has not yet been forward-ported to `main`. - Do not create beta-specific `CHANGELOG.md` headings. Beta releases use the stable base version section, for example `v2026.4.20-beta.1` uses `## 2026.4.20` release notes. - When any beta, stable, or extended-stable release is live, make a best-effort Discord announcement using the release-track-specific wording; do not block or roll back the release if the announcement fails. - When asked to announce on X, use `~/Projects/bird/bird` and follow the release tweet style below. ## Prepare extended-stable backports When asked to create the initial `.33` extended-stable line or a later maintenance patch, read `references/backport-discovery.md` and `references/extended-stable-backports.md` and follow both before version, tag, or publication work. Treat backport discovery and preparation as an ability of this release skill, not as a separate release workflow. The backport flow covers mainline inventory, private-security reconciliation, approval, the staging PR, and proof handoff. After it lands, use the sequence below. Never route `.33+` through regular beta/stable release steps. Extended-stable requires a visible **SDK/config backport warning** whenever a candidate changes the public plugin SDK or a config/default/schema/migration surface. Prefer an adaptation that uses the SDK and configuration already shipped on that line. If a contract change remains necessary, record its published impact and the maintainer decision in the ledger and staging PR. Read `references/extended-stable-backports.md`; a clean cherry-pick, green release checks, or a regenerated baseline does not by itself explain the maintenance risk. ## Publish Gateway extended-stable releases Use this path only for the trailing completed month's `.33+` Gateway distribution: the `openclaw` npm package, official npm plugins, and matching Docker Gateway images. Treat `docs/reference/RELEASING.md`, `scripts/openclaw-npm-extended-stable-release.mjs`, and the release workflows on pinned current `main` as the exact command and validation contract. 1. On `extended-stable/YYYY.M.33`, verify the root and every publishable official plugin have the intended version. Generate and commit the complete `## YYYY.M.P` changelog section with `### Highlights`, `### Changes`, and `### Fixes`. Carry the full current-main Docker release-channel unit: workflow, promoter, policy, shared classifier, tests, and workflow validation. Run focused checks and freeze the untagged tip SHA. 2. Keep the frozen SHA and canonical branch as the validation target; Full Release Validation derives `npm_dist_tag=extended-stable` from the version. 3. Run complete Full Release Validation against the canonical branch with `release_profile=stable`; save its run ID and successful `run_attempt`. Prefer the trusted main-pinned harness, which attests the immutable target SHA in its manifest. Current manifests include qualified npm and prepared Docker artifacts; use that same run ID for npm preflight evidence. Historical manifests without them still need a separate npm preflight. Any candidate branch change invalidates both gates. 4. Require the tip still equals the frozen SHA, then create signed `vYYYY.M.P`. Never move or delete a final tag; later source changes need a new patch. 5. Require the saved validation run to be complete and successful, bind its manifest target SHA and attempt to the tag, and accept a direct run from the canonical branch, a direct current-`main` run whose workflow SHA is still reachable from main, or a trusted main-pinned `release-ci/*` harness. Reject narrow reruns. 6. Dispatch `plugin-npm-release.yml` from the same branch with `publish_scope=all-publishable`, the full release SHA as `ref`, and `npm_dist_tag=extended-stable`. Require complete exact-version and selector readback, then save the successful plugin run ID. 7. Publish core with the tag, `npm_dist_tag=extended-stable`, all three run IDs, and `full_release_validation_run_attempt=<saved-attempt>`. Normally dispatch from the canonical branch. For a workflow-only recovery after the candidate is immutable, dispatch trusted current `main` with `release_candidate_branch=extended-stable/YYYY.M.33`; it still publishes the tag checkout and accepts canonical-branch, current-main, or trusted-pinned validation evidence; the prepared tarball and every evidence identity must still match the candidate SHA. 8. From a clean current-`main` checkout, run `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P`. Verify signatures, provenance, inventories, exact versions, and selectors. Use the generated repair only for the root selector; repair other selectors with approved credential-isolated tooling. Never republish a version. 9. Require `Docker Release` to verify default, slim, browser, and architecture images in GHCR and Docker Hub, including attestations and platform versions. It must advance only `extended-stable`, `extended-stable-slim`, and `extended-stable-browser` by digest and refuse automatic rollback. For alias repair, dispatch the approval-gated `docker-channel-promote.yml` from current `main` with the exact tag; never rebuild or move the release tag. 10. Do not create a GitHub Release or publish macOS, Windows, mobile, website, ClawHub, or private dist-tag artifacts from this path. ## Keep release channel naming aligned - `stable`: user updates resolve npm `latest`; tagged regular releases publish to npm `beta` by default, then operators may target or promote to `latest` explicitly - `extended-stable`: user updates resolve npm `extended-stable`; operators publish the trailing completed month's `.33+` line from `extended-stable/YYYY.M.33` - `beta`: prerelease tags like `vYYYY.M.PATCH-beta.N`, with npm dist-tag `beta` - Prefer `-beta.N`; do not mint new `-1` or `-2` beta suffixes - `dev`: moving head on `main` - When using a beta Git tag, publish npm with the matching beta version suffix so the plain version is not consumed or blocked ## Close stable releases on main This gate starts only after stable publication. It is a narrow shipped-state closeout, not permission to heal broader `main`. Stable publication is not complete until `main` carries the actual shipped release state. 1. Start from fresh latest `main`. Audit `release/YYYY.M.PATCH` against it and forward-port real fixes that are absent from `main`. Do not blindly merge release-only compatibility, test, or validation adapters into newer `main`. 2. Set `main` to the shipped stable version, not a speculative next train. Run `pnpm release:prep` after the root version change, then `pnpm deps:npm-lock:check`. 3. Make `CHANGELOG.md`'s `## YYYY.M.PATCH` section on `main` exactly match the tagged release branch. Include the stable `appcast.xml` update when the mac release published one. 4. Do not add `YYYY.M.PATCH+1`, a beta version, or an empty future changelog section to `main` until the operator explicitly starts that release train. 5. Run `pnpm release:generated:check`, `pnpm deps:npm-lock:check`, and `OPENCLAW_TESTBOX=1 pnpm check:changed`. Push, then verify `origin/main` contains the shipped version and changelog before calling the stable release done. 6. Keep repository variables `RELEASE_ROLLBACK_DRILL_ID` and `RELEASE_ROLLBACK_DRILL_DATE` current after each private rollback drill. `openclaw-stable-main-closeout.yml` starts from the `main` push carrying the shipped version, changelog, and appcast after stable publication, then binds immutable evidence to the published tag. Do not declare stable complete until it writes the immutable closeout manifest to the GitHub release. The drill must be within 90 days; manual dispatch is only for repair/replay, and private rollback commands remain in the maintainer-only runbook. ## Handle versions and release files consistently Use the release preparation controller before manual version edits: ```bash pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --shadow pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --write pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --check ``` Shadow mode is the default and never runs mutating commands. Write mode aligns the root and macOS versions, optionally Android with `--android`, then runs only the version-owned generated metadata DAG. Every mode writes an exact HEAD/worktree-bound manifest under git metadata for cutover review. - Version locations include: - `package.json` - `apps/android/app/build.gradle.kts` - `apps/ios/Sources/Info.plist` - `apps/ios/Tests/Info.plist` - `apps/macos/Sources/OpenClaw/Resources/Info.plist` - `docs/install/updating.md` - Peekaboo Xcode project and plist version fields - Before creating a release tag, make every version location above match the version encoded by that tag. - For fallback correction tags like `vYYYY.M.PATCH-N`, the repo version locations still stay at `YYYY.M.PATCH`. - “Bump version everywhere” means all version locations above except `appcast.xml`. - Release signing and notary credentials live outside the repo in the private maintainer docs. - Every stable OpenClaw release ships the npm package, macOS app, and signed Windows Hub installers together. Beta releases normally ship npm/package artifacts first and skip native app build/sign/notarize/promote unless the operator requests native beta validation. - Do not let the slower macOS signing/notary path block npm publication once the npm preflight has passed. Keep mac validation/publish running in parallel, publish npm from the successful npm preflight, then start published npm install/update, Docker, and Parallels verification while mac artifacts continue. - After a beta is published, overlap remote/manual release rosters where useful, but avoid piling local Docker, Parallels, and QA-Lab work onto the same host when it would create system-load noise. Use selective reruns after failures or fixes, but keep proof that Docker, Parallels, and QA-Lab each passed at least once before stable/latest promotion. - Mac packaging may be built from a slight release-branch variation of the tagged commit when the delta is mac packaging, signing, workflow, or validation-only release machinery. If mac packaging needs release-branch-only fixes after the stable npm package or GitHub tag is already published, do not create a `vYYYY.M.PATCH-N` correction tag just to change the workflow source. Dispatch the release-ops mac workflows for the original `tag=vYYYY.M.PATCH` with `source_ref=release/YYYY.M.PATCH` and `public_release_branch=release/YYYY.M.PATCH`; provenance checks must prove the source SHA descends from the tag and validation/preflight use the same source. Reserve `vYYYY.M.PATCH-N` correction tags for emergency hotfixes that must publish a new npm package/release identity, not for ordinary mac-only packaging recovery. - The production Sparkle feed lives at `https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`, and the canonical published file is `appcast.xml` on `main` in the `openclaw` repo. - That shared production Sparkle feed is stable-only. Beta mac releases may upload assets to the GitHub prerelease, but they must not replace the shared `appcast.xml` unless a separate beta feed exists. - For fallback correction tags like `vYYYY.M.PATCH-N`, the repo version still stays at `YYYY.M.PATCH`, but the mac release must use a strictly higher numeric `APP_BUILD` / Sparkle build than the original release so existing installs see it as newer. - Stable Windows Hub release closeout requires the signed `OpenClawCompanion-Setup-x64.exe`, `OpenClawCompanion-Setup-arm64.exe`, and `OpenClawCompanion-SHA256SUMS.txt` assets on the canonical `openclaw/openclaw` GitHub Release. Pass the exact signed `openclaw/openclaw-windows-node` release tag as `windows_node_tag` to `OpenClaw Release Publish`, together with the candidate-approved `windows_node_installer_digests` map; it prevalidates the published source release and required installers against that map before any publish child, dispatches the public `Windows Node Release` workflow while the OpenClaw release is still a draft, carries those pinned source asset digests unchanged, verifies the expected OpenClaw Foundation Authenticode signer on