Status
Accepted
Context
Pnyma's constitutional principles must be both human-readable governance documents and machine-operable policy artifacts. Keeping them as unstructured prose creates drift risk, reduces testability, and makes change control ambiguous.
Decision
Represent constitutional principles and conflict resolution rules in versioned, machine-readable files stored under constitution/ in the canonical repository. These files are the authoritative source for runtime constitutional enforcement.
Rationale
Treating the constitution as code enables:
- Deterministic policy checks — runtime components consume canonical YAML/JSON artifacts rather than interpreting prose.
- Auditable change control — every modification is a versioned diff subject to review and approval.
- Release gating — CI/CD pipelines can run constitutional fidelity benchmarks against proposed changes before merge.
- Regression detection — automated tests validate that new versions do not reduce constitutional compliance scores.
Consequences
Positive
- Policy updates require PR review and benchmark reruns — no silent drift.
- Runtime components consume canonical constitution artifacts directly.
- Audit trail is complete and reproducible.
Negative
- Requires maintaining schema definitions and migration tooling as the constitution evolves.
- Prose rationale must be kept in sync with structured artifacts — dual maintenance overhead.
Implementation Notes
- Constitutional artifacts are stored under
constitution/as versioned YAML files. - Each principle includes: identifier, text, precedence rank, conflict rules, refusal triggers.
- A constitutional parser loads these artifacts at initialization.
- Schema changes require a separate ADR.