## Purpose

A policy gate decides whether a proposed action is permitted before that action
takes effect. It sits between proposal and execution. The gate reads structured
facts, applies a named policy version, and returns one of three decisions:
allow, deny, or require approval.

The worker that proposes an action may supply context, but it should not control
the gate, the policy, or the enforcement point. The component is useful only if
an allowed decision is required to proceed.

## When to use

Use a policy gate when a workflow can cross a boundary that should not depend on
model judgment alone. Common boundaries include writing outside an assigned
directory, merging a protected branch, deploying to a shared environment,
sending a customer message, changing account access, or spending above a set
amount.

Do not insert a gate into every internal step. Put it where an action changes
state or grants capability. A gate that runs constantly but controls nothing is
an audit message, not an enforcement mechanism.

## Inputs and outputs

Inputs:

- the proposed action, target, and requested capability;
- the actor and workflow run identifiers;
- the intent brief reference;
- relevant context from trusted systems, such as environment classification;
- the policy name and version to apply;
- evidence references needed by a rule.

Outputs:

- an `allow`, `deny`, or `review` decision;
- machine-readable reason codes;
- the policy version and input digest used for the decision;
- optional conditions, such as a time limit or approved target;
- a durable decision identifier for the execution record.

## Smallest useful interface

```ts
type GateRequest = {
  action: string;
  target: string;
  actor: string;
  intentRef: string;
  context: Record<string, unknown>;
  evidenceRefs: string[];
};

type GateDecision = {
  id: string;
  result: "allow" | "deny" | "review";
  reasonCodes: string[];
  policyVersion: string;
  requestDigest: string;
  expiresAt?: string;
};

function decide(request: GateRequest): GateDecision;
```

The executor should verify that the decision matches the exact request digest,
has not expired, and permits the requested target. It should reject a missing
or malformed decision.

## Example

A worker proposes a production deployment after tests pass:

```json
{
  "action": "deploy",
  "target": "production/checkout-api",
  "actor": "run-1842/implementation-worker",
  "intentRef": "checkout-timeout-fix@1",
  "context": {
    "environment": "production",
    "changeClass": "application-code"
  },
  "evidenceRefs": ["packet:run-1842:sha256:8f2c"]
}
```

Policy `deployments@7` requires human approval for every production target. The
gate returns `review` with reason code `PRODUCTION_APPROVAL_REQUIRED`. The
deployment service refuses to continue until a human approval checkpoint issues
an approval bound to the same action digest.

If the worker changes the target or artifact after approval, the digest changes
and the earlier decision no longer applies.

## Failure modes

- **The gate trusts free-form claims from the worker.** A worker can label a
  production target as staging. Resolve sensitive context from a trusted
  registry or execution environment.
- **Policies are not versioned.** A later audit cannot reconstruct why the gate
  allowed an action. Store the policy version with every decision.
- **An allow result can be replayed.** Bind the decision to the request digest,
  target, actor, and an expiry or single-use nonce where replay matters.
- **Missing context defaults to allow.** Treat unknown required facts as
  `review` or `deny`, based on the policy's stated fallback.
- **The worker can call the executor directly.** Move enforcement to the
  capability boundary. Hiding an executor in prompt instructions is not a gate.
- **Rules contain broad natural-language exceptions.** A model may interpret
  the same exception differently across runs. Use explicit predicates for
  enforceable rules and route true judgment calls to review.
- **Policy owners cannot test changes.** Add saved allow, deny, and review cases
  before publishing a new policy version.

## What it does not solve

A policy gate does not establish that an action is effective, that tests are
meaningful, or that supplied evidence is authentic. It does not replace
authorization at the underlying platform. It also does not make a poor policy
safe. The gate makes policy application visible and enforceable; policy owners
still have to define suitable rules and review their effects.

## Related reading

- [Intent brief](/components/intent-brief)
- [Evidence packet](/components/evidence-packet)
- [Human approval checkpoint](/components/human-approval-checkpoint)
- [Two-plane loop](/reference/two-plane-loop)