fix(release): qualify immutable Main Guard candidates (#10665)

Author: chubes4

.github/workflows/audit-debt.yml

@@ -51,6 +51,11 @@
 
 name: Main Guard
 
+# A dispatched qualification is an immutable release proof; a push is only a
+# latest-tip health signal. The run name is the stable lookup key used by
+# release.yml when a dispatch starts after main has moved again.
+run-name: ${{ inputs.qualification_sha && format('Release Qualification {0}', inputs.qualification_sha) || 'Main Guard' }}
+
 on:
   push:
     branches: [main]
@@ -63,6 +68,10 @@ on:
         description: 'Audit profile to run (full = all discovery detectors).'
         required: false
         default: 'full'
+      qualification_sha:
+        description: 'Immutable commit SHA to qualify for a release.'
+        required: false
+        type: string
 
 # Latest merge wins. This gate answers exactly one question — "is main green
 # RIGHT NOW?" — and that answer is a pure function of the current tip, so a
@@ -86,8 +95,10 @@ on:
 # Push and sweep get separate groups so a merge train never cancels the weekly
 # audit sweep (and vice versa).
 concurrency:
-  group: main-guard-${{ github.event_name == 'push' && 'post-merge' || 'sweep' }}
-  cancel-in-progress: true
+  group: main-guard-${{ inputs.qualification_sha && format('qualification-{0}', inputs.qualification_sha) || (github.event_name == 'push' && 'post-merge' || 'sweep') }}
+  # A qualification proves one immutable release candidate and must survive
+  # newer merges. Push monitoring remains latest-wins.
+  cancel-in-progress: ${{ inputs.qualification_sha == '' }}
 
 permissions:
   contents: read
@@ -103,14 +114,16 @@ jobs:
   # every merge. One release build now feeds all three.
   gate-build:
     name: Build
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || inputs.qualification_sha != ''
     runs-on: ubuntu-latest
     # Least privilege: this job compiles and uploads, it never files issues.
     permissions:
       contents: read
       actions: read
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.qualification_sha || github.sha }}
       - uses: dtolnay/rust-toolchain@stable
 
       # Deliberately the same cache key as release.yml's gate-build: both run
@@ -180,7 +193,7 @@ jobs:
   # `continue-on-error` from the audit step below.
   full-audit-gate:
     name: Full-tree audit gate
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || inputs.qualification_sha != ''
     needs: gate-build
     runs-on: ubuntu-latest
     # Pure pass/fail gate — deliberately cannot file issues, unlike the sweep.
