veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
71 lines
4.8 KiB
Markdown
71 lines
4.8 KiB
Markdown
---
|
|
kind: record
|
|
status: active
|
|
---
|
|
|
|
# #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: focused queue and merge shell regressions passed after the wrapper change.
|
|
- GREEN: isolated Mosaic Vitest run passed (81 files, 1,514 tests).
|
|
- The normal parallel Mosaic Vitest run has an environment-sensitive pre-existing failure in `install-ordering-guard.spec.ts`: the real activation probe changes between two calls while other suites run concurrently. Running the same spec alone and the complete Vitest suite with one fork passes.
|
|
- The framework shell suite's pre-existing `version_coupling_unittest.py` also fails locally because the newly installed `mosaic` is now on PATH despite the test injecting a nonexistent PATH; CI's clean image does not have this global CLI. All changed queue/merge harnesses pass.
|
|
- 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.
|