> ## 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. # Governance precedence # Governance Precedence — 5-Layer Narrower-Wins + Mandatory Override Gate > Architectural reference for the governance model ratified in Plan #10 > Wave 1 (2026-05-04). Audience: agents resolving conflicts between > instruction surfaces; operators authoring guardrails at any layer. > > **Source artifacts:** SPEC-077 v0.2 (Canonical Boot + Governance > Resolution) and ADR #47 v0.2 (Governance Layer Precedence + Override > Semantics, supersedes ADR #45 v0.1). ## 1. The 5 layers Governance instructions live in 5 stacked layers. From broadest to narrowest: | # | Layer | Typical file(s) | Owner | Authority scope | | - | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------- | | 1 | **global** | `/global/PRISM_GLOBAL.md` | Operator (org-wide defaults) | Every project, every tenant | | 2 | **tenant** | `/tenants//TENANT.md` | Operator or external tenant authority | Every project under that tenant | | 3 | **org** | `$PRISM_ROOT/Orgs/$PRISM_ORG/ORG.md` | Operator or org authority | Every project under that org | | 4 | **project** | `$PRISM_ROOT/PRISM.md` (sibling-projects layout) or `/.../projects//PRISM.md` (central-registry layout) | Project PO | Just this project | | 5 | **user-session-runtime** | `$HOME/.prism/env`, runtime prompts, launcher-injected vars | Operator or agent at session start | Just this session | The runtime resolver (`resolveGovernance()` in `mcp-node/src/ops/governance/resolver.ts`, gated on `PRISM_GOVERNANCE_RESOLVER_ENABLED=true`) reads the file-bearing layers 1–4 and reports per-layer state, conflicts, and a `gov:N/M` summary on the `prism_start` return. Layer 5 is reported separately and is **not** counted in `M` (per Texi v0.2 amendment 2 — `M=4` file-bearing layers). ## 2. Narrower-wins (default) When two layers carry conflicting binding rules on the same topic, the **narrower** layer wins by default. Concrete examples: * A project-layer rule beats an org-layer rule. * An org-layer rule beats a tenant-layer rule. * A tenant-layer rule beats a global-layer rule. This is the inverse of the pre-Plan-#10 model, where the broader file was assumed to be operator-canonical and a narrower file was assumed to be subordinate. The new model treats the narrower layer as the operator's most-recent and most-context-specific intent. ```mermaid theme={null} flowchart TB subgraph layers["Governance Layers — broad to narrow"] direction TB L1["1. global
 
PRISM_GLOBAL.md"] L2["2. tenant
 
TENANT.md"] L3["3. org
 
ORG.md"] L4["4. project
 
PRISM.md"] L5["5. user-session-runtime
 
