docs(fleet): refine Mosaic Platform PRD per Jason's review (R1–R7)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
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
This commit is contained in:
Jason Woltje
@@ -4,30 +4,30 @@
|
||||
|
||||
## Mission
|
||||
|
||||
Users choose where they *see and touch* work — Gitea, GitHub, a local kanban — while the **Mosaic Backlog on native Postgres stays the sole record and dispatch engine** (upholds ASM-1; NS-3/NS-4/NS-5 guarantees never depend on an external provider). Providers attach as bidirectional sync adapters.
|
||||
Users choose where they _see and touch_ work — Gitea, GitHub, a local kanban — while the **Mosaic Backlog on native Postgres stays the sole record and dispatch engine** (upholds ASM-1; NS-3/NS-4/NS-5 guarantees never depend on an external provider). Providers attach as bidirectional sync adapters.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Adapter interface + Gitea (Q1)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| Q-R1 | A `BacklogProviderAdapter` interface: map card ⇄ external item (create/update/close/comment/label), with stable external-id linkage stored on the card. |
|
||||
| ID | Requirement |
|
||||
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Q-R1 | A `BacklogProviderAdapter` interface: map card ⇄ external item (create/update/close/comment/label), with stable external-id linkage stored on the card. |
|
||||
| Q-R2 | Sync is bidirectional and conflict-safe: native record wins on divergence; external edits arrive as proposed mutations (applied if non-conflicting, else surfaced). |
|
||||
| Q-R3 | Claims, TTLs, depends_on DAG, and dispatch state live **only** in the native record; adapters project them (e.g. as labels/comments) but never own them. |
|
||||
| Q-R4 | Gitea adapter first (webhook + API), configured per workspace: repo mapping, label conventions, direction (mirror-out / mirror-in / full). |
|
||||
| Q-R5 | Adapter enable/disable is workspace configuration; zero adapters is a fully supported mode. |
|
||||
| Q-R3 | Claims, TTLs, depends_on DAG, and dispatch state live **only** in the native record; adapters project them (e.g. as labels/comments) but never own them. |
|
||||
| Q-R4 | Gitea adapter first (webhook + API), configured per workspace: repo mapping, label conventions, direction (mirror-out / mirror-in / full). |
|
||||
| Q-R5 | Adapter enable/disable is workspace configuration; zero adapters is a fully supported mode. |
|
||||
|
||||
### GitHub (Q2)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Q-R6 | Same interface, GitHub Issues backend. Existing `packages/cli-tools` platform detection informs but does not implement this (that is dev tooling, not product runtime). |
|
||||
|
||||
### Local kanban (Q3)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Q-R7 | A webUI kanban board over the native backlog (no external provider needed) — the "local kanban" choice. Builds on W3's card views and/or the existing `KanbanBoard` component upgraded from demo-grade to live data. |
|
||||
|
||||
## Acceptance criteria
|
||||
@@ -43,4 +43,4 @@ Users choose where they *see and touch* work — Gitea, GitHub, a local kanban
|
||||
|
||||
## Assumptions
|
||||
|
||||
- ASSUMPTION: the delivery fleet's *engineering* PR/issue flow on the stack repo itself continues to use `cli-tools`/Gitea directly — workstream Q is the product feature for user workspaces, not a replacement for the dev workflow.
|
||||
- ASSUMPTION: the delivery fleet's _engineering_ PR/issue flow on the stack repo itself continues to use `cli-tools`/Gitea directly — workstream Q is the product feature for user workspaces, not a replacement for the dev workflow.
|
||||
|
||||
@@ -7,45 +7,52 @@
|
||||
|
||||
The trial runs in the **homelab**. Hermes and the primitive-era stack (`mos-claude.service`, jarvis-brain boards) live in the **USC/web1 environment**, which is untouched during the trial. This workstream therefore lands in two stages: **X-in-homelab** (prove parity where the fleet is native — mainly K/P/Q verification plus tenant-1 migration) and **X-at-USC** (post-trial adoption: apply the parity checklist to web1, migrate Mos-on-web1 to `mosaic-agent@orchestrator`, then decommission Hermes there, with `/src/infrastructure` GitOps updates in the same delivery set).
|
||||
|
||||
**Trial go/no-go (D12/ASM-9 gate):** the homelab→USC promotion is **owner-judgment**, not an automated metric. The stage gate is: _Jason instantiates and operates the split-agent stack in the homelab and is satisfied with its operation._ Only on that explicit sign-off does X-at-USC begin. The capability ACs (AC-NS-8…11) are the evidence Jason weighs; they inform the decision but do not auto-trigger USC deployment.
|
||||
|
||||
## Mission
|
||||
|
||||
Retire Hermes entirely. Mosaic becomes the platform for transport (Matrix connector), task board (native backlog + webUI/adapters), approvals (permission relay), and multi-platform reach (mautrix bridges). In the same arc, Jason's jarvis-brain flat-file data migrates into the product as **tenant #1**, making the product's PA feature set the dogfooded default.
|
||||
|
||||
## Parity map (what replaces what)
|
||||
|
||||
| Hermes function | Mosaic replacement | Workstream |
|
||||
|---|---|---|
|
||||
| Messaging bridge (Discord/Telegram/…) | Matrix connector + mautrix bridges | K1, K2 |
|
||||
| Kanban / task board | Native Mosaic Backlog + webUI board + provider adapters | A*, Q, W3 |
|
||||
| Permission relay (`permissions_*`) | Guard-rails engine + approval queue (Matrix + webUI) | P1–P3 |
|
||||
| Cross-platform user reach | mautrix bridges (agents speak Matrix only) | K2 |
|
||||
| Hermes MCP tools in agent sessions | Mosaic-native equivalents (gateway API / MCP) | J2, Q1 |
|
||||
| Hermes function | Mosaic replacement | Workstream |
|
||||
| ------------------------------------- | ------------------------------------------------------- | ---------- |
|
||||
| Messaging bridge (Discord/Telegram/…) | Matrix connector + mautrix bridges | K1, K2 |
|
||||
| Kanban / task board | Native Mosaic Backlog + webUI board + provider adapters | A\*, Q, W3 |
|
||||
| Permission relay (`permissions_*`) | Guard-rails engine + approval queue (Matrix + webUI) | P1–P3 |
|
||||
| Cross-platform user reach | mautrix bridges (agents speak Matrix only) | K2 |
|
||||
| Hermes MCP tools in agent sessions | Mosaic-native equivalents (gateway API / MCP) | J2, Q1 |
|
||||
|
||||
## Requirements
|
||||
|
||||
### Parity checklist + cutover plan (X1)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| X-R1 | A written, testable parity checklist per row above; each item verified in production before its Hermes counterpart is disabled. |
|
||||
| X-R2 | Cutover is staged with rollback at every stage; Hermes runs untouched until AC-NS-11 is verified (ASM-8). |
|
||||
| X-R3 | The Matrix charter's live-cutover rules apply: stated window, announce before/after, rollback ready. |
|
||||
| X-R2 | Cutover is staged with rollback at every stage; Hermes runs untouched until AC-NS-11 is verified (ASM-8). |
|
||||
| X-R3 | The Matrix charter's live-cutover rules apply: stated window, announce before/after, rollback ready. |
|
||||
|
||||
### Tenant-1 migration (X2)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| X-R4 | One-shot migrator: `data/projects/*.json`, `data/tasks/*.json`, `data/events/*.json`, `data/tickets.json`, and knowledge-worthy docs → the Jason workspace (Project/Task/Event/KnowledgeEntry entities), preserving ids in metadata for traceability. |
|
||||
| X-R5 | Dry-run mode with a diffable report; Jason ratifies the report before the real run (canonical-data gate — this is the one migration step that is his call). |
|
||||
| X-R6 | External sync jobs (GLPI, Google Calendar, ICS, Gmail) are re-pointed to product integrations; each re-point verified before the flat-file sync job is retired. |
|
||||
| X-R7 | jarvis-brain repo is archived read-only after cutover (history preserved); generated views and brain.py retire. Agent meta-observation flow (OpenBrain/OpenViking) is unaffected — it was never Hermes. |
|
||||
**Framing (ratified 2026-07-09):** jarvis-brain **is the P0 (prototype) Mosaic Stack** — its flat-file data layer is the zeroth implementation of what the product does properly. Migration is therefore _P0 → proper Mosaic Stack_, whose storage layer is **pluggable: vector DB + enhanced memory service + flat-file storage backends**. Two distinct data classes migrate into that layer — they are not the same destination and neither is frozen:
|
||||
|
||||
- **(a) PA data** (projects, tasks, events, tickets, knowledge) → product entities in the Jason workspace (Project/Task/Event/KnowledgeEntry), on the relational + flat-file backends.
|
||||
- **(b) Agent memory & operational knowledge** (runbooks, digests, scratchpads, OpenBrain thoughts) → the proper stack's **enhanced memory subsystem (vector DB + memory service)**. This flow stays **live and writable** throughout — it was never Hermes and must not be frozen by the PA cutover.
|
||||
|
||||
| ID | Requirement |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| X-R4 | One-shot PA migrator: `data/projects/*.json`, `data/tasks/*.json`, `data/events/*.json`, `data/tickets.json`, and knowledge-worthy docs → the Jason workspace entities, preserving ids in metadata for traceability. |
|
||||
| X-R5 | Dry-run mode with a diffable report; Jason ratifies the report before the real run (canonical-data gate — this is the one migration step that is his call). |
|
||||
| X-R6 | External sync jobs (GLPI, Google Calendar, ICS, Gmail) are re-pointed to product integrations; each re-point verified before the flat-file sync job is retired. |
|
||||
| X-R7 | Agent memory/operational knowledge (b) is migrated into the proper stack's memory subsystem **before** any jarvis-brain retirement; the memory write path stays continuously available (no read-only freeze of an active substrate). Only once **both** (a) and (b) are migrated and verified is the jarvis-brain repo retired read-only (history preserved); generated views and brain.py retire. This closes the P0 prototype. |
|
||||
|
||||
### Decommission (X3)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| X-R8 | Hermes services stopped, disabled, and removed from infra (GitOps: `/src/infrastructure` updated in the same delivery set); credentials revoked; MCP registrations removed from agent runtimes. |
|
||||
| X-R9 | 30-day observation window between stop and removal; any regression flips back per X-R2 rollback. |
|
||||
| X-R9 | 30-day observation window between stop and removal; any regression flips back per X-R2 rollback. |
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
|
||||
@@ -7,56 +7,62 @@
|
||||
|
||||
Every Mosaic system gets exactly one always-on human-machine-interface agent — default alias **Jarvis**, unit `mosaic-agent@main.service` — that owns the human relationship: conversation, idea development, schedule, email, tasks, knowledge. It delegates all engineering/research/ops work to the orchestrator (**Mos**, `mosaic-agent@orchestrator.service`) through the Mosaic Backlog, and reports fleet status to the user without ever interrupting the orchestrator.
|
||||
|
||||
Jarvis is a **Level-0 orchestrator**: it accomplishes its own work through _delegation and subagents_, never by executing coding/infra tasks itself. PA mutations (tasks/events/knowledge) are direct API calls; everything heavier is either a spawned subagent (research, drafting, analysis) or a backlog card handed to Mos (engineering/infra/fleet). This keeps the main agent's context conversational and light.
|
||||
|
||||
This solves the observed failure mode: a busy orchestrator that can't respond, accumulates conversational context rot, and derails over time. Post-split, the orchestrator's context is execution-only.
|
||||
|
||||
Because Jarvis and Mos are **separate agents with separate model capacity** (D11: Jarvis on Opus, Mos on Fable; independent inference quota), orchestrator load cannot degrade conversational latency — the isolation in AC-NS-8 is a capacity guarantee, not merely a separate process.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Persona & runtime (J1)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| J-R1 | Jarvis is provisioned from the personal-assistant persona baseline via system-type profiles (H2/H3); alias, model tier, host, and channel are profile fields, not code. |
|
||||
| J-R2 | Default model tier **Opus** (ratified D11); the orchestrator's tier is independent. |
|
||||
| J-R3 | Jarvis survives reboot under systemd (`mosaic-agent@main`), participates in the fleet heartbeat protocol, and is counted in the supervisor's health floor. |
|
||||
| J-R4 | Persona customization is update-surviving per H4 (override layer wins on merge). |
|
||||
| ID | Requirement |
|
||||
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| J-R1 | Jarvis is provisioned from the personal-assistant persona baseline via system-type profiles (H2/H3); alias, model tier, host, and channel are profile fields, not code. |
|
||||
| J-R2 | Default model tier **Opus** (ratified D11); the orchestrator's tier is independent. Always-_available_ ≠ always-_billed_: Opus is provisioned 24/7 but cost is per-interaction — an idle Jarvis (no user turn in flight) incurs no model spend, so "always-on" carries no standing token bill. |
|
||||
| J-R3 | Jarvis survives reboot under systemd (`mosaic-agent@main`), participates in the fleet heartbeat protocol, and is counted in the supervisor's health floor. |
|
||||
| J-R4 | Persona customization is update-surviving per H4 (override layer wins on merge). |
|
||||
|
||||
### PA toolchain (J2)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| J-R5 | Jarvis executes personal-assistant mutations **directly** in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas, tickets. No delegation for PA ops (ratified D4). |
|
||||
| ID | Requirement |
|
||||
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| J-R5 | Jarvis executes personal-assistant mutations **directly** in the user's workspace via the product API: tasks, events/calendar, knowledge entries, ideas, tickets. No delegation for PA ops (ratified D4). |
|
||||
| J-R6 | External PA integrations (email, external calendars, helpdesk) are workspace-scoped integrations with credentials in the product credential vault; actions flagged `requires_approval` route through the permission relay (workstream P). |
|
||||
| J-R7 | Until tenant-1 migration (X2) completes, Jarvis may read/write the jarvis-brain flat files as a transitional adapter; the adapter is deleted at X2 cutover. |
|
||||
| J-R7 | Until tenant-1 migration (X2) completes, Jarvis may read/write the jarvis-brain flat files as a transitional adapter; the adapter is deleted at X2 cutover. |
|
||||
|
||||
### Delegation contract (J3)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| J-R8 | The Jarvis→Mos handoff is **only** via Mosaic Backlog cards: goal, acceptance criteria, priority, depends_on, advisory budget. Never via chat messages to the orchestrator. |
|
||||
| J-R9 | Jarvis translates conversation outcomes into card sets; ambiguity is resolved with the user *before* card creation — the orchestrator receives only decision-complete work. |
|
||||
| J-R10 | Card authorship is attributed (author=main-agent, ratified-by=user where applicable) for audit. |
|
||||
| ID | Requirement |
|
||||
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| J-R8 | The Jarvis→Mos handoff is **only** via Mosaic Backlog cards: goal, acceptance criteria, priority, depends_on, advisory budget. Never via chat messages to the orchestrator. |
|
||||
| J-R9 | Jarvis translates conversation outcomes into card sets; ambiguity is resolved with the user _before_ card creation — the orchestrator receives only decision-complete work. |
|
||||
| J-R10 | Card authorship is attributed (author=main-agent, ratified-by=user where applicable) for audit. |
|
||||
| J-R11 | Authority line: Mos holds all execution and merge authority (NS-4). Jarvis relays the user's GO/NO-GO gates as card state, and never acquires fleet mutation, merge, or dispatch rights. |
|
||||
|
||||
### Passive observability (J4)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| J-R12 | Jarvis answers "what's the fleet doing" from read-only sources: heartbeat files, `mosaic fleet ps` JSON, backlog card states, CI status. Zero messages to the orchestrator for status. |
|
||||
| J-R13 | Jarvis proactively surfaces to the user: blocked cards, failed CI on user-ratified missions, approval requests pending, budget advisories. (PDA-friendly phrasing per SOUL.md.) |
|
||||
| J-R13 | Jarvis proactively surfaces to the user: blocked cards, failed CI on user-ratified missions, approval requests pending, budget advisories. (PDA-friendly phrasing per SOUL.md.) |
|
||||
|
||||
### Channel (J5)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| J-R14 | Jarvis's conversation lives in a dedicated Matrix room on the self-hosted homeserver via `OrchestratorConnector(matrix)` (K1). Matrix-first: no Discord channel is created for Jarvis (ratified D1). |
|
||||
| J-R15 | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only. |
|
||||
| ID | Requirement |
|
||||
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| J-R14 | **Phase 2 (target channel):** Jarvis's conversation lives in a dedicated Matrix room on the self-hosted homeserver via `OrchestratorConnector(matrix)` (K1 = f4 Phase 2). Matrix-first: no Discord channel is created for Jarvis (ratified D1). |
|
||||
| J-R14a | **Phase 1 (interim channel, ratified):** Jarvis runs on the **tmux/CLI connector** — the f4 Phase-1 default connector. The operator launches the `mosaic-agent@main` tmux session and issues `/remote-control` to grant interactive access; this is the day-one conversation surface. No Discord, no Matrix dependency in Phase 1 (keeps D1 intact and unblocks J1–J4 before K1 lands). |
|
||||
| J-R15 | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only (from Phase 2 onward). |
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
1. AC-NS-8: user converses with Jarvis under full orchestrator load; latency unaffected; orchestrator receives zero conversational traffic.
|
||||
2. AC-NS-9: a conversationally-agreed mission round-trips (cards → drained → completed → reported by Jarvis) with no chat handoff.
|
||||
3. Kill the orchestrator mid-conversation: Jarvis conversation is unaffected; Jarvis reports the outage from heartbeat state.
|
||||
4. `!sys`-equivalent admin verbs work in the Matrix room (status/logs/clear/restart of the main agent).
|
||||
3. Kill the orchestrator mid-conversation: Jarvis conversation is unaffected; Jarvis reports the outage from heartbeat state. (Directly exercises the separate-capacity guarantee.)
|
||||
4. `!sys`-equivalent admin verbs work in Jarvis's active channel — the tmux/CLI session in Phase 1, the Matrix room in Phase 2 (status/logs/clear/restart of the main agent).
|
||||
5. **Phase-1 channel:** operator launches the `mosaic-agent@main` tmux session, issues `/remote-control`, and holds a full conversation with Jarvis over CLI with no Matrix/Discord dependency.
|
||||
|
||||
## Non-goals
|
||||
|
||||
@@ -67,4 +73,4 @@ This solves the observed failure mode: a busy orchestrator that can't respond, a
|
||||
## Open items (for Mos's planner)
|
||||
|
||||
- Context hygiene: Jarvis's durable memory is the workspace (tasks/knowledge/ideas); define its resume protocol (KICKSTART-equivalent) so `/clear` is cheap. ASSUMPTION: mirror the MOS-KICKSTART two-file pattern until the product grows a native session-resume feature.
|
||||
- Reconcile the old `apps/api` matrix-bot-sdk workspace bridge with the F4 connector design (one Matrix stack, not two).
|
||||
- Reconcile the old `apps/api` matrix-bot-sdk workspace bridge with the F4 connector design (one Matrix stack, not two). NOTE (verified 2026-07-09): no matrix dependency remains in `apps/api` on `origin/main` — this item is likely already moot; confirm before K1 build.
|
||||
|
||||
@@ -1,37 +1,46 @@
|
||||
# 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")
|
||||
> **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 design doc and a bare `applyGuardRails()` method; Hermes currently fills the gap and must be replaced before decommission.
|
||||
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 |
|
||||
|---|---|
|
||||
| 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. |
|
||||
| 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). |
|
||||
| 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 |
|
||||
|---|---|
|
||||
| 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
|
||||
@@ -43,7 +52,7 @@ A human-in-the-loop approval mechanism for agent actions: any capability listed
|
||||
## Non-goals
|
||||
|
||||
- Automated quality gates (coordinator/CI approvals) — different system, already exists.
|
||||
- Fine-grained LLM output moderation — out of scope; this governs *actions*.
|
||||
- Fine-grained LLM output moderation — out of scope; this governs _actions_.
|
||||
|
||||
## Assumptions
|
||||
|
||||
|
||||
@@ -11,28 +11,28 @@ The user can pop in on **any** agentic tmux session from the web, and get a full
|
||||
|
||||
### Attach service (W1)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| W-R1 | A gateway service exposes per-agent session streams over WebSocket: **watch** (read-only pane view, cannot type) and **butt-in** (interactive takeover), mirroring the existing CLI verbs `mosaic agent watch/attach`. |
|
||||
| W-R2 | Authz is workspace-scoped through the product auth stack (BetterAuth/Authentik); watch and butt-in are separate grants; butt-in may be `requires_approval` per workspace policy (workstream P). |
|
||||
| W-R3 | Every attach (watch or butt-in) is audited: who, which agent, when, duration. |
|
||||
| W-R4 | Butt-in visibly flags the session to the agent runtime and other viewers (no silent takeover). |
|
||||
| W-R5 | Contract is stable JSON + streaming frames per F6's "stable JSON contract" requirement, so TUI/CLI and webUI share it. |
|
||||
| W-R2 | Authz is workspace-scoped through the product auth stack (BetterAuth/Authentik); watch and butt-in are separate grants; butt-in may be `requires_approval` per workspace policy (workstream P). |
|
||||
| W-R3 | Every attach (watch or butt-in) is audited: who, which agent, when, duration. |
|
||||
| W-R4 | Butt-in visibly flags the session to the agent runtime and other viewers (no silent takeover). |
|
||||
| W-R5 | Contract is stable JSON + streaming frames per F6's "stable JSON contract" requirement, so TUI/CLI and webUI share it. |
|
||||
|
||||
### Web terminal (W2)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| ID | Requirement |
|
||||
| ---- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| W-R6 | xterm.js view in `apps/web` wired to W1: session list → click → live pane; toggle watch↔butt-in per grants. |
|
||||
| W-R7 | Reconnect-safe (network blips resume the stream), mobile-usable read-only view. |
|
||||
| W-R7 | Reconnect-safe (network blips resume the stream), mobile-usable read-only view. |
|
||||
|
||||
### Top-down dashboard (W3)
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| W-R8 | Fleet dashboard: roster with per-agent state (systemd + tmux + heartbeat join, as `fleet ps` provides), current card/task, last activity, drift/boot-enable warnings. |
|
||||
| W-R9 | Work-in-flight view: backlog cards by state with depends_on DAG rendering; advisory spend per card (NS-2/NS-5). |
|
||||
| W-R10 | Operator controls: PAUSE kill-switch (NS-8), per-agent terminate (killswitch service), queue pause/resume — each gated + audited; destructive controls confirm. |
|
||||
| ID | Requirement |
|
||||
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| W-R8 | Fleet dashboard: roster with per-agent state (systemd + tmux + heartbeat join, as `fleet ps` provides), current card/task, last activity, drift/boot-enable warnings. |
|
||||
| W-R9 | Work-in-flight view: backlog cards by state with depends_on DAG rendering; advisory spend per card (NS-2/NS-5). |
|
||||
| W-R10 | Operator controls: PAUSE kill-switch (NS-8), per-agent terminate (killswitch service), queue pause/resume — each gated + audited; destructive controls confirm. |
|
||||
| W-R11 | Existing widget framework (`AgentStatusWidget`, `OrchestratorEventsWidget`, SSE proxy routes) is the starting point, upgraded to the fleet contract rather than rebuilt. |
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
@@ -1,42 +1,44 @@
|
||||
# Mosaic Platform PRD — Jarvis HMI + Hermes Decommission (DRAFT for ratification)
|
||||
|
||||
**Date:** 2026-07-09 · **Author:** proto-Jarvis session with Jason · **Status:** DRAFT — awaiting Jason ratification
|
||||
**Date:** 2026-07-09 · **Author:** proto-Jarvis session with Jason · **Status:** Decisions D1–D12 **ratified** (fixed inputs); implementing PRD structure **DRAFT** — refined 2026-07-09 post-review
|
||||
**Target home:** `mosaicstack/stack` → `docs/fleet/` (NORTH_STAR.yaml additions + per-phase PRDs)
|
||||
**Execution:** hand to the **homelab orchestrator** as orchestrated missions once ratified (D12). Land in `docs/fleet/` from `origin/main` — the `/src/mosaic-stack` clone on web1 is 5 months stale and must not be the base. The USC/web1 environment is out of scope for the trial; its cutover (workstream X applied to web1's Hermes + mos-claude) is a post-trial phase.
|
||||
|
||||
> **For the homelab orchestrator:** D1–D12 below are settled constraints, not open questions — do not reopen them. What is under review is only the _implementation_ (workstreams, goals, sequencing) that realizes them.
|
||||
> **Execution:** hand to the **homelab orchestrator** as orchestrated missions once ratified (D12). Land in `docs/fleet/` from `origin/main` — the `/src/mosaic-stack` clone on web1 is 5 months stale and must not be the base. The USC/web1 environment is out of scope for the trial; its cutover (workstream X applied to web1's Hermes + mos-claude) is a post-trial phase.
|
||||
|
||||
## Ratified decisions (Jason, 2026-07-09)
|
||||
|
||||
| # | Decision |
|
||||
|---|---|
|
||||
| D1 | Jarvis conversation channel is **Matrix-first** — no #jarvis Discord channel is ever created. |
|
||||
| D2 | Mosaic absorbs **all four** Hermes functions before decommission: messaging bridge, Kanban/task board, permission relay, multi-platform reach. |
|
||||
| D3 | Task handoff: **native Mosaic Backlog is the record; Gitea/GitHub/local-kanban attach as bidirectional sync adapters** (upholds ASM-1). |
|
||||
| D4 | Jarvis executes **PA ops directly** (email, calendar, tasks, knowledge, tickets, research); all code/infra/fleet work is delegated to Mos via the backlog. |
|
||||
| D5 | Mosaic Stack is a **product from day one** — multi-user, Authentik tenancy, per-workspace isolation. |
|
||||
| D6 | Multi-platform reach via **Matrix + mautrix bridges** (telegram/signal/whatsapp/slack/discord); agents only ever speak Matrix. |
|
||||
| D7 | webUI builds on the existing `mosaicstack/stack` monorepo (`apps/web`), realizing the already-scoped F6 phase. |
|
||||
| D8 | **PRD first, then Mos runs it** as orchestrated missions. |
|
||||
| D9 | jarvis-brain flat-file data **migrates into the product as tenant #1** (workspace = Jason); brain.py/flat files retire after cutover. |
|
||||
| D10 | PRD form: **extend NORTH_STAR.yaml + per-phase docs in docs/fleet/** (NS-1 compliant). |
|
||||
| D11 | Jarvis runs **Opus**; Fable stays exclusive to Mos per the standing cost directive. Model tier is a persona/profile field. |
|
||||
| # | Decision |
|
||||
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| D1 | Jarvis conversation channel is **Matrix-first** — no #jarvis Discord channel is ever created. |
|
||||
| D2 | Mosaic absorbs **all four** Hermes functions before decommission: messaging bridge, Kanban/task board, permission relay, multi-platform reach. |
|
||||
| D3 | Task handoff: **native Mosaic Backlog is the record; Gitea/GitHub/local-kanban attach as bidirectional sync adapters** (upholds ASM-1). |
|
||||
| D4 | Jarvis executes **PA ops directly** (email, calendar, tasks, knowledge, tickets, research); all code/infra/fleet work is delegated to Mos via the backlog. |
|
||||
| D5 | Mosaic Stack is a **product from day one** — multi-user, Authentik tenancy, per-workspace isolation. |
|
||||
| D6 | Multi-platform reach via **Matrix + mautrix bridges** (telegram/signal/whatsapp/slack/discord); agents only ever speak Matrix. |
|
||||
| D7 | webUI builds on the existing `mosaicstack/stack` monorepo (`apps/web`), realizing the already-scoped F6 phase. |
|
||||
| D8 | **PRD first, then Mos runs it** as orchestrated missions. |
|
||||
| D9 | jarvis-brain flat-file data **migrates into the product as tenant #1** (workspace = Jason); brain.py/flat files retire after cutover. |
|
||||
| D10 | PRD form: **extend NORTH_STAR.yaml + per-phase docs in docs/fleet/** (NS-1 compliant). |
|
||||
| D11 | Jarvis runs **Opus**; Fable stays exclusive to Mos per the standing cost directive. Model tier is a persona/profile field. |
|
||||
| D12 | **Trial in the homelab** (the proper mosaic-fleet deployment, built by the homelab agents from `origin/main`), NOT at USC. The USC/web1 environment runs the primitive-era implementation (`mos-claude.service`, Hermes, jarvis-brain boards) and adopts only after the homelab trial validates. Jason relays this PRD to the homelab agent for implementation. |
|
||||
|
||||
## Artifacts in this draft
|
||||
|
||||
| File | Content |
|
||||
|---|---|
|
||||
| `north-star-additions.yaml` | Proposed NORTH_STAR.yaml merge: NS-10…NS-13, workstreams J/K/W/P/Q/X, goal cards with DAG |
|
||||
| `PRD-jarvis-main-agent.md` | Workstream J — the HMI main agent |
|
||||
| `PRD-permission-relay.md` | Workstream P — human-in-the-loop approvals |
|
||||
| `PRD-webui-fleet-control.md` | Workstream W — tmux pop-in + top-down view (realizes F6) |
|
||||
| `PRD-backlog-providers.md` | Workstream Q — provider sync adapters |
|
||||
| `PRD-hermes-decommission.md` | Workstream X — parity checklist, tenant-1 migration, cutover |
|
||||
| File | Content |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `north-star-additions.yaml` | Proposed NORTH_STAR.yaml merge: NS-10…NS-13, workstreams J/K/W/P/Q/X, goal cards with DAG |
|
||||
| `PRD-jarvis-main-agent.md` | Workstream J — the HMI main agent |
|
||||
| `PRD-permission-relay.md` | Workstream P — human-in-the-loop approvals |
|
||||
| `PRD-webui-fleet-control.md` | Workstream W — tmux pop-in + top-down view (realizes F6) |
|
||||
| `PRD-backlog-providers.md` | Workstream Q — provider sync adapters |
|
||||
| `PRD-hermes-decommission.md` | Workstream X — parity checklist, tenant-1 migration, cutover |
|
||||
|
||||
Workstream K (Matrix connector + mautrix bridges) intentionally has no new PRD doc: it extends the existing `docs/fleet/f4-matrix-connector.md`; its deltas are captured as K-goals in the YAML additions and referenced from the J/P/X PRDs.
|
||||
|
||||
## Relationship to existing upstream work
|
||||
|
||||
- Fleet CLI, persona library, system-type profiles (H1–H4), supervisor/dispatch (B), native backlog (A): **already exist or in flight upstream — not re-specified here.**
|
||||
- `f4-matrix-connector.md`: K1 = its Phase 2 implementation; K2 (mautrix bridges) is additive infra.
|
||||
- F6 (webUI hooks) in `PRD-fleet-suite.md`: realized by workstream W.
|
||||
- `docs/3-architecture/guard-rails-capability-permissions.md` (old snapshot): design source for workstream P.
|
||||
- `f4-matrix-connector.md`: K1 = its Phase 2 implementation (verified present on `origin/main`; Phase 1 already ships the **tmux-default connector** that serves the P1 CLI channel per J-R14a). K2 (mautrix bridges) is additive infra.
|
||||
- F6 (webUI hooks) in `PRD-fleet-suite.md`: realized by workstream W (verified present on `origin/main`).
|
||||
- `docs/3-architecture/guard-rails-capability-permissions.md`: original design snapshot for workstream P — **not present on `origin/main`** (lives only in the stale `/src/mosaic-stack` clone). Its essential model is therefore folded into `PRD-permission-relay.md`, which is now the **self-contained authoritative spec** for P; the old path is cited as historical origin only.
|
||||
|
||||
@@ -11,8 +11,12 @@ standing_objectives:
|
||||
alias "Jarvis", unit mosaic-agent@main) that owns all human conversation
|
||||
and user-level personal-assistant work (ideas, schedule, email, tasks,
|
||||
knowledge) and delegates engineering/research/ops missions to the
|
||||
orchestrator as Mosaic Backlog cards; the main agent never executes fleet
|
||||
work itself and never interrupts the orchestrator for status.
|
||||
orchestrator as Mosaic Backlog cards. It is a Level-0 orchestrator:
|
||||
it accomplishes work through delegation and subagents, never by executing
|
||||
coding/infra tasks itself, and it runs on model capacity separate from the
|
||||
orchestrator so its conversational latency is isolated from fleet load. The
|
||||
main agent never executes fleet work itself and never interrupts the
|
||||
orchestrator for status.
|
||||
- id: NS-11
|
||||
text: >-
|
||||
Irreversible or externally-visible agent actions pass a human-in-the-loop
|
||||
@@ -32,9 +36,10 @@ standing_objectives:
|
||||
success_criteria:
|
||||
- id: AC-NS-8
|
||||
text: >-
|
||||
A user converses with the main agent in its Matrix room while the
|
||||
orchestrator is under full load; main-agent response latency is unaffected
|
||||
and the orchestrator receives zero conversational traffic.
|
||||
A user converses with the main agent in its channel while the
|
||||
orchestrator is under full load; because the main agent runs on separate
|
||||
model capacity, its response latency is unaffected and the orchestrator
|
||||
receives zero conversational traffic.
|
||||
- id: AC-NS-9
|
||||
text: >-
|
||||
A mission agreed in the main-agent conversation appears as a backlog card
|
||||
@@ -162,8 +167,10 @@ goals:
|
||||
phase: 3
|
||||
priority: must-have
|
||||
depends_on: [K1, P2, Q1]
|
||||
# jarvis-brain is the P0 (prototype) Mosaic Stack; migration targets the proper
|
||||
# stack storage layer (vector DB + enhanced memory + flat-file backends).
|
||||
- id: X2
|
||||
title: Tenant-1 migration — jarvis-brain flat files (projects, tasks, events, tickets, knowledge) into the Jason workspace; brain.py retires
|
||||
title: 'Tenant-1 migration — P0 (jarvis-brain) into the proper Mosaic Stack: (a) PA data (projects/tasks/events/tickets/knowledge) into the Jason workspace, (b) agent memory/runbooks into the enhanced memory subsystem (kept live, not frozen); jarvis-brain retires read-only only after both are verified'
|
||||
phase: 3
|
||||
priority: must-have
|
||||
depends_on: [J2]
|
||||
@@ -179,7 +186,9 @@ assumptions:
|
||||
text: >-
|
||||
The main agent initially runs on the homelab fleet host alongside the
|
||||
orchestrator under mosaic-agent@main.service; host placement is a config
|
||||
field, not a code assumption.
|
||||
field, not a code assumption. Host co-location does NOT imply shared
|
||||
inference: Jarvis (Opus) and Mos (Fable) hold separate model capacity/quota
|
||||
so orchestrator load cannot degrade conversational latency (AC-NS-8).
|
||||
- id: ASM-6
|
||||
vetoable: true
|
||||
text: >-
|
||||
|
||||
Reference in New Issue
Block a user