Approvals
Submit an epic, story, requirement, rule or use case for review, who decides under the project's policy, the inbox, resubmitting after changes, withdrawing, the clocks, and what a client guest signs.
By the end of this page you will know how a planning record becomes approved: who submits it, who the project's policy names to decide, what each verdict does, how a request is resubmitted after changes or withdrawn, where the inbox is, what the clocks do, how the policies are set, and what a client guest sees and signs.
An approval is a promise about a record: that the people the project named read this version and agreed to it. Zuse Bifrost keeps that promise literal. Submitting binds a request to the version of the record as it stood; every verdict is written once per person per round with a signature hash; carrying the request stamps the record approved at the next version, bound to the revision that was read. Nothing reaches Approved by hand any more: the status menu offers only the moves that are not the approval engine's.
Before you begin
| To | You need |
|---|---|
| Submit, resubmit or withdraw your own | The record's update permission (requirement:update, epic:update and so on), as staff |
| Decide a request | To be named on it by the project's policy, and to reach the project |
| Withdraw someone else's request | approval:withdraw |
| Read the inbox and a project's approvals | approval:view-any; a client guest reads only the requests that name them |
| Change a project's policies | approval:manage-policies |
| Submit a baseline, or ask the client to sign a scope baseline | baseline:freeze, as staff |
| Submit a change request | change-request:approve, as staff |
Approvals are on by default: every project starts with the workspace defaults for each kind, and a submission on a project nobody configured asks the project managers. Six kinds are open today: the Requirement review, the Baseline approval, the Client sign-off on a scope baseline, the Change request, the Document approval and the Sprint commitment; the other kinds are declared, documented below, and open with their modules.
What can be approved
The requirement review covers the five planning records that carry versions: an epic, a story on the backlog, a requirement, a business rule and a use case. Each shows the Approval bar in its flyout, under the action buttons. A story keeps its board status throughout; the other four move into In review on submission and into Approved when the request carries.
A baseline passes two gates on the same bar: the Baseline approval that freezes it and locks every record it holds, then, for a scope baseline, the Client sign-off by the stakeholders flagged as approving requirements, resolved from their seats rather than from the policy's lists. A change request passes the Change request gate, whose approval unlocks the baseline items it names; the stakeholder who asked for the change is added to its approvers beside the policy's people.
A generated document passes the Document approval: a rendered draft BRD or SRS is submitted from its flyout once it has a file, the project manager role answers by default, and the approval makes the copy Final, stamps its version and supersedes the kind's earlier final copy on the project, which is when the client's guests see it; a rejection returns it to Draft for the author to edit and render again.
A sprint passes the Sprint commitment: a planned sprint with its dates and its scope is submitted from its flyout, the project manager and the developer roles answer by default under the Any one approver rule, and the approval starts the sprint, stamping the points its scope held; a rejection returns it to Planned. Only one sprint of a project runs at a time, so a sprint cannot be submitted while another runs.
| Kind | Code | What it decides | Open |
|---|---|---|---|
| Requirement review | requirement_review | Epics, stories, requirements, rules and use cases before they count as approved. | Now |
| Client sign-off | client_sign_off | The client's word on a scope baseline or a UAT run. | Now |
| Test plan approval | test_plan_approval | A test plan before its runs may start. | Later |
| Baseline approval | baseline_approval | A baseline before its items are frozen. | Now |
| Change request | change_request | A change request before it unlocks the baseline it names. | Now |
| Deployment promotion | deployment_promotion | A deployment into a protected environment. | Later |
| Release go-live | release_go_live | A release before it goes to production. | Later |
| Post-mortem sign-off | post_mortem_sign_off | An incident's post-mortem before it is final. | Later |
| Document approval | document_approval | A generated document before it is final and shared. | Now |
| Timesheet approval | timesheet_approval | A member's week of time logs before it is locked. | Later |
| Sprint commitment | sprint_commitment | The team's commitment when a sprint starts. | Now |
Submit a record for review
Open the record's flyout. The Approval bar reads Not submitted for approval yet. and offers Submit for review (or Submit again once it carries a version) to someone who may change the record; a draft and an approved record that changed since can be submitted, a record already under review cannot. Press it, write a few lines for the approvers under Summary (what changed and why; they read it before the record) and press Submit for review again.
What happens on submission:
- The record's latest version becomes the version under review.
- Where the record has a review status, it moves into In review; a story keeps its board status.
- The approvers are resolved from the project's policy for the kind at that moment: everyone holding one of the named project roles (a membership on the project counts first, the team role on a whole-team project otherwise), the people named by name, and the stakeholder seats with a linked guest account. The list is written onto the request and does not move afterwards.
- Each approver is told through their alert destinations, with a button that opens the approval in the inbox. The person who submitted hears nothing; they raised it.
- The policy's clocks start: when the request is due, when the undecided approvers are nudged, when the request may carry by itself.
The bar then reads Waiting on 0 of 1 approvals; due in 3 days., lists the approvers as badges that fill in as they answer, and shows your summary. A submission on a project whose gate is switched off is approved at once and says so.
A gate that names nobody
A submission is refused when the policy is on and resolves to no one, for example a project with no project manager and nobody named. The message says so; name an approver under the project's settings or switch the gate off.
Decide
An approver sees three buttons on the bar, in the record's flyout or in the inbox: Approve, Request changes and Reject. Each opens a short confirmation with a Reason; the reason is required for a rejection or a request for changes when the project's policy says so, which it does by default, and optional otherwise. You decide once per round.
| Verdict | What it does |
|---|---|
| Approve | Counts towards what the rule needs. When enough approvers agree, the request carries: the record is approved at the next version, stamped with when and with the revision that was read. |
| Request changes | Holds the request. Nobody else decides until the author edits the record and resubmits it as the next round; the verdicts of the earlier round stay on the record. |
| Reject | Closes the request under every rule. The record returns to where it stood: draft when it was never approved, approved at its last version when it was. |
The policy's rule says how many approvals carry a request: Any one approver, Every approver, or A quorum of a set size. The bar shows the tally the whole time, and the person who raised the request hears about every verdict: an approval that does not yet carry it says how many are still needed.
Resubmit after changes
When an approver asked for changes, the bar reads who asked and on which round and offers Resubmit to someone who may change the record. Edit the record first; then press Resubmit, add new words for the approvers or keep the earlier ones, and confirm. The request opens the next round: pending again, the approvers resolved again from the policy, the clocks reset, the earlier verdicts kept below the line. The record never left review in between.
Withdraw
Withdraw takes an open request back. The person who raised it may always do so, and so may
anyone whose role on the project carries approval:withdraw; a client guest never may. The record
returns to where it stood and the request leaves the approvers' queues without a word to them. A new
submission later is a new request.
When an approved record changes
Editing an approved record does not take its approval away: the record stays approved at its version, and the bar shows Changed since with submit it again to approve the new version. A new submission opens a new request; its approval stamps the next version, and a rejection returns the record to approved at the version it had. Readers who must see only what was agreed, such as a client guest, see the record by its status, which an edit leaves as it is.
The inbox
Approvals in the sidebar, with a badge of what waits on you, opens the inbox: every request on the projects you can see, in three views:
- Waiting on me: the pending requests that name you and that you have not answered this round.
- Raised by me: everything you submitted, open or settled.
- All: everything you may read.
Filter by project, status and the record's family, or search by reference or title; sort by reference, title, kind, status or due date. Open a row for the flyout: the record's reference and title, who raised it and when, Open followed by its reference to its own page with the flyout showing, and the same approval bar as the record carries, so a verdict is taken here without leaving the inbox. A row past its due date shows the time in red.
The clocks
Every policy sets three optional clocks, in hours from the submission:
- Hours to decide: when it runs out, the request is overdue, the project's lead (or the team's
owner when the project names none) is told once, and
approval.escalatedgoes out. The request stays pending; the approvers may still decide. - Reminder after: the approvers who have not answered are nudged once.
- Approve by itself after: an unanswered request carries on its own, announced as an approval
with
autoset, and the author is told the time ran out.
The clocks are read every hour. A resubmission resets them for the new round.
Set the policies
Under the project's Settings, the Approvals section holds one editor per open kind. Each
starts from the workspace defaults and says so with a Workspace default badge until the project
saves its own, which turns it into Set on this project. A person without
approval:manage-policies sees a read-only summary.
- Rule and Quorum: how many approvals carry a request; the quorum applies to the quorum rule alone.
- Approver roles: tick the project roles whose holders approve. The guest role is never offered; the client's people are named through their seats.
- Named people: people asked whatever their role; each must be a member of the team.
- Stakeholder seats: the client's stakeholders; a seat with no linked guest account is listed for the record and cannot decide.
- Hours to decide, Reminder after, Approve by itself after: the clocks, 1 to 720 hours each; empty for none.
- Reason required on a refusal and Gate on.
A line under the fields says who the policy asks today, resolved live as you change it, or warns that nobody matches. Save Policy writes it; requests already open keep the approvers they were sent to. Fill with Defaults puts the workspace defaults back into the form without saving.
All the fields
What happens next
- Submitting emits
approval.requestedand, for a record with a review status, its family'sstatus_changedevent; the approvers are notified under the Approvals alert class. - Every verdict emits
approval.decided; what it settles emitsapproval.approved,approval.rejectedorapproval.changes_requestedbeside it, and the author is notified. - Withdrawing emits
approval.withdrawn; an overdue request emitsapproval.escalated; a saved policy emitsapproval.policy_updatedwith what changed. - An approval writes a version with the reason approval on the record, visible in its history; the request keeps the id of the version that was read.
- A client guest sees an epic, requirement, rule or use case from the moment it is approved, as before.
- A baseline's approval freezes it and emits
baseline.frozen; the client's sign-off emitsbaseline.signed_off; a change request's approval unlocks the baseline items it names and the request moves on by hand from there. See baselines and change requests.
Heimdall on this page
Heimdall reads approvals and never decides them. Ask "What waits on me?" or "Why is CRM-FR-12 still in review?" and it reads the inbox and the request with its verdicts. An agent working on a story can submit its draft for review once it is complete; the people decide. The council's requirement review is the reading to ask for before you approve a story, requirement or rule you are unsure of.
From the API and MCP
Approvals API
The inbox, a project's requests, one request with its verdicts, the submit door on each family, decide, withdraw and the policies.
submit_for_review
An agent submits an epic, story, requirement, rule or use case once its draft is complete, a composed baseline, or an analysed change request.
list_pending_approvals
The inbox in its three views, for an agent explaining what waits on whom.
approval.* events
Requested, decided, approved, rejected, changes requested, withdrawn, escalated and policy updated.
Permissions
| Action | Permission |
|---|---|
| Submit, resubmit or withdraw your own | The record's update permission, as staff |
| Decide | Named on the request by the policy; approval:decide over the API |
| Withdraw another person's request | approval:withdraw |
| Read the inbox and a project's requests | approval:view-any, approval:view |
| Change the policies | approval:manage-policies |
| Submit a baseline or ask for the client's sign-off | baseline:freeze, as staff |
| Submit a change request | change-request:approve, as staff |
Frequently asked
Can I approve my own submission? When the policy names you, yes; the engine does not refuse it. Name someone else on the policy where a second pair of eyes is the point.
The status menu lost In review and Approved. Where did they go? To the bar. Submitting moves a record into review; the approvers' decisions move it out. While a request is open, the status menu is closed; withdraw the request first.
What does a client guest see? Only the requests that name them through a stakeholder seat linked to their account, in the inbox and on the record once it is visible to them; they decide those and submit nothing. The sign-off of a scope baseline names every seat flagged as approving requirements, and a change request names the seat that asked for it. See approving as a client and signing off the scope.
Nobody was asked. Why? The policy's roles matched no one on the project. On a members-only project only membership rows count; on a whole-team project the team role counts too. Add a person to the project with the role, or name them by name.
Related
- Revisions and versions — the version an approval binds to, and the one it writes
- Project settings — where the policies live
- Stakeholders — the seats a policy may name
- Notifications — where the approvals alert class is routed
- Status reference — every approval status and verdict
- Approving as a client — the guest's side of the same request
- Baselines — the two gates a scope baseline passes on this bar
- Change requests — the gate whose approval unlocks a frozen record
How is this guide?
Last updated on
Revisions and Versions
Every save of a planning artefact, by a person or by Heimdall, writes a version with its diff, author and reason; read them in the flyout, the API or the tools, and restore any.
Baselines
Compose a baseline from approved records, submit it for the project manager's approval that freezes it, have the client sign a scope baseline, read what it holds, supersede it, and understand the lock a frozen baseline puts on every record it holds.