@plainconceptsplatform/workflows 1.5.0 → 1.6.0

package/dist/route-processing.js

@@ -10,7 +10,12 @@ const routeCrons = {
 const routeHelperJobs = {
     implement: ["check-implement-pr"],
     triage: ["dispatch-triage"],
-    "merge-gate": ["merge-approved"],
+    "merge-gate": ["merge-approved", "merge-train"],
+};
+// Dispatch operations that exist only to serve one worker route. A router without the worker
+// would offer an operation no job answers, which the route matrix reports.
+const routeHelperOperations = {
+    "merge-gate": ["merge-train"],
 };
 export function stripRouteFromRouter(yaml, route) {
     let result = yaml;
@@ -21,7 +26,9 @@ export function stripRouteFromRouter(yaml, route) {
     for (const job of [`call-${route}`, ...(routeHelperJobs[route] ?? [])]) {
         result = removeJobBlock(result, job);
     }
-    result = result.replace(new RegExp(`^          - ${escapeRegex(route)}\\n`, "gm"), "");
+    for (const operation of [route, ...(routeHelperOperations[route] ?? [])]) {
+        result = result.replace(new RegExp(`^          - ${escapeRegex(operation)}\\n`, "gm"), "");
+    }
     return result;
 }
 export function processRoutes(files, selectedRoutes) {

package/dist/workflow-catalog.js

@@ -12,7 +12,7 @@ export const workflowRoutes = [
     { name: "implement", worker: "agent-implement.md", description: "Implements an issue and opens a pull request. Stops there: the merge decision belongs to the merge gate.", defaultEnabled: true },
     { name: "triage", worker: "agent-triage.md", description: "Triages issues opened from outside the organisation: runs 10 checks (template, security, size, danger, duplicates, clarity, reproducibility, acceptance, cross-cutting, product scope). Loops up to 3 rounds. Passes to refine, asks the author for more, parks out-of-scope work open for a maintainer, or closes what is genuinely rejected.", defaultEnabled: true },
     { name: "apply-review", worker: "agent-apply-review.md", description: "Applies reviewer feedback to an open pull request the bot authored, then pushes the fixes to the same branch.", defaultEnabled: true },
-    { name: "merge-gate", worker: "agent-merge-gate.md", description: "Decides what happens to a bot-authored pull request once CI has reported: merge, hand to a human, or fix CI.", defaultEnabled: true },
+    { name: "merge-gate", worker: "agent-merge-gate.md", description: "Decides what happens to the pull request the merge train hands it, the bot's or a person's: repair it, merge it, or hand it to a human.", defaultEnabled: true },
     { name: "audit", worker: "agent-audit.md", description: "Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a single issue that Refine then sizes and splits.", defaultEnabled: true },
     { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job opens a version-bump pull request with auto-merge; once it merges, release-tag.yml tags the commit and publishes the GitHub Release. Manual dispatch only (operation=release).", defaultEnabled: true, companions: ["release-tag.yml"] },
 ];

package/loops/actions/apply-agent-output/action.yml

@@ -19,6 +19,10 @@ inputs:
     description: Apply push_to_pull_request_branch items.
     required: false
     default: 'false'
+  expected-branch:
+    description: The only branch a push may target. A push naming any other branch is refused. Empty accepts the branch the item names.
+    required: false
+    default: ''
   close-issues:
     description: Apply close_issue items.
     required: false
@@ -73,6 +77,7 @@ runs:
         output-file: ${{ steps.output.outputs.output-file }}
         bundle-file: ${{ steps.output.outputs.bundle-file }}
         token: ${{ inputs.token }}
+        expected-branch: ${{ inputs.expected-branch }}
 
     - name: Close issues
       if: inputs.close-issues == 'true' && steps.output.outputs.item-count != '0'

package/loops/actions/classify-route/classify-route.sh

@@ -156,9 +156,9 @@ classify_route() {
         ci_run_id=""
       elif [ "${ACTION:-}" = "closed" ] && [ "${PR_MERGED:-false}" = "true" ]; then
         # A merge is when the change's verification plan describes what the default branch now
-        # does, so the evidence run replays it then. detect-pr-conflicts reacts to this same
-        # event as its own event-gated job, not as a route, so taking the route here costs it
-        # nothing.
+        # does, so the evidence run replays it then. The merge train and land-stack-child react
+        # to this same event as event-gated jobs, not as routes, so taking the route here costs
+        # them nothing.
         if [ "${EVIDENCE_ENABLED:-true}" = "true" ]; then
           route="evidence"
           pr_number="${EVENT_PR_NUMBER:-}"
@@ -171,17 +171,17 @@ classify_route() {
       ;;
 
     workflow_run)
-      # Only a FAILED CI run on an attached pull request auto-dispatches the gate. A green
-      # run reaches the gate through the consumer CI's dispatch-merge-gate job and the
-      # reconcile belt, so routing success here would double-fire the gate for every passing
-      # pull request. GitHub delivers workflow_run only for CI runs whose actor is a human;
-      # a bot pull request's CI never arrives here at all, and the same two paths cover it.
-      if [ "${RUN_CONCLUSION:-}" != "failure" ]; then
-        error="CI concluded '${RUN_CONCLUSION:-}'; the gate auto-triggers only on failure"
+      # A CI verdict on a pull request moves the merge train, green or red. The train, not this
+      # event, decides which pull request the gate takes next: dispatching the gate for this one
+      # directly is what let a night of pull requests race each other for the default branch.
+      # GitHub delivers workflow_run only for CI runs whose actor is a human; a bot-updated pull
+      # request's CI reaches the train through the consumer CI's dispatch job and the schedule.
+      if [ "${RUN_CONCLUSION:-}" != "failure" ] && [ "${RUN_CONCLUSION:-}" != "success" ]; then
+        error="CI concluded '${RUN_CONCLUSION:-}'; only a success or a failure moves the merge train"
       elif is_issue_number "${RUN_PR_NUMBER:-}"; then
-        route="merge-gate"
+        route="merge-train"
         pr_number="${RUN_PR_NUMBER}"
-        ci_conclusion="failure"
+        ci_conclusion="${RUN_CONCLUSION}"
         ci_run_id="${RUN_ID:-}"
       else
         error="CI run has no attached pull request"
@@ -237,7 +237,17 @@ classify_route() {
           fi
           ;;
         merge-gate)
-          if is_issue_number "${INPUT_PR_NUMBER:-}"; then
+          # A consumer CI hands its verdict over with GITHUB_TOKEN, whose dispatches carry
+          # github-actions[bot] as the actor; the train and a person dispatch with other
+          # identities. That handover is a CI completion, so it moves the train rather than
+          # jumping the queue. The CI templates now dispatch merge-train; this keeps a consumer
+          # CI that still dispatches merge-gate in line until it is updated.
+          if is_issue_number "${INPUT_PR_NUMBER:-}" && [ "${ACTOR:-}" = "github-actions[bot]" ]; then
+            route="merge-train"
+            pr_number="${INPUT_PR_NUMBER}"
+            ci_conclusion="${INPUT_CI_CONCLUSION:-}"
+            ci_run_id="${INPUT_CI_RUN_ID:-}"
+          elif is_issue_number "${INPUT_PR_NUMBER:-}"; then
             route="merge-gate"
             pr_number="${INPUT_PR_NUMBER}"
             ci_conclusion="${INPUT_CI_CONCLUSION:-}"
@@ -260,6 +270,17 @@ classify_route() {
           route="${OPERATION}"
           trigger_kind="${INPUT_TRIGGER_KIND:-manual}"
           ;;
+        merge-train)
+          # The train always takes the oldest pull request that can move. A CI handover names its
+          # pull request and verdict because it runs inside that CI run, which still reads as in
+          # progress when the train looks; the verdict stands in for the run's own conclusion.
+          route="merge-train"
+          if is_issue_number "${INPUT_PR_NUMBER:-}"; then
+            pr_number="${INPUT_PR_NUMBER}"
+            ci_conclusion="${INPUT_CI_CONCLUSION:-}"
+            ci_run_id="${INPUT_CI_RUN_ID:-}"
+          fi
+          ;;
         audit-close | cleanup-artifacts | reconcile-bot-pr-runs | housekeeping | validate)
           route="${OPERATION}"
           ;;

package/loops/actions/identify-gate-subject/action.yml

@@ -1,10 +1,14 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/actions/identify-gate-subject/action.yml. Update with workflows update --force; consumer edits may be overwritten.
 name: Identify gate subject
-description: Confirm the pull request is one we authored, resolve the issue it closes, and check that issue carries the required label.
+description: Confirm the pull request is one the gate may act on, resolve the issue it closes, and check a bot pull request's issue carries the required label.
 inputs:
   token:
     description: GitHub token with issues and pull-requests read access.
     required: true
+  trusted-bots:
+    description: Space-separated bot logins whose pull requests the gate gates. Anyone else needs write access.
+    required: false
+    default: ''
   pr-number:
     description: Pull request number to gate.
     required: true
@@ -21,7 +25,7 @@ inputs:
     required: false
     default: ''
   require-label:
-    description: Label the closing issue must carry. Empty disables the check.
+    description: Label a bot pull request's closing issue must carry. Empty disables the check. A person's pull request needs neither an issue nor the label.
     required: false
     default: ''
 outputs:
@@ -32,8 +36,17 @@ outputs:
     description: Pull request number.
     value: ${{ steps.identify.outputs.pr }}
   issue:
-    description: Issue number the pull request closes.
+    description: Issue number the pull request closes. Empty for a person's pull request that closes none.
     value: ${{ steps.identify.outputs.issue }}
+  record:
+    description: Where the gate writes its verdict and labels. The issue when there is one, otherwise the pull request.
+    value: ${{ steps.identify.outputs.record }}
+  head-ref:
+    description: The pull request's head branch, the only branch the gate may push to.
+    value: ${{ steps.identify.outputs.head-ref }}
+  closes:
+    description: "What the pull request closes, as the prompt says it: `closes issue #N` or `closes no issue`. gh-aw allows no expression logic in a prompt."
+    value: ${{ steps.identify.outputs.closes }}
   conclusion:
     description: CI conclusion, passed through unchanged or fetched from latest CI run.
     value: ${{ steps.identify.outputs.conclusion }}
@@ -54,6 +67,7 @@ runs:
         CI_RUN_ID: ${{ inputs.ci-run-id }}
         LINKED_ISSUE: ${{ inputs.linked-issue }}
         REQUIRE_LABEL: ${{ inputs.require-label }}
+        TRUSTED_BOTS: ${{ inputs.trusted-bots }}
       run: |
         set -euo pipefail
 
@@ -64,10 +78,31 @@ runs:
         }
 
         pr="$(gh pr view "$PR_NUMBER" --repo "$REPO" \
-          --json state,author,closingIssuesReferences,body)"
+          --json state,author,closingIssuesReferences,body,isCrossRepository,headRefName)"
 
         [ "$(jq -r '.state' <<<"$pr")" = "OPEN" ] || none "PR #$PR_NUMBER is not open"
 
+        # The gate checks out the branch, runs the repository's commands on it and pushes to it,
+        # with secrets. A fork's branch is someone else's code: never.
+        [ "$(jq -r '.isCrossRepository' <<<"$pr")" = "false" ] || none "PR #$PR_NUMBER comes from a fork"
+
+        # A bot this repository trusts, or a person with write access, who could push the same
+        # branch themselves. GraphQL spells a GitHub App `app/<name>`, REST `<name>[bot]`.
+        author="$(jq -r '.author.login' <<<"$pr")"
+        bot=false
+        if [ "$(jq -r '.author.is_bot // false' <<<"$pr")" = "true" ]; then
+          for candidate in "$author" "${author#app/}[bot]"; do
+            case " $TRUSTED_BOTS " in *" $candidate "*) bot=true ;; esac
+          done
+          [ "$bot" = true ] || none "PR #$PR_NUMBER was opened by $author, a bot this repository does not trust"
+        else
+          permission="$(gh api "repos/$REPO/collaborators/$author/permission" --jq '.permission' 2>/dev/null || echo none)"
+          case "$permission" in
+            admin | maintain | write) ;;
+            *) none "PR #$PR_NUMBER was opened by $author, who has $permission access" ;;
+          esac
+        fi
+
         issue="$LINKED_ISSUE"
 
         if [ -z "$issue" ]; then
