Scope Versioning
A scope is a commitment surface, not a working document. Once a scope is approved, it is never edited in place — it is superseded by a new version. That discipline is what gives calibration a real baseline to measure actual effort against: if an approved scope could be quietly edited, every project would retroactively look like it landed on target, and the system would learn from a fabricated history.
The version lifecycle
Each scope document has a chain of versions. A version moves through these statuses:
draft ──▶ in_review ──▶ approved ──▶ superseded
└──▶ rejected- draft — editable, work in progress.
- in_review — submitted for approval.
- approved — committed and frozen. This is what readers see.
- superseded — a previously approved version replaced by a newer approved one.
- rejected — a version that didn't make it through review.
One open, one approved
A document has at most one open version (a draft or in-review) and one approved version at a time. Readers always see the current version; work in progress doesn't leak into what everyone else reads until it's approved.
Committing a change
To change an approved scope, you fork a new draft version from it, edit, submit it for review, and approve it. Approving the new version supersedes the old one. The available operations mirror the lifecycle: fork a version, submit it for review, approve it, reject it, and diff any two versions.
Approving a scope typically requires a separate approver from the author. Orgs that permit it can enable self-approval as an org setting. See roles & permissions.
The change record
Every version transition writes to an append-only, signed change record. For each changed item it records the change type and a reason code — for example, a dropped requirement, a deferred requirement, a corrected estimate, a clarified requirement, or a descope for a deadline.
The reason matters because a bare numeric diff can't tell an estimating miss apart from a customer changing their mind — opposite conclusions for calibration. Reason codes route each change to the right place:
- Estimate corrected feeds the estimation-bias signal that calibration learns from.
- Dropped / added / descoped changes are excluded from bias correction and feed org-level rates instead.
- Split / merge are neutral lineage re-maps.
Immutability
Approved and superseded versions are frozen. The version record is protected in the database, the change record is append-only, and the scope content itself is guarded at the write path — an attempt to edit frozen content is refused. This is enforced server-side, not just as a read-only screen. You get history you can trust and a diff between any two versions.
Frozen content is deliberately bypassed only on documented deletion paths (when a document or organization is purged). See data management.
Drift
Provenance links a scope to the PRD version it was generated from. When that source PRD version is superseded by an approved change, every scope derived from the now-outdated version is flagged as drifted.
Drift is a signal, not an automatic change. Scopingly does not rewrite your scope — it surfaces a drift banner on the scope editor telling you the requirement it was built from has moved on, so you can decide whether to regenerate or leave it. Regeneration itself is non-destructive: you can preview what a fresh generation would change before applying anything (see regenerating without losing your edits).
Drift is per-scope
Because drift rides the provenance link, only scopes generated from the superseded PRD version are flagged. A scope regenerated against the current PRD version clears.
Availability
Scope versioning is available on all plans.