stack/docs/fleet/NORTH_STAR.yaml

# Mosaic Fleet — NORTH_STAR (machine-readable source of truth)
#
# This file is the single machine-readable source of truth for fleet planning.
# Prose docs (including NORTH_STAR.md) are deterministic PROJECTIONS of this file.
# Regenerate the Markdown projection with the pure generator in
# packages/mosaic/src/commands/fleet.ts (renderNorthStarMarkdown). Edit the YAML,
# never the .md.
#
# Self-contained Mosaic. The backlog of record is
# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.

version: 1

mission: >-
  A self-driving Mosaic system that 24/7 unattended converts a machine-readable
  goal set into merged, CI-green, budget-bounded change — looping
  plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native
  backlog/dispatch engine. Mosaic is general-purpose: the user declares the
  system type they want (software delivery, personal assistant, research,
  business/operations, …) and the orchestrator provisions the matching persona
  roster and structure; the delivery fleet is one profile among many.

substrate:
  note: >-
    The Mosaic Backlog is the backlog of record + dispatch engine, built on
    Mosaic's native Postgres storage service (@mosaicstack/db drizzle;
    PGlite-embedded by default, full Postgres by config).

standing_objectives:
  - id: NS-1
    text: >-
      Single machine-readable source (this file) drives planning; prose docs are
      projections.
  - id: NS-2
    text: >-
      Every backlog item is an independently-shippable unit with stable id,
      priority, depends_on DAG, represented as a Mosaic Backlog card; spend
      tracked as advisory projection.
  - id: NS-3
    text: >-
      The supervisor guarantees movement: no idle agent while ready
      dependency-satisfied work exists; no empty backlog without a replan
      request; assignment via Mosaic native dispatch/claim.
  - id: NS-4
    text: >-
      Exactly one merge-gate approver; nothing reaches main except via
      pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the
      backstop.
  - id: NS-5
    text: >-
      Every unit bounded by wall-clock TTL on its claim; token caps enforced
      only where a real meter exists, else advisory.
  - id: NS-6
    text: >-
      Context cleared between tasks for ephemeral runners
      (reset_between_tasks); persona+mission re-injected per task.
  - id: NS-7
    text: >-
      Meta-loop (session-review + enhancer) continuously proposes small
      fleet-improvement PRs.
  - id: NS-8
    text: >-
      Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
      before every dispatch and every merge.
  - id: NS-9
    text: >-
      Mosaic is a general-purpose multi-agent system: the user declares the
      SYSTEM TYPE to run (e.g. software delivery, personal assistant, research,
      business/operations) and the orchestrator provisions the matching persona
      roster and org structure from a cross-domain baseline persona library; the
      delivery/coding fleet is one profile among many.
  - id: NS-10
    text: >-
      An adoption is not complete until the mechanism it replaces is removed.
      Two live conventions for one concern is the defect, not a transition
      state. Measured 2026-08-20: brain-home adopted by 9 modules and not 10;
      MOSAIC_HOME honored in 4 places, each re-deriving it; backlog cards
      declared while TASKS.md files stayed authoritative. Every one was decided
      correctly and left half-applied.

success_criteria:
  - id: AC-NS-0
    tier: 0
    text: >-
      The operator launches an agent on any configured harness with one
      command, observes its state and sends it work without attaching to a
      terminal multiplexer.
  - id: AC-NS-1
    tier: 1
    text: >-
      The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
      healthy across reboot.
  - id: AC-NS-2
    tier: 1
    text: >-
      A goal added to this YAML is decomposed to cards and either merged or
      escalated, with no human in the loop.
  - id: AC-NS-3
    tier: 1
    text: >-
      No PR merges with failure/error/no-status/timeout CI, and none bypass
      pr-merge.sh.
  - id: AC-NS-4
    tier: 1
    text: >-
      TTL is enforced on claims; token caps remain advisory until a real meter
      exists.
  - id: AC-NS-5
    tier: 1
    text: >-
      Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
  - id: AC-NS-6
    tier: 2
    text: >-
      A user can declare a system type and the fleet provisions the matching
      persona roster + topology from the baseline library, with no code change.
  - id: AC-NS-7
    tier: 2
    text: >-
      A user-customized persona (edited or added via the orchestrator) survives
      mosaic update: baseline reseed never clobbers user overrides.