@@ -190,6 +203,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
+          ref: ${{ inputs.qualification_sha || github.sha }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -286,12 +300,13 @@ jobs:
   # autofix/auto-push path to disable. This gate never mutates the repo.
   full-lint-gate:
     name: Full-suite lint gate
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || inputs.qualification_sha != ''
     needs: gate-build
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
         with:
+          ref: ${{ inputs.qualification_sha || github.sha }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -338,12 +353,13 @@ jobs:
 
   full-test-gate:
     name: Full-suite test gate
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' || inputs.qualification_sha != ''
     needs: gate-build
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
         with:
+          ref: ${{ inputs.qualification_sha || github.sha }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -390,7 +406,7 @@ jobs:
 
   full-audit:
     name: Full-tree audit → tracking issues
-    if: github.event_name != 'push'
+    if: github.event_name != 'push' && inputs.qualification_sha == ''
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

.github/workflows/release.yml

@@ -231,13 +231,108 @@ jobs:
             echo "::notice::Release dry-run predicts v${RELEASE_VERSION} (${BUMP_TYPE})"
           fi
 
-  # ── Step 2: Build once ──
+  # ── Step 2: Exact-SHA release qualification ──
+  #
+  # A release owns an immutable candidate (github.sha), unlike Main Guard's
+  # push monitoring, which is intentionally latest-wins. Reuse terminal green
+  # Main Guard evidence for this SHA when it exists; otherwise dispatch a
+  # non-cancellable qualification and await that exact proof.
+  release-qualification:
+    name: Release qualification
+    needs: check
+    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    outputs:
+      candidate-sha: ${{ steps.proof.outputs.candidate-sha }}
+      proof-sha: ${{ steps.proof.outputs.proof-sha }}
+      proof-run: ${{ steps.proof.outputs.proof-run }}
+      proof-status: ${{ steps.proof.outputs.proof-status }}
+      next-action: ${{ steps.proof.outputs.next-action }}
+    steps:
+      - name: Reuse or await exact Main Guard proof
+        id: proof
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CANDIDATE_SHA: ${{ github.sha }}
+          DRY_RUN: ${{ inputs.dry-run || 'false' }}
+        run: |
+          set -euo pipefail
+
+          title="Release Qualification ${CANDIDATE_SHA}"
+          run_json="$(gh run list --workflow audit-debt.yml --limit 100 --json databaseId,displayTitle,status,conclusion,url | jq -c --arg title "$title" 'map(select(.displayTitle == $title)) | first // empty')"
+          action="reused exact terminal proof"
+
+          # A push-triggered Main Guard has the candidate as its workflow SHA,
+          # so it is equally valid evidence and avoids an unnecessary dispatch.
+          if [ -z "$run_json" ]; then
+            run_json="$(gh run list --workflow audit-debt.yml --commit "$CANDIDATE_SHA" --status completed --limit 100 --json databaseId,status,conclusion,url | jq -c 'map(select(.conclusion == "success")) | first // empty')"
+          fi
+
+          if [ -z "$run_json" ]; then
+            gh workflow run audit-debt.yml --ref main -f qualification_sha="$CANDIDATE_SHA"
+            action="started immutable qualification"
+            for _ in $(seq 1 30); do
+              run_json="$(gh run list --workflow audit-debt.yml --limit 100 --json databaseId,displayTitle,status,conclusion,url | jq -c --arg title "$title" 'map(select(.displayTitle == $title)) | first // empty')"
+              [ -n "$run_json" ] && break
+              sleep 2
+            done
+          fi
+
+          if [ -z "$run_json" ]; then
+            echo "::error::Main Guard qualification did not appear for ${CANDIDATE_SHA}"
+            exit 1
+          fi
+
+          run_id="$(jq -r '.databaseId' <<<"$run_json")"
+          while :; do
+            run_json="$(gh run view "$run_id" --json status,conclusion,url)"
+            status="$(jq -r '.status' <<<"$run_json")"
+            [ "$status" = "completed" ] && break
+            sleep 30
+          done
+
+          conclusion="$(jq -r '.conclusion // "cancelled"' <<<"$run_json")"
+          url="$(jq -r '.url' <<<"$run_json")"
+          if [ "$conclusion" = "success" ]; then
+            next_action="release immutable candidate"
+          else
+            next_action="repair or rerun the exact qualification"
+          fi
+
+          {
+            echo "candidate-sha=${CANDIDATE_SHA}"
+            echo "proof-sha=${CANDIDATE_SHA}"
+            echo "proof-run=${url}"
+            echo "proof-status=${conclusion}"
+            echo "next-action=${next_action}"
+          } >> "$GITHUB_OUTPUT"
+
+          {
+            echo "### Release qualification"
+            echo
+            echo "- Selected SHA: \`${CANDIDATE_SHA}\`"
+            echo "- Exact gate proof SHA: \`${CANDIDATE_SHA}\`"
+            echo "- Exact gate proof run: ${url}"
+            echo "- Proof status: \`${conclusion}\`"
+            echo "- Next action: ${next_action}"
+            echo "- Proof source: ${action}"
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "- Dry run: release mutation remains disabled"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          [ "$conclusion" = "success" ]
+
+  # ── Step 3: Build once ──
   # Compile homeboy from source once and share the binary with all
   # quality gate jobs. Eliminates 3× redundant cargo builds.
   gate-build:
     name: Build
-    needs: check
-    if: needs.check.outputs.should-release == 'true'
+    needs:
+      - check
+      - release-qualification
+    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.release-qualification.outputs.proof-status != 'success'
     # This binary is executed by the ubuntu-22.04 publication jobs. Build on
     # the oldest consumer runtime so recovery finalizers cannot require a newer GLIBC.
     runs-on: ubuntu-22.04
@@ -280,8 +375,9 @@ jobs:
     name: Audit
     needs:
       - check
+      - release-qualification
       - gate-build
-    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true'
+    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.release-qualification.outputs.proof-status != 'success'
     runs-on: ubuntu-latest
     outputs:
       audit-result: ${{ steps.audit.outcome }}
@@ -329,8 +425,9 @@ jobs:
     name: Lint
     needs:
       - check
+      - release-qualification
       - gate-build
-    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true'
+    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.release-qualification.outputs.proof-status != 'success'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -373,8 +470,9 @@ jobs:
     name: Test
     needs:
       - check
+      - release-qualification
       - gate-build
-    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true'
+    if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.release-qualification.outputs.proof-status != 'success'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -430,11 +528,12 @@ jobs:
     name: Release Quality Policy
     needs:
       - check
+      - release-qualification
       - gate-build
       - gate-audit
       - gate-lint
       - gate-test
-    if: ${{ always() && needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.gate-build.result == 'success' }}
+    if: ${{ always() && needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true' && needs.release-qualification.result == 'success' }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout workflow event commit
@@ -445,20 +544,26 @@ jobs:
       - name: Enforce release-blocking commands
         env:
           BLOCKING_COMMANDS: ${{ env.RELEASE_BLOCKING_COMMANDS }}
+          QUALIFICATION_RESULT: ${{ needs.release-qualification.outputs.proof-status }}
           AUDIT_RESULT: ${{ needs.gate-audit.outputs.audit-result || needs.gate-audit.result }}
           LINT_RESULT: ${{ needs.gate-lint.result }}
           TEST_RESULT: ${{ needs.gate-test.result }}
         run: |
+          if [ "$QUALIFICATION_RESULT" != "success" ]; then
+            echo "::error::Exact Main Guard qualification finished with result: $QUALIFICATION_RESULT"
+            exit 1
+          fi
           bash .github/release-quality-policy.sh
 
   # ── Step 4: Version bump + changelog + tag ──
   prepare:
     name: Prepare Release
     needs:
       - check
+      - release-qualification
       - gate-build
       - release-quality-policy
-    if: ${{ always() && needs.check.outputs.should-release == 'true' && needs.gate-build.result == 'success' && (needs.check.outputs.recovery-release == 'true' || inputs.release_tag != '' || needs.release-quality-policy.result == 'success') }}
+    if: ${{ always() && needs.check.outputs.should-release == 'true' && (needs.release-qualification.outputs.proof-status == 'success' || needs.check.outputs.recovery-release == 'true' || inputs.release_tag != '') && (needs.check.outputs.recovery-release == 'true' || inputs.release_tag != '' || needs.release-quality-policy.result == 'success') }}
     runs-on: ubuntu-latest
     outputs:
       release-version: ${{ steps.outputs.outputs['release-version'] }}

docs/architecture/release-pipeline.md

@@ -97,6 +97,18 @@ Release execution:
 4. Stops on failure and returns structured step results.
 5. Leaves plan-only steps visible for review without executing them.
 
+## CI Qualification
+
+The release workflow selects its triggering commit as an immutable candidate. It
+reuses a terminal green Main Guard run for that exact SHA when one exists. Without
+one, it dispatches a SHA-pinned Main Guard qualification and waits for its terminal
+result. This qualification has its own non-cancellable concurrency key, while push
+triggered Main Guard monitoring remains latest-wins.
+
+Workflow dry runs report the selected SHA, exact proof SHA and run, proof status,
+and one next action in the job summary. The selected candidate remains valid when
+new commits arrive; releasing only the latest tip is not inferred from PR state.
+
 Release requires a clean working tree except for files the release process owns,
 such as version targets and changelog targets.
 

tests/audit_debt_workflow_test.rs

@@ -287,13 +287,37 @@ fn post_merge_gates_never_mutate_the_repository() {
 #[test]
 fn superseded_post_merge_runs_are_cancelled() {
     let workflow = main_guard_workflow();
-    // Opposite of release.yml's `cancel-in-progress: false`: this gate reports
-    // on the current tip and strands nothing, so a superseded run is worthless.
-    assert!(workflow.contains("cancel-in-progress: true"));
+    // Push monitoring reports on the current tip and strands nothing, so a
+    // superseded run is worthless. An explicit qualification is different: it
+    // proves an immutable release candidate and must not be cancelled by a
+    // later merge.
+    assert!(workflow.contains("cancel-in-progress: ${{ inputs.qualification_sha == '' }}"));
     // Push and sweep are separate groups so a merge train cannot cancel the
     // weekly audit sweep.
     assert!(workflow.contains("group: main-guard-"));
     assert!(workflow.contains("github.event_name == 'push' && 'post-merge' || 'sweep'"));
+    assert!(workflow.contains("format('qualification-{0}', inputs.qualification_sha)"));
+}
+
+#[test]
+fn immutable_qualification_checks_out_and_gates_the_requested_sha() {
+    let workflow = main_guard_workflow();
+
+    assert!(workflow.contains("qualification_sha:"));
+    assert!(workflow.contains("Release Qualification {0}"));
+    assert!(workflow.contains("ref: ${{ inputs.qualification_sha || github.sha }}"));
+    for name in [
+        "gate-build",
+        "full-audit-gate",
+        "full-lint-gate",
+        "full-test-gate",
+    ] {
+        let gate = job(name);
+        assert!(
+            gate.contains("inputs.qualification_sha != ''"),
+            "{name} must run for an immutable qualification"
+        );
+    }
 }
 
 /// The audit gate must be able to SEE the tree it claims to gate.

tests/release_workflow_test.rs

@@ -213,6 +213,42 @@ fn release_concurrency_scopes_recovery_runs_to_the_requested_tag() {
     ));
 }
 
+#[test]
+fn release_reuses_or_awaits_an_exact_main_guard_qualification() {
+    let workflow = release_workflow();
+    let qualification = job_section(workflow, "release-qualification");
+
+    assert!(qualification.contains("CANDIDATE_SHA: ${{ github.sha }}"));
+    assert!(qualification.contains("gh run list --workflow audit-debt.yml"));
+    assert!(qualification.contains("--commit \"$CANDIDATE_SHA\""));
+    assert!(qualification.contains(
+        "gh workflow run audit-debt.yml --ref main -f qualification_sha=\"$CANDIDATE_SHA\""
+    ));
+    assert!(qualification.contains("proof-status=${conclusion}"));
+    assert!(qualification.contains("Selected SHA:"));
+    assert!(qualification.contains("Exact gate proof run:"));
+    assert!(qualification.contains("Proof source: ${action}"));
+    assert!(qualification.contains("Dry run: release mutation remains disabled"));
+}
+
+#[test]
+fn terminal_green_qualification_skips_duplicate_release_gates() {
+    let workflow = release_workflow();
+
+    for job in ["gate-build", "gate-audit", "gate-lint", "gate-test"] {
+        let section = job_section(workflow, job);
+        assert!(
+            section.contains("needs.release-qualification.outputs.proof-status != 'success'"),
+            "{job} must reuse exact terminal green Main Guard evidence"
+        );
+    }
+
+    let policy = job_section(workflow, "release-quality-policy");
+    assert!(policy
+        .contains("QUALIFICATION_RESULT: ${{ needs.release-qualification.outputs.proof-status }}"));
+    assert!(policy.contains("Exact Main Guard qualification finished with result"));
+}
+
 #[test]
 fn release_test_gate_does_not_repeat_separate_lint_gate() {
     let gate_test = job_section(release_workflow(), "gate-test");