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”:

Agent surface loads static BIOS at launch (Codex: AGENTS.md; Claude Code: CLAUDE.md).
Static BIOS instructs the agent to call prism_start.
prism_start is the first Prism runtime / tool action.
prism_start returns the effective live context + boot report.
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_<LAYER>=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:

If $PRISM_ROOT/templates/PRISM_GLOBAL.md is present AND schema_version-compatible → copy template to governance root.
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:<summary> status-card field is rendered only when the flag is on. When flag is ON, response gains a governance block:

{
  "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:<summary> field:

[Prism <pid> · Phase <n> · <session_status> · rules_reminders: <n> · gov:<summary>]

When flag is off, the status card is unchanged from current (no gov: field). No fallback gov:off rendering — the field is simply absent. <summary> 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)

---
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:<summary>` 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)

prism_install_local reports layout + governance_root + per-layer creation results (4-bucket idempotency report per Lafonda v0.2 §4).
With flag ON: prism_start response includes governance block per §7; status card displays gov:N/M <state> per §8 with M=4.
Per-layer state classification matches §4 across 4 file-bearing layers; user/session/runtime reported separately.
Dual ORG sources: when both $PROJECT_ROOT/ORG.md and repo-local ./ORG.md exist, response reports the conflict + identifies effective source.
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.
Status card field split: card shows compact summary; detail-only fields ONLY in prism_start JSON, never in card text.
Porsche measurement gate: boot-correctness panel shows per-layer state distribution + mandatory-guardrail counts BEFORE flag flips default-on.
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 <state> 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.

Specifications

Architectural Decisions

Plans

Retrospectives

SPEC-077: Canonical Boot + Governance Resolution

SPEC-077: Canonical Boot + Governance Resolution

SPEC-077 — Canonical Boot + Governance Resolution v0.2

Status

Shared definitions

1. Problem (unchanged from v0.1)

2. Locked boot model (unchanged from v0.1)

3. Governance layers (5)

4. Per-layer state classification (5-state)

5. ORG.md discovery

6. PRISM_GLOBAL.md source policy (Texi `d15c8380` SPEC-077 nit 2)

7. `prism_start` response shape (Texi `d15c8380` SPEC-077 amendments 1, 3 — folded)

8. Status card field split (Texi `d15c8380` SPEC-077 amendments 1, 2 — folded)

9. Stub frontmatter contract (unchanged from v0.1)

10. Layout detection / collision handling (unchanged from v0.1)

11. Engineering inventory (Texi `d15c8380` SPEC-077 nit 1 — module-neutral)

12. Acceptance criteria (Texi `d15c8380` SPEC-077 amendment 6 — tests added)

13. Feature flag (Texi `d15c8380` SPEC-077 amendment 5 — folded)

14. Out of scope (deferred to other Wave 1 blockers — clarified per Texi `d15c8380` SPEC-077 amendment 7)

15. Cross-references

16. Authority

​SPEC-077: Canonical Boot + Governance Resolution

​SPEC-077 — Canonical Boot + Governance Resolution v0.2

​Status

​Shared definitions

​1. Problem (unchanged from v0.1)

​2. Locked boot model (unchanged from v0.1)

​3. Governance layers (5)

​4. Per-layer state classification (5-state)

​5. ORG.md discovery

​6. PRISM_GLOBAL.md source policy (Texi d15c8380 SPEC-077 nit 2)

​7. prism_start response shape (Texi d15c8380 SPEC-077 amendments 1, 3 — folded)

​8. Status card field split (Texi d15c8380 SPEC-077 amendments 1, 2 — folded)

​9. Stub frontmatter contract (unchanged from v0.1)

​10. Layout detection / collision handling (unchanged from v0.1)

​11. Engineering inventory (Texi d15c8380 SPEC-077 nit 1 — module-neutral)

​12. Acceptance criteria (Texi d15c8380 SPEC-077 amendment 6 — tests added)

​13. Feature flag (Texi d15c8380 SPEC-077 amendment 5 — folded)

​14. Out of scope (deferred to other Wave 1 blockers — clarified per Texi d15c8380 SPEC-077 amendment 7)

​15. Cross-references

​16. Authority

SPEC-077: Canonical Boot + Governance Resolution

SPEC-077 — Canonical Boot + Governance Resolution v0.2

Status

Shared definitions

1. Problem (unchanged from v0.1)

2. Locked boot model (unchanged from v0.1)

3. Governance layers (5)

4. Per-layer state classification (5-state)

5. ORG.md discovery

6. PRISM_GLOBAL.md source policy (Texi `d15c8380` SPEC-077 nit 2)

7. `prism_start` response shape (Texi `d15c8380` SPEC-077 amendments 1, 3 — folded)

8. Status card field split (Texi `d15c8380` SPEC-077 amendments 1, 2 — folded)

9. Stub frontmatter contract (unchanged from v0.1)

10. Layout detection / collision handling (unchanged from v0.1)

11. Engineering inventory (Texi `d15c8380` SPEC-077 nit 1 — module-neutral)

12. Acceptance criteria (Texi `d15c8380` SPEC-077 amendment 6 — tests added)

13. Feature flag (Texi `d15c8380` SPEC-077 amendment 5 — folded)

14. Out of scope (deferred to other Wave 1 blockers — clarified per Texi `d15c8380` SPEC-077 amendment 7)

15. Cross-references

16. Authority