Skip to content

feat(governance): expose stable machine-readable GovernanceDecision contract (#29) - #179

Merged
ElliotSun merged 6 commits into
mainfrom
29-expose-a-stable-machine-readable-governancedecision-contract
Aug 28, 2026
Merged

feat(governance): expose stable machine-readable GovernanceDecision contract (#29)#179
ElliotSun merged 6 commits into
mainfrom
29-expose-a-stable-machine-readable-governancedecision-contract

Conversation

@ElliotSun

Copy link
Copy Markdown
Collaborator

Summary

Exposes a versioned, machine-readable public representation for SemaPact governance decisions (PublicGovernanceDecisionV1), establishing a stable, deterministic integration contract for CI/CD gates, CLI output, PR annotations, APIs, and future external consumers without leaking internal domain types.

Key features:

  • PublicGovernanceDecisionV1 Model (semapact/governance/public.py): Immutable, strict, versioned schema (schemaVersion: "1") with camelCase JSON serialization and snake_case Python attribute support via AliasChoices.
  • Public Protocol Vocabulary: Explicit Literal definitions for public vocabulary (PublicDecisionResult, PublicRequiredVersionBump, PublicSeverity, PublicChangeType, PublicEntityType, PublicChangeDomain, PublicEvidenceSource) without speculative additions.
  • Strict One-Way Boundary: Domain layer remains decoupled from presentation/public projections (GovernanceDecision has zero dependencies on public.py).
  • Deterministic Canonical Serialization: serialize_public_governance_decision() provides byte-level deterministic JSON with sort_keys=True and sorted reasonCodes / evidence.
  • Read-Only Golden Fixtures: Added 5 golden JSON fixtures in tests/fixtures/governance_decisions/ verified by strict string equality tests.

Closes #29

Architecture

Owned by semapact.governance.public layer. Adheres to the strict unidirectional flow:
Domain GovernanceDecision $\longrightarrow$ Projection Layer $\longrightarrow$ PublicGovernanceDecisionV1.

Validation

  • Tests added or updated where behavior changed (tests/test_public_governance_decision.py)
  • uv run pytest (445 passed)
  • uvx ruff check . --select E9,F63,F7,F82 (All checks passed)
  • uv build (Built sdist and wheel successfully)

Governance / compatibility impact

Introduces the stable public schema version 1 for governance decisions. Does not alter internal evaluation logic or break existing CLI / pipeline behavior.

@ElliotSun
ElliotSun merged commit fb1d6e3 into main Aug 28, 2026
7 checks passed
@ElliotSun
ElliotSun deleted the 29-expose-a-stable-machine-readable-governancedecision-contract branch August 28, 2026 23:02
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.

1 participant