> ## Documentation Index > Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt > Use this file to discover all available pages before exploring further. # Spec 085 v0 2 constitutional governance vocabulary and rights model # SPEC-085 v0.2 — Constitutional Governance Vocabulary and Rights Model **Status:** accepted v0.1; v0.2 amendment draft pending Texi precision review and Donna ratification. **Author:** Candi **Architecture reviewer:** Texi **Governance/PO reviewer:** Donna **Docs owner:** Desiree **Origin ADR:** ADR #50 — Governance Vocabulary v1.0 **Drafted:** 2026-05-05 **v0.1 review fold:** Donna review `a850d430` blockers/majors folded: citizenship standing, mandatory conflict rule, canonical role vs persona instance, judicial review mechanics. Minor findings folded where low-risk. **v0.2 amendment:** Folds Texi precision nits from Donna TaskAssigned `33f13e53`: preserve both ring and ADR-47 `authority_layer`, do not collapse tenant/org into `tenant_org_constitution`, scope standing to role-binding tuples by default, and use `Prism Constitution` for product-level canon. ## Summary This SPEC operationalizes ADR #50 by defining Prism's Constitutional Governance Model: the vocabulary, rights model, ring naming, generated documentation targets, validation rules, and rollout sequence for explaining and enforcing governance across Prism product canon, tenant/org overlays, project constitutions, runtime/session configuration, and agent contracts. The goal is not to add legal ceremony. The goal is to give agents and operators a precise mental model: * BIOS loads the system. * Constitution defines the substantive rules. * Overlays customize without changing canon. * Amendments change canon through ratified process. * Override gates protect mandatory guardrails. * Agent Contracts define agent citizenship, lane, authority, and duties. * Configurability rights are not amendment rights. ## Problem Prism's governance system has outgrown its early vocabulary. Current confusion points: * `BIOS` is sometimes used for loader files and sometimes for substantive law. * `override` is used for ordinary layering, formal canonical change, and mandatory-guardrail blocking. * `Ring 2.5` is awkward and unclear in diagrams and docs. * `ORG.md` and project-local governance need clearer user-configurability boundaries. * Agent roles are moving toward governed contracts, but the vocabulary does not yet say who may configure which contracts. * Users need to know what they can configure and what requires amendment by Prism, tenant/org, or project authority. Without this clarification, documentation sweeps and generated instruction surfaces will keep propagating ambiguous terms. ## Goals 1. Define the canonical governance vocabulary for BIOS, Constitution, Prism Constitution, Overlay, Amendment, Override Gate, Ring, Agent Contract, Configurability Right, and Amendment Right. 2. Replace old `Ring 2.5` language with explicit `Ring 3`. 3. Define an explicit Ring 0-5 model. 4. Define the configurability/amendment rights matrix across Prism product, tenant/org, project, runtime/session, and agent-contract layers. 5. Establish the Federal Republic metaphor as explanatory, not normative. 6. Define how docs, templates, generated instruction surfaces, and future governance lookup should consume the vocabulary. 7. Define validation checks that prevent users or agents from silently mutating constitutional layers outside their authority. ## Non-Goals * No change to the SPEC-077 / ADR #47 precedence algorithm. * No immediate implementation of a new resolver. * No automatic rewrite of templates before ADR #50 ratification. * No new hard enforcement in v0.1. * No import of legal process beyond the useful governance metaphor. * No change to tenant/project authority beyond clarifying existing boundaries. * No full Agent Contract implementation; this SPEC defines vocabulary and rights boundaries only. ## Vocabulary | Term | Definition | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BIOS` | Thin runtime loader and boot discipline. Generated/replicated, project-agnostic, minimal. | | `Constitution` | Substantive governance corpus: methodology, authority, precedence, amendment, and decision law. | | `Prism Constitution` | Product-level Prism canon owned by Prism maintainers and released through Prism's ADR/SPEC/release process. Avoid `Global Constitution` because `global` is already an ADR-47 authority layer and may collide with `PRISM_GLOBAL.md`. | | `Overlay` | Contextual layer that adds or applies policy without changing canon. | | `Amendment` | Ratified canonical text change with supersession/versioning. | | `Override gate` | `mandatory: true` frontmatter that blocks narrower bypass of a broader mandatory guardrail. | | `Override` | The concrete blocking effect of an override gate. Avoid for ordinary layering or amendment. | | `Ring` | Named governance/runtime surface from Ring 0 through Ring 5. | | `Agent Contract` | Governed role contract for canonical or transient agent citizenship in Prism. | | `Configurability right` | Permission to set local values or overlays inside an allowed scope. | | `Amendment right` | Permission to change durable constitutional text at a specific layer through ratified process. | | `Judicial review` | Governance lookup/conflict/supersession process; advisory to agents unless backed by mandatory governance. | | `Canonical role` | Product-governed role contract such as Product Owner, System Architect, Engineering Executor, RTE, Docs Owner, Install Owner, Governess, or Dashboard Owner. | | `Persona instance` | Human-addressable agent identity such as Donna, Texi, Samantha, or Candi that binds to one or more role contracts for a project/session. | ## BIOS vs Constitution BIOS and Constitution are complementary. BIOS means: * boot files and loader behavior * `AGENTS.md` / `CLAUDE.md` thin startup contract * `prism_start` ritual * status card discipline * signal-drain obligations * offline fallback behavior * whole-file replica sync behavior Constitution means: * substantive governance rules * methodology * authority scopes * decision procedures * precedence model * amendment process * mandatory guardrails * agent citizenship duties Rule: ```text theme={null} BIOS loads and orients. Constitution governs. ``` BIOS files may contain minimum viable boot law, but substantive doctrine should live in constitutional artifacts or be cited from them. ## Ring Model Use explicit Rings 0-5. | Ring | Name | Purpose | | ------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Ring 0 | Bootstrap Enforcement | Session bootstrap, status-card requirement, signal-drain discipline, and minimum start/continue rules. | | Ring 1 | BIOS Loader | Thin universal runtime files such as `AGENTS.md` and `CLAUDE.md`; project-agnostic loader contract. | | Ring 2 | Project Constitution | Project-local methodology and project-level law, primarily `PRISM.md`. | | Ring 3 | Organization / Tenant Constitution | Org/tenant overlays and mandatory guardrails, including `ORG.md` or future tenant/org governance files. Supersedes old `Ring 2.5`. | | Ring 4 | Live Prism State | Runtime project/session state returned by `prism_start`, advisory governance lookup, open work, drift warnings, and coordination state. | | Ring 5 | Enforcement and Telemetry | Server-side soft enforcement, wrap/checkpoint warnings, audit, telemetry, and dashboard reporting. | Important: Rings are surfaces and runtime layers. Rings alone do not define precedence. Precedence remains: ```text theme={null} narrower wins by default, except broader mandatory:true guardrails block narrower bypass ``` If two mandatory guardrails conflict across rings, the broader mandatory guardrail wins until amended by the authority that owns that broader layer. Examples: * Ring 1 mandatory canon beats conflicting Ring 3 mandatory org policy. * Ring 3 mandatory org policy beats conflicting Ring 2 project policy. * Ring 2 project constitution beats conflicting Ring 4 runtime/session preference for durable project rules. The resolver must report the conflict instead of silently flattening it. Ring 4 live state is advisory. It may supply current context, warnings, and recommendations, but it does not amend or override committed Constitution. Runtime/session state can route work and inform agents; durable constitutional change requires amendment through the owning layer. ## Federal Republic Metaphor Use the US Federal Republic metaphor as an explanatory frame, not as normative law. | US concept | Prism mapping | | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | | US Constitution / federal supremacy | Global BIOS + canonical methodology; `mandatory: true` acts as the supremacy clause for mandatory canon. | | Bill of Rights / mandatory canon | Non-bypassable guardrails at broader layers. | | Federal preemption | `mandatory: true` override gate. | | State sovereignty | Org/project autonomy in areas not occupied by mandatory canon. | | State constitution / state law | Ring 3 organization or tenant constitution/overlays. | | Local ordinance | Ring 2 project constitution/methodology. | | Amendment process | SPEC-078-style high-tier ratification arc for canonical change. | | Judicial review | `prism_governance_lookup` and governance conflict reporting. | | Citizens | Agents bootstrapped into Prism governance. | | Citizenship duties | Agent Contracts: identity, lane, authority, non-authority, handoff, escalation, and review obligations. | Product docs should prefer the phrase **Constitutional Governance Model**. The Federal Republic metaphor can be used in explanatory docs and diagrams, but the vocabulary must stand on its own. ## Rights Matrix Every constitutional layer must declare configurability and amendment rights. | Layer | User-configurable? | Amendment authority | Overlay rights | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Prism Constitution | No direct user mutation. Users consume released Prism canon. | Prism maintainers through ratified ADR/SPEC/release process. | Tenants/orgs/projects may overlay non-mandatory areas only. Mandatory Prism canon remains binding. | | Tenant constitution | Yes, by tenant owners or delegated tenant governance admins. | Tenant governance authority, subject to mandatory Prism canon. | Orgs/projects may overlay non-mandatory tenant areas unless tenant marks a guardrail `mandatory: true`. | | Organization constitution | Yes, by org owners or delegated org governance admins. | Org governance authority, subject to Prism and tenant mandatory canon. | Projects may overlay non-mandatory org areas unless org marks a guardrail `mandatory: true`. | | Project constitution | Yes, by project owner/operator/approved project governance lane. | Project governance process, subject to Prism and tenant/org mandatory guardrails. | Session/runtime context may adapt execution, but cannot amend project constitution. | | Runtime/session operating state | Yes, by active operator and authorized agents within session authority. | No durable constitutional amendment authority unless promoted through the appropriate governance process. | Can provide temporary assignment, context, preferences, feature flags, and task constraints. | | Agent Contract | Canonical Prism roles: configurable only through Agent Contract governance. Persona instances bind to roles and are fungible unless the role contract says otherwise. Non-Prism/project-local roles are configurable by owning project/org within broader guardrails. | Canonical role contracts require Prism governance ratification; local/transient role contracts require project/org authority. | Local projects may bind, specialize, or create non-Prism contracts, but cannot mutate Prism canonical role contracts. | Core rule: ```text theme={null} Configurability is not constitutional authorship. ``` Prism can be highly configurable while still preserving product-level guarantees users cannot silently rewrite. Operator/maintainer dual-hat is handled by scope. Frank as active operator has runtime/session configurability rights. Frank acting as Prism maintainer can amend Prism product constitution only through the Prism amendment process. Same human, different hat, different authority path. ## Overlay and Amendment Rules Overlay: * adds local policy, * narrows behavior inside allowed scope, * configures preferences or defaults, * may bind project-local roles, * may not rewrite upstream canon, * may not bypass broader `mandatory: true`. Amendment: * changes canonical text, * requires explicit ratification, * records supersession/versioning, * updates generated mirrors, * may require docs/template sweep, * may require migration or feature flag plan. Override gate: * is explicit frontmatter, * blocks narrower bypass, * must be reported by governance lookup/resolver, * should be visible in dashboard/conflict views, * should be rare and intentional. ## Agent Contract Rules An Agent Contract is a governance object, not a personality sketch. It defines: * identity or transient role binding * specialization/lane * authority scope * explicit non-authority scope * required startup context * expected artifacts * review obligations * handoff obligations * permitted tools/skills/method fragments * prohibited shortcuts * escalation triggers * lifecycle/versioning * evidence links Canonical Prism agent contracts are Prism-governed product capabilities. Users may bind or invoke them locally but cannot mutate their canonical definitions directly. Project-local and non-Prism agent contracts are configurable by their owning project/org, constrained by broader mandatory guardrails. Canonical roles and persona instances are distinct: * canonical role = product-governed office/capability, such as Product Owner or System Architect * persona instance = named agent binding, such as Donna, Texi, Samantha, or Candi A persona may be replaced, reassigned, or multiply bound only according to the relevant Agent Contract and project governance. Transient role contracts must include: * bounded task * explicit resource/file ownership * output shape * review target * maximum lifetime * no durable constitutional amendment authority ## Citizenship Standing Agent Contracts must define what loss of standing looks like. A postmortem alone is evidence; it is not the full standing model. Standing attaches by default to the role-binding tuple, not to the canonical role globally: ```text theme={null} (role_contract_id, persona_id_or_agent_id, project_or_session_scope) ``` This prevents one problematic binding from suspending the canonical role everywhere. A canonical role itself can be deprecated, superseded, or suspended only through Prism-level Agent Contract governance. Minimum standing states: | State | Meaning | | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `active` | Agent/role binding is trusted for normal work within contract. | | `warned` | A violation or drift was observed; work may continue with explicit warning and evidence link. | | `probation` | Repeated or serious issue; agent may operate only with narrowed scope, extra review, or temporary routing limits. | | `suspended` | Agent/role binding may not receive new authority-bearing assignments until recovery is completed. | | `retired` | Contract or binding is no longer active and should not be used for new work. | Standing triggers: * governance violation * repeated failure to journal/checkpoint * unauthorized authority claim * bypass attempt against `mandatory: true` * unsafe tool use * repeated postmortem-causing shortcut * stale or unreviewed contract drift Recovery path: 1. Record postmortem or review finding. 2. Identify violated contract/governance source. 3. Define remediation action. 4. Route to owning governance lane for review. 5. Record restoration, continued probation, suspension, or retirement decision. Ring 5 enforcement should report standing and trend data. It should not silently suspend an agent without a recorded governance action. ## Judicial Review Judicial review is the structured governance conflict process, not an agent's private reasoning. It fires when: * governance lookup detects conflicting applicable rules * a narrower layer attempts to bypass a broader `mandatory: true` guardrail * runtime/session context conflicts with committed Constitution * an Agent Contract claims authority outside its lane * an ADR/SPEC/documentation artifact appears superseded or internally inconsistent Mechanism: * `prism_governance_lookup` or successor resolver returns applicable rules, authority layer, mandatory state, supersession state, and conflict entries. * `prism_start` / `prism_status` surfaces unresolved conflicts to the active agent. * Candi owns governance-methodology triage. * Texi owns architecture/precedence review. * Donna owns ratification/PO resolution unless a narrower artifact assigns different authority. * Findings must cite source artifacts and proposed operator action. Judicial review remains advisory unless backed by a mandatory guardrail or ratified amendment. It explains what law applies; it does not invent new law. ## Governance Lookup Contract Future governance lookup/resolver surfaces should expose: ```json theme={null} { "ring": "Ring 3", "authority_layer": "org", "constitution_layer": "organization_constitution", "source_path": "...", "term": "mandatory_guardrail", "configurability_right": "org_owner", "amendment_right": "org_governance", "overlay_allowed": true, "mandatory": true, "conflicts": [] } ``` Minimum fields for rights-aware reporting: * ring * ADR-47 `authority_layer` (`global`, `tenant`, `org`, `project`, `user_session_runtime`) * constitution layer (`prism_constitution`, `tenant_constitution`, `organization_constitution`, `project_constitution`, `runtime_session_state`, `agent_contract`) * source * authority owner * configurability owner * amendment owner * overlay allowed * mandatory guardrail state * supersession state * conflict state * operator action ## Template and Docs Targets After ADR #50 ratification, update: * `templates/AGENTS.md` * `templates/CLAUDE.md` * `templates/PRISM.md` or base methodology templates * project `AGENTS.md` / `CLAUDE.md` replicas through `prism_sync_bios` * project `PRISM.md` through governed sync path * `docs/vision.mdx` * `docs/index.mdx` * `docs/hybrid-rag.mdx` * `docs/signal-mesh.mdx` * `docs/multi-prism-controller.mdx` * `docs/history.mdx` * `docs/agent-surfaces.mdx` * governance precedence reference page Docs must avoid using `override` where `overlay` or `amendment` is meant. ## Visual Model Recommended primary diagram: ```text theme={null} Prism Constitution mandatory:true locks | Tenant Constitution overlays + tenant mandatory guardrails | Organization Constitution overlays + organization mandatory guardrails | Project Constitution local methodology + project rules | Runtime / Session State temporary assignment + context + flags | Ring 5 Enforcement + Telemetry warnings + audit + dashboards + improvement loop ``` Recommended short explainer: ```text theme={null} BIOS boots. Constitution governs. Overlays configure. Amendments change canon. Override gates protect mandatory rules. Agent Contracts define citizenship. ``` ## Validation Rules Validator should flag: * `Ring 2.5` references after migration cutoff. * `override` used where `overlay` or `amendment` is intended. * generated BIOS files with hand-edited constitutional content. * project constitution attempting to bypass broader `mandatory: true`. * runtime/session config attempting durable amendment. * standing state attached to canonical role globally when the incident is only binding-scoped. * local agent contract mutating canonical Prism agent contract. * active role contract missing authority or non-authority scope. * docs pages presenting Federal Republic metaphor as normative authority. ## Acceptance Criteria ADR/SPEC acceptance: * ADR #50 reviewed by Texi and Donna. * SPEC-085 updated to fold binding review findings. * Ring 0-5 vocabulary accepted or explicitly revised. * Rights matrix accepted or explicitly revised. * Agent Contract vocabulary accepted or explicitly deferred. Docs/template acceptance: * No remaining authoritative docs use `Ring 2.5`. * `override`, `overlay`, and `amendment` are used consistently. * BIOS vs Constitution distinction appears in BIOS templates. * User-configurable vs amendment-required areas are documented. * Docs explain local non-Prism agents are configurable while Prism canonical agents require Prism-level amendment. Validation acceptance: * A static vocabulary scan can detect old terms. * A governance lookup response can represent configurability and amendment owners. * A governance lookup response includes both `ring` and ADR-47 `authority_layer`. * Tenant and org governance are represented as distinct authority/constitution layers. * Agent standing state is attached to the role-binding tuple unless a Prism-level governance action targets the canonical role itself. * Drift warnings are visible but non-blocking in v0.1. ## Rollout Plan Phase 0 — Review: * Donna full review. * Texi architecture review. * Candi folds findings. Phase 1 — Ratify: * Promote ADR #50 from draft to accepted after review closure. * Seal or file SPEC-085 as the operational contract. Phase 2 — Docs sweep: * Desiree updates public docs and reference pages. * Keep metaphor explanatory; use Constitutional Governance Model as product wording. Phase 3 — Template sweep: * Update source templates. * Use `prism_sync_bios` for BIOS replicas. * Use governed PRISM.md sync path for project constitution updates. Phase 4 — Validator: * Add static vocabulary scanner. * Add generated-file provenance checks. * Add rights fields to governance lookup/resolver output while preserving both ring and ADR-47 `authority_layer`. Phase 5 — Agent Contracts: * Write follow-on SPEC for Agent Contract schema and compiler. * Link canonical/non-Prism configurability rules into that SPEC. ## Risks | Risk | Mitigation | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Metaphor becomes too legalistic | Use metaphor for explanation only; product term is Constitutional Governance Model. | | Ring 0-5 conflicts with existing SPEC-077 / ADR-47 layer names | Keep rings as surfaces; always report ADR-47 `authority_layer` separately. | | Users think configurable means editable canon | Rights matrix states configurability is not amendment authority. | | Docs sweep lands before review | Gate docs/template sweep on ADR #50 review/ratification. | | Agent Contract term outruns implementation | Define vocabulary now; require follow-on SPEC for schema/compiler. | | Citizenship standing becomes punitive or automatic | Require recorded governance action; Ring 5 reports and warns, it does not silently suspend. | | Rollout exceeds docs-lane capacity | Size the sweep explicitly and split into reviewable PRs. | ## Open Questions 1. Texi: does `Agent Contract` belong in this SPEC or should this SPEC only reserve the term and defer all details? 2. Desiree: which public docs need the metaphor and which should only use the vocabulary? ## Implementation Cost Expected implementation/docs sweep: * SPEC-021 and SPEC-077 amendments. * ADR #47 vocabulary update or superseding amendment. * `PRISM.md`, `AGENTS.md`, and `CLAUDE.md` source templates. * Generated replicas through normal sync paths. * At least seven docs pages: vision, index, hybrid-rag, signal-mesh, multi-prism-controller, history, agent-surfaces. * Governance precedence reference page. * Selected memory/feedback references where old vocabulary creates operational drift. Expected cost: roughly 8-12 focused PRs over 1-2 sessions if split into reviewable slices. ## References * ADR #50 — Governance Vocabulary v1.0 * ADR #47 — Layer Precedence and Override Semantics * SPEC-077 — Canonical Boot and Governance Resolution * SPEC-078 — Consensus-First Parallelism and Method Fragments * SPEC-080 — Tri-Graph Governance Lookup and Capability Index * ADR #40 — Persona Role Reshape * `docs/ideas/prism-agent-role-contracts.md` * `docs/ideas/prism-differentiated-capability-wishlist.md` * Journal #75 — Governance vocabulary v1.0 proposal