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

6.7 KiB

Raw Blame History

kind, status

kind	status
spec	active

CI Queue Guard Purpose Semantics Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make the pre-push CI queue guard pass when no pipeline is queued or running while preserving fail-closed merge readiness.

Architecture: Keep provider lookup and tri-state classification unchanged. Make only the final state dispatch purpose-sensitive: push treats valid non-pending states as queue-clear, while merge continues to require terminal success. Preserve --require-status, malformed-payload rejection, unknown-state rejection, and audited provider-unavailable behavior.

Tech Stack: Bash, process-level shell regression harnesses, Gitea/GitHub status APIs.

Task 1: Freeze Purpose-Specific State Semantics

Files:

Modify: packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
Test: packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh

Step 1: Add failing push assertions

Change push expectations so terminal-failure and no-status require exit 0 plus an explicit queue-clear diagnostic. Add a --require-status assertion that keeps push/no-status non-zero.

Step 2: Add failing merge assertions

Invoke the same harness with MOSAIC_TEST_PURPOSE=merge and assert terminal failure and no status remain non-zero while terminal success remains zero.

Step 3: Add unknown-state coverage

Add a stub payload with a syntactically valid but unsupported status value and assert both purposes reject it.

Step 4: Run the focused test and verify RED

Run:

bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh

Expected: failures showing push terminal-failure and no-status returned exit 3 instead of exit 0 or lacked queue-clear diagnostics.

Step 5: Commit the failing tests

git add packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
git commit -m "test(ci): define purpose-aware queue readiness"

Task 2: Implement Purpose-Sensitive Final-State Dispatch

Files:

Modify: packages/mosaic/framework/tools/git/ci-queue-wait.sh:458-481
Test: packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
Test: packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh

Step 1: Implement push queue-clear behavior

For no-status, retain the existing --require-status failure. Otherwise, return success for push with an explicit diagnostic such as:

[ci-queue-wait] queue-clear state=no-status purpose=push branch=<branch>; no queued or running CI.

For terminal-failure, return success only for push with the same queue-clear wording. Merge must continue returning asserted non-readiness.

Step 2: Preserve malformed and unknown rejection

Keep malformed, unknown, and unrecognized states non-zero for both purposes.

Step 3: Run focused tests and verify GREEN

Run:

bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh

Expected: both scripts exit 0 and report their regression suites passed.

Step 4: Commit implementation

git add packages/mosaic/framework/tools/git/ci-queue-wait.sh
git commit -m "fix(ci): separate push queue clearance from merge readiness"

Task 3: Verify, Review, and Document Evidence

Files:

Modify: docs/scratchpads/1146-ci-queue-purpose.md

Step 1: Run shell syntax and focused regressions

bash -n packages/mosaic/framework/tools/git/ci-queue-wait.sh
bash -n packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh

Step 2: Run repository quality gates

pnpm preflight
pnpm typecheck
pnpm lint
pnpm test
pnpm format:check

Expected: every command exits 0.

Step 3: Obtain independent review

Request review of the exact branch head. Remediate all blocking findings and rerun focused and baseline gates.

Step 4: Record evidence and commit

Update the scratchpad with test output, review result, and residual risk, then commit it:

git add docs/scratchpads/1146-ci-queue-purpose.md
git commit -m "docs(ci): record queue guard verification"

Task 4: Keep the Merge Wrapper Aligned with the `next` Lane

Files:

Modify: packages/mosaic/framework/tools/git/pr-merge.sh:97-101
Test: packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh

Step 1: Write the failing regression

Run the exact-head merge regression with its Gitea fixture targeting next and confirm the current wrapper rejects it because it only permits main.

Step 2: Allow only documented integration targets

Permit main and next; reject every other target. Do not alter exact-head pinning, queue-guard invocation, provider selection, or merge method enforcement.

Step 3: Run focused merge regressions

bash packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh
bash packages/mosaic/framework/tools/git/test-pr-merge-queue-branch.sh
bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh

Expected: all pass, including a Gitea merge fixture targeting next.

Step 4: Commit

git add packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh
git commit -m "fix(ci): allow reviewed merges into next"

Task 5: Activate and Deliver Through `next`

Files:

Installed output: ~/.config/mosaic/tools/git/ci-queue-wait.sh

Step 1: Activate through the canonical installer

From the reviewed worktree, run the framework installer in sync-only keep mode so operator files remain protected:

MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_SKIP_SKILLS_SYNC=1 \
  bash packages/mosaic/framework/install.sh

Step 2: Verify installed/source parity

cmp -s \
  packages/mosaic/framework/tools/git/ci-queue-wait.sh \
  ~/.config/mosaic/tools/git/ci-queue-wait.sh

Expected: exit 0.

Step 3: Run mandatory pre-push queue guard

~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B fix/1146-ci-queue-purpose

Expected: branch-absent or queue-clear success.

Step 4: Push and open a PR against next

git push -u origin fix/1146-ci-queue-purpose
~/.config/mosaic/tools/git/pr-create.sh \
  -t "fix(ci): make queue guard purpose-sensitive" \
  -b "Closes #1146" \
  -B next \
  -H fix/1146-ci-queue-purpose \
  -i 1146

Step 5: Complete reviewed integration

Wait for exact-head terminal-green CI, obtain the required review, merge via the Mosaic wrapper, verify merged CI, and close #1146. Do not bypass any gate.

6.7 KiB Raw Blame History

CI Queue Guard Purpose Semantics Implementation Plan

Task 1: Freeze Purpose-Specific State Semantics

Task 2: Implement Purpose-Sensitive Final-State Dispatch

Task 3: Verify, Review, and Document Evidence

Task 4: Keep the Merge Wrapper Aligned with the next Lane

Task 5: Activate and Deliver Through next

6.7 KiB

Raw Blame History

Task 4: Keep the Merge Wrapper Aligned with the `next` Lane

Task 5: Activate and Deliver Through `next`