@plainconceptsplatform/workflows 1.5.0 → 1.6.0

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -203,20 +203,23 @@ assert_route "EVIDENCE_ENABLED=false turns the merge route off" none \
   EVENT=pull_request_target ACTION=closed PR_MERGED=true EVENT_PR_NUMBER=7 EVIDENCE_ENABLED=false
 
 echo "── CI completion ─────────────────────────────────────────────────────────"
-assert_route "a failed App CI run on a pull request routes to merge-gate" merge-gate \
-  EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=failure RUN_ID=99
-assert "merge-gate carries the failing CI conclusion" failure \
-  "$(route_field ci-conclusion EVENT=workflow_run RUN_PR_NUMBER=7 \
-    RUN_CONCLUSION=failure RUN_ID=99)"
-assert "merge-gate carries the failing CI run id" 99 \
-  "$(route_field ci-run-id EVENT=workflow_run RUN_PR_NUMBER=7 \
-    RUN_CONCLUSION=failure RUN_ID=99)"
-assert_route "a green App CI run does not auto-trigger the gate" none \
-  EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=success RUN_ID=99
-assert_route "a cancelled App CI run does not auto-trigger the gate" none \
-  EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=cancelled RUN_ID=99
-assert_route "a failed CI run with no pull request routes nowhere" none \
-  EVENT=workflow_run RUN_PR_NUMBER= RUN_CONCLUSION=failure RUN_ID=99
+# A CI verdict moves the merge train, green or red; the train picks which pull request the gate
+# takes. Dispatching the gate for the run's own pull request is how a night of them raced each
+# other for the default branch.
+assert_route "a failed App CI run on a pull request moves the merge train" merge-train   EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=failure RUN_ID=99
+assert_route "a green App CI run on a pull request moves the merge train" merge-train   EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=success RUN_ID=99
+assert "the train hears the CI conclusion" failure   "$(route_field ci-conclusion EVENT=workflow_run RUN_PR_NUMBER=7     RUN_CONCLUSION=failure RUN_ID=99)"
+assert "the train hears the CI run id" 99   "$(route_field ci-run-id EVENT=workflow_run RUN_PR_NUMBER=7     RUN_CONCLUSION=failure RUN_ID=99)"
+assert_route "a cancelled App CI run moves nothing" none   EVENT=workflow_run RUN_PR_NUMBER=7 RUN_CONCLUSION=cancelled RUN_ID=99
+assert_route "a failed CI run with no pull request routes nowhere" none   EVENT=workflow_run RUN_PR_NUMBER= RUN_CONCLUSION=failure RUN_ID=99
+# A consumer CI hands its verdict over with GITHUB_TOKEN. Old CIs dispatch merge-gate; that is a
+# CI completion, so it moves the train instead of jumping the queue. A person or the train itself
+# dispatching merge-gate still reaches the gate.
+assert_route "a consumer CI's merge-gate handover moves the train" merge-train   EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=7 ACTOR='github-actions[bot]'
+assert "the handover carries its verdict to the train" success   "$(route_field ci-conclusion EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=7     ACTOR='github-actions[bot]' INPUT_CI_CONCLUSION=success INPUT_CI_RUN_ID=5)"
+assert_route "the train's own gate dispatch reaches the gate" merge-gate   EVENT=workflow_dispatch OPERATION=merge-gate INPUT_PR_NUMBER=7 ACTOR='platform-devbox[bot]'
+assert_route "merge-train dispatch needs no pull request" merge-train   EVENT=workflow_dispatch OPERATION=merge-train
+assert "a merge-train handover carries its run id" 5   "$(route_field ci-run-id EVENT=workflow_dispatch OPERATION=merge-train INPUT_PR_NUMBER=7     INPUT_CI_CONCLUSION=failure INPUT_CI_RUN_ID=5)"
 
 echo "── Schedules ─────────────────────────────────────────────────────────────"
 while read -r cron; do
@@ -694,60 +697,76 @@ if worker_installed merge-gate; then
   fi
 fi
 
