docs(agents): mandatory CI pre-flight gate — no exceptions, no rationalizations

Agents keep rationalizing exceptions to the one-build-at-a-time rule and
destroying the builder. The rule now has teeth:

- copilot-instructions.md rule #9: explicit pre-flight command that MUST
  return 'OK: field is clear' before any CI action. Lists every known
  rationalization by name and marks each one wrong.
- ci-reference.md: pre-flight command block at top of file, not buried
- quickstart.md: pre-flight as rule #1 in Always Rules
- release-promotion.md: pre-flight as step 1 in Core Process

The command is copy-pasteable and self-describing. There is no ambiguity
about what 'cancel everything' means.

Assisted-by: Claude Sonnet 4.6 via GitHub Copilot

Author: castrojo

.github/copilot-instructions.md

@@ -133,28 +133,49 @@ Every PR must include an update to the relevant `docs/skills/` file (per AGENTS.
 
 `task_complete` without the skill contribution is incomplete.
 
-### 9. One BST build at a time — cancel everything before starting a new build
+### 9. Mandatory CI pre-flight — run this before every CI action, no exceptions
 
-Before triggering any new BST build (merging a PR, landing changes to `testing`, or
-dispatching `workflow_dispatch`), cancel **all** in-progress BST runs first:
+**Before merging any PR, pushing to any branch, or dispatching any workflow**, run the
+pre-flight check and verify the output shows zero active runs. This is not optional.
+There is no exception. There is no rationalization that makes skipping this correct.
 
 ```bash
-# Find and cancel all active runs
-gh run list --repo projectbluefin/dakota --json databaseId,status,name \
-  | python3 -c "import json,sys; [print(r['databaseId']) for r in json.load(sys.stdin) if r['status'] in ('in_progress','queued','pending')]" \
-  | xargs -I{} gh run cancel {} --repo projectbluefin/dakota
+# MANDATORY PRE-FLIGHT — run before every CI action
+gh run list --repo projectbluefin/dakota --limit 30 \
+  --json databaseId,status,name,headBranch \
+  | python3 -c "
+import json, sys
+runs = json.load(sys.stdin)
+active = [r for r in runs if r['status'] in ('in_progress', 'queued', 'pending', 'waiting')]
+if active:
+    print(f'BLOCKED: {len(active)} active run(s). Cancel all before proceeding:')
+    for r in active:
+        print(f'  gh run cancel {r[\"databaseId\"]} --repo projectbluefin/dakota  # {r[\"name\"]} [{r[\"headBranch\"]}]')
+else:
+    print('OK: field is clear, safe to proceed')
+"
 ```
 
-This includes:
-- **cache-warm runs** — not exempt. "Its progress is additive" is the rationalization that causes failure.
-- **stale builds** from prior branch state
-- **any other BST job** regardless of how long it has been running
+If the output is not `OK: field is clear` — **stop**. Cancel every listed run, then
+re-run the pre-flight until it is clean. Only then proceed.
 
-Concurrent BST builds compete for the same `ubuntu-24.04` runners and the same remote
-CAS write bandwidth. Running two simultaneously does not halve the time — it more than
-doubles it and risks 6h timeouts with `Cached elements after warm: 0`.
+**What counts as an active run that must be cancelled:**
+- Any `Build Bluefin dakota` run — regardless of branch, age, or how long it has run
+- Any `Warm BuildStream Cache` run — **cache-warm is not exempt, ever**
+- Any `Publish Bluefin dakota` run in progress
 
-**One build. Field clear. Then trigger.**
+**The rationalizations that have caused real failures — all are wrong:**
+- "The cache-warm run is additive, it helps the new build" → **No. It starves both. Cancel it.**
+- "This build is almost done, just a few more minutes" → **Cancel it. You don't know that.**
+- "The stale build is for a different branch, it won't interfere" → **It uses the same runners and CAS. Cancel it.**
+- "I already cancelled one build, that's enough" → **Cancel ALL of them. Run the pre-flight again.**
+
+Concurrent BST builds share the same `ubuntu-24.04` runner pool and the same remote CAS
+write bandwidth at `cache.projectbluefin.io:11002`. Two concurrent builds do not halve
+wall time — they more than double it and risk 6-hour timeouts with
+`Cached elements after warm: 0`.
+
+**One build. Field clear first. No exceptions.**
 
 ## CI overview
 

docs/skills/ci-reference.md

@@ -92,6 +92,29 @@ Route through `ci.md` first, then come here only when the focused skills do not
 
 **Push is conditional:** Remote cache section is only added to `buildstream-ci.conf` if **both** are set. Without credentials, BST builds from source using local disk cache only — slower but functional. This is normal for external contributors' forks.
 
+## ⚠️ Mandatory CI Pre-flight — run before every merge, push, or dispatch
+
+Before any action that could trigger a build, verify the field is clear:
+
+```bash
+gh run list --repo projectbluefin/dakota --limit 30 \
+  --json databaseId,status,name,headBranch \
+  | python3 -c "
+import json, sys
+runs = json.load(sys.stdin)
+active = [r for r in runs if r['status'] in ('in_progress', 'queued', 'pending', 'waiting')]
+if active:
+    print(f'BLOCKED: {len(active)} active run(s). Cancel all before proceeding:')
+    for r in active:
+        print(f'  gh run cancel {r[\"databaseId\"]} --repo projectbluefin/dakota  # {r[\"name\"]} [{r[\"headBranch\"]}]')
+else:
+    print('OK: field is clear, safe to proceed')
+"
+```
+
+If not `OK: field is clear` — cancel every listed run, re-run until clean. Cache-warm
+runs are not exempt. See Hard Rule #9 in `.github/copilot-instructions.md`.
+
 ## ⚠️ aarch64 cache-warm: first run is always a cold miss (2026-06-22)
 
 The GHA `actions/cache` restore key for aarch64 is `bst-warm-aarch64-`. On the first

docs/skills/quickstart.md

@@ -38,7 +38,8 @@ Use when:
 
 ## Always Rules
 
-1. Run `just --list` first.
+1. **Run the CI pre-flight before any merge or push.** (See Hard Rule #9 in `.github/copilot-instructions.md`.)
+2. Run `just --list` first.
 2. Use `just bst ...`, not bare `bst`.
 3. Grep all references before removing a package or file.
 4. Add new package elements to the correct stack.

docs/skills/release-promotion.md

@@ -35,7 +35,9 @@ Use when the task mentions:
 
 ## Core Process
 
-1. **Identify the stage.**
+1. **Run the CI pre-flight first.** Verify `OK: field is clear` before any action.
+   See Hard Rule #9 in `.github/copilot-instructions.md`. No exceptions.
+2. **Identify the stage.**
    - publish to `:testing`
    - open/update promotion PR
    - gate the promotion PR