Submit and approve

<!-- Reviewed 2026-09-08 (no default team; team codes capped at three): the covered code lost one payload field (`isDefault` on `GET /api/teams?mine=true`, which no surface this page describes ever showed), renamed the team-less fallback helper, and had its comments corrected — the fallback itself is now the workspace's OLDEST team rather than its flagged one, which resolves to the same team on every workspace the app has made. New team codes are 2–3 characters; existing longer codes are untouched and keep numbering, because the numbers already issued cite them. Nothing this page states about behaviour changes. --> <!-- Reviewed 2026-09-02 (the renew loop — failed runs propose a fix to the document): src/lib/server/notifications.ts gained one kind, process.needs_attention, emitted when a document's process keeps failing or its connection is broken. It reaches the document owner or the team owners, not a submitter or a gatekeeper; the approval round trip this page describes is untouched. The notice itself is documented under Getting started -> Notifications. --> <!-- Reviewed 2026-09-02 (saving a document updates its processes and its agent): the covered lifecycle changed in what rides a submit — the save seam now runs after the submit's flush (the document's index and processes re-derive from the text), and the header states that review is what a document-control workflow's approval step USES rather than a gate the product imposes. Requesting, deciding and separation of duties are unchanged. --> <!-- Reviewed 2026-08-30 (one state, active): the covered documentLifecycle changed only in comments — its publish-time trigger sync stays, now as the LEGACY body-chip hook rather than the gate that decides whether a workflow runs. Accepting a workflow is what makes it act (store.ts), so nothing this page describes about drafts, review or publishing moved; the workflow story is authoring/workflows.md, rewritten in the same change. --> <!-- Reviewed 2026-08-30 (the workflow leaves the document body): the covered documentLifecycle changed only in its publish-time trigger sync, which is store-first behind the same call. Nothing about submit/approve moved; the workflow story is authoring/workflows.md, rewritten in the same change. --> <!-- Reviewed 2026-08-17 (versions are a COUNT — owner ruling): version labels are plain numbers now (v1, v2, v3); every act mints exactly the next one, and the editorial/material declaration is recorded on the version instead of changing it. Labels this page quotes were updated with that change. --> <!-- Reviewed 2026-08-17 (plain-name mentions): notifyCommentMention now takes the mentioned ids as data instead of parsing the body. Who is notified and what the notice says are unchanged — nothing THIS page documents moved. --> <!-- Reviewed 2026-08-26 (the Governance Automations feature deleted, owner directive): src/lib/server/notifications.ts LOST that failure notifier again — notifyAutomationRunFailed went with its one caller, the deleted automations executor. The review/approval notices this page documents are unchanged, and the register automations' own notifier is a different module that stays. The note below is the dated record of its arrival. --> <!-- Reviewed 2026-08-18: src/lib/server/notifications.ts gained an automations failure notifier (notifyAutomationRunFailed — documented under Getting started → Notifications and Intelligence → Automations). The review/approval notices this page documents are unchanged. -->

Every controlled document has one working draft. Nothing you type reaches readers until that draft goes through review and publishes as a new version. Use this page when you are ready to hand a draft to an approver, or when a review is waiting on your decision.

How a review is opened

There is no "Request approval" button in the app — on any kind of record. Opening a review is a server verb — the same one for documents, registers and risks — and it is called programmatically: today by integrations or administrative tooling, and by the automation layer when it is connected.

A review, however it was opened, is the same unit everywhere: a pinned copy, one human decision, one ledger.

Two things block a submit:

• Unresolved required inputs. If the document still has placeholders the template marked as required, fill them first.
• An archived document. Restore it before submitting.

Opening a review takes an exact, immutable copy of the draft. That copy is what the approver reads, what the decision is recorded against, and what publishes — nothing typed afterwards can reach it.

That copy is also what gets checked. Approving a review runs the same publish checks a direct publish does, against those pinned bytes rather than against the draft as it stands at the moment you decide — so approving cannot issue something different from what you read. One of those checks refuses a document that still carries bracketed placeholders like [the approving role]; another refuses a workflow chip that names a field its record does not have, or a connected source the document's team does not hold. If either fires, the approval is not recorded and the message names what is still open. See Publishing.

