ci: add beta release workflow tracks (udecode#5030)

Co-authored-by: zbeyens <zbeyens@udecode.dev>

Author: felixfeng33

.agents/AGENTS.md

@@ -52,6 +52,7 @@ Use those skills when relevant:
 - `editor-test-harvester` for mining external editor repositories for portable editor-behavior tests, Slate v2 coverage gaps, and copy/refactor/create decisions
 - `editor-harvest-plan` for turning an `editor-test-harvester` result into a lane-specific Slate v2 or Plate execution plan
 - `sync-plate-ui` for fork-aware Plate UI registry component syncs into downstream apps like Potion, including status, planning, review, dashboard, and accepted-row apply workflows
+- `release-lanes` for beta/latest release lane maintenance, promote, direct main-to-next sync, beta pre-mode, and npm/GitHub release verification
 - `tdd`
 - @.agents/rules/changeset.mdc when updating packages to write a changeset before completing
 - @.agents/rules/plate-plan.mdc when defining or updating editor-behavior law, authority maps, protocol rows, or parity coverage

.agents/rules/promote-beta.mdc

@@ -0,0 +1,44 @@
+---
+description: Compatibility entrypoint for beta promotion. Prefer release-lanes for end-to-end latest/beta lane maintenance.
+argument-hint: '[repo, dry-run, real promote, PR URL, or release version]'
+---
+
+# Promote Beta
+
+Compatibility shim. Use `release-lanes` for end-to-end beta/latest maintenance.
+This file exists so older prompts that say `promote-beta` still route correctly.
+
+## Route
+
+If the request is anything beyond read-only explanation, load
+`.agents/rules/release-lanes.mdc` and follow that skill instead.
+
+The old split was too manual: promote PR, generated sync PR, then beta re-entry.
+The current owner is `release-lanes`, which treats promotion, direct
+`main -> next` sync, beta re-entry, release watching, npm readback, and stale PR
+cleanup as one autogoal-backed lane.
+
+Do not run the old post-promotion checklist from this file.
+
+## Quick Commands
+
+Create the lane plan:
+
+```bash
+node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
+  --template release-lanes \
+  --title "release lane maintenance"
+```
+
+Run a promote dry run:
+
+```bash
+gh workflow run promote.yml --ref next -f dry_run=true
+```
+
+Run direct `main -> next` sync through the release-lanes script:
+
+```bash
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --dry-run
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --push
+```

.agents/rules/release-lanes.mdc

@@ -0,0 +1,227 @@
+---
+description: 'Maintain Plate''s latest and beta release lanes end-to-end with an autogoal plan: promote next to main, sync main directly back into next, repair release metadata conflicts, re-enter beta, and verify npm/GitHub release state.'
+argument-hint: '[status | sync | promote | verify | full]'
+---
+
+# Release Lanes
+
+Use this when the user asks to maintain Plate `latest` and `beta`, promote beta
+to stable, sync `main` into `next`, recover release lane drift, verify npm
+dist-tags, or run the release lane after a stable release.
+
+## Core Take
+
+CI owns publishing. This skill owns lane maintenance.
+
+Do not create a routine `main -> next` sync PR. That path creates review churn
+for deterministic release metadata conflicts. Sync directly with a merge commit,
+repair known release metadata automatically, push `next`, then let `release.yml`
+publish beta.
+
+One invocation is permission to run the lane until completion. Ask again only
+for hard stops.
+
+## Autogoal Contract
+
+This is a derived autogoal skill.
+
+Default flow mode: one-shot execution.
+
+Use:
+
+```bash
+node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
+  --template release-lanes \
+  --title "release lane maintenance"
+```
+
+Create or continue a goal before mutating remote release branches. The goal is
+complete only when the requested lane state is true and the template gates pass.
+
+## Lanes
+
+- `main` publishes stable packages with npm tag `latest`.
+- `next` publishes prerelease packages with npm tag `beta`.
+- `.changeset/pre.json` belongs on `next` only.
+- `main` must never publish while `.changeset/pre.json` exists.
+- Major changesets target `next` for beta before stable promotion.
+- Minor changesets target `main`, not `next`.
+- Patch changes may target `main`; use `next` patch changes only for active
+  beta-lane fixes or direct-sync beta metadata.
+
+## Modes
+
+### Status
+
+Read state only:
+
+```bash
+git fetch origin main next
+gh pr list --base main --head next --state open --json number,title,url,state
+gh run list --workflow release.yml --branch main --limit 5 \
+  --json databaseId,status,conclusion,createdAt,url
+gh run list --workflow release.yml --branch next --limit 5 \
+  --json databaseId,status,conclusion,createdAt,url
+npm view platejs dist-tags --json
+```
+
+Record:
+
+- `origin/main` SHA
+- `origin/next` SHA
+- whether `origin/next:.changeset/pre.json` exists and has tag `beta`
+- latest GitHub release
+- npm `platejs` dist-tags for `latest` and `beta`
+- open promote PR, if any
+- stale `sync/main-to-next` PRs, if any
+
+### Sync Main To Next
+
+Run after a stable release, after merging a promote PR, or whenever `main` has
+commits missing from `next`.
+
+Dry run first:
+
+```bash
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --dry-run
+```
+
+Then run the direct sync:
+
+```bash
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --push
+```
+
+The script must:
+
+- fetch `main` and `next`
+- refuse real direct sync when the checkout has local tracked or untracked
+  changes
+- create a merge commit on `next`
+- keep `next` beta package versions over `main` stable versions
+- keep `.changeset/pre.json` from `next`, or create beta pre mode in the same
+  sync commit when `next` is out of pre mode after promotion
+- insert or refresh stable changelog sections from `main`
+- create patch changesets for public packages changed by the synced `main`
+  commits so the beta lane can publish those fixes
+- run `pnpm ci:version` before committing when beta changesets are generated,
+  so `next` receives versioned beta package metadata instead of a pending
+  Version Packages PR
+- use a `[skip release]` sync commit only when no beta changesets were generated
+- verify the merge commit with `verify-main-to-next-sync`
+- push directly to `origin/next`
+
+If the script stops on files outside known release metadata, do not guess.
+Resolve only when source ownership is obvious; otherwise stop with exact files.
+
+### Re-Enter Beta
+
+After a beta-to-stable promotion, `next` may be out of prerelease mode. The
+direct `main -> next` sync restores beta pre mode in the same unskipped merge
+commit, so the next release workflow can publish the generated beta changesets.
+
+Use a standalone beta re-entry commit only when no direct sync is needed and no
+beta changesets need publication:
+
+```bash
+git switch next
+git pull --ff-only origin next
+pnpm changeset pre enter beta
+git add .changeset/pre.json
+git commit -m "chore: enter beta pre-release mode [skip release]"
+git push origin next
+```
+
+If `.changeset/pre.json` already exists with `{ "mode": "pre", "tag": "beta" }`,
+record N/A and do not create a duplicate commit.
+
+### Promote Beta To Stable
+
+Run dry first unless the user explicitly asks for the real promotion:
+
+```bash
+gh workflow run promote.yml --ref next -f dry_run=true
+gh run watch <run-id> --exit-status
+```
+
+For a real promotion:
+
+```bash
+gh workflow run promote.yml --ref next -f dry_run=false
+gh run watch <run-id> --exit-status
+```
+
+Then review the generated `next -> main` PR:
+
+- base `main`
+- head `next`
+- no `.changeset/pre.json`
+- package versions are stable, not `-beta.*`
+- body tells maintainers to use **Create a merge commit**
+
+Merging the promote PR is allowed when the user asked for full automation or
+merge. Use a merge commit, not squash or rebase.
+
+### Verify Releases
+
+Watch release workflows:
+
+```bash
+gh run list --workflow release.yml --branch main --limit 5 \
+  --json databaseId,status,conclusion,createdAt,url
+gh run list --workflow release.yml --branch next --limit 5 \
+  --json databaseId,status,conclusion,createdAt,url
+```
+
+Verify npm:
+
+```bash
+npm view platejs dist-tags --json
+npm view platejs@latest version
+npm view platejs@beta version
+```
+
+Verify GitHub releases:
+
+```bash
+gh release list --limit 10
+```
+
+## Stale PR Cleanup
+
+Close stale `sync/main-to-next` PRs after direct sync succeeds:
+
+```bash
+gh pr list --base next --head sync/main-to-next --state open --json number,url
+gh pr close <number> --comment "Closing because release-lanes synced main directly into next."
+```
+
+Do this only after direct sync and verification pass.
+
+## Hard Stops
+
+Stop only for:
+
+- missing GitHub or npm auth needed for the requested live action
+- real source conflicts outside package manifests, changelogs, and
+  `.changeset/pre.json`
+- release workflow failure after one clear retry or repair attempt
+- npm `latest` or `beta` points at an unexpected version after publication
+- branch protection rejects the required merge or push
+- local tracked or untracked changes are present before a real direct sync
+
+Do not stop to ask whether to run the next obvious lane step. The goal plan is
+the authorization boundary.
+
+## Handoff
+
+Report:
+
+- `main` SHA and `next` SHA
+- promote PR URL or N/A
+- direct sync result and pushed commit
+- beta pre mode state
+- release run URLs
+- npm `latest` and `beta` versions
+- stale PR cleanup
+- residual risk or `none`

.agents/skills/promote-beta/SKILL.md

@@ -0,0 +1,48 @@
+---
+description: Compatibility entrypoint for beta promotion. Prefer release-lanes for end-to-end latest/beta lane maintenance.
+argument-hint: '[repo, dry-run, real promote, PR URL, or release version]'
+name: promote-beta
+metadata:
+  skiller:
+    source: .agents/rules/promote-beta.mdc
+---
+
+# Promote Beta
+
+Compatibility shim. Use `release-lanes` for end-to-end beta/latest maintenance.
+This file exists so older prompts that say `promote-beta` still route correctly.
+
+## Route
+
+If the request is anything beyond read-only explanation, load
+`.agents/rules/release-lanes.mdc` and follow that skill instead.
+
+The old split was too manual: promote PR, generated sync PR, then beta re-entry.
+The current owner is `release-lanes`, which treats promotion, direct
+`main -> next` sync, beta re-entry, release watching, npm readback, and stale PR
+cleanup as one autogoal-backed lane.
+
+Do not run the old post-promotion checklist from this file.
+
+## Quick Commands
+
+Create the lane plan:
+
+```bash
+node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
+  --template release-lanes \
+  --title "release lane maintenance"
+```
+
+Run a promote dry run:
+
+```bash
+gh workflow run promote.yml --ref next -f dry_run=true
+```
+
+Run direct `main -> next` sync through the release-lanes script:
+
+```bash
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --dry-run
+node tooling/scripts/release-branch-prs.mjs sync-main-to-next --push
+```