jason.woltje
13968e9a8b
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
4.8 KiB
id, status, ratified
| id | status | ratified |
|---|---|---|
| ROLE.1 | 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 configreconfigures 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.