stack/docs/plans/2026-08-10-ci-queue-purpose-design.md

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.