stack/docs/fleet/proposals/mosaic-platform-prd/README.md

Mosaic Platform PRD — Jarvis HMI + Hermes Decommission (DRAFT for 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, then stress-tested by a 9-persona × 2-round debate panel the same day; all 24 panel findings dispositioned and folded (see DEBATE-FINDINGS.md; one item OPEN — Jason: gate superstructure, §3.1) Target home: mosaicstack/stack → docs/fleet/ (NORTH_STAR.yaml additions + per-phase PRDs)

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.
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-14, workstreams J/K/W/P/Q/X + M (memory subsystem) + L (logging/telemetry), 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
DEBATE-FINDINGS.md	2026-07-09 debate pass — all 24 findings dispositioned, open-disagreement judgment calls, process rules

Workstreams M (M1 enhanced memory subsystem) and L (L1 restore MALS · L2 Mosaic-native log ingestion · L3 anonymous agentic telemetry, NS-14) carry no standalone PRD doc: M1's scope is defined by its consumers (X-R7 retrieval eval, J memory rules) and L's by the MALS lineage (~/src/mals, infrastructure #135); both live as goal cards in the YAML.

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 (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.

Gate Zero — pre-ratification checklist (debate P0 #3/#4, §3.7)

Ratification does not proceed on presumption. Before D-level sign-off, run and record:

1. Upstream-artifact audit. Every artifact this PRD load-bears on is verified present @ <SHA> on origin/main or marked MISSING → goal card. Presumed-missing rows already carded by this draft: M1 (enhanced memory subsystem — nothing on main provides vector DB + memory service today), J6 (event/wake router), K3 (Matrix push pipeline + homeserver ops). If an audit finds one of these actually exists, retire the card and pin the SHA; if it finds another gap, card it — no silent presumption in either direction.
2. Hermes traffic audit (§3.7): per-platform bridge traffic + per-MCP-tool call counts over a trailing window. Platforms with live traffic become the must-have K2 subset gating X3; zero-traffic platforms become post-trial nice-to-haves. Feeds the X-R1 parity checklist and its low-n drill list.
3. Sandbox dispatch-test of the DAG: load north-star-additions.yaml into a sandbox backlog and verify the dispatcher's actual claim order respects every depends_on edge (phases are documentation; edges are law).

Process rules adopted from the debate pass (normative for this PRD's execution)

• Conflict register: a discovered contradiction between spec documents blocks the affected requirement (not the whole mission) until a register entry records the resolution. "Alert, don't auto-resolve" is promoted from data conflicts to spec conflicts. A CI lint greps for register references in amended docs.
• DoD line on every goal card: each card states its definition-of-done additions — runbook updated, health-floor alert registered, AGENTS.md touched — so operational debt can't silently accrue card-by-card.
• Silent-roster rule: in any panel/review round, a member's silence records their open findings as open items, never consensus (instance: Codex's unanswered principal-resolution and policy-evaluation-time findings were folded as P-R16/P-R17, explicitly not consensus-resolved).
• Immutable spec + typed amendments (J-R20) applies to these PRD docs themselves post-ratification: changes arrive as amendments with a revision counter, and sign-offs pin the revision.