ci: the merge queue builds both images, the guest suite runs nightly, documentation alone builds nothing

.github/workflows/ci.yml

@@ -1,9 +1,11 @@
 name: ci
 
-# CI runs once per pull request, in the merge queue. On `pull_request` every
-# check reports skipped, which a required check reads as green; the skip sits
-# in the called workflow's job, because a skipped caller reports its own name
-# and not `toolchain / build` or `guest / suite`.
+# CI runs once per pull request, in the merge queue: the host checks and every
+# architecture's shipped image. The guest suite is nightly's. On `pull_request`
+# every job is skipped, which a required check reads as green. A merge group
+# that changes documentation alone against its parent (`build/ci.rs`'s `scope`;
+# sound only under the ruleset's `ALLGREEN` grouping) runs the host checks that
+# read it and skips `toolchain` and `image`.
 on:
   pull_request:
     branches: [main]
@@ -42,20 +44,40 @@ jobs:
 
       - run: cargo run -- --ci host
 
+  scope:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    outputs:
+      build: ${{ steps.scope.outputs.build }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - id: scope
+        run: cargo run -- --ci scope
+
+  # Skipped where `build` is `false` and nowhere else: a `scope` that failed
+  # leaves it empty, and everything builds.
   toolchain:
+    needs: scope
+    if: ${{ github.event_name != 'pull_request' && !cancelled() && needs.scope.outputs.build != 'false' }}
     uses: ./.github/workflows/toolchain.yml
 
   # A required check that is skipped reads as green, so this runs whatever
   # `toolchain` concluded.
-  guest:
-    needs: toolchain
-    if: ${{ !cancelled() }}
-    # Its container's pull.
-    permissions:
-      contents: read
-      packages: read
-    uses: ./.github/workflows/guest.yml
-    with:
-      kvm: true
-      sysroot-key: ${{ needs.toolchain.outputs.sysroot-key }}
-      sysroot-path: ${{ needs.toolchain.outputs.sysroot-path }}
+  image:
+    needs: [scope, toolchain]
+    if: ${{ github.event_name != 'pull_request' && !cancelled() && needs.scope.outputs.build != 'false' }}
+    # Bare, as `toolchain / build` is: the sysroot is built for its glibc.
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ${{ needs.toolchain.outputs.sysroot-path }}
+          key: ${{ needs.toolchain.outputs.sysroot-key }}
+          fail-on-cache-miss: true
+
+      - run: cargo run -- --ci image

.github/workflows/guest.yml

@@ -17,8 +17,6 @@ on:
 
 jobs:
   suite:
-    # ci.yml's pull request run reports this check skipped.
-    if: github.event_name != 'pull_request'
     runs-on: ubuntu-24.04
     # A wedge guard, not a budget.
     timeout-minutes: 60
@@ -76,7 +74,8 @@ jobs:
         continue-on-error: true
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          name: serial-${{ github.job }}
+          # One per lane: nightly calls this twice in one run.
+          name: serial-${{ inputs.kvm && 'kvm' || 'tcg' }}
           path: target/red-run-serial/**/uart-*.log
           if-no-files-found: warn
           retention-days: 7

.github/workflows/nightly.yml

@@ -72,6 +72,19 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: cargo run -- --ci release
 
+  kvm:
+    needs: toolchain
+    if: ${{ !cancelled() }}
+    # Its container's pull.
+    permissions:
+      contents: read
+      packages: read
+    uses: ./.github/workflows/guest.yml
+    with:
+      kvm: true
+      sysroot-key: ${{ needs.toolchain.outputs.sysroot-key }}
+      sysroot-path: ${{ needs.toolchain.outputs.sysroot-path }}
+
   tcg:
     needs: toolchain
     if: ${{ !cancelled() }}

.github/workflows/toolchain.yml

@@ -10,8 +10,6 @@ on:
 
 jobs:
   build:
-    # ci.yml's pull request run reports this check skipped.
-    if: github.event_name != 'pull_request'
     # Bare, not a container: its glibc is a build's floor.
     runs-on: ubuntu-24.04
     timeout-minutes: 350
@@ -52,7 +50,7 @@ jobs:
       - id: build
         run: cargo run -- --ci bootstrap
 
-      # A merge group's scope is read only by its own guest job, which restores
+      # A merge group's scope is read only by its own image job, which restores
       # the sysroot alone.
       - if: steps.build.outputs.llvm == 'built' && github.event_name != 'merge_group'
         uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0

CLAUDE.md

@@ -56,7 +56,7 @@ Rust and QEMU are the development prerequisites. Other host tools must be builda
 - **Investigate reds.** Do not rerun a failure merely to get green. Fix a defect introduced by the change. A real unrelated defect may be recorded without blocking the PR once its independence is established. Repair or delete a defective or redundant test according to its value, preserving evidence of any real bug it exposed. Host load invalidates timing claims in guest tests, not evidence of an actual race or lost progress.
 - **Show evidence.** Record commands, exit codes, logs, revisions and machines. Identify earlier evidence reused and why later edits do not invalidate it. Use an independent oracle where available and a negative control where a defect would otherwise land unseen; the whole change reverted onto the measured base is the control for the whole change. Another agent is not an independent oracle. Do not add a test for what a type or straightforward inspection already establishes.
 
-Agents may run their own selected guest tests. Metal runs are coordinated and executed by the orchestrator; implementers prepare them with `--metal-readback`, which touches no machine. Preserve the existing required CI checks until a separately scoped workflow change implements the agreed scheduling policy.
+Agents may run their own selected guest tests. Metal runs are coordinated and executed by the orchestrator; implementers prepare them with `--metal-readback`, which touches no machine.
 
 ## Working safely