Move old docs into _old_structure dir. Create blank GETTING_STARTED.md document

2026-08-10 14:53:21 -05:00
parent 1655b1579a
commit cd4409abc3
273 changed files with 278 additions and 247 deletions
@@ -0,0 +1,215 @@
+# 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 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). 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.
+  - 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.
+
+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.
+  - id: AC-NS-6
+    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
+    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: H
+    title: Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization
+
+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]
+  - id: H1
+    title: Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)
+    phase: 1
+    priority: must-have
+    depends_on: [A1]
+  - id: H2
+    title: System-type profiles — declarative mapping of system type to persona roster + topology
+    phase: 2
+    priority: must-have
+    depends_on: [H1]
+  - id: H3
+    title: System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure
+    phase: 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
+    priority: must-have
+    depends_on: [H1]
+
+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.