Standards pack upgrades¶
The org/team standards layer is pulled and pinned by cortexbuild standards
pull (see Roll out across an organisation). This page
covers upgrading a pinned pack to a newer version safely and reversibly.
Versioning¶
A pack declares a version, and the kind of version change determines how an upgrade behaves:
| Change | Behaviour |
|---|---|
Patch (1.2.3 -> 1.2.4) |
Preview, then apply automatically |
Minor (1.2.3 -> 1.3.0) |
Preview, then apply automatically |
Major (1.2.3 -> 2.0.0) |
Breaking -- requires --confirm to apply |
Downgrade (1.2.3 -> 1.1.0) |
Use standards downgrade (restores a snapshot) |
Preview, then apply¶
# 1. Preview only (no change made)
cortexbuild standards upgrade v2.0.0 --source [email protected]:org/pack.git
# 2. Apply
cortexbuild standards upgrade v2.0.0 --source ... --apply --confirm
The preview reports the version change, whether it's breaking, which rules were added or removed, and any conflicts between the new pack and rules you've overridden locally -- as counts and rule ids only; nothing about the content of your overrides leaves your machine.
If you have overridden a rule that the new pack also changes, the preview
flags the conflict and blocks a silent apply unless you pass --confirm. A
major (breaking) version change always requires --confirm too.
Applying re-verifies exactly what was previewed before making any change, so an upgrade can never silently apply something other than what you reviewed.
Reversibility¶
Every apply first takes a full, safely-written snapshot of everything the upgrade could touch: the pack itself, your local rule overrides, and the manifest that tracks what's rendered where. To roll back:
cortexbuild standards downgrade --backup-id pre-1.0.0-to-2.0.0-<id>
downgrade restores that snapshot exactly and re-renders every AI-tool
surface from it, so your whole repository -- not just its governance
files -- returns to its pre-upgrade state with nothing half-updated.
If any step of an apply fails, the pre-upgrade snapshot is restored automatically before the failure is reported, so a failed upgrade never leaves your repository in a mixed old/new state.
Audit trail¶
Each applied upgrade and each downgrade is recorded in the governance audit log (see Roll out across an organisation). The audit log is append-only and is deliberately not rolled back by a downgrade -- the record of what happened survives the reversal.