feat: add port-to-next label for forward-porting merged PRs

Adds a generic `port-to-next` label that mirrors the `backport-to-*`
labels but with a fixed target: on merge, the PR is cherry-picked onto an
accumulating `port-to-next-staging` branch that opens/updates a single PR
into `merge-train/spartan` (which flows to `next`).

Reuses `scripts/backport_to_staging.sh` via optional STAGING_BRANCH /
STAGING_PR_TITLE env overrides (defaults keep existing backport behavior).
The backport workflow now resolves either label family; the update-pr-body
and auto-merge (8h) automations cover the new staging branch.

Author: PhilWindle

.claude/claudebox/backport.md

@@ -10,8 +10,10 @@ You will receive a prompt like:
 
 Variables you need to extract from the prompt:
 - `PR_NUMBER`: the PR number (e.g., `21829`)
-- `TARGET_BRANCH`: the release branch (e.g., `v4-next`)
-- `STAGING_BRANCH`: always `backport-to-${TARGET_BRANCH}-staging`
+- `TARGET_BRANCH`: the target branch (e.g., `v4-next`, or `merge-train/spartan` for a `port-to-next` port)
+- `STAGING_BRANCH`: `backport-to-${TARGET_BRANCH}-staging` for a backport. For a
+  `port-to-next` port it is `port-to-next-staging`; the prompt states it explicitly
+  (`... (staging branch port-to-next-staging) ...`) — use the branch named there.
 
 ## Constraints
 

.claude/skills/merge-train-infra/SKILL.md

