jason.woltje
ad21ad7ac5
ci/woodpecker/pr/ci Pipeline failed
Ratifies the Mosaic Stack PRD rev1 (Jason Woltje, 2026-09-01) as project source of truth and installs the GOV.1 lifecycle model: - docs/PRD.md becomes a permanent shim (kind: shim, current_rev -> docs/PRDs/2026-08-31_PRD_rev1/). Its path never changes again. - docs/PRDs/2026-08-26_PRD_rev0/PRD.md archives the 2026-08-26 North Star verbatim (sha256 60cc2f98...36afdf unchanged). Archive, never delete. - docs/PRDs/2026-08-31_PRD_rev1/ is the frozen rev1 bundle: 18 sectioned documents (VIS, DATA, AUTHN, AUTHZ, SEAT, ROLE, HARN, PROV, SESS, UI, CLI, GOV.1-5) consolidating rev0 D1-D15, the fleet north star, the agent-runtime L1/L2 contracts and the control-plane-surfaces lane findings, with a single decision map (GOV.3) and a closed open-questions frontier (GOV.5, grill rounds 1-8). Drafting inputs (_source-* snapshots) are not shipped. Consequences of the ratified rulings carried in the same change: - Q-T1 (ruling B, "shipped but frozen"): D3 amended in GOV.3/VIS.1; federation M1-M3 acknowledged as shipped behind tier === 'federated', excluded from the v1 bar and frozen, with a security re-audit gate before any resumption. docs/MISSION-MANIFEST.md, docs/federation/MISSION-MANIFEST.md and docs/scratchpads/mvp-20260312.md get status: superseded + banners (content preserved verbatim); docs/guides/deployment.md gains a "Relationship to the PRD (D15)" section. NORTH_STAR.yaml adds dormant workstream M (projects no goals by design); NORTH_STAR.md regenerated. - Q-G2 (distinct registry prefixes): every citation of the operator DECISION-REGISTER in the bundle reads OD-nn; the stack registry stays D1-D15; L1-Dnn/L2-Dnn untouched. Prefix rule recorded in GOV.1. Follow-ups (not in this PR): CI parity drift-gate witness (Q-C1); brain-side DECISION-REGISTER rename to OD- with redirect table on its next touch.
85 lines
4.5 KiB
Markdown
85 lines
4.5 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.
|