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	`<govroot>/global/PRISM_GLOBAL.md`	Operator (org-wide defaults)	Every project, every tenant
2	tenant	`<govroot>/tenants/<slug>/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 `<govroot>/.../projects/<slug>/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.

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/<project>/PRISM.md.
central-registry (for hosted / multi-tenant deployments) — governance files live under $PRISM_ROOT/governance/; project files live at $PRISM_ROOT/governance/.../projects/<slug>/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):

{
  "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_<LAYER>=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.

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).

Introduction

Thesis

Architecture

Prism-Vault

Skills

Method Fragments

Operations

Releases

Changelog

Prism History

Case Studies

Legal

Governance precedence

Governance Precedence — 5-Layer Narrower-Wins + Mandatory Override Gate

1. The 5 layers

2. Narrower-wins (default)

3. Mandatory override gate

4. ORG source path

4.5 Prism repo guardrails

5. Layout disambiguation

6. The `prism_start` `governance` block

7. Per-layer state taxonomy

8. Authority of this document

​Governance Precedence — 5-Layer Narrower-Wins + Mandatory Override Gate

​1. The 5 layers

​2. Narrower-wins (default)

​3. Mandatory override gate

​4. ORG source path

​4.5 Prism repo guardrails

​5. Layout disambiguation

​6. The prism_start governance block

​7. Per-layer state taxonomy

​8. Authority of this document

​9. Related artifacts

Governance Precedence — 5-Layer Narrower-Wins + Mandatory Override Gate

1. The 5 layers

2. Narrower-wins (default)

3. Mandatory override gate

4. ORG source path

4.5 Prism repo guardrails

5. Layout disambiguation

6. The `prism_start` `governance` block

7. Per-layer state taxonomy

8. Authority of this document

9. Related artifacts