mosaicstack/stack
1
0
Fork 0
Code Issues 48 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

docs(fleet): refine Mosaic Platform PRD per Jason's review (R1–R7)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source 
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
2026-07-09 14:50:54 -05:00
parent d1f69bfd37
commit 6b8c3c5d3a
7 changed files with 153 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/fleet/proposals/mosaic-platform-prd/PRD-backlog-providers.md
View File

@@ -4,30 +4,30 @@
## Mission ## 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 ## Requirements
### Adapter interface + Gitea (Q1) ### Adapter interface + Gitea (Q1)
| ID | Requirement | | 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-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-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-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-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-R5 | Adapter enable/disable is workspace configuration; zero adapters is a fully supported mode. |
### GitHub (Q2) ### 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). | | 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) ### 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. | | 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 ## Acceptance criteria
@@ -43,4 +43,4 @@ Users choose where they *see and touch* work — Gitea, GitHub, a local kanban
## Assumptions ## 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.

47
docs/fleet/proposals/mosaic-platform-prd/PRD-hermes-decommission.md
View File

@@ -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). 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 ## 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. 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) ## Parity map (what replaces what)
| Hermes function | Mosaic replacement | Workstream | | Hermes function | Mosaic replacement | Workstream |
|---|---|---| | ------------------------------------- | ------------------------------------------------------- | ---------- |
| Messaging bridge (Discord/Telegram/…) | Matrix connector + mautrix bridges | K1, K2 | | Messaging bridge (Discord/Telegram/…) | Matrix connector + mautrix bridges | K1, K2 |
| Kanban / task board | Native Mosaic Backlog + webUI board + provider adapters | A*, Q, W3 | | 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 | | Permission relay (`permissions_*`) | Guard-rails engine + approval queue (Matrix + webUI) | P1–P3 |
| Cross-platform user reach | mautrix bridges (agents speak Matrix only) | K2 | | 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 MCP tools in agent sessions | Mosaic-native equivalents (gateway API / MCP) | J2, Q1 |
## Requirements ## Requirements
### Parity checklist + cutover plan (X1) ### 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-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-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-R3 | The Matrix charter's live-cutover rules apply: stated window, announce before/after, rollback ready. |
### Tenant-1 migration (X2) ### Tenant-1 migration (X2)
| ID | Requirement | **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:
|---|---|
| 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. | - **(a) PA data** (projects, tasks, events, tickets, knowledge) → product entities in the Jason workspace (Project/Task/Event/KnowledgeEntry), on the relational + flat-file backends.
| 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). | - **(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.
| 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. | | 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) ### 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-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 ## Acceptance criteria

56
docs/fleet/proposals/mosaic-platform-prd/PRD-jarvis-main-agent.md
View File

@@ -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. 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. 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 ## Requirements
### Persona & runtime (J1) ### Persona & runtime (J1)
| ID | Requirement | | 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-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-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-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). | | J-R4 | Persona customization is update-surviving per H4 (override layer wins on merge). |
### PA toolchain (J2) ### PA toolchain (J2)
| ID | Requirement | | 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-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-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) ### Delegation contract (J3)
| ID | Requirement | | 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-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-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-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. | | 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) ### 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-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) ### Channel (J5)
| ID | Requirement | | 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-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-R15 | Multi-platform user reach arrives via mautrix bridges (K2); Jarvis's code path is Matrix-only. | | 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 ## Acceptance criteria
1. AC-NS-8: user converses with Jarvis under full orchestrator load; latency unaffected; orchestrator receives zero conversational traffic. 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. 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. 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 the Matrix room (status/logs/clear/restart of the main agent). 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 ## 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) ## 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. - 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.

41
docs/fleet/proposals/mosaic-platform-prd/PRD-permission-relay.md
View File

@@ -1,37 +1,46 @@
# PRD — Permission Relay · Workstream P # 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) > **Replaces:** Hermes `permissions_list_open` / `permissions_respond` relay (Hermes exit prerequisite, NS-13)
## Mission ## 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 ## Requirements
### Guard-rails engine (P1) ### 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-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-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-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-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) ### Approval queue + chat approvals (P2)
| ID | Requirement | | ID | Requirement |
|---|---| | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| P-R5 | A pending approval is a durable queue record: requesting agent, capability, human-readable intent summary, prepared payload reference, TTL. | | 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-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-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-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. | | 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) ### 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). | | P-R10 | Pending-approval queue view in `apps/web` with one-click approve/deny, filterable per workspace/agent (depends W3 dashboard shell). |
## Acceptance criteria ## Acceptance criteria
@@ -43,7 +52,7 @@ A human-in-the-loop approval mechanism for agent actions: any capability listed
## Non-goals ## Non-goals
- Automated quality gates (coordinator/CI approvals) — different system, already exists. - 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 ## Assumptions

