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. NO Hermes runtime dependency. The backlog of record is
# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.

version: 1

mission: >-
  A self-driving Mosaic delivery fleet 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.

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). NOT Hermes.

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.

success_criteria:
  - id: AC-NS-1
    text: >-
      The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
      healthy across reboot.
  - id: AC-NS-2
    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
    text: >-
      No PR merges with failure/error/no-status/timeout CI, and none bypass
      pr-merge.sh.
  - id: AC-NS-4
    text: >-
      TTL is enforced on claims; token caps remain advisory until a real meter
      exists.
  - id: AC-NS-5
    text: >-
      Flipping fleet/run/PAUSED halts dispatch and merges within one tick.

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

goals:
  - id: A1
    title: Machine-readable NORTH_STAR.yaml + Markdown projection
    phase: 1
    priority: must-have
    depends_on: []
  - id: A2
    title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
    phase: 1
    priority: must-have
    depends_on: [A1]
  - id: A3a
    title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
    phase: 1
    priority: must-have
    depends_on: [A2]
  - id: A3b
    title: TTL-bounded claim enforcement (wall-clock) on cards
    phase: 1
    priority: must-have
    depends_on: [A3a]
  - id: A4
    title: Advisory spend projection per card (degrades to TTL, no real meter)
    phase: 1
    priority: should-have
    depends_on: [A3a]
  - id: B1
    title: Supervisor tick — readiness scan, two-agent-floor health check
    phase: 2
    priority: must-have
    depends_on: [A3a]
  - id: B2
    title: Native dispatch/claim — assign ready dependency-satisfied work
    phase: 2
    priority: must-have
    depends_on: [A3b, B1]
  - id: B3a
    title: Planner decompose — goal added to YAML → cards
    phase: 2
    priority: must-have
    depends_on: [A2, B1]
  - id: B3b
    title: Replan request on empty backlog; escalate on no-decompose
    phase: 2
    priority: should-have
    depends_on: [B3a]
  - id: G1
    title: PAUSE kill-switch + merge-gate honored before dispatch and merge
    phase: 2
    priority: must-have
    depends_on: [B2]

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

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.