test: snapshot planner output over real-world queries in CI

.github/PULL_REQUEST_TEMPLATE/projectasap.md

@@ -57,6 +57,12 @@ Mark non-applicable forms explicitly; do not fabricate evidence.
 
 Give each new test a one- or two-line behavioral purpose.
 
+## Snapshot changes
+
+For each changed file under `crates/devtools/tests/corpus_snapshots/`: the
+query and why its plan changed. Write "None" if no snapshot changed. See
+[planner snapshots](../../docs/develop_docs/planner-snapshots.md).
+
 ## Architectural decisions
 
 List consequential decisions and rejected alternatives, or state why this is not

.github/workflows/rust.yml

@@ -149,3 +149,45 @@ jobs:
       run: python3 tools/verify_metricsql_vendored_baseline.py
       env:
         RUSTC_WRAPPER: sccache
+
+  # Planner snapshots (#941). A release build: the corpus queries take minutes
+  # in debug. A failure means a plan changed; the regenerated snapshots are
+  # uploaded so an intended change can be committed without a local rerun.
+  corpus-snapshots:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    # Planning takes 2-6 min (6 min on one core) plus the release build; each
+    # query stops at 240 s.
+    timeout-minutes: 45
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        toolchain: stable
+
+    # sccache alone: caching the release target as well would duplicate it.
+    - name: Run sccache-cache
+      uses: mozilla-actions/sccache-action@v0.0.4
+
+    - name: Cache cargo registry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+        key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+
+    - name: Check planner snapshots
+      run: cargo test --release --locked -p asap-devtools --test corpus_snapshots -- --include-ignored
+      env:
+        RUSTC_WRAPPER: sccache
+
+    - name: Upload regenerated snapshots
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: corpus-snapshots
+        path: target/tmp/corpus_snapshots/
+        if-no-files-found: ignore

AGENTS.md

@@ -28,6 +28,9 @@
   Explicitly describe **Before this PR** and **After this PR**, using an
   end-to-end example, screenshot, measurement, or diagram appropriate to the
   change.
+- A PR that changes planner snapshots
+  (`crates/devtools/tests/corpus_snapshots/`) says under **Snapshot changes**
+  which queries changed and why; a person confirms the why.
 - Agents must not complete fields reserved for human judgment, approval, or
   attestation.
 - Do not create, push, or publish commits or pull requests unless the user has