A pending review does not lock the record. On every kind — a document, a register, a risk — editing simply continues while the decision is out, and that is safe by construction: the approver is deciding on the pinned copy, and nothing typed afterwards can reach it. What a pending review does hold still is the review's own ground: a document's type and code cannot change while it is under review, the record cannot be archived until the review closes, and a direct publish waits for the decision (or a withdraw) rather than going around it.

Who is notified

Alchex notifies the Owners of the document's team, excluding you. They get an in-app notification whose Open button lands on My Approvals, where the review is ready to read and decide. Workspace admins and owners can also decide the review even though they are not on that notification list. To put the request in front of one named person, assign them — it then also appears in their My Approvals list.

Four things about a document reach a person's inbox:

Both outcomes of a review reach the person who asked for it. A rejection carries the reason; an approval says which version it published as, so "it went out as 2.0" is something you are told rather than something you go and check. An Owner publishing their own draft directly is not notified — they are the one who did it.

The notice lands in the submitter's inbox within about half a minute of the decision, so a review you are waiting on is not something you have to sit and refresh.

Each of the four can be switched off individually in Settings → Notifications — they are on until you turn them off. Worth knowing before you mute the first one: switching off "a document is waiting on your approval" stops the notice, not the work. The review still needs deciding; you have only asked Alchex to stop telling you about it.

Nothing else about a document notifies. In particular an ordinary reply on a thread you are part of does not, so naming someone is how you actually reach them.

The same inbox also carries notices from registers, from risks you have been made the owner of and actions on them assigned to you, and from long reviews that finish after you have moved on. Each is its own kind of notice rather than one general one, so you can tell them apart by scanning rather than by opening them. The full list is on Your inbox.

Who may approve

Deciding a review requires the Owner rung on the document's team. In practice that means a team Owner, or a workspace Owner or Admin (who count as Owner on every team). Writers and Readers cannot decide a review.

The separation-of-duties rule

The person who submitted a review cannot approve it. Alchex reads the submitter from the review record on the server, inside the same transaction that applies the decision — it is never taken from anything the browser sends, so it cannot be worked around by role. A workspace Owner who submitted the review is still refused, with the message: "You submitted this document for review, so you can't approve it yourself — another Owner has to decide it."

Two details matter, because they are easy to assume wrongly:

• The rule keys on the submitter, not the author. An Owner who wrote or edited the draft, or who happened to create it, may still approve it — as long as someone else submitted it. Contribution-level checks are out of scope; the activity log shows who touched what.
• You can still see your own review. The review screen opens for you and shows the footer "You submitted this draft — another owner must approve it". Your only actions there are Withdraw from review and reading the diff.

There is one sanctioned self-approval: the server's direct-publish verb, at the Owner rung — administrative tooling and the automation layer call it; the app offers no publish button. It is recorded in the log as a self-publish, and Alchex refuses it while someone else's review is pending — that review gets decided instead of published over.

Reading the review

While a review is pending, the record says so with one status line — a document's sits in its Document control section (In review — requested by …), and the other record types show the same line in their properties. The full story is the record's Activity trail. View changes on the My Approvals row opens the full comparison — the record itself carries no such door; on a document it takes over the whole document area, so the diff gets the full reading width. The review surface a decider reads is also where they can approve or request changes — reading and deciding stay together.

• The header answers "what am I deciding". The version step (v7 → v8 · replaces v7 for all readers), who requested the review and when, the fingerprint the decision will record, and the submitter's summary note. Counters for added, removed and edited blocks sit beside them — click one to focus on just that kind of change.
• The change index lists every change under the section heading it belongs to, with a short excerpt. Click an entry to jump straight to it in the document.
• Only changes is on by default: untouched passages collapse into a Show N unchanged blocks line you can expand in place, while the headings of changed sections stay visible so you keep your bearings. Turn the toggle off to read the document in full.
• Every changed block is labeled Added, Removed or Edited. Edited text shows the old wording struck through next to the new. Tables and other structured blocks show an explicit Was / Now pair instead of a word-by-word diff.
• Step change-by-change with the ↑/↓ arrows in the toolbar, or the J and K keys.