28
docs/fleet/proposals/mosaic-platform-prd/PRD-webui-fleet-control.md
View File

@@ -11,28 +11,28 @@ The user can pop in on **any** agentic tmux session from the web, and get a full
### Attach service (W1) ### 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-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-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-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-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-R5 | Contract is stable JSON + streaming frames per F6's "stable JSON contract" requirement, so TUI/CLI and webUI share it. |
### Web terminal (W2) ### 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-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) ### Top-down dashboard (W3)
| ID | Requirement | | 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-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-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-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. | | W-R11 | Existing widget framework (`AgentStatusWidget`, `OrchestratorEventsWidget`, SSE proxy routes) is the starting point, upgraded to the fleet contract rather than rebuilt. |
## Acceptance criteria ## Acceptance criteria

54
docs/fleet/proposals/mosaic-platform-prd/README.md
View File

@@ -1,42 +1,44 @@
# Mosaic Platform PRD — Jarvis HMI + Hermes Decommission (DRAFT for ratification) # 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) **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) ## Ratified decisions (Jason, 2026-07-09)
| # | Decision | | # | Decision |
|---|---| | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| D1 | Jarvis conversation channel is **Matrix-first** — no #jarvis Discord channel is ever created. | | 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. | | 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). | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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). | | 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. | | 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. | | 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 ## Artifacts in this draft
| File | Content | | 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 | | `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-jarvis-main-agent.md` | Workstream J — the HMI main agent |
| `PRD-permission-relay.md` | Workstream P — human-in-the-loop approvals | | `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-webui-fleet-control.md` | Workstream W — tmux pop-in + top-down view (realizes F6) |
| `PRD-backlog-providers.md` | Workstream Q — provider sync adapters | | `PRD-backlog-providers.md` | Workstream Q — provider sync adapters |
| `PRD-hermes-decommission.md` | Workstream X — parity checklist, tenant-1 migration, cutover | | `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. 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 ## 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.** - 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. - `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. - 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` (old snapshot): design source for workstream P. - `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.

23
docs/fleet/proposals/mosaic-platform-prd/north-star-additions.yaml
View File

@@ -11,8 +11,12 @@ standing_objectives:
alias "Jarvis", unit mosaic-agent@main) that owns all human conversation alias "Jarvis", unit mosaic-agent@main) that owns all human conversation
and user-level personal-assistant work (ideas, schedule, email, tasks, and user-level personal-assistant work (ideas, schedule, email, tasks,
knowledge) and delegates engineering/research/ops missions to the knowledge) and delegates engineering/research/ops missions to the
orchestrator as Mosaic Backlog cards; the main agent never executes fleet orchestrator as Mosaic Backlog cards. It is a Level-0 orchestrator:
work itself and never interrupts the orchestrator for status. 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 - id: NS-11
text: >- text: >-
Irreversible or externally-visible agent actions pass a human-in-the-loop Irreversible or externally-visible agent actions pass a human-in-the-loop
@@ -32,9 +36,10 @@ standing_objectives:
success_criteria: success_criteria:
- id: AC-NS-8 - id: AC-NS-8
text: >- text: >-
A user converses with the main agent in its Matrix room while the A user converses with the main agent in its channel while the
orchestrator is under full load; main-agent response latency is unaffected orchestrator is under full load; because the main agent runs on separate
and the orchestrator receives zero conversational traffic. model capacity, its response latency is unaffected and the orchestrator
receives zero conversational traffic.
- id: AC-NS-9 - id: AC-NS-9
text: >- text: >-
A mission agreed in the main-agent conversation appears as a backlog card A mission agreed in the main-agent conversation appears as a backlog card
@@ -162,8 +167,10 @@ goals:
phase: 3 phase: 3
priority: must-have priority: must-have
depends_on: [K1, P2, Q1] 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 - 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 phase: 3
priority: must-have priority: must-have
depends_on: [J2] depends_on: [J2]
@@ -179,7 +186,9 @@ assumptions:
text: >- text: >-
The main agent initially runs on the homelab fleet host alongside the The main agent initially runs on the homelab fleet host alongside the
orchestrator under mosaic-agent@main.service; host placement is a config 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 - id: ASM-6
vetoable: true vetoable: true
text: >- text: >-