Skip to content

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

Draft
ElliotSun wants to merge 3 commits into
mainfrom
82-standardize-governance-change-representation-across-merge-policy-and-release
Draft

feat(governance): standardize governance change representation (#82)#172
ElliotSun wants to merge 3 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

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