@plainconceptsplatform/workflows 1.5.0 → 1.6.10

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
@@ -490,6 +493,14 @@ if [ "$BELT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 # trailing space, so a number at the end of a body is still followed by a non-digit, and the
 # pattern matches `[^0-9]`. Four quoting layers cannot eat a character class.
 SWEEP_OK=1
+# The live runs come from status-filtered queries. Reading the repository's latest hundred runs of
+# any kind let a long-queued implement fall out of the window, and the sweep cleared bot-working
+# from issues whose runs were alive (Pliny-Bot #693 and #707).
+if grep -q 'gh api "repos/\$REPO/actions/runs?per_page=100"' "$ROUTER_YML" ||
+  ! grep -qF 'actions/runs?status=$status&per_page=100' "$ROUTER_YML"; then
+  SWEEP_OK=0
+  echo "FAIL: the stale-reservation sweep must read live runs by status, not the latest hundred runs" >&2
+fi
 if ! grep -qF 'test(\"#${issue}[^0-9]\")' "$ROUTER_YML"; then
   SWEEP_OK=0
   echo "FAIL: the stale-reservation sweep does not match a run title with a character class; a word boundary there is eaten by bash and jq" >&2
@@ -685,69 +696,90 @@ if worker_installed merge-gate; then
   # The merge belt is serial for the whole repository: several overnight pull requests
   # mean every merge moves the default branch under the rest, and gates running at once
   # rebase onto bases other gates are about to invalidate. A per-issue group here would
-  # reintroduce that race, so assert the repo-wide lock is the one in use.
-  if grep -A7 'call-merge-gate:' "$ROUTER_YML" | grep -q 'group: merge-belt'; then
+  # reintroduce that race, so assert the repo-wide lock is the one in use. The exception is a gate
+  # handed red CI: it repairs and pushes and can never merge, so it queues per pull request.
+  gate_group="$(sed -n '/^  call-merge-gate:/,/^    permissions:/p' "$ROUTER_YML" | grep 'group:')"
+  if grep -q "'merge-belt'" <<<"$gate_group" &&
+    grep -q "ci-conclusion == 'failure' && format('merge-repair-{0}', needs.classify.outputs.pr-number)" <<<"$gate_group"; then
     PASS=$((PASS + 1))
   else
     FAIL=$((FAIL + 1))
-    echo "FAIL: call-merge-gate must hold the repo-wide merge-belt lock" >&2
+    echo "FAIL: call-merge-gate must queue on merge-belt, and only a gate handed red CI may queue per pull request instead" >&2
   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}'.*/\1/p" "$ROUTER_YML" | head -1)"
