Reviews and approvals

Request review when a variation needs a person's sign-off before the work proceeds. Reviews and approvals require Business or Enterprise, docs:write and the organization's approvals feature to be enabled. Agents can request review; agents never approve.

Set the review rules

Open Settings > Design docs and enable Approvals, which is off by default in configurable organizations without saved settings. Under Variation types, edit the Spec, Implementation plan or another document type. Settings changes require org:manage.

Each type defines when it applies, the sizes that require it, approval counts for each size and eligible approvers. You can name people, select a team, or use both. With no people or team configured, anyone with write permission who meets the authorship rules can approve.

By default, Spec and Implementation plan require zero approvals for Small and Standard changes and one for Large. Evidence of work requires zero for every size and is optional. Sizes are off by default, so the Standard counts apply until you enable sizes. Journal types have no approval requirements.

Owners can approve their agent's work defaults to on for the presets. It lets a person recorded as an operator of agent-authored work approve it. Without that exception, a person who authored any version cannot approve the variation. The setting never permits an agent to approve.

Mark ready or request review

1. Finish the variation and its brief.
2. If its required approval count is zero, select Mark ready. This is the final required readiness action; an eligible person can add an optional approval stamp.
3. If the count is greater than zero, select Request review. The variation becomes In review. Eligible people open Approvals and select Approve.

Ready means the author has finished a variation that does not require approval. In review means required human approvals are still being collected. When enough valid approvals exist, the variation becomes Approved. The overall document status also depends on the other required variations.

Decide what an edit does to approvals

Each variation type has a stale-approval policy:

Under Let the writer decide, an agent sets changeIsMaterial and explains the choice with changeReason. A material edit dismisses approvals; wording or formatting changes can keep them. An omitted decision on an agent write counts as material. Live human edits leave a pending decision for a person to resolve. This decision controls existing approval stamps; it does not let an agent approve the new text.

Amend frozen text

An Approved variation is frozen while approvals are enabled. Shipping also freezes document variations. Open an amendment with a reason before changing frozen text. The next content or brief write consumes the amendment, dismisses approvals and returns a variation that requires approvals to In review. Finish open amendments before shipping.

Open History to read saved versions and their attribution, including the client and operator for agent writes. Compare versions in the diff view. The approval list keeps dismissed stamps with the version and reason that dismissed them, so you can see what a person approved before the text changed.

Use acceptance criteria to evaluate implementation claims. Approval of design text and verification of an implementation are separate facts.