docs(release): preserve handoff and recovery guidance (#153322)

Co-authored-by: steipete <58493+steipete@users.noreply.github.com>

.agents/skills/release-openclaw-maintainer/references/publication-recovery.md

@@ -71,6 +71,13 @@ Prefer repairing that workflow's token path. Point `latest` or `beta` only at
 the operator-approved already-published version, then verify cache-bypassed
 registry readback.
 
+Immediately after publishing or promoting to `latest`, dispatch that same
+release-ledger workflow to repair the beta floor: raise missing or older beta
+selectors to each package's own latest, preserve newer betas, and verify the
+selected core/plugin roster. The scheduled repair is only a backstop. Use the
+documented owner recovery for packages the ledger does not cover; do not lower
+a newer beta merely to make the selectors equal.
+
 If the workflow is unavailable, use the approved `$one-password` / `$npm`
 workflow in its persistent tmux session and private credential locators.
 Authenticate as the intended npm owner and keep secrets/OTPs out of output.

.agents/skills/release-openclaw-maintainer/references/regular-release.md

@@ -72,14 +72,24 @@ against the untagged Release SHA:
 pnpm release:candidate -- \
   --tag <tag> \
   --target-sha <release-sha> \
+  --npm-dist-tag <beta-or-latest> \
+  --publication-route <normal-or-prepared> \
   --full-release-run <release-sha-validation-run-id> \
   --publish-workflow-ref release-publish/<tooling-sha12>-<epoch> \
   --plugin-sdk-api-acknowledgement <reviewed-8-character-digest> \
   --skip-dispatch
 ```
 
+Match `--npm-dist-tag` and `--publication-route` to the frozen validation
+selection; the helper defaults to `beta` and `normal`.
+`--publish-workflow-ref` selects the publication tag, not the helper checkout.
+The same-checkout bootstrap fetches the workflow branch tip. Verify that the
+executing helper's Tooling SHA matches the recorded tag; if it differs, use
+only an owner-supported exact-tooling entry path, without moving the protected
+tag or silently changing qualification identity.
+
 Omit `--plugin-sdk-api-acknowledgement` when no API change exists. The helper
-completes package/install proof and prints the publish command; do not dispatch
+completes package/install proof and prints the selected route's next command; do not dispatch
 another equivalent validation. Its `npm-beta-v1` Telegram package result is
 `deferred-postpublish`, never passed. Other policies retain their check. Beta
 and alpha defer Parallels to `pnpm release:beta-smoke`; stable/full run it before
@@ -99,8 +109,15 @@ Keep their exact run/attempt identities in the handoff's publication rows.
 
 ## Publish and verify
 
-Read [publication authentication and recovery](publication-recovery.md).
-Dispatch `.github/workflows/openclaw-release-publish.yml` using the candidate
+Read [publication authentication and recovery](publication-recovery.md) and
+keep the admitted publication route. For `prepared`, run the candidate's
+printed `openclaw-release-prepare.yml` command after the frozen release tag
+exists. Once preparation succeeds, pass its summary's `prepared_artifact` JSON
+to `openclaw-release-button.yml` at the same protected Tooling tag. Follow
+[the release-button procedure](../../../../docs/reference/RELEASING.md#prepare-once-then-use-the-release-button)
+and its readiness receipt; do not also dispatch the normal publisher.
+
+For `normal`, dispatch `.github/workflows/openclaw-release-publish.yml` using the candidate
 helper's protected `release-publish/<tooling-sha12>-<epoch>` ref. Pass matching
 `npm_dist_tag`, `preflight_run_id`, `full_release_validation_run_id` and its
 exact successful `full_release_validation_run_attempt`. Include the reviewed
@@ -138,8 +155,9 @@ when still applicable. Run published npm verification, Docker install/update,
 macOS-only Parallels smoke and required QA signal; broaden only for stale
 proof, material stable/beta differences, or explicit retesting. Promote beta to
 latest through the restricted dist-tag workflow in
-[publication recovery](publication-recovery.md). For direct latest publication,
-point beta to that stable only if requested. Verify each selector readback.
+[publication recovery](publication-recovery.md#registry-selectors). After either
+publishing or promoting to latest, immediately repair the beta floor through
+that owner and verify each selector readback; preserve any newer beta.
 
 Complete [stable main closeout](stable-main-closeout.md) once version,
 changelog, npm and Docker evidence are ready. Record pending apps and monitor

.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md

@@ -17,9 +17,11 @@ operator steering. Do not preserve superseded scope.
 - cut SHA: `<full sha>`
 - Code SHA: `<regular release full sha | not applicable>`
 - Tooling SHA: `<trusted workflow full sha>`
-- Release SHA: `<regular release full sha | exact extended-stable branch tip>`
+- Release SHA: `<same as Code SHA | notes-only descendant | exact extended-stable branch tip>`
 - tag: `v<version>`
-- workflow ref: `<release-ci ref | canonical branch>`
+- validation workflow ref: `<release-ci ref | canonical branch>`
+- publication tooling ref: `<release-publish/tooling-sha12-epoch | track-specific ref>`
+- publication selection: `<normal/prepared route, npm dist-tag, package roster>`
 - publication inventory: `<exact surfaces>`
 - approved backports: `<none or exact PRs/commits>`
 - approved main changes: `<none or exact blocker>`
@@ -30,6 +32,8 @@ operator steering. Do not preserve superseded scope.
 
 - Full Release Validation parent: `<run id / attempt / URL or none>`
 - npm preflight: `<run id / URL or none>`
+- qualified npm/OCI descriptors: `<exact producer run/attempt and artifact identities>`
+- candidate acceptance: `<green untagged-SHA evidence | pending>`
 - Plugin NPM Release: `<run id / URL or none>`
 - publish parent: `<run id / URL or none>`
 - Docker release/repair: `<run ids / tag / aliases or none>`
@@ -76,9 +80,11 @@ reference for commands rather than redispatching the release parent.
 
 - confirmed product/code failure: fix the release branch, freeze a new Code
   SHA, and invalidate downstream product evidence
-- regular changelog-only failure: change the selected release entry and only
+- regular changelog-only failure before tagging: change the selected release entry and only
   its permitted record/index paths, freeze a new Release SHA, and reuse green
   Code SHA evidence after `split-changelog-release-v1` delta proof
+- source fix after a pushed beta tag: use the next beta number; never move the
+  old tag or rerun fresh candidate acceptance against it
 - extended-stable branch change: land the approved product/changelog change or
   smallest frozen-target repair by PR, record its source/invariant, and replace
   all exact-head evidence

.agents/skills/release-openclaw-maintainer/references/stable-main-closeout.md

@@ -11,8 +11,10 @@ complete until `main` carries the actual shipped release state.
    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
+2. Normally set `main` to the shipped stable version, not a speculative next
+   train. For late closeout, do not downgrade an already-started later stable
+   train; retain the validator's exact shipped-note and version checks. Run
+   `pnpm release:prep` after any root version change, then
    `pnpm deps:npm-lock:check`.
 3. Resolve the shipped section through `scripts/lib/release-changelog.mjs`
    so historical tags and current split artifacts use the same reader. Make
@@ -32,12 +34,12 @@ complete until `main` carries the actual shipped release state.
    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.
+   contains the exact shipped notes and the validator-accepted shipped-or-later
+   stable version 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 and changelog after stable publication, then binds immutable
+   accepted stable version and shipped changelog after stable publication, then binds immutable
    evidence to the published tag. App assets may still be pending; record
    `appPlatforms` states for macOS, Windows, and Android, with aggregate
    `apps: attached` only when every canonical platform asset contract is