feat(release-gate): gate main every 8 hours and feed the stable release (inert until adopted)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

.github/workflows/evals-main-backstop.yml

@@ -12,6 +12,10 @@ name: Main backstop gate
 # (success when a green train covers the tree or the backstop gated it green,
 # neutral when the push was superseded or deferred, failure when it froze the
 # queue or could not finish); the stable release reads it (docs/releases.md).
+#
+# Once main's policy declares a `release_gate` block, the release gate
+# (release-gate.yml, every 8 hours) gates main instead and this backstop stands
+# down: no gate, no freeze and no check run on a push.
 on:
   push:
     branches: [main]
@@ -60,9 +64,13 @@ jobs:
             done
           fi
           train=$(jq -c 'if (.train | type) == "object" then .train else null end' <<<"$policy") || { echo "::error::${GITHUB_SHA}:.gstack/ship-policy.json is not valid JSON; fix the policy file" >&2; exit 1; }
+          release=$(jq -r 'if (.release_gate | type) == "object" then "true" else "false" end' <<<"$policy")
           if [ -z "$train" ] || [ "$train" = null ]; then
             echo "train=false" >> "$GITHUB_OUTPUT"
             echo "- Backstop inert: main's .gstack/ship-policy.json declares no train block; per-PR gates cover main" >> "$GITHUB_STEP_SUMMARY"
+          elif [ "$release" = true ]; then
+            echo "train=false" >> "$GITHUB_OUTPUT"
+            echo "- Backstop stands down: main's .gstack/ship-policy.json declares a release_gate block; the scheduled release gate gates main (release-gate.yml, docs/ship-policy.md#release-gate)" >> "$GITHUB_STEP_SUMMARY"
           else
             echo "train=true" >> "$GITHUB_OUTPUT"
           fi

.github/workflows/evals.yml

@@ -166,7 +166,8 @@ jobs:
       pull-requests: read
     outputs:
       mode: ${{ steps.route.outputs.mode }}
-      record_artifact: ${{ steps.policy.outputs.record_artifact }}
+      # A release bisect (gstack-release-gate) names its own prefix-record artifact; everything else uses the train block's.
+      record_artifact: ${{ steps.route.outputs.record_artifact || steps.policy.outputs.record_artifact }}
       full_gate_check: ${{ steps.policy.outputs.full_gate_check }}
       screen_head: ${{ steps.screen.outputs.head_sha }}
       screen_base: ${{ steps.screen.outputs.base_sha }}
@@ -218,10 +219,23 @@ jobs:
             echo "::warning::the train block at ${base} names no valid record_artifact and full_gate_check; this run routes as before"
           fi
 
+      # The release gate's bisect (gstack-release-gate) routes only under a
+      # release_gate block at the same base revision; git and jq only.
+      - name: Read the release gate policy (base revision)
+        id: release_policy
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          policy=$(git show "${BASE_SHA:-origin/${DEFAULT_BRANCH}}:.gstack/ship-policy.json" 2>/dev/null || echo null)
+          release=$(jq -r 'if (.release_gate | type) == "object" then "true" else "false" end' <<<"$policy" 2>/dev/null || echo false)
+          echo "release=${release}" >> "$GITHUB_OUTPUT"
+
       - name: Route this run
         id: route
         env:
           TRAIN_POLICY: ${{ steps.policy.outputs.train }}
+          RELEASE_POLICY: ${{ steps.release_policy.outputs.release }}
           NONCE: ${{ inputs.nonce }}
           EXPECTED_SHA: ${{ inputs.expected_sha }}
           EVALS_ALL: ${{ inputs.evals_all }}

.github/workflows/release-gate.yml

