stack/docs/scratchpads/1146-ci-queue-purpose.md

#1146 — CI Queue Guard Purpose Semantics

Objective

Make the pre-push queue guard wait for queued/running CI without requiring the previous remote head to have successful CI. Preserve fail-closed merge readiness.

Scope

• packages/mosaic/framework/tools/git/ci-queue-wait.sh
• focused queue-guard regression tests
• design and scratchpad documentation
• local framework activation required before the fixed guard can authorize this branch's push

Plan

1. Freeze purpose-specific behavior in failing process-level tests.
2. Implement the smallest state-dispatch change.
3. Run focused shell tests and repository quality gates.
4. Obtain independent review and remediate findings.
5. Install the reviewed framework source locally, run the mandatory pre-push queue guard, and push.
6. Open a PR against next, verify terminal-green CI, and close #1146 after merge.

Budget

• ASSUMPTION: no explicit token cap was provided.
• Working estimate: 12K tokens.
• Scope reduction: change only final-state dispatch and focused tests; do not redesign provider adapters.

Progress

• Confirmed source and installed guards are byte-identical.
• Reproduced terminal-failure blocking --purpose push.
• Root cause: final-state dispatch requires terminal success for both push and merge.
• Design approved: push is queue-clear on valid non-pending states; merge remains fail-closed.

Tests

Pending.

Risks and Blockers

• A source-only fix does not update ~/.config/mosaic/tools/git/ci-queue-wait.sh; local framework activation must use the reviewed installer path rather than a manual copy.
• Existing .mosaic/orchestrator/* working-tree changes are unrelated and must remain unstaged.