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 workspace 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. Exactly-one-per-workspace is enforced by a
      workspace lease (J-R16), not by convention.
  - 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).
  - id: NS-14
    text: >-
      Mosaic Stack accepts inbound structured error/log reporting from every
      agent and install (MALS-lineage logging service); agentic-efficiency
      telemetry is optional, opt-in, and anonymous by construction — no IP or
      PII is captured or derivable from the ingestion path.

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 (distinct credential/quota pools pinned in the J1
      profile), its response latency is unaffected and the orchestrator
      receives zero conversational traffic. Measured, not vibes: scripted
      suite, >=30 interleaved turns, TTFT p95 <= 1.2x idle baseline with
      bootstrap CI.
  - 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
  - id: M
    title: Enhanced memory subsystem — vector DB + memory service + provenance/tombstones (Gate Zero MISSING artifact)
  - id: L
    title: Logging & telemetry — MALS-lineage inbound error reporting + optional anonymous efficiency telemetry

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]
  # J2 split (debate P0 #2): phase-1 Jarvis must not hold an external-write
  # credential path before the permission relay (P2) exists — NS-11 by DAG.
  - id: J2a
    title: PA toolchain (workspace-internal) — tasks, events, knowledge, ideas executed directly against the product API in the user's workspace; no external credentials provisioned
    phase: 1
    priority: must-have
    depends_on: [J1]
  - id: J2b
    title: PA toolchain (external integrations) — email, external calendars, helpdesk via workspace-scoped integrations; credentials gateway-held; requires_approval routes through the relay
    phase: 2
    priority: must-have
    depends_on: [J2a, P2]
  - 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]
  - id: J6
    title: Shared event/wake router — level-triggered reconciler over durable state (heartbeats, cards, approvals) with hysteretic per-condition suppression; templated provenance-tagged wake turns; per-agent polling forbidden (Gate Zero MISSING artifact; J-R13 depends on it)
    phase: 1
    priority: must-have
    depends_on: [J1]

  # 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: []
  # K2 scope (debate §3.7): a pre-ratification Hermes traffic audit narrows the
  # must-have bridge subset to platforms with live traffic; only that subset
  # gates X3 — remaining bridges are genuinely optional post-X3.
  - id: K2
    title: mautrix bridge deployment (telegram/signal/whatsapp/slack/discord) as GitOps-managed infra; agents speak only Matrix; must-have subset = platforms carrying live Hermes traffic per Gate Zero audit
    phase: 3
    priority: should-have
    depends_on: [K1]
  - id: K3
    title: Push pipeline (Sygnal or equivalent) + homeserver ops — monitored delivery checks, health-floor registration, rehearsed backup/restore (Gate Zero MISSING artifact; P2 phone-approval AC depends on it)
    phase: 2
    priority: must-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. Storage authority (debate P0 #1): Postgres is
    # authoritative for ALL product entities; the flat-file backend is a derived,
    # regenerated, READ-ONLY projection — never a second writable store.
  - id: X2
    title: 'Tenant-1 migration — P0 (jarvis-brain) into the proper Mosaic Stack: (a) PA data (projects/tasks/events/knowledge) into the Jason workspace, (b) agent memory/runbooks into the enhanced memory subsystem M1 (kept live, not frozen); jarvis-brain retires read-only only after both are verified'
    phase: 3
    priority: must-have
    depends_on: [J2a, P2, M1]
  - id: X3
    title: Hermes decommission — stop and remove Hermes services after AC-NS-11 verified; pre-stop evidence snapshot (logs/config/callback inventory + checksum) is a machine gate
    phase: 4
    priority: must-have
    depends_on: [X1, X2, K2]

  # M — enhanced memory subsystem (Gate Zero: cited by X2(b) but not built by
  # any prior workstream — this card closes that gap)
  - id: M1
    title: Enhanced memory subsystem — vector DB + memory service with mandatory provenance (human/agent/external), source-grounded retrieval preference, tombstones + re-embedding on source update, normative/parametric corpus split
    phase: 2
    priority: must-have
    depends_on: []

  # L — logging & telemetry (Jason 2026-07-09; NS-14). MALS (~/src/mals) is the
  # P0 of this capability; restoring it is infra work tracked as
  # infrastructure#135 (k3s migration landed without an Ingress).
  - id: L1
    title: MALS restored & exposed — k3s Ingress for mals.mosaicstack.dev, health verified, authenticated write smoke-tested (infrastructure#135); trial day-1 metric emission targets MALS until W3 panels exist
    phase: 1
    priority: must-have
    depends_on: []
  - id: L2
    title: Mosaic-native log ingestion — gateway/API endpoint for structured inbound error reporting from agents and installs (MALS-compatible schema; levels, categories, trace ids), workspace-scoped keys
    phase: 2
    priority: must-have
    depends_on: [L1]
  - id: L3
    title: Anonymous agentic-efficiency telemetry — opt-in, aggregate-only, no IP/PII captured or derivable at ingestion (NS-14); feeds W3 trend panels
    phase: 3
    priority: should-have
    depends_on: [L2, W3]

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.