Skip to content

feat(governance): standardize governance change representation (#82) - #172

Merged
ElliotSun merged 5 commits into
mainfrom
82-standardize-governance-change-representation-across-merge-policy-and-release
Aug 20, 2026
Merged

feat(governance): standardize governance change representation (#82)#172
ElliotSun merged 5 commits into
mainfrom
82-standardize-governance-change-representation-across-merge-policy-and-release

Conversation

@ElliotSun

Copy link
Copy Markdown
Collaborator

Description

Closes #82.

Introduces one authoritative, deterministic, ODCS-aware semantic change representation (GovernanceChange) for governed contract evolution. The canonical changes are computed exactly once in the governance kernel and uniformly consumed across lifecycle policy, release classification, merge conflict correlation, and decision explanations.

Key Changes

  1. Canonical Governance Change Model (semapact/lifecycle/changes.py):
    • GovernanceChange: Frozen Pydantic model capturing change_type, entity_type, identity (canonical ancestry tuple), path, field, before/after (JsonValue), domain, breaking, reason_codes, and evidence.
    • analyze_governance_changes(): Pure ODCS-aware comparison of base and candidate contracts with semantic deprecation coalescing.
    • governance_change_sort_key(): Canonical deterministic ordering.
    • describe_governance_change(): Explainability helper.
  2. Lifecycle Policy Projection (semapact/lifecycle/policy.py):
    • evaluate_merge_policy() accepts canonical changes sequence, annotating breaking changes and reason codes without re-diffing.
  3. Change-Driven Release Classification (semapact/core/release.py):
    • classify_contract_change() projects required version bumps directly from canonical change categories, eliminating redundant diffing.
  4. Evaluator Integration (semapact/governance/evaluator.py, models.py):
    • evaluate_governance_decision() computes canonical changes once.
    • Attaches MERGE_CONFLICT evidence to matching changes via _correlate_merge_conflicts().
    • Populates GovernanceDecision.changes.
  5. Testing:
    • tests/test_governance_changes.py: 13 unit tests for analyzer matrix, sorting, and serialization.
    • tests/test_governance_change_integration.py: 11 integration tests for policy projection, release parity, and evaluator evidence correlation.

Verification

  • uv run pytest: 417 passed
  • uv run ruff check: all checks passed

@ElliotSun
ElliotSun marked this pull request as ready for review August 20, 2026 06:19
@ElliotSun
ElliotSun merged commit faf748f into main Aug 20, 2026
4 checks passed
@ElliotSun
ElliotSun deleted the 82-standardize-governance-change-representation-across-merge-policy-and-release branch August 20, 2026 06:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Standardize governance change representation across merge, policy, and release

1 participant