mosaicstack/stack
13
0
Fork 1
Code Issues 305 Pull Requests 9 Actions Packages Projects Releases 15 Wiki Activity

docs(fleet): tier the north star and declare the tier-0 operator surface (#1337)
ci/woodpecker/push/publish Pipeline was canceled
Details

Browse Source
This commit was merged in pull request #1337.
This commit is contained in:
fred
2026-08-20 23:05:34 +00:00
parent ca97b885b0
commit af43a7a63e
27 changed files with 307 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TASKS.md
+15 -1
View File
@@ -1,5 +1,19 @@
# Tasks — MVP (Top-Level Rollup)
> ---
>
> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
>
> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
> model replaced this one and nobody retired the old file, so it kept reading as
> authoritative while going stale.
>
> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
> code when it froze five weeks ago.
>
> Kept as a record of what was believed. Do not update it; update the YAML.
> Single-writer: orchestrator only. Workers read but never modify.
>
> **Mission:** mvp-20260312
@@ -108,7 +122,7 @@ Active workstream is **W1 — Federation v1**. Workers should:
## north-star doctrine consolidation — doc PR — feat/north-star-doctrine
- Status: applied Mos's consolidated merge-map to docs/fleet/north-star.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
- Status: applied Mos's consolidated merge-map to docs/fleet/FLEET-DOCTRINE.md (budget governance + control plane/central register + 200k cap + delegation + unified-identity Fleet + role-based naming + tmux security + drift re-captures). Doctrine only; #622/#623/#625/#628 out-of-scope. Conflict checklist green. Detail: scratchpads/north-star-doctrine.md.
## #631 — re-seed preserves user fleet data (CRITICAL) — fix/631-reseed-preserves-fleet-data
docs/federation/TASKS.md
+16
View File
@@ -1,5 +1,21 @@
# Tasks — Federation v1
> ---
>
> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
>
> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
> model replaced this one and nobody retired the old file, so it kept reading as
> authoritative while going stale.
>
> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
> code when it froze five weeks ago. `FED-M3-06` is marked not-started and `get.controller.ts`
> has existed for eight weeks; `FED-M3-10/11` claim no tests exist while fifteen spec files
> do. `FED-M2-DEPLOY-IMG-FIX` names `apps/gateway/Dockerfile`, which is not in the repo.
>
> Kept as a record of what was believed. Do not update it; update the YAML.
> Single-writer: orchestrator only. Workers read but never modify.
>
> **Mission:** federation-v1-20260419
docs/fleet/north-star.md → docs/fleet/FLEET-DOCTRINE.md
+31 -12
View File
@@ -1,9 +1,26 @@
# Mosaic Fleet — North Star
---
kind: spec
parent: docs/fleet/NORTH_STAR.yaml
status: active
---
# Mosaic Fleet — Doctrine
> **This is the WHY. `NORTH_STAR.yaml` is the WHAT and WHEN.**
> Renamed from `north-star.md` on 2026-08-20. It sat one character away from the
> generated `NORTH_STAR.md` in the same directory, and the two are read by different
> populations — the PRDs and TASKS files cite this one, while the agent role contracts
> and the generator spec cite the YAML pair. Same-name-different-thing was the confusion;
> the content was never in conflict.
>
> **Nothing here overrides `NORTH_STAR.yaml`.** Where this document states a plan item,
> the YAML is authoritative. Where it states a decision, a rationale, or a role
> definition, this document is the record and the YAML carries none of it.
>
> **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312`
> **Umbrella:** [docs/MISSION-MANIFEST.md](../MISSION-MANIFEST.md) · [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
> **Status:** doctrine — authored 2026-06-20. Owner of this file: Fleet workstream lead.
> This document does **not** modify the MVP rollup; a rollup row is proposed, not written here.
> **Umbrella:** [docs/MISSION-MANIFEST.md](../MISSION-MANIFEST.md)
> **Authored:** 2026-06-20. Owner: Fleet workstream lead.
> This document does **not** modify the MVP rollup.
## Vision
@@ -264,15 +281,17 @@ Dedicated Postgres **instance** vs. dedicated **schema** in the existing instanc
Recommendation: dedicated schema, existing instance (a migration file, not new infra);
re-evaluate if isolation or write-volume demands it.
## Phased roadmap
## Phased roadmap — SUPERSEDED
| Phase | Outcome | Status |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| 0–1 | tmux PoC, hardening, published CLI v0.0.34 (#565–#568) | ✅ done |
| **2 — Observability** | fleet ps (host+tenant aware join), heartbeat protocol + dogfood stub answers it, agent watch (read-only), agent send --verify receipts | ▶ now |
| 3 — Real runtimes | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane) | planned |
| 4 — Unified definition | one agent schema in gateway; mosaic agent --new → materialized per-tenant session; uid-tenant provisioning; **`fleet` schema migration + `forge-exec` TaskExecutor adapter (forge → `agent-send.sh`)** | planned |
| 5 — Control plane | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity; **central register live (spend ledger, docs-as-projections, multi-host Kanban)** | planned |
Superseded 2026-08-20 by [`NORTH_STAR.yaml`](./NORTH_STAR.yaml), whose `goals` carry both
a `phase` (build order) and a `tier` (which promise the goal delivers). The five-phase
table that stood here could not express those as separate axes, and its "Phase 2 —
Observability ▶ now" row stayed unfalsified for two months because a phase has no exit
test. Tiers do: see `AC-NS-0` through `AC-NS-7`.
The phase-2 content itself is not lost — it is specified in
[`PRD.md`](./PRD.md) (Fleet Phase 2: Operator Observability) and is now tracked as
goals `I1`–`I5` at tier 0.
## Decisions of record (2026-06-20, with Jason)
docs/fleet/NORTH_STAR.md
+45 -25
View File
@@ -3,7 +3,7 @@
> **Generated file — do not edit by hand.**
> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
> Edit the YAML, then regenerate. Self-contained Mosaic.
## Mission
@@ -11,7 +11,7 @@ A self-driving Mosaic system that 24/7 unattended converts a machine-readable go
## Substrate
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.
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
@@ -24,16 +24,18 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
- **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
- **NS-9** — 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.
- **NS-10** — 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
- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
- **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
- **AC-NS-0** (tier 0) — 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.
- **AC-NS-1** (tier 1) — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
- **AC-NS-2** (tier 1) — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
- **AC-NS-3** (tier 1) — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
- **AC-NS-4** (tier 1) — TTL is enforced on claims; token caps remain advisory until a real meter exists.
- **AC-NS-5** (tier 1) — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
- **AC-NS-6** (tier 2) — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
- **AC-NS-7** (tier 2) — A user-customized persona (edited or added via the orchestrator) survives mosaic update: baseline reseed never clobbers user overrides.
## Workstreams
@@ -45,26 +47,44 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
| D | Merge-gate — single approver, pr-merge.sh after CI wait |
| E | Meta-loop — session-review + enhancer improvement PRs |
| F | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch |
| G | Kill-switch — operator PAUSE honored before dispatch and merge |
| H | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
| I | Operator surface — launcher, fleet visibility, reliable steering (tier 0) |
| J | Web control plane — browser surface over the gateway (tier 1) |
| K | Clients — desktop and mobile over the same backend (tier 2) |
| L | Auth profiles — per-provider accounts, per-session selection (tier 2) |
## Goals (backlog projection)
| id | title | phase | priority | depends_on |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
| A1 | Machine-readable NORTH_STAR.yaml + Markdown projection | 1 | must-have | — |
| A2 | Mosaic Backlog schema + storage-service card store (drizzle/PGlite) | 1 | must-have | A1 |
| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1 | must-have | A2 |
| A3b | TTL-bounded claim enforcement (wall-clock) on cards | 1 | must-have | A3a |
| A4 | Advisory spend projection per card (degrades to TTL, no real meter) | 1 | should-have | A3a |
| B1 | Supervisor tick — readiness scan, two-agent-floor health check | 2 | must-have | A3a |
| B2 | Native dispatch/claim — assign ready dependency-satisfied work | 2 | must-have | A3b, B1 |
| B3a | Planner decompose — goal added to YAML → cards | 2 | must-have | A2, B1 |
| B3b | Replan request on empty backlog; escalate on no-decompose | 2 | should-have | B3a |
| G1 | PAUSE kill-switch + merge-gate honored before dispatch and merge | 2 | must-have | B2 |
| H1 | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles) | 1 | must-have | A1 |
| H2 | System-type profiles — declarative mapping of system type to persona roster + topology | 2 | must-have | H1 |
| H3 | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure | 2 | must-have | H2 |
| H4 | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2 | must-have | H1 |
| id | title | tier | phase | priority | depends_on |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----- | ----------- | -------------- |
| A1 | Machine-readable NORTH_STAR.yaml + Markdown projection | 1 | 1 | must-have | — |
| A2 | Mosaic Backlog schema + storage-service card store (drizzle/PGlite) | 1 | 1 | must-have | A1 |
| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1 | 1 | must-have | A2 |
| A3b | TTL-bounded claim enforcement (wall-clock) on cards | 1 | 1 | must-have | A3a |
| A4 | Advisory spend projection per card (degrades to TTL, no real meter) | 1 | 1 | should-have | A3a |
| B1 | Supervisor tick — readiness scan, two-agent-floor health check | 1 | 2 | must-have | A3a |
| B2 | Native dispatch/claim — assign ready dependency-satisfied work | 1 | 2 | must-have | A3b, B1 |
| B3a | Planner decompose — goal added to YAML → cards | 1 | 2 | must-have | A2, B1 |
| B3b | Replan request on empty backlog; escalate on no-decompose | 1 | 2 | should-have | B3a |
| G1 | PAUSE kill-switch + merge-gate honored before dispatch and merge | 1 | 2 | must-have | B2 |
| H1 | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles) | 2 | 1 | must-have | A1 |
| H2 | System-type profiles — declarative mapping of system type to persona roster + topology | 2 | 2 | must-have | H1 |
| H3 | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure | 2 | 2 | must-have | H2 |
| H4 | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2 | 2 | must-have | H1 |
| A5 | 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 | 0 | 1 | must-have | A1 |
| I1 | 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 | 0 | 1 | must-have | — |
| I2 | 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 | 0 | 1 | must-have | I1 |
| I3 | 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 | 0 | 1 | must-have | I1 |
| I4 | 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 | 0 | 1 | must-have | I1, I5 |
| I5 | 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 | 0 | 1 | must-have | — |
| I6 | 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 | 0 | 1 | must-have | — |
| I7 | 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 | 0 | 1 | must-have | I2, I3, I4, I6 |
| I8 | 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 | 0 | 1 | must-have | — |
| I9 | 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 | 0 | 1 | should-have | — |
| J1 | Web control plane over the gateway — fleet visibility and steering in a browser, same data source as I2 | 1 | 3 | must-have | I2 |
| K1 | Desktop and mobile clients against the gateway, authenticated | 2 | 4 | must-have | J1 |
| L1 | Per-provider auth profiles with per-session selection | 2 | 4 | must-have | I4 |
## Assumptions (vetoable)
docs/fleet/NORTH_STAR.yaml
+129 -2
View File
@@ -6,7 +6,7 @@
# 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
# Self-contained Mosaic. The backlog of record is
# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.
version: 1
@@ -24,7 +24,7 @@ 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.
PGlite-embedded by default, full Postgres by config).
standing_objectives:
- id: NS-1
@@ -69,32 +69,53 @@ standing_objectives:
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.
@@ -112,80 +133,186 @@ workstreams:
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)
# NOTE: workstreams C, D, E and F 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
docs/fleet/PRD-fleet-suite.md
+1 -1
View File
@@ -1,7 +1,7 @@
# PRD — Mosaic Fleet Suite (init, configure, operate)
> **Workstream:** W-FLEET (Fleet) under mission `mvp-20260312` · **Phase:** 3→4 productization
> **North star:** [docs/fleet/north-star.md](./north-star.md) · prior: Phase-2 observability (#579), durable launch (#581), real-agent enablement (#583/#584/#586), releases 0.0.35–0.0.37
> **North star:** [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md) · prior: Phase-2 observability (#579), durable launch (#581), real-agent enablement (#583/#584/#586), releases 0.0.35–0.0.37
> **Lead:** Jarvis @ `w-jarvis`. **Collaborator:** coder agent @ `dragon-lin` ([email protected]:coder0-0).
> Owner of this file: Fleet workstream lead. Does not modify MVP single-writer control-plane files.
docs/fleet/PRD.md
+1 -1
View File
@@ -1,7 +1,7 @@
# PRD — Fleet Phase 2: Operator Observability
> **Workstream:** W-FLEET under `mvp-20260312` · **Phase:** 2
> **North star:** [docs/fleet/north-star.md](./north-star.md)
> **North star:** [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md)
> **Source umbrella PRD:** [docs/PRD.md](../PRD.md) (Mosaic Stack v0.1.0)
> **Tracks task:** `fleet-observability-1` — restore operator observability into fleet agent sessions.
docs/fleet/TASKS.md
+16 -1
View File
@@ -1,10 +1,25 @@
# Tasks — W-FLEET (Fleet) Phase 2: Observability
> ---
>
> **STATUS: SUPERSEDED — 2026-08-20.** kind `tracking` · superseded by `docs/fleet/NORTH_STAR.yaml`
>
> This file is the pre-backlog tracking mechanism. `NS-2` in the north star declares the
> replacement: every backlog item is a Mosaic Backlog card projected from the YAML. That
> model replaced this one and nobody retired the old file, so it kept reading as
> authoritative while going stale.
>
> **Do not trust a status in this file.** Verified 2026-08-20: it was already behind the
> code when it froze five weeks ago. The `FLEET-OBS` series was the one thing worth salvaging and
> is now carried as goals `I2`, `I3`, `I6` and `I7` at tier 0.
>
> Kept as a record of what was believed. Do not update it; update the YAML.
> Workstream task file for the Fleet. Single-writer: Fleet workstream lead (orchestrator).
> Workers read but never modify. This is **not** the MVP rollup (`docs/TASKS.md`) — a
> rollup row is proposed to the MVP orchestrator, not written here.
>
> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/north-star.md](./north-star.md)
> Mission: `mvp-20260312` · PRD: [docs/fleet/PRD.md](./PRD.md) · North star: [docs/fleet/FLEET-DOCTRINE.md](./FLEET-DOCTRINE.md)
> Status: `not-started` | `in-progress` | `done` | `blocked` | `failed`
| id | status | description | depends_on | agent | pr | notes |
docs/fleet/f4-matrix-connector.md
+1 -1
View File
@@ -1,6 +1,6 @@
# F4 — Orchestrator chat connector + Matrix (local homeserver)
> **Issue:** #616 · **Doctrine:** `docs/fleet/north-star.md` (#613) — orchestrator-chat-connector decision.
> **Issue:** #616 · **Doctrine:** `docs/fleet/FLEET-DOCTRINE.md` (#613) — orchestrator-chat-connector decision.
> **Status:** Phase 1 (abstraction + scaffold) in this PR; Phase 2+ are follow-ups (below).
## Goal
docs/native-kanban-sot/TASKS.md
+10 -1
View File
@@ -4,7 +4,16 @@
**Tracking:** [Mosaic Stack issue #751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
**Execution:** USC web1 only; collision-free GPT coder2/3/4/5 lanes
**Contract:** `SHARED-CONTRACT.md` + four `contracts/*.v1.ts` files
**Implementation hold:** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
> **HOLD LIFTED — 2026-08-20.** The stated condition ("no feature slice starts until the
> canon PR is merged to `main` with terminal-green CI") was **met on 2026-07-14** by
> `49e8a541` — _docs(#751): Publish native Kanban/SOT canon (#752)_ — which is on both
> `main` and `next`, and `docs/requirements/native-kanban-sot.md` is present on `main`.
> The line below was never updated, so for five weeks this file advertised a blocker that
> did not exist. The status line above ("PUBLICATION IN PROGRESS") is stale for the same
> reason. This file is a build plan, not a task tracker, and is NOT superseded.
**Implementation hold (SATISFIED — see note above):** no feature slice starts until the canon PR is merged to `main` with terminal-green CI; after merge, each slice remains held until every declared KBN prerequisite is complete.
> This publication file is not a runtime task authority. After cutover, repository `TASKS.md` is generated read-only and never imported.
packages/mosaic/framework/fleet/roles/board.md
+1 -1
View File
@@ -35,4 +35,4 @@ A standing panel of senior voices, each arguing from a fixed vantage. The board
deliberately slow and adversarial — its value is catching the expensive mistake
before a single agent-hour is spent on it.
> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` ('board' role = forge BOD; role library).
packages/mosaic/framework/fleet/roles/code.md
+1 -1
View File
@@ -33,4 +33,4 @@ The code role writes the change and opens the PR; it never touches the merge pat
The focused builder. It takes one well-scoped card, drives it to green, opens a
clean PR, and hands off — never reaching past the card it was given.
> Doctrine: `docs/fleet/north-star.md` (role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).
packages/mosaic/framework/fleet/roles/decomposition.md
+1 -1
View File
@@ -35,4 +35,4 @@ The work-breakdown specialist. It takes a phased plan and a DAG and emits a clea
linked set of single-PR cards on the Mosaic backlog — then steps back and lets the
executors run.
> Doctrine: `docs/fleet/north-star.md` (role library); spend accounting is a process mandate.
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); spend accounting is a process mandate.
packages/mosaic/framework/fleet/roles/documentation.md
+1 -1
View File
@@ -36,4 +36,4 @@ The scribe of record. It makes sure the docs and the north star's projections
describe the system as it actually is, and it never lets two writers fight over one
TASKS file.
> Doctrine: `docs/fleet/north-star.md` (role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).
packages/mosaic/framework/fleet/roles/enhancer.md
+1 -1
View File
@@ -38,4 +38,4 @@ The orchestrator alone optimizes for _this_ delivery; the enhancer optimizes for
delivery — self-healing the fleet's tools, skills, and harnesses, and routing real defects
upstream. Together they are the irreducible core; every other role is added on demand.
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).
packages/mosaic/framework/fleet/roles/merge-gate.md
+1 -1
View File
@@ -46,4 +46,4 @@ The single, accountable gatekeeper. It waits for green CI (`pr-ci-wait.sh`),
respects the pause switch, merges only through `pr-merge.sh`, and records every
decision — so the fleet has exactly one trustworthy door to production.
> Doctrine: `docs/fleet/north-star.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.
packages/mosaic/framework/fleet/roles/operator.md
+1 -1
View File
@@ -35,4 +35,4 @@ The on-call dispatcher. It makes sure every escalation is seen and re-seen until
handled, and it holds the one switch that can stop the fleet when something is
wrong.
> Doctrine: `docs/fleet/north-star.md` (role library); pause switch: `fleet/run/PAUSED`.
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); pause switch: `fleet/run/PAUSED`.
packages/mosaic/framework/fleet/roles/orchestrator.md
+1 -1
View File
@@ -43,4 +43,4 @@ A lean, decisive coordinator. It thinks in readiness and throughput, dispatches
next ready card the instant a dependency clears, and never lets an idle agent sit
while ready work exists — keeping its own context minimal so the loop never slows.
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).
packages/mosaic/framework/fleet/roles/planner.md
+1 -1
View File
@@ -38,4 +38,4 @@ The architect of the mission's shape. It thinks in phases and dependencies, hand
a clean DAG to decomposition, and reports its plan back to the orchestrator that
dispatched it.
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (two-agent floor + role library).
packages/mosaic/framework/fleet/roles/rebase.md
+1 -1
View File
@@ -34,4 +34,4 @@ The rebase role keeps PR branches fresh; it never approves or merges.
The janitor of the merge queue. It quietly keeps branches current and re-runnable,
and knows when a conflict is beyond a mechanical rebase and must be escalated.
> Doctrine: `docs/fleet/north-star.md` (role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).
packages/mosaic/framework/fleet/roles/review.md
+1 -1
View File
@@ -35,4 +35,4 @@ The careful reader. It assumes nothing, checks the change against its card and i
tests, and is willing to say "not yet" — its value is catching the wrong change
before it reaches the merge-gate.
> Doctrine: `docs/fleet/north-star.md` (role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).
packages/mosaic/framework/fleet/roles/security-review.md
+1 -1
View File
@@ -36,4 +36,4 @@ tree or the merge path.
The adversary on your side. It reads every diff asking "how does this get exploited
or leak?" — the second, security-focused pair of eyes before the merge-gate.
> Doctrine: `docs/fleet/north-star.md` (role library); forbidden paths: `pr-merge.sh` guard.
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); forbidden paths: `pr-merge.sh` guard.
packages/mosaic/framework/fleet/roles/session-review.md
+1 -1
View File
@@ -34,4 +34,4 @@ The retrospective analyst. It reads completed sessions and distills them into cl
actionable signals — the raw material the enhancer uses to make the fleet better
next time.
> Doctrine: `docs/fleet/north-star.md` (role library); consumed by the enhancer role.
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library); consumed by the enhancer role.
packages/mosaic/framework/fleet/roles/site-tester.md
+1 -1
View File
@@ -34,4 +34,4 @@ merge path.
The skeptic who insists on running it. It trusts observed behavior over claimed
behavior, and turns "should work" into "verified works" — or a concrete bug report.
> Doctrine: `docs/fleet/north-star.md` (role library).
> Doctrine: `docs/fleet/FLEET-DOCTRINE.md` (role library).
packages/mosaic/src/commands/fleet-north-star.spec.ts
+2 -2
View File
@@ -147,11 +147,11 @@ describe('renderNorthStarMarkdown', () => {
'standing_objectives:',
' - { id: NS-1, text: t }',
'success_criteria:',
' - { id: AC-NS-1, text: t }',
' - { id: AC-NS-1, text: t, tier: 0 }',
'workstreams:',
' - { id: A, title: t }',
'goals:',
' - { id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }',
' - { id: A1, title: t, phase: 1, tier: 0, priority: must-have, depends_on: [] }',
'assumptions:',
' - { id: ASM-1, vetoable: true, text: t }',
'spend:',
packages/mosaic/src/commands/fleet.ts
+24 -8
View File
@@ -191,6 +191,10 @@ export interface NorthStarIdText {
text: string;
}
export interface NorthStarCriterion extends NorthStarIdText {
tier: number;
}
export interface NorthStarWorkstream {
id: string;
title: string;
@@ -200,6 +204,8 @@ export interface NorthStarGoal {
id: string;
title: string;
phase: number;
/** Capability tier this goal serves: 0 dogfood, 1 MVP, 2 full vision. Orthogonal to phase, which is build order. */
tier: number;
priority: string;
depends_on: string[];
}
@@ -220,7 +226,7 @@ export interface NorthStar {
mission: string;
substrate: { note: string };
standing_objectives: NorthStarIdText[];
success_criteria: NorthStarIdText[];
success_criteria: NorthStarCriterion[];
workstreams: NorthStarWorkstream[];
goals: NorthStarGoal[];
assumptions: NorthStarAssumption[];
@@ -280,9 +286,13 @@ export function parseNorthStar(rawText: string): NorthStar {
standing_objectives: requireArray(parsed.standing_objectives, 'standing_objectives').map(
(row, i) => idText(row, 'standing_objectives', i),
),
success_criteria: requireArray(parsed.success_criteria, 'success_criteria').map((row, i) =>
idText(row, 'success_criteria', i),
),
success_criteria: requireArray(parsed.success_criteria, 'success_criteria').map((row, i) => {
const tier = (row as Record<string, unknown>)?.tier;
if (typeof tier !== 'number') {
throw new Error(`NORTH_STAR.yaml: success_criteria[${i}].tier must be a number.`);
}
return { ...idText(row, 'success_criteria', i), tier };
}),
workstreams: requireArray(parsed.workstreams, 'workstreams').map((row, i) => {
const ws = row as Record<string, unknown>;
return {
@@ -300,10 +310,15 @@ export function parseNorthStar(rawText: string): NorthStar {
if (typeof phase !== 'number') {
throw new Error(`NORTH_STAR.yaml: goals[${i}].phase must be a number.`);
}
const tier = goal?.tier;
if (typeof tier !== 'number') {
throw new Error(`NORTH_STAR.yaml: goals[${i}].tier must be a number.`);
}
return {
id: requireString(goal?.id, `goals[${i}].id`),
title: requireString(goal?.title, `goals[${i}].title`),
phase,
tier,
priority: requireString(goal?.priority, `goals[${i}].priority`),
depends_on: dependsRaw.map((dep, j) => requireString(dep, `goals[${i}].depends_on[${j}]`)),
};
@@ -349,7 +364,7 @@ function renderMarkdownTable(headers: string[], rows: string[][]): string[] {
* Pure function of its input — same input always yields byte-identical output,
* so the round-trip (YAML → render → write) is stable across runs. No clock, no
* network, no CLI. Layout follows the repo's existing doctrine-doc convention
* (heading, blockquote banner, then sections + tables, e.g. north-star.md /
* (heading, blockquote banner, then sections + tables, e.g. FLEET-DOCTRINE.md /
* mission-control/BOARD.md).
*/
export function renderNorthStarMarkdown(ns: NorthStar): string {
@@ -362,7 +377,7 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
'> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure',
);
lines.push('> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).');
lines.push('> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.');
lines.push('> Edit the YAML, then regenerate. Self-contained Mosaic.');
lines.push('');
lines.push('## Mission');
@@ -385,7 +400,7 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
lines.push('## Success criteria');
lines.push('');
for (const ac of ns.success_criteria) {
lines.push(`- **${ac.id}** — ${ac.text}`);
lines.push(`- **${ac.id}** (tier ${ac.tier}) — ${ac.text}`);
}
lines.push('');
@@ -403,10 +418,11 @@ export function renderNorthStarMarkdown(ns: NorthStar): string {
lines.push('');
lines.push(
...renderMarkdownTable(
['id', 'title', 'phase', 'priority', 'depends_on'],
['id', 'title', 'tier', 'phase', 'priority', 'depends_on'],
ns.goals.map((goal) => [
goal.id,
goal.title,
String(goal.tier),
String(goal.phase),
goal.priority,
goal.depends_on.length > 0 ? goal.depends_on.join(', ') : '—',
packages/mosaic/src/fleet/fleet-documentation.spec.ts
+2 -2
View File
@@ -922,8 +922,8 @@ describe('fleet operator documentation', (): void => {
);
expect(
surfaces.filter((surface): boolean => surface.category === 'InlineLiteral'),
).toHaveLength(863);
expect(surfaces).toHaveLength(887);
).toHaveLength(882);
expect(surfaces).toHaveLength(906);
const rosterSource = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
const auxiliary: CodeSurface = {