docs(fleet): DRAFT PRD proposal — Jarvis HMI main agent, Matrix-first transport, webUI fleet control, permission relay, backlog providers, Hermes decommission

Ratification draft (Jason, 2026-07-09) extending NORTH_STAR.yaml with NS-10..NS-13
and workstreams J/K/W/P/Q/X. Written against origin/main's fleet suite (F4/F6
anchors, H2 profiles, native backlog per ASM-1). Homelab is the trial
environment (D12); USC/web1 adopts post-trial. See proposals/mosaic-platform-prd/README.md
for the full decision record D1-D12.

Not yet merged into NORTH_STAR.yaml — landing and card decomposition are the
homelab orchestrator's mission.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

@@ -0,0 +1,46 @@
+# PRD — Backlog Provider Sync Adapters · Workstream Q
+
+> **Status:** DRAFT for ratification · **Goals:** Q1–Q3 · **Doctrine:** NS-12 (ratified D3)
+
+## 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.
+
+## 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. |
+| 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. |
+
+### GitHub (Q2)
+
+| 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 |
+|---|---|
+| 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
+
+1. A card created by Jarvis (J3) appears as a Gitea issue within one sync interval; closing the issue in Gitea marks the card for review, not silent closure; dispatch/claims never round-trip through Gitea.
+2. Killing the adapter mid-mission: dispatch continues unaffected (record is native); on restart, sync converges without duplicates.
+3. The same mission can be mirrored to Gitea and viewed on the local kanban simultaneously without state divergence.
+
+## Non-goals
+
+- External provider AS the backlog (vetoed — "truly swappable backends" option declined 2026-07-09).
+- Two-way sync of claims/TTL semantics (external systems can't express them; projection only).
+
+## 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.

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

@@ -0,0 +1,60 @@
+# PRD — Hermes Decommission & Tenant-1 Migration · Workstream X
+
+> **Status:** DRAFT for ratification · **Goals:** X1–X3 · **Doctrine:** NS-13, ASM-8 (Hermes untouched until verified parity)
+> Ratified direction (D2, 2026-07-09): Mosaic absorbs **all four** Hermes functions — messaging bridge, task board, permission relay, multi-platform reach.
+
+## Deployment scope (D12/ASM-9)
+
+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).
+
+## 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 |
+
+## Requirements
+
+### Parity checklist + cutover plan (X1)
+
+| 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. |
+
+### 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. |
+
+### Decommission (X3)
+
+| 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. |
+
+## Acceptance criteria
+
+1. AC-NS-11: with Hermes stopped, no fleet or main-agent capability regresses.
+2. `python tools/brain.py today`'s information content is fully answerable by Jarvis from the product workspace post-X2.
+3. Zero references to Hermes MCP tools in any active agent runtime config after X3.
+
+## Sequencing note
+
+X depends on the longest chains (K1→K2, P2, Q1, J2). Expected order of value delivery: J1–J4 (Jarvis on existing transport interim) → K1/J5 (Matrix room) → P2, W1–W3, Q1 in parallel → X1 checklist → X2 migration → K2 bridges → X3 decommission.
+
+- ASSUMPTION (interim transport): until K1 lands, Jarvis may run against the tmux connector (CLI/`agent send`) rather than standing up any Discord channel — keeps D1 (Matrix-first, no #jarvis Discord) intact.

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

@@ -0,0 +1,70 @@
+# PRD — HMI Main Agent ("Jarvis") · Workstream J
+
+> **Status:** DRAFT for ratification · **Source of truth once landed:** NORTH_STAR.yaml goals J1–J5
+> **Depends on upstream:** H2 (system-type profiles), A3a (card lifecycle), B1 (supervisor tick), F4/K1 (Matrix connector)
+
+## Mission
+
+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.
+
+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.
+
+## 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). |
+
+### 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). |
+| 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. |
+
+### 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. |
+| 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 |
+|---|---|
+| 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.) |
+
+### 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. |
+
+## 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).
+
+## Non-goals
+
+- Jarvis executing code/infra changes (that is Mos + fleet).
+- Horizontal sharding of the main agent (rejected in the Matrix charter: split-brain).
+- Per-workspace fleets (post-MVP per ASM-6).
+
+## 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).

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

