jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
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.
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
---
|
||
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.
|