gate-work

name	gate-work
description	Executes an operator-authored gate document by loading it into context and working through each checkpoint as the executing agent — no subagent dispatch. Handles resume of partially-completed gates against the operator's validation plan.
when_to_use	Use when the user asks to work/execute/run a gate, work or resume a specific Q-number (e.g. "work Q3"), execute gate checkpoints, or validate against an existing gate document.

Gate Work — Gate Execution

You are the executing agent. This skill loads a gate document into your context and you work through it directly. There is no subagent dispatch — you read the gate, adopt the framing below, and do the work.

Input

The operator provides a gate reference: a Q-number (e.g., "Q3"), a filename (e.g., "Q3-gate.md"), or a path. Resolve to a *-gate.md file at the workspace root.

Step 1 — Resolve and Validate

1. Resolve the gate file at the workspace root. If the file doesn't exist, stop and tell the operator.
2. Read the gate file.
3. Check for ## Gate Status: CLEARED. If the gate is already cleared, tell the operator and stop. Do not re-execute a cleared gate without explicit confirmation.
4. Read the verdict: field from the gate's YAML frontmatter — the fixed-position machine-readable current-state, read with a position-anchored read of that one key (see the Machine-readable review header convention in ${CLAUDE_PLUGIN_ROOT}/skills/gate-plan/references/gate-template.md). verdict: pass → the gate was reviewed and passed; proceed. verdict: fail or verdict: pending → stop and tell the operator the gate needs a passing review before execution. An absent frontmatter block or verdict: key → the gate predates the machine-readable verdict contract; halt loud and tell the operator to migrate it (backfill the frontmatter verdict: from the ## Gate Review log's current verdict). Read only the frontmatter field — do not grep the body or the ## Gate Review narrative for a Verdict: line (the append-only log may carry superseded verdicts, and the body may carry comparison/quoted Verdict: tokens). The gate lifecycle is plan → review → work — executing an unreviewed gate wastes effort on work that may be blocked at clearance.

Step 2 — Extract Context

1. Completion criteria: The first paragraph after the # Q{n} Gate: title and before the first ## heading. This is what success means.
2. Dependencies: The "Depends on:" line, if present. If the gate depends on an uncleared gate, warn the operator.
3. Queue context: Read QUEUE.md at the workspace root. Find the matching Q-item for additional context on intent and scope. If no match, proceed without it — the gate file is self-contained.
4. Anti-pattern registry: Read ${CLAUDE_PLUGIN_ROOT}/references/anti-pattern-registry.md. When a checkpoint carries an anti-pattern tag (`{AP-nn}`), understand what failure mode that checkpoint guards against — this informs verification rigor. A checkpoint tagged {AP-07} (Vacuous Green) means verification must produce substantive evidence, not just confirm structural existence. A checkpoint tagged {AP-10} (Recursive Defect) means the verification itself should be audited for the defect class being checked. The tag is a signal, not a procedure — use judgment on how the anti-pattern awareness shapes verification depth.

Step 3 — Adopt Framing and Begin

After completing Steps 1 and 2, adopt this operational context and begin working through the gate:

The gate file is an operator-authored validation plan. You did not create it. It is not code you can compile or test in that manner. It is a structured set of checkpoints that must be satisfied through real work — executing commands, verifying outputs, producing artifacts, and confirming results.

Your completion criteria: you must be able to claim the extracted completion criteria when done. Every checkpoint in the gate serves that claim. Work through them in order, respecting any stated dependencies between phases.

How to work the gate:

