Merge branch 'next' into merge-train/spartan

AztecBot · AztecBot · commit f6782da599e7 · 2026-06-03T20:02:34.000Z
diff --git a/.claude/skills/fix/SKILL.md b/.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 "..."
diff --git a/.claude/skills/merge-train-infra/SKILL.md b/.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
 
diff --git a/.claude/skills/merge-trains/SKILL.md b/.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.
 
diff --git a/.github/ci3_labels_to_env.sh b/.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"
diff --git a/.github/workflows/merge-train-create-pr.yml b/.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" \
diff --git a/.github/workflows/merge-train-next-to-branches.yml b/.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
 
diff --git a/.github/workflows/merge-train-stale-check.yml b/.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'
diff --git a/CLAUDE.md b/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>
 
diff --git a/ci.sh b/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'
diff --git a/ci3/merge_train_failure_slack_notify b/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
diff --git a/ci3/run_test_cmd b/ci3/run_test_cmd
@@ -50,12 +50,13 @@ if [ "$CI" -eq 1 ]; then
     track_test_history=1
   fi
 
-  # Notify on flakes if in merge queue, backport-to-v2-staging, or merge-train/spartan.
-  # merge-train/spartan runs its full test suite on pull_request (via ci-full-no-test-cache),
-  # not just merge_group, so without this case the spartan PR's flakes are never reported.
+  # Notify on flakes if in merge queue, backport-to-v2-staging, or a spartan merge-train.
+  # The spartan trains run their full test suite on pull_request (via ci-full-no-test-cache),
+  # not just merge_group, so without these cases the spartan PR's flakes are never reported.
   [[ "$is_merge_queue" -eq 1 \
       || "$REF_NAME" == "backport-to-v2-staging" \
-      || "$REF_NAME" == "merge-train/spartan" ]] && slack_notify_flake=1
+      || "$REF_NAME" == "merge-train/spartan" \
+      || "$REF_NAME" == "merge-train/spartan-v5" ]] && slack_notify_flake=1
 
   # Notify on fails for scenario tests.
   [[ ${SCENARIO_TESTS:-0} -eq 1 ]] && slack_notify_fail=1
@@ -354,7 +355,7 @@ function flake_slack_channel {
   fi
   local channel=""
   case "$head_branch" in
-    merge-train/spartan) channel="#team-alpha-ci" ;;
+    merge-train/spartan | merge-train/spartan-v5) channel="#team-alpha-ci" ;;
   esac
   echo "$channel" > "$cache"
   echo "$channel"
diff --git a/scripts/merge-train/merge-next.sh b/scripts/merge-train/merge-next.sh
@@ -62,14 +62,17 @@ function get_meaningful_commits {
     --pretty=format:"%s" | grep -v "^\[empty\]" || true
 }
 
-# Usage: merge-next.sh <train-branch>
-if [[ $# -ne 1 ]]; then
-  echo "Usage: $0 <train-branch>"
+# Usage: merge-next.sh <train-branch> [source-branch]
+# source-branch defaults to "next"; the spartan-v5 train is fed from "v5-next".
+if [[ $# -lt 1 || $# -gt 2 ]]; then
+  echo "Usage: $0 <train-branch> [source-branch]"
   echo "Example: $0 merge-train/docs"
+  echo "Example: $0 merge-train/spartan-v5 v5-next"
   exit 1
 fi
 
 TRAIN_BRANCH="$1"
+SOURCE_BRANCH="${2:-next}"
 
 # Check if PR has auto-merge enabled
 pr_info=$(get_pr_for_branch "$TRAIN_BRANCH")
@@ -87,23 +90,23 @@ fi
 
 # Fetch and checkout the merge-train branch
 git fetch origin "$TRAIN_BRANCH" || exit 1
-git fetch origin next || exit 1
+git fetch origin "$SOURCE_BRANCH" || exit 1
 git checkout "$TRAIN_BRANCH" || exit 1
 
-# Check if there are meaningful commits in next that aren't in the train branch
-meaningful_commits=$(get_meaningful_commits "$TRAIN_BRANCH" "origin/next")
+# Check if there are meaningful commits in the source branch that aren't in the train branch
+meaningful_commits=$(get_meaningful_commits "$TRAIN_BRANCH" "origin/$SOURCE_BRANCH")
 
 if [[ -z "$meaningful_commits" ]]; then
-  echo "No meaningful commits found in next that aren't already in $TRAIN_BRANCH, skipping merge"
+  echo "No meaningful commits found in $SOURCE_BRANCH that aren't already in $TRAIN_BRANCH, skipping merge"
   exit 0
 fi
 
 echo "Found meaningful commits to merge:"
 echo "$meaningful_commits"
 
-# Attempt to merge next
-if git merge "origin/next" --no-edit -m "Merge branch 'next' into $TRAIN_BRANCH"; then
-  echo "Successfully merged next into $TRAIN_BRANCH"
+# Attempt to merge the source branch
+if git merge "origin/$SOURCE_BRANCH" --no-edit -m "Merge branch '$SOURCE_BRANCH' into $TRAIN_BRANCH"; then
+  echo "Successfully merged $SOURCE_BRANCH into $TRAIN_BRANCH"
 
   # Try to push
   if git push origin "$TRAIN_BRANCH"; then
@@ -136,7 +139,7 @@ else
   # Create conflict comment
   conflict_comment="## ⚠️ Auto-merge to ${TRAIN_BRANCH} failed
 
-Merge conflicts detected when merging \`next\` into \`${TRAIN_BRANCH}\`.
+Merge conflicts detected when merging \`${SOURCE_BRANCH}\` into \`${TRAIN_BRANCH}\`.
 
 **Conflicted files:**
 \`\`\`
@@ -145,8 +148,8 @@ ${conflicts}
 
 Please resolve the conflicts manually."
 
-  # Post comment on the most recent commit on next
-  latest_commit=$(gh api repos/{owner}/{repo}/commits/next --jq '.sha')
+  # Post comment on the most recent commit on the source branch
+  latest_commit=$(gh api "repos/{owner}/{repo}/commits/${SOURCE_BRANCH}" --jq '.sha')
   gh api "repos/{owner}/{repo}/commits/${latest_commit}/comments" \
     -f body="$conflict_comment"
 