+    grep -q "' (repair)'" "$ROUTER_YML" ||
+      { BELT_OK=0; echo "FAIL: run-name must mark a gate handed red CI as a (repair), the train counts them by it" >&2; }
+    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 +1142,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
@@ -1752,19 +1784,165 @@ if [ -f "$GATE_VALIDATOR" ] && worker_installed merge-gate; then
   if [ "$VALIDATOR_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+# The gate takes any pull request the train hands it. A subject check that refuses one without
+# leaving a verdict or an attempt is a loop: the train cannot tell a gate that declined from a gate
+# that has not run. Refusals are for what the train never hands over (a fork, a stranger, a pull
+# request that is not open), and the train filters those itself.
+if worker_installed merge-gate; then
+  # check-diff exiting 1 is the `fail` the code_rules job reports. Under GitHub's `bash -e` a bare
+  # assignment from it ends the step, so the report is never recorded and the gate burns its
+  # budget on a failure it could have repaired.
+  if grep -qF 'check-diff.mjs --base "$BASE" 2>&1) || code=$?' "$MERGE_GATE_WORKER_MD"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: code_rules must capture check-diff's exit code with || code=\$?; a bare assignment dies under bash -e" >&2
+  fi
+  # A run killed by its infrastructure is repeated whatever its duration; one the agent got wrong is
+  # not. The two signatures are read from places a tool's output cannot write: GitHub's annotations
+  # for the runner shutdown, and the line above the sandbox teardown for an engine cut off one turn
+  # after it asked the model something (Pliny-Bot #699 and #693's first attempt).
+  CLASSIFY="${HERE}/../decide-agent-retry/classify-failure.sh"
+  if [ -f "$CLASSIFY" ]; then
+    ctmp="$(mktemp -d)"
+    printf '%s
+' '2026-10-16T22:13:03Z > ci-workflow-agent · glm-5-2' '2026-10-16T22:13:05Z the grep printed a line' '2026-10-16T22:13:36Z > ci-workflow-agent · glm-5-2' '2026-10-16T22:13:37Z [INFO] Stopping containers...' >"$ctmp/cutoff.log"
+    printf '%s
+' '2026-10-16T22:13:03Z > ci-workflow-agent · glm-5-2' '2026-10-16T22:13:36Z Done. The pull request is ready.' '2026-10-16T22:13:37Z [INFO] Stopping containers...' >"$ctmp/done.log"
+    printf '%s
+' '2026-10-16T22:13:03Z the log quotes: Process completed with exit code 143 and The runner has received a shutdown signal' '2026-10-16T22:13:04Z Done.' '2026-10-16T22:13:37Z [INFO] Stopping containers...' >"$ctmp/quoted.log"
+    printf '%s
+' 'Process completed with exit code 143.' 'Property x does not exist' >"$ctmp/sigterm.ann"
+    printf '%s
+' 'Process completed with exit code 137.' >"$ctmp/sigkill.ann"
+    printf '%s
+' 'Process completed with exit code 1.' >"$ctmp/plain.ann"
+    assert "an engine stopped one turn after its request is a cut-off" cut-off "$(bash "$CLASSIFY" "$ctmp/cutoff.log" "")"
+    assert "a run that said its piece is not a cut-off" none "$(bash "$CLASSIFY" "$ctmp/done.log" "")"
+    assert "a tool quoting the shutdown text does not count" none "$(bash "$CLASSIFY" "$ctmp/quoted.log" "")"
+    assert "exit 143 in the annotations is a runner shutdown" runner-shutdown "$(bash "$CLASSIFY" "$ctmp/done.log" "$ctmp/sigterm.ann")"
+    assert "exit 137 (an out-of-memory kill) is repeated by nobody" none "$(bash "$CLASSIFY" "$ctmp/done.log" "$ctmp/sigkill.ann")"
+    assert "an ordinary failure is not infrastructure" none "$(bash "$CLASSIFY" "$ctmp/done.log" "$ctmp/plain.ann")"
+    assert "nothing to read classifies as nothing" none "$(bash "$CLASSIFY" "" "")"
+    rm -rf "$ctmp"
+  fi
+  # The implement worker carried its own copy of the retry rule while four other workers used the
+  # shared action, so a rule fixed in one place stayed broken in the other.
+  IMPLEMENT_MD="${WORKFLOWS_DIR}/agent-implement.md"
+  if [ -f "$IMPLEMENT_MD" ]; then
+    uses=$(count -c "uses: ./.github/actions/decide-agent-retry" "$IMPLEMENT_MD")
+    if [ "$uses" -ge 2 ] && ! grep -q 'minutes=$(( ( $(date -u -d "$finished"' "$IMPLEMENT_MD"; then
+      PASS=$((PASS + 1))
+    else
+      FAIL=$((FAIL + 1))
+      echo "FAIL: agent-implement.md must decide a retry through the shared decide-agent-retry action, in both incomplete and conclude" >&2
+    fi
+  fi
+  # Implement runs spread over IMPLEMENT_PARALLELISM queues, but the children of one refine share
+  # a queue keyed on their split parent: they build on each other's code. The queue step's
+  # arithmetic is exercised with the same expression the router runs.
+  if grep -q 'group: implement-queue-${{ needs.check-stack-branch.outputs.implement-queue' "$ROUTER_YML" &&
+    sed -n '/- name: Pick the implement queue/,/- name: Resolve the feature branch/p' "$ROUTER_YML" | grep -q 'key="${parent:-$ISSUE_NUMBER}"'; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: call-implement must queue on check-stack-branch's implement-queue, keyed on the split parent" >&2
+  fi
+  queue_for() { local parent="$1" issue="$2" queues="$3"; case "$queues" in ''|*[!0-9]*|0) queues=1 ;; esac; local key="${parent:-$issue}"; echo $(( key % queues )); }
+  assert "siblings of one refine share a queue" "$(queue_for 690 693 3)" "$(queue_for 690 694 3)"
+  assert "parallelism 1 is one queue for everything" 0 "$(queue_for "" 722 1)"
+  assert "an unset or garbled parallelism is one queue" 0 "$(queue_for "" 725 abc)"
+  assert "independent issues spread across the queues" 1 "$(queue_for "" 724 3)"
+  # The router queues implement runs FIFO, so a run waiting an hour behind the one in progress is
+  # healthy. The janitor cancelling every pending run over an hour old took every issue queued
+  # behind the first out of the queue and left it holding bot-working (Pliny-Bot #706, #644).
+  if [ -f "${HERE}/../housekeeping/action.yml" ] && ! grep -q "liveKinds" "${HERE}/../housekeeping/action.yml"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: the janitor cancels pending runs without checking for a live run of their own kind ahead of them" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+  # The implement worker names every phase skill it must load. Left as "load each phase skill",
+  # glm-5-2 loaded pc-plan-goal, wrote proposal.md and tasks.md itself and edited the code alone:
+  # a hand-written tasks.md has no <!-- agent --> annotations, so pc-plan-apply had no subagents
+  # to spawn and the whole change ran on one model, in sequence (Pliny-Bot #693, #699).
+  IMPL_MD="${WORKFLOWS_DIR}/agent-implement.md"
+  if [ -f "$IMPL_MD" ]; then
+    if grep -q 'You never write' "$IMPL_MD" && grep -q '`pc-plan-propose`, even when the issue is refined' "$IMPL_MD" &&
+      grep -q 'In this phase you do not edit source files' "$IMPL_MD" && grep -q '`pc-repo-verify`, then `pc-plan-archive`' "$IMPL_MD"; then
+      PASS=$((PASS + 1))
+    else
+      FAIL=$((FAIL + 1))
+      echo "FAIL: agent-implement.md must name pc-plan-propose, pc-plan-apply, pc-repo-verify and pc-plan-archive and forbid writing tasks.md by hand" >&2
+    fi
+  fi
+  # Refine writes in English and may retitle an issue written in another language; without
+  # allow_title on update-issue the title in the call is dropped and the issue keeps its language.
+  REFINE_MD="${WORKFLOWS_DIR}/agent-refine.md"
+  if [ -f "$REFINE_MD" ]; then
+    if sed -n '/^  update-issue:/,/^  add-comment:/p' "$REFINE_MD" | grep -q '^    title:' &&
+      grep -q 'Everything you write is in English' "$REFINE_MD"; then
+      PASS=$((PASS + 1))
+    else
+      FAIL=$((FAIL + 1))
+      echo "FAIL: agent-refine.md must write in English and be allowed to retitle an issue (update-issue title:)" >&2
+    fi
+  fi
+  # A token written to the runner's global git config outlives the job on a runner that is reused:
+  # rules for revoked tokens pile up for the same prefix and git picks one at random, so the same
+  # gate pushed for one pull request and was refused for the next (Pliny-Bot #716 and #717).
+  PUSH_ACTION="${HERE}/../push-agent-branch/action.yml"
+  if [ -f "$PUSH_ACTION" ] && grep -qE 'git config( --global)? url\.' "$PUSH_ACTION" && ! grep -qF 'git config --local url.' "$PUSH_ACTION"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: push-agent-branch writes its token to the global git config, where stale rules from earlier jobs accumulate" >&2
+  elif [ -f "$PUSH_ACTION" ] && grep -qE 'git config --global url\.' "$PUSH_ACTION"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: push-agent-branch adds to the global git config; set the rule with --local" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+  # A conclude that dies leaves no verdict and no attempt comment unless `incomplete` records it,
+  # and the train then reads the run as a gate that did nothing and never offers the pull request
+  # again.
+  if sed -n '/^  incomplete:/,/^    runs-on:/p' "$MERGE_GATE_WORKER_MD" | grep -q "needs.conclude.result == 'failure'"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: the gate's incomplete job must record a failed conclude as an attempt, or the train strands the pull request" >&2
+  fi
+  # A stack child is dispatched on its feature branch, and a dispatched run reads repository secrets
+  # by their own names, not through the router's FORGE_API_KEY mapping. Without the fallback every
+  # stack child died at activation on "Validate CODEX_API_KEY or OPENAI_API_KEY secret".
+  COMPILE_SCRIPT="${HERE}/../../scripts/compile-agent-workflows.mjs"
+  if [ -f "$COMPILE_SCRIPT" ] && ! grep -qF "secrets.OPENAI_API_KEY || secrets.FORGE_API_KEY" "$COMPILE_SCRIPT"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: the compile script no longer gives the engine key a FORGE_API_KEY fallback; dispatched stack children cannot start" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+  SUBJECT_YML="${HERE}/../identify-gate-subject/action.yml"
+  if grep -qE 'does not close a numbered issue|does not carry' "$SUBJECT_YML" || grep -q 'require-label' "$SUBJECT_YML" "$MERGE_GATE_WORKER_MD"; then
+    FAIL=$((FAIL + 1))
+    echo "FAIL: the gate's subject job refuses a pull request for lacking an issue or a label; the train hands it back forever" >&2
+  else
+    PASS=$((PASS + 1))
+  fi
+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 +1950,41 @@ 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)"
+    # The loop that ran Pliny-Bot's gate twenty times on one pull request: the gate declined it
+    # (its issue was closed), left no verdict and no attempt, and every tick handed it back.
+    assert "a gate that ran and left no trace is not asked again" skip "$(move SILENT_GATE=true MERGEABLE=CONFLICTING CI_STATUS=none)"
+    assert "a gate that ran and left no trace is not asked again, green or red" skip "$(move SILENT_GATE=true MERGEABLE=MERGEABLE 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,13 +2724,13 @@ 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")
 printf '%s
-' "$belt_caller" | grep -qE '^ *group: merge-belt *$' ||
+' "$belt_caller" | grep -qE "^ *group: .*'merge-belt'" ||
   { BELT_QUEUE_OK=0; echo "FAIL: the merge gate is no longer serialised on the merge-belt concurrency group" >&2; }
 printf '%s
 ' "$belt_caller" | grep -qE '^ *queue: max *$' ||
@@ -2573,7 +2779,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 10000+ 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 -.->|"10000+ 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