@@ -13,16 +13,25 @@ The merge-train system is fully automated via GitHub Actions in `.github/workflo
 
 1. **PR Creation** (`merge-train-create-pr.yml`): Triggered on push to `merge-train/*` branches. Creates a PR targeting `next` (or `v5-next` for `-v5` trains such as `merge-train/spartan-v5` and `merge-train/fairies-v5`) with the `ci-no-squash` label (plus `private-port-next` for any train that targets `v5-next`, and `ci-full-no-test-cache` for `merge-train/spartan`, `merge-train/spartan-v5`, and `merge-train/ci`). Skips merge commits and commits already in the base branch.
 
-2. **Body Updates** (`merge-train-update-pr-body.yml`): Triggered on push to `merge-train/**` and `backport-to-*-staging` branches. Updates the PR body with meaningful commits (those containing PR references like `(#1234)`). The body wraps the commit list in `BEGIN_COMMIT_OVERRIDE` / `END_COMMIT_OVERRIDE` markers. Backport staging PRs also call `update-pr-body.sh` inline from `scripts/backport_to_staging.sh` to handle the first-push case (where the PR doesn't exist yet when the workflow fires).
+2. **Body Updates** (`merge-train-update-pr-body.yml`): Triggered on push to `merge-train/**`, `backport-to-*-staging`, and `port-to-next-staging` branches. Updates the PR body with meaningful commits (those containing PR references like `(#1234)`). The body wraps the commit list in `BEGIN_COMMIT_OVERRIDE` / `END_COMMIT_OVERRIDE` markers. Backport/port staging PRs also call `update-pr-body.sh` inline from `scripts/backport_to_staging.sh` to handle the first-push case (where the PR doesn't exist yet when the workflow fires).
 
 3. **Next Integration** (`merge-train-next-to-branches.yml`): Triggered on push to `next` and `v5-next`. A push to `next` merges `next` into each `next`-based train; a push to `v5-next` merges `v5-next` into the `-v5` trains (`merge-train/spartan-v5`, `merge-train/fairies-v5`). Both go through `scripts/merge-train/merge-next.sh`, which takes an optional second argument for the source branch (defaults to `next`). Uses `continue-on-error: true` so a conflict in one branch does not block others. Skips branches whose PR already has auto-merge enabled.
 
-4. **Auto-Merge** (`merge-train-auto-merge.yml`): Runs hourly via cron (`0 * * * *`). Calls `scripts/merge-train/auto-merge.sh` for both merge-train (4-hour inactivity) and backport-train (8-hour inactivity) branches. Uses separate GitHub tokens: `AZTEC_BOT_GITHUB_TOKEN` for API calls and `MERGE_TRAIN_GITHUB_TOKEN` for approvals. Will not auto-merge if the last merge-queue CI run failed or was cancelled.
+4. **Auto-Merge** (`merge-train-auto-merge.yml`): Runs hourly via cron (`0 * * * *`). Calls `scripts/merge-train/auto-merge.sh` for merge-train (4-hour inactivity), backport-train (`BRANCH_PATTERN=backport-to-`, 8-hour), and port-to-next (`BRANCH_PATTERN=port-to-next`, 8-hour) branches. Uses separate GitHub tokens: `AZTEC_BOT_GITHUB_TOKEN` for API calls and `MERGE_TRAIN_GITHUB_TOKEN` for approvals. Will not auto-merge if the last merge-queue CI run failed or was cancelled.
 
 5. **Recreation & Wakeup** (`merge-train-recreate.yml`): Triggered when a PR is closed (merged). If the merged PR's head branch starts with `merge-train/`, recreates the branch from the base branch (usually `next`). Then runs `scripts/merge-train/wakeup-prs.sh` to add the `ci-wakeup-pr-after-merge` label to all open PRs targeting the branch that have passed CI and have automerge enabled. This triggers a CI re-run (typically a no-op via tree-hash cache) so those PRs can proceed through the merge queue. The label is immediately removed by a step in `ci3.yml` so it can be re-applied on subsequent merges.
 
 6. **Failure Notification** (`merge-queue-dequeue-notify.yml`): Triggered when a PR is dequeued from the merge queue. If the PR's head branch starts with `merge-train/` and the PR was NOT merged, sends a Slack notification via `ci3/merge_train_failure_slack_notify`. That script also kicks off a ClaudeBox session to investigate/fix the dequeued PR (`ci3/slack_notify_with_claudebox_kickoff`), passing `--repo "$GITHUB_REPOSITORY"` so the session runs in the mode matching the repo the train lives on. When the train is on a private mirror (`…-private`), `claudebox.yml` selects private mode; otherwise it stays public. Without that repo hint a private-train fix session lands in public mode and cannot read the PR or open the fix.
 
+## Label-Driven Ports (`backport.yml`)
+
+`backport.yml` (triggered on `pull_request_target` labeled/closed) cherry-picks a merged PR onto an accumulating staging branch, then opens/updates one staging PR into a target branch. It handles two label families, both driven by `scripts/backport_to_staging.sh`:
+
+- **`backport-to-<branch>`** (e.g. `backport-to-v5-next`): target is `<branch>` (derived from the label), staging branch `backport-to-<branch>-staging`. Direction `next` → release line.
+- **`port-to-next`** (fixed, generic): target is `merge-train/spartan`, staging branch `port-to-next-staging`. Direction: forward-port an already-merged PR into the spartan train (which flows to `next`). The workflow passes `STAGING_BRANCH` / `STAGING_PR_TITLE` env overrides into the script; `port-to-next` takes precedence if both label families are present.
+
+On cherry-pick conflict the workflow comments on the PR, posts to `#backports`, and dispatches ClaudeBox (`.claude/claudebox/backport.md`) with the staging branch to resolve manually. Staging PRs are auto-merged by the 8-hour jobs in `merge-train-auto-merge.yml`.
+
 ## CI Integration Details
 
 ### CI Mode Selection (`.github/ci3_labels_to_env.sh`)
@@ -94,6 +103,7 @@ When a CI run fails on an EC2 instance, it calls `merge_train_failure_slack_noti
 | `.github/workflows/merge-train-update-pr-body.yml` | Updates PR body with commit list (merge-train and backport branches) |
 | `.github/workflows/merge-queue-dequeue-notify.yml` | Slack notification on merge-queue dequeue |
 | `.github/workflows/squashed-pr-check.yml` | Squash enforcement (skipped for `ci-no-squash`) |
+| `.github/workflows/backport.yml` | Cherry-picks merged PRs to staging branches for `backport-to-*` and `port-to-next` labels |
 
 ### Scripts
 

.github/workflows/backport.yml

@@ -1,4 +1,4 @@
-name: Automatic backport action
+name: Automatic backport/port action
 
 on:
   pull_request_target:
@@ -15,7 +15,7 @@ jobs:
         uses: agilepathway/label-checker@825944377ab3bce1269b38c99b718767e2ca6bbc
         with:
           prefix_mode: true
-          any_of: backport-to-
+          any_of: backport-to-,port-to-next
           repo_token: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
           allow_failure: true
       - name: Print status
@@ -24,7 +24,7 @@ jobs:
 
   backport:
     needs: [label_checker]
-    name: Backport PR
+    name: Backport/port PR
     if: github.event.pull_request.merged == true && needs.label_checker.outputs.state == 'success'
     runs-on: ubuntu-latest
     steps:
@@ -34,30 +34,48 @@ jobs:
           fetch-depth: 0
           token: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
 
-      - name: Extract target branch from labels
+      - name: Resolve port target from labels
         id: extract-branch
         env:
           LABELS_JSON: ${{ toJson(github.event.pull_request.labels.*.name) }}
         run: |
           LABELS="$LABELS_JSON"
           echo "All labels: $LABELS"
 
-          # Extract the branch name from backport-to-* label
-          TARGET_BRANCH=$(echo "$LABELS" | jq -r '.[] | select(startswith("backport-to-")) | sub("backport-to-"; "")')
-
-          if [ -z "$TARGET_BRANCH" ]; then
-            echo "No backport-to-* label found"
-            exit 1
+          # port-to-next is a fixed-target port into the spartan merge-train
+          # (which flows to next). It takes precedence over backport-to-* if
+          # both are somehow present.
+          if echo "$LABELS" | jq -e 'index("port-to-next")' >/dev/null; then
+            TARGET_BRANCH="merge-train/spartan"
+            STAGING_BRANCH="port-to-next-staging"
+            STAGING_PR_TITLE="chore: Accumulated ports to next"
+            VERB="ported"
+          else
+            # Extract the branch name from a backport-to-* label
+            TARGET_BRANCH=$(echo "$LABELS" | jq -r '.[] | select(startswith("backport-to-")) | sub("backport-to-"; "")')
+            if [ -z "$TARGET_BRANCH" ]; then
+              echo "No backport-to-* or port-to-next label found"
+              exit 1
+            fi
+            STAGING_BRANCH="backport-to-${TARGET_BRANCH}-staging"
+            STAGING_PR_TITLE="chore: Accumulated backports to $TARGET_BRANCH"
+            VERB="backported"
           fi
 
           echo "target_branch=$TARGET_BRANCH" >> $GITHUB_OUTPUT
+          echo "staging_branch=$STAGING_BRANCH" >> $GITHUB_OUTPUT
+          echo "staging_pr_title=$STAGING_PR_TITLE" >> $GITHUB_OUTPUT
+          echo "verb=$VERB" >> $GITHUB_OUTPUT
           echo "Target branch: $TARGET_BRANCH"
+          echo "Staging branch: $STAGING_BRANCH"
 
       - name: Run backport script
         id: backport
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
+          STAGING_BRANCH: ${{ steps.extract-branch.outputs.staging_branch }}
+          STAGING_PR_TITLE: ${{ steps.extract-branch.outputs.staging_pr_title }}
         run: |
           # Kludge. We should write this in Python or not checkout history.
           # Bash has an ugly footgun with changing history while running the script.
@@ -72,13 +90,14 @@ jobs:
           GH_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
         run: |
           TARGET_BRANCH="${{ steps.extract-branch.outputs.target_branch }}"
-          STAGING_BRANCH="backport-to-${TARGET_BRANCH}-staging"
+          STAGING_BRANCH="${{ steps.extract-branch.outputs.staging_branch }}"
+          VERB="${{ steps.extract-branch.outputs.verb }}"
           STAGING_PR=$(gh pr list --base "$TARGET_BRANCH" --head "$STAGING_BRANCH" --json number,url --jq '.[0]')
           STAGING_PR_NUMBER=$(echo "$STAGING_PR" | jq -r '.number')
           STAGING_PR_URL=$(echo "$STAGING_PR" | jq -r '.url')
 
           gh pr comment "${{ github.event.pull_request.number }}" --body \
-            "✅ Successfully backported to [$STAGING_BRANCH #$STAGING_PR_NUMBER]($STAGING_PR_URL)."
+            "✅ Successfully $VERB to [$STAGING_BRANCH #$STAGING_PR_NUMBER]($STAGING_PR_URL)."
 
       - name: Comment on original PR (failure)
         if: steps.backport.outcome == 'failure'
@@ -91,7 +110,7 @@ jobs:
           gh pr comment "${{ github.event.pull_request.number }}" --body \
             "❌ Failed to cherry-pick to \`$TARGET_BRANCH\` due to conflicts. (🤖) [View backport run]($WORKFLOW_URL)."
 
-      - name: Notify Slack and dispatch ClaudeBox on backport failure
+      - name: Notify Slack and dispatch ClaudeBox on failure
         if: steps.backport.outcome == 'failure'
         env:
           SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
@@ -101,11 +120,13 @@ jobs:
           URL: ${{ github.event.pull_request.html_url }}
           AUTHOR: ${{ github.event.pull_request.user.login }}
           BRANCH: ${{ steps.extract-branch.outputs.target_branch }}
+          STAGING_BRANCH: ${{ steps.extract-branch.outputs.staging_branch }}
+          VERB: ${{ steps.extract-branch.outputs.verb }}
         run: |
 
           # Post single message to #backports, derive permalink from response
-          TEXT=$(printf '⚠️ Backport failed: <%s|#%s %s> → `%s` (author: %s) (🤖)' \
-            "$URL" "$PR" "$TITLE" "$BRANCH" "$AUTHOR")
+          TEXT=$(printf '⚠️ %s failed: <%s|#%s %s> → `%s` (author: %s) (🤖)' \
+            "${VERB^}" "$URL" "$PR" "$TITLE" "$BRANCH" "$AUTHOR")
           RESP=$(curl -sS -X POST https://slack.com/api/chat.postMessage \
             -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
             -H "Content-type: application/json" \
@@ -120,8 +141,8 @@ jobs:
           fi
 
           gh workflow run claudebox.yml \
-            -f prompt="Backport PR #$PR ($TITLE) to $BRANCH. The automatic cherry-pick failed due to conflicts. Follow .claude/claudebox/backport.md to resolve conflicts and create a PR." \
+            -f prompt="${VERB^} PR #$PR ($TITLE) to $BRANCH (staging branch $STAGING_BRANCH). The automatic cherry-pick failed due to conflicts. Follow .claude/claudebox/backport.md to resolve conflicts and create a PR." \
             -f link="${LINK:-$URL}" \
-            -f target_ref="origin/backport-to-${BRANCH}-staging" \
+            -f target_ref="origin/$STAGING_BRANCH" \
             -f slack_channel="$CHANNEL_ID" \
             -f slack_thread_ts="$TS"

.github/workflows/merge-train-auto-merge.yml

@@ -31,3 +31,12 @@ jobs:
           MERGE_STRATEGY=merge \
           INACTIVITY_HOURS=8 \
           ./scripts/merge-train/auto-merge.sh
+
+      - name: Run auto-merge script (port-to-next)
+        run: |
+          GH_TOKEN=${{ secrets.AZTEC_BOT_GITHUB_TOKEN }} \
+          MERGE_TRAIN_GITHUB_TOKEN=${{ secrets.MERGE_TRAIN_GITHUB_TOKEN }} \
+          BRANCH_PATTERN=port-to-next \
+          MERGE_STRATEGY=merge \
+          INACTIVITY_HOURS=8 \
+          ./scripts/merge-train/auto-merge.sh

.github/workflows/merge-train-update-pr-body.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - 'merge-train/**'
       - 'backport-to-*-staging'
+      - 'port-to-next-staging'
 
 jobs:
   update-pr-body:

scripts/backport_to_staging.sh

@@ -66,7 +66,11 @@ if [[ -z "$PR_NUMBER" || -z "$TARGET_BRANCH" ]]; then
   usage
 fi
 
-STAGING_BRANCH="backport-to-${TARGET_BRANCH}-staging"
+# STAGING_BRANCH and STAGING_PR_TITLE may be pre-set in the environment to
+# reuse this script for non-backport ports (e.g. the port-to-next label, which
+# targets merge-train/spartan). They default to the backport naming.
+STAGING_BRANCH="${STAGING_BRANCH:-backport-to-${TARGET_BRANCH}-staging}"
+STAGING_PR_TITLE="${STAGING_PR_TITLE:-chore: Accumulated backports to $TARGET_BRANCH}"
 
 # Check for required tools
 command -v gh >/dev/null 2>&1 || { echo "Error: 'gh' CLI not found. Install from https://cli.github.com/" >&2; exit 1; }
@@ -197,7 +201,7 @@ if [[ -z "$EXISTING_PR" ]]; then
   do_or_dryrun gh pr create \
     --base "$TARGET_BRANCH" \
     --head "$STAGING_BRANCH" \
-    --title "chore: Accumulated backports to $TARGET_BRANCH" \
+    --title "$STAGING_PR_TITLE" \
     --body "Backport staging PR. Body will be updated with commit list."
   do_or_dryrun echo "Created new backport PR"
 else