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.claude/skills/gate-advance/SKILL.md
GitHubGate 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(rewritesdocs/gatewith the computed value + a# basis:derivation + a compute date). - Freshness is guarded by the
derived-gatestep (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:
StatusDraft→Plannedon 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=Verifiedonce 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
-000placeholders where committed), acceptance criteria measurable, the UX/edge-case lens applied. Sign-offs recorded indocs/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 theIF-###interface rows its new LLRs imply — when a decomposition mints a seam (a module now provides/consumes a contract), add itsinterfaces.csvrow in the same batch rather than retrofitting later (PROCESS.md §8; theregistry-hygieneskill). - 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 isVerified.
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(likeAnalysis/Inspection) is LLR-exempt but still needs ≥1 TC. Don't fake subjective work into aTest; give it an honestAttesthome.
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.