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

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