6b8c3c5d3a
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
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
61 lines
5.3 KiB
Markdown
61 lines
5.3 KiB
Markdown
# 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
|
||
|
||
1. AC-NS-10 end-to-end: a `requires_approval` action executes only post-approve; deny/timeout paths verified unchanged + audited.
|
||
2. Approval round-trip from a phone Matrix client (Element) in under 3 taps.
|
||
3. 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.
|