diff --git a/docs/plans/2026-08-10-ci-queue-purpose-design.md b/docs/plans/2026-08-10-ci-queue-purpose-design.md new file mode 100644 index 00000000..ce56c668 --- /dev/null +++ b/docs/plans/2026-08-10-ci-queue-purpose-design.md @@ -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. diff --git a/docs/scratchpads/1146-ci-queue-purpose.md b/docs/scratchpads/1146-ci-queue-purpose.md new file mode 100644 index 00000000..ace90e8e --- /dev/null +++ b/docs/scratchpads/1146-ci-queue-purpose.md @@ -0,0 +1,43 @@ +# #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.