> ## 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-077: Canonical Boot + Governance Resolution
> Canonical Boot + Governance Resolution (v0.2, status: accepted)
**Status:** `accepted` v0.2 — body sourced from TriGraph spec entity. Docs-mirror file added by docs lane to surface ratified specs that lacked an on-disk mirror.
# SPEC-077: Canonical Boot + Governance Resolution
# SPEC-077 — Canonical Boot + Governance Resolution v0.2
**Plan:** #10 — Governance Foundation Implementation
**Wave:** 1 (P0)
**Blocker:** #1 of 6
**Sealing order:** AFTER ADR #45 v0.2 (now ADR #47, supersedes #45) per Plan #10 v0.2 amendment 1
**Authored:** Donna, 2026-05-04
**v0.2 changelog:** folds Texi `d15c8380` 7 binding amendments + 2 nits + cross-blocker shared-definition-reference.
***
## Status
Draft (v0.2 awaiting Texi re-review for Donna ratification)
## Shared definitions
This SPEC consumes the shared term table defined in **ADR #47 v0.2 §"Shared definitions"** (the v0.2 of ADR #45). Terms used herein: governance layer, authority-bearing, routing-authority, governance authority, mandatory guardrail, runtime override, effective source, feature flag.
## 1. Problem (unchanged from v0.1)
The boot contract distinguishes static editor-loaded context from live runtime initialization. Existing ring-precedence text in CLAUDE.md / AGENTS.md + governance file locations + env-block + `prism_start` lack a single source-of-truth specification. This SPEC consolidates that.
## 2. Locked boot model (unchanged from v0.1)
Per Candi research §"Agreement 1":
1. Agent surface loads static BIOS at launch (Codex: `AGENTS.md`; Claude Code: `CLAUDE.md`).
2. Static BIOS instructs the agent to call `prism_start`.
3. `prism_start` is the first Prism runtime / tool action.
4. `prism_start` returns the effective live context + boot report.
5. The first substantive human-visible response displays a status / boot card.
## 3. Governance layers (5)
Per ADR #47 v0.2 §1 — narrowest-wins across 5 layers (global / tenant / org / project / user-session-runtime). Project PRISM.md is PO-owned. **Mandatory guardrails** are file-level frontmatter (per ADR #47 v0.2 §3); user/session/runtime is bounded to operational/transient scope (per ADR #47 v0.2 §2).
## 4. Per-layer state classification (5-state)
Per Lafonda v0.2 §6 + Plan #10 v0.2 amendment 5 + Texi `d15c8380` SPEC-077 amendment 4:
| State | Meaning | Operator action |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `found_nonempty` | Layer file exists with non-stub content | None |
| `found_empty_stub` | Layer file with schema-correct stub frontmatter, body empty | Operator can populate when ready |
| `missing` | No file at expected path | Run installer to create stub OR set explicit env override |
| `skipped` | **RESERVED for v1** — explicit opt-out via `PRISM_GOVERNANCE_LAYER_SKIPPED_=true` env when implemented. Until skip mechanism ships, implementers MUST NOT infer `skipped` from missing files. | None when intentional opt-out |
| `invalid` | File exists but frontmatter fails schema validation | **OPERATOR ATTENTION** — fix file or escalate to Candi |
**`skipped` is reserved**; only emit it when an explicit opt-out env/flag is set. Missing files → `missing`, never `skipped` (Texi v0.2 amendment 4).
## 5. ORG.md discovery
Consumes ADR #47 v0.2 §4 directly. `prism_start.governance.layers.org.repo_local_used: true|false` reports whether repo-local override was used; mandatory canonical ORG cannot be bypassed.
## 6. PRISM\_GLOBAL.md source policy (Texi `d15c8380` SPEC-077 nit 2)
On first install:
1. If `$PRISM_ROOT/templates/PRISM_GLOBAL.md` is present AND schema\_version-compatible → **copy** template to governance root.
2. Else → **create empty schema-compatible stub.**
Installer reports:
* `copied_template` vs `created_stub`
* **Source hash + version** when `copied_template` (Texi nit 2): `template_source_hash` (sha256), `template_source_version` (schema\_version of source)
* Schema mismatch fallback reason (if applicable)
**Never overwrite** an existing `PRISM_GLOBAL.md` without explicit `force=true` flag.
## 7. `prism_start` response shape (Texi `d15c8380` SPEC-077 amendments 1, 3 — folded)
**Default-off invariant resolution** (amendment 1): when `PRISM_GOVERNANCE_RESOLVER_ENABLED=false`, the existing `prism_start` response shape and existing status card remain UNCHANGED. The `governance` block is OMITTED entirely. The `gov:` status-card field is rendered only when the flag is on.
When flag is ON, response gains a `governance` block:
```jsonc theme={null}
{
"context": { ... }, // existing
"all_projects": [ ... ], // existing
"rules_reminders": [ ... ], // existing
"controller_status": { ... }, // existing
"governance": { // NEW (this SPEC)
"resolver_enabled": true,
"layout": "sibling-projects",
"governance_root": "/Users/fpn/projects/.prism-governance",
"tenant_slug": "personal",
"org_slug": "personal",
"project_slug": "prism",
"layers": {
"global": {"state": "found_nonempty", "path": "...", "schema_version": 1},
"tenant": {"state": "found_empty_stub", "path": "...", "schema_version": 1},
"org": {"state": "found_nonempty", "path": "...", "schema_version": 1, "repo_local_used": false},
"project": {"state": "found_nonempty", "path": "...", "schema_version": 1}
},
"user_session_runtime": { // NOT counted in N/M (see §8)
"state": "found_nonempty",
"sources": ["env", "session"]
},
"mandatory_guardrails": [ // NEW per amendment 3
{"path": "...", "layer": "tenant", "rules_count": 3}
],
"conflicts": [ // NEW per amendment 3 + ADR #47 §6
{"kind": "...", "broader_path": "...", "narrower_path": "...", "winner": "...", ...}
],
"bios_source": "CLAUDE.md",
"summary": "gov:4/4 ok"
},
"session_id": "...",
...
}
```
## 8. Status card field split (Texi `d15c8380` SPEC-077 amendments 1, 2 — folded)
When `PRISM_GOVERNANCE_RESOLVER_ENABLED=on`, status card adds `gov:` field:
```
[Prism · Phase · · rules_reminders: · gov:]
```
When flag is **off**, the status card is unchanged from current (no `gov:` field). No fallback `gov:off` rendering — the field is simply absent.
`` shape (when flag on):
* `gov:N/M ok` — N of M file-bearing layers in `found_nonempty` or `found_empty_stub`, none `invalid`
* `gov:N/M warn` — at least one file-bearing layer `missing` or `skipped`, none `invalid`
* `gov:invalid` — at least one layer `invalid` — OPERATOR ATTENTION
* `gov:offline` — governance layer cannot be resolved (offline mode)
**M = 4 file-bearing layers** (global / tenant / org / project) per Texi v0.2 amendment 2. User/session/runtime is reported separately in detail JSON (`governance.user_session_runtime`); not counted in `M` because it is not a static file layer.
Detail-only fields (NOT in card; available in `prism_start` JSON `governance` block): layout, governance\_root, all slugs, per-layer paths, BIOS source, source hashes, schema versions, mandatory\_guardrails array, conflicts array, user\_session\_runtime sub-block, invalid/missing reasons, offline fallback details.
## 9. Stub frontmatter contract (unchanged from v0.1)
```markdown theme={null}
---
schema_version: 1
governance_layer: tenant # or global / org / project
slug: personal
status: empty
created_by: prism_install_local
created_at: 2026-05-04T00:00:00Z
---
```
Body intentionally blank. Operator fills the file later. Installer never re-edits an existing stub.
## 10. Layout detection / collision handling (unchanged from v0.1)
Per Lafonda v0.2 §5 + ADR #47 v0.2 §5. Explicit-wins → both-detected ambiguity-stops → installer-first-run-defaults-sibling-projects → runtime-resolver-no-silent-pick.
## 11. Engineering inventory (Texi `d15c8380` SPEC-077 nit 1 — module-neutral)
| Surface | Change |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `prism_start` response | Add `governance` block per §7 (only when flag on) |
| Status card composition | Add `gov:` field per §8 (only when flag on) |
| Backend status-aggregation service (module name TBD at impl) | Add governance-block computation alongside existing project + agents + recent\_postmortems |
| Backend route for status payload | No route change; response shape additive |
| Launcher prompts (`bin/coder.sh` / `coder.ps1`) | No change in this SPEC; identity-field changes land in ADR #46/#48 |
| Ring-1 templates (`templates/CLAUDE.md`, `AGENTS.md`) | Update boot-sequence wording: replace "ORG.md > PRISM.md" with scoped-override-semantics; reference SPEC-077 + ADR #47 |
| ORG / PRISM discovery helper | New helper module; resolves all 5 layers; returns per-layer state + conflicts array |
| Installer env-block writer | Lafonda v0.2 — Phase 2 implementation gated on Blocker #1 (this SPEC) + #2 (ADR #47) ratification |
| Dashboard boot-report panel | Porsche acceptance gate per Plan #10 v0.2 §5 |
(Spec language kept module-neutral per Texi nit 1; exact backend module name verified during implementation.)
## 12. Acceptance criteria (Texi `d15c8380` SPEC-077 amendment 6 — tests added)
1. `prism_install_local` reports layout + governance\_root + per-layer creation results (4-bucket idempotency report per Lafonda v0.2 §4).
2. With flag ON: `prism_start` response includes `governance` block per §7; status card displays `gov:N/M ` per §8 with M=4.
3. Per-layer state classification matches §4 across 4 file-bearing layers; user/session/runtime reported separately.
4. Dual ORG sources: when both `$PROJECT_ROOT/ORG.md` and repo-local `./ORG.md` exist, response reports the conflict + identifies effective source.
5. PRISM\_GLOBAL.md source policy: fresh install with schema-compatible template → `copied_template` + `template_source_hash` + `template_source_version`. Without template → `created_stub`. Existing PRISM\_GLOBAL.md never overwritten without `force=true`.
6. Status card field split: card shows compact summary; detail-only fields ONLY in `prism_start` JSON, never in card text.
7. Porsche measurement gate: boot-correctness panel shows per-layer state distribution + mandatory-guardrail counts BEFORE flag flips default-on.
8. **NEW TESTS** (Texi v0.2 amendment 6):
* **Invalid frontmatter test:** layer file with bad `schema_version` → state=`invalid`; `prism_start.governance.conflicts` contains entry with `kind=invalid_frontmatter`.
* **Dual ORG with mandatory canonical test:** canonical ORG marked `mandatory: true` + repo-local ORG present → canonical wins; conflict reported with `winner=broader, rationale=mandatory_guardrail`.
* **Layout collision test:** both `.prism-governance/` and `governance/` present, no env override → installer + resolver fail-fast with structured error listing collisions.
* **Feature flag OFF inertness test:** with `PRISM_GOVERNANCE_RESOLVER_ENABLED=false`, response shape EXACTLY matches pre-SPEC-077 shape (no `governance` block, no `gov:` in card).
* **Feature flag ON compact summary test:** with flag on, status card includes `gov:N/M ` matching `governance.summary` field.
## 13. Feature flag (Texi `d15c8380` SPEC-077 amendment 5 — folded)
Per Plan #10 v0.2 §4 strict policy + cross-blocker amendment 2 (mirrored shape):
* **Flag name:** `PRISM_GOVERNANCE_RESOLVER_ENABLED`
* **Default:** `false` (off)
* **Owner:** Donna (engineering) until SPEC ratifies; Donna PO post-ratification
* **Operator-visible state:** when ON, `prism_start.governance.resolver_enabled: true` + dashboard panel; when OFF, no `governance` block (visibility from absence)
* **Default-off invariant:** when flag is off, `prism_start` returns existing response shape; status card unchanged; existing flows behaviorally unchanged. NO shadow-mode telemetry — telemetry consumes the same response field, so when flag off, no telemetry is generated. Porsche measurement panels source from on-flag deployments only; default-off measurement gate evaluates panel after operator flips on in test environment first.
* **Default-off tests:** see §12 amendment 6 — invariance test required before merge.
* **Rollback instructions:** unset env var → resolver returns to current behavior; no schema changes to roll back; dashboard panel hides.
* **Shadow mode:** **NO** (Texi amendment 5). Resolver does NOT run when flag off. If shadow telemetry is needed later, define in a follow-up SPEC.
## 14. Out of scope (deferred to other Wave 1 blockers — clarified per Texi `d15c8380` SPEC-077 amendment 7)
* **Layer precedence + override semantics in detail** → ADR #47 v0.2 (Blocker #2)
* **Identity / persona / specialization field model** → ADR #46 / #48 (Blocker #3)
* **Memory-domain-aware recall** → Wave 2 Blocker #5
* **Tri-graph governance recall** → Wave 3 Blocker #6
* **Method fragments** → Wave 2 Blocker #4
**SPEC-021 relationship (Texi amendment 7):** SPEC-077 EXTENDS and SUPERSEDES the boot-card / governance-reporting portion of SPEC-021 ONLY. The session-bootstrap-enforcement portions of SPEC-021 (controller registration, session lifecycle, master election) remain SPEC-021's domain and are NOT touched by SPEC-077.
## 15. Cross-references
* ADR #47 v0.2 — Layer Precedence + Override Semantics (this SPEC consumes; supersedes ADR #45)
* ADR #46/#48 v0.2 — Persona / Identity / Specialization Field Model (orthogonal; same Wave 1)
* Plan #10 v0.2 (`prism_plan` number=10, ID `d23a0b0d`)
* Lafonda install plan v0.2
* Candi research §"Agreement 1, 2"
* Candi `3bb3d70d` (3 governance-input answers folded)
* Texi `e215ed87` + `fe4cbb13` + `d15c8380` (architectural reviews; v0.2 folds d15c8380)
* SPEC-021 (extended/superseded only on boot-card/governance-reporting per §14)
* SPEC-031 (Session lifecycle — `prism_status` payload basis; no change)
* ADR #16 (BIOS sync gate — adjacent; no change)
## 16. Authority
Donna authored under Plan #10 PO authority per operating contract rule 1. Texi reviewed v0.1 (`d15c8380`) with binding amendments; v0.2 folds them. Donna ratifies per Ring authority. Sealing AFTER ADR #47 per Plan #10 v0.2 amendment 1.