Files

ci/woodpecker/push/ci Pipeline was successful

Details

docs(fleet): refine Mosaic Platform PRD per Jason's review (R1–R7)

Post-review refinements to the DRAFT PRD set (decisions D1–D12 unchanged):

- R1: PRD-permission-relay is now self-contained — its cited design source
  (guard-rails-capability-permissions.md) is absent from origin/main, so the
  essential model (prepare-freely/execute-with-approval, permission levels,
  resource:action grants) is folded in as the authoritative spec.
- R2: Phase-1 conversation channel is tmux/CLI via the f4 Phase-1 tmux
  connector (operator issues /remote-control); Matrix room (J5/K1) is Phase 2.
- R3: Jarvis is a Level-0 orchestrator (delegation + subagents, never executes
  coding/infra); AC-NS-8 latency isolation is a separate-model-capacity
  guarantee, not just a separate process (NS-10, AC-NS-8, ASM-5).
- R4: jarvis-brain reframed as the P0 (prototype) Mosaic Stack; tenant-1
  migration targets the proper stack storage layer (vector DB + enhanced
  memory + flat-file backends). Agent memory/runbooks migrate live into the
  memory subsystem and are NOT frozen; repo retires read-only only after both
  PA data and agent memory are verified migrated (X2/X-R7).
- R5: homelab→USC promotion is an explicit owner sign-off gate, not an
  automated metric (X deployment-scope).
- R6: verified K1 is covered by f4-matrix-connector.md Phase 2 (no new doc).
- R7: clarified always-available Opus ≠ standing cost (idle = no bill) (J-R2).
- Also normalized PRD-backlog-providers.md and PRD-webui-fleet-control.md with
  prettier (whitespace-only) — they were non-conformant as originally pushed
  and would have re-broken repo-wide format:check on merge.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMoEx7hfdFGjUiCHuN1RRi

2026-07-09 14:50:54 -05:00

5.3 KiB

Raw Blame History

PRD — Permission Relay · Workstream P

Status: DRAFT for ratification · Goals: P1–P3 Design origin (historical): docs/3-architecture/guard-rails-capability-permissions.md — the "prepare freely, execute with approval" snapshot. Not present on origin/main (survives only in the stale /src/mosaic-stack clone), so its essential model is folded into this PRD below; this document is the authoritative, self-contained spec for P. Replaces: Hermes permissions_list_open / permissions_respond relay (Hermes exit prerequisite, NS-13)

Mission

A human-in-the-loop approval mechanism for agent actions: any capability listed as requires_approval is prepared by the agent, queued, and executed only after an explicit human approve — from the Matrix room or the webUI. Today this exists only as a bare applyGuardRails() method; Hermes currently fills the gap and must be replaced before decommission.

Design model (folded in — the authoritative spec, since the origin snapshot is off-main)

Doctrine — "prepare freely, execute with approval": an agent may plan, draft, and stage any action without friction; only the committing step of a requires_approval capability blocks on a human decision.

Permission levels (least→most): read → organize → draft → execute → admin. A capability grant names a level; requires_approval gates the transition into execute/admin for the capabilities a workspace marks sensitive.

Grant shape: resource:action (e.g. email:send, git:push_main, dns:update), scoped per workspace and per agent-persona, stored as configuration (profile field) so a user tightens/loosens without a code change.

Requirements

Guard-rails engine (P1)

ID	Requirement
P-R1	Capabilities are `resource:action` grants (e.g. `email:send`, `git:push_main`, `dns:update`) with permission levels (read / organize / draft / execute / admin) per the existing design doc.
P-R2	Each integration declares its `requires_approval` list; grants are workspace-scoped and per-agent-persona.
P-R3	Enforcement sits in the gateway/API dispatch path — an agent cannot bypass it by construction; bypass attempts are audited and denied.
P-R4	Policy is configuration (profile field), honoring the configurability pillar: a user can tighten/loosen per capability without code change.

Approval queue + chat approvals (P2)

ID	Requirement
P-R5	A pending approval is a durable queue record: requesting agent, capability, human-readable intent summary, prepared payload reference, TTL.
P-R6	Approve/deny from the Matrix room (message action or reply verb); the requesting agent is notified of the outcome and proceeds/aborts.
P-R7	Timeout = deny (fail-closed). Deny and timeout leave the system unchanged.
P-R8	Full audit trail: who approved what, when, from which surface (AC-NS-10).
P-R9	The main agent (Jarvis) surfaces pending approvals conversationally (J-R13) but approval authority is the human's — Jarvis never auto-approves.

webUI surface (P3)

ID	Requirement
P-R10	Pending-approval queue view in `apps/web` with one-click approve/deny, filterable per workspace/agent (depends W3 dashboard shell).

Acceptance criteria

AC-NS-10 end-to-end: a requires_approval action executes only post-approve; deny/timeout paths verified unchanged + audited.
Approval round-trip from a phone Matrix client (Element) in under 3 taps.
With Hermes stopped, permission flow fully served by Mosaic (feeds AC-NS-11).

Non-goals

Automated quality gates (coordinator/CI approvals) — different system, already exists.
Fine-grained LLM output moderation — out of scope; this governs actions.

Assumptions

ASSUMPTION: the durable queue rides the native Postgres storage service (same substrate as the backlog), not a new datastore.
ASSUMPTION: routine delivery operations already hard-gated as no-confirmation (push/merge per Mosaic contract) are NOT routed through the relay — the relay is for requires_approval capabilities only, so it does not reintroduce routine confirmation prompts.

5.3 KiB Raw Blame History Unescape Escape