diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4f74ef2db4..091be19ecd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ on: # lane or a bugfix-release/** carve-out get the CORE matrix directly; # backport.yml's token pushes compensate by dispatching this workflow # on the carry/lane ref. - branches: [master, "*_release-v*", "bugfix-release/**", "bugfix-v*"] + branches: [master, "*_release-v*", "bugfix-release/**", "bugfix-v*", bugfix] pull_request: # agent-relay: #3468 agent PRs target the relay branch. # bugfix-v*: carry PRs INTO the current patch lane (backport/carry-N) @@ -21,7 +21,10 @@ on: # release-bugfix.yml's dispatch, not this trigger. # bugfix-release/**: legacy one-off carve-out branches keep their old # behaviour. - branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**"] + # bugfix: THE GATE branch (v3 release model). Ship PRs (tag lane -> + # bugfix) must run the FULL matrix BEFORE the merge can happen — the + # scope step below forces full for base=bugfix regardless of labels. + branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**", bugfix] # three-layer CI (#3295): synchronize keeps the CORE matrix blocking on # every push; `labeled` lets the `ci:full` label widen a PR to the FULL # matrix without a re-push (other labels no-op in the plan job). @@ -119,6 +122,7 @@ jobs: # pull_request case below. PR_AUTHOR: ${{ github.event.pull_request.user.login }} PR_HEAD_REF: ${{ github.event.pull_request.head.ref }} + PR_BASE_REF: ${{ github.event.pull_request.base.ref }} PR_TITLE: ${{ github.event.pull_request.title }} HEAD_SHA: ${{ github.sha }} FULL_INPUT: ${{ inputs.full }} @@ -192,8 +196,14 @@ jobs: # lane ship PRs are deliberately NOT glob-matched: their own # workflow gates the full suite at the PR head tree already # (lane ship PRs ride the bot-author rule above). + # v3 gate-branch model: a ship PR INTO `bugfix` is born + # full-scope — that merge IS the publish decision, so the FULL + # matrix must exist at the PR head before the human merges + # (same label/merge race lesson as #3688); no ci:full label + # needed on the ship PR itself. [ "${PR_AUTHOR:-}" = "github-actions" ] \ || [ "${PR_AUTHOR:-}" = "app/github-actions" ] \ + || [ "${PR_BASE_REF:-}" = "bugfix" ] \ || case "${PR_HEAD_REF:-}" in *_release-v*) true ;; *) false ;; esac \ || case "${PR_TITLE:-}" in "[PR] release"*|"release v"[0-9]*) true ;; *) false ;; esac then @@ -385,7 +395,11 @@ jobs: set -euo pipefail BRANCH="${GITHUB_HEAD_REF}" # Release + bugfix carve-out branches (#2851/#2853) may bump version — one isolated 'release v{VERSION}' commit each. - if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* ]]; then + # v3 gate-branch model (#4660): tag lanes keep their ONE legal pre-bump commit (made at cut time); the + # auto-opened alignment PR (head=bugfix) carries that bump into master, and backport carry branches + # (backport/carry-N) inherit it from their lane base — all three head shapes must pass this guard or the + # cycle deadlocks at P3 (alignment never merges → next lane never auto-cuts). + if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* || "$BRANCH" == bugfix || "$BRANCH" == backport/carry-* ]]; then echo "✓ release branch ($BRANCH) — version changes allowed" exit 0 fi diff --git a/.github/workflows/lane-leak-guard.yml b/.github/workflows/lane-leak-guard.yml index af42d28c70..0ad4b29fa5 100644 --- a/.github/workflows/lane-leak-guard.yml +++ b/.github/workflows/lane-leak-guard.yml @@ -32,6 +32,18 @@ jobs: git fetch -q origin master --tags BASE_TAG="$(git describe --match 'v[0-9]*' --tags --abbrev=0 HEAD || true)" [ -n "$BASE_TAG" ] || { echo "::error::cannot find the lane's base tag — refusing to skip the scan"; exit 1; } + # A lane deliberately cut from aligned MASTER (v3 epoch-1 transition, #4660) + # carries master's post-tag merges BY DESIGN — scanning from the base tag + # would flag them as leaks (and its "rebuild from the tag" advice would + # re-inherit the stale pre-v3 workflow file). When the lane forked from + # master strictly AFTER its base tag, rescan from the fork point: the + # window then covers exactly the commits the lane adds over master. + FORK="$(git merge-base HEAD origin/master 2>/dev/null || true)" + BASE_SHA="$(git rev-parse "${BASE_TAG}^{commit}")" + if [ -n "$FORK" ] && [ "$FORK" != "$BASE_SHA" ] && git merge-base --is-ancestor "$BASE_SHA" "$FORK"; then + echo "::notice::$BRANCH forked from master at ${FORK:0:12} (strictly past base tag $BASE_TAG) — scanning ${FORK:0:12}..HEAD instead" + BASE_TAG="$FORK" + fi LEAKS="$(git log --format=%H --merges "${BASE_TAG}..HEAD" \ | while read -r M; do P2="$(git rev-parse "${M}^2" 2>/dev/null || echo "")" diff --git a/.github/workflows/release-bugfix.yml b/.github/workflows/release-bugfix.yml index 54054302ed..7dd4f4499e 100644 --- a/.github/workflows/release-bugfix.yml +++ b/.github/workflows/release-bugfix.yml @@ -1,72 +1,86 @@ -name: Bugfix Release (carve-out) +name: Bugfix Release (gate-branch model) -# Dedicated emergency / hotfix publish channel (#2011), PR-gated since #2851. +# Patch-lane release channel, v3 model (2026-10-25, owner decision; supersedes +# the v2 "any merge INTO a lane publishes" trigger and the backport-ship label +# path from #4596 — both decommissioned). # -# Publishes a version cut from a NON-master ref -- e.g. a released tag plus -# fixes -- STRICTLY excluding the unreleased work that has since accumulated -# on master. First used for the v0.1.182 emergency: ship ONLY the integer -# max_tokens fix without dragging in the ~70 commits already merged to -# master after v0.1.181. +# THREE BRANCHES, ONE ROLE EACH: +# bugfix THE GATE. A standalone PROTECTED branch with the same +# status as master (PR-only, required checks, no +# force/delete). It never accumulates development; it only +# RECEIVES a finished tag lane. +# bugfix-vX.Y.Z THE TAG LANES. Each cycle's lane is cut from the released +# vX.Y.Z tag (first lane manually; every later lane +# AUTO-CUT by this workflow, stage P4 below) and carries +# package.json pre-bumped to the next version. All fixes +# enter a lane through reviewed carry PRs (backport.yml +# auto-opens them from the `backport` label); those +# merges NEVER publish. +# master MAINLINE. Re-aligned after every publish via the +# auto-opened alignment PR (stage P3). # -# MERGE-GATED LANE PUBLISH (v2 model, 2026-10-25; SUPERSEDES the backport-ship -# label path from #4596 -- a label publishes without a human merge decision -# and is deliberately gone now): -# - A patch lane (bugfix-v*) is cut from the latest released TAG and is a -# PROTECTED branch with the same status as master (PR-only, required -# checks, no force/delete). Every piece of content enters the lane -# through a reviewed PR -- there is no other way. -# - When such a PR MERGES into the lane, THIS workflow fires (the -# `pull_request_target` closed trigger below; GitHub runs the lane-side -# copy of this file against the base ref) and publishes the POST-MERGE -# LANE HEAD (= the merge sha) -- exactly the reviewed state of the lane, -# nothing else. The human MERGE BUTTON IS THE RELEASE TRIGGER: no label, -# no direct push, no silent auto-publish. -# - Right after a successful publish the workflow AUTO-OPENS an alignment -# PR (lane -> master) so master picks up the shipped content. It -# structurally conflicts (master evolved past the older tag); resolve -# master-first, keeping only lane-unique content. Merging it closes the -# release cycle. -# - The target version lives in the LANE's package.json (bumped when the -# lane was cut), so the guards below enforce monotonicity without any -# further input. -# - Emergency escape hatch: manual workflow_dispatch with the `fast` input -# (owner-owned risk; skips the full-CI lanes + the full npm test, keeps -# every version guard + npm ci + typecheck + build). +# THE FIRE IS ONE EXACT PR SHAPE AND NOTHING ELSE: +# a SAME-REPO PR, MERGED, base = `bugfix`, head = `bugfix-vX.Y.Z`. +# That merge publishes the POST-MERGE lane head (= the merge sha) through +# the full guard chain. Every other close — any PR into a lane, any +# non-tag-branch into `bugfix`, a non-merged close, a fork — is a +# millisecond no-op. Merging carries into a lane therefore NEVER ships a +# version; only the explicit lane -> bugfix ship PR does. # -# LEGACY path (kept dormant): the original `pull_request` closed trigger for -# bugfix-release/* one-off carve-outs PR'd AGAINST MASTER predates the lane -# model. It still works so an old in-flight carve-out can finish safely; new -# work must go through a protected lane. +# CYCLE (v3): +# P1 carry PRs (reviewed, full checks) land in bugfix-vX.Y.Z [silent] +# P2 ship PR bugfix-vX.Y.Z -> bugfix is MERGED [PUBLISH: +# post-merge lane head -> version guards -> full CI dispatch+wait +# at the publish sha -> npm/typecheck/test/build -> tag -> npm +# publish -> GH Release; audit comment left on the ship PR] +# P3 right after a successful publish this workflow AUTO-OPENS the +# alignment PR (head=`bugfix` -> master; title contract below). The owner +# merges it (structural conflicts expected; master-first resolution). +# P4 the merge of THAT alignment PR fires this workflow again (second path +# below): it AUTO-CUTS the next lane bugfix-vX.Y.Z from tag vX.Y.Z +# (pre-bumped +1 patch) so the following cycle starts with zero manual +# steps. Only the very first lane (bugfix-v0.1.206) was cut manually. # -# Unlike release.yml (which builds the POST-MERGE MASTER tree on -# push-to-master, so it can never exclude master's existing commits), this -# checks out and publishes the LANE HEAD tree itself -- the artifact is -# exactly that tree, nothing else. +# ALIGNMENT PR TITLE CONTRACT (load-bearing for P4): +# "align master with vX.Y.Z (shipped from )" +# Renaming this format silently breaks the auto-cut; documented in +# reference/release.md. +# +# Emergency escape hatch: workflow_dispatch with `fast=true` (owner picks the +# ref in the UI): skips the full-CI dispatch/gate and the full npm test, keeps +# every version guard + npm ci + typecheck + build. Owner-owned risk. +# +# LEGACY path (kept dormant, unchanged): the original `pull_request` closed +# trigger for bugfix-release/* one-off carve-outs PR'd AGAINST MASTER predates +# the lane model. It still works so an old in-flight carve-out can finish +# safely; new work must go through the gate-branch flow. # # Guarded so it can never: -# - move `latest` backwards (target must be strictly newer than npm latest); +# - move `latest` backwards (target strictly newer than npm latest); # - re-publish an already-live version; # - ship a sub-0.1.0 line (#1385); -# - act on fork PRs (secrets unavailable) or on non-merged closes; -# - publish anything but the reviewed post-merge lane head. +# - act on fork PRs (secrets unavailable) or non-merged closes; +# - publish anything but the reviewed post-merge lane head; +# - fire on ANY other merge shape (see THE FIRE above). # -# Master interaction: the post-publish alignment PR brings the lane content -# (and the version bump) INTO master. Master's next normal release MUST be -# higher than the carved-out version -- the one-click bump derives from npm -# latest, so this holds automatically. +# Master interaction: the post-publish alignment PR brings the shipped lane +# content (and the version bump) INTO master. Master's next normal release +# MUST be higher than the shipped version -- the one-click bump derives from +# npm latest, so this holds automatically. on: pull_request: types: [closed] branches: [master] pull_request_target: - # v2 merge-gated lane publish: fires when a PR is CLOSED against a patch - # lane; the resolve step no-ops within milliseconds on every close that - # is not a MERGE into a bugfix-v* / bugfix-release/** lane. Runs the - # BASE (lane-side) copy of this workflow with secrets; the resolve step - # rejects fork PRs before any head content is touched. + # v3 dual path (resolve step sorts it out): + # A) base=`bugfix`, head=`bugfix-vX.Y.Z`, merged => PUBLISH + # B) base=`master`, head=`bugfix`, merged, alignment title => AUTO-CUT + # Runs the BASE-side copy of this workflow with secrets; the resolve step + # rejects fork PRs before any head content is touched and no-ops within + # milliseconds on every close that is not one of the two shapes. types: [closed] - branches: ["bugfix-v*", "bugfix-release/**"] + branches: [bugfix, master] workflow_dispatch: inputs: fast: @@ -85,26 +99,31 @@ jobs: contents: write id-token: write actions: write - pull-requests: write # annotate the merged lane PR + auto-open the alignment PR + pull-requests: write # annotate the ship PR + auto-open the alignment PR + announce auto-cuts steps: - - name: Validate trigger + resolve the publish ref + - name: Validate trigger + resolve the path (publish | cut | noop) id: resolve run: | + PATH=noop + BRANCH="" + SHA="" + VER="" + HEADSHA="" + TITLE="$(jq -r '.pull_request.title // ""' "$GITHUB_EVENT_PATH")" if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then # LEGACY one-off carve-out: PR against master whose head is the # carve-out branch. Publishes the PRE-MERGE head on merge. MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" - BRANCH="$(jq -r '.pull_request.head.ref' "$GITHUB_EVENT_PATH")" + HEADREF="$(jq -r '.pull_request.head.ref' "$GITHUB_EVENT_PATH")" SAME_REPO="$(jq -r '(.pull_request.base.repo.full_name == .pull_request.head.repo.full_name)' "$GITHUB_EVENT_PATH")" - SHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" if [ "$MERGED" != "true" ]; then echo "::notice::PR $GITHUB_EVENT_NUMBER closed without merging — nothing to publish" exit 0 fi - case "$BRANCH" in + case "$HEADREF" in bugfix-release/*) ;; # legacy one-off carve-out *) - echo "::notice::head branch '$BRANCH' is not a legacy bugfix-release/* carve-out — nothing to publish" + echo "::notice::head branch '$HEADREF' is not a legacy bugfix-release/* carve-out — nothing to publish" exit 0 ;; esac @@ -112,71 +131,159 @@ jobs: echo "::error::fork PRs cannot use the carve-out channel (repo secrets are unavailable for them)" exit 1 fi + PATH=publish + BRANCH="$HEADREF" + SHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" + HEADSHA="$SHA" elif [ "$GITHUB_EVENT_NAME" = "pull_request_target" ]; then - # v2 merge-gated lane publish: a REVIEWED PR was merged into a - # patch lane. Publish the POST-MERGE lane head (== merge sha). MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" STATE="$(jq -r '.pull_request.state' "$GITHUB_EVENT_PATH")" - BRANCH="$(jq -r '.pull_request.base.ref' "$GITHUB_EVENT_PATH")" - SHA="$(jq -r '.pull_request.merge_commit_sha' "$GITHUB_EVENT_PATH")" + BASE="$(jq -r '.pull_request.base.ref' "$GITHUB_EVENT_PATH")" + HEADREF="$(jq -r '.pull_request.head.ref' "$GITHUB_EVENT_PATH")" SAME_REPO="$(jq -r '(.pull_request.base.repo.full_name == .pull_request.head.repo.full_name)' "$GITHUB_EVENT_PATH")" if [ "$STATE" != "closed" ] || [ "$MERGED" != "true" ]; then - echo "::notice::PR $GITHUB_EVENT_NUMBER is '$STATE' (merged=$MERGED) — only MERGES into a lane publish" + echo "::notice::PR $GITHUB_EVENT_NUMBER is '$STATE' (merged=$MERGED) — only MERGED same-repo PRs act" exit 0 fi - case "$BRANCH" in - bugfix-v*) ;; # protected patch lane (v2 model) - bugfix-release/*) ;; # same treatment for lane-shaped targets - *) - echo "::notice::base branch '$BRANCH' is not a patch lane — nothing to publish" - exit 0 - ;; - esac - if [ "$SAME_REPO" != "true" ]; then - echo "::error::fork PRs cannot use the lane publish channel (repo secrets are unavailable for them)" - exit 1 + # ---- path A: the ship shape — a TAG LANE merged into `bugfix` ---- + if [ "$BASE" = "bugfix" ]; then + case "$HEADREF" in + bugfix-v[0-9]*.[0-9]*.[0-9]*) ;; + *) + echo "::notice::'$HEADREF' -> bugfix is not a tag lane (bugfix-vX.Y.Z) — NOT a ship PR; nothing to publish" + exit 0 + ;; + esac + if [ "$SAME_REPO" != "true" ]; then + echo "::error::fork PRs cannot use the gate-branch publish channel (repo secrets are unavailable for them)" + exit 1 + fi + PATH=publish + BRANCH="$HEADREF" + SHA="$(jq -r '.pull_request.merge_commit_sha' "$GITHUB_EVENT_PATH")" + HEADSHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" + echo "::notice::SHIP PR detected: $HEADREF -> bugfix @ ${SHA:0:12} — publishing the post-merge lane head" + # ---- path B: the alignment landed — auto-cut the next lane ---- + elif [ "$BASE" = "master" ] && [ "$HEADREF" = "bugfix" ]; then + if [ "$SAME_REPO" != "true" ]; then + echo "::error::fork PRs cannot drive the auto-cut (repo secrets are unavailable for them)" + exit 1 + fi + case "$TITLE" in + "align master with v"*) + REST="${TITLE#align master with v}" + VER="${REST%% *}" + if ! printf '%s' "$VER" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then + echo "::error::alignment title does not follow the contract 'align master with vX.Y.Z (...)' (parsed version '$VER') — auto-cut refused" + exit 1 + fi + PATH=cut + echo "::notice::alignment PR '$TITLE' merged — auto-cutting lane bugfix-v$VER from tag v$VER" + ;; + *) + echo "::notice::bugfix -> master merge without the alignment title contract ('$TITLE') — nothing to cut" + exit 0 + ;; + esac + else + echo "::notice::base '$BASE' / head '$HEADREF' matches neither ship nor alignment shape — nothing to do" + exit 0 fi else + # workflow_dispatch: EMERGENCY fast publish of the selected ref + PATH=publish BRANCH="$GITHUB_REF_NAME" SHA="" fi + [ "$PATH" = "noop" ] && { echo "proceed=false" >> "$GITHUB_OUTPUT"; exit 0; } + echo "proceed=true" >> "$GITHUB_OUTPUT" + echo "path=$PATH" >> "$GITHUB_OUTPUT" echo "branch=$BRANCH" >> "$GITHUB_OUTPUT" echo "sha=$SHA" >> "$GITHUB_OUTPUT" - echo "proceed=true" >> "$GITHUB_OUTPUT" + echo "headsha=$HEADSHA" >> "$GITHUB_OUTPUT" + echo "ver=$VER" >> "$GITHUB_OUTPUT" - - name: Checkout + - uses: actions/checkout@v4 if: steps.resolve.outputs.proceed == 'true' - uses: actions/checkout@v4 with: fetch-depth: 0 + - name: Auto-cut the next tag lane (path B — after the alignment merge) + # v3 stage P4: the alignment PR (bugfix -> master) just merged. Cut + # bugfix-vX.Y.Z from tag vX.Y.Z, pre-bump package.json to the next + # patch version, push. Idempotent: an existing branch is a no-op. + # NOTE: GITHUB_TOKEN cannot apply branch protection — the announcement + # comment tells the owner the one remaining manual click (Settings -> + # Branches, or the PUT JSON in reference/release.md). + if: steps.resolve.outputs.path == 'cut' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -uo pipefail + VER="${{ steps.resolve.outputs.ver }}" + NEW_LANE="bugfix-v$VER" + MANUAL_CMDS='git fetch origin tag v'"$VER"' --no-tags && git checkout -b '"$NEW_LANE"' v'"$VER" && (edit package.json version to the next patch) && git commit -am "release: cut $NEW_LANE from v$VER" && git push origin "$NEW_LANE" + fail() { + echo "::error::$1" + gh pr comment "$GITHUB_EVENT_NUMBER" --body "❌ **Auto-cut failed**: $1\n\nManual recovery:\n\`\`\`bash\n$MANUAL_CMDS\n\`\`\`\nThen protect \`$NEW_LANE\` exactly like master (reference/release.md § Lane protection)." \ + || echo "::warning::could not annotate PR $GITHUB_EVENT_NUMBER" + exit 1 + } + git fetch origin "refs/tags/v$VER" --no-tags || fail "tag v$VER not found on origin — the alignment was merged before the publish tag existed?" + git rev-parse --verify --quiet "v$VER^{commit}" >/dev/null || fail "tag v$VER present but unresolvable" + LIVE="$(git ls-remote origin "refs/heads/$NEW_LANE" | awk '{print $1}')" + if [ -n "$LIVE" ]; then + echo "::notice::$NEW_LANE already exists on origin ($LIVE) — idempotent no-op" + exit 0 + fi + NEXT="$(node -p "(function(){const v=process.argv[1].split('.');return v[0]+'.'+v[1]+'.'+(Number(v[2])+1)})" "$VER")" + git checkout -b "$NEW_LANE" "v$VER" + sed -i "s/\"version\": \"$VER\"/\"version\": \"$NEXT\"/" package.json + node -e "if(require('./package.json').version!=='$NEXT'){console.error('::error::pre-bump failed');process.exit(1)}" + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git commit -q -m "release: auto-cut patch lane $NEW_LANE from v$VER; pre-bump package.json to $NEXT (v3 stage P4)" + git push -q origin "$NEW_LANE" || fail "push of $NEW_LANE rejected" + SHA="$(git rev-parse HEAD)" + gh pr comment "$GITHUB_EVENT_NUMBER" --body "✅ **Stage P4 complete** — lane \`$NEW_LANE\` auto-cut from tag \`v$VER\` (@ ${SHA:0:12}), package.json pre-bumped to \`$NEXT\`. One manual step remains before it takes on carries: apply the same protection as master (Settings → Branches → \`$NEW_LANE\`; payload: reference/release.md § Lane protection). Carry PRs (backport label) can start immediately." \ + || echo "::warning::could not annotate PR $GITHUB_EVENT_NUMBER (non-fatal)" + echo "::notice::lane cycle advanced: next lane $NEW_LANE ready (unprotected until the owner clicks)" + - name: Switch to the publish tree (post-merge lane head / legacy pre-merge head) - # v2: publish the EXACT reviewed state — the merge sha of the PR that - # just landed in the lane. Legacy: pre-merge head of a merged - # carve-out PR. If the lane head has already moved past the merge sha - # (another PR landed first while this run queued behind it under the - # concurrency group), warn loudly and still publish the reviewed sha; - # the newer content rides the next release. - if: steps.resolve.outputs.proceed == 'true' && (github.event_name == 'pull_request' || github.event_name == 'pull_request_target') + # v3 path A: publish the EXACT reviewed state — the merge sha of the + # ship PR that just landed in `bugfix`. Legacy: pre-merge head of a + # merged carve-out PR. If the LANE head has moved past the reviewed + # ship state (another carry landed while this run queued behind the + # ship PR under the concurrency group), warn loudly and still publish + # the reviewed sha; content past a SHIPPED lane never rides another + # release of that lane (the monotonic guard freezes it) — move it + # forward to master and carry it into the NEXT lane. + if: steps.resolve.outputs.path == 'publish' && steps.resolve.outputs.sha != '' run: | SHA="${{ steps.resolve.outputs.sha }}" BRANCH="${{ steps.resolve.outputs.branch }}" + HEADSHA="${{ steps.resolve.outputs.headsha }}" git rev-parse --verify --quiet "${SHA}^{commit}" >/dev/null || git fetch origin "$SHA" LIVE_HEAD="$(git ls-remote origin "refs/heads/$BRANCH" | awk '{print $1}')" - if [ -n "$LIVE_HEAD" ] && [ "$LIVE_HEAD" != "$(git rev-parse ${SHA}^{commit})" ]; then - echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) differs from the merge sha ($SHA) — publishing the reviewed merge sha anyway; newer lane content will ride the NEXT release" + # Drift reference = the lane tip reviewed at ship time (the ship PR's + # head sha). Comparing against the MERGE sha would warn on every ship: + # that commit lives on `bugfix`, never on the lane. + DRIFT_REF="$HEADSHA" + [ -z "$DRIFT_REF" ] && DRIFT_REF="$SHA" + if [ -n "$LIVE_HEAD" ] && [ "$LIVE_HEAD" != "$(git rev-parse ${DRIFT_REF}^{commit} 2>/dev/null)" ]; then + echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) is past the reviewed ship state ($DRIFT_REF) — publishing the reviewed merge sha ($SHA) only; anything newer on the lane is FROZEN out of this lane's releases (monotonic guard) and must ride master/the next lane" fi git checkout --detach "$SHA" - uses: actions/setup-node@v4 - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' with: node-version: 22 registry-url: https://registry.npmjs.org - name: Read version id: version - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | V="$(node -p "require('./package.json').version")" case "$V" in @@ -189,7 +296,7 @@ jobs: REF="${{ steps.resolve.outputs.branch }}" SHA="${{ steps.resolve.outputs.sha }}" [ -z "$SHA" ] && SHA="$(git rev-parse HEAD)" - echo "::notice::Publishing carve-out from '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)" + echo "::notice::Publishing from lane '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)" - name: Check plugin manifest versions (#4449) # Same gate as release.yml: the publish tree is a frozen lane state @@ -197,7 +304,7 @@ jobs: # synced plugin manifests — drift fails fast here instead of shipping # a release whose marketplace update detection never fires. See # reference/release.md. - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' # #4576 follow-up: lanes cut from a pre-#4449 tag do not carry the # manifest sync script at all -- fail-open with a notice there instead # of MODULE_NOT_FOUND (same existence-guard philosophy as release-manual's @@ -210,7 +317,7 @@ jobs: fi - name: Publish guard (monotonic + not-already-live) - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | VER="${{ steps.version.outputs.version }}" LATEST="$(npm view billion-context version)" @@ -235,7 +342,7 @@ jobs: # declarations — only severe releases need one; ordinary releases ship # silently with NO entry. Missing entry => notice + pass; present # entry => validated and logged. - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | VER="${{ steps.version.outputs.version }}" case "$VER" in @@ -254,14 +361,15 @@ jobs: - name: Full CI dispatch (all lanes, publish sha) # Policy (2026-10-10, after the v0.1.192 carve-out): every release # channel must run the COMPLETE CI set at the exact publish sha before - # npm publish. For a v2 lane publish the merge sha is brand-new (PR-era - # lane runs sit on earlier shas), so the gate dispatches the missing - # lanes here; idempotent where runs already exist. + # npm publish. The ship PR's own runs sit on the pre-merge head; the + # merge sha is brand-new, so the gate dispatches the missing lanes + # here; idempotent where runs already exist. Belt-and-braces on top of + # the gate branch's required checks. # EMERGENCY fast mode (owner 2026-10-17): dispatch is already a # human-picked ref; with fast=true the human explicitly owns skipping # this lane matrix — version guards and the build sanity below still # run. - if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true + if: steps.resolve.outputs.path == 'publish' && inputs.fast != true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -273,7 +381,7 @@ jobs: - name: Pre-flight gate (full suite) # keep the claude-native live e2e subtests in this pre-publish gate (#1248) - if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true + if: steps.resolve.outputs.path == 'publish' && inputs.fast != true env: ACP_TEST_CLAUDE_NATIVE: "1" run: | @@ -286,7 +394,7 @@ jobs: # EMERGENCY fast mode: keep the cheap sanity (install/typecheck/build) # so a broken tree still fails loudly, but skip the full npm test — # the lane matrix above was skipped by explicit human choice. - if: steps.resolve.outputs.proceed == 'true' && inputs.fast == true + if: steps.resolve.outputs.path == 'publish' && inputs.fast == true run: | echo "::warning::FAST MODE — full CI lanes and the full npm test were SKIPPED by an explicit human choice (workflow_dispatch fast=true). Publish sanity = version guards + npm ci + typecheck + build only." npm ci @@ -294,11 +402,11 @@ jobs: npm run build - name: Full CI gate (all lanes green at this sha) - # Hard precondition for publish: lanes dispatched above (plus any PR-era - # lane runs already at this sha) ran in parallel with the pre-flight; - # wait them out now. Any red lane or timeout ⇒ release fails, nothing - # is published. - if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true + # Hard precondition for publish: lanes dispatched above (plus any runs + # already at this sha) ran in parallel with the pre-flight; wait them + # out now. Any red lane or timeout ⇒ release fails, nothing is + # published. + if: steps.resolve.outputs.path == 'publish' && inputs.fast != true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CI_GATE_TIMEOUT_MIN: "60" @@ -311,7 +419,7 @@ jobs: - name: Check if prerelease id: pre - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | if echo "${{ steps.version.outputs.version }}" | grep -q '-'; then echo "tag=dev" >> $GITHUB_OUTPUT @@ -322,7 +430,7 @@ jobs: fi - name: Create tag - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" @@ -330,23 +438,23 @@ jobs: git push origin "v${{ steps.version.outputs.version }}" || true - name: Publish - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: npm publish --tag ${{ steps.pre.outputs.tag }} --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - name: Annotate the merged lane PR (audit trail) - # Merge-gated lane publish: the carrying PR is already merged; leave - # the audit trail on it so a later reader sees publish == that merge. - if: github.event_name == 'pull_request_target' && steps.resolve.outputs.proceed == 'true' + - name: Annotate the merged ship PR (audit trail) + # Merge-gated publish: the ship PR is already merged; leave the audit + # trail on it so a later reader sees publish == that merge. + if: steps.resolve.outputs.path == 'publish' && github.event_name == 'pull_request_target' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - gh pr comment "$GITHUB_EVENT_NUMBER" --body "Published v${{ steps.version.outputs.version }} from the POST-MERGE lane head \`${{ steps.resolve.outputs.sha }}\` (merge-gated lane publish, v2 flow). Master alignment follows via the auto-opened PR." \ + gh pr comment "$GITHUB_EVENT_NUMBER" --body "Published v${{ steps.version.outputs.version }} from the POST-MERGE lane head \`${{ steps.resolve.outputs.sha }}\` (gate-branch publish, v3 flow: ${{ steps.resolve.outputs.branch }} → bugfix). Master alignment follows via the auto-opened \`bugfix → master\` PR." \ || echo "::notice::could not annotate PR $GITHUB_EVENT_NUMBER (non-fatal)" - name: Create GitHub Release - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -377,41 +485,41 @@ jobs: curl -sS -f -X POST \ -H "Authorization: Bearer $GH_TOKEN" \ -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ + -H "X-GitHub-API-Version: 2022-11-28" \ -H "Content-Type: application/json" \ "https://api.github.com/repos/${{ github.repository }}/releases" \ -d @"$RUNNER_TEMP/release.json" - - name: Open the alignment PR into master (cycle stage 5) - # v2 flow: right after a successful lane publish, open a dedicated - # alignment PR (lane -> master) so master picks up the shipped content - # (incl. the version bump). Structural conflicts vs master are EXPECTED - # (the lane is based on an older tag while master moved on): resolve - # master-first, keeping only lane-unique content. Merging this PR - # completes the release cycle. Non-fatal: a failed open is flagged and - # the PR can be opened manually. - if: github.event_name == 'pull_request_target' && steps.resolve.outputs.proceed == 'true' + - name: Open the alignment PR (bugfix -> master, cycle stage P3) + # v3: right after a successful publish, open the dedicated alignment + # PR carrying the shipped lane content (incl. the version bump) into + # master. head=`bugfix` (which now contains exactly the merged lane), + # base=master. Title contract (DO NOT RENAME — stage P4 matches it): + # "align master with vX.Y.Z (shipped from )" + # Structural conflicts vs master are EXPECTED (the lane derives from an + # older tag while master moved on): resolve master-first, keeping only + # lane-unique content. Merging this PR fires stage P4 (auto-cut of the + # next lane). Non-fatal: a failed open is flagged and can be retried + # manually. + if: steps.resolve.outputs.path == 'publish' && github.event_name == 'pull_request_target' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | LANE="${{ steps.resolve.outputs.branch }}" VER="${{ steps.version.outputs.version }}" - OPEN_PRS="$(gh pr list --base master --head "$LANE" --state open --json number 2>/dev/null | jq 'length')" + OPEN_PRS="$(gh pr list --base master --head bugfix --state open --json number 2>/dev/null | jq 'length')" if [ "${OPEN_PRS:-0}" -gt 0 ]; then - echo "::notice::an alignment PR ($LANE -> master) is already open — leaving it as-is" + echo "::notice::an alignment PR (bugfix -> master) is already open — leaving it as-is" else - gh pr create --base master --head "$LANE" \ + gh pr create --base master --head bugfix \ --title "align master with v$VER (shipped from $LANE)" \ - --body "Auto-opened by Bugfix Release right after v$VER shipped from \`$LANE\` (post-merge sha \`${{ steps.resolve.outputs.sha }}\`). Structural conflicts vs master are EXPECTED — the lane is based on an older tag while master moved on; resolve master-first, keeping only lane-unique content (release notes, advisories, diagnostics). Merging this PR completes the release cycle." \ - || echo "::warning::could not open the alignment PR automatically — open it manually: base=master head=$LANE (non-fatal)" + --body "Auto-opened by Bugfix Release right after v$VER shipped (\`$LANE\` → bugfix, post-merge sha \`${{ steps.resolve.outputs.sha }}\`). Structural conflicts vs master are EXPECTED — the lane derives from an older tag while master moved on; resolve master-first, keeping only lane-unique content (advisories, diagnostics, fixes). Merging this PR completes the release cycle and AUTO-CUTS the next lane (bugfix-v$VER) from tag v$VER (stage P4)." \ + || echo "::warning::could not open the alignment PR automatically — open it manually: base=master head=bugfix, title MUST start with 'align master with v$VER (shipped from $LANE)' (non-fatal)" fi - - name: Close the patch-lane cycle (notice — the state is derived, nothing to clear) - # Lanes derive from the latest released tag: once this publish creates - # vNEXT, the NEXT lane is cut FRESH from vNEXT (one-click / manual - # cut). Nothing is stored, nothing to reset; the old lane stays frozen - # as the record of what shipped. - if: steps.resolve.outputs.proceed == 'true' + - name: Close the ship PR cycle (notice — the state is derived, nothing to clear) + if: steps.resolve.outputs.path == 'publish' run: | - BRANCH="${{ steps.resolve.outputs.branch }}" - echo "::notice::shipped '$BRANCH' — the fresh tag closes this lane cycle by derivation; the next lane is cut from it (aligned back to master via the auto-opened PR)" + LANE="${{ steps.resolve.outputs.branch }}" + VER="${{ steps.version.outputs.version }}" + echo "::notice::shipped '$LANE' — the fresh tag v$VER freezes this lane (the monotonic guard refuses to re-publish it); the next lane is auto-cut from the tag once master is aligned" diff --git a/reference/release.md b/reference/release.md index 5a417a4744..5dc097e3e4 100644 --- a/reference/release.md +++ b/reference/release.md @@ -205,34 +205,111 @@ commit. The standard branch/PR flow above remains the canonical path for anythin non-trivial (updater changes, cross-repo bumps, or whenever a human wants the review gate). -## Bugfix patch-lane channel (release-bugfix.yml) +## Bugfix patch-lane channel (release-bugfix.yml — gate-branch model) Emergency hotfix path (#2011, first used for v0.1.182), PR-gated since #2851, -and since 2026-10-25 hard-gated on human review as the **protected patch-lane -model**: publish a version cut from a **non-master ref** — a released tag plus -the fixes that landed on its lane — STRICTLY excluding the unreleased work that +and since 2026-10-25 hard-gated on human review as the **protected +gate-branch model (v3)**: publish a version cut from a **non-master ref** — a +released tag plus the fixes that landed on its lane — STRICTLY excluding the +unreleased work that has since accumulated on master. -**The governing rules (v2 — supersedes the `backport-ship` label path):** - -- A patch lane (`bugfix-v*`) is a **PROTECTED branch with the same status as - master**: pull-request-only, required checks green, force-push and delete - disabled, admins included. There is NO direct-push path into a lane. -- Every piece of content enters the lane through a **reviewed PR**. -- **Merging a PR INTO the lane IS the release.** On such a merge, the - `pull_request_target` closed trigger fires and CI publishes the POST-MERGE - lane head (= the PR's `merge_commit_sha`, cross-checked against the live lane - ref with a drift warning) with the full guard chain below — then AUTO-OPENS - an alignment PR (lane → master) so master picks up the shipped content. - Merging that alignment PR completes the cycle; the next lane is cut fresh - from the new tag. Non-merged closes no-op within milliseconds; fork PRs are - rejected before any head content is touched. - -GitHub executes the WORKFLOW FILE FROM THE BASE (LANE-SIDE) COPY for -`pull_request_target` events, so the updated `release-bugfix.yml` must sit ON -the lane before its first merge-trigger can fire — it rides in with an ordinary -carry PR ("armed, not fired": until it lands, earlier merges stay silent -because the older copy simply has no such trigger). +**The governing rules (v3, 2026-10-25 — supersedes the v2 "any merge into the +lane publishes" trigger AND the `backport-ship` label path):** + +Three branches, one role each: + +- **`bugfix` — THE GATE.** A standalone PROTECTED branch with the same status + as master (PR-only, required checks green, force-push/delete disabled, + admins included). It never accumulates development; it only receives a + finished tag lane. The v3 workflow file sits ON this branch from birth + (`pull_request_target` executes the base-side copy), so there is NO + "arming" window: the first ship PR works immediately. +- **`bugfix-vX.Y.Z` — the TAG LANES.** Each cycle's lane is cut from the + released `vX.Y.Z` tag with package.json pre-bumped to the next version, and + protected exactly like master. All fixes enter through reviewed carry PRs + (opened automatically from the `backport` label); **merging carries into a + lane NEVER publishes**. +- **master** — the mainline; re-aligned after every publish (below). + +**THE FIRE IS ONE EXACT PR SHAPE AND NOTHING ELSE:** a same-repo PR, MERGED, +base = `bugfix`, head = `bugfix-vX.Y.Z`. Only that merge publishes: +`release-bugfix.yml`'s `pull_request_target` closed trigger (executing the +`bugfix`-side copy) resolves the POST-MERGE lane head (= the ship PR's +`merge_commit_sha`, cross-checked against the live lane ref with a drift +warning), runs the full guard chain below, tags + publishes + creates the +GitHub Release, leaves an audit comment on the merged ship PR, then AUTO-OPENS +the alignment PR (**head = `bugfix`**, base = master). Every other close — any +PR into a lane, any non-tag-branch into `bugfix`, a non-merged close, a fork — +is a millisecond no-op. + +**Why v3 has no arming step (2026-10-25 incident — never re-arm lanes):** the +v2 design carried a separate "arming" commit to each new lane (the lane-side +copy of this workflow). The window proved fatal once: when arming PR #4654 +merged into `bugfix-v0.1.206`, GitHub resolved the `pull_request_target` event +against the base ref *after* the merge commit had landed — so the arm's own +trigger matched its own merge and immediately published v0.1.207 +(tag `7e69b49f`, GH Release 08:09:37Z) with none of the review the channel is +supposed to provide. No double-ship followed: every later close against that +frozen lane hits the monotonic npm guard (`0.1.207` already live) and dies red +without publishing. The lesson, codified in the model: **an arming commit +whose trigger matches its own target fires itself.** Hence the gate branch is +born carrying the workflow (no arming step exists in v3) and merges into tag +lanes can never fire anything. + +**Epoch-1 transition (2026-10-25 — the first v3 lane is special; do it in order):** +tag `v0.1.207`'s published tree still carries the **v2** workflow file (it IS the +self-fired arm's tree), and `pull_request_target` executes the **base-side** copy — +so the first v3 lane must be cut from **aligned master**, NOT from that tag: a lane +inheriting the v2 wide trigger would self-fire its FIRST carry merge straight into a +publish — the same incident, delivered by `backport.yml`, which AUTO-CUTS a missing +lane from the latest tag the moment any PR gets the `backport` label. Procedure: +1. merge this PR (#4660) into master; +2. merge the open alignment PR #4659 ("align master with v0.1.207 …") — it currently + conflicts against master, resolve/rebase first. After it, master equals npm latest + AND carries the v3 doc. (The two merges are order-safe: with v3 live, #4659's head + `bugfix-v0.1.206` matches neither path and no-ops; with v2 live, base=`master` + matches no trigger at all); +3. create + protect the `bugfix` gate branch from master (payload above); +4. manually cut the first v3 lane from ALIGNED MASTER (same recipe as the auto-cut + step's manual-recovery block, base swapped for aligned master), pre-bump + package.json to the next patch over npm latest (`0.1.208`), protect it (same payload); +5. do NOT apply `backport` labels before step 4 lands — they would auto-cut + `bugfix-v0.1.207` from the stale tag instead; +6. carry the outstanding fixes into the new lane — including advisory bc-2026-001 + (#4655): its original target `bugfix-v0.1.206` is frozen by the monotonic guard + and can never ship it; +7. open the ship PR (lane → `bugfix`, label `ci:full`) and merge = publish `0.1.208`. + +Two accepted consequences of cutting from aligned master: the epoch-1 push trips +`lane-leak-guard.yml`'s tag-based window unless the fork-point baseline shipped with +#4660 is present (it is), and the epoch-1 publish ships everything master held at cut +time — the narrow "tag + fixes only" property is lost for this ONE cycle only; every +later lane is auto-cut from its freshly shipped tag, whose tree carries the v3 file, so +the property holds indefinitely after that. (The alternative — cut from the stale tag +and carry the v3 workflow file in as an inert first commit — was rejected: it strands +the tag stream on the v2-era ci.yml, so lane PRs lose the core matrix permanently.) + +Ship PRs run the COMPLETE suite: ci.yml forces FULL scope for base=`bugfix` +(no label needed), and the e2e lanes ride the standard `ci:full` label on the +ship PR. Belt-and-braces, the publish pipeline ALSO dispatches whatever is +missing of the full set at the exact post-merge sha and waits for green before +npm publish (hard fail; fast-mode skip = owner-owned risk). + +**Cycle stages:** P1 carries land in the lane (silent) → P2 the ship PR +(lane → `bugfix`) merges = publish → P3 right after success the alignment PR +(`bugfix` → master) is auto-opened; the owner merges it (structural conflicts +EXPECTED — resolve master-first, keeping only lane-unique content) → **P4 the +merge of THAT alignment PR auto-cuts the next lane**: `release-bugfix.yml`'s +second path cuts `bugfix-vX.Y.Z` from tag `vX.Y.Z`, pre-bumps package.json +(+1 patch) and pushes it — zero manual steps per cycle after the very first +(one-time manual cut: `bugfix-v0.1.206`). GITHUB_TOKEN cannot apply branch +protection, so each auto-cut ends with an announcement comment carrying the +one remaining click (Settings → Branches, or the payload below). + +**Alignment PR title contract (load-bearing for P4 — do not rename):** +`align master with vX.Y.Z (shipped from )`. An alignment PR whose title +lacks this prefix is ignored by the auto-cut path. `release.yml` cannot do this: it builds the post-merge MASTER tree on push-to-master, so it can never exclude commits already on master. This channel checks out and @@ -292,14 +369,33 @@ removed from `release-bugfix.yml` and from the repository vocabulary: a publish action must be a human MERGE into the protected lane. Runs labeled before the removal complete on their own terms; do not apply the label again. -**Master interaction:** after a lane publish the pipeline AUTO-OPENS the -alignment PR (lane → master) carrying the shipped content incl. the version -bump; structural conflicts vs an evolved master are EXPECTED — resolve -master-first, keeping only lane-unique content. Merging it completes the cycle -(master then equals npm latest, so the master lane's drift guard sees a clean -tree again). Master's next normal release MUST be higher than the shipped -version (after v0.1.206 shipped off its lane, the next normal release is ≥ -0.1.207). +**Lane / gate-branch protection (same status as master — the one manual +click per new branch):** Settings → Branches → Add rule (or API — GITHUB_TOKEN +cannot): +```json +PUT /repos//billion-context/branches/{bugfix | bugfix-vX.Y.Z}/protection +{ + "required_status_checks": { "strict": true, "contexts": [""], "context_options": [] }, + "enforce_admins": false, + "required_pull_request_reviews": { "required_approving_review_count": 0 }, + "allow_force_pushes": { "enabled": false }, + "allow_deletions": { "enabled": false } +} +``` +Context rosters come from the PR's own commits/check-runs (a required context +that ever lands `skipped` deadlocks merges — verified on #4577: lane PRs +produce only `gate`; ship PRs into `bugfix` produce the full ci.yml names plus +the e2e lanes once labeled `ci:full`). + +**Master interaction:** after a publish the pipeline AUTO-OPENS the alignment +PR (`bugfix` → master — the gate branch contains exactly the merged lane) +carrying the shipped content incl. the version bump; structural conflicts vs +an evolved master are EXPECTED — resolve master-first, keeping only +lane-unique content. Merging it completes the cycle (master then equals npm +latest, so the master lane's drift guard sees a clean tree again) and triggers +stage P4 (auto-cut of the next lane). Master's next normal release MUST be +higher than the shipped version (after v0.1.207 ships off its lane, the next +normal release is ≥ 0.1.208). ## Dual-lane releases: label → carry PR → ship @@ -318,10 +414,11 @@ patch, 0.1.207 feature, 0.1.208 patch … all legal). The lane name IS its base tag — no stored pointer anywhere: GITHUB_TOKEN cannot touch the actions- variables API (the earlier variable-based bot 403'd on its maiden run), so the current lane is always DERIVED as `bugfix-v$(git tag --list 'v[0-9]*' --sort=-v:refname | head -1)`. -Since 2026-10-25 the lane is additionally PROTECTED with the same status as -master (see the patch-lane channel rules above) — cutting a fresh lane is a -manual step (push the branch), immediately followed by applying that -protection. +Since 2026-10-25 every lane is PROTECTED with the same status as master (see +the gate-branch rules above). Lane cutting: the FIRST lane of the epoch is +cut manually (push + protect); every later lane is AUTO-CUT by +release-bugfix.yml stage P4 (from the freshly shipped tag, pre-bumped), +leaving only the protection click for the owner. **Routing a fix (label BEFORE merge):** apply the `backport` label to the fix's OPEN PR — any base, any state. `backport.yml` reacts at once: @@ -355,16 +452,18 @@ on `merge^1..merge^2` semantics and must refuse squash/rebase merges outright (rewritten SHAs would ship a PARTIAL fix silently). Pick-from-head works for every merge shape, every time, and lets temporary fixes stay lane-only. -**Ship the lane (v2, 2026-10-25 — MERGE-GATED):** the lane is protected -exactly like master, so the ONLY way content reaches it is a reviewed PR. -**Merging the final carry PR INTO the lane IS the release**: `release-bugfix.yml`'s -`pull_request_target` closed trigger (executing the lane-side copy of the -workflow) publishes the POST-MERGE lane head (= that PR's `merge_commit_sha`), -runs the full guard chain, tags + publishes + creates the GitHub Release, -leaves the audit comment on the merged PR, and AUTO-OPENS the alignment PR -into master. Merging the alignment PR closes the cycle; the next lane is cut -fresh from the new tag. No labels, no direct pushes, no closeout step — -nothing is stored. +**Ship the lane (v3, 2026-10-25 — GATE-BRANCH):** the lane is protected +exactly like master, so the ONLY way content reaches it is a reviewed PR — and +carries merging into the lane publish NOTHING. When the batch is ready, open +the ship PR **`bugfix-vX.Y.Z` → `bugfix`** (tag it `ci:full` for the e2e +lanes; ci.yml already forces the FULL core matrix for base=`bugfix`). +**Merging THAT PR IS the release**: `release-bugfix.yml` (executing the +`bugfix`-side copy) publishes the POST-MERGE lane head (= the ship PR's +`merge_commit_sha`), runs the full guard chain, tags + publishes + creates the +GitHub Release, leaves the audit comment on the merged ship PR, and +AUTO-OPENS the alignment PR (`bugfix` → master). Merging the alignment PR +closes the cycle and auto-cuts the next lane (stage P4). No mechanism labels, +no direct pushes, no closeout step — nothing is stored. (LEGACY, retired with the same change: the "Release (one-click)" `train` dispatch — bump the lane / open a ship PR vs master / publish on that merge — @@ -394,21 +493,23 @@ SHA-differing cherry-pick is the price of leak safety, and `lane-leak-guard.yml` fails any lane push whose history contains a merge whose second parent is a master ancestor. -**CI wiring:** the lane's required checks are the `gate` contexts — one per -e2e-lane workflow (`ci-e2e-*.yml`), each that workflow's scope-decision job, -green on every non-ci:full PR (verified live on a lane PR, #4653 review -2026-10-25: `gate` success while all e2e suites report skipped). REVIEW -FINDING of that pass: although ci.yml's pull_request filter lists `bugfix-v*`, -lane PRs currently produce NO core-matrix check contexts (no plan/test/ -static-gates at the PR head) — treat "core matrix on lane PRs" as aspirational -until that trigger demonstrably fires; it does not gate merges today. What -actually gates a publish is structural: at ship time the post-merge sha is -brand-new, so `release-bugfix.yml` dispatches whatever is missing of the FULL -matrix at the exact publish sha and waits for green before npm publish (hard -fail; fast-mode skip = owner-owned risk, see the workflow). Pushes to -`bugfix-v*` still match ci.yml's push trigger (moot under protected lanes — -direct pushes are forbidden). The `ci.yml` version-guard allowlists `bugfix-v*` -heads (the lane carries its one legal bump commit, made at cut time). +**CI wiring (v3):** lane carry PRs produce the per-e2e-workflow `gate` +contexts (scope-decision jobs, green while e2e suites report skipped) — those +are the lane's required checks (verified live on #4577: 16× `gate` success, +every e2e suite context present-as-skipped). SHIP PRS (into `bugfix`) get the +real deal: ci.yml runs FULL scope for base=`bugfix` (the 16-leg test matrix +under its legacy `test (...)` shard names + static gates) and the `ci:full` +label rides all eight e2e lanes green — so the gate branch's required-checks +list is the ship PR's observed context roster, i.e. full gating realized +literally where a green full suite is actually achievable. Pushes to +`bugfix-v*`/`bugfix` still match ci.yml's push trigger (moot under protection +— direct pushes are forbidden). The `ci.yml` version-guard allowlists +`bugfix-v*` heads (the lane carries its one legal bump commit, made at cut +time). Whatever a ship PR does not cover is closed structurally: at publish +time the post-merge sha is brand-new, so `release-bugfix.yml` dispatches +whatever is missing of the FULL matrix at the exact publish sha and waits for +green before npm publish (hard fail; fast-mode skip = owner-owned risk, see +the workflow). ## CI publish mechanism (what release.yml does)