Review, approve, request changes

After every reviewed step, the pipeline stops and waits for a person. You read the draft, then approve it — which unlocks the next step — or ask for changes, which sends it back to the agent. This page covers both decisions and what they change.

Which steps wait for review

Six steps finish as Awaiting your review: RFP (when the agent drafts it), Scope, SRS, SDS, STS and Proposal. Tasks, Compliance and Traceability have no review gate; they are complete as soon as they finish.

An uploaded RFP needs no review: uploading it records it as approved by you.

Awaiting your review

A step waiting for you shows, on its turn in the conversation:

• the status Awaiting your review;
• a document card with the document's name, its version (for example v1) and "Draft, awaiting approval", with a Read button;
• Approve and Request changes, and the reminder "Read it first — the document opens beside this chat."

The composer also says, for example, "/srs is waiting on your review above.", and the step rail marks the step Awaiting your review. A step waiting for review has no run button: you decide on it from its turn.

Read the draft

Press Read on the document card. The document opens in a panel beside the conversation (on a narrow screen, in a sheet over it), so you can read and decide without losing your place. The card shows Open while its document is showing.

• Drag the divider between the conversation and the panel to give the document more or less width, or focus it and use the arrow keys.
• Use the contents panel to jump between sections, and Preview / Markdown to switch between the rendered document and its source.
• Close the panel with its close button or Escape.

The reader's header marks a draft as Draft · under review. See Read and export documents for everything the reader does.

Approve

Press Approve. Alara Code:

1. stores the approved version of the document permanently;
2. records the approval — who approved it, which version, and a fingerprint of its exact content;
3. marks the step Approved and unlocks the steps that were waiting for it.

A notification confirms it: "/scope approved — the next phase is unlocked." The reader's badge changes to Approved.

What approval unlocks

Tasks and Compliance unlock when the STS has been produced, and Traceability when the SDS has been produced; they do not wait for an approval.

Who may approve

Approving needs the Projects › Run permission, the same as running a step, and a bound agent. Anyone who can open the project and has that permission may approve — including a step someone else ran. Without it, Approve and Request changes are disabled and say which permission is missing when you hover them.

Approval is refused while any step in the project is running: "A command is running for this project. Wait for it to finish before approving."

Request changes

When the draft needs work, press Request changes. The composer turns into a change list for that document, headed "Request changes to /srs — Requirements Spec":

• Write one change per line. Enter applies the list; Shift+Enter starts the next change. The counter shows how many changes you have written.
• Be specific. The placeholder suggests the style: "Downgrade REQ-FUNC-027 priority to could", "Fix the blank BR-001 statement".
• Escape or Cancel abandons the request.

When you apply, "Only /srs is regenerated with these changes, then it comes back for review." A new run starts for that step, the agent revises the draft under review with your changes, and the result lands back at Awaiting your review.

Versions while you iterate

Requesting changes rewrites the draft in place: a draft keeps its version number however many times you revise it. The document's version moves on only after approval — see "Re-running an approved step" below. The document's Version History table records each revision.

When Request changes is refused

Re-running an approved step

To change a document that is already approved, run its step again with the re-run button on its row in the step rail. The agent writes a fresh document, which becomes the next version (v2 after v1) as a new draft, Awaiting your review. Approve it or request changes as before.

If the re-run produces exactly the same document as the approved one, the run fails with "…did not produce a new version — the artifact is unchanged since the last approval, so there is nothing to review." The approved version stands.

What a new version resets

Approvals are tied to a fingerprint of the exact document that was approved.

• The regenerated step's own approval re-opens. Its new version must be reviewed and approved again.
• Approved documents after it keep their approval, but they were built on the older version. They are marked stale: their rows read Approved · upstream changed. Re-run them, in order, to rebuild them on the new version.
• A step that needs the regenerated step's approval, and has not run yet, stays locked until you approve the new version.

For example, re-running /scope after the SRS and SDS are approved puts the Scope back to Awaiting your review; the SRS and SDS stay approved but show re-run, upstream changed. Once you approve the new scope, re-run /srs, review it, then re-run /sds.

Replacing the RFP with Replace RFP has the same effect on what was built from the old one.

Drawing diagram…

Start a new version

Once every document from the RFP to the proposal is approved (and none is stale), the conversation ends with a card: Version 1.0 is complete, and a Start version 2.0 button. A new version is how you change the whole document set when the project changes — a new feature, dropped scope, a moved deadline.

1. Press Start version 2.0. The dialog asks for the version name (suggested: the next whole number, e.g. 2.0 or Phase 2 — a name already used is refused), What should change? — describe the changes as specifically as you can — and what to do with the RFP:

   • Keep the RFP — the approved RFP stays; the documents from Scope on are revised.
   • Upload a new RFP — pick a file (PDF, Word, text or Markdown) that already contains the changes. It replaces the RFP for this version and is approved as it uploads, so Scope opens straight away. If the upload fails, the version is still started and Upload RFP waits in the step rail.
   • Revise the RFP — the RFP reopens first. Run it and the agent applies your changes to the RFP you created or uploaded (an uploaded file is revised from its text); review it, edit it if you like, and approve it before Scope opens.

   The box below the choice, What happens next, lists the steps that will reopen, in order, for the choice you made.

2. Press Start version. A divider in the conversation marks where the version began, with the changes you asked for. The step rail shows Version 2.0 · In progress and how many of its five documents are revised.
3. Scope, SRS, SDS, STS and Proposal reopen, in that order — after the RFP when you chose to upload or revise it. Each step unlocks when the one before it is approved in this version. While each new draft is under review you can edit it yourself or request changes; see Edit a draft.
4. Run each step. Instead of writing its document afresh, the agent revises the version you approved last — keeping every section, id and sentence the changes do not touch — and the result comes back for your review as the next document version (v2 after v1). Request changes and approve exactly as before. Each step also works from the documents approved before it in this version — the revised RFP, Scope, SRS and so on, including any edits you made to them — which the agent treats as authoritative; see Your edits carry forward.
5. Approving the Proposal completes the version, and the card offers the next one.

Traceability, Compliance and Tasks can run again once the documents they need are approved in the new version. Nothing can start a version while a step is running.

Drawing diagram…

Under the hood

Approve posts POST /api/projects/:id/approvals/:phase. Request changes posts POST /api/projects/:id/commands/amend with the step and the list of changes; the amend runs through the same machinery as a normal run and lands in review again. An approval stays valid only while the document's content hash matches the hash recorded when it was approved. See Document checks and versioning and How the pipeline works.