release-openclaw-maintainer

name release-openclaw-maintainer description Prepare or verify OpenClaw stable, beta, and extended-stable releases, including backport discovery, changelogs, release notes, publish commands, and artifacts. 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. 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. Keep the frozen SHA and canonical branch as the validation target; Full Release Validation derives npm_dist_tag=extended-stable from the version. 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. 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. 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. 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. 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. 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. 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. 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. 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 . 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 . 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. 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. 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. 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: 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