docs(release): clarify unpublished beta tag reuse

steipete · steipete · commit 7969f1f07ccc · 2026-04-30T18:21:14.000+01:00
diff --git a/.agents/skills/openclaw-release-maintainer/SKILL.md b/.agents/skills/openclaw-release-maintainer/SKILL.md
@@ -41,9 +41,11 @@ Use this skill for release and publish-time workflow. Keep ordinary development
   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 they leave the machine. If a
-  published or pushed beta needs a fix, commit the fix on the release branch and
-  increment to the next `-beta.N`.
+- Do not delete or rewrite beta tags after their matching npm package has been
+  published. If a pushed beta tag fails preflight before npm publish, delete and
+  recreate the tag and prerelease at the fixed commit so npm prerelease versions
+  stay contiguous. 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, run the fast local preflight first, publish the
   beta to npm `beta`, then run the expensive published-package roster focused
   on install/update/Docker/Parallels/NPM Telegram. If anything fails, fix it on
@@ -367,8 +369,10 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
 - Any fix after preflight means a new commit. Delete and recreate the tag and
   matching GitHub release from the fixed commit, then rerun preflight from
   scratch before publishing.
-  Exception: never delete or recreate a beta tag that has already been pushed or
-  published; increment to the next beta number instead.
+  Exception: never delete or recreate a beta tag whose matching npm package has
+  already been published; increment to the next beta number instead. If only the
+  pushed tag/prerelease exists and npm publish has not happened, recreate that
+  same beta tag at the fixed commit.
 - For stable mac releases, generate the signed `appcast.xml` before uploading
   public release assets so the updater feed cannot lag the published binaries.
 - Serialize stable appcast-producing runs across tags so two releases do not
@@ -561,6 +565,9 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
     commit, and rerun all relevant preflights from scratch before continuing.
     Never reuse old preflight results after the commit changes. For pushed or
     published beta tags, do not delete/recreate; increment to the next beta tag.
+    For preflight-only failures where npm did not publish the beta version,
+    delete/recreate the same beta tag and prerelease at the fixed commit instead
+    of skipping a prerelease number.
 20. Start `.github/workflows/openclaw-npm-release.yml` from the same branch with
     the same tag for the real publish, choose `npm_dist_tag` (`beta` default,
     `latest` only when you intentionally want direct stable publish), keep it
@@ -573,9 +580,9 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
     for critical fixes that landed after the release branch cut; backport only
     important low-risk fixes before starting expensive lanes, or increment to
     the next beta if the fix must change the already-published package. If any
-    lane fails after the beta tag/package is pushed or published, fix,
-    commit/push/pull, increment to the next beta tag, and rerun the affected
-    beta evidence. Once the beta is live, start remote/manual rosters where they
+    lane fails after the beta package is published, fix, commit/push/pull,
+    increment to the next beta tag, and rerun the affected beta evidence. Once
+    the beta is live, start remote/manual rosters where they
     can overlap safely, but keep local Docker and Parallels load controlled.
     Ensure the full expensive roster has passed at least once before
     stable/latest promotion. The roster includes the manual Actions >
