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

• RED confirmed before implementation: the focused tri-state harness reported push terminal-failure and no-status as ASSERTED_NOT_READY.
• GREEN: bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh — all outcome classes passed.
• GREEN: bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh — 6/6 purpose-aware cases passed.
• GREEN: bash -n passed for the changed guard and both focused harnesses.
• GREEN: pnpm preflight, pnpm typecheck, and pnpm lint passed.
• pnpm test ran 45/46 workspace test tasks successfully, but the pre-existing Gateway cross-user-isolation.test.ts failed during cleanup with PostgreSQL error 28P01 (local mosaic password authentication failure). The changed Mosaic framework test task passed within that run.
• GREEN: pnpm --filter @mosaicstack/mosaic test passed (81 Vitest files, 1,514 tests, plus the complete framework shell suite, including both queue-guard regressions).
• GREEN: pnpm format:check passed.
• Note: an additional ad hoc Prettier command was not applicable to shell files because Prettier has no shell parser; the repository-wide format check passed using its configured file globs.

Review

• Independent Codex review of the six-file diff: approved, confidence 0.84, zero blockers/should-fix/suggestions.
• Review confirmed push queue-clear behavior, merge fail-closed behavior, and --require-status coverage.

Risks and Blockers

• Canonical framework activation completed with MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_SKIP_SKILLS_SYNC=1 bash packages/mosaic/framework/install.sh.
• Source and installed queue guards are byte-identical (cmp and SHA-256 parity passed).
• The installed pre-push guard now passes for the not-yet-remote feature branch with queue clear.
• The required merge wrapper then exposed a second bootstrap defect: pr-merge.sh hardcoded main, contradicting the documented PR-based next integration lane. Tracked as #1149 and fixed in the same delivery branch with a regression fixture targeting next.
• Activation emitted the existing manifest-safety warning that six fleet/run/*.hb* operator files were touched then restored; no data loss was observed, but this remains a pre-existing framework-manifest defect to report separately.
• The first activation attempt timed out after 600 seconds while copying the 113K-file operator snapshot; the bounded 1,800-second retry completed successfully. It left a partial durable snapshot from the interrupted attempt in the normal backup directory; the completed snapshot is the newer pre-update-20260810T195317Z entry.
• Full baseline test completion is blocked by the unrelated local PostgreSQL authentication/cleanup failure described above; CI has its own disposable PostgreSQL service.
• Existing .mosaic/orchestrator/* working-tree changes are unrelated and must remain unstaged.