workstreams:
  - id: A
    title: Substrate — Mosaic Backlog on native Postgres storage service
  - id: B
    title: Supervisor — movement guarantee, two-agent floor, dispatch/claim
  - id: C
    title: Planner — goal decomposition into independently-shippable cards
  - id: D
    title: Merge-gate — single approver, pr-merge.sh after CI wait
  - id: E
    title: Meta-loop — session-review + enhancer improvement PRs
  - id: F
    title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
  - id: G
    title: Kill-switch — operator PAUSE honored before dispatch and merge
  - id: H
    title: Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization
  - id: I
    title: Operator surface — launcher, fleet visibility, reliable steering (tier 0)
  - id: J
    title: Web control plane — browser surface over the gateway (tier 1)
  - id: K
    title: Clients — desktop and mobile over the same backend (tier 2)
  - id: L
    title: Auth profiles — per-provider accounts, per-session selection (tier 2)
  # M is DORMANT by ruling (PRD rev1, D3 as amended 2026-09-01, GOV.5 Q-T1
  # ruling B). Federation M1–M3 exist in code behind `tier === 'federated'`
  # (M3 landed 2026-06-24/25), are excluded from the v1 bar and frozen. It
  # projects no goals on purpose: none may be added before a security
  # re-audit of the frozen cert/auth code and a federation PRD revision.
  - id: M
    title: Federation — DORMANT; M1–M3 shipped and frozen (PRD rev1 D3 as amended; security re-audit gate before resumption)

# NOTE: workstreams C, D, E, F and M are declared but currently project no goals.
# That is planning debt, not an editing error: their goals have not been written
# yet. The A5 validator below reports it rather than letting it stay invisible.

