PRD-018: Semantic Change Proposals

Document Type

Product Requirements Document (PRD)

Status

Draft

Problem Statement

Changes to canonical semantics (concept definitions, policies, normalizer rules, identity schemas) are currently approved as binary accept/reject decisions. This approach:

Hides trade-offs: Reviewers don’t see alternative approaches or their relative costs
Enables rubber-stamping: Without explicit options, approvers may not fully consider implications
Lacks structured impact analysis: Blast radius, compatibility, and debt creation are not systematically evaluated
Reduces accountability: No record of which alternatives were considered and rejected

Vision

A forced-choice governance mechanism where the system generates up to three structured options for every semantic change, each with explicit trade-offs, impact analysis, and risk ratings. Human approvers MUST actively select an option with explicit justification—the system cannot auto-choose.

Goals

Goal ID	Description	Success Metric
`G-01`	All semantic changes require structured proposal	100% of changes have SemanticChangeProposal
`G-02`	Reviewers see explicit trade-offs	≥2 options presented for 80% of proposals
`G-03`	No auto-approval possible	0% of proposals approved without human selection
`G-04`	Full audit trail of decision rationale	100% of approvals include justification
`G-05`	Impact analysis before approval	100% of options include blast radius + debt analysis

User Stories

US-01: As a Developer, I propose a semantic change

Given I have modified a concept definition or policy
When I submit my change for review
Then the system generates a SemanticChangeProposal with up to 3 options
And each option shows impact analysis and required approver role

US-02: As a Domain Steward, I review a proposal

Given a SemanticChangeProposal is assigned to me
When I open the proposal
Then I see all generated options with trade-off comparisons
And I cannot approve without selecting a specific option
And I must provide written justification for my selection

US-03: As an Architecture Governor, I review breaking changes

Given a proposal is flagged as breaking change
When I review the options
Then I see which invariants each option preserves or violates
And the aggressive option clearly shows elevated governance cost

US-04: As an Auditor, I review proposal history

Given a semantic change was approved
When I query the audit trail
Then I see all options that were generated
And I see which option was selected and why
And I see the approver’s explicit justification

Functional Requirements

FR-01: Proposal Artifact

Every change to canonical semantics MUST be wrapped in a SemanticChangeProposal artifact
Artifact includes: proposal ID, author, affected artifacts, change type, generated options

FR-02: Option Generation

The system MUST generate 1 to 3 options for each proposal
Options are categorized as:
- Conservative (minimal change, preserves all invariants)
- Balanced (recommended default if safe; optimal trade-off)
- Aggressive (maximum capability; higher governance cost)
See SDS-031 §3 for option generation policy

FR-03: Impact Analysis (per option)

Each option MUST include:

Semantic Debt created (new) and retired (resolved)
Projections affected (downstream artifacts requiring regeneration)
Compatibility assessment (backward/forward)
Blast radius (count of affected concepts, policies, consumers)
Invariants preserved and invariants violated

FR-04: Risk Rating

Each option MUST have a risk rating:

Low: No invariant violations, minimal blast radius
Medium: Some invariant relaxation, moderate blast radius
High: Invariant violations, large blast radius, requires elevated approval
Critical: Breaking change, regulatory implications, requires R-SO consultation

FR-05: Required Approver Role

FR-06: Forced Selection

The system MUST NOT auto-select an option
The approver MUST explicitly click/select one of the presented options
Selection without justification is BLOCKED

FR-07: Justification Requirement

Every option selection MUST include a written justification (min 20 characters)
Justification is stored in the approval event
Justification is part of the permanent audit record

FR-08: Audit Trail

All proposal lifecycle events are emitted to IFL
Each event includes: proposal state, actor, timestamp, selected option (if applicable), justification (if applicable)
Events are immutable and append-only

Non-Functional Requirements

NFR ID	Category	Requirement
`NFR-01`	Performance	Option generation completes in < 5 seconds
`NFR-02`	Availability	Proposal system 99.9% uptime
`NFR-03`	Security	All proposals and approvals cryptographically signed
`NFR-04`	Audit	Full proposal history retained for 7 years

Acceptance Criteria

SemanticChangeProposal schema is defined and validated
Option generation produces 1-3 options per proposal
Impact analysis includes all required fields
Approval blocked without option selection + justification
All lifecycle events emitted to IFL with correct schema
Audit trail queryable via sea-gate query-proposals
Four-eyes rule enforced (proposer ≠ approver)

Dependencies

Dependency	Specification	Status
Authority & Ownership	SDS-031	Draft
CI Semantic Gates	SDS-020	Draft
Semantic Debt Ledger	SDS-016	Draft
Identity & Addressing	SDS-050	Draft

SDS-031: Authority & Ownership Boundaries §5 — Technical implementation (Decision Execution chapter)
SDS-020: CI Semantic Gates — CI enforcement hooks

Note: SDS-031 (Semantic Change Workflow) has been consolidated into SDS-031 §5.

Changelog

Version	Date	Author	Change
0.1.0	2025-12-22	SEA-Forge™	Initial draft