Gate

A synchronization checkpoint that pauses execution until an explicit external resolution is received.

Overview

Gates introduce controlled pauses into plan execution. When execution reaches a Gate node, downstream tasks are suspended until the gate is explicitly resolved.

A gate may be resolved by humans, automated systems, policies, or external services. This allows plans to incorporate authorization, review, coordination, or waiting on real-world events that cannot be determined by execution alone.

Gates are commonly used for:

Human approvals — security reviews, compliance sign-offs, quality gates
Policy evaluations — automated checks against organizational rules
Quorum decisions — N-of-M approval requirements
External signals — waiting for webhooks, events, or other systems
Inter-plan coordination — one plan unblocking another

Once resolved, the gate produces a deterministic outcome that determines whether execution resumes or terminates.

Schema

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: string          # Required, unique identifier
  namespace: string     # Required, resource namespace
  labels: object        # Optional, key-value pairs
  annotations: object   # Optional, metadata
spec:
  gateType: string      # Required: approval | review | sign-off
  targetRef:            # Required, what this gate controls
    kind: string        # Target resource kind (e.g., Execution)
    name: string        # Target resource name
    apiVersion: string  # Optional, target API version
    namespace: string   # Optional, target namespace
    uid: string         # Optional, target UID
    nodeId: string      # Optional, specific node in a plan
  description: string   # Optional, purpose of the gate
  reviewers: string[]   # Optional, who can resolve
  requiredApprovers: number  # Optional, minimum approvals needed (default: 1)
  context: object       # Optional, additional context data
status:
  phase: string         # Pending | Waiting | Approved | Rejected
  conditions: object[]  # Status conditions
  reviewHistory: object[]  # History of resolution actions
  resolution: object    # Final resolution details
  observedGeneration: number  # Last observed generation
  decidedGeneration: number   # Generation when decision was made

Fields

Spec Fields

Field	Type	Required	Description
`gateType`	string	Yes	Type of gate: `approval`, `review`, or `sign-off`
`targetRef`	object	Yes	Reference to the controlled resource
`targetRef.kind`	string	Yes	Target kind (typically "Execution")
`targetRef.name`	string	Yes	Name of the target resource
`targetRef.apiVersion`	string	No	API version of the target resource
`targetRef.namespace`	string	No	Namespace of the target resource
`targetRef.uid`	string	No	UID of the target resource
`targetRef.nodeId`	string	No	Specific node ID in a plan graph
`description`	string	No	Purpose of this gate
`reviewers`	string[]	No	Who can resolve (e.g., "team:security", "user:alice", "svc:policy-engine")
`requiredApprovers`	number	No	Minimum number of approvals required (default: 1)
`context`	object	No	Additional context data for reviewers

Status Fields

Field	Type	Description
`phase`	string	Current gate phase
`conditions`	object[]	Status conditions with type, status, reason, message
`reviewHistory`	object[]	Array of review actions taken
`resolution`	object	Final resolution details (required when phase is terminal)
`observedGeneration`	number	Last observed spec generation
`decidedGeneration`	number	Spec generation when decision was made

Gate Phases

Phase	Description
`Pending`	Gate created, waiting to become active
`Waiting`	Gate active, awaiting resolution
`Approved`	Gate resolved positively, execution may proceed
`Rejected`	Gate resolved negatively, execution blocked

Gate Types

Type	Purpose
`approval`	General approval to proceed
`review`	Code, design, or artifact review checkpoint
`sign-off`	Formal sign-off (compliance, legal, security)

While the schema defines three gate types, the resolver can be human or automated. Use the reviewers field with prefixes like svc:policy-engine or svc:external-webhook to indicate automated resolvers.

Review History Entry

Field	Type	Required	Description
`reviewer`	string	Yes	Identity of the reviewer
`action`	string	Yes	Action taken: `approve`, `reject`, `comment`
`timestamp`	string	Yes	When the action was taken (RFC3339)
`comment`	string	No	Optional comment or reason
`targetGeneration`	number	No	Spec generation this action was taken against

Resolution Object

Field	Type	Required	Description
`outcome`	string	Yes	Final outcome: `approved` or `rejected`
`actors`	string[]	No	Identifiers of reviewers who contributed
`timestamp`	string	Yes	When the resolution was made (RFC3339)
`comment`	string	No	Optional summary comment

Examples

Human Approval Gate

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: security-review
  namespace: default
  labels:
    stage: pre-production
spec:
  gateType: review
  targetRef:
    kind: Execution
    name: user-auth-execution
    nodeId: security-review
  description: Security team must review authentication implementation before production deployment
  reviewers:
    - team:security
    - user:security-lead@example.com
  requiredApprovers: 2

Compliance Sign-off Gate

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: compliance-sign-off
  namespace: default
spec:
  gateType: sign-off
  targetRef:
    kind: Execution
    name: user-auth-execution
  description: Compliance sign-off for handling PII data
  reviewers:
    - team:compliance
  requiredApprovers: 1

Automated Policy Gate

Use approval type with a service account reviewer for automated policy checks:

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: cost-policy-check
  namespace: default
spec:
  gateType: approval
  targetRef:
    kind: Execution
    name: infrastructure-deployment
  description: Automated check that infrastructure changes are within budget
  reviewers:
    - svc:cost-policy-engine
  requiredApprovers: 1
  context:
    policyRef: cost-limits
    maxBudgetIncrease: 1000

External Webhook Gate

Use approval type with a service account for external system integration:

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: dependency-ready
  namespace: default
spec:
  gateType: approval
  targetRef:
    kind: Execution
    name: integration-tests
  description: Wait for upstream service deployment to complete
  reviewers:
    - svc:deployment-webhook
  context:
    webhookUrl: https://deploy-status.example.com/callback
    expectedSignal: deployment-complete

JSON Schema

The full JSON Schema is available at: Gate Schema

Next Steps

Execution - Track plan execution with gates
Plan - Define the tasks that gates protect
Concepts: Goals, Tasks & Gates - Learn more about gates