$HOME/.prism/env + runtime prompts"] L1 -->|narrower wins| L2 L2 -->|narrower wins| L3 L3 -->|narrower wins| L4 L4 -->|narrower wins| L5 end classDef layerBox fill:#1e293b,stroke:#475569,color:#e2e8f0,stroke-width:1px classDef stack fill:#0f172a,stroke:#334155,color:#cbd5e1 class L1,L2,L3,L4,L5 layerBox class layers stack ``` ## 3. Mandatory override gate A binding rule in a broader layer can declare itself non-overridable by adding `mandatory: true` to the file-level frontmatter. When a narrower layer attempts to set a conflicting value on the same topic, the broader rule wins **only because it is mandatory** — and the resolver reports `winner=broader`, `rationale=mandatory_guardrail` in the governance block. This is the only path through which a broader layer overrides a narrower one. Without `mandatory: true`, narrower-wins is unconditional. The `mandatory: true` flag is set by operators / org authorities, never by the installer. The install-lane create-or-merge logic must **preserve** the flag on existing files (see `docs/plans/install-lane-governance-env-2026-05-04.md` v0.3 §4 for the install-side contract). ## 4. ORG source path As of SPEC-133 R2 (PR #521, 2026-05-22), the org layer resolves to a single canonical path: `$PRISM_ROOT/Orgs/$PRISM_ORG/ORG.md`. The `PRISM_ORG` env var is launcher-guaranteed (set by `coder.sh` / `coder.ps1` before the editor opens), so the path is deterministic at boot time. The earlier dual-source transition model (`$PROJECT_ROOT/ORG.md` canonical / `$PRISM_ROOT/ORG.md` repo-local override) is retired. Resolver conflict fields `repo_local_used` and `dual_org_sources` remain in the taxonomy for backward compatibility but will not be set on SPEC-133 R2+ installs. The resolver reports `effective_org_path` = `$PRISM_ROOT/Orgs/$PRISM_ORG/ORG.md` and `repo_local_used` = `false` on compliant installs. ## 4.5 Prism repo guardrails For the Prism repo itself, runtime identity/persona assignment is a **boot-only** concern. The active identity comes from launcher-provided runtime state and the boot path (`PRISM_AGENT_IDENTITY` -> `prism_start` / committed persona bindings). `ORG.md`, repo-local style overlays, and other non-boot governance surfaces may shape tone, workflow, or display, but they must **not** assign, rename, or override the runtime identity for a live session. Repo dotpaths are **ignored by default** at the governance/doc level. Only the following dotpath directories are in-scope without an explicit task-level exception: * Prism-managed: `.prism/`, `.agent/` * Approved editor/config surfaces: `.claude/`, `.codex/`, `.cursor/`, `.vscode/`, `.github/`, `.githooks/` All other dotpaths are out-of-scope by default and must not be treated as governance-bearing surfaces unless a narrower explicit instruction names them. ## 5. Layout disambiguation Two on-disk layouts are supported for the file-bearing layers: * **`sibling-projects`** (default for personal installs) — governance files live under `$PROJECT_ROOT/.prism-governance/`; project files live alongside each project's repo at `$PROJECT_ROOT//PRISM.md`. * **`central-registry`** (for hosted / multi-tenant deployments) — governance files live under `$PRISM_ROOT/governance/`; project files live at `$PRISM_ROOT/governance/.../projects//PRISM.md`. The active layout is named in `PRISM_GOVERNANCE_LAYOUT` in `$HOME/.prism/env`. When this var is set the resolver uses it directly (explicit-wins, per SPEC-077 §10) and does **not** raise a layout-collision error. When the env var is absent, the resolver runs collision detection: if both layouts have content, it reports `gov:offline/invalid` rather than silently picking one. ## 6. The `prism_start` `governance` block When `PRISM_GOVERNANCE_RESOLVER_ENABLED=true`, `prism_start` returns a `governance` field on the response with this shape (abbreviated): ```jsonc theme={null} { "governance": { "summary": "gov:4/4 ok", // or "gov:3/4 warn", "gov:offline/invalid" "layers": { "global": { "state": "found_nonempty", "path": "...", "mandatory": false }, "tenant": { "state": "found_empty_stub", "path": "...", "mandatory": false }, "org": { "state": "found_nonempty", "effective_path": "...", "repo_local_used": true, "mandatory": false }, "project": { "state": "found_nonempty", "path": "...", "mandatory": false } }, "conflicts": [], // invalid_frontmatter, dual_org_sources, // layout_collision, schema_version_mismatch, // layer_mismatch, slug_mismatch "mandatory_guardrails": [], // any layer with mandatory:true "user_session_runtime": { // reported but NOT counted in M "env_path": "$HOME/.prism/env", "session_overrides": [] } } } ``` When the flag is OFF (default), `prism_start` omits the field entirely and the response shape exactly matches pre-SPEC-077. Agents written against the older shape are unaffected. ## 7. Per-layer state taxonomy Each file-bearing layer is classified into one of 5 states: | State | Meaning | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `found_nonempty` | File exists, frontmatter parses, body has content | | `found_empty_stub` | File exists, frontmatter parses, body is empty (intentional placeholder) | | `missing` | File does not exist on disk | | `skipped` | RESERVED for v1 (per Texi v0.2 amendment 4); installer MUST NOT infer skipped from missing files. Future env-var mechanism `PRISM_GOVERNANCE_LAYER_SKIPPED_=true` will set it explicitly. | | `invalid` | File exists but frontmatter fails to parse, or schema\_version mismatch | `found_empty_stub` counts as `ok` in the `gov:N/M` summary; `missing` counts as `warn`; `invalid` counts as `invalid` and short-circuits the whole summary to `gov:offline/invalid`. ## 8. Authority of this document ADR #47 v0.2 is the binding source for layer precedence semantics. SPEC-077 v0.2 is the binding source for the boot model and resolver contract. This page is a reference / explainer — when the spec text and this page disagree, the spec text wins. File a docs-refresh task to fix the drift. ## 9. Related artifacts * **SPEC-077 v0.2** — Canonical Boot + Governance Resolution. Boot model (static BIOS → `prism_start` → governance block); 5-state per-layer classification; `PRISM_GOVERNANCE_RESOLVER_ENABLED` default-off. * **ADR #47 v0.2** — Governance Layer Precedence + Override Semantics. 5-layer narrower-wins; mandatory:true override gate; canonical ORG cannot be bypassed by repo-local override. * **ADR #48 v0.2** — Persona / Identity / Specialization Field Model. Specialization is routing/memory/skill authority, **not** governance authority — distinct concept; layer precedence does not depend on persona. * **`docs/plans/install-lane-governance-env-2026-05-04.md` v0.3** — installer-side contract (env-var write block, directory skeletons, helpers). * **`docs/research/instruction-surface-inventory-2026-05-04.md` v0.2+** — per-file inventory of every instruction-bearing surface in Prism with per-entry `authority_layer` field. * **PRs #114 / #115 / #116** — implementation cluster: launcher env source + governance-var forwarding (#114), install-lane helpers (#115), runtime resolver + `prism_start` extension + BIOS bump 2.4.0 (#116). * **templates/CLAUDE.md** + **templates/AGENTS.md** at `bios_version 2.9.0` — Ring 0 BIOS replicas of this precedence rule (SPEC-133 R2).