## Purpose

A human approval checkpoint pauses a consequential action and hands a bounded
decision to an accountable person. It presents the requested outcome, the exact
action, the evidence, the evaluator's verdict, and unresolved risks. The person
can approve, reject, or request a revision.

The approval applies only to the reviewed subject and action. It should be
recorded as a scoped authorization that the executor can verify, not as a chat
message that a worker interprets.

## When to use

Use a human checkpoint when policy assigns final authority to a person or when
the consequences exceed what the automated controls may authorize. Examples
include production deployment, irreversible migration, access expansion,
customer-facing publication, legal or safety claims, and unusual financial
commitments.

Do not require approval merely because a workflow contains an agent. Routine,
low-risk actions with tested policy and evaluation paths can stay automated.
Place human attention at the boundary where judgment, accountability, or risk
ownership is required.

## Inputs and outputs

Inputs:

- the intent brief and current version;
- the proposed action, target, and subject digest;
- the sealed evidence packet;
- policy and evaluator decisions;
- known gaps, warnings, rollback information, and expected impact;
- the approver role and expiry policy.

Outputs:

- `approved`, `rejected`, or `revision-requested`;
- the approver identity and role;
- a timestamp, expiry, and single action digest;
- an optional reason or requested change;
- a signed or otherwise verifiable approval reference for the executor.

## Smallest useful interface

```ts
type ApprovalRequest = {
  intentRef: string;
  action: string;
  target: string;
  subjectDigest: string;
  evidencePacketRef: string;
  policyDecisionRef: string;
  evaluationRef: string;
  risks: string[];
  expiresAt: string;
};

type ApprovalDecision = {
  requestDigest: string;
  result: "approved" | "rejected" | "revision-requested";
  approver: string;
  approverRole: string;
  decidedAt: string;
  expiresAt?: string;
  reason?: string;
};

function recordApproval(
  request: ApprovalRequest,
  decision: Omit<ApprovalDecision, "requestDigest">
): ApprovalDecision;
```

The executor should accept an approval only when the approver has the required
role, the request digest matches, the approval is current, and no newer artifact
has replaced the reviewed subject.

## Example

A checkout change has passed its evaluator and reached the production policy
gate. The policy requires an on-call release approver. The checkpoint displays:

```yaml
intent: checkout-timeout-fix@2
action: Deploy checkout-api release 2026.08.13.3 to production
subject: sha256:94ab...
evaluation: pass
policy: review required for production
evidence:
  focused-timeout-test: pass
  checkout-integration-suite: pass
  release-artifact-digest: sha256:94ab...
known-risks:
  - The change adds a new retry response on one upstream timeout path.
rollback:
  - Redeploy release 2026.08.12.5 using the existing release procedure.
expires: 2026-08-13T12:30:00Z
```

The approver selects `approved`. The checkpoint issues a decision bound to the
production target and release digest. If a worker rebuilds the release, the new
digest requires a new approval even when the source diff appears unchanged.

## Failure modes

- **The request asks only "approve?"** The person cannot see scope or
  consequence. Show the action, target, artifact, evidence, gaps, and rollback
  information in a compact decision view.
- **Approval applies to a moving branch or latest release.** The subject can
  change after review. Bind approval to an immutable digest.
- **A chat reaction becomes authorization.** The executor cannot verify who
  approved what. Record a structured decision through an authenticated path.
- **The only easy action is approve.** This encourages a rubber-stamp path.
  Give rejection and revision equal visibility and require no workaround to
  stop the action.
- **Every workflow requests human review.** Repeated low-value prompts consume
  attention and hide unusual risk. Use policy to reserve checkpoints for named
  boundaries and exceptions.
- **The approver lacks the relevant role.** Identity alone is not authority.
  Resolve the required role at decision time and record it.
- **The request expires but execution continues.** Verify freshness at the
  execution boundary and request approval again after expiry.
- **New evidence arrives after approval.** Treat changes to the subject,
  required evidence, or risk statement as a new request.

## What it does not solve

A human checkpoint does not guarantee that a person will notice every defect or
make the best decision. It cannot compensate for missing evidence, a misleading
summary, or an approver without enough context. It also does not replace access
control at the execution platform. Its job is narrower: preserve human
authority at a named boundary and make the resulting authorization specific,
visible, and enforceable.

## Related reading

- [Intent brief](/components/intent-brief)
- [Policy gate](/components/policy-gate)
- [Evidence packet](/components/evidence-packet)
- [Independent evaluator](/components/independent-evaluator)
- [Your agent should not be its own reviewer](/notes/control-loop/your-agent-should-not-be-its-own-reviewer)