Reviewing an uploaded file. An uploaded file publishes the moment it is uploaded — it has no draft to submit, so this route is voluntary rather than the way its editions reach readers. When you do ask for one, a document whose content is a file has no line-by-line comparison to show, so the review shows the submitted file itself, exactly as it was submitted — alongside who submitted it, when, its fingerprint, and the name of the file it replaces. Approve and request changes work the same way. The editorial-or-material question is not asked — a file has no editorial half-step, so the next whole edition is minted for you and the confirm button names it. What you read is provably what publishes: the approval is pinned to that file's fingerprint. See External documents.

Deciding: approve, request changes, withdraw

The decision actions stay visible in the review header the whole time.

Approving an authored document is one click — there is no confirmation step. Every approval publishes the next version (v7 → v8) — nobody is asked for a number. Every approval is an editorial change by default; when the substance moved, tick Material change on the review surface first. The number is the same either way: what the tick records is that readers should re-read this one. (An uploaded file has no such toggle — see above.) If the submitted copy still carries unfilled [bracketed] placeholders, the surface says so up front and holds the approve button until they are resolved — see Publishing.

Approving is not reversible as a step — to undo it you publish a further version. Once a document has published, it can no longer be deleted at all; Archive retires it and keeps every version, approval and comment. See Publishing.

What publishes is what was submitted, and only that. If somebody kept typing while the decision was being made — which they are free to do — those words are not in that version. They are not lost either: the draft is never rewound to what published, so anything written during the review is still sitting in it, ready for the next round. Submitting and deciding also no longer depend on a separate editing service being reachable, so "try again shortly" is not an answer either of them can give any more.

Reviewing a second round

When an author addresses your comments and submits again, the review screen opens on the new submitted copy. The conversation from the earlier round is not attached to the review — it lives in the document's own Comments panel, in time order with everything else ever said about the document, so checking whether a point you raised was addressed is a matter of reading the panel beside the new copy.

My approvals

My Approvals in the sidebar's My work section is the one place decisions are made. It lists every pending review that awaits you — the ones routed to you by assignment, and the ones you hold the decide rung for in your teams (minus your own requests, which you can never decide). Each row carries Approve, Send back (with an optional note) and View changes, so a decider clears everything from one page; a document's View changes opens the document's full comparison, where the same decision buttons are available beside the diff. The "a review awaits you" notifications land here.

Reviews can also be routed to a person through the server's assign verb (an API act today — the same verb a future automation calls): being assigned puts the review on that person's My Approvals list and tells them once. It does not make them the decider — who may approve stays exactly as the sections above describe. There is no assign button in the app since the one-home cut: deciders already see everything they may decide, so routing is a nudge, not a requirement.

Automation can also open a review — a recurrence asking for a fresh sign-off submits exactly like a person and is recorded as what it is; deciding still always takes a person. When the requester is a document workflow, the row says so: a line under the record names the procedure that is stalled on your decision, with the procedure one click away — because approving or sending back is also what resumes that run. Person-filed reviews carry no such line.

A waiting review can also be nudged: a reminder notice that names the record and nothing else — no sender, because the nudge is about the work. Reminders and every other review notice have their own switches under Settings → Notifications.

Everything currently assigned to you, across every record type, is listed under My Approvals in the sidebar's My work section. Each row names the record, its type, who asked and when; opening the row takes you to the record itself, where the usual decision rules apply. When the review is decided or withdrawn, the row leaves the list — the record's own activity keeps the permanent trail. A decision a process is waiting on also shows in the team's Activity, pinned above the stream until it is made.

Document states

While a document is in review, its type and code are locked — other records cite it by those. A rename is allowed and applies from the version after the one under review.

Related: comments, publishing, versions, permissions.

<!-- Reviewed 2026-08-25 (workflow manager P1 — schema + repo): documentLifecycle's publish now also extracts workflow trigger chips into the workflow_triggers index (same write-through as citations, best-effort savepoint). No editor can place such a chip yet, so no published document contains one and publish behaves exactly as documented. Nothing this page documents changed. --> <!-- Reviewed 2026-08-26 (workflow manager P2 — the executor): the covered record routes gained post-commit workflow dispatch hooks (record created / submitted → runs; decisions → resume). No editor can place a workflow chip yet, so no published document declares a trigger and every documented flow behaves exactly as before. Nothing this page documents changed. -->