@@ -0,0 +1,51 @@
+# 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")
+> **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.
+
+## Requirements
+
+### Guard-rails engine (P1)
+
+| ID | Requirement |
+|---|---|
+| P-R1 | Capabilities are `resource:action` grants (e.g. `email:send`, `git:push_main`, `dns:update`) with permission levels (read / organize / draft / execute / admin) per the existing design doc. |
+| P-R2 | Each integration declares its `requires_approval` list; grants are workspace-scoped and per-agent-persona. |
+| P-R3 | Enforcement sits in the gateway/API dispatch path — an agent cannot bypass it by construction; bypass attempts are audited and denied. |
+| P-R4 | Policy is configuration (profile field), honoring the configurability pillar: a user can tighten/loosen per capability without code change. |
+
+### Approval queue + chat approvals (P2)
+
+| ID | Requirement |
+|---|---|
+| P-R5 | A pending approval is a durable queue record: requesting agent, capability, human-readable intent summary, prepared payload reference, TTL. |
+| P-R6 | Approve/deny from the Matrix room (message action or reply verb); the requesting agent is notified of the outcome and proceeds/aborts. |
+| P-R7 | Timeout = deny (fail-closed). Deny and timeout leave the system unchanged. |
+| P-R8 | Full audit trail: who approved what, when, from which surface (AC-NS-10). |
+| P-R9 | The main agent (Jarvis) surfaces pending approvals conversationally (J-R13) but approval authority is the human's — Jarvis never auto-approves. |
+
+### webUI surface (P3)
+
+| ID | Requirement |
+|---|---|
+| P-R10 | Pending-approval queue view in `apps/web` with one-click approve/deny, filterable per workspace/agent (depends W3 dashboard shell). |
+
+## Acceptance criteria
+
+1. AC-NS-10 end-to-end: a `requires_approval` action executes only post-approve; deny/timeout paths verified unchanged + audited.
+2. Approval round-trip from a phone Matrix client (Element) in under 3 taps.
+3. With Hermes stopped, permission flow fully served by Mosaic (feeds AC-NS-11).
+
+## Non-goals
+
+- Automated quality gates (coordinator/CI approvals) — different system, already exists.
+- Fine-grained LLM output moderation — out of scope; this governs *actions*.
+
+## Assumptions
+
+- ASSUMPTION: the durable queue rides the native Postgres storage service (same substrate as the backlog), not a new datastore.
+- ASSUMPTION: routine delivery operations already hard-gated as no-confirmation (push/merge per Mosaic contract) are NOT routed through the relay — the relay is for `requires_approval` capabilities only, so it does not reintroduce routine confirmation prompts.

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

@@ -0,0 +1,52 @@
+# PRD — webUI Fleet Control · Workstream W (realizes F6)
+
+> **Status:** DRAFT for ratification · **Goals:** W1–W3 · **Upstream anchor:** `PRD-fleet-suite.md` Phase F6 ("webUI hooks — stable JSON contract + terminate/attach(butt-in) surface")
+> Confirmed gap: zero xterm/pty/tmux code in `apps/web` on either the old snapshot or `origin/main`.
+
+## Mission
+
+The user can pop in on **any** agentic tmux session from the web, and get a full top-down view of the system — fleet roster, health, work in flight, spend — without touching a terminal. This is the product surface for "user has ability to pop in on any agent session; full top-down view available."
+
+## Requirements
+
+### Attach service (W1)
+
+| 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. |
+
+### Web terminal (W2)
+
+| 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. |
+
+### 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. |
+| W-R11 | Existing widget framework (`AgentStatusWidget`, `OrchestratorEventsWidget`, SSE proxy routes) is the starting point, upgraded to the fleet contract rather than rebuilt. |
+
+## Acceptance criteria
+
+1. From a browser (desktop + phone), the user watches a live coder-agent pane read-only, then butt-ins with the right grant, types a message, detaches; agent session continues; audit log shows both.
+2. Dashboard reflects an agent crash within one heartbeat interval; PAUSE flip halts dispatch within one tick (AC-NS-5) from the UI.
+3. A user without butt-in grant can watch but cannot type (enforced server-side).
+
+## Non-goals
+
+- Replacing tmux as the session substrate (tmux remains the transport; web is a view).
+- Cross-host federation of the dashboard (rides the existing federation workstream later, per upstream note "Phase 5 rides federation").
+
+## Assumptions
+
+- ASSUMPTION: pty bridging terminates at the gateway on the fleet host (web1), not in `apps/web`; Next.js only speaks WebSocket to the gateway.
+- ASSUMPTION: the jarvis-brain dashboard's node-pty/xterm work (`dashboard/server/terminal.ts`) serves as reference implementation only; code is not ported wholesale into the multi-tenant product without the authz layer above.

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

