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. It is a Level-0 orchestrator:
      it accomplishes work through delegation and subagents, never by executing
      coding/infra tasks itself, and it runs on model capacity separate from the
      orchestrator so its conversational latency is isolated from fleet load. The
      main agent never executes fleet work itself and never interrupts the
      orchestrator for status.
  - id: NS-11
    text: >-
      Irreversible or externally-visible agent actions pass a human-in-the-loop
      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 channel while the
      orchestrator is under full load; because the main agent runs on separate
      model capacity, its response latency is unaffected and the orchestrator
      receives zero conversational traffic.
  - id: AC-NS-9
    text: >-
      A mission agreed in the main-agent conversation appears as a backlog card
      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]
    # jarvis-brain is the P0 (prototype) Mosaic Stack; migration targets the proper
    # stack storage layer (vector DB + enhanced memory + flat-file backends).
  - id: X2
    title: 'Tenant-1 migration — P0 (jarvis-brain) into the proper Mosaic Stack: (a) PA data (projects/tasks/events/tickets/knowledge) into the Jason workspace, (b) agent memory/runbooks into the enhanced memory subsystem (kept live, not frozen); jarvis-brain retires read-only only after both are verified'
    phase: 3
    priority: must-have
    depends_on: [J2]
  - 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. Host co-location does NOT imply shared
      inference: Jarvis (Opus) and Mos (Fable) hold separate model capacity/quota
      so orchestrator load cannot degrade conversational latency (AC-NS-8).
  - id: ASM-6
    vetoable: true
    text: >-
      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.