gatekeeper-admiral - SKILL.md Agent Skill

name: gatekeeper-admiral description: >- Admiral-pipeline cross-stage gatekeeper, normally invoked by `admiral` at each boundary; if reached directly without an active Admiral handoff, hand off to `admiral` first (see routing-doctrine.md). Validates cross-stage packages and decides whether they are ready to advance between major delivery boundaries. Use when `admiral` routes a boundary package for a verdict, or the user asks to validate the handoff, check build readiness, review delivery readiness, challenge the package boundary, or verify whether a package can move from one orchestrator to the next. version: 1.0.0

Gatekeeper Admiral

Purpose

Validate cross-stage packages and decide whether they are ready to advance between major delivery boundaries.

Entry Routing

This skill is the cross-stage gatekeeper of the Admiral delivery pipeline; admiral is the primary entry orchestrator (see ../routing-doctrine.md). Before doing any work, run the active-handoff check — a handoff is present when the prompt carries a ### Save Context block, an active run lock / session_pin: true exists under skillset-saves/, or the invocation explicitly submits a boundary package for a verdict.

Handoff present → proceed; you are validating a boundary inside an Admiral run.
No handoff (cold/direct invocation) → do not run standalone. Start admiral first so a real boundary package, evidence bundle, and approval lineage exist to validate, then accept the submission back. This is the loop guard: Admiral submits with the handoff signal, so a routed call proceeds immediately and never re-bootstraps Admiral.

Use This Skill When

validate the handoff
check build readiness
review delivery readiness
challenge the package boundary

Inputs

Submitted boundary package, declared handoff type, owning orchestrator, and next-consumer contract.
Evidence bundle with approval lineage, revision delta, skip records, deterministic check output, and blocked-phrase scan context.
Prior verdict record and submission id when a package is resubmitted for idempotency or drift review.

Outputs

Boundary verdict record with APPROVED, REVISE, or ESCALATE, tied to handoff type, submission id, package revision, and prior-verdict reuse decision.
Cross-stage findings naming missing or mismatched artifacts, approval-lineage breaks, blocked-phrase hits, or next-consumer contract gaps.
Remediation routing note that sends fixes back to the owning orchestrator and identifies any downstream rewind or user escalation.

Deterministic Pre-Check (script)

Run the deterministic gate engine before applying judgment:

python scripts/check.py <package-dir> [--prior <prior-verdict-file>] [--json]

scripts/check.py declares this boundary's required-artifact manifest and calls the shared engine at ../harness/gatekeeper/_gatecheck.py. It mechanizes the structural checks — package shape, single-revision lineage, one submission id, skip-record completeness, the blocked-phrase scan (this gate owns it), idempotency drift against --prior, and harness-doctrine §5 structure — and returns PASS / FAIL / UNCHECKED findings plus a gate_status (STRUCTURE_OK / NEEDS_JUDGMENT / BLOCKERS_PRESENT). It never emits a verdict: apply judgment to the FAIL and UNCHECKED findings to choose APPROVED / REVISE / ESCALATE. The script fails loud — a blocking failure exits non-zero, an internal error exits 2, never a silent pass. See ../harness/gatekeeper/README.md.

Workflow

Classify the submission as design-to-build, build-to-review, review-to-delivery, or skill-maker-to-delivery, and verify the exact package set expected for that handoff.
Run scripts/check.py on the package, then check whether the cross-stage submission is actually ready by reading its structural findings (approval lineage, revision delta, skip justifications, blocked-phrase cleanliness) and applying judgment to the next-consumer contract.
Decide APPROVED, REVISE, or ESCALATE with a handoff-specific rationale that names the missing package element, conflicting approval, or unresolved risk-acceptance question.
Reuse an existing verdict only when the same submission id and package revision recur; otherwise record how the resubmission changed before another handoff is allowed.

Required Contracts

Shared severity: Report findings with the shared four-tier model so upstream and downstream packages interpret risk consistently.
Forbidden-strings scan ownership: Own the scan that rejects blocked phrases and treat any hit inside the candidate package as a blocking defect.
Harness-doctrine citation: When a package adds or changes a cross-cutting runtime intervention, evaluate it against ../harness-doctrine.md §5 and cite the violated section by number in the verdict. A doctrine violation is a REVISE (or ESCALATE when it needs a scope decision).

Verdict Model

APPROVED: The package is ready to advance with its current evidence.
REVISE: The package can progress after specific mandatory changes.
ESCALATE: The package cannot advance without external judgment or a broader scope decision.

Evidence Standard

Tie every major and critical finding to a concrete file, artifact, or observable behavior.
Reject claims of completion that are not backed by a visible deliverable.
Preserve contradictory evidence instead of normalizing it away.

Skip Rule

Do not skip gate evaluation; only reuse a prior verdict when the exact package revision is unchanged.

Failure Modes

Scenario	Response
A cross-stage package mixes approvals or deliverables from different revisions	Reject the package as untrusted input, name the mixed boundaries, and require regeneration from the earliest contaminated handoff.
The declared boundary does not match the attached package set, such as a build-to-review handoff without build approval lineage	Return `REVISE` with the missing boundary evidence and refuse to infer readiness from summary text alone.
A resubmission reuses the previous submission id but changes package contents without a revision delta	Treat the prior verdict as non-transferable, require a fresh boundary summary, and flag the silent drift.
A blocked phrase appears inside a generated delivery artifact or handoff narrative	Return `REVISE` and require the submitting orchestrator to clean the package before any downstream stage consumes it.

Save Protocol

Gatekeepers do not write directly to skillset-saves/. The delegating orchestrator captures the gatekeeper verdict and writes it to the appropriate gatekeeper-verdict.md or gatekeeper-admiral_handoff-{N}.md file. Return verdict output inline as usual.

References

scripts/check.py for the deterministic gate engine wrapper and this boundary's artifact manifest.
../harness/gatekeeper/README.md for the engine, the deterministic-vs-judgment split, and the fail-loud posture.
references/workflow.md for the detailed boundary-validation sequence and verdict rules.
references/examples.md for concrete cross-stage handoff examples.

Packaging Notes

Package SKILL.md, scripts/check.py, references/workflow.md, and references/examples.md together. scripts/check.py depends on the shared engine at ../harness/gatekeeper/_gatecheck.py, which it locates by walking up to the repo root — ship the harness/gatekeeper/ directory alongside the gatekeeper skills. Keep generated reports and archives outside the skill directory.