Files

T

ci/woodpecker/pr/ci Pipeline failed

Details

docs: ratify PRD rev1 — consolidated bundle, permanent shim, rev0 archived

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.

2026-09-01 18:32:14 -05:00

4.5 KiB

Raw Blame History

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 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.

4.5 KiB Raw Blame History Unescape Escape