feat(ci): add merge-train/spartan-v5 targeting v5-next (#23831)

## Summary

Wires up a new merge-train branch, `merge-train/spartan-v5`, that
behaves exactly like `merge-train/spartan` but tracks the **v5 release
line**: it is fed from and targets `v5-next` instead of `next`.

Scoped by grepping every `merge-train` reference repo-wide (all file
types, not just workflows) and adding the `spartan-v5` equivalent
wherever spartan-specific behavior is hard-coded.

## Changes

**Workflows**
- `merge-train-create-pr.yml` — base branch is resolved per train
(`v5-next` for `merge-train/spartan-v5`, `next` otherwise); the "already
merged" ancestor check and the `ci-full-no-test-cache` label list both
use it.
- `merge-train-next-to-branches.yml` — now also triggers on push to
`v5-next`. A push to `v5-next` merges `v5-next` into
`merge-train/spartan-v5`; pushes to `next` continue feeding the other
six trains.
- `merge-train-stale-check.yml` — added a `spartan-v5` job running the
stale check with `BASE_BRANCH=v5-next`, alerting `#team-alpha`.

**Scripts**
- `scripts/merge-train/merge-next.sh` — takes an optional second arg for
the source branch (defaults to `next`); all `next` references (fetch,
diff, merge message, conflict comment + the commit it's posted on) now
use it.

**CI plumbing**
- `.github/ci3_labels_to_env.sh` — `merge-train/spartan-v5` merge-group
runs map to `merge-queue-heavy` (10 grind runs), same as spartan.
- `ci3/run_test_cmd` — flake notifications and the `#team-alpha-ci`
channel mapping include `spartan-v5`.
- `ci3/merge_train_failure_slack_notify` — `merge-train/spartan-v5`
failures route to `#team-alpha`.
- `ci.sh` — comment updated.

**Docs / skills / base-branch guidance**
- `merge-trains` + `merge-train-infra` skills (branch table, CI
behavior, automation lifecycle, and "create a new merge train" steps now
cover non-`next` base branches).
- Root `CLAUDE.md` base-branch mapping notes `merge-train/spartan-v5` (→
`v5-next`) as the v5-line alternative to `merge-train/spartan`.
- `.claude/skills/fix/SKILL.md` notes branching/PR-basing off
`merge-train/spartan-v5` for v5-scoped fixes.

## Verified branch-agnostic — no change needed
These already match `merge-train/*` or capture the subsystem
generically, so they cover `spartan-v5` automatically:
- `merge-train-recreate.yml`, `merge-train-update-pr-body.yml`,
`merge-queue-dequeue-notify.yml` (`startsWith('merge-train/')`)
- `scripts/merge-train/auto-merge.sh` (`BRANCH_PATTERN=merge-train/`),
`update-pr-body.sh` (reads the PR's real base)
- `ci3.sh` instance-postfix + `ci3.yml` concurrency (`merge-train/*`)
- `ci3/dashboard/ci-metrics/github_data.py` and `rk.py` (regex
`merge-train/([^\s]+)`)
- `scripts/commits`, `scripts/filter_history`,
`scripts/find_orphaned_issues_in_prs.py` (`merge-train/` prefix)

No in-repo CODEOWNERS / ruleset / branch-protection config exists (those
live in the GitHub UI). Remaining literal `merge-train/spartan` strings
are illustrative `Example:`/usage comments with no behavior.

## Follow-up needed (cannot be done from this PR)
The `merge-train/spartan-v5` branch itself must be created from
`v5-next` and pushed — branch creation can't go through PR tooling. Once
it exists the automation here takes over (PR creation, integration from
`v5-next`, stale checks, auto-merge, recreation). `v5-next` already
exists as a protected branch.

## CI
Labeled `ci-skip` — workflow/script/docs config only. Shell scripts pass
`bash -n`; workflow YAML parses cleanly.

Author: spalladino

.claude/skills/fix/SKILL.md

@@ -29,7 +29,7 @@ For each issue number provided:
 
 Work through each confirmed issue **sequentially** in the main checkout:
 
-1. **Stash & branch**: Stash any uncommitted changes, then create a branch from `merge-train/spartan` using the issue's `gitBranchName` from Linear.
+1. **Stash & branch**: Stash any uncommitted changes, then create a branch from `merge-train/spartan` using the issue's `gitBranchName` from Linear. For a fix scoped to the v5 release line, branch from `merge-train/spartan-v5` (which targets `v5-next`) instead.
    ```
    git stash
    git checkout -B <gitBranchName> origin/merge-train/spartan
@@ -43,7 +43,7 @@ Work through each confirmed issue **sequentially** in the main checkout:
    - Message format: `fix: <short description> (A-XXX)`
    - Include `Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>`
 
-5. **Push & PR**: Push the branch and create a draft PR.
+5. **Push & PR**: Push the branch and create a draft PR. Use `--base merge-train/spartan-v5` for v5-scoped fixes.
    ```
    git push -u origin <gitBranchName>
    gh pr create --draft --base merge-train/spartan --title "fix: ..." --body "..."

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

@@ -11,11 +11,11 @@ This skill covers the automation internals of the merge-train system. For contri
 
 The merge-train system is fully automated via GitHub Actions in `.github/workflows/merge-train-*.yml`:
 
-1. **PR Creation** (`merge-train-create-pr.yml`): Triggered on push to `merge-train/*` branches. Creates a PR targeting `next` with the `ci-no-squash` label (and `ci-full-no-test-cache` for spartan). Skips merge commits and commits already in `next`.
+1. **PR Creation** (`merge-train-create-pr.yml`): Triggered on push to `merge-train/*` branches. Creates a PR targeting `next` (or `v5-next` for `merge-train/spartan-v5`) with the `ci-no-squash` label (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).
 
-3. **Next Integration** (`merge-train-next-to-branches.yml`): Triggered on push to `next`. Merges `next` into each active merge-train branch via `scripts/merge-train/merge-next.sh`. Uses `continue-on-error: true` so a conflict in one branch does not block others. Skips branches whose PR already has auto-merge enabled.
+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 `merge-train/spartan-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.
 
@@ -29,7 +29,7 @@ The merge-train system is fully automated via GitHub Actions in `.github/workflo
 
 Merge-train branches influence CI mode:
 - `merge_group` events or `ci-merge-queue` label → `merge-queue` mode
-- If the merge-group event is for `merge-train/spartan` → upgraded to `merge-queue-heavy` mode (10 parallel grind runs instead of 4)
+- If the merge-group event is for `merge-train/spartan` or `merge-train/spartan-v5` → upgraded to `merge-queue-heavy` mode (10 parallel grind runs instead of 4)
 - Target branch `merge-train/docs` → `ci-docs` mode
 - Target branch `merge-train/barretenberg` → `ci-barretenberg` mode
 
@@ -57,7 +57,7 @@ Merge-train PRs get a unique instance postfix (commit count) to allow parallel E
 - `ci-barretenberg`: Only builds and tests barretenberg (AVM disabled)
 - `ci-barretenberg-full`: Full barretenberg CI including acir_tests
 - `merge-queue`: 4x AMD64 full + 1x ARM64 fast in parallel
-- `merge-queue-heavy`: 10x AMD64 full + 1x ARM64 fast in parallel (used for `merge-train/spartan`)
+- `merge-queue-heavy`: 10x AMD64 full + 1x ARM64 fast in parallel (used for `merge-train/spartan` and `merge-train/spartan-v5`)
 
 ### Test History Tracking (`ci3/run_test_cmd`)
 
@@ -73,11 +73,12 @@ When a CI run fails on an EC2 instance, it calls `merge_train_failure_slack_noti
 
 ## Creating a New Merge Train
 
-1. Create a branch from `next` with naming pattern `merge-train/{team}`
-2. Add the branch to the matrix in `.github/workflows/merge-train-next-to-branches.yml`
-3. Add the branch-to-Slack-channel mapping in `ci3/merge_train_failure_slack_notify`
-4. Optionally add CI mode overrides in `.github/ci3_labels_to_env.sh` and `bootstrap.sh`
-5. Push code to the branch -- automation handles PR creation from there
+1. Create a branch from the desired base (`next` for most trains; a release line like `v5-next` for a release-specific train) with naming pattern `merge-train/{team}`
+2. Add the branch to the loop in `.github/workflows/merge-train-next-to-branches.yml`. If it tracks a base branch other than `next`, also add that base to the workflow's `push` trigger and pass it as the second argument to `merge-next.sh` (see the `merge-train/spartan-v5` → `v5-next` wiring)
+3. If the base is not `next`, set the PR base in `.github/workflows/merge-train-create-pr.yml` and pass `BASE_BRANCH` to the stale check in `.github/workflows/merge-train-stale-check.yml`
+4. Add the branch-to-Slack-channel mapping in `ci3/merge_train_failure_slack_notify`
+5. Optionally add CI mode overrides in `.github/ci3_labels_to_env.sh` and `bootstrap.sh`
+6. Push code to the branch -- automation handles PR creation from there
 
 ## Key Files Reference
 

.claude/skills/merge-trains/SKILL.md

@@ -19,6 +19,9 @@ A merge train is an automated batching system (inspired by [Rust rollups](https:
 | `merge-train/docs` | Documentation | `#dev-rels` |
 | `merge-train/fairies` | aztec-nr | `#team-fairies` |
 | `merge-train/spartan` | Spartan / infra / yarn-project sequencer and prover orchestration | `#team-alpha` |
+| `merge-train/spartan-v5` | Same as `merge-train/spartan` but for the v5 release line (targets `v5-next` instead of `next`) | `#team-alpha` |
+
+> Every train targets `next` except `merge-train/spartan-v5`, which targets `v5-next`.
 
 ## How to Use a Merge Train
 
@@ -39,7 +42,7 @@ A merge train is an automated batching system (inspired by [Rust rollups](https:
 ## CI Behavior for Merge Trains
 
 - **Specialized CI modes**: PRs targeting `merge-train/docs` run docs-only CI. PRs targeting `merge-train/barretenberg` run barretenberg-only CI. This avoids running the full test suite for domain-specific changes.
-- **Merge-queue mode**: When the merge-train PR enters GitHub's merge queue, it runs the full `merge-queue` CI mode (4 parallel grind runs on AMD64 + 1 ARM64). `merge-train/spartan` uses the heavier `merge-queue-heavy` mode (10 grind runs).
+- **Merge-queue mode**: When the merge-train PR enters GitHub's merge queue, it runs the full `merge-queue` CI mode (4 parallel grind runs on AMD64 + 1 ARM64). `merge-train/spartan` and `merge-train/spartan-v5` use the heavier `merge-queue-heavy` mode (10 grind runs).
 - **Full concurrency**: Merge-train PRs get unique CI concurrency groups (using `github.run_id`), so multiple CI runs can proceed in parallel without cancelling each other.
 - **Test history tracking**: Test results are tracked for merge-train PRs, same as merge-queue runs.
 

.github/ci3_labels_to_env.sh

@@ -107,7 +107,7 @@ function main {
     ci_mode="skip"
   elif [ "${GITHUB_EVENT_NAME:-}" == "merge_group" ] || has_label "ci-merge-queue"; then
     ci_mode="merge-queue"
-    # Check if this is a merge-train/spartan PR entering the merge queue.
+    # Check if this is a spartan merge-train PR entering the merge queue.
     # If so, use the heavier merge-queue-heavy mode (10 grind runs).
     if [ "${GITHUB_EVENT_NAME:-}" == "merge_group" ] && [ -n "${GITHUB_TOKEN:-}" ]; then
       # GITHUB_REF_NAME in merge_group is like: gh-readonly-queue/next/pr-XXX-SHA
@@ -116,7 +116,7 @@ function main {
       if [ -n "$pr_number" ]; then
         local head_branch
         head_branch=$(GH_TOKEN="$GITHUB_TOKEN" gh pr view "$pr_number" --json headRefName -q '.headRefName' 2>/dev/null || true)
-        if [ "$head_branch" == "merge-train/spartan" ]; then
+        if [ "$head_branch" == "merge-train/spartan" ] || [ "$head_branch" == "merge-train/spartan-v5" ]; then
           ci_mode="merge-queue-heavy"
         elif [ "$head_branch" == "merge-train/ci" ]; then
           ci_mode="merge-queue-ci"

.github/workflows/merge-train-create-pr.yml

@@ -23,16 +23,23 @@ jobs:
         run: |
             branch="${{ github.ref_name }}"
 
+            # Determine base branch. Most trains target next; the spartan-v5
+            # train targets the v5 release line (v5-next) instead.
+            base_branch="next"
+            if [[ "$branch" == "merge-train/spartan-v5" ]]; then
+              base_branch="v5-next"
+            fi
+
             # Skip if this is a merge commit (check for multiple parents)
             parent_count=$(git rev-list --parents -n 1 "${{ github.sha }}" | wc -w)
             if [[ $parent_count -gt 2 ]]; then
               echo "Skipping: This is a merge commit."
               exit 0
             fi
 
-            # Skip if this commit is already in the next branch
-            if git merge-base --is-ancestor "${{ github.sha }}" origin/next; then
-              echo "Skipping: This commit is already in the next branch"
+            # Skip if this commit is already in the base branch
+            if git merge-base --is-ancestor "${{ github.sha }}" "origin/$base_branch"; then
+              echo "Skipping: This commit is already in the $base_branch branch"
               exit 0
             fi
 
@@ -42,12 +49,9 @@ jobs:
             if [[ -z "$existing_pr" ]]; then
               echo "No PR exists for $branch, creating one"
 
-              # Determine base branch (default to next)
-              base_branch="next"
-
               # Create PR with ci-no-squash label
               labels="ci-no-squash"
-              if [[ "$branch" == "merge-train/spartan" || "$branch" == "merge-train/ci" ]]; then
+              if [[ "$branch" == "merge-train/spartan" || "$branch" == "merge-train/spartan-v5" || "$branch" == "merge-train/ci" ]]; then
                 labels="$labels,ci-full-no-test-cache"
               fi
               gh pr create --base "$base_branch" --head "$branch" \

.github/workflows/merge-train-next-to-branches.yml

@@ -4,10 +4,11 @@ on:
   push:
     branches:
       - next
+      - v5-next
 
 jobs:
   merge-to-trains:
-    name: Merge next to merge-train branches
+    name: Merge base branch into merge-train branches
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -26,7 +27,14 @@ jobs:
           GH_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
           COMMIT_SHA: ${{ github.sha }}
         run: |
-          for branch in merge-train/avm merge-train/barretenberg merge-train/ci merge-train/docs merge-train/fairies merge-train/spartan; do
-            ./scripts/merge-train/merge-next.sh "$branch" || true
-          done
+          # The spartan-v5 train tracks the v5 release line (v5-next); every
+          # other train tracks next. Sync only the trains fed by the branch
+          # that was just pushed.
+          if [[ "${{ github.ref_name }}" == "v5-next" ]]; then
+            ./scripts/merge-train/merge-next.sh merge-train/spartan-v5 v5-next || true
+          else
+            for branch in merge-train/avm merge-train/barretenberg merge-train/ci merge-train/docs merge-train/fairies merge-train/spartan; do
+              ./scripts/merge-train/merge-next.sh "$branch" || true
+            done
+          fi
 

.github/workflows/merge-train-stale-check.yml

@@ -20,3 +20,18 @@ jobs:
           GH_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
           SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
         run: ./ci3/merge_train_stale_check merge-train/spartan '#team-alpha'
+
+  spartan-v5:
+    name: Check merge-train/spartan-v5
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - name: Run stale check
+        env:
+          GH_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          BASE_BRANCH: v5-next
+        run: ./ci3/merge_train_stale_check merge-train/spartan-v5 '#team-alpha'

CLAUDE.md

@@ -40,6 +40,8 @@ Otherwise infer from the component being worked in:
 | `barretenberg/cpp/src/barretenberg/vm2/**` | `merge-train/avm` |
 | everything else | `next` |
 
+The bases above target the `next` line. For work scoped to the v5 release line, use `merge-train/spartan-v5` (which targets `v5-next`) in place of `merge-train/spartan`.
+
 Use the discovered base in `git diff origin/<base>...HEAD` and `git log origin/<base>..HEAD`. Always `git fetch` before creating branches so the base is not stale.
 </critical_never_assume_master>
 

ci.sh

@@ -165,7 +165,7 @@ case "$cmd" in
       'a1-fast arm64 ci-fast'
     ;;
   merge-queue-heavy)
-    # Heavy merge queue with 10 parallel grind runs, used for merge-train/spartan PRs.
+    # Heavy merge queue with 10 parallel grind runs, used for merge-train/spartan and merge-train/spartan-v5 PRs.
     multi_job_run \
       'x'{1..10}'-full amd64 ci-full-no-test-cache' \
       'a1-fast arm64 ci-fast'

ci3/merge_train_failure_slack_notify

@@ -35,6 +35,8 @@ elif [[ "$REF_NAME" == "merge-train/fairies" ]]; then
   channel="#team-fairies"
 elif [[ "$REF_NAME" == "merge-train/spartan" ]]; then
   channel="#team-alpha"
+elif [[ "$REF_NAME" == "merge-train/spartan-v5" ]]; then
+  channel="#team-alpha"
 else
   exit 0
 fi