Viewport Docs

Viewport's launch approval model is intentionally simple:

route matches
  -> policy composes a plan gate
  -> tagged reviewer approves or requests changes
  -> worker continues only after the server records the decision

Do not configure hidden risk engines or workflow-specific user permission overrides for the first rollout. Use explicit org/team roles, team reviewer tags, and a committed .viewport/policy.yaml.

Launch-Safe Gate

Put the gate in .viewport/policy.yaml:

gates:
  - name: plan-review
    type: plan
    reviewers:
      tags: ["tech-lead"]
    timeout: 4h
    on_timeout: escalate

This means:

the agent drafts a plan before write steps continue;
the run blocks at gate_plan-review;
only current team members with the tech-lead reviewer tag should approve;
request changes keeps the run blocked and asks the worker for a revised plan;
approval lets implementation continue.

Viewport rejects policy sync when a gate references a reviewer tag with no matching team member. Fix the team membership or the tag before triggering a run.

Reviewer Tags

Use reviewer tags for human routing. They are team-scoped and should describe the decision responsibility, not the person's job title.

Good first tags:

Tag	Use
`tech-lead`	First plan review for engineering changes.
`security`	Changes touching auth, secrets, or sensitive data paths.
`support-owner`	Customer-facing support responses or docs updates.

Keep at least two people able to clear the first launch gate. A single reviewer creates a fragile rollout.

Request Changes

When a reviewer clicks request changes:

Viewport records the decision and reviewer note.
The run remains blocked.
The worker receives a workflow.approval_decision command.
The revision attempt runs in plan mode with no write/shell tools.
A revised plan reopens review.
Implementation stays queued until the revised plan is approved.

If that loop stalls, use Approval or plan revision is stuck.

Timeout Behavior

Use timeouts to make stuck gates visible:

gates:
  - name: plan-review
    type: plan
    reviewers:
      tags: ["tech-lead"]
    timeout: 4h
    on_timeout: escalate

Launch-safe values:

Field	Recommended launch value
`timeout`	`4h` for PM/plan gates; shorter only if the team agrees.
`on_timeout`	`escalate` for first rollout.

Avoid automatic approval in the first team rollout. Once the run path is proven and the team has audit expectations, you can design narrower automation with separate tests and proof.

What Not To Use For V1

These are not part of the launch approval model:

per-workflow user permission overrides;
broad auto-approval predicates;
Slack-only approvals as the only decision record;
direct production deploy approval;
direct push or merge to protected branches.

The run detail and audit trail in Viewport are the source of truth for approval decisions. Slack can notify and link people back to the run, but do not rely on Slack as the only review surface unless your workspace has separately tested that behavior.

First-Team Checklist

Before inviting the broader team:

.viewport/policy.yaml has exactly one initial plan gate;
the reviewer tag resolves to at least two current team members;
a non-reviewer cannot approve the gate;
request changes produces a revised plan and does not run implementation;
approval records the approver, message, and timestamp;
run detail shows the plan, decision, branch/PR receipt, Slack receipt, usage, and cleanup.

Where To Go Next

Reference: .viewport YAML. Exact gate fields.
Launch checklist. Acceptance bar before inviting a team.
Approval or plan revision is stuck.
Audit log. What decisions are recorded.

Approval policies