Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

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

2026-08-20 19:30:25 -05:00

4.8 KiB

Raw Blame History

kind, status

kind	status
record	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

Freeze purpose-specific behavior in failing process-level tests.
Implement the smallest state-dispatch change.
Run focused shell tests and repository quality gates.
Obtain independent review and remediate findings.
Install the reviewed framework source locally, run the mandatory pre-push queue guard, and push.
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.

4.8 KiB Raw Blame History