Jason Woltje
319e21ddc0
Splits the 155-line thin-core AGENTS.md into: - defaults/CONSTITUTION.md (L0): gates + integrity + escalation + block-vs-done + mode + two-axis precedence + hooks-are-the-gate + framework-PR firewall + structured-reasoning capability + tier-aware self-load. Capability-verb authored. - defaults/AGENTS.md gutted to an ~80-line load-order dispatcher + guide table (kills the false "already in context, do not re-read" line). - constitution/LAYER-MODEL.md: source-only governance spec (layers + precedence). Non-regression wiring (fresh-install functional; upgrade-safety is P4): - launch.ts injects CONSTITUTION.md before AGENTS.md (tolerant of un-reseeded installs) - install.sh + file-adapter.ts seed CONSTITUTION.md (+ test fixture updated) Runtime adapters: capability-verb the sequential-thinking binding; claude/codex/ opencode restate the REQUIRED hard-stop, pi binds to native thinking (gate=false) — restores the force the adversarial review flagged as weakened. Gate hardening (dual-engine review): identity denylist now covers examples/ (closes the Codex open-source gap), self-test-first, *.json in scope, ci.yml typecheck depends on sanitization (fail-fast), L0 line-count ceiling (<=120). Adversarial gate-preservation review: every original rule traced to L0, the dispatcher, or a routed guide — nothing lost. Refs #542, closes #574 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
51 lines
5.7 KiB
Markdown
51 lines
5.7 KiB
Markdown
# 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.
|