@@ -80,9 +115,14 @@ runs:
             grep -oE '[0-9]+' | head -n 1 || true)"
         fi
 
-        [ -n "$issue" ] || none "PR #$PR_NUMBER does not close a numbered issue"
+        # The bot only opens a pull request for an issue it was given, so one that closes none, or
+        # whose issue lost the label, is not work the gate was handed. A person's pull request is
+        # gated on its own description when it closes nothing.
+        if [ "$bot" = true ]; then
+          [ -n "$issue" ] || none "PR #$PR_NUMBER does not close a numbered issue"
+        fi
 
-        if [ -n "$REQUIRE_LABEL" ]; then
+        if [ "$bot" = true ] && [ -n "$REQUIRE_LABEL" ]; then
           labels="$(gh issue view "$issue" --repo "$REPO" --json labels \
             --jq '[.labels[].name]')"
 
@@ -122,8 +162,11 @@ runs:
           echo "found=true"
           echo "pr=$PR_NUMBER"
           echo "issue=$issue"
+          echo "record=${issue:-$PR_NUMBER}"
+          echo "head-ref=$(jq -r '.headRefName' <<<"$pr")"
+          if [ -n "$issue" ]; then echo "closes=closes issue #$issue"; else echo "closes=closes no issue"; fi
           echo "conclusion=$ci_conclusion"
           echo "run-id=$ci_run_id"
         } >> "$GITHUB_OUTPUT"
 
