docs(ci): design purpose-aware queue guard

2026-08-10 14:32:19 -05:00
parent 00eb216480
commit 03786d6803
2 changed files with 76 additions and 0 deletions
@@ -0,0 +1,33 @@
+# CI Queue Guard Purpose Semantics
+
+- **Issue:** #1146
+- **Target branch:** `next`
+
+## Problem
+
+`ci-queue-wait.sh` treats any result other than terminal success as asserted non-readiness. That is correct for merge readiness, but incorrect for the pre-push queue guard: a terminal failure or an empty status set means no pipeline is queued or running, so the queue is clear.
+
+## Design
+
+Make final-state handling purpose-sensitive while preserving the existing provider and payload safeguards:
+
+- `--purpose push`
+  - wait while state is `pending`;
+  - return success for `terminal-success`, `terminal-failure`, and `no-status`;
+  - continue rejecting `malformed`, `unknown`, and unrecognized states.
+- `--purpose merge`
+  - return success only for `terminal-success`;
+  - continue rejecting `terminal-failure`, `no-status`, malformed, unknown, and unrecognized states.
+- `--require-status` remains authoritative: `no-status` fails for either purpose when it is supplied.
+
+Diagnostics will explicitly distinguish a queue-clear push result from successful CI so callers cannot mistake an old failure for a green pipeline.
+
+## Testing
+
+Extend the process-level tri-state regression harness with separate push and merge assertions:
+
+1. Push passes for terminal success, terminal failure, and no status.
+2. Push still fails for pending, malformed, and unknown states.
+3. `--require-status` makes push/no-status fail.
+4. Merge behavior remains fail-closed except for terminal success.
+5. Existing provider-unavailable audit behavior remains unchanged.