Reviewing and refining

Review is its own run

Four kinds of document carry a review-and-refine loop: the PRD, the RFC, the Feature Specification and the Feature-Slice Specification. review-prd and review-rfc are pipeline operations, and the pipeline does not advance past them. review-feature and review-feature-slice sit beside the pipeline: the specification is already sealed, so reviewing it advances nothing.

Every review reads the sealed bytes of the one revision it names, on the same independence terms: a run distinct from the author’s, read-only access to the subject and no inherited author reasoning. Each review issues one of five verdicts: PASS, PASS_WITH_ADVISORIES, REVISE, PROVISIONAL or BLOCKED.

A session decides; it never edits

refine-prd, refine-rfc, refine-feature and refine-feature-slice each run a decision session over a sealed review. The owner decides each finding, and the decisions are recorded in a separate overlay revision that the next review reads alongside the document. The subject’s bytes do not change, and a disputed finding stays standing until the next review adjudicates it.

A session admits a subject on its current state, not its origin. A document authored by Specgent, one imported from elsewhere and one compiled by an earlier session are admitted on the same terms: the bound revision must be the subject’s latest, and a sealed review must be bound to it by content hash with a verdict the policy admits.

The loop

Compiling a session seals the next revision of the same subject, and that revision needs its own sealed review. Each pass adds exactly one revision; nothing earlier is amended, and every revision stays readable.

Nothing decides when the loop is done. There is no convergence threshold and no round limit: the loop runs until the operator stops invoking it. A passing verdict is still not acceptance, and a compiled revision stays unaccepted until someone approves it.

Choosing a lane

Re-running the operation that authored a document fits a change upstream of it, such as a change to the idea, the research or the requirements, because the operation rebuilds the whole document from the corrected inputs. A refine session fits a response to review findings on the document as it stands. A document imported from outside Specgent has no authoring run to re-enter, so for it the session is the only lane.

Approvals

Sealing is not acceptance. An approval is a separate record naming an authority, a revision and an approval identifier, and nothing derives from a sealed revision that has not been approved. Any user may invoke any operation; what is bound to a role is approval.

Organization policy may strengthen this floor but not remove the review: independent review of a PRD or an RFC is mandatory and cannot be skipped. A PRD or RFC whose review came back REVISE or BLOCKED can still be accepted, but only by the role the policy names, citing waivers that are issued by roles owning their category and that together cover every open blocking finding. A PROVISIONAL verdict is never waived; the review is re-run instead.

For a Feature Specification or a Slice Specification, a review is evidence that an approval may cite, never a gate it has to break. The acceptance records which review round the approver read and what was still open in it.