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