Approval gate pattern

patterns specs/patterns/approval-gate.kmd

A paused step that waits for an authorized human to approve or reject a pending action — a deploy/release gate, a content-moderation hold, a sensitive-operation sign-off. Defines the decision surface (what + why + context), the authorization + reason rules, and the mandatory audit trail. Generalizes the AI-specific mcp-sampling-approval. GitLab Pajamas (manual job/deploy approval) parity.

Quando este padrão se aplica

Triggers primários

Todos os triggers

Pattern — Approval gate

Status: v0.1.0 — Draft. Promoted from the GitLab Pajamas parity scan (meta/docs/stack #093). Generalizes specs/ai-ui/mcp-sampling-approval.kmd (the AI-tool-call specialization). Source: https://design.gitlab.com/ (manual approval / protected environments).

R1 — When to use

A pending action blocks until an authorized human decides. Use for deploy/release gates, content moderation, refunds/payouts, destructive or irreversible operations, and policy sign-offs. Do NOT use for reversible, low-stakes actions (just do them, with undo).

R2 — The decision surface

Shows everything needed to decide without leaving:

  • What is pending (the action + target);
  • Context — a diff/summary/preview of the change and its blast radius;
  • Who requested it and when;
  • the current status (specs/components/state-label.kmd: Pending → Approved / Rejected);
  • Approve and Reject controls, plus an optional comment.

R3 — Decision rules

  • Approve releases the blocked action to proceed.
  • Reject blocks it and returns it to the requester; a reason is required on reject (specs/errors/user-facing-messages.kmd tone).
  • Decisions are final for that request (a new attempt is a new gate); never silently auto-approve on timeout (R5).

R4 — Authorization

  • Only users with the approver role/permission for that gate may decide; the controls are absent (not just disabled) for others.
  • Self-approval follows an explicit policy (allowed / forbidden / N-eyes); when forbidden, the requester cannot be the approver.
  • Multi-approver gates state the quorum ("2 of 3 approvals required").

R5 — Timeout, escalation, notification

  • A gate may expire after a configured window → it resolves to a safe default (block/cancel, never auto-approve) and notifies.
  • Pending gates notify the eligible approvers; resolution notifies the requester.

R6 — Audit (mandatory)

Every gate decision — approver identity, decision, reason, timestamp — is recorded in the specs/patterns/audit-log.kmd trail. An approval gate without an audit record is non-conformant.

R7 — Accessibility & i18n

  • The decision surface is keyboard-operable; Approve/Reject are real buttons with the destructive-ish Reject not the default focus.
  • Status conveyed by label text + icon, not color alone (WCAG 1.4.1).
  • All chrome (status, controls, reason prompt, quorum text) translatable per specs/i18n/contract.kmd.

Não-escopo

  • The AI tool-call approval specialization (specs/ai-ui/mcp-sampling-approval.kmd).
  • The pipeline/job engine that pauses (Koder Pipe / CI backend).
  • Role/permission definition (the tenant's RBAC model).

Referências