gate-close
Close a landed change into ONE owner-decision packet before any governed-doc status advances. Use whenever CODE HAS LANDED and one or more PRD/RFC/ADR/US docs are candidates to move status, or when the user says "close this slice", "prep the flips", "ready to flip". For a single doc with NO code landed yet (a draft heading to proposed/accepted), use spec-red-team instead — gate-close already contains a red team per flip.
- License 许可
- MIT
- 所属仓库
- baodq97/govkit
- 最近更新
- 2026-09-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- gate-close
- hooks
- { "PreToolUse": [ { "hooks": [ { "type": "command", "command": "node \"${CLAUDE_SKILL_DIR}/freeze-status-edit.mjs\"" } ], "matcher": "Edit|Write" } ] }
- description
- Close a landed change into ONE owner-decision packet before any governed-doc status advances. Use whenever CODE HAS LANDED and one or more PRD/RFC/ADR/US docs are candidates to move status, or when the user says "close this slice", "prep the flips", "ready to flip". For a single doc with NO code landed yet (a draft heading to proposed/accepted), use spec-red-team instead — gate-close already contains a red team per flip.
02 资源文件 2
- 脚本freeze-status-edit.mjs13.1 KB
- 脚本freeze-status-edit.test.mjs17.5 KB
03 SKILL.md 正文
Gate Close
A status flip is a ratification, and a ratification needs evidence. This skill collapses the repetitive pre-flip tail into one packet the owner decides from in a single pass.
When to run it
After the change has landed and been committed, and before proposing any status advance. Do not run it while agents are still editing the tree — the verifier reads the working tree, so a mid-edit tree yields a false BLOCK. Commit first, then close.
Current gate verdict (live)
Injected at invocation so the packet is read against ground truth, not a reconstruction — this is the repo's real verify, read-only:
!npx govkit verify --json
The injection is an accelerant, not a dependency: if that command is unavailable (govkit not
installed, or a non-Node repo), ignore this block and discover the real gate from package.json
below. verify reads the working tree, so a non-empty violation list here usually means the tree
is still dirty — commit first (see above), then close.
How to run it
Workflow({
name: 'gate-loop',
args: {
verifyCmd: 'bun run check',
changeSummary: 'One paragraph on what the landed change actually does — the mechanism, the seams, what was verified and how. This is what the red-teamers reason from, so name real symbols and real commands.',
flips: [
{ id: 'US-0015', target: 'done', doc: 'docs/issues/US-0015-....md' },
{ id: 'RFC-0025', target: 'implemented', doc: 'docs/rfc/RFC-0025-....md' },
],
},
})
verifyCmd is required and must be the repo's real gate — never guess it. Discover it from
package.json, Makefile, or the CI workflow before invoking. changeSummary matters most: a
vague summary produces a vague red team.
Reading the packet
{ gate: { verdict, gates, gateProvenFallible, findings[] },
live: { liveVerdict, ranCommands, claims, notMeasured }, // 'skipped' unless args.live set (always set at a release gate)
reconcile: { edits: [{ doc, reason, proposed }] }, // exact text, NOT applied
redTeam: [{ id, verdict, criteriaSummary, reconciledText, sourcesExist, killCriterion }],
humanGates: ["US-0015 -> done", ...] }
gate.verdict: BLOCKorgate.gateProvenFallible: false— stop. Nothing advances on an unproven gate.live.liveVerdict: fail, or anylive.claims[].verdict: refuted— stop. The shipped artifact did not run; a green source gate does not override a red real-artifact run.flip-as-is— the status is honest; still apply anyreconcile.edits.flip-after-reconcile— applyreconciledTextfirst, then flip.blocked— do not flip. Fix the code, or scope the claim down to what shipped.
packet.humanGates lists every flip candidate flatly — the workflow itself does not tier them.
The split below (RFC-0027) is this skill's job, done once the packet is back.
Acting on the packet
- Tier each flip (RFC-0027). Read the repo's
govkit.ymlfor a top-levelratification:block. For each flip, its transition key isdoctype:from->to— read the doc's CURRENTstatus:(packet.humanGatesonly names the id and the target) to build it.- Block absent → every flip is R0 (owner-tier). This is the pre-RFC-0027 behavior, unchanged — nothing here regresses a repo that has not adopted the block yet.
- Block present, transition matches
R0_owner.transitions, matches no tier at all, or IS an edit to theratification:block itself → R0. An unmatched transition always falls to R0, never to R1 — the default is the ask, not the skip. - Matches
R1_packet.transitions(rfc:accepted->implemented,us:in-progress->done,drift --ack) AND every condition holds —gate.verdict == "SAFE-TO-COMMIT"withgate.gateProvenFallible == true(the FULL gate, never a narrower command), this packet is itself the required evidence, and this flip'sredTeam[].verdictisflip-as-isorflip-after-reconcilewithreconciledTextalready applied → R1, auto-apply. - Matches
R1_packet.transitionsbut a condition fails (gate.verdict == "BLOCK"orgateProvenFallible == false,redTeam[].verdict == "blocked", or aflip-after-reconcilewhosereconciledTextwas never applied) → R1, escalate — fold it into the owner-facing set below, naming the exact condition that failed. Never quietly downgrade an unmet R1 to a silent auto-apply. - Matches
R2_lead.transitions(us:open->in-progress,us->blocked) → R2, no ceremony — these carry no evidence bar to begin with; land directly, citing the policy source only.
- Present the R0 set — including every escalated R1, each tagged with the condition that failed
— to the owner as ONE decision via the
AskUserQuestiontool: surface every flip in this set in a single ratification (not N separate prompts), with structured options — authorize / hold / reword-first — alongside the reconcile edits and any limitation the red team surfaced. Recommend with trade-offs; the owner authorizes. Scope this prompt to the R0 + escalated-R1 set ONLY — the R1 auto-apply (step 4) and R2 no-ceremony flips get no fresh ask (RFC-0027). - Only on that authorization, apply
reconcile.editsand everyreconciledTextfor the R0/escalated set. A governed doc must certify exactly what shipped — never round a partial criterion up to done. Land each as a separate accept commit that edits the front-matterstatus:and the matching INDEX row, citing the owner's in-session authorization. - R1 auto-apply (and R2) flips do not wait for step 2. Apply that flip's
reconciledTextfirst if its verdict wasflip-after-reconcile, then land it in its OWN commit whose message cites the packet's run id (the workflow invocation id, e.g.wf_xxxxxxxx) and the policy source (govkit.yml @ <short-sha>) — that citation REPLACES the in-session owner quote, it does not supplement it. - Re-run the gate after the flips, and confirm the remote ref actually moved after pushing.
Why fewer asks is safe here
R1 removes the ask; it removes nothing that verifies. Three controls stay exactly as strict as before RFC-0027:
- The deterministic section gate at
implementedis untouched.govkit verifystill fails an RFC flipped toimplemented(or arelatreleased) that is missing itsrequiredSectionsByStatussections — As-built / Deviations from design (RFC-0010). An R1 flip that skips the ask still cannot skip proving what shipped. - The distiller audits every R1 flip commit. DISTILL (RFC-0017) reads each R1 commit against
the packet it cites: a flip that cites a red gate, a
blockedred-team, or no packet at all is an escape, logged to LEARNING-LOOP. The audit lands after the fact, but it is not optional — R1 is fast, not unwatched. - Code approval stays untouched, always. This tiering covers doc
status:bookkeeping only. Never self-approve, never self-merge, never act as code owner (AGENTS.md) — R1 does not touch that rule and never will; it only changes who signs the transcription of a fact the gate and the packet already established.
Release close
At a release gate the loop runs its strongest form: gate: 'release', which REQUIRES a live
scenario. The scenario is a real consumer install, not a re-run of this repo's own gate.
Workflow({
name: 'gate-loop',
args: {
gate: 'release',
verifyCmd: 'bun run check',
changeSummary: 'One paragraph on what this release ships.',
live: {
scenario: 'npm pack the tarball; install it into a clean scratch dir (mktemp -d); run `npx govkit init`; confirm the gate is green; then break one governed doc (remove a required front-matter key) and confirm the gate exits non-zero.',
expectations: [
'the packed tarball installs into a clean dir',
'npx govkit init scaffolds and the gate exits 0',
'a doc with a required front-matter key removed makes the gate exit non-zero',
],
},
flips: [{ id: 'REL-0001', target: 'released', doc: 'docs/releases/REL-0001-....md' }],
},
})
The verifier returns live: { liveVerdict, ranCommands, claims, notMeasured }. On owner
ratification, the ledger entry's check string is GENERATED from the verifier's ranCommands —
the real commands and their real exit codes — not typed by hand. That turns the
docs/ledger.json check field from testimony ("I ran it, it passed") into evidence (the exact
command a reader can re-run). Never write a released flip whose ledger check is not backed by
a ranCommands entry that exited 0.
Gotchas
The failure modes this ritual keeps re-learning, written where you meet them (seeded from
LEARNING-LOOP.md; the distiller extends this list from new escapes):
- Premature
drift --ack.drifthashes the staged/committed blob, not the working tree. Acking while the governed change is still unstaged pins the old blob — the gate goes green, then drift re-fires the moment you commit. Always stage/commit the governed change first, thendrift --ack. (Round 23; hit twice in one gate-close session.) - Front-matter ↔ INDEX drift. A doc's
status:/owner:and its INDEX row cell must match;verifycatches a mismatch. When you flip a status, edit both the front-matter and the INDEX row in the same change, or the close goes red on the next run. - Status flip is an owner act, in its own commit. A sub-agent never flips a
status:(the skill-scoped freeze hook now denies it at the tool boundary). The main agent flips only on the owner's in-session authorization, in a separate commit that cites it — never folded into the implementation commit. (RFC-0027/RFC-0032 F-freeze.) - Never pipe the gate through
head/grepin a&&chain — the pipe swallows the failing exit code and a red gate reads green. Capture to a file or check$?before chaining. (Round 12.) - Act on the same green.
bun run check && <flip/merge/push>in one chain — a green captured a few edits ago certifies the previous tree, not this one. (Round 22.)
Why one packet
The owner is the bottleneck when every flip is surfaced separately. Batching the whole tail into one packet turns N interruptions into one ratification, while keeping the two controls that protect the record: an independent verify and an independent red team, neither authored by whoever wrote the change.
04 同仓库更多 Skills
trigger-shaped
Use when the user says "plan a sprint retro"; drafts retro/notes.md for the team.
terse-unguarded
Step 2 — writes docs/x/output.json quietly.
guarded
Summarizes ledger totals into reports/monthly.csv.
open
Draft a spec. Use when asked to "draft a spec" or "write the RFC".
guarded
Deploy the thing.
working-discipline
Thinking-checkpoint discipline for substantive implementation, debugging, or autonomous work — 21 trigger-gated items (trigger → mandatory question → evidence to produce) that cut agent error and human escalation. Use before an autonomous or long-running run, when asked to "work carefully", "double-check", "làm cẩn thận", "reduce errors", "be more autonomous", or after looping twice on the same failing fix. NOT a procedure — checkpoints fire on their triggers and demand evidence, with an N/A escape valve so a strong model pays near-zero overhead.