diff --git a/docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md b/docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md index 190bcea..becc818 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md +++ b/docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md @@ -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. diff --git a/docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md b/docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md index a71190f..4e86549 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md +++ b/docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md @@ -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 diff --git a/docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md b/docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md index 9592cf9..a354238 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md +++ b/docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md @@ -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. diff --git a/docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md b/docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md index a7fa89c..625783c 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md +++ b/docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md @@ -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 diff --git a/docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md b/docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md index c20dc41..ec870d1 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md +++ b/docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md @@ -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 diff --git a/docs/fleet/proposals/mosaic-platform-prd/README.md b/docs/fleet/proposals/mosaic-platform-prd/README.md index bd88e07..67953b5 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/README.md +++ b/docs/fleet/proposals/mosaic-platform-prd/README.md @@ -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. diff --git a/docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml b/docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml index 1745d20..2d33f39 100644 --- a/docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml +++ b/docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml @@ -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: >-