Approval gate pattern

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.

Status: v0.1.0 — Draft. Promoted from the GitLab Pajamas parity scan (metadocsstack #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 deployrelease gates, content moderation, refundspayouts, 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 diffsummarypreview 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 *eason 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 *afe

    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).