release-lanes

# 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`