gate-advance

Use when moving a project honestly from one gate to the next (G1 to G2 to G3) — what each gate requires, how ratification works as a reviewed Status-change commit (docs/gate is DERIVED from artifact s

SKILL.md

GitHub

Gate advance (move G1 → G2 → G3 honestly)

Advancing a gate is a decision recorded in a reviewed commit, backed by a green harness at that gate's bar. Never self-advance; never report a green you didn't run. Authority: docs/process.md §4 (gates), §5 (verdict protocol), §7 (the active gate). The gate's acceptor is whoever docs/gate-policy declares (default attended = a human at every gate; the other levels + the deviation register: process-options.md "Gate authority levels") — on a non-default repo, read "human" in this skill as that declared acceptor.

The active-gate mechanism (derived, not hand-set)

The current gate is the first non-comment line in docs/gate (G1|G2|G3), which scripts/check.py reads to run only that gate's checks — so CI enforces the bar the project is actually at. But docs/gate is now generated by scripts/derive_gate.py, not hand-set (docs/specs/derived-gate-model.md): the gate is computed from the artifact states (SN section-state + SR/LLR/TC Status maturity) — the repo is at gate G iff every in-scope artifact meets G's bar. You never edit that line; you ratify artifacts and regenerate.

  • Regenerate after a ratification: python scripts/derive_gate.py (rewrites docs/gate with the computed value + a # basis: derivation + a compute date).
  • Freshness is guarded by the derived-gate step (derive_gate.py --check), wired into the pre-commit floor and every gate — so a ratification that moved the states but not the cache fails loudly.

Ratification = a reviewed Status-change commit

Closing a gate is no longer a docs/gate bump. The acceptor marks a batch of artifacts ratified in a reviewed commit — that commit is the sign-off, and the gate derives from it:

  • G0 → G1 — a draft requirement is ratified: Status Draft → Planned on the SR (and an SN moves out of the ## Draft needs (unratified) section into a core section). The ratification date is git-derived (the commit that moved it).
  • G2 → G3 — the SR reaches Status=Verified once its tests pass; the derived gate follows.

Carry the batch-scoped hierarchy view (G1/G2). A ratification brief presents the batch's SN → SR → LLR/TC tree with its prose so the acceptor rules on the whole decomposition, not a row list. Generate it, never hand-copy: python scripts/trace.py --ratify <phase> --out docs/ratify/<phase>-g2.md (scope is a phase tag or an SR-### list) emits the tree with each SR's Requirement/AC, LLR Detail, TC Method/Expected, and any cited rubric — then link that file from the ## OI-N brief. check_trajectory.py warns (never fails) when a [phase]-[g1|g2] ratification brief carries no such link.

This preserves the reviewed-commit discipline while making the marker computed. It composes with the gate-authority levels (docs/gate-policy): attended = the human ratifies each batch; single-ratify = the batch is ratified once at its [phase]-[g2] close (one review per phase gate — a natural fit); autonomous = a fresh-context reviewer's recorded verdict ratifies. An agent may make the ratifying commit on the acceptor's behalf, governed by that level. Record the sign-off in docs/log.md (the append-only history docs/status.md points at).

What each gate takes

  • G1 → G2 (Requirements/UX/Constraints done). Real SN/SR rows (no -000 placeholders where committed), acceptance criteria measurable, the UX/edge-case lens applied. Sign-offs recorded in docs/log.md.
  • G2 → G3 (Decomposition & Test Coverage). Every SR decomposes to LLR/TC; each requirement's TC exists as a failing test first (red → green). The harness at G2 runs traceability + --no-placeholders + runnable tests + flow checks. orphans=0. A [g2] batch also authors/updates the IF-### interface rows its new LLRs imply — when a decomposition mints a seam (a module now provides/consumes a contract), add its interfaces.csv row in the same batch rather than retrofitting later (PROCESS.md §8; the registry-hygiene skill).
  • G3 (Implementation). Code implements the LLRs with Implements: back-links; the full harness passes: trace.py --strict --no-placeholders --strict-schema --require-verified, coverage ≥ threshold, arch-map fresh, flows current. Every test-verifiable SR is Verified.

Run the gate bar with scripts/check.py (it selects the gate's checks from docs/gate); paste the real output into the docs/log.md audit log.

Sync before you ratify (iteration-branch repos)

Policy-flip sweep. A change to docs/gate-policy, docs/push-policy, docs/review-policy, or docs/guardrails-policy is a status-staleness event: in the same sitting, grep docs/status.md and docs/run-state for old pause/stop/approval wording and point it to the declared policy file rather than paraphrasing the value.

If the repo runs the agent iteration branch & sync layer (docs/process-options.md; agent work rides llm/<branch>, the development branch is curated), a gate closure is a sync point. Run the five-step ritual before the ratifying commit lands: backup ref → scrub (privacy-checked repos only; fail closed if the scrub agent can't run) → optional iteration-branch push per docs/push-policy → collate into categorical commits → land on the development branch. The ratification (the Status-change commit + the regenerated docs/gate) rides the landed, collated history. Landing is not a stopping point — but pushing follows docs/push-policy (default human: an agent never pushes; the human publishes at leisure).

Honest verification where machines can't (Attest)

Some SRs can't be mechanically tested (subjective quality, a binary asset, a witnessed behavior). Use the Attest verification method: a named human's recorded judgment, captured in the TC's Parameters/Expected cell (who + when

  • what was judged) — a trust-based floor, not a runnable check. Attest (like Analysis/Inspection) is LLR-exempt but still needs ≥1 TC. Don't fake subjective work into a Test; give it an honest Attest home.

Report attested vs. mechanized

trace.py always emits a "Verification basis (attested vs mechanized)" count. When reporting a gate's readiness, state that split honestly — how many SRs are machine-verified vs. resting on a human attestation — so a reviewer sees the trust footprint rather than a single "all green". An attested gate can be legitimate; hiding that it's attested is not.