goals:
  - id: A1
    title: Machine-readable NORTH_STAR.yaml + Markdown projection
    phase: 1
    tier: 1
    priority: must-have
    depends_on: []
  - id: A2
    title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
    phase: 1
    tier: 1
    priority: must-have
    depends_on: [A1]
  - id: A3a
    title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
    phase: 1
    tier: 1
    priority: must-have
    depends_on: [A2]
  - id: A3b
    title: TTL-bounded claim enforcement (wall-clock) on cards
    phase: 1
    tier: 1
    priority: must-have
    depends_on: [A3a]
  - id: A4
    title: Advisory spend projection per card (degrades to TTL, no real meter)
    phase: 1
    tier: 1
    priority: should-have
    depends_on: [A3a]
  - id: B1
    title: Supervisor tick — readiness scan, two-agent-floor health check
    phase: 2
    tier: 1
    priority: must-have
    depends_on: [A3a]
  - id: B2
    title: Native dispatch/claim — assign ready dependency-satisfied work
    phase: 2
    tier: 1
    priority: must-have
    depends_on: [A3b, B1]
  - id: B3a
    title: Planner decompose — goal added to YAML → cards
    phase: 2
    tier: 1
    priority: must-have
    depends_on: [A2, B1]
  - id: B3b
    title: Replan request on empty backlog; escalate on no-decompose
    phase: 2
    tier: 1
    priority: should-have
    depends_on: [B3a]
  - id: G1
    title: PAUSE kill-switch + merge-gate honored before dispatch and merge
    phase: 2
    tier: 1
    priority: must-have
    depends_on: [B2]
  - id: H1
    title: Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)
    phase: 1
    tier: 2
    priority: must-have
    depends_on: [A1]
  - id: H2
    title: System-type profiles — declarative mapping of system type to persona roster + topology
    phase: 2
    tier: 2
    priority: must-have
    depends_on: [H1]
  - id: H3
    title: System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure
    phase: 2
    tier: 2
    priority: must-have
    depends_on: [H2]
  - id: H4
    title: Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides)
    phase: 2
    tier: 2
    priority: must-have
    depends_on: [H1]
  - id: A5
    title: NORTH_STAR schema validator — every goal's workstream declared, every workstream has a goal, every depends_on id exists, every tier has a success criterion; runs in CI beside the Markdown regeneration check
    phase: 1
    tier: 0
    priority: must-have
    depends_on: [A1]
  - id: I1
    title: One home resolver — a single function resolving MOSAIC_HOME with a sane default, adopted by every module. Today brain-home.ts is imported by 9 modules while 10 still use DEFAULT_MOSAIC_HOME, and MOSAIC_HOME is re-derived ad hoc in 4 places. NS-10 applies - finish the adoption and delete the second path
    phase: 1
    tier: 0
    priority: must-have
    depends_on: []
  - id: I2
    title: 'mosaic fleet ps sees the fleet that is actually running. Three measured blockers: the roster declares socket `mosaic-fleet` which does not exist, the 18 live sessions are on the default socket, and nothing writes a roster because seats are launched outside the CLI. Make the socket configurable and the roster written at launch, or make ps read tmux + seat dirs directly'
    phase: 1
    tier: 0
    priority: must-have
    depends_on: [I1]
  - id: I3
    title: Migrate fleet steering onto mosaic agent send --verify (exists, FLEET-OBS-005, spec FR-5) and retire tools/tmux/agent-send.sh, which forges the sender (D33) and returns an uninformative rc (D16, D34). FR-5 predates those defects by a month
    phase: 1
    tier: 0
    priority: must-have
    depends_on: [I1]
  - id: I4
    title: 'mosaic fleet absorbs what launch-seat.sh does and launch-seat.sh is deprecated: compose the prompt file set, force the skill set, wire the style hook, fail closed on any unreadable input, export per-seat git identity, and register the seat in the roster. launch-seat.sh was a manual method; it is the reference implementation, not the destination'
    phase: 1
    tier: 0
    priority: must-have
    depends_on: [I1, I5]
  - id: I5
    title: Harness probe matrix — verify a working prompt-injection path for claude, codex, opencode and pi, and refuse any runtime whose path is unverified. AC-NS-0 clause 1 ("any configured harness") rests on this. The probe work in docs/plans/2026-08-19_launch-seat-multi-runtime.md (brain, untracked) transfers; its launch-seat.sh target does not
    phase: 1
    tier: 0
    priority: must-have
    depends_on: []
  - id: I6
    title: Finish the heartbeat responder (FLEET-OBS-002, the only Phase-2 task still in-progress; spec FR-2). Health must mean "answered a heartbeat", not "pane alive" — pane state measured two seats wrong on 2026-08-20
    phase: 1
    tier: 0
    priority: must-have
    depends_on: []
  - id: I7
    title: Independent review and live-fleet dogfood of the Phase-2 verbs (FLEET-OBS-008), then land them (FLEET-OBS-009). Implementation is done and verification is not; "done" in a task file frozen five weeks is not evidence
    phase: 1
    tier: 0
    priority: must-have
    depends_on: [I2, I3, I4, I6]
  - id: I8
    title: Neutralize misleading documentation — supersede headers on docs that state a stale status, a false blocker or a retired mechanism. Cheap, and it is tier 0 because a stale doc does not merely fail to help an agent, it actively misroutes one. Rebuilding the documentation is a separate and later job
    phase: 1
    tier: 0
    priority: must-have
    depends_on: []
  - id: I9
    title: Study t3code's agent-attach and multi-provider auth methods and record what transfers. Reference only — Mosaic implements its own within the stack, never adopts the code and never takes the dependency. Informs HOW I/J/K/L are built, not whether
    phase: 1
    tier: 0
    priority: should-have
    depends_on: []
  - id: J1
    title: Web control plane over the gateway — fleet visibility and steering in a browser, same data source as I2
    phase: 3
    tier: 1
    priority: must-have
    depends_on: [I2]
  - id: K1
    title: Desktop and mobile clients against the gateway, authenticated
    phase: 4
    tier: 2
    priority: must-have
    depends_on: [J1]
  - id: L1
    title: Per-provider auth profiles with per-session selection
    phase: 4
    tier: 2
    priority: must-have
    depends_on: [I4]

assumptions:
  - id: ASM-1
    vetoable: true
    text: >-
      The Mosaic Backlog on the native Postgres storage service is the backlog
      of record.
  - id: ASM-2
    vetoable: true
    text: >-
      Claude gate roles have no native busy status, so readiness = pane-idle +
      heartbeat.
  - id: ASM-3
    vetoable: true
    text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
  - id: ASM-4
    vetoable: true
    text: >-
      Baseline personas ship in framework/fleet/roles/ (reseeded on update);
      user overrides live in a separate PRESERVE_PATHS-protected layer and win
      on merge.

spend:
  advisory: true
  note: >-
    No per-task token meter yet; budgets degrade to TTL. Spend is tracked only
    as an advisory projection alongside each card.