Operations

Release Notes

Operator surface for authoring release notes that accompany each published world-model version. Release notes are not auxiliary marketing copy — they are the restatement mechanism (per ADR-026). When a subsequent version corrects a prior rule, the release notes carry the correction record; prior WorldModelCards remain authoritative for their own version and reconcile through the intervening release notes.

Scope

Release-note authoring UI — structured editor for the narrative and the correction/restatement content
Correction record — explicit linkage from each correction to the rule it corrects and the prior version it restates (per domain-model — ReleaseNotesCorrection)
Agent-drafted starting content — Operations Agent proposes initial release-notes content; operator edits before the parent version is published
No independent lifecycle — release notes follow the publishing state of the parent WorldModel version (see Lifecycle is the version’s, not the notes’)

Governance invariants

Release notes are first-class. They are an authority artifact of the world model, not an auxiliary document (ADR-026).
Corrections live in the correcting version’s release notes. There is no separate restatement protocol, no retroactive card mutation, and no automatic recertification — these absences are deliberate.
Cross-version comparability flows through authority_version on the system card (ADR-015). Readers comparing cards across versions reconcile differences by reading the intervening release notes.
Recertification is subject-driven. A downstream subject may choose to recertify against a new version after reading its release notes; that choice is not automatic.

Lifecycle is the version’s, not the notes’

Release notes have no independent draft / published state machine. Their publishing state follows the parent WorldModel version’s lifecycle:

While the parent version is in draft state, the release notes are mutable — operators (and the Operations Agent on initial proposal) create and revise the content.
At version publication, the release notes are locked in alongside the version mint and surfaced on the public WorldModelCard. Edits are rejected from that point forward.

Mutability is enforced at the use-case layer (and by a trigger at the schema layer; Postgres CHECK constraints can’t reference rows in other tables, so the parent-version-state check has to be a trigger); edits are rejected when the parent version is published. Concurrent operator actions on the same release-notes row are serialized at the row level — one wins; the other receives a clean conflict response.

Review-gating lives at the rule-set or publication-trigger gate, not at a release-notes-specific review layer. Peer review of accumulated rule changes happens at the reviewer surface; operator sign-off on the publication decision happens at the publication confirmation step. Release notes are an artifact of that process, not a separately review-gated artifact.

Audit trail

Every operator authoring action on this surface appends a row to the WorldAuthoringAudit record family (per domain-model — WorldAuthoringAudit). The discriminators introduced for release notes are:

target_type = release_notes, action = created — operator (or Operations Agent on the operator’s behalf) creates the initial release-notes draft (HTTP POST)
target_type = release_notes, action = revised — operator edits the release-notes draft (HTTP PATCH; the audit vocabulary names the workflow action, the HTTP verb names the wire semantics — both flow through the same use-case path)

The publication action that locks the release notes in is audited under (target_type = world_model_version, action = version_published) per the publication audit trail.

The audit row is appended alongside the entity-state mutation in the same transaction; it is never appended outside the originating use-case transaction.

UI surfaces

The release-notes editor is one of three panels in the publication UI flow. It surfaces:

Narrative editor — operator-edits the agent-proposed (or empty) narrative content
Correction-record editor — structured fields for each correction (corrected rule reference, prior version restated, restatement narrative)
Lock indicator — when the parent version is published, the editor reads as locked-in; historical release notes for prior versions are inspect-only

Every UI surface has a corresponding API endpoint per the dual-occupant API/UI parity rule; the Operations Agent consumes the same endpoints to propose initial content.

API surfaces

The HTTP routes consumed by both the UI and the Operations Agent (per the parity contract) include:

POST /worlds/:world_id/release-notes — create initial release-notes draft for the in-flight version (idempotent on (operator_id, correlation_id))
PATCH /worlds/:world_id/release-notes/:id — operator edits the draft (idempotent on (operator_id, correlation_id)); rejected with a 409 when the parent version is published
GET /worlds/:world_id/release-notes/:id — read release notes (current and historical)
GET /worlds/:world_id/release-notes/:id/corrections — list of structured correction records

Auth middleware sets app.user_id via SET LOCAL per ADR-041 D4; RLS predicates compare against app.user_id per ADR-039.

What’s next

Architecture — the next cluster in the spine. The three-context library topology + Clean Architecture inside each context; the operations-app surfaces this cluster describes ride atop the layout introduced there.