---
kind: spec
status: active
---

# 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.
