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>
5.7 KiB
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 dispatcherAGENTS.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.