feat(governance): expose stable machine-readable GovernanceDecision contract (#29) - #179
Merged
ElliotSun merged 6 commits intoAug 28, 2026
Conversation
…nd strict read-only golden tests
…and add typed mappers
…policy bumps (none, minor, major)
ElliotSun
deleted the
29-expose-a-stable-machine-readable-governancedecision-contract
branch
August 28, 2026 23:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
PublicGovernanceDecisionV1Model (semapact/governance/public.py): Immutable, strict, versioned schema (schemaVersion: "1") with camelCase JSON serialization and snake_case Python attribute support viaAliasChoices.Literaldefinitions for public vocabulary (PublicDecisionResult,PublicRequiredVersionBump,PublicSeverity,PublicChangeType,PublicEntityType,PublicChangeDomain,PublicEvidenceSource) without speculative additions.GovernanceDecisionhas zero dependencies onpublic.py).serialize_public_governance_decision()provides byte-level deterministic JSON withsort_keys=Trueand sortedreasonCodes/evidence.tests/fixtures/governance_decisions/verified by strict string equality tests.Closes #29
Architecture
Owned by
$\longrightarrow$ $\longrightarrow$
semapact.governance.publiclayer. Adheres to the strict unidirectional flow:Domain GovernanceDecisionProjection LayerPublicGovernanceDecisionV1.Validation
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.