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.
By the end of this page you will know what a baseline is, how to compose one from the records the team approved, how the project manager's approval freezes it and what that freeze does to every record it holds, how the client signs a scope baseline as a second gate, how a frozen baseline is read and superseded, and the one way a frozen record changes afterwards: an approved change request.
A baseline is a named set of approved records frozen together: the scope the client signs before the build starts, what a release ships, what a sprint commits to, what a milestone promised. Until it is frozen it is a draft list anyone with the permission composes and recomposes. Once the project manager approves it, every record it holds is pinned to the version that was approved and locked: the record's editor, its status menu and its restore button all refuse until a change request that names the baseline and the record is approved. A scope baseline then goes to the client's stakeholders for their signature, and the record the project is held to is the one they signed. Three Norns hold the frozen record; nothing moves without their say.
Before you begin
| To | You need |
|---|---|
| See the baselines | baseline:view-any and baseline:view; a client guest sees the frozen ones |
| Compose a draft and change it | baseline:create, baseline:update |
| Submit a draft for approval, ask for the sign | baseline:freeze |
| Approve a baseline | To be named by the project's Baseline approval policy; the project manager role by default |
| Sign a scope baseline | A stakeholder seat flagged Approves requirements with your guest account linked to it |
| Supersede a frozen baseline | baseline:update |
| Delete a draft | baseline:delete |
Only approved records join a baseline: an epic, a story, a requirement, a business rule or a use case that carries a version. Approve the records first through their own approval; the picker offers nothing else.
Open the page
Baselines in the project's sidebar opens the page, under its Baselines tab; the Change Requests tab beside it is the other half of the same family. The badge on the sidebar entry counts the change requests still open, not the baselines. The list shows each baseline's name and the first line of its description, its kind, its status, how many records it holds, when it was frozen, when the client signed it (a dash on a kind the client does not sign) and when it last changed. Sort by name, kind, status, the frozen date, the signed date or the last change; filter by kind or status, or search by name; Clear Filters drops every filter.
A client guest opens the same page and sees the frozen baselines only: approved, awaiting the client's signature, signed, or superseded. A draft or a baseline in review is not theirs to see.
Compose a draft
Press New Baseline. The editor asks for a Name, unique within the project (v1.0 scope, Release 1.1, Sprint 3), a Kind and an optional Description of what the baseline marks and why it was cut; the client reads the description beside the records. Under Records, the picker lists every approved record the project holds, each with its family, its key and its title (Requirement · CRM-FR-12 Password reset by email (v2)); pick the ones the baseline freezes. Press Create Baseline.
The draft is written with its records in the order you picked them, every record noted at the version it is approved at today; nothing is frozen yet. A draft changes freely: Edit Baseline in the row menu or Edit in the flyout reopens the editor with the name, the kind, the words and the records, and Save Changes writes them, dropping the records you removed and adding the ones you picked. Every save is a version of the baseline.
Four kinds, one engine
Scope, Release, Sprint and Milestone differ in one way: a scope baseline is signed by the client after the team approved it. The other three are frozen by the team's approval alone. Pick the kind before you submit; it is part of the record the approvers read.
Submit it for the team's approval
Open the baseline's flyout. The Approval bar offers Submit for review once the draft holds at least one record; an empty draft cannot be submitted. Write a few lines for the approvers under Summary and confirm. The baseline moves to In review, the approvers of the project's Baseline approval policy are told (the project manager role by default, under the Any one approver rule), and the draft stops changing until they answer.
What the approval does when it carries:
- The baseline becomes Approved at version 1, stamped with when it was frozen and by whom.
- Every record it holds is pinned to the revision that was approved and marked frozen.
- A requirement or a business rule it holds moves from Approved to Baselined, with a version written under the reason baselined; an epic, a story or a use case keeps its status.
- Each record is now locked: editing it, moving it, deleting it or restoring an earlier version of it is refused with the baseline named, until a change request that names it is approved.
baseline.frozengoes out besidebaseline.status_changed, with the number of records held.
A rejection returns the baseline to Draft with nothing frozen; the approver's reason is on the request. A request for changes holds it until you edit the draft and resubmit.
Have the client sign the scope
A frozen scope baseline shows a callout under its approval bar: Frozen by the team. Submit it again from the approval bar to ask the client's stakeholders to sign the scope. Press Submit for review again. This second submission opens a Client sign-off, not a baseline approval: the approvers are every stakeholder of the project flagged Approves requirements whose guest account is linked to their seat, under the Every approver rule, so the scope stands signed only when each of them agrees. The baseline reads Awaiting sign-off meanwhile, its records as locked as before.
When every stakeholder approves, the baseline becomes Signed off at version 2, stamped with the
date of the signature; the callout turns green and names the date, and baseline.signed_off goes
out. A stakeholder who rejects returns it to Approved, still frozen, with their reason on the
request; the team reads it, raises what it must as a change request, and asks again. A release,
sprint or milestone baseline never takes this step: its approval is its last gate.
Nobody to sign
The sign-off resolves its approvers from the stakeholder seats, not from the policy's roles. A project whose stakeholders have no linked guest account, or none flagged as approving requirements, cannot submit the sign-off; the message says so. Flag the seats and invite the people under stakeholders first.
Read a frozen baseline
Open a row for the flyout: the kind, the status and the version as badges, the name, the approval bar with the request that froze or signed it, the client callout on a scope baseline, the description, and the Records table: each record's key, title, the version held and whether it is Held, Unlocked by a change request, or still a Draft row of a baseline not yet frozen. Below sit the clocks (frozen and by whom, signed off, created, updated), the Versions of the baseline itself, its links, files and comments, and Activity. A client guest reads the same flyout without the versions, the links and the activity.
Open a record held by the baseline and its own flyout says so too: the editor is refused with the baseline's name, and the status menu offers nothing the lock forbids.
Supersede a baseline
A frozen baseline is never edited and never deleted; it is the record. When a newer baseline replaces it, choose Move to → Superseded in the row menu or the flyout. A superseded baseline stays readable with every stamp it carried, but it no longer holds its records: a record only it held is free to change again, and a requirement or a rule that still reads Baselined is moved on by hand or by the next baseline that holds it. Only an approved or a signed baseline moves to superseded; the moves through In review, Approved, Awaiting sign-off and Signed off are the approval engine's and the menu does not offer them.
Delete a draft
Delete Baseline in the row menu or Delete in the flyout opens the confirmation. A draft is removed with its record rows and its versions; its name is free again. A baseline past its draft cannot be deleted; supersede it instead.
All the fields
What happens next
- Composing a baseline emits
baseline.created, and every change to its words or its recordsbaseline.updatedwith what changed (the records as the list of keys before and after). - The approval engine emits
approval.requested, the verdicts, andbaseline.status_changedon every move; the freeze addsbaseline.frozenand the signaturebaseline.signed_off, each with the approval that carried it and the version reached. - Superseding emits
baseline.status_changed; deleting a draft emitsbaseline.deleted; putting an earlier version of a draft back emitsbaseline.restored. - A frozen record refused over the API answers
BASELINE_LOCKEDwith the baseline's id in the error's context; the application shows the same refusal as a message naming the baseline. - The project overview and the sidebar count the open change requests; the releases will cut their scope from a release baseline, and the sprints from a sprint baseline, as those modules land.
Heimdall on this page
Heimdall reads baselines and composes them when asked: "Freeze the approved requirements and the loyalty epic as the v1.0 scope" composes the draft from the records it finds approved and tells you to submit it; "What does the signed scope hold?" lists the records and the versions held; "Which requirements changed since the client signed?" compares the held versions with the records as they stand. Heimdall never approves, signs or supersedes a baseline; those stay with the people named.
From the API and MCP
Baselines API
A project's baselines, one with its records, compose and recompose a draft, supersede a frozen one, delete a draft, the versions, and the submit door for both gates.
list_baselines and get_baseline
An agent reads the frozen record before it changes a requirement or a story, so a locked record is known before the refusal.
create_baseline and update_baseline
Compose a draft from approved records, recompose it, and supersede a frozen baseline on the person's word.
baseline.* events
Created, updated, status changed, frozen, signed off, restored and deleted.
Permissions
| Action | Permission |
|---|---|
| See the baselines and open one | baseline:view-any, baseline:view; a client guest sees the frozen baselines only |
| Compose a draft | baseline:create |
| Change a draft's words or records, supersede | baseline:update |
| Submit for approval, ask the client to sign | baseline:freeze, as staff |
| Approve | Named by the Baseline approval policy; approval:decide over the API |
| Sign a scope baseline | A stakeholder seat flagged Approves requirements, linked to the guest's account |
| Delete a draft | baseline:delete |
| Read and restore the baseline's own versions | baseline:view, baseline:update; staff only |
Frequently asked
Can I add a record to a frozen baseline? No. A frozen baseline is the record the client agreed to. Compose the next baseline with the new record and supersede the old one, or raise a change request if what changes is a record the baseline already holds.
A requirement reads Baselined but no baseline holds it. Why? Its status was moved by hand, which the status menu still allows for an approved requirement or rule. The lock comes from a frozen baseline, not from the badge; a requirement no frozen baseline holds is free to change whatever its badge says. The freeze and the unlock move the badge themselves.
The client signed, and now the scope must change. That is what a change request is for. It names the signed baseline and the records it touches; when the approvers and the stakeholder who asked agree, those records, and only those, are unlocked. The signed baseline keeps its signature.
Why can a guest see a baseline awaiting their signature but not one in review? A baseline in review is the team's draft under the team's gate. From the moment the team's approval freezes it, it is the client's record too, so every frozen status is visible to them.
Related
- Change requests — the one way a frozen record changes
- Approvals — the engine behind both gates, the policies and the inbox
- Signing off the scope — the client's side of the signature
- Revisions and versions — the versions a freeze pins
- Status reference — every baseline kind and status
- Stakeholders — the seats that sign
How is this guide?
Last updated on
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.
Change Requests
Raise a change request against a frozen baseline, name the records it touches, write or ask Heimdall for the impact on scope, schedule, effort, cost and risk, convene the council, submit it to the approvers whose agreement unlocks the records named, and see the change through to verified.