---
id: ROLE.1
status: ratified
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
---

# ROLE.1 — Role governance and configuration

## What a role is

A role is the reviewed, Git-owned capability ceiling for a class of seats:
Role Definition → immutable, digested Role Revisions → the active revision
projects `mosaic-core.manifest.json` and role-scoped settings. Authority table:
[[DATA.1-record-authority]]. Enforcement: [[AUTHZ.1-capability-authority]].

## The separation rule (Jason, 2026-08-31 — closes gap G6)

- The **seat** configuration surface NEVER directly modifies role config.
- The **role** configuration surface NEVER directly modifies seat config.
- A seat page writes at most a per-seat **overlay**, never the role file.

The original `role-harness-config/DESIGN.md` sentence constrained a surface it
never named — both readings were faithful, and reviewer context decided the
meaning. The staged amendment names the surface explicitly.

## Role configuration surface (WebUI page + CLI)

| Control | Notes |
|---|---|
| manifest editing | capability grants against the C1–C8 (later open) registry; schema-validated before commit |
| revision management | create revision, diff against active, activate, roll back — every revision immutable and digested |
| role links | which seats bind this role (read-only here; binding happens on the seat surface — see [[SEAT.1-seat-profile]]) |
| projection status | whether each bound seat's on-disk projection matches the active revision (`role check` class) |

All writes go through the one canonical role-management API (L2-D14) shared
with the CLI — the WebUI holds no separate role logic. Role management is
**principal-only** (L2-D13): no agent identity may ever invoke these
operations, and the API enforces that, not the page.

## Manifest invariants (must survive any surface)

- Committed, non-symlink, trusted-path — `mosaic-core`'s loader refuses
  violations; no surface may "fix" that by writing a symlink.
- Nothing env-overridable, nothing cwd-relative.
- `tools[]` equals exactly the bound bindings of granted capabilities.
- Role cross-checked against path at load.
## Specialization model (pulled 2026-08-31 from SPECIALIZATION-MODEL draft)

Four layers: **Role** (decision ownership and prohibited actions — few,
stable) → **Seat** (durable identity performing the role) → **Specialization**
(recurring domain/tools/behavior — open-ended, composable, never changes
authority) → **Task** (current activity). Rules:

- A seat has **exactly one role at a time**; never activate a second role
  inside a session. If authority changes, `mosaic config` reconfigures the seat
  and the coordinator starts a **clean session** — seat identity, history, and
  authorship survive; the old lease is revoked and a new incarnation starts.
  (Independent confirmation of register OD-02/OD-03 and the
  [[SESS.1-session-continuity]] two-operations rule.)
- Promotion to a new role only when decision ownership or prohibited actions
  materially differ; otherwise a formal specialization profile. Promotion
  triggers: different authority/external side effects, distinct
  credential/identity/data boundaries, added compliance controls, stable
  machine-readable I/O contract, required independence, deterministic gate
  behavior, repeated cross-seat use.
- Ad-hoc task-scoped specialization is valid only inside existing authority,
  with no new credential/safety/independence boundary; it dies with the task
  unless intentionally promoted.
- Anti-patterns: per-topic role explosion; role-subtype hierarchies no workflow
  consumes; model IDs or harness syntax inside specialization definitions;
  using specialization to bypass role authority or gates.

## E2 inputs (triage 2026-08-31; see [[GOV.2-docs-inventory]])

**Canonical ground truth**: `fleet/reference/role-classes.md`,
`fleet/concepts/role-authority-and-leases.md`, `fleet/how-to/customize-roles.md`
(baseline + `roles.local` resolver), `fleet/migration/legacy-class-aliases.md`,
`ADMIN-GUIDE/security/discord-ingress.md` (viewer/operator/admin precedent).
**Pending pulls**: brain `docs/guides/proposed/SPECIALIZATION-MODEL.md`
(Role/Seat/Specialization/Task layering — the conceptual basis of this
section's separation rule); `plans/2026-08-29-agent-enrollment-command-design.md`
(enrollment authority composed across three contracts — fragility to fix or document).
**Naming hazard**: "Tess"/"Ultron" are roster-class display aliases in fleet
how-tos and named product identities elsewhere (defect N6) — qualify every use.