• Check off items as you complete them by changing [ ] to [x] in the gate file.
• Produce the verification each checkpoint requires. If a checkpoint specifies a command, run it. If it specifies an observable outcome, confirm it and document the result.
• Document artifact evidence inline for every checkpoint you complete. When you mark a checkpoint [x], the gate file must contain the concrete evidence that proves it — command output, file contents, counts, or results quoted directly below the checkpoint. A checkpoint marked [x] without artifact evidence documented in the gate file is not completed. Either produce the evidence or leave the checkpoint unchecked.
• If a checkpoint cannot be completed, do not mark it [x]. Explain what blocked it and continue with unblocked checkpoints. The operator will decide how to proceed.
• If a checkpoint should be bypassed, mark it [~] and document the justification inline. Bypasses are decisions — they require reasoning.
• If you discover issues with the gate document itself (wrong assumptions, filename mismatches, spec-vs-reality divergences), document them under a ## Gate Errata section at the end.
• Pre-clear detector. Before writing ## Gate Status: CLEARED, verify all three conditions. If any condition fails, the gate cannot clear — halt and report to the operator. This is fail-closed: ambiguity on any condition is a halt, not a pass.
  1. At least one checkpoint is marked [x] (not all bypassed, deferred, or blocked).
  2. Every checkpoint marked [x] has artifact evidence documented inline in the gate file (no prose-only completions).
  3. The gate's frontmatter verdict: field reads pass — the fixed-position machine-readable current-state, read with a position-anchored read of that one key, confirming the gate was reviewed and found adequate. verdict: fail or verdict: pending blocks clearance; an absent frontmatter block or verdict: key means the gate predates this contract and must be migrated first (halt loud — backfill the frontmatter from the ## Gate Review log's current verdict). Do not read the ## Gate Review narrative or grep the body for a Verdict: line — the append-only log may carry a superseded Verdict: FAIL alongside the operative PASS, and the body may carry comparison/quoted Verdict: tokens; only the frontmatter field governs.
• Post-clearance exit sequence. When the pre-clear detector passes, execute the following before stamping CLEARED. Evidence from each step is written into the gate file itself — the gate file is the enforcement contract and must contain complete proof before being sealed. The gate file remains at the workspace root throughout this sequence.
  1. Commit and push. All changes produced during gate execution — modified source files and any artifacts referenced by checkpoints — are committed and pushed. Write the commit hash into the gate file. Evidence: commit hash documented in gate file.
  2. Version bump. If the gate modified any file within a plugin repository, bump the patch version, commit, and push. Write the new version number and commit hash into the gate file. Evidence: version number and commit hash documented in gate file.
  3. Consumer reachability (conditional). If the gate modified artifacts consumed external to the current domain, identify the distribution path and document it in the gate file. Flag the operator on any distribution steps the agent cannot perform (e.g., plugin cache refresh). The agent's obligation is to make the delivery path visible — not to verify or execute distribution. If all artifacts are domain-local, state so explicitly in the gate file.
  4. Remove queue item. Delete the matching Q-row from QUEUE.md at the workspace root. The queue tracks live operational state — a cleared gate is done, not active. If no matching row exists, skip silently.
• Stamp CLEARED. Only after the exit sequence completes and all delivery evidence is documented in the gate file, add a ## Gate Status: CLEARED section with the validation date and a summary sentence stating what was proven. The CLEARED stamp is the seal on the complete contract — checkpoints, review, and delivery proof. Do not stamp CLEARED before the exit sequence is complete.
• Archive the gate. Move the cleared gate file from the workspace root to gates/ (create the directory if it doesn't exist), and in the same closing act move the gate's companion Q{n}-why.md — the frozen intent record triage left at the workspace root — into gates/ alongside it. Move, never delete: the relocation preserves the why-record's bytes at its new path, so the retired-number trace is kept by construction — do not delete it, and do not delete-and-recreate it. Skip the why-record silently when no companion Q{n}-why.md exists — gates predating the intent-record convention have no companion, and that absence is not an error. This is the final step. Nothing follows it: the gate and its why-record land in gates/ together as the closing act, and the archive move releases the contract. A cleared gate with uncommitted changes, an unbumped version, or unreachable consumers is delivery without deployment.

The operator is here to assist you, not as a crutch. You may work toward the completion criteria in whatever way you deem appropriate. If you are blocked and cannot unblock yourself, ask. Otherwise, proceed.

Related Skills

• gate-plan — Authors a gate document. Plan creates the gate; work executes it.
• gate-review — Audits a gate document against the quality bar. Review sits between plan and work in the lifecycle.
• prime — Session context loading. Prime and gate-work are independent — prime loads context, gate-work frames execution against an existing gate.

Reference Files

• ${CLAUDE_PLUGIN_ROOT}/skills/gate-plan/references/gate-template.md — Gate document conventions: section ordering (phases, errata, notes, status), checkpoint ID format, bypass markers, anti-pattern tags, and verification method placement.
• ${CLAUDE_PLUGIN_ROOT}/references/anti-pattern-registry.md — Named failure modes catalog. Read during Step 2 to understand what failure modes tagged checkpoints guard against, informing verification rigor.