-# A verdict is the gate marker AND a `**Verdict:**` line together. Comments carrying the
-# marker alone were progress notes and failed attempts, and the reconcile belt read every
-# one of them as final: a crashed or OOM-killed gate parked its pull request for the rest
-# of the night. Attempts are counted separately, capped, and reset by any new CI run.
-# The belt lives in the router's plumbing jobs, so this holds in every repository.
-BELT_OK=1
-if ! grep -q 'agent-merge-gate-attempt' "$ROUTER_YML"; then
-  BELT_OK=0; echo "FAIL: router never counts gate attempts" >&2
-fi
-if [ "$(count -cF 'contains("<!-- agent-merge-gate -->")) and (.body | contains("**Verdict:**"))' "$ROUTER_YML")" -lt 4 ]; then
-  BELT_OK=0; echo "FAIL: verdict detection must pair the gate marker with a Verdict line in both dispatch paths" >&2
-fi
-if [ "$(count -c 'attempts_so_far' "$ROUTER_YML")" -lt 2 ]; then
-  BELT_OK=0; echo "FAIL: dispatch sites must forward attempts_so_far" >&2
-fi
-# A second gate for a pull request whose gate is already queued or running reads the same CI
-# verdict, and the belt's queue would run it twice.
-if [ "$(count -c 'a merge-gate run is already live' "$ROUTER_YML")" -lt 2 ]; then
-  BELT_OK=0; echo "FAIL: both dispatch paths must skip a pull request whose gate is already live" >&2
-fi
-# A conflicting pull request has no refs/pull/N/merge for GitHub to build, so a `pull_request`
-# CI workflow can never run on that head. Requiring a fresh verdict before dispatching deadlocks
-# the belt: only the gate resolves the conflict, and the gate never runs. Both paths fall back to
-# the branch's last verdict when, and only when, the pull request is conflicting.
-if [ "$(count -c 'conflicts, so CI cannot run on' "$ROUTER_YML")" -lt 2 ]; then
-  BELT_OK=0
-  echo "FAIL: both dispatch paths must gate a conflicting pull request that can never get fresh CI" >&2
-fi
-# That fallback has to read the computed mergeable state. The REST boolean is null until GitHub
-# recomputes it, and stays null for a pull request nobody has opened recently, which is exactly
-# the stale conflicting pull request the fallback exists for: it never fired once in production.
-# The state has to be polled, not read once. GitHub computes mergeability on demand and the
-# first read answers UNKNOWN (or null through REST) while it works it out, so a single read
-# reports "not conflicting" for exactly the stale pull requests the fallback is for. Observed
-# twice in production: the fallback logged "no completed CI run" for a pull request that
-# `gh pr view` reported as CONFLICTING from a warm cache seconds later.
-if [ "$(count -c 'mergeable_state()' "$ROUTER_YML")" -lt 2 ] ||
-  [ "$(count -c 'mergeable_now=$(mergeable_state' "$ROUTER_YML")" -lt 2 ]; then
-  BELT_OK=0
-  echo "FAIL: both dispatch paths must poll the mergeable state; a single read answers UNKNOWN" >&2
+# The belt is the merge train now: one gate at a time, oldest pull request first. Its I/O lives in
+# the merge-train action and every rule it learned as the belt is asserted there.
+#
+# A verdict is the gate marker AND a `**Verdict:**` line together. Comments carrying the marker
+# alone were progress notes and failed attempts, and the belt read every one of them as final: a
+# crashed or OOM-killed gate parked its pull request for the rest of the night. Attempts are
+# counted separately and capped.
+TRAIN_SH="${HERE}/../merge-train/merge-train.sh"
+if worker_installed merge-gate; then
+  BELT_OK=1
+  if [ ! -f "$TRAIN_SH" ]; then
+    BELT_OK=0; echo "FAIL: the merge gate is installed without the merge-train action" >&2
+  else
+    grep -q 'agent-merge-gate-attempt' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the merge train never counts gate attempts" >&2; }
+    grep -qF 'contains("<!-- agent-merge-gate -->")) and (.body | test("Verdict:' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the train's verdict detection must pair the gate marker with a Verdict line" >&2; }
+    grep -qF 'inputs[attempts_so_far]=' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the train must forward attempts_so_far to the gate" >&2; }
+    # One gate at a time, found by the title run-name gives it. The belt looked for a title that
+    # run-name had stopped producing, saw no live gate ever, and dispatched #680 five times in
+    # an hour onto a belt that runs one gate at a time.
+    gate_title="$(sed -n "s/.*format('\(Agent: Merge Gate - PR #\){0}'.*/\1/p" "$ROUTER_YML" | head -1)"
+    if [ -z "$gate_title" ] || ! grep -qF "GATE_TITLE_PREFIX=\"${gate_title}\"" "$TRAIN_SH"; then
+      BELT_OK=0
+      echo "FAIL: the train looks for live gates titled differently from what run-name names them ('${gate_title:-unread}')" >&2
+    fi
+    # A conflicting pull request has no refs/pull/N/merge, so CI can never run on its head; the
+    # train hands it to the gate on the branch's last verdict rather than waiting forever.
+    grep -qF 'actions/runs?branch=$head_ref' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the train must gate a conflicting pull request on its branch's last verdict" >&2; }
+    # GitHub computes mergeability on demand and the first read answers UNKNOWN.
+    grep -q 'mergeable=$(mergeable_state' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the train must poll the mergeable state; a single read answers UNKNOWN" >&2; }
+    # The park is keyed to the head commit, never the CI time: a CI re-run must not reopen a park
+    # a person owns.
+    grep -qF '[ "$verdict_at" \> "$head_committed" ]' "$TRAIN_SH" ||
+      { BELT_OK=0; echo "FAIL: the train must key a verdict's park to the head commit" >&2; }
+  fi
+  # The App token: a dispatch or a branch update made with GITHUB_TOKEN starts no workflow.
+  train_job="$(sed -n '/^  merge-train:$/,/^  [a-z-]*:$/p' "$ROUTER_YML")"
+  if ! grep -q 'token: ${{ steps.app-token.outputs.token }}' <<<"$train_job" ||
+    ! grep -q 'group: merge-train' <<<"$train_job" ||
+    ! grep -q 'needs: \[classify, call-merge-gate\]' <<<"$train_job"; then
+    BELT_OK=0
+    echo "FAIL: the merge-train job must use the App token, hold the merge-train lock and tick after the gate" >&2
+  fi
+  if [ "$BELT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
-if [ "$BELT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-# GitHub delivers workflow_run only for CI runs whose actor is a human, so a bot pull request's
-# CI never reaches the router's CI-completion route. The package ships a dispatch-merge-gate job
-# in templates/ci that hands the verdict over from inside CI; a consumer CI workflow, where one
-# exists beside the router, must carry it or bot pull requests wait for the hourly belt.
+# GitHub delivers workflow_run only for CI runs whose actor is a human, so a bot-updated pull
+# request's CI never reaches the router's CI-completion route. The package ships a dispatch job in
+# templates/ci that hands the verdict over from inside CI; a consumer CI workflow, where one exists
+# beside the router, must carry it or those pull requests wait for the hourly tick.
 for ci in "${WORKFLOWS_DIR}/ci.yml" "${WORKFLOWS_DIR}/app-ci.yml"; do
   [ -f "$ci" ] || continue
-  if grep -q 'operation=merge-gate' "$ci"; then
+  if grep -qE 'operation=merge-(gate|train)' "$ci"; then
     PASS=$((PASS + 1))
   else
     FAIL=$((FAIL + 1))
-    echo "FAIL: $(basename "$ci") has no dispatch-merge-gate job; bot pull requests would wait for the hourly belt" >&2
+    echo "FAIL: $(basename "$ci") hands no CI verdict to the merge train; pull requests would wait for the hourly tick" >&2
+  fi
+done
+for template in "${HERE}/../../templates/ci/"*.yml; do
+  [ -f "$template" ] || continue
+  if grep -q 'operation=merge-train' "$template" && ! grep -q "pull_request.user.type == 'Bot'" "$template"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: $(basename "$template") must hand every same-repository pull request's verdict to the merge train" >&2
   fi
 done
 
@@ -1110,7 +1129,7 @@ done < <(sed -n '/^      operation:/,/^      issue-number:/p' "$ROUTER_YML" |
 # contents and issues and failed nightly on a 403 that named the endpoint and nothing else.
 # Paired job-to-scope rather than parsed out of each action: the jobs that touch pull
 # requests are few and known, and naming them here is what makes the omission visible.
-for pr_job in audit-close reconcile-bot-pr-runs detect-pr-conflicts housekeeping; do
+for pr_job in audit-close reconcile-bot-pr-runs merge-train land-stack-child housekeeping; do
   if ! grep -q "^  ${pr_job}:$" "$ROUTER_YML"; then
     continue
   fi
@@ -1754,17 +1773,18 @@ fi
 
 echo "── Merge gate park ───────────────────────────────────────────────────────"
 
-# A gate verdict parks the code it was given on. Both dispatch paths -- detect-pr-conflicts and
-# the reconcile belt -- used to compare the standing verdict against the CI finish time, which
-# made the park worthless: any later run on the same commits was newer than the verdict, so the
-# belt re-dispatched a pull request a human already owned and reset its attempt budget at the
-# same time. Lyceum PR #13 sat parked for six days while that happened. Asserted because both
-# comparisons are one line and neither failing produces a red run.
+# A gate verdict parks the code it was given on. The belt used to compare the standing verdict
+# against the CI finish time, which made the park worthless: any later run on the same commits was
+# newer than the verdict, so it re-dispatched a pull request a human already owned. Lyceum PR #13
+# sat parked for six days while that happened. The opposite failure is what parked Pliny-Bot for
+# whole weekends: a park that never expired, so a pull request blocked on Friday night was still
+# blocked on Monday though the default branch had moved under it a dozen times. The train's two
+# pure functions decide both, and they are exercised here rather than read.
 if worker_installed merge-gate; then
   GATE_OK=1
 
-  # Neither path may key the park to CI timing again.
-  stale_horizon=$(count -cE 'verdict" \\> "\$ci_finished"|latest_verdict" \\> "\$ci_finished"' "$ROUTER_YML")
+  # Nothing may key the park to CI timing again.
+  stale_horizon=$(count -cE 'verdict" \> "\$ci_finished"|latest_verdict" \> "\$ci_finished"' "$ROUTER_YML")
   if [ "$stale_horizon" -eq 0 ]; then
     PASS=$((PASS + 1))
   else
@@ -1772,13 +1792,37 @@ if worker_installed merge-gate; then
     echo "FAIL: the merge-gate park is keyed to the CI finish time in ${stale_horizon} place(s); a CI re-run would reopen a park a person owns" >&2
   fi
 
-  # Both must fall back to the CI time only when the head commit cannot be read.
-  horizons=$(count -cE '\$\{head_committed:-\$ci_finished\}' "$ROUTER_YML")
-  if [ "$horizons" -eq 2 ]; then
-    PASS=$((PASS + 1))
-  else
-    GATE_OK=0
-    echo "FAIL: ${horizons} of the 2 gate dispatch paths key their park to the head commit" >&2
+  if [ -f "$TRAIN_SH" ]; then
+    # Each call in its own shell: the facts are environment variables, and one case's must not
+    # leak into the next.
+    park() { env "$@" bash -c "source '$TRAIN_SH'; train_park"; }
+    move() { env "$@" bash -c "source '$TRAIN_SH'; train_move" | sed -n 's/^move=//p'; }
+
+    assert "no verdict leaves the pull request to the train" none "$(park VERDICT= VERDICT_NEWER=false)"
+    assert "a verdict older than the head is spent" none "$(park VERDICT=owner-review VERDICT_NEWER=false)"
+    assert "owner-review on this head waits for its owner" held "$(park VERDICT=owner-review VERDICT_NEWER=true BASE_MOVED=true)"
+    assert "human-review on this head waits for a person" held "$(park VERDICT=human-review VERDICT_NEWER=true BASE_MOVED=true)"
+    assert "remediated never parks: the gate wants the next CI" none "$(park VERDICT=remediated VERDICT_NEWER=true)"
+    assert "blocked holds while the base has not moved" held "$(park VERDICT=blocked VERDICT_NEWER=true BASE_MOVED=false RETRIES=1)"
+    assert "blocked is retried once the base moves" none "$(park VERDICT=blocked VERDICT_NEWER=true BASE_MOVED=true RETRIES=1 MAX_RETRIES=3)"
+    assert "blocked holds once its retries are spent" held "$(park VERDICT=blocked VERDICT_NEWER=true BASE_MOVED=true RETRIES=3 MAX_RETRIES=3)"
+    assert "a merge that did not happen is retried once the base moves" none "$(park VERDICT=auto-merge VERDICT_NEWER=true BASE_MOVED=true RETRIES=1)"
+    assert "a stack root is never retried into a merge" held "$(park VERDICT=auto-merge VERDICT_NEWER=true BASE_MOVED=true RETRIES=0 STACK_ROOT=true)"
+
+    assert "hold keeps a pull request off the train" skip "$(move HOLD=true CI_STATUS=completed CI_CONCLUSION=success)"
+    assert "requested changes keep it off the train" skip "$(move REVIEW_DECISION=CHANGES_REQUESTED CI_STATUS=completed CI_CONCLUSION=success)"
+    assert "a parked pull request is passed by, not waited on" skip "$(move PARK=held CI_STATUS=completed CI_CONCLUSION=success)"
+    assert "a spent attempt budget is passed by" skip "$(move ATTEMPTS=6 MAX_ATTEMPTS=6 CI_STATUS=completed CI_CONCLUSION=failure)"
+    assert "a conflict goes to the gate even with no CI" gate "$(move MERGEABLE=CONFLICTING CI_STATUS=none)"
+    assert "running CI is waited on" wait "$(move MERGEABLE=MERGEABLE CI_STATUS=in_progress)"
+    assert "CI stuck past the limit is passed by" skip "$(move MERGEABLE=MERGEABLE CI_STATUS=queued CI_STUCK=true)"
+    assert "red CI goes to the gate" gate "$(move MERGEABLE=MERGEABLE CI_STATUS=completed CI_CONCLUSION=failure)"
+    assert "green but behind is brought up to date first" update "$(move MERGEABLE=MERGEABLE CI_STATUS=completed CI_CONCLUSION=success BEHIND_BY=2)"
+    assert "green and current goes to the gate" gate "$(move MERGEABLE=MERGEABLE CI_STATUS=completed CI_CONCLUSION=success BEHIND_BY=0)"
+    assert "no CI run is passed by" skip "$(move MERGEABLE=MERGEABLE CI_STATUS=none)"
+    assert "a trusted bot's CI awaiting approval is approved" approve "$(move CI_STATUS=completed CI_CONCLUSION=action_required TRUSTED_AUTHOR=true)"
+    assert "a person's CI awaiting approval is not approved by the train" skip "$(move CI_STATUS=completed CI_CONCLUSION=action_required TRUSTED_AUTHOR=false)"
+    assert "a cancelled run is no verdict" skip "$(move MERGEABLE=MERGEABLE CI_STATUS=completed CI_CONCLUSION=cancelled)"
   fi
 
   # One cap, not four literals, and it has to match what the worker tells the reader.
@@ -2518,8 +2562,8 @@ for worker_md in "${WORKFLOWS_DIR}"/agent-*.md; do
 done
 if [ "$INPUT_WIRING_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
-# Several paths dispatch gates at once (the reconcile tick, CI's dispatch-merge-gate, the
-# conflict rescan). Without `queue: max` GitHub keeps one pending run in the group and cancels the
+# The train dispatches one gate at a time, but a person, a merge-gate label and an old consumer CI
+# can still dispatch one beside it. Without `queue: max` GitHub keeps one pending run in the group and cancels the
 # rest with no comment and no recorded attempt; every dispatch still returns 204.
 BELT_QUEUE_OK=1
 belt_caller=$(awk '/^  call-merge-gate:/ { found = 1; print; next } found && /^  [a-z]/ { exit } found { print }' "$ROUTER_YML")
@@ -2573,7 +2617,7 @@ if worker_installed merge-gate; then
     echo "FAIL: the incomplete job must read one computed budget decision, not re-derive it" >&2
   fi
   # The park has to be a verdict or the belt keeps dispatching: a comment carrying the gate
-  # marker AND a Verdict line is what detect-pr-conflicts and the reconcile belt both park on.
+  # marker AND a Verdict line is what the merge train parks on.
   if ! grep -A 16 "Record an unusable report as a decision" "$MERGE_GATE_WORKER_MD" |
        grep -q '\${{ env.GATE_MARKER }}' ||
      ! grep -A 16 "Record an unusable report as a decision" "$MERGE_GATE_WORKER_MD" |

package/loops/docs/diagrams.md

@@ -57,7 +57,7 @@ flowchart TD
     wTriage("agent-triage")
     classify -.->|"cron or dispatch"| plumbing
     plumbing["deterministic jobs<br/>no model runs in any of these"] --> pJobs
-    pJobs("bot-approve · audit-close<br/>cleanup-artifacts · validate<br/>reconcile-bot-pr-runs · detect-pr-conflicts<br/>check-stack-branch · dispatch-implement")
+    pJobs("bot-approve · audit-close<br/>cleanup-artifacts · validate<br/>reconcile-bot-pr-runs · merge-train · land-stack-child<br/>check-stack-branch · dispatch-implement")
     idle(("Idle<br/>run ends, ~10s, every job skipped"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
@@ -87,10 +87,14 @@ flowchart LR
     refine -->|"8 or more"| split("Split into children") --> refine
     refine -.->|questions| author
     implement("implement<br/>branch, PR, closes the issue") --> ci("CI")
-    ci --> gate{"merge-gate"}
+    person("A person opens a PR") --> ci
+    ci --> train{"merge train<br/>oldest PR first,<br/>one at a time"}
+    train -.->|"green, behind main"| update("Merge main in") --> ci
+    train --> gate{"merge-gate"}
     gate -->|merge| merged(("Merged"))
-    gate -.->|"CI failed"| fix("Fix, push, CI again") --> gate
-    gate -.->|"risk or protected"| human(("Human review"))
+    merged -->|"next PR"| train
+    gate -.->|"CI failed or conflict"| fix("Fix, push, CI again") --> ci
+    gate -.->|".github, secrets<br/>or 1000+ lines"| human(("Human review"))
     review("Someone reviews the PR") --> applyReview("apply-review") --> ci
     audit("audit, weekly") -->|"files one issue"| refine
 
@@ -99,9 +103,9 @@ flowchart LR
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
-    class open,write,review,audit start
-    class refine,split,implement,ci,fix,applyReview,author action
-    class triage,gate decision
+    class open,write,review,audit,person start
+    class refine,split,implement,ci,fix,applyReview,author,update action
+    class triage,gate,train decision
     class human,closed failure
     class merged success
 ```
@@ -110,6 +114,44 @@ Audit creates work rather than consuming it, and files into `refine` rather than
 `implement`, so a report of several unrelated findings becomes one properly sized issue per finding
 instead of one pull request that has to fix them all.
 
+### The merge train
+
+One pull request moves at a time, the lowest number first, whoever opened it. Everything else waits
+untouched, so a merge never invalidates work in flight. A pull request a person has to decide on is
+passed by, so it never blocks the line. The train ticks on every merge, every CI completion, after
+every gate, and hourly as the fallback.
+
+```mermaid
+flowchart TD
+    trainTick("A merge, a CI verdict,<br/>a finished gate, or the hour") --> trainLive
+    trainLive{"A gate already<br/>on the belt?"}
+    trainLive -.->|yes| trainWait
+    trainLive -->|no| trainNext
+    trainNext{"Oldest open PR from this repo,<br/>bot or writer, not draft,<br/>no hold label"}
+    trainNext -.->|"none left"| trainIdle
+    trainNext --> trainPark
+    trainPark{"Parked on this head?<br/>owner or human review,<br/>blocked with main unmoved,<br/>attempts spent"}
+    trainPark -.->|"yes: pass it by"| trainNext
+    trainPark -->|no| trainCi
+    trainCi{"Its CI"}
+    trainCi -.->|running| trainWait
+    trainCi -->|"green, behind main"| trainUpdate
+    trainCi -->|"red, conflicting,<br/>or green and current"| trainGate
+    trainUpdate(("Merge main in<br/>CI reruns on what it<br/>will land on"))
+    trainGate(("Dispatch the gate<br/>repair or squash-merge"))
+    trainWait(("Wait<br/>the next tick looks again"))
+    trainIdle(("Idle<br/>the train is empty"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class trainTick start
+    class trainLive,trainNext,trainPark,trainCi decision
+    class trainWait,trainIdle idle
+    class trainUpdate,trainGate success
+```
+
 ### How a feature stacks
 
 When refine splits a story that carries real sequencing — a feature whose children build on each
@@ -319,8 +361,8 @@ overnight pull requests mean every merge moves the default branch under the rest
 
 ```mermaid
 flowchart TD
-    gateStart("Work Router<br/>merge-gate route<br/>CI reported, or the hourly<br/>reconcile belt dispatched it") --> gateSubject
-    gateSubject{"subject (rung 4)<br/>Our open PR?<br/>Closes an implement issue?"}
+    gateStart("Work Router<br/>merge-gate route<br/>the merge train dispatched it,<br/>oldest PR first") --> gateSubject
+    gateSubject{"subject (rung 4)<br/>Open PR from this repo,<br/>by the bot or a writer?"}
     gateSubject -.->|no| gateIdle
     gateSubject -->|yes| gateBranch
     gateBranch("Check out the PR branch<br/>the push is fast-forward only,<br/>so never rebase") --> gateFacts
@@ -332,14 +374,14 @@ flowchart TD
     gatePush(("Pushed<br/>CI runs again, gate re-enters"))
     gateFix -.->|"cannot fix"| gateHuman
     gateProtected{"protected_changes (rung 4b)<br/>blast radius from paths, CODEOWNERS<br/>and the size of the code that ships"}
-    gateProtected -.->|"protected path"| gateOwner
+    gateProtected -.->|".github/ path"| gateOwner
     gateProtected -->|"measured low, medium or high"| gateAssess
     gateAssess("Agent (rung 5)<br/>find defects, verify them,<br/>rate recoverability") --> gateDisposition
     gateDisposition{"Disposition<br/>computed in shell from<br/>the facts and the report"}
     gateDisposition -->|"no verified blocker,<br/>radius low or recoverable medium"| gateRootCheck
     gateRootCheck{"PR base is a<br/>stack feature branch<br/>and this PR is the root?"}
     gateRootCheck -->|"child PR: no"| gateMerge
-    gateDisposition -.->|"radius high, protected<br/>or owner path"| gateOwner
+    gateDisposition -.->|"1000+ lines, .github/<br/>or a secret"| gateOwner
     gateDisposition -.->|"fragile, unmet criteria<br/>or low confidence"| gateHuman
     gateDisposition -.->|"CI red or a verified<br/>high finding"| gateBlocked
     gateMerge(("AUTO-MERGE<br/>squash into the PR's base<br/>(main, or the feature branch:<br/>then the child issue closes,<br/>pr-pending removed)"))
@@ -350,8 +392,8 @@ flowchart TD
     gateOwner --> gatePreview
     gatePreview("operation=evidence<br/>screenshots of the head<br/>before the person decides") --> gateApproved
     gateApproved(("Approved by a writer<br/>merge-approved merges<br/>the approved commit"))
-    gateBlocked(("BLOCKED<br/>review + blocked,<br/>the belt does not retry"))
-    gateIdle(("Idle<br/>not ours, or not open"))
+    gateBlocked(("BLOCKED<br/>review + blocked, the train<br/>retries it when main moves"))
+    gateIdle(("Idle<br/>a fork, a stranger,<br/>or not open"))
     gateFix -.->|"attempt 6 of 6"| gateBlocked
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033

package/loops/templates/ci/app-ci-dotnet-next.yml

@@ -280,32 +280,31 @@ jobs:
           # needs contents: write this workflow does not have, and fails the run that gates deploy.
           upload-release-assets: false
 
-  # A bot pull request is opened with GITHUB_TOKEN, and GitHub delivers no workflow_run event
-  # for the CI runs that follow (the run's actor is the bot). The router's CI-completion route
-  # never sees them, so this job hands the verdict over from inside CI. workflow_dispatch is
-  # one of the two events GITHUB_TOKEN may raise, so no App token is needed here, and the
-  # router treats a dispatch as trusted. Human pull requests are left to the workflow_run
-  # route, which does fire for them. The reconcile belt remains the hourly fallback.
+  # Hands this run's verdict to the router's merge train, which decides whether this pull request
+  # is the one in front and what it needs. A pull request opened or updated with a bot token gets
+  # no workflow_run event for its CI (the run's actor is the bot), and the train brings people's
+  # pull requests up to date with one too, so every pull request on this repository hands over
+  # from here. workflow_dispatch is one of the two events GITHUB_TOKEN may raise, so no App token
+  # is needed, and the router treats a dispatch as trusted. The hourly schedule is the fallback.
   #
   # If a deploy pipeline calls this workflow with `uses:`, that caller must also grant
   # `actions: write`. A called workflow may not request a scope its caller withheld, and the
   # whole run fails to start with zero jobs and no annotation when it does.
-  dispatch-merge-gate:
-    name: Dispatch merge gate
+  dispatch-merge-train:
+    name: Dispatch merge train
     needs: [api, mutation-api, web, mutation-web]
     if: >
       always() &&
       github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.pull_request.draft == false &&
-      github.event.pull_request.user.type == 'Bot'
+      github.event.pull_request.draft == false
     runs-on: agents-arc
     timeout-minutes: 5
     permissions:
       contents: read
       actions: write
     steps:
-      - name: Dispatch the merge gate with this run's verdict
+      - name: Hand this run's verdict to the merge train
         env:
           GH_TOKEN: ${{ github.token }}
           REPO: ${{ github.repository }}
@@ -324,10 +323,10 @@ jobs:
           done
           # A cancelled run was superseded by a newer push, whose own run dispatches.
           if [ "$conclusion" = cancelled ]; then
-            echo "CI was cancelled; not dispatching the merge gate."
+            echo "CI was cancelled; not moving the merge train."
             exit 0
           fi
-          echo "Dispatching the merge gate for PR #$PR_NUMBER with CI $conclusion (run $RUN_ID)."
+          echo "Moving the merge train for PR #$PR_NUMBER with CI $conclusion (run $RUN_ID)."
           gh workflow run work-router.yml --repo "$REPO" --ref "$REF" \
-            -f operation=merge-gate -f pr-number="$PR_NUMBER" \
+            -f operation=merge-train -f pr-number="$PR_NUMBER" \
             -f ci-conclusion="$conclusion" -f ci-run-id="$RUN_ID"

package/loops/templates/ci/app-ci-node-monorepo.yml

@@ -210,32 +210,31 @@ jobs:
           # needs contents: write this workflow does not have, and fails the run that gates deploy.
           upload-release-assets: false
 
-  # A bot pull request is opened with GITHUB_TOKEN, and GitHub delivers no workflow_run event
-  # for the CI runs that follow (the run's actor is the bot). The router's CI-completion route
-  # never sees them, so this job hands the verdict over from inside CI. workflow_dispatch is
-  # one of the two events GITHUB_TOKEN may raise, so no App token is needed here, and the
-  # router treats a dispatch as trusted. Human pull requests are left to the workflow_run
-  # route, which does fire for them. The reconcile belt remains the hourly fallback.
+  # Hands this run's verdict to the router's merge train, which decides whether this pull request
+  # is the one in front and what it needs. A pull request opened or updated with a bot token gets
+  # no workflow_run event for its CI (the run's actor is the bot), and the train brings people's
+  # pull requests up to date with one too, so every pull request on this repository hands over
+  # from here. workflow_dispatch is one of the two events GITHUB_TOKEN may raise, so no App token
+  # is needed, and the router treats a dispatch as trusted. The hourly schedule is the fallback.
   #
   # If a deploy pipeline calls this workflow with `uses:`, that caller must also grant
   # `actions: write`. A called workflow may not request a scope its caller withheld, and the
   # whole run fails to start with zero jobs and no annotation when it does.
-  dispatch-merge-gate:
-    name: Dispatch merge gate
+  dispatch-merge-train:
+    name: Dispatch merge train
     needs: [lint, web, mutation-web, e2e, desktop, mobile]
     if: >
       always() &&
       github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.pull_request.draft == false &&
-      github.event.pull_request.user.type == 'Bot'
+      github.event.pull_request.draft == false
     runs-on: agents-arc
     timeout-minutes: 5
     permissions:
       contents: read
       actions: write
     steps:
-      - name: Dispatch the merge gate with this run's verdict
+      - name: Hand this run's verdict to the merge train
         env:
           GH_TOKEN: ${{ github.token }}
           REPO: ${{ github.repository }}
@@ -254,10 +253,10 @@ jobs:
           done
           # A cancelled run was superseded by a newer push, whose own run dispatches.
           if [ "$conclusion" = cancelled ]; then
-            echo "CI was cancelled; not dispatching the merge gate."
+            echo "CI was cancelled; not moving the merge train."
             exit 0
           fi
-          echo "Dispatching the merge gate for PR #$PR_NUMBER with CI $conclusion (run $RUN_ID)."
+          echo "Moving the merge train for PR #$PR_NUMBER with CI $conclusion (run $RUN_ID)."
           gh workflow run work-router.yml --repo "$REPO" --ref "$REF" \
-            -f operation=merge-gate -f pr-number="$PR_NUMBER" \
+            -f operation=merge-train -f pr-number="$PR_NUMBER" \
             -f ci-conclusion="$conclusion" -f ci-run-id="$RUN_ID"