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.