​

Install-Lane Plan: Governance Hierarchy Env Vars + Directory Skeletons

• §3: Add row for PRISM_GOVERNANCE_LOOKUP_ENABLED (default false, per SPEC-080 §13). Identical shape to GOV / CONSENSUS / MEMDOM flags.
• §12.2: 2-line edit per Option B pattern — append PRISM_GOVERNANCE_LOOKUP_ENABLED to FEATURE_FLAGS + add optional override field on EnvBlockInputs. Third config-only flag add since the refactor; pattern remains 2 lines.
• §lifecycle: Wave 3 install-lane prerequisite for SPEC-080 Phase 2 (prism_governance_lookup verb) — once this PR deploys to server1, Donna’s PR #127 deploy gate clears. Verb default-off invariant preserved: flag’s existence in env file does NOT trigger any new behavior in this PR.

• §3: Add row for PRISM_MEMORY_DOMAINS_ENABLED (default false, per SPEC-079 §13). Identical shape to GOV + CONSENSUS flags.
• §12.2: 2-line edit per Option B pattern — append PRISM_MEMORY_DOMAINS_ENABLED to FEATURE_FLAGS + add optional override field on EnvBlockInputs. Validates the Option B refactor’s promise: subsequent flags really are config-only.
• §13: 4 Wave 2 SPEC-079 smoke cases verified pre-PR (21 assertions PASS) — all 3 flags default-false on fresh install; operator-set MEMDOM=true preserved; cross-flag independence (GOV=true + MEMDOM=true + CONSENSUS=false coexist); byte-compat for pre-PR-#121 envs.
• §lifecycle: Wave 2 install-lane fully closed once this PR + PR #120 both deploy. Wave 2 Blockers #4 + #5 install-lane DONE.

• §3: Add row for PRISM_CONSENSUS_PARALLELISM_ENABLED (default false, per SPEC-078 §13). Same shape as PRISM_GOVERNANCE_RESOLVER_ENABLED.
• §12.2: envBlockWriter.ts refactored to FEATURE_FLAGS array (Option B). Adding a new flag is now a 2-line change: append to FEATURE_FLAGS + add optional override field on EnvBlockInputs. SPEC-079’s PRISM_MEMORY_DOMAINS_ENABLED will follow this pattern when ratified.
• §13: 5 Wave 2 smoke cases verified pre-PR — both flags default-false on fresh install; operator-set GOV=true preserved; operator-set CONSENSUS=true preserved; mixed flag values preserved; byte-compat for pre-Wave-2 envs.
• §lifecycle: Plan #10 Wave 1 Blocker #1: CLOSED (PR #114+#115+#116+#117 merged+deployed+smoked). Wave 2 Blocker #4 install-lane: PR drafted (this revision).

• Architecture (v0.1): Texi 26e74209 — accept_with_amendments. All amendments folded into v0.2.
• Engineering authorization (v0.2): Donna d9cd9d0c — engineering_authorization_granted_for_phase_2_PREP_only.
• v0.3 input: SPEC-077 v0.2 (Donna e29ecde6, Texi d15c8380 7 binding amendments folded) + ADR #47 v0.2 (Donna 7fff65bd, supersedes ADR #45). Donna PO ratified per 639e652f Donna as PO.
• v0.4 trigger: PR #116 boot-report extension merged at 1dcf5f3 + Samantha deploy-green at image 6a5ff3387422.... Donna chained TaskAssigned f8cbe3d9 → Lafonda activation per signal 13d22051 standby commitment.

• §11: Status flipped from “held” to “active”. Wave 1 install-lane Blocker #1 closure pending this PR’s deploy + smoke verification.
• §12.2: Removed “(held)” annotation on tier1c.ts wiring; helpers now actively called.
• §13: Smoke matrix annotated — cases 1-9 all PASS pre-activation (5 helper-level + 4 just-verified before this PR); cases 10-11 ready to run via integration through Samantha’s deploy lane post-merge.