-        echo "PR #$PR_NUMBER closes #$issue; CI concluded $ci_conclusion"
+        echo "PR #$PR_NUMBER by $author closes #${issue:-nothing}; CI concluded $ci_conclusion"

package/loops/actions/merge-train/action.yml

@@ -0,0 +1,66 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/merge-train/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Merge train
+description: >-
+  Move the oldest open pull request that can move one step towards merging (update it from its
+  base, hand it to the merge gate, or approve its CI), and leave every other one alone.
+  Deterministic: no model runs here.
+
+inputs:
+  token:
+    description: App token. Its dispatches and branch updates must start workflows, which GITHUB_TOKEN's do not.
+    required: true
+  ci-workflow-name:
+    description: The CI workflow whose verdict the train reads.
+    required: true
+  trusted-bots:
+    description: Space-separated bot logins whose pull requests ride the train and whose CI runs it approves.
+    required: false
+    default: ''
+  hold-label:
+    description: A pull request carrying this label stays off the train.
+    required: false
+    default: hold
+  max-gate-attempts:
+    description: Failed gate attempts on one head before the train stops dispatching it.
+    required: false
+    default: '6'
+  max-retries:
+    description: How many times a blocked verdict, or a merge that did not happen, is retried after the base branch moves.
+    required: false
+    default: '3'
+  stuck-hours:
+    description: How long the train waits behind a CI run that never finishes before it passes that pull request by.
+    required: false
+    default: '3'
+  dry-run:
+    description: Decide and report the move without making it.
+    required: false
+    default: 'false'
+  ci-run-id:
+    description: A CI run that handed its verdict over from inside itself, and so still reads as in progress.
+    required: false
+    default: ''
+  ci-conclusion:
+    description: That run's verdict, success or failure, which stands in for its conclusion.
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Move the train
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        CI_WORKFLOW_NAME: ${{ inputs.ci-workflow-name }}
+        TRUSTED_BOTS: ${{ inputs.trusted-bots }}
+        HOLD_LABEL: ${{ inputs.hold-label }}
+        MAX_ATTEMPTS: ${{ inputs.max-gate-attempts }}
+        MAX_RETRIES: ${{ inputs.max-retries }}
+        STUCK_HOURS: ${{ inputs.stuck-hours }}
+        DRY_RUN: ${{ inputs.dry-run }}
+        HINT_RUN_ID: ${{ inputs.ci-run-id }}
+        HINT_CONCLUSION: ${{ inputs.ci-conclusion }}
+      run: bash "${GITHUB_ACTION_PATH}/merge-train.sh"