stack/packages/mosaic/framework/constitution/LAYER-MODEL.md

Mosaic Layer Model (governance spec)

Source-only. This file documents the framework's layering for maintainers. It is NOT deployed to ~/.config/mosaic/ and is never resident in an agent's context. The deployed AGENTS.md is the thin load-order dispatcher; the deployed CONSTITUTION.md is L0.

The legitimacy test

A layer boundary is legitimate iff the two sides differ in owner, upgrade-fate, OR residency. This single test decides every split and rejects gratuitous ones.

The layers

#	Layer	Owns	Owner	Upgrade fate	Residency	Deployed path
L0	Constitution	Irreducible non-negotiable law: hard gates, integrity, escalation triggers, block-vs-done, mode declaration, two-axis precedence, "hooks are the gate", the framework-PR firewall, structured-reasoning capability, tier-aware self-load	Framework	Overwritten verbatim every upgrade; user MUST NOT edit	Always resident	~/.config/mosaic/CONSTITUTION.md
L1	Standards & Guides	How to do the work well: secrets/ESO, trunk-based git, image tagging, the E2E procedure, QA matrix, orchestrator protocol, all guides/*	Framework (a deployment may tighten via overlay)	Overwritten; user delta in STANDARDS.local.md; guides never forked	STANDARDS.md resident; guides/* on-demand	~/.config/mosaic/STANDARDS.md, guides/*
L2	Persona (SOUL)	Agent name, tone, role, communication style, persona principles	User (init-generated)	Never overwritten	Always resident	~/.config/mosaic/SOUL.md (+ optional SOUL.local.md)
L3	Operator (USER)	Human name, pronouns, timezone, accessibility, comms prefs, projects, operator policy (e.g. merge-authority delegation), operator tool paths/env	User (init-generated)	Never overwritten	Always resident	~/.config/mosaic/USER.md (+ optional USER.local.md, policy/*.md)
L4	Project / Runtime mechanism	Per-repo AGENTS.md deltas; harness-specific mechanism only (subagent syntax, hook/MCP wiring, injection tier, capability bindings)	Repo / framework	Project file user-owned; runtime mechanism overwritten	Project in-repo; runtime resident (small)	<repo>/AGENTS.md, runtime/<h>/RUNTIME.md

The deployed AGENTS.md is not a layer — it is the load-order dispatcher + Conditional Guide Loading table that routes to L0–L4. Framework-owned, overwritten on upgrade.

Precedence (two axes)

• Safety axis (gates, integrity, destructive actions): L0 is supreme. A lower layer may only make behavior stricter, never more permissive. Nothing may relax or suspend a gate.
• Taste axis (tone, formatting, verbosity, iconography): the operator layers (SOUL/USER) win over generic framework or model defaults.

What may live in L0

Only the irreducible: a rule that is genuinely universal, operator-agnostic, and a hard stop-condition or destructive-action guard. Procedure (wrapper paths, flags, how-to depth) belongs in L1 guides. If a rule is checkable, prefer a hook/CI gate over prose (see "hooks are the gate").

Overlay-eligibility (what a deployment may customize without forking)

• SOUL.md / SOUL.local.md — persona (taste axis).
• USER.md / USER.local.md / policy/*.md — operator profile + tighten-only operator policy.
• STANDARDS.local.md — tighten-only engineering-standard deltas.
• NOT overlay-eligible: CONSTITUTION.md, the dispatcher AGENTS.md, guides/* — framework-owned, overwritten on upgrade. To change these, contribute upstream (operator-agnostic only — firewall).

Enforcement ladder

mechanical (hook / CI) > resident-by-value (prompt injection) > file-read (self-load fallback). Every checkable gate should become a hook or CI check; the irreducible non-checkable gates are injected resident; bare launches fall back to an unconditional self-load read.