• §4: Stub frontmatter optionally accepts mandatory: true (per ADR #47 §3) for guardrail rules; installer never sets it (PO/operator-controlled), but the create-or-merge logic must preserve it on existing files.
• §4: Idempotency report adds template_copied[] for PRISM_GLOBAL.md template-copy outcomes (per SPEC-077 §6); existed_preserved[] items for layer files with mandatory: true get an extra mandatory_guardrail: true flag for operator visibility.
• §6: Boot-report skipped layer state is RESERVED for v1 (per SPEC-077 §4 + Texi v0.2 amendment 4); installer MUST NOT infer skipped from missing files. Lafonda’s install verbs only emit skipped once a PRISM_GOVERNANCE_LAYER_SKIPPED_<LAYER>=true env mechanism ships (post-v1).
• §6: Add ORG.md dual-source row (per ADR #47 §4): canonical $PROJECT_ROOT/ORG.md vs repo-local ./ORG.md — installer writes to canonical location on sibling-projects layout; resolver reports repo_local_used when override active.
• §6: Add feature flag row PRISM_GOVERNANCE_RESOLVER_ENABLED (default false, per SPEC-077 §13). Installer writes the flag to $HOME/.prism/env on every install with explicit false default so operators have a clear toggle; install-verb behavior is unaffected by the flag (only the runtime resolver checks it).
• §10: Resolved — PRISM_GLOBAL.md source policy LOCKED by SPEC-077 §6: template-copy-if-present (schema-version-compatible) + report template_source_hash (sha256) + template_source_version; never overwrite without force=true.
• §12.2: Add 6th helper templateCopier.ts for the PRISM_GLOBAL.md template-copy logic.
• §12.3: Locked TS shape for template_copied[] and mandatory_guardrail flag.
• §13: Add 6 new smoke cases — PRISM_GLOBAL.md template-copy compatible/incompatible/existing-not-overwritten; mandatory-guardrail preservation on re-run; feature-flag-OFF default written; skipped-state-not-inferred-from-missing.

• §3: Defer PRISM_USER_SLUG (Texi: PII / cross-machine drift); keep PRISM_CONFIG_PROFILE in v1; PRISM_SURFACE remains runtime-only.
• §4: Add schema_version to stub frontmatter; explicit slug validation [a-z0-9-]+ with structured error and no silent normalization; asymmetric PRISM.md write policy spelled out.
• §5: Resolve the v0.1 contradiction — installer-first-run vs runtime-resolver behaviors are now distinct sub-rules.
• §4 (new): Structured idempotency report contract (counts + paths for created / existed_preserved / skipped_project_owned / drift_or_invalid_frontmatter).
• §6: Boot-report layer states expanded from 4 to 5 (found_nonempty, found_empty_stub, missing, skipped, invalid).
• §6 (new): Shared resolver helper + shared env-block writer helper; no separate prism_write_env verb yet.

​

1. Source Artifacts

• governance-sim/README.md — locked boot model + governance precedence + 7+3 env var contract
• governance-sim/central-registry/README.md — Option A layout (Prism-managed governance/ tree under $PRISM_ROOT)
• governance-sim/sibling-projects/README.md — Option B layout (.prism-governance/ under $PROJECT_ROOT + project-local PRISM.md)
• docs/research/prism-governance-improvement-recommendations-2026-05-04.md — P0–P2 recommendations including Agreement 1 (static BIOS first, prism_start first runtime action) and Agreement 2 (governance layers need discoverable filesystem roots)

​

2. Phase Split

​

Phase 1 — Plan & design (this document; no code changes)

• Define env-var write contract for the installer.
• Define directory skeleton creation logic per layout.
• Define layout-detection and collision-handling rules.
• Define idempotency / re-run behavior.
• Define install-time defaults for each new env var.
• Identify lane crossings and route them to the correct owners.

​

Phase 2 — Implementation (gated on governance-resolution spec approval)

• Wire env-var write block into prism_install_local + prism_install_lan.
• Wire directory skeleton creation per layout into the same verbs.
• Implement PRISM_GOVERNANCE_LAYOUT explicit-wins → detect → ambiguity-stops resolver.
• Update .env.example and any BIOS/install templates referencing the new vars.
• Smoke on mini4.home.lan (single-operator local install path per memory reference_mini4_ssh.md) and on server1.home.lan (LAN install path).
• Bake the prism_start boot-report extension hooks (cross-lane — see §6).

​

3. Env Var Contract (installer-written)

​

Minimum (must be written by every install verb)

​

Optional / deferred

​

4. Directory Skeleton Contract

​

Sibling-projects (default)

$PROJECT_ROOT/.prism-governance/
  global/
    PRISM_GLOBAL.md   ← stub if missing, untouched if present
  tenants/
    $PRISM_TENANT_SLUG/
      TENANT.md       ← empty stub
      orgs/
        $PRISM_ORG_SLUG/
          ORG.md      ← empty stub

​

Central-registry (opt-in via flag/env)

$PRISM_ROOT/governance/
  global/
    PRISM_GLOBAL.md   ← stub if missing
  tenants/
    $PRISM_TENANT_SLUG/
      TENANT.md       ← empty stub
      orgs/
        $PRISM_ORG_SLUG/
          ORG.md      ← empty stub
          projects/
            $PRISM_PROJECT_SLUG/
              PRISM.md   ← stub if missing; never overwrite if present

​

Stub file shape (every empty placeholder)

---
schema_version: 1
governance_layer: tenant   # or org / project / global
slug: personal
status: empty
created_by: prism_install_local
created_at: 2026-05-04T00:00:00Z
# mandatory: true            # OPTIONAL — operator/PO sets this on rules that
#                            # cannot be overridden by narrower layers
#                            # (per ADR #47 §3). Installer NEVER sets it.
---

​

PRISM_GLOBAL.md template-copy policy (per SPEC-077 §6)

1. Template present + schema-version-compatible ($PRISM_ROOT/templates/PRISM_GLOBAL.md exists AND its frontmatter schema_version matches the installer’s expected version) → copy the template to $PRISM_GOVERNANCE_ROOT/global/PRISM_GLOBAL.md. Idempotency report records template_copied[] entry with path, source_path, source_hash (sha256 of source bytes), source_version (template’s schema_version).
2. Template absent OR schema-version-incompatible → create empty stub with the standard frontmatter shape above. Idempotency report records the stub in created[].
3. Existing PRISM_GLOBAL.md present → never overwrite unless force=true flag passed to the install verb. Idempotency report records existed_preserved[] entry.

​

Slug validation (installer-written slugs only)

​

Asymmetric PRISM.md write policy (per Texi nit #3)

​

Idempotent re-run report contract (per Texi review §“Idempotent re-run” + SPEC-077 v0.2 §6)

{
  "layout": "sibling-projects",
  "governance_root": "/Users/fpn/projects/.prism-governance",
  "created":                      [{"path": "...", "layer": "..."}],
  "existed_preserved":            [{"path": "...", "layer": "...", "mandatory_guardrail": false}],
  "skipped_project_owned":        [{"path": "...", "reason": "project_PRISM_md_never_overwritten"}],
  "drift_or_invalid_frontmatter": [{"path": "...", "issue": "schema_version mismatch | invalid layer field | slug mismatch"}],
  "template_copied":              [{"path": "...", "source_path": "...", "source_hash": "sha256:...", "source_version": 1}]
}

​

5. Layout Detection / Collision Handling

​

Common rule (both contexts)

1. Explicit wins. If PRISM_GOVERNANCE_LAYOUT is set in the env or passed as an install flag, use it.
2. Both detected → ambiguity-stops. If both .prism-governance/ (sibling) and governance/ (central) trees are present and no explicit selector resolves the conflict, fail-fast with a structured error listing every collision found and the explicit PRISM_GOVERNANCE_LAYOUT=… resolution. (Per feedback_preflight_checks.md.)

​

Installer-specific rule (first-run, none-present)

• If no env / flag and no existing tree, the installer defaults to sibling-projects, creates the skeleton, and writes the env block.
• The installer prints the chosen layout in its summary (and includes it in the re-run report) so the operator can override on re-run via PRISM_GOVERNANCE_LAYOUT=central-registry.
• Rationale: the installer is the initialization surface — its job is to put the system into a known state. Leaving an uninitialized system because a default wasn’t explicit would be hostile.

​

Runtime resolver rule (prism_start, none-present)

• If prism_start finds no env-block layout selector and no existing tree at any standard location, it reports missing / ambiguous per layer and does NOT silently choose a layout.
• Rationale: the resolver is the enforcement surface — silently picking a layout at runtime would mask install drift. The fix is to re-run the installer (or set the env var explicitly), not to have the resolver guess.

​

6. Lane Crossings (NOT in this plan)

​

Implementation pattern (per Texi’s answers to optional questions in 26e74209)

• Resolver code is shared, parametrized by layout. Both layouts resolve the same conceptual layers and differ only by path templates — separate code paths would drift.
• Env-block writer is a shared internal helper used by both prism_install_local and prism_install_lan. Do not expose prism_write_env as a public verb yet; promote to a verb only if a real operator workflow needs repair/rotation without a full reinstall.
• Naming is PRISM_GOVERNANCE_ROOT (long form) — semantic clarity wins over shell-typo risk; matches PRISM_GOVERNANCE_LAYOUT.

​

7. Acceptance Criteria Mapping (back to TaskAssigned 0af3c095)

​

8. Open Dependencies (block Phase 2)

1. Texi architectural review of §3/§4/§5 dispositions — especially: stub-file frontmatter shape, PRISM_USER_SLUG/PRISM_CONFIG_PROFILE write decision, ambiguity-stop semantics.
2. Donna engineering authorization once Texi review settles (Frank-away coverage path).
3. Governance-resolution spec ratified by Donna.
4. Confirmation of canonical env-block surface location (likely $HOME/.prism/env per host_contract; needs read of existing installer code at implementation time).
5. prism_start boot-report extension specced + scheduled (Donna) so the hook exists when Phase 2 ships.

​

9. Smoke Test Plan (Phase 2 only — not exercised by this draft)

• mini4 (Linux, lafonda@mini4.home.lan) — fresh prism_install_local against an empty $PROJECT_ROOT; verify env-block written with all 7 minimums + 2 optionals (PRISM_USER_SLUG, PRISM_CONFIG_PROFILE); verify .prism-governance/ skeleton created with correct stubs; re-run to confirm idempotency.
• server1 (donna@server1.home.lan) — prism_install_lan re-run against an installed target; verify env block + skeleton on the LAN target; verify deploy delta still ships per existing SPEC-055 contract.
• Collision case — manually pre-seed both .prism-governance/ and governance/; run installer with no PRISM_GOVERNANCE_LAYOUT; assert structured failure listing both detected trees.
• Override case — set PRISM_GOVERNANCE_LAYOUT=central-registry on a fresh local install; assert governance/ skeleton created under $PRISM_ROOT.

​

10. Open Questions

​

Resolved by v0.2 (Texi review 26e74209)

• PRISM_USER_SLUG ship vs defer → defer (PII / cross-machine drift). §3.
• PRISM_CONFIG_PROFILE single vs list → single value derived from install verb. §3.
• Interactive prompt vs fail-fast on ambiguity → fail-fast at runtime; installer first-run defaults to sibling-projects. §5.
• Slug charset validation → [a-z0-9-]+ lowercase, structured error, no silent normalization. §4.

​

Resolved by v0.3 (SPEC-077 v0.2 + ADR #47 v0.2)

• PRISM_GLOBAL.md template-vs-stub disposition → template-copy-if-present + schema-version-compatible; report source_hash (sha256) + source_version; never overwrite without force=true per SPEC-077 §6. Plan §4 + §12.2 (templateCopier.ts) + §13.8 codify.

​

Still open (none — all routed)

​

11. Plan Status & Next Step

• ✅ v0.1 reviewed by Texi (26e74209 — accept_with_amendments).
• ✅ v0.2 folds all 4 required changes + 4 architectural nits.
• ✅ Donna engineering authorization (d9cd9d0c) for Phase 2 PREP; implementation behavior gated on Plan #10 Blockers #1 + #2 ratification.
• ✅ Launcher source-block patch shipped as DRAFT PR #114 (queued for post-ratification merge).
• ✅ v0.3 folds SPEC-077 v0.2 (e29ecde6) + ADR #47 v0.2 (7fff65bd) contract additions.
• ✅ PRISM_GLOBAL.md source policy resolved by SPEC-077 §6 (template-copy-if-present + schema-version-compatible + sha256 hash report).
• ✅ skipped state RESERVED for v1 per SPEC-077 §4; installer never infers from missing files.
• ⏳ Donna engineering authorization on v0.3 — pending; will be requested after install-verb PR draft lands.
• ⏳ Install-verb PR draft — Lafonda next deliverable; will queue alongside PR #114 for post-ratification merge.
• ⏳ Donna spec ratification — gates Phase 2 implementation behavior shipping.
• Lafonda current activity: drafting install-verb PR per rule 7 (milestones not stops). Speculative draft per Donna 20460d0f decision (1 of 3 optional asks: q1_speculative_install_verb_pr: YES, start drafting).

​

12. Phase 2 Implementation Map (PREP — locked at v0.2 + Donna d9cd9d0c)

​

12.1 Env-block surface

​

12.2 Install-verb modification mapping

• envBlockWriter.ts — atomic write of $HOME/.prism/env with KEY=VALUE pairs, preserving operator-added vars not in the governance set. Always writes PRISM_GOVERNANCE_RESOLVER_ENABLED=false on first install so operators have a clear toggle (per SPEC-077 §13 + plan §6); preserves operator-set value on re-run if changed to true.
• skeletonCreator.ts — ensureGovernanceSkeleton({layout, governanceRoot, tenantSlug, orgSlug, projectSlug}) — create-or-merge directory structure + stub frontmatter writes per §4. Calls templateCopier.ts for PRISM_GLOBAL.md specifically.
• templateCopier.ts — PRISM_GLOBAL.md template-copy logic per SPEC-077 §6: check $PRISM_ROOT/templates/PRISM_GLOBAL.md presence + schema_version compatibility; on match, copy + compute sha256 + report template_copied[] entry; on mismatch or absence, fall through to stub creation; never overwrite existing without force=true.
• layoutResolver.ts — explicit-wins → detect → ambiguity-stops logic per §5.
• slugValidator.ts — [a-z0-9-]+ validation, structured error before any write.
• idempotencyReport.ts — type definition + builder for the §4 5-bucket report (4 original + template_copied[]).

​

12.3 Idempotency report — locked TypeScript shape

type GovernanceLayer = "global" | "tenant" | "org" | "project";

interface GovernanceIdempotencyReport {
  layout: "sibling-projects" | "central-registry";
  governance_root: string;
  created:                      Array<{ path: string; layer: GovernanceLayer }>;
  existed_preserved:            Array<{ path: string; layer: GovernanceLayer; mandatory_guardrail: boolean }>;
  skipped_project_owned:        Array<{ path: string; reason: "project_PRISM_md_never_overwritten" }>;
  drift_or_invalid_frontmatter: Array<{ path: string; issue: "schema_version_mismatch" | "invalid_layer_field" | "slug_mismatch" }>;
  template_copied:              Array<{ path: string; source_path: string; source_hash: string; source_version: number }>;
}

​

13. Phase 2 Smoke Test Checklist (post-ratification)

​

13.1 Local install — mini4 (lafonda@mini4.home.lan, Ubuntu 24.04)

• Fresh empty $PROJECT_ROOT (no .prism-governance/); run prism_install_local.
• Assert $HOME/.prism/env created with all 7 minimums + PRISM_CONFIG_PROFILE=local (8 vars total in v1).
• Assert .prism-governance/ skeleton created per §4 with schema_version: 1 in every stub.
• Assert structured re-run report returned (4 buckets present even if empty).
• Re-run prism_install_local; assert created: [] + existed_preserved populated for every stub + drift_or_invalid_frontmatter: [].
• Manually edit a stub frontmatter to break schema_version; re-run; assert drift_or_invalid_frontmatter lists the file with issue: "schema_version_mismatch".
• Assert project repo’s PRISM.md untouched across all runs.

​

13.2 LAN install — server1 (donna@server1.home.lan)

• Re-run prism_install_lan against installed target; assert governance env-block + skeleton present on remote + locally; assert existing upgrade-full deploy delta still ships per SPEC-055.
• Assert remote $HOME/.prism/env matches local except for target-specific overrides (none in v1).
• Confirm SSH-key-based deploy chain (reference_server1_ssh.md) unchanged.

​

13.3 Collision case (any host)

• Pre-seed both .prism-governance/ (under $PROJECT_ROOT) and governance/ (under $PRISM_ROOT); run installer with no PRISM_GOVERNANCE_LAYOUT env.
• Assert structured failure with both detected paths in error payload + the PRISM_GOVERNANCE_LAYOUT=… resolution hint.

​

13.4 Override case

• Set PRISM_GOVERNANCE_LAYOUT=central-registry on a fresh local install; assert $PRISM_ROOT/governance/ skeleton created (not .prism-governance/); assert PRISM_GOVERNANCE_LAYOUT=central-registry written to $HOME/.prism/env.

​

13.5 Slug validation

• Pass PRISM_TENANT_SLUG=PersonalCo (mixed case); assert structured error before any file write.
• Pass PRISM_TENANT_SLUG=personal-co (valid); assert acceptance + skeleton created with that slug.

​

13.6 Launcher source-block

• After prism_install_local, run bin/coder.sh -as Lafonda (or bin/coder.ps1 -as Lafonda on Windows); assert all 8 governance vars are visible to the spawned MCP server process (via mcp-node process.env read — verify with prism_status extended payload once Donna’s boot-report extension lands).

​

13.7 Idempotency-report consumer (post-Donna boot-report)

• After install, run prism_start; assert per-layer state classification matches the v1-active vocabulary (found_nonempty, found_empty_stub, missing, invalid). Verify skipped is NEVER emitted for missing files (per SPEC-077 §4 + Texi v0.2 amendment 4); skipped reserved for explicit opt-out env mechanism (post-v1).

​

13.8 PRISM_GLOBAL.md template-copy (per SPEC-077 §6)

• Template present + schema-compatible: seed $PRISM_ROOT/templates/PRISM_GLOBAL.md with schema_version: 1 frontmatter + content; run prism_install_local against fresh $PROJECT_ROOT; assert template_copied[] entry with correct path, source_path, source_hash (validate sha256 matches), source_version: 1.
• Template absent: remove $PRISM_ROOT/templates/PRISM_GLOBAL.md; run prism_install_local; assert created[] entry for the global stub (no template_copied[] entry).
• Template schema-incompatible: seed template with schema_version: 999; run prism_install_local; assert installer falls through to stub creation (created[] entry for global stub, NOT template_copied[]); structured warning surfaced about template version mismatch.
• Existing PRISM_GLOBAL.md never overwritten: pre-seed governance root with operator-edited PRISM_GLOBAL.md; run prism_install_local; assert existed_preserved[] entry; file unchanged on disk; assert prism_install_local with force=true overwrites (operator confirmation path).

​

13.9 Mandatory guardrail preservation

• Pre-seed $PROJECT_ROOT/.prism-governance/tenants/personal/TENANT.md with frontmatter including mandatory: true; run prism_install_local; assert existed_preserved[] entry has mandatory_guardrail: true. Re-run; assert flag still surfaces; file content unchanged.

​

13.10 Feature flag default-OFF

• Fresh prism_install_local; assert $HOME/.prism/env contains PRISM_GOVERNANCE_RESOLVER_ENABLED=false; assert no governance block in prism_start response (per SPEC-077 §13 default-off invariant).
• Operator manually flips to true in env file; re-run prism_install_local; assert installer preserves operator’s true value (does NOT reset to false on idempotent re-run).
• Reset to false; re-run prism_install_local; assert idempotency report shows env block unchanged.

​

13.11 Cross-spec contract checks

• Layout-collision case (§13.3) matches SPEC-077 §10 + ADR #47 §5 fail-fast contract: structured error includes both detected paths + the explicit PRISM_GOVERNANCE_LAYOUT=… hint.
• Per ADR #47 §4: when both $PROJECT_ROOT/ORG.md and repo-local ./ORG.md exist post-install, prism_start.governance.layers.org.repo_local_used: true (cross-lane verification with Donna’s resolver — gated on Phase 2 + Donna’s helper landing).