@@ -0,0 +1,42 @@
+# 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
+**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.
+
+## 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-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.

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

@@ -0,0 +1,207 @@
+# Proposed additions to docs/fleet/NORTH_STAR.yaml — DRAFT (Jason ratification pending, 2026-07-09)
+#
+# Merge these entries into the existing NORTH_STAR.yaml sections, then regenerate
+# NORTH_STAR.md via renderNorthStarMarkdown (packages/mosaic/src/commands/fleet.ts).
+# Ids chosen to avoid collision with existing workstreams A–H and goals.
+
+standing_objectives:
+  - id: NS-10
+    text: >-
+      Every Mosaic system runs exactly one always-on HMI main agent (default
+      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.
+  - id: NS-11
+    text: >-
+      Irreversible or externally-visible agent actions pass a human-in-the-loop
+      permission relay (approve/deny from chat or webUI) governed by
+      per-capability guard rails; prepare freely, execute with approval.
+  - id: NS-12
+    text: >-
+      The Mosaic Backlog remains the sole backlog of record; external providers
+      (Gitea, GitHub, local kanban, …) attach as bidirectional sync adapters,
+      never as the record.
+  - id: NS-13
+    text: >-
+      Hermes is fully decommissioned once Mosaic reaches verified parity on
+      transport (Matrix connector), task board (native backlog + webUI),
+      permission relay, and multi-platform reach (mautrix bridges).
+
+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.
+  - id: AC-NS-9
+    text: >-
+      A mission agreed in the main-agent conversation appears as a backlog card
+      set with acceptance criteria, is drained by the orchestrator without
+      chat-level handoff, and its completion is reported back to the user by the
+      main agent from board/heartbeat state alone.
+  - id: AC-NS-10
+    text: >-
+      An action listed as requires_approval executes only after an explicit
+      human approve from Matrix or webUI; deny and timeout paths leave the
+      system unchanged and audited.
+  - id: AC-NS-11
+    text: >-
+      With Hermes stopped, no fleet or main-agent capability regresses
+      (transport, board, approvals, multi-platform reach all served by Mosaic).
+
+workstreams:
+  - id: J
+    title: HMI main agent ("Jarvis") — persona, PA toolchain, delegation contract
+  - id: K
+    title: Connectors & multi-platform reach — F4 Matrix implementation + mautrix bridges
+  - id: W
+    title: webUI fleet control — tmux pop-in, top-down view (realizes F6)
+  - id: P
+    title: Permission relay — capability guard rails + human approval queue
+  - id: Q
+    title: Backlog provider sync adapters — Gitea/GitHub/local kanban
+  - id: X
+    title: Hermes decommission & tenant-1 migration
+
+goals:
+  # J — HMI main agent
+  - id: J1
+    title: Main-agent persona + profile — instantiate personal-assistant system type as mosaic-agent@main (alias Jarvis), model tier a profile field (Opus default)
+    phase: 1
+    priority: must-have
+    depends_on: [H2]
+  - id: J2
+    title: PA toolchain — email, calendar, tasks, knowledge, tickets executed directly against the product API in the user's workspace
+    phase: 1
+    priority: must-have
+    depends_on: [J1]
+  - id: J3
+    title: Delegation contract — main agent authors mission cards (goal, acceptance criteria, budget advisory) onto the backlog; orchestrator drains; no chat-level handoff
+    phase: 1
+    priority: must-have
+    depends_on: [J1, A3a]
+  - id: J4
+    title: Passive fleet observability — main agent answers status from heartbeats, fleet ps JSON, and board state; zero orchestrator interrupts
+    phase: 1
+    priority: must-have
+    depends_on: [J1, B1]
+  - id: J5
+    title: Main-agent Matrix room via OrchestratorConnector(matrix)
+    phase: 2
+    priority: must-have
+    depends_on: [J1, K1]
+
+  # K — connectors & reach (extends f4-matrix-connector.md)
+  - id: K1
+    title: Matrix connector implementation — CS-API client factory per f4 Phase 2, self-hosted homeserver
+    phase: 2
+    priority: must-have
+    depends_on: []
+  - id: K2
+    title: mautrix bridge deployment (telegram/signal/whatsapp/slack/discord) as GitOps-managed infra; agents speak only Matrix
+    phase: 3
+    priority: should-have
+    depends_on: [K1]
+
+  # W — webUI fleet control (realizes F6)
+  - id: W1
+    title: Gateway pty/tmux attach service — read-only watch and interactive butt-in verbs, workspace-scoped authz, audit log
+    phase: 2
+    priority: must-have
+    depends_on: []
+  - id: W2
+    title: xterm.js session view in apps/web wired to W1 (watch + butt-in)
+    phase: 2
+    priority: must-have
+    depends_on: [W1]
+  - id: W3
+    title: Top-down fleet dashboard — roster, heartbeats, cards in flight, advisory spend, PAUSE control
+    phase: 2
+    priority: must-have
+    depends_on: [B1]
+
+  # P — permission relay
+  - id: P1
+    title: Capability guard-rails engine — resource:action grants, permission levels, requires_approval list per integration
+    phase: 2
+    priority: must-have
+    depends_on: []
+  - id: P2
+    title: Approval queue + approve/deny from the Matrix room (timeout = deny; full audit)
+    phase: 2
+    priority: must-have
+    depends_on: [P1, K1]
+  - id: P3
+    title: Approval surface in webUI (pending queue, one-click approve/deny)
+    phase: 3
+    priority: should-have
+    depends_on: [P1, W3]
+
+  # Q — backlog provider sync adapters
+  - id: Q1
+    title: Provider adapter interface + Gitea adapter (bidirectional card↔issue sync; native backlog stays record)
+    phase: 2
+    priority: must-have
+    depends_on: [A2]
+  - id: Q2
+    title: GitHub adapter
+    phase: 3
+    priority: should-have
+    depends_on: [Q1]
+  - id: Q3
+    title: Local kanban surface — webUI board view over the native backlog (no external provider required)
+    phase: 2
+    priority: should-have
+    depends_on: [A2, W3]
+
+  # X — Hermes decommission & tenant-1 migration
+  - id: X1
+    title: Hermes parity checklist + cutover plan (transport, board, approvals, reach) with rollback
+    phase: 3
+    priority: must-have
+    depends_on: [K1, P2, Q1]
+  - id: X2
+    title: Tenant-1 migration — jarvis-brain flat files (projects, tasks, events, tickets, knowledge) into the Jason workspace; brain.py retires
+    phase: 3
+    priority: must-have
+    depends_on: [J2]
+  - id: X3
+    title: Hermes decommission — stop and remove Hermes services after AC-NS-11 verified
+    phase: 4
+    priority: must-have
+    depends_on: [X1, X2, K2]
+
+assumptions:
+  - id: ASM-5
+    vetoable: true
+    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.
+  - id: ASM-6
+    vetoable: true
+    text: >-
+      Product multi-tenancy at MVP means self-hosted installs with multiple
+      workspaces per install (Authentik OIDC); per-tenant isolated FLEETS
+      (agents per workspace) are post-MVP.
+  - id: ASM-7
+    vetoable: true
+    text: >-
+      mautrix bridges are deployed as infrastructure (GitOps), not as Mosaic
+      application code; Mosaic's only conversational protocol is Matrix.
+  - id: ASM-8
+    vetoable: true
+    text: >-
+      During migration (before X3), Hermes remains running untouched; no
+      Hermes-dependent capability is removed until its Mosaic replacement is
+      verified in production.
+  - id: ASM-9
+    vetoable: true
+    text: >-
+      The trial environment is the homelab fleet deployment (D12). Environments
+      running the primitive-era implementation (USC/web1: mos-claude.service,
+      Hermes, jarvis-brain boards) are untouched during the trial; workstream X
+      executes there as a post-trial adoption phase, environment by
+      environment.