@@ -0,0 +1,118 @@
+name: Release gate
+# The release gate (docs/ship-policy.md#release-gate; bin/gstack-release-gate,
+# lib/release-gate.ts): the full paid gate on main's head every 8 hours, only
+# when main moved since the last gate. It records the verdict as a release
+# note in refs/notes/gstack-trains, publishes the main-backstop check run on
+# the gated commit (what scripts/release-cut.ts reads as gated), and bisects
+# a red gate's cases. It never writes the stable branch: release-cut is its
+# only writer, and refuses every cut while the newest gate is red. Inert (no
+# paid work, nothing written) unless main's .gstack/ship-policy.json declares
+# a release_gate block; with one, the per-push main backstop
+# (evals-main-backstop.yml) stands down and this replaces it.
+on:
+  schedule:
+    # Every 8 hours (RELEASE_GATE_SCHEDULE_HOURS in lib/release-gate-policy.ts;
+    # test/release-gate-workflow.test.ts pins the two together), off the hour.
+    - cron: '17 */8 * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Print what the gate would test and dispatch nothing'
+        type: boolean
+        default: false
+      ignore_cadence:
+        description: 'Gate now even if the last gate is younger than cadence_hours (main must still have moved)'
+        type: boolean
+        default: true
+
+# One gate at a time; a second run waits for the first.
+concurrency:
+  group: release-gate
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  release-gate:
+    runs-on: ubuntu-24.04
+    # A dispatch gates only from the default branch, with its tooling.
+    if: github.ref_name == github.event.repository.default_branch
+    # The full gate (270) + a bisect round + margin; past --budget-minutes the
+    # record stays resumable by the next run.
+    timeout-minutes: 345
+    outputs:
+      action: ${{ steps.gate.outputs.action }}
+      sha: ${{ steps.gate.outputs.sha }}
+      check: ${{ steps.gate.outputs.check }}
+    permissions:
+      # Pushes the release record to refs/notes/gstack-trains and a bisect's
+      # release-gate/<id> branch (deleted after its round).
+      contents: write
+      # Dispatches the gate and reads its runs and artifacts.
+      actions: write
+      checks: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      # Read with git and jq only: without a release_gate block nothing below runs.
+      - name: Read the release gate policy (main)
+        id: policy
+        run: |
+          file=.gstack/ship-policy.json
+          policy=$(git show "${GITHUB_SHA}:${file}" 2>/dev/null || echo null)
+          gate=$(jq -c 'if (.release_gate | type) == "object" then .release_gate else null end' <<<"$policy") || { echo "::error::${GITHUB_SHA}:${file} is not valid JSON; fix the policy file" >&2; exit 1; }
+          if [ -z "$gate" ] || [ "$gate" = null ]; then
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "- Release gate inert: main's ${file} declares no release_gate block; the per-push backstop gates main" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "release=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        if: steps.policy.outputs.release == 'true'
+        with:
+          bun-version: 1.4.2
+
+      - name: Gate main's head when it moved
+        id: gate
+        if: steps.policy.outputs.release == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GSTACK_STATE_ROOT: ${{ runner.temp }}/gstack-state
+          DRY_RUN: ${{ inputs.dry_run && '1' || '' }}
+          IGNORE_CADENCE: ${{ inputs.ignore_cadence && '1' || '' }}
+        run: |
+          ./bin/gstack-release-gate run --repo "$GITHUB_REPOSITORY" --sha "$GITHUB_SHA" --budget-minutes 330 \
+            --summary "$GITHUB_STEP_SUMMARY" --outputs "$GITHUB_OUTPUT" ${DRY_RUN:+--dry-run} ${IGNORE_CADENCE:+--ignore-cadence}
+
+  # The gated commit's check run (release_gate.check_name, main-backstop), the
+  # evidence scripts/release-cut.ts reads. Its own job with checks: write and
+  # no repository code, as for backstop-check: only the recorded action word.
+  release-check:
+    runs-on: ubuntu-24.04
+    needs: release-gate
+    if: ${{ !cancelled() && contains(fromJSON('["gated","held","failed"]'), needs.release-gate.outputs.action) && needs.release-gate.outputs.sha != '' }}
+    timeout-minutes: 5
+    permissions:
+      checks: write
+    steps:
+      - name: Publish the release gate's check run on the gated commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTION: ${{ needs.release-gate.outputs.action }}
+          SHA: ${{ needs.release-gate.outputs.sha }}
+          CHECK: ${{ needs.release-gate.outputs.check }}
+        run: |
+          case "$ACTION" in
+            gated) conclusion=success ;;
+            held|failed) conclusion=failure ;;
+            *) echo "::error::unknown release gate action '$ACTION'"; exit 1 ;;
+          esac
+          [[ "$SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::'$SHA' is not a commit SHA"; exit 1; }
+          [[ "$CHECK" =~ ^[A-Za-z0-9_./-]{1,64}$ ]] || { echo "::error::'$CHECK' is not a check-run name"; exit 1; }
+          gh api "repos/${GITHUB_REPOSITORY}/check-runs" -X POST -f name="$CHECK" -f head_sha="$SHA" -f status=completed -f conclusion="$conclusion" \
+            -f details_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
+            -f "output[title]=Release gate: ${ACTION}" -f "output[summary]=${ACTION}: see the release-gate job summary of run ${GITHUB_RUN_ID}" >/dev/null
+          echo "- ${CHECK}: ${conclusion} (release gate ${ACTION}) on ${SHA}" >> "$GITHUB_STEP_SUMMARY"