Files

ci/woodpecker/push/ci Pipeline failed

Details

docs(fleet): DRAFT PRD proposal — Jarvis HMI main agent, Matrix-first transport, webUI fleet control, permission relay, backlog providers, Hermes decommission

Ratification draft (Jason, 2026-07-09) extending NORTH_STAR.yaml with NS-10..NS-13
and workstreams J/K/W/P/Q/X. Written against origin/main's fleet suite (F4/F6
anchors, H2 profiles, native backlog per ASM-1). Homelab is the trial
environment (D12); USC/web1 adopts post-trial. See proposals/mosaic-platform-prd/README.md
for the full decision record D1-D12.

Not yet merged into NORTH_STAR.yaml — landing and card decomposition are the
homelab orchestrator's mission.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-09 14:19:05 -05:00

3.2 KiB

Raw Blame History

PRD — Permission Relay · Workstream P

Status: DRAFT for ratification · Goals: P1–P3 · Design source: docs/3-architecture/guard-rails-capability-permissions.md (old snapshot — "prepare freely, execute with approval") 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 design doc and a bare applyGuardRails() method; Hermes currently fills the gap and must be replaced before decommission.

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.

3.2 KiB Raw Blame History Unescape Escape