Compare commits
1 Commits
release/mo
...
feat/h1-pe
| Author | SHA1 | Date | |
|---|---|---|---|
|
7533a615b1 |
@@ -7,7 +7,7 @@
|
|||||||
|
|
||||||
## Mission
|
## 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.
|
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
|
## Substrate
|
||||||
|
|
||||||
@@ -23,7 +23,6 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
|
|||||||
- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
|
- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
|
||||||
- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
|
- **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-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.
|
|
||||||
|
|
||||||
## Success criteria
|
## Success criteria
|
||||||
|
|
||||||
@@ -32,46 +31,38 @@ The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's
|
|||||||
- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
|
- **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-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-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.
|
|
||||||
|
|
||||||
## Workstreams
|
## Workstreams
|
||||||
|
|
||||||
| id | title |
|
| id | title |
|
||||||
| --- | ----------------------------------------------------------------------------------------------------------- |
|
| --- | ---------------------------------------------------------------- |
|
||||||
| A | Substrate — Mosaic Backlog on native Postgres storage service |
|
| A | Substrate — Mosaic Backlog on native Postgres storage service |
|
||||||
| B | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
|
| B | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
|
||||||
| C | Planner — goal decomposition into independently-shippable cards |
|
| C | Planner — goal decomposition into independently-shippable cards |
|
||||||
| D | Merge-gate — single approver, pr-merge.sh after CI wait |
|
| D | Merge-gate — single approver, pr-merge.sh after CI wait |
|
||||||
| E | Meta-loop — session-review + enhancer improvement PRs |
|
| E | Meta-loop — session-review + enhancer improvement PRs |
|
||||||
| F | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch |
|
| F | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch |
|
||||||
| H | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
|
|
||||||
|
|
||||||
## Goals (backlog projection)
|
## Goals (backlog projection)
|
||||||
|
|
||||||
| id | title | phase | priority | depends_on |
|
| id | title | phase | priority | depends_on |
|
||||||
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
|
| --- | ---------------------------------------------------------------------- | ----- | ----------- | ---------- |
|
||||||
| A1 | Machine-readable NORTH_STAR.yaml + Markdown projection | 1 | must-have | — |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
|
||||||
|
|
||||||
## Assumptions (vetoable)
|
## Assumptions (vetoable)
|
||||||
|
|
||||||
- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
|
- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
|
||||||
- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
|
- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
|
||||||
- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
|
- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
|
||||||
- **ASM-4** (vetoable) — 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
|
## Spend
|
||||||
|
|
||||||
|
|||||||
@@ -12,13 +12,10 @@
|
|||||||
version: 1
|
version: 1
|
||||||
|
|
||||||
mission: >-
|
mission: >-
|
||||||
A self-driving Mosaic system that 24/7 unattended converts a machine-readable
|
A self-driving Mosaic delivery fleet that 24/7 unattended converts a
|
||||||
goal set into merged, CI-green, budget-bounded change — looping
|
machine-readable goal set into merged, CI-green, budget-bounded change —
|
||||||
plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native
|
looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN
|
||||||
backlog/dispatch engine. Mosaic is general-purpose: the user declares the
|
native backlog/dispatch engine.
|
||||||
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:
|
substrate:
|
||||||
note: >-
|
note: >-
|
||||||
@@ -62,13 +59,6 @@ standing_objectives:
|
|||||||
text: >-
|
text: >-
|
||||||
Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
|
Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
|
||||||
before every dispatch and every merge.
|
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:
|
success_criteria:
|
||||||
- id: AC-NS-1
|
- id: AC-NS-1
|
||||||
@@ -90,14 +80,6 @@ success_criteria:
|
|||||||
- id: AC-NS-5
|
- id: AC-NS-5
|
||||||
text: >-
|
text: >-
|
||||||
Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
|
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:
|
workstreams:
|
||||||
- id: A
|
- id: A
|
||||||
@@ -112,8 +94,6 @@ workstreams:
|
|||||||
title: Meta-loop — session-review + enhancer improvement PRs
|
title: Meta-loop — session-review + enhancer improvement PRs
|
||||||
- id: F
|
- id: F
|
||||||
title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
|
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:
|
goals:
|
||||||
- id: A1
|
- id: A1
|
||||||
@@ -166,26 +146,6 @@ goals:
|
|||||||
phase: 2
|
phase: 2
|
||||||
priority: must-have
|
priority: must-have
|
||||||
depends_on: [B2]
|
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:
|
assumptions:
|
||||||
- id: ASM-1
|
- id: ASM-1
|
||||||
@@ -201,12 +161,6 @@ assumptions:
|
|||||||
- id: ASM-3
|
- id: ASM-3
|
||||||
vetoable: true
|
vetoable: true
|
||||||
text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
|
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:
|
spend:
|
||||||
advisory: true
|
advisory: true
|
||||||
|
|||||||
@@ -353,25 +353,6 @@ re-evaluate if isolation or write-volume demands it.
|
|||||||
- **Docs as projections:** `docs/TASKS.md` and `MISSION-MANIFEST.md` become generated exports of the DB, not hand-maintained.
|
- **Docs as projections:** `docs/TASKS.md` and `MISSION-MANIFEST.md` become generated exports of the DB, not hand-maintained.
|
||||||
- **Sub-decision pending:** dedicated schema in existing PG instance (recommended) vs. dedicated PG instance. Revisit if isolation or write-volume demands it.
|
- **Sub-decision pending:** dedicated schema in existing PG instance (recommended) vs. dedicated PG instance. Revisit if isolation or write-volume demands it.
|
||||||
|
|
||||||
## Decisions of record (2026-06-24, with Jason)
|
|
||||||
|
|
||||||
- **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
|
|
||||||
**per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
|
|
||||||
`~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
|
|
||||||
roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
|
|
||||||
agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
|
|
||||||
**North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
|
|
||||||
per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
|
|
||||||
that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
|
|
||||||
downgrade ladder (opus → sonnet → haiku, then Claude → Codex): the operator sets the per-agent model
|
|
||||||
_intent/ceiling_; budget pacing may downgrade within policy. Tracked as a Fleet `TASKS.md` entry under
|
|
||||||
the Phase-5 webUI surface.
|
|
||||||
- **Orchestrator runtime (confirmed live):** the **orchestrator and enhancer run Claude Opus 4.8 in the
|
|
||||||
Claude Code harness**; only workers (coder/reviewer) run pi/gpt-5.5. Consistent with the 2026-06-20
|
|
||||||
"Claude reserved for Claude Code only" decision (the orchestrator runs _in_ Claude Code, not an
|
|
||||||
alternate Claude harness). Pi/gpt-5.5 as the orchestrator is permitted **only if proven** at least as
|
|
||||||
satisfactory; absent that proof, the orchestrator stays on Claude Opus 4.8.
|
|
||||||
|
|
||||||
## Future enhancements (north-star, post-MVP — not on the MVP track)
|
## Future enhancements (north-star, post-MVP — not on the MVP track)
|
||||||
|
|
||||||
- **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
|
- **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "@mosaicstack/db",
|
"name": "@mosaicstack/db",
|
||||||
"version": "0.0.4",
|
"version": "0.0.3",
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||||
|
|||||||
@@ -1,30 +0,0 @@
|
|||||||
id: business
|
|
||||||
title: Business (Company-in-a-Box)
|
|
||||||
description: >-
|
|
||||||
A full company org: the CEO sets direction, the COO and CFO run execution and
|
|
||||||
finance, and the functional leads (product, marketing, sales, operations,
|
|
||||||
customer success) plus a small engineering slice deliver the work. reports_to
|
|
||||||
encodes the org chart.
|
|
||||||
lead: ceo
|
|
||||||
floor:
|
|
||||||
- ceo
|
|
||||||
roster:
|
|
||||||
- class: ceo
|
|
||||||
- class: coo
|
|
||||||
reports_to: ceo
|
|
||||||
- class: cfo
|
|
||||||
reports_to: ceo
|
|
||||||
- class: product-manager
|
|
||||||
reports_to: coo
|
|
||||||
- class: marketing-lead
|
|
||||||
reports_to: coo
|
|
||||||
- class: sales-lead
|
|
||||||
reports_to: coo
|
|
||||||
- class: operations-manager
|
|
||||||
reports_to: coo
|
|
||||||
- class: customer-success-manager
|
|
||||||
reports_to: coo
|
|
||||||
- class: code
|
|
||||||
reports_to: product-manager
|
|
||||||
- class: review
|
|
||||||
reports_to: product-manager
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
id: marketing
|
|
||||||
title: Marketing
|
|
||||||
description: >-
|
|
||||||
A marketing org that owns strategy, content, channels, and growth. The
|
|
||||||
marketing-lead sets strategy and budget and runs a roster of content, copy,
|
|
||||||
SEO, social, brand, growth, and UX specialists.
|
|
||||||
lead: marketing-lead
|
|
||||||
floor:
|
|
||||||
- marketing-lead
|
|
||||||
roster:
|
|
||||||
- class: marketing-lead
|
|
||||||
- class: content-strategist
|
|
||||||
reports_to: marketing-lead
|
|
||||||
- class: copywriter
|
|
||||||
reports_to: content-strategist
|
|
||||||
- class: seo-specialist
|
|
||||||
reports_to: marketing-lead
|
|
||||||
- class: social-media-manager
|
|
||||||
reports_to: content-strategist
|
|
||||||
- class: brand-strategist
|
|
||||||
reports_to: marketing-lead
|
|
||||||
- class: growth-marketer
|
|
||||||
reports_to: marketing-lead
|
|
||||||
- class: ux-designer
|
|
||||||
reports_to: marketing-lead
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
id: personal-assistant
|
|
||||||
title: Personal Assistant
|
|
||||||
description: >-
|
|
||||||
A personal-logistics fleet for one principal: handles errands, reminders,
|
|
||||||
calendar, inbox triage, and ad-hoc lookups. The personal-assistant leads and
|
|
||||||
delegates scheduling, inbox triage, and research to specialist seats.
|
|
||||||
lead: personal-assistant
|
|
||||||
floor:
|
|
||||||
- personal-assistant
|
|
||||||
roster:
|
|
||||||
- class: personal-assistant
|
|
||||||
- class: executive-assistant
|
|
||||||
reports_to: personal-assistant
|
|
||||||
- class: scheduler
|
|
||||||
reports_to: executive-assistant
|
|
||||||
- class: inbox-manager
|
|
||||||
reports_to: personal-assistant
|
|
||||||
- class: researcher
|
|
||||||
reports_to: personal-assistant
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
id: research
|
|
||||||
title: Research
|
|
||||||
description: >-
|
|
||||||
A research fleet that decomposes a question, gathers and analyzes evidence, and
|
|
||||||
synthesizes cited findings. The lead-researcher owns the agenda and assigns
|
|
||||||
individual questions to researchers and the analytics seats.
|
|
||||||
lead: lead-researcher
|
|
||||||
floor:
|
|
||||||
- lead-researcher
|
|
||||||
roster:
|
|
||||||
- class: lead-researcher
|
|
||||||
- class: researcher
|
|
||||||
reports_to: lead-researcher
|
|
||||||
multiplicity: 2
|
|
||||||
- class: data-analyst
|
|
||||||
reports_to: lead-researcher
|
|
||||||
- class: data-scientist
|
|
||||||
reports_to: lead-researcher
|
|
||||||
- class: market-analyst
|
|
||||||
reports_to: lead-researcher
|
|
||||||
- class: documentation
|
|
||||||
reports_to: lead-researcher
|
|
||||||
- class: review
|
|
||||||
reports_to: lead-researcher
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
# Mosaic system-type profile — SCHEMA REFERENCE
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
# A profile is a DECLARATIVE mapping from a "system type" to a persona roster
|
|
||||||
# plus its org topology. Profiles are DATA: drop a new <id>.yaml here and the
|
|
||||||
# loader/CLI pick it up with no code change (North Star NS-9 / AC-NS-6).
|
|
||||||
#
|
|
||||||
# Every persona referenced below (lead, floor[], roster[].class, roster[].reports_to)
|
|
||||||
# MUST resolve to a real persona in the library. The loader validates this against
|
|
||||||
# the role contracts in ../roles/*.md (see LIBRARY.md for the grouped index).
|
|
||||||
#
|
|
||||||
# Schema (this file documents every key; other profiles omit the comments):
|
|
||||||
#
|
|
||||||
# id: kebab-case system-type id — MUST equal the filename stem.
|
|
||||||
# title: human-readable name.
|
|
||||||
# description: one paragraph — what this system does.
|
|
||||||
# lead: persona class that coordinates the roster (the orchestrating seat).
|
|
||||||
# floor: persistent minimum roster that must stay staffed (list of classes).
|
|
||||||
# roster: the full default roster. Each entry:
|
|
||||||
# - class: persona class (MUST resolve to a role file).
|
|
||||||
# reports_to: optional — the class this seat reports to
|
|
||||||
# (encodes org topology). Omit for the lead.
|
|
||||||
# MUST resolve to a class present in this roster.
|
|
||||||
# multiplicity: optional int (default 1) — e.g. 2 coders.
|
|
||||||
# notes: optional free text.
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
id: software-delivery
|
|
||||||
title: Software Delivery
|
|
||||||
description: >-
|
|
||||||
The engineering fleet that turns ratified objectives into shipped, reviewed,
|
|
||||||
merged code. The lead (orchestrator) runs the supervisor loop and dispatches
|
|
||||||
ready work; it hands goal-decomposition to the planner, which plans phased FRs
|
|
||||||
into a depends_on DAG, decomposition splits them into one-PR-each cards, coders
|
|
||||||
execute to green CI, and review / security-review / site-tester / merge-gate
|
|
||||||
guard the merge. This mirrors today's coding fleet.
|
|
||||||
# NOTE: the lead seat is the dedicated "orchestrator" — the always-on coordinator
|
|
||||||
# that runs the supervisor tick, dispatches ready work, and routes PRs to the
|
|
||||||
# merge-gate while holding only lean coordination state. The planner is now a
|
|
||||||
# distinct seat (heavy goal-decomposition context) that reports to the
|
|
||||||
# orchestrator. The two-agent floor is orchestrator + enhancer.
|
|
||||||
lead: orchestrator
|
|
||||||
floor:
|
|
||||||
- orchestrator
|
|
||||||
- enhancer
|
|
||||||
roster:
|
|
||||||
- class: orchestrator
|
|
||||||
- class: board
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: planner
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: decomposition
|
|
||||||
reports_to: planner
|
|
||||||
- class: code
|
|
||||||
reports_to: decomposition
|
|
||||||
multiplicity: 2
|
|
||||||
- class: review
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: security-review
|
|
||||||
reports_to: review
|
|
||||||
- class: site-tester
|
|
||||||
reports_to: review
|
|
||||||
- class: documentation
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: merge-gate
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: rebase
|
|
||||||
reports_to: merge-gate
|
|
||||||
- class: operator
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: session-review
|
|
||||||
reports_to: orchestrator
|
|
||||||
- class: enhancer
|
|
||||||
reports_to: orchestrator
|
|
||||||
notes: >-
|
|
||||||
Two-agent floor (orchestrator + enhancer) is always staffed; every other seat is
|
|
||||||
added on demand.
|
|
||||||
@@ -19,7 +19,6 @@ their intro so tooling can group them.
|
|||||||
|
|
||||||
| Persona | Purpose |
|
| Persona | Purpose |
|
||||||
| --------------- | ------------------------------------------------------------------------------ |
|
| --------------- | ------------------------------------------------------------------------------ |
|
||||||
| orchestrator | Always-on coordinator — runs the supervisor loop, dispatches ready work |
|
|
||||||
| board | Multi-lens deliberation panel; owns the mission's direction, not its execution |
|
| board | Multi-lens deliberation panel; owns the mission's direction, not its execution |
|
||||||
| planner | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG |
|
| planner | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG |
|
||||||
| decomposition | Splits FRs into one-PR-each cards wired with `depends_on` edges |
|
| decomposition | Splits FRs into one-PR-each cards wired with `depends_on` edges |
|
||||||
|
|||||||
@@ -1,46 +0,0 @@
|
|||||||
# Orchestrator — fleet role definition
|
|
||||||
|
|
||||||
The **orchestrator** is one half of the fleet's two-agent floor: every fleet runs,
|
|
||||||
at minimum, an **orchestrator** and an **enhancer**. The orchestrator is the
|
|
||||||
fleet's **always-on coordinator and dispatcher** (`class: orchestrator`,
|
|
||||||
`persistent_persona: true`) — it owns fleet _movement_, not the work itself.
|
|
||||||
|
|
||||||
It is a **core, always-on** agent, not an ephemeral per-lane worker.
|
|
||||||
|
|
||||||
## Mandate
|
|
||||||
|
|
||||||
1. **Run the supervisor tick** — perform the readiness scan each loop and keep the
|
|
||||||
two-agent floor (orchestrator + enhancer) healthy, restoring it the moment it
|
|
||||||
drops below the floor.
|
|
||||||
2. **Dispatch ready work** — pick up cards whose `depends_on` edges are satisfied
|
|
||||||
and assign them via the backlog/claim, so no idle agent sits while ready work
|
|
||||||
exists.
|
|
||||||
3. **Delegate decomposition, don't do it** — hand goal-decomposition work to the
|
|
||||||
**planner**, which it coordinates; the orchestrator tracks the resulting plan
|
|
||||||
but does not author the DAG itself.
|
|
||||||
4. **Route PRs to the merge-gate** — push reviewed, ready-to-land PRs at the
|
|
||||||
**merge-gate** (the only merge path); it never approves or merges itself.
|
|
||||||
5. **Interface with the operator/user** — be the fleet's coordination surface,
|
|
||||||
relaying status and accepting direction, while holding only coordination state.
|
|
||||||
6. **Keep the loop turning** — re-dispatch on completion or failure so the fleet
|
|
||||||
keeps moving rather than stalling.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
- **Does NOT decompose goals into the DAG/cards** — that is the **planner**'s lane,
|
|
||||||
which the orchestrator dispatches to.
|
|
||||||
- **Does NOT write product/source code** (coders), **review** (review), or
|
|
||||||
**approve merges itself** (merge-gate).
|
|
||||||
- **Does NOT carry deep per-task context** — it delegates and tracks, keeping its
|
|
||||||
own context lean so the coordination loop stays fast.
|
|
||||||
|
|
||||||
The orchestrator moves work; it never holds the heavy planning or execution
|
|
||||||
context that the seats it dispatches to carry.
|
|
||||||
|
|
||||||
## Persona
|
|
||||||
|
|
||||||
A lean, decisive coordinator. It thinks in readiness and throughput, dispatches the
|
|
||||||
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).
|
|
||||||
@@ -3,11 +3,11 @@
|
|||||||
The **planner** turns ratified objectives into an executable **plan** — phased
|
The **planner** turns ratified objectives into an executable **plan** — phased
|
||||||
functional requirements (FRs) wired into a `depends_on` DAG.
|
functional requirements (FRs) wired into a `depends_on` DAG.
|
||||||
|
|
||||||
> **Reports to the orchestrator.** The planner is the goal-decomposition seat that
|
> **Alias:** the planner role IS the existing **orchestrator** class. The
|
||||||
> the **orchestrator** dispatches planning work to; it carries the heavy
|
> orchestrator _plays_ planner; this file documents the planning contract, it does
|
||||||
> goal-decomposition context, while the orchestrator holds only the lean
|
> **not** introduce a competing class. The two-agent floor (orchestrator +
|
||||||
> coordination state. The two-agent floor is **orchestrator + enhancer** — the
|
> enhancer) is preserved — do not split planner into a separate persistent agent
|
||||||
> planner is added on demand, not part of the floor.
|
> that would break it.
|
||||||
|
|
||||||
It is a **front-office** role.
|
It is a **front-office** role.
|
||||||
|
|
||||||
@@ -19,8 +19,8 @@ It is a **front-office** role.
|
|||||||
between FRs so downstream decomposition can parallelize safely.
|
between FRs so downstream decomposition can parallelize safely.
|
||||||
3. **Emit a plan, not tasks** — the planner's output is the phased FR/DAG
|
3. **Emit a plan, not tasks** — the planner's output is the phased FR/DAG
|
||||||
document. Splitting FRs into one-PR-each cards is the **decomposition** role's job.
|
document. Splitting FRs into one-PR-each cards is the **decomposition** role's job.
|
||||||
4. **Re-plan on failure** — when execution diverges, the planner re-sequences the
|
4. **Re-plan on failure** — when execution diverges, the planner (orchestrator)
|
||||||
DAG rather than letting agents improvise.
|
re-sequences the DAG rather than letting agents improvise.
|
||||||
|
|
||||||
## Boundaries
|
## Boundaries
|
||||||
|
|
||||||
@@ -35,7 +35,6 @@ merge path.
|
|||||||
## Persona
|
## Persona
|
||||||
|
|
||||||
The architect of the mission's shape. It thinks in phases and dependencies, hands
|
The architect of the mission's shape. It thinks in phases and dependencies, hands
|
||||||
a clean DAG to decomposition, and reports its plan back to the orchestrator that
|
a clean DAG to decomposition, and keeps the orchestrator/enhancer floor intact.
|
||||||
dispatched it.
|
|
||||||
|
|
||||||
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
|
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
|
||||||
|
|||||||
@@ -24,11 +24,9 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
|
|||||||
# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
|
# reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
|
||||||
# User-created content in these paths survives rsync --delete.
|
# User-created content in these paths survives rsync --delete.
|
||||||
#
|
#
|
||||||
# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, and
|
# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
|
||||||
# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
|
# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
|
||||||
# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
|
# lands automatically via this sync, so no per-file entry is needed). The user's
|
||||||
# so no per-file entry is needed; the preserved "fleet/*.yaml" glob is anchored to
|
|
||||||
# the top level only and does NOT shadow fleet/profiles/*.yaml). The user's
|
|
||||||
# own fleet files MUST
|
# own fleet files MUST
|
||||||
# survive `mosaic update` (which runs this sync automatically): the active
|
# survive `mosaic update` (which runs this sync automatically): the active
|
||||||
# roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
|
# roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
|
||||||
@@ -37,14 +35,7 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
|
|||||||
# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
|
# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
|
||||||
# wipes the operator's fleet AND their backlog. Glob entries are honored by
|
# wipes the operator's fleet AND their backlog. Glob entries are honored by
|
||||||
# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
|
# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
|
||||||
#
|
PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog")
|
||||||
# fleet/roles.local — the persona OVERRIDE layer (H4). Baseline personas in
|
|
||||||
# fleet/roles/ are reseeded normally on every update (delivering new baseline
|
|
||||||
# personas), so any local edit there would be clobbered. User customizations
|
|
||||||
# and user-ADDED personas instead live in fleet/roles.local/ and MUST survive
|
|
||||||
# `mosaic update` — they win over the baseline on merge (AC-NS-7; see
|
|
||||||
# packages/mosaic/src/commands/fleet-personas.ts).
|
|
||||||
PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog" "fleet/roles.local")
|
|
||||||
|
|
||||||
# Framework-owned contract files: re-copied from defaults/ on every upgrade (the
|
# Framework-owned contract files: re-copied from defaults/ on every upgrade (the
|
||||||
# user must not edit them; a divergent copy is backed up once before overwrite).
|
# user must not edit them; a divergent copy is backed up once before overwrite).
|
||||||
|
|||||||
@@ -114,21 +114,10 @@ MOSAIC_RUNTIME_BIN_PREFIX=$(_build_runtime_bin_prefix)
|
|||||||
# safe single bash token regardless of the name's characters.
|
# safe single bash token regardless of the name's characters.
|
||||||
AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
|
AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
|
||||||
|
|
||||||
# MOSAIC_AGENT_CLASS must ALSO be exported INTO the pane, for the same reason as
|
|
||||||
# MOSAIC_AGENT_NAME above: the pane inherits the tmux SERVER environment (not this
|
|
||||||
# script's env, and not the systemd unit's EnvironmentFile), so the per-agent class
|
|
||||||
# written to agents/<name>.env would otherwise be invisible in-pane. The launcher
|
|
||||||
# composes the persona contract from process.env.MOSAIC_AGENT_CLASS at launch
|
|
||||||
# (compose-contract -> readPersonaContractBlock); without this export it sees an
|
|
||||||
# undefined class and silently injects NO persona contract. %q-quote it so it is a
|
|
||||||
# safe single bash token; an empty/unset class %q-quotes to '' and is a harmless
|
|
||||||
# no-op downstream (readPersonaContractBlock returns '' for an empty class).
|
|
||||||
AGENT_CLASS_Q=$(printf '%q' "${MOSAIC_AGENT_CLASS:-}")
|
|
||||||
|
|
||||||
if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
|
if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
|
||||||
PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
|
PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
|
||||||
else
|
else
|
||||||
PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; exec ${MOSAIC_AGENT_COMMAND}"
|
PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; exec ${MOSAIC_AGENT_COMMAND}"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
mkdir -p "$MOSAIC_AGENT_WORKDIR"
|
mkdir -p "$MOSAIC_AGENT_WORKDIR"
|
||||||
|
|||||||
@@ -104,7 +104,6 @@ PATH="$FAKE_BIN:$PATH" \
|
|||||||
MOSAIC_TMUX_SOCKET="$SOCKET3" \
|
MOSAIC_TMUX_SOCKET="$SOCKET3" \
|
||||||
MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
|
MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
|
||||||
MOSAIC_AGENT_RUNTIME="pi" \
|
MOSAIC_AGENT_RUNTIME="pi" \
|
||||||
MOSAIC_AGENT_CLASS="code" \
|
|
||||||
MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
|
MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
|
||||||
MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
|
MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
|
||||||
MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
|
MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
|
||||||
@@ -128,18 +127,6 @@ echo "$all_args" | grep -qF "exec " || fail "pane command does not use exec"
|
|||||||
echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
|
echo "$all_args" | grep -qF "mosaic yolo pi --model openai-codex/gpt-5.5:high" || \
|
||||||
fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
|
fail "pane command does not forward MOSAIC_AGENT_COMMAND with flags intact"
|
||||||
|
|
||||||
# d) MOSAIC_AGENT_NAME and the per-agent MOSAIC_AGENT_CLASS must BOTH be exported
|
|
||||||
# INTO the pane. The pane inherits the tmux SERVER environment (not this
|
|
||||||
# script's env, nor the systemd unit's EnvironmentFile), so any per-agent var
|
|
||||||
# the launcher needs in-pane must be re-exported in the snippet. CLASS is
|
|
||||||
# load-bearing: the launcher composes the persona contract from
|
|
||||||
# process.env.MOSAIC_AGENT_CLASS, so a missing export silently drops the
|
|
||||||
# persona (regression guard for the A3a pane-propagation gap).
|
|
||||||
echo "$all_args" | grep -qF "export MOSAIC_AGENT_NAME=" || \
|
|
||||||
fail "pane command does not export MOSAIC_AGENT_NAME into the pane"
|
|
||||||
echo "$all_args" | grep -qF "export MOSAIC_AGENT_CLASS=code" || \
|
|
||||||
fail "pane command does not export MOSAIC_AGENT_CLASS into the pane (persona would silently drop)"
|
|
||||||
|
|
||||||
# ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
|
# ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
|
||||||
TMUX_ARGS_FILE2=$(mktemp)
|
TMUX_ARGS_FILE2=$(mktemp)
|
||||||
FAKE_BIN2=$(mktemp -d)
|
FAKE_BIN2=$(mktemp -d)
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "@mosaicstack/mosaic",
|
"name": "@mosaicstack/mosaic",
|
||||||
"version": "0.0.48",
|
"version": "0.0.45",
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||||
|
|||||||
@@ -164,89 +164,4 @@ describe('composeContract — overlay composer', () => {
|
|||||||
expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
|
expect(composeContract('pi', fixture.home)).toContain('# pi runtime contract');
|
||||||
expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
|
expect(composeContract('codex', fixture.home)).not.toContain('# pi runtime contract');
|
||||||
});
|
});
|
||||||
|
|
||||||
// ── Persona contract injection (A3b) ──────────────────────────────────────
|
|
||||||
// composeContract reads MOSAIC_AGENT_CLASS and injects the resolved persona
|
|
||||||
// (override-aware). Save/restore the env so these tests don't leak state.
|
|
||||||
describe('persona contract (A3b)', () => {
|
|
||||||
let prevClass: string | undefined;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
prevClass = process.env['MOSAIC_AGENT_CLASS'];
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => {
|
|
||||||
if (prevClass === undefined) delete process.env['MOSAIC_AGENT_CLASS'];
|
|
||||||
else process.env['MOSAIC_AGENT_CLASS'] = prevClass;
|
|
||||||
});
|
|
||||||
|
|
||||||
const seedBaseline = (klass: string, body: string): void => {
|
|
||||||
mkdirSync(join(fixture.home, 'fleet', 'roles'), { recursive: true });
|
|
||||||
writeFileSync(join(fixture.home, 'fleet', 'roles', `${klass}.md`), body);
|
|
||||||
};
|
|
||||||
const seedOverride = (klass: string, body: string): void => {
|
|
||||||
mkdirSync(join(fixture.home, 'fleet', 'roles.local'), { recursive: true });
|
|
||||||
writeFileSync(join(fixture.home, 'fleet', 'roles.local', `${klass}.md`), body);
|
|
||||||
};
|
|
||||||
|
|
||||||
it('injects the baseline persona when MOSAIC_AGENT_CLASS is set and a role file exists', () => {
|
|
||||||
seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE: ship the lane.\n');
|
|
||||||
process.env['MOSAIC_AGENT_CLASS'] = 'coder';
|
|
||||||
const out = composeContract('claude', fixture.home);
|
|
||||||
expect(out).toContain('# Persona Contract (coder)');
|
|
||||||
expect(out).toContain('BASELINE-MANDATE');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('OVERRIDE WINS at launch: roles.local persona is injected over baseline (AC-NS-7)', () => {
|
|
||||||
seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
|
|
||||||
seedOverride('coder', '# Coder (override)\n\n(`class: coder`)\n\nOVERRIDE-MANDATE.\n');
|
|
||||||
process.env['MOSAIC_AGENT_CLASS'] = 'coder';
|
|
||||||
const out = composeContract('claude', fixture.home);
|
|
||||||
expect(out).toContain('# Persona Contract (coder)');
|
|
||||||
expect(out).toContain('OVERRIDE-MANDATE');
|
|
||||||
expect(out).not.toContain('BASELINE-MANDATE');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('does NOT inject a persona when MOSAIC_AGENT_CLASS is unset', () => {
|
|
||||||
seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
|
|
||||||
delete process.env['MOSAIC_AGENT_CLASS'];
|
|
||||||
const out = composeContract('claude', fixture.home);
|
|
||||||
expect(out).not.toContain('# Persona Contract');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('does NOT inject (no throw) when MOSAIC_AGENT_CLASS names an unknown class', () => {
|
|
||||||
seedBaseline('coder', '# Coder\n\n(`class: coder`)\n\nBASELINE-MANDATE.\n');
|
|
||||||
process.env['MOSAIC_AGENT_CLASS'] = 'nonexistent';
|
|
||||||
expect(() => composeContract('claude', fixture.home)).not.toThrow();
|
|
||||||
expect(composeContract('claude', fixture.home)).not.toContain('# Persona Contract');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('places the persona contract BEFORE the fleet comms block (identity, then peers)', () => {
|
|
||||||
seedBaseline('enhancer', '# Enhancer\n\n(`class: enhancer`)\n\nIMPROVE.\n');
|
|
||||||
mkdirSync(join(fixture.home, 'fleet'), { recursive: true });
|
|
||||||
writeFileSync(
|
|
||||||
join(fixture.home, 'fleet', 'roster.yaml'),
|
|
||||||
[
|
|
||||||
'agents:',
|
|
||||||
' - name: orchestrator',
|
|
||||||
' class: orchestrator',
|
|
||||||
' - name: enhancer',
|
|
||||||
' class: enhancer',
|
|
||||||
'',
|
|
||||||
].join('\n'),
|
|
||||||
);
|
|
||||||
const prevName = process.env['MOSAIC_AGENT_NAME'];
|
|
||||||
try {
|
|
||||||
process.env['MOSAIC_AGENT_CLASS'] = 'enhancer';
|
|
||||||
process.env['MOSAIC_AGENT_NAME'] = 'enhancer';
|
|
||||||
const out = composeContract('claude', fixture.home);
|
|
||||||
expect(out).toContain('# Persona Contract (enhancer)');
|
|
||||||
expect(out).toContain('# Fleet Comms');
|
|
||||||
expect(out.indexOf('# Persona Contract')).toBeLessThan(out.indexOf('# Fleet Comms'));
|
|
||||||
} finally {
|
|
||||||
if (prevName === undefined) delete process.env['MOSAIC_AGENT_NAME'];
|
|
||||||
else process.env['MOSAIC_AGENT_NAME'] = prevName;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -25,8 +25,7 @@ describe('NORTH_STAR.yaml', () => {
|
|||||||
it('parses to a typed object with the required top-level keys', async () => {
|
it('parses to a typed object with the required top-level keys', async () => {
|
||||||
const ns = await loadParsed();
|
const ns = await loadParsed();
|
||||||
expect(ns.version).toBeTypeOf('number');
|
expect(ns.version).toBeTypeOf('number');
|
||||||
expect(ns.mission).toContain('self-driving Mosaic system');
|
expect(ns.mission).toContain('self-driving Mosaic delivery fleet');
|
||||||
expect(ns.mission).toContain('Mosaic is general-purpose');
|
|
||||||
expect(ns.substrate.note).toBeTruthy();
|
expect(ns.substrate.note).toBeTruthy();
|
||||||
expect(ns.standing_objectives.length).toBeGreaterThan(0);
|
expect(ns.standing_objectives.length).toBeGreaterThan(0);
|
||||||
expect(ns.success_criteria.length).toBeGreaterThan(0);
|
expect(ns.success_criteria.length).toBeGreaterThan(0);
|
||||||
|
|||||||
@@ -1,210 +0,0 @@
|
|||||||
import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
|
|
||||||
import { tmpdir } from 'node:os';
|
|
||||||
import { dirname, join, resolve } from 'node:path';
|
|
||||||
import { fileURLToPath } from 'node:url';
|
|
||||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
|
||||||
import {
|
|
||||||
extractClassesFromDir,
|
|
||||||
listPersonaClasses,
|
|
||||||
personaStatus,
|
|
||||||
resolvePersona,
|
|
||||||
} from './fleet-personas.js';
|
|
||||||
import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';
|
|
||||||
|
|
||||||
// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
|
|
||||||
const frameworkFleet = resolve(
|
|
||||||
dirname(fileURLToPath(import.meta.url)),
|
|
||||||
'..',
|
|
||||||
'..',
|
|
||||||
'framework',
|
|
||||||
'fleet',
|
|
||||||
);
|
|
||||||
const realRolesDir = join(frameworkFleet, 'roles');
|
|
||||||
|
|
||||||
let tmp: string;
|
|
||||||
let rolesDir: string;
|
|
||||||
let overrideDir: string;
|
|
||||||
|
|
||||||
// A minimal baseline persona file with an inline `class:` + `domain:` marker.
|
|
||||||
function baselinePersona(klass: string, domain: string, marker = 'BASELINE'): string {
|
|
||||||
return `# ${klass} — fleet role definition
|
|
||||||
|
|
||||||
The **${klass}** is the ${marker} definition (\`class: ${klass}\`, \`domain: ${domain}\`).
|
|
||||||
`;
|
|
||||||
}
|
|
||||||
|
|
||||||
function overridePersona(klass: string, domain: string, marker = 'OVERRIDE'): string {
|
|
||||||
return `# ${klass} — fleet role definition (override)
|
|
||||||
|
|
||||||
The **${klass}** is the ${marker} definition (\`class: ${klass}\`, \`domain: ${domain}\`).
|
|
||||||
`;
|
|
||||||
}
|
|
||||||
|
|
||||||
beforeEach(async () => {
|
|
||||||
tmp = await mkdtemp(join(tmpdir(), 'h4-personas-'));
|
|
||||||
rolesDir = join(tmp, 'roles');
|
|
||||||
overrideDir = join(tmp, 'roles.local');
|
|
||||||
await mkdir(rolesDir, { recursive: true });
|
|
||||||
// Seed two baseline personas. (No override dir yet — created per test.)
|
|
||||||
await writeFile(join(rolesDir, 'ceo.md'), baselinePersona('ceo', 'executive'), 'utf8');
|
|
||||||
await writeFile(join(rolesDir, 'code.md'), baselinePersona('code', 'engineering'), 'utf8');
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(async () => {
|
|
||||||
await rm(tmp, { recursive: true, force: true });
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('extractClassesFromDir (shared extraction)', () => {
|
|
||||||
it('records class + domain from inline markers and degrades on missing dir', async () => {
|
|
||||||
const base = await extractClassesFromDir(rolesDir);
|
|
||||||
expect(base.classes.has('ceo')).toBe(true);
|
|
||||||
expect(base.byClass.get('ceo')?.domain).toBe('executive');
|
|
||||||
const missing = await extractClassesFromDir(join(tmp, 'nope'));
|
|
||||||
expect(missing.classes.size).toBe(0);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('resolvePersona — override wins', () => {
|
|
||||||
it('resolves to the override when a class exists in BOTH layers', async () => {
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
|
|
||||||
|
|
||||||
const resolved = await resolvePersona('ceo', { rolesDir, overrideDir });
|
|
||||||
expect(resolved?.layer).toBe('override');
|
|
||||||
expect(resolved?.content).toContain('OVERRIDE');
|
|
||||||
expect(resolved?.file).toBe(join(overrideDir, 'ceo.md'));
|
|
||||||
});
|
|
||||||
|
|
||||||
it('resolves to the baseline when no override exists', async () => {
|
|
||||||
const resolved = await resolvePersona('code', { rolesDir, overrideDir });
|
|
||||||
expect(resolved?.layer).toBe('baseline');
|
|
||||||
expect(resolved?.content).toContain('BASELINE');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns null for an unknown class', async () => {
|
|
||||||
expect(await resolvePersona('does-not-exist', { rolesDir, overrideDir })).toBeNull();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('custom add — override-only class', () => {
|
|
||||||
it('a class present only in roles.local/ appears in listPersonaClasses and resolves', async () => {
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
join(overrideDir, 'mascot.md'),
|
|
||||||
overridePersona('mascot', 'fun', 'CUSTOM'),
|
|
||||||
'utf8',
|
|
||||||
);
|
|
||||||
|
|
||||||
const classes = await listPersonaClasses({ rolesDir, overrideDir });
|
|
||||||
expect(classes.has('mascot')).toBe(true);
|
|
||||||
// Baseline classes are still present (union).
|
|
||||||
expect(classes.has('ceo')).toBe(true);
|
|
||||||
|
|
||||||
const resolved = await resolvePersona('mascot', { rolesDir, overrideDir });
|
|
||||||
expect(resolved?.layer).toBe('override');
|
|
||||||
expect(resolved?.content).toContain('CUSTOM');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('personaStatus classification', () => {
|
|
||||||
it('classifies baseline / overridden / custom correctly', async () => {
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
// ceo: overridden (both). code: baseline (only base). mascot: custom (only override).
|
|
||||||
await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
|
|
||||||
await writeFile(join(overrideDir, 'mascot.md'), overridePersona('mascot', 'fun'), 'utf8');
|
|
||||||
|
|
||||||
const status = await personaStatus({ rolesDir, overrideDir });
|
|
||||||
const byClass = new Map(status.map((s) => [s.klass, s]));
|
|
||||||
expect(byClass.get('ceo')?.status).toBe('overridden');
|
|
||||||
expect(byClass.get('code')?.status).toBe('baseline');
|
|
||||||
expect(byClass.get('mascot')?.status).toBe('custom');
|
|
||||||
// Domain surfaced.
|
|
||||||
expect(byClass.get('ceo')?.domain).toBe('executive');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('AC-NS-7 — update-survival simulation', () => {
|
|
||||||
it('override and custom-added class survive a baseline reseed', async () => {
|
|
||||||
// 1. User customizes ceo and adds a brand-new persona in the override layer.
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
await writeFile(join(overrideDir, 'ceo.md'), overridePersona('ceo', 'executive'), 'utf8');
|
|
||||||
await writeFile(
|
|
||||||
join(overrideDir, 'mascot.md'),
|
|
||||||
overridePersona('mascot', 'fun', 'CUSTOM'),
|
|
||||||
'utf8',
|
|
||||||
);
|
|
||||||
|
|
||||||
// 2. Simulate `mosaic update`: REPLACE the baseline roles/ entirely (as the
|
|
||||||
// framework reseed/rsync does), leaving roles.local/ untouched. The reseed
|
|
||||||
// even ships a NEW baseline ceo and adds a brand-new baseline persona.
|
|
||||||
await rm(rolesDir, { recursive: true, force: true });
|
|
||||||
await mkdir(rolesDir, { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
join(rolesDir, 'ceo.md'),
|
|
||||||
baselinePersona('ceo', 'executive', 'RESEEDED-BASELINE'),
|
|
||||||
'utf8',
|
|
||||||
);
|
|
||||||
await writeFile(join(rolesDir, 'code.md'), baselinePersona('code', 'engineering'), 'utf8');
|
|
||||||
await writeFile(join(rolesDir, 'new-role.md'), baselinePersona('new-role', 'ops'), 'utf8');
|
|
||||||
|
|
||||||
// 3. The override STILL wins (was not clobbered by the reseed).
|
|
||||||
const ceo = await resolvePersona('ceo', { rolesDir, overrideDir });
|
|
||||||
expect(ceo?.layer).toBe('override');
|
|
||||||
expect(ceo?.content).toContain('OVERRIDE');
|
|
||||||
expect(ceo?.content).not.toContain('RESEEDED-BASELINE');
|
|
||||||
|
|
||||||
// 4. The custom-added class still exists and resolves.
|
|
||||||
const mascot = await resolvePersona('mascot', { rolesDir, overrideDir });
|
|
||||||
expect(mascot?.layer).toBe('override');
|
|
||||||
expect(mascot?.content).toContain('CUSTOM');
|
|
||||||
|
|
||||||
// 5. New baseline personas from the reseed are now visible too.
|
|
||||||
const classes = await listPersonaClasses({ rolesDir, overrideDir });
|
|
||||||
expect(classes.has('new-role')).toBe(true);
|
|
||||||
expect(classes.has('mascot')).toBe(true);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('fleet-profiles validation accepts a custom (override-only) persona', () => {
|
|
||||||
it('a profile referencing an override-only class validates', async () => {
|
|
||||||
// Build a profiles dir + roles using the REAL library plus a custom persona.
|
|
||||||
const profilesDir = join(tmp, 'profiles');
|
|
||||||
const customRolesDir = join(tmp, 'real-roles');
|
|
||||||
const customOverrideDir = join(tmp, 'real-roles.local');
|
|
||||||
await mkdir(profilesDir, { recursive: true });
|
|
||||||
await cp(realRolesDir, customRolesDir, { recursive: true });
|
|
||||||
await mkdir(customOverrideDir, { recursive: true });
|
|
||||||
await writeFile(join(customOverrideDir, 'mascot.md'), overridePersona('mascot', 'fun'), 'utf8');
|
|
||||||
|
|
||||||
// A profile whose roster references the custom (override-only) persona.
|
|
||||||
const profileYaml = [
|
|
||||||
'id: custom-team',
|
|
||||||
'title: Custom Team',
|
|
||||||
'description: A team that uses a user-added persona.',
|
|
||||||
'lead: ceo',
|
|
||||||
'floor:',
|
|
||||||
' - ceo',
|
|
||||||
'roster:',
|
|
||||||
' - class: ceo',
|
|
||||||
' - class: mascot',
|
|
||||||
' reports_to: ceo',
|
|
||||||
].join('\n');
|
|
||||||
await writeFile(join(profilesDir, 'custom-team.yaml'), profileYaml, 'utf8');
|
|
||||||
|
|
||||||
// Override-aware loadProfiles must accept it (would throw if mascot unknown).
|
|
||||||
const profiles = await loadProfiles({
|
|
||||||
profilesDir,
|
|
||||||
rolesDir: customRolesDir,
|
|
||||||
overrideDir: customOverrideDir,
|
|
||||||
});
|
|
||||||
const team = profiles.find((p: FleetProfile) => p.id === 'custom-team');
|
|
||||||
expect(team).toBeDefined();
|
|
||||||
|
|
||||||
// And direct validation against the union confirms zero problems.
|
|
||||||
const validClasses = await listPersonaClasses({
|
|
||||||
rolesDir: customRolesDir,
|
|
||||||
overrideDir: customOverrideDir,
|
|
||||||
});
|
|
||||||
expect(validateProfile(team as FleetProfile, validClasses)).toEqual([]);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,512 +0,0 @@
|
|||||||
/**
|
|
||||||
* Persona override layer + resolver (North Star H4).
|
|
||||||
*
|
|
||||||
* Baseline personas are markdown role contracts seeded by the framework into
|
|
||||||
* <mosaicHome>/fleet/roles/*.md
|
|
||||||
* They are RESEEDED on every `mosaic update` (so new baseline personas ship to
|
|
||||||
* existing installs). That reseed is exactly what would clobber any local edit,
|
|
||||||
* so user customizations must NOT live in roles/.
|
|
||||||
*
|
|
||||||
* The override layer is a sibling directory:
|
|
||||||
* <mosaicHome>/fleet/roles.local/*.md
|
|
||||||
* It is PRESERVE-protected in install.sh (see PRESERVE_PATHS "fleet/roles.local"),
|
|
||||||
* so `mosaic update` never deletes it while roles/ keeps reseeding. An override
|
|
||||||
* file WINS over the baseline of the same class, and an override file may ADD an
|
|
||||||
* entirely new class that has no baseline at all. This delivers AC-NS-7: a
|
|
||||||
* user-customized persona survives `mosaic update`.
|
|
||||||
*
|
|
||||||
* Class identity is encoded INLINE in the role prose, not as YAML frontmatter:
|
|
||||||
* (`class: ceo`, `domain: executive`)
|
|
||||||
* The marker value may wrap across a newline. A few engineering personas carry
|
|
||||||
* no marker at all and are identified by filename (e.g. planner -> orchestrator).
|
|
||||||
*
|
|
||||||
* The class-extraction logic here is the SINGLE SOURCE OF TRUTH for "what
|
|
||||||
* persona classes exist"; fleet-profiles.ts imports it (DRY) so a profile roster
|
|
||||||
* can reference a customized or user-added persona.
|
|
||||||
*/
|
|
||||||
|
|
||||||
import { readFileSync, readdirSync } from 'node:fs';
|
|
||||||
import { readFile, readdir } from 'node:fs/promises';
|
|
||||||
import { homedir } from 'node:os';
|
|
||||||
import { basename, join } from 'node:path';
|
|
||||||
import type { Command } from 'commander';
|
|
||||||
|
|
||||||
function defaultMosaicHome(): string {
|
|
||||||
return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Baseline persona role contracts (reseeded on update). */
|
|
||||||
export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
|
|
||||||
return join(mosaicHome, 'fleet', 'roles');
|
|
||||||
}
|
|
||||||
|
|
||||||
/** PRESERVE-protected override layer (survives update; wins on merge). */
|
|
||||||
export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
|
|
||||||
return join(mosaicHome, 'fleet', 'roles.local');
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Match a `class: X` marker even when the value wrapped onto the next line.
|
|
||||||
* Allow surrounding backtick(s); the value is a single kebab-case token.
|
|
||||||
* Shared by every caller so the definition of "a class marker" lives once.
|
|
||||||
*/
|
|
||||||
const CLASS_MARKER = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g;
|
|
||||||
/** Optional `domain: Y` marker that travels alongside the class in the prose. */
|
|
||||||
const DOMAIN_MARKER = /`?domain:\s*\n?\s*([a-z][a-z0-9-]*)`?/;
|
|
||||||
/** LIBRARY.md persona rows: the first table cell is the persona name. */
|
|
||||||
const LIBRARY_ROW = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
|
|
||||||
|
|
||||||
/** Where a resolved persona's definition came from. */
|
|
||||||
export type PersonaLayer = 'baseline' | 'override';
|
|
||||||
|
|
||||||
/** One discovered persona file (a single role contract on disk). */
|
|
||||||
export interface PersonaFile {
|
|
||||||
klass: string;
|
|
||||||
/** The markdown file the class was found in. */
|
|
||||||
file: string;
|
|
||||||
domain?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** The set of persona classes a directory of role contracts defines. */
|
|
||||||
export interface DirClasses {
|
|
||||||
/** Every class name the dir contributes (markers + filenames + LIBRARY rows). */
|
|
||||||
classes: Set<string>;
|
|
||||||
/** For classes whose file carries a marker, the file + domain that defined it. */
|
|
||||||
byClass: Map<string, PersonaFile>;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Scan one directory of role contracts and extract the persona classes it
|
|
||||||
* defines. THIS is the shared extraction both fleet-personas and fleet-profiles
|
|
||||||
* rely on. Sources, unioned (each needed — see module doc):
|
|
||||||
* 1. inline `class: X` markers in roles/*.md (primary; may wrap a newline),
|
|
||||||
* 2. persona-name cells from LIBRARY.md index tables,
|
|
||||||
* 3. the role filename stem (covers marker-less alias docs like planner).
|
|
||||||
*
|
|
||||||
* Missing dir / unreadable files degrade gracefully to whatever was found.
|
|
||||||
* `byClass` records the defining file+domain for marker-bearing classes so the
|
|
||||||
* resolver can map a class back to its file; filename-only and LIBRARY-only
|
|
||||||
* classes still appear in `classes` for membership checks.
|
|
||||||
*/
|
|
||||||
export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
|
|
||||||
const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
|
|
||||||
let entries: string[];
|
|
||||||
try {
|
|
||||||
entries = await readdir(dir);
|
|
||||||
} catch {
|
|
||||||
return acc;
|
|
||||||
}
|
|
||||||
|
|
||||||
for (const entry of entries) {
|
|
||||||
if (!entry.endsWith('.md')) continue;
|
|
||||||
let text: string;
|
|
||||||
try {
|
|
||||||
text = await readFile(join(dir, entry), 'utf8');
|
|
||||||
} catch {
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
accumulateEntry(acc, dir, entry, text);
|
|
||||||
}
|
|
||||||
return acc;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Synchronous twin of {@link extractClassesFromDir}. Identical extraction
|
|
||||||
* semantics (same markers, same union of marker/filename/LIBRARY sources) on
|
|
||||||
* sync fs, for the synchronous launch-time prompt path (composeContract) which
|
|
||||||
* cannot await. Missing dir / unreadable files degrade gracefully.
|
|
||||||
*/
|
|
||||||
export function extractClassesFromDirSync(dir: string): DirClasses {
|
|
||||||
const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
|
|
||||||
let entries: string[];
|
|
||||||
try {
|
|
||||||
entries = readdirSync(dir);
|
|
||||||
} catch {
|
|
||||||
return acc;
|
|
||||||
}
|
|
||||||
|
|
||||||
for (const entry of entries) {
|
|
||||||
if (!entry.endsWith('.md')) continue;
|
|
||||||
let text: string;
|
|
||||||
try {
|
|
||||||
text = readFileSync(join(dir, entry), 'utf8');
|
|
||||||
} catch {
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
accumulateEntry(acc, dir, entry, text);
|
|
||||||
}
|
|
||||||
return acc;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Apply the class-extraction rules for ONE role file's text into `acc`. Pure
|
|
||||||
* over already-read content, so the async and sync directory scanners share a
|
|
||||||
* single definition of "what classes a file contributes" (DRY — no semantic
|
|
||||||
* drift between the launch-time and command-time paths).
|
|
||||||
*/
|
|
||||||
function accumulateEntry(acc: DirClasses, dir: string, entry: string, text: string): void {
|
|
||||||
const { classes, byClass } = acc;
|
|
||||||
if (entry === 'LIBRARY.md') {
|
|
||||||
for (const m of text.matchAll(LIBRARY_ROW)) {
|
|
||||||
const name = m[1];
|
|
||||||
if (name && name !== 'persona') classes.add(name);
|
|
||||||
}
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
// The filename stem is itself a valid class (covers marker-less alias docs).
|
|
||||||
const stem = basename(entry, '.md');
|
|
||||||
classes.add(stem);
|
|
||||||
const domainMatch = DOMAIN_MARKER.exec(text);
|
|
||||||
const domain = domainMatch?.[1];
|
|
||||||
let markedClassForFile: string | undefined;
|
|
||||||
for (const m of text.matchAll(CLASS_MARKER)) {
|
|
||||||
const klass = m[1];
|
|
||||||
if (!klass) continue;
|
|
||||||
classes.add(klass);
|
|
||||||
// Record the FIRST marker as the file's defining class (the prose names
|
|
||||||
// the persona's own class up top; later mentions reference siblings).
|
|
||||||
if (!markedClassForFile) {
|
|
||||||
markedClassForFile = klass;
|
|
||||||
byClass.set(klass, { klass, file: join(dir, entry), ...(domain ? { domain } : {}) });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
// A marker-less file still maps its stem to itself (no domain known).
|
|
||||||
if (!markedClassForFile && !byClass.has(stem)) {
|
|
||||||
byClass.set(stem, { klass: stem, file: join(dir, entry) });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface PersonaDirs {
|
|
||||||
/** Baseline roles dir. Defaults to <mosaicHome>/fleet/roles. */
|
|
||||||
rolesDir?: string;
|
|
||||||
/** Override dir. Defaults to <mosaicHome>/fleet/roles.local. */
|
|
||||||
overrideDir?: string;
|
|
||||||
mosaicHome?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
function resolveDirs(opts: PersonaDirs): { rolesDir: string; overrideDir: string } {
|
|
||||||
const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
|
|
||||||
return {
|
|
||||||
rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
|
|
||||||
overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* UNION of baseline classes and override classes. Overrides may ADD entirely new
|
|
||||||
* classes not present in the baseline, so callers (e.g. profile roster
|
|
||||||
* validation) treat a user-added persona as a real class.
|
|
||||||
*/
|
|
||||||
export async function listPersonaClasses(opts: PersonaDirs = {}): Promise<Set<string>> {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const [base, over] = await Promise.all([
|
|
||||||
extractClassesFromDir(rolesDir),
|
|
||||||
extractClassesFromDir(overrideDir),
|
|
||||||
]);
|
|
||||||
const union = new Set<string>(base.classes);
|
|
||||||
for (const c of over.classes) union.add(c);
|
|
||||||
return union;
|
|
||||||
}
|
|
||||||
|
|
||||||
export type PersonaStatus = 'baseline' | 'overridden' | 'custom';
|
|
||||||
|
|
||||||
export interface PersonaResolution {
|
|
||||||
klass: string;
|
|
||||||
layer: PersonaLayer;
|
|
||||||
/** The file the resolved persona was read from (override wins). */
|
|
||||||
file: string;
|
|
||||||
content: string;
|
|
||||||
domain?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Resolve a persona class to its winning definition: the override file if
|
|
||||||
* roles.local/ defines that class, else the baseline. Match by inline `class:`
|
|
||||||
* marker first, then by filename stem (roles.local/<klass>.md) as a fallback.
|
|
||||||
* Returns null if neither layer defines the class.
|
|
||||||
*/
|
|
||||||
export async function resolvePersona(
|
|
||||||
klass: string,
|
|
||||||
opts: PersonaDirs = {},
|
|
||||||
): Promise<PersonaResolution | null> {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const [base, over] = await Promise.all([
|
|
||||||
extractClassesFromDir(rolesDir),
|
|
||||||
extractClassesFromDir(overrideDir),
|
|
||||||
]);
|
|
||||||
return resolvePersonaFrom(klass, { rolesDir, overrideDir, base, over });
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Resolve a single class against ALREADY-EXTRACTED layer maps. Callers that
|
|
||||||
* resolve many classes against the same two directories (e.g. provisioning a
|
|
||||||
* full roster) should {@link extractClassesFromDir} each dir ONCE and reuse the
|
|
||||||
* result here, rather than paying a full directory re-scan per class. Precedence
|
|
||||||
* is identical to {@link resolvePersona}: override layer wins, then baseline.
|
|
||||||
*/
|
|
||||||
export async function resolvePersonaFrom(
|
|
||||||
klass: string,
|
|
||||||
layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
|
|
||||||
): Promise<PersonaResolution | null> {
|
|
||||||
const { rolesDir, overrideDir, base, over } = layers;
|
|
||||||
|
|
||||||
const fromLayer = async (
|
|
||||||
dir: string,
|
|
||||||
extracted: DirClasses,
|
|
||||||
layer: PersonaLayer,
|
|
||||||
): Promise<PersonaResolution | null> => {
|
|
||||||
// Prefer the marker-defined file; fall back to the filename stem.
|
|
||||||
let pf = extracted.byClass.get(klass);
|
|
||||||
if (!pf) {
|
|
||||||
const byName = join(dir, `${klass}.md`);
|
|
||||||
if (!extracted.classes.has(klass)) return null;
|
|
||||||
// Class known only via filename/LIBRARY: read the stem file if present.
|
|
||||||
try {
|
|
||||||
const content = await readFile(byName, 'utf8');
|
|
||||||
const dm = DOMAIN_MARKER.exec(content);
|
|
||||||
return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
try {
|
|
||||||
const content = await readFile(pf.file, 'utf8');
|
|
||||||
return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
return (
|
|
||||||
(await fromLayer(overrideDir, over, 'override')) ??
|
|
||||||
(await fromLayer(rolesDir, base, 'baseline'))
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Synchronous twin of {@link resolvePersona} — same override-wins precedence
|
|
||||||
* (roles.local/ beats roles/, by marker first then filename stem), returning
|
|
||||||
* null if neither layer defines the class. Exists for the synchronous launch
|
|
||||||
* prompt path (composeContract → readPersonaContractBlock) which cannot await.
|
|
||||||
* Keeping it here, beside the async resolver, keeps the resolution semantics in
|
|
||||||
* one module so the launch-time and command-time resolutions never diverge.
|
|
||||||
*/
|
|
||||||
export function resolvePersonaSync(
|
|
||||||
klass: string,
|
|
||||||
opts: PersonaDirs = {},
|
|
||||||
): PersonaResolution | null {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const base = extractClassesFromDirSync(rolesDir);
|
|
||||||
const over = extractClassesFromDirSync(overrideDir);
|
|
||||||
|
|
||||||
const fromLayer = (
|
|
||||||
dir: string,
|
|
||||||
extracted: DirClasses,
|
|
||||||
layer: PersonaLayer,
|
|
||||||
): PersonaResolution | null => {
|
|
||||||
// Prefer the marker-defined file; fall back to the filename stem.
|
|
||||||
const pf = extracted.byClass.get(klass);
|
|
||||||
if (!pf) {
|
|
||||||
if (!extracted.classes.has(klass)) return null;
|
|
||||||
const byName = join(dir, `${klass}.md`);
|
|
||||||
try {
|
|
||||||
const content = readFileSync(byName, 'utf8');
|
|
||||||
const dm = DOMAIN_MARKER.exec(content);
|
|
||||||
return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
try {
|
|
||||||
const content = readFileSync(pf.file, 'utf8');
|
|
||||||
return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
return fromLayer(overrideDir, over, 'override') ?? fromLayer(rolesDir, base, 'baseline');
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface PersonaStatusEntry {
|
|
||||||
klass: string;
|
|
||||||
status: PersonaStatus;
|
|
||||||
domain?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Classify every known class:
|
|
||||||
* - baseline — present only in roles/
|
|
||||||
* - overridden — present in BOTH roles/ and roles.local/ (override wins)
|
|
||||||
* - custom — present only in roles.local/ (user-added)
|
|
||||||
* Domain is taken from the WINNING layer (override domain wins if present).
|
|
||||||
*/
|
|
||||||
export async function personaStatus(opts: PersonaDirs = {}): Promise<PersonaStatusEntry[]> {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const [base, over] = await Promise.all([
|
|
||||||
extractClassesFromDir(rolesDir),
|
|
||||||
extractClassesFromDir(overrideDir),
|
|
||||||
]);
|
|
||||||
|
|
||||||
const all = new Set<string>([...base.classes, ...over.classes]);
|
|
||||||
const domainOf = (extracted: DirClasses, klass: string): string | undefined =>
|
|
||||||
extracted.byClass.get(klass)?.domain;
|
|
||||||
|
|
||||||
const entries: PersonaStatusEntry[] = [];
|
|
||||||
for (const klass of all) {
|
|
||||||
const inBase = base.classes.has(klass);
|
|
||||||
const inOver = over.classes.has(klass);
|
|
||||||
const status: PersonaStatus = inOver ? (inBase ? 'overridden' : 'custom') : 'baseline';
|
|
||||||
const domain = (inOver ? domainOf(over, klass) : undefined) ?? domainOf(base, klass);
|
|
||||||
entries.push({ klass, status, ...(domain ? { domain } : {}) });
|
|
||||||
}
|
|
||||||
entries.sort((a, b) => a.klass.localeCompare(b.klass));
|
|
||||||
return entries;
|
|
||||||
}
|
|
||||||
|
|
||||||
// ─── CLI: `mosaic fleet persona <list|show|customize>` ───────────────────────
|
|
||||||
|
|
||||||
function printPersonaList(entries: PersonaStatusEntry[]): void {
|
|
||||||
if (entries.length === 0) {
|
|
||||||
console.log('(no personas)');
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
for (const e of entries) {
|
|
||||||
console.log(`${e.klass}\t[${e.status}]\tdomain=${e.domain ?? '-'}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Minimal override scaffold for a brand-new (no-baseline) class. */
|
|
||||||
function scaffoldOverride(klass: string): string {
|
|
||||||
return `# ${klass} — fleet role definition (override)
|
|
||||||
|
|
||||||
The **${klass}** persona (\`class: ${klass}\`) is a user-defined override that
|
|
||||||
lives in the PRESERVE-protected \`fleet/roles.local/\` layer and survives
|
|
||||||
\`mosaic update\`. Edit this file to define the persona's mandate and boundaries.
|
|
||||||
|
|
||||||
## Mandate
|
|
||||||
|
|
||||||
1. (describe what this persona owns)
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
- (describe what this persona does NOT do)
|
|
||||||
`;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Register `persona` under an existing `fleet` command. `mosaicHomeFor` resolves
|
|
||||||
* the active --mosaic-home (parent flag) at call time, mirroring the backlog and
|
|
||||||
* profile subcommand wiring.
|
|
||||||
*/
|
|
||||||
export function registerFleetPersonaCommand(
|
|
||||||
fleetCmd: Command,
|
|
||||||
mosaicHomeFor: () => string,
|
|
||||||
): Command {
|
|
||||||
const personaCmd = fleetCmd
|
|
||||||
.command('persona')
|
|
||||||
.description('Update-surviving persona overrides: baseline ⊕ roles.local layer (H4)');
|
|
||||||
|
|
||||||
personaCmd
|
|
||||||
.command('list')
|
|
||||||
.description('List every persona class with its status (baseline/overridden/custom) and domain')
|
|
||||||
.option('--json', 'Print JSON')
|
|
||||||
.action(async (opts: { json?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const entries = await personaStatus({ mosaicHome: mosaicHomeFor() });
|
|
||||||
if (opts.json) {
|
|
||||||
console.log(JSON.stringify(entries));
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
printPersonaList(entries);
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
personaCmd
|
|
||||||
.command('show <class>')
|
|
||||||
.description('Show the RESOLVED persona (override wins) and which layer it came from')
|
|
||||||
.option('--json', 'Print JSON')
|
|
||||||
.action(async (klass: string, opts: { json?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const resolved = await resolvePersona(klass, { mosaicHome: mosaicHomeFor() });
|
|
||||||
if (!resolved) {
|
|
||||||
process.stderr.write(`Unknown persona class "${klass}"\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
if (opts.json) {
|
|
||||||
console.log(JSON.stringify(resolved));
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
console.log(`# class: ${resolved.klass}`);
|
|
||||||
console.log(`# layer: ${resolved.layer}`);
|
|
||||||
console.log(`# domain: ${resolved.domain ?? '-'}`);
|
|
||||||
console.log(`# file: ${resolved.file}`);
|
|
||||||
console.log('');
|
|
||||||
console.log(resolved.content);
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
personaCmd
|
|
||||||
.command('customize <class>')
|
|
||||||
.description(
|
|
||||||
'Copy the baseline persona into fleet/roles.local/ to edit (override layer). ' +
|
|
||||||
'--new scaffolds a brand-new persona with no baseline.',
|
|
||||||
)
|
|
||||||
.option('--new', 'Scaffold a minimal override for a brand-new class (no baseline required)')
|
|
||||||
.action(async (klass: string, opts: { new?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const { mkdir, writeFile, copyFile, access } = await import('node:fs/promises');
|
|
||||||
const { constants } = await import('node:fs');
|
|
||||||
const mosaicHome = mosaicHomeFor();
|
|
||||||
const rolesDir = defaultRolesDir(mosaicHome);
|
|
||||||
const overrideDir = defaultOverrideDir(mosaicHome);
|
|
||||||
const target = join(overrideDir, `${klass}.md`);
|
|
||||||
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
|
|
||||||
// Do not clobber an existing override.
|
|
||||||
try {
|
|
||||||
await access(target, constants.F_OK);
|
|
||||||
console.log(`Override already exists, not clobbering: ${target}`);
|
|
||||||
return;
|
|
||||||
} catch {
|
|
||||||
// not present — proceed
|
|
||||||
}
|
|
||||||
|
|
||||||
if (opts.new) {
|
|
||||||
await writeFile(target, scaffoldOverride(klass), 'utf8');
|
|
||||||
console.log(`Scaffolded new persona override: ${target}`);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Copy the baseline. Prefer the marker-defining file; fall back to stem.
|
|
||||||
const base = await extractClassesFromDir(rolesDir);
|
|
||||||
const pf = base.byClass.get(klass);
|
|
||||||
const source = pf?.file ?? join(rolesDir, `${klass}.md`);
|
|
||||||
try {
|
|
||||||
await access(source, constants.F_OK);
|
|
||||||
} catch {
|
|
||||||
process.stderr.write(
|
|
||||||
`No baseline persona "${klass}" to copy. Use --new to scaffold one.\n`,
|
|
||||||
);
|
|
||||||
process.exitCode = 1;
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
await copyFile(source, target);
|
|
||||||
console.log(`Copied baseline persona to override layer: ${target}`);
|
|
||||||
console.log('Edit it there; it wins over the baseline and survives `mosaic update`.');
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return personaCmd;
|
|
||||||
}
|
|
||||||
@@ -1,226 +0,0 @@
|
|||||||
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
|
|
||||||
import { tmpdir } from 'node:os';
|
|
||||||
import { dirname, join, resolve } from 'node:path';
|
|
||||||
import { fileURLToPath } from 'node:url';
|
|
||||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
|
||||||
import {
|
|
||||||
listPersonaClasses,
|
|
||||||
loadProfile,
|
|
||||||
loadProfiles,
|
|
||||||
parseProfile,
|
|
||||||
validateProfile,
|
|
||||||
type FleetProfile,
|
|
||||||
} from './fleet-profiles.js';
|
|
||||||
|
|
||||||
// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
|
|
||||||
const frameworkFleet = resolve(
|
|
||||||
dirname(fileURLToPath(import.meta.url)),
|
|
||||||
'..',
|
|
||||||
'..',
|
|
||||||
'framework',
|
|
||||||
'fleet',
|
|
||||||
);
|
|
||||||
const rolesDir = join(frameworkFleet, 'roles');
|
|
||||||
const profilesDir = join(frameworkFleet, 'profiles');
|
|
||||||
|
|
||||||
const realLib = { rolesDir, profilesDir };
|
|
||||||
|
|
||||||
const EXPECTED_IDS = [
|
|
||||||
'business',
|
|
||||||
'marketing',
|
|
||||||
'personal-assistant',
|
|
||||||
'research',
|
|
||||||
'software-delivery',
|
|
||||||
];
|
|
||||||
|
|
||||||
describe('listPersonaClasses (real role library)', () => {
|
|
||||||
it('extracts inline `class:` markers from the role contracts', async () => {
|
|
||||||
const classes = await listPersonaClasses(rolesDir);
|
|
||||||
// Personas that carry an inline `class: X` marker.
|
|
||||||
expect(classes.has('code')).toBe(true);
|
|
||||||
expect(classes.has('marketing-lead')).toBe(true);
|
|
||||||
expect(classes.has('ceo')).toBe(true);
|
|
||||||
// support-agent's marker wraps across a newline — must still resolve.
|
|
||||||
expect(classes.has('support-agent')).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('covers marker-less engineering personas via filename + LIBRARY index', async () => {
|
|
||||||
const classes = await listPersonaClasses(rolesDir);
|
|
||||||
// planner/decomposition have a role file but no inline marker — they resolve
|
|
||||||
// from the filename + LIBRARY.md row.
|
|
||||||
expect(classes.has('planner')).toBe(true);
|
|
||||||
expect(classes.has('decomposition')).toBe(true);
|
|
||||||
// The dedicated orchestrator persona resolves (inline marker + filename + row).
|
|
||||||
expect(classes.has('orchestrator')).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns an empty set for a missing roles dir (graceful)', async () => {
|
|
||||||
const classes = await listPersonaClasses(join(tmpdir(), 'definitely-missing-roles-xyz'));
|
|
||||||
expect(classes.size).toBe(0);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('baseline profiles (real library)', () => {
|
|
||||||
it('loads exactly the five baseline profiles, sorted by id', async () => {
|
|
||||||
const profiles = await loadProfiles(realLib);
|
|
||||||
expect(profiles.map((p) => p.id)).toEqual(EXPECTED_IDS);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('every referenced class resolves against the real role library (drift guard)', async () => {
|
|
||||||
// This is the key test: it fails if a profile drifts from the persona library.
|
|
||||||
const profiles = await loadProfiles(realLib);
|
|
||||||
const validClasses = await listPersonaClasses(rolesDir);
|
|
||||||
for (const profile of profiles) {
|
|
||||||
expect(validateProfile(profile, validClasses)).toEqual([]);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('software-delivery has the expected lead, floor, and roster shape', async () => {
|
|
||||||
const profile = await loadProfile('software-delivery', realLib);
|
|
||||||
expect(profile.lead).toBe('orchestrator');
|
|
||||||
expect(profile.floor).toEqual(['orchestrator', 'enhancer']);
|
|
||||||
const code = profile.roster.find((r) => r.class === 'code');
|
|
||||||
expect(code?.multiplicity).toBe(2);
|
|
||||||
expect(code?.reportsTo).toBe('decomposition');
|
|
||||||
// The dedicated orchestrator is the lead seat (no reports_to); the planner is
|
|
||||||
// now a distinct seat that reports to it.
|
|
||||||
const orchestrator = profile.roster.find((r) => r.class === 'orchestrator');
|
|
||||||
expect(orchestrator?.reportsTo).toBeUndefined();
|
|
||||||
const planner = profile.roster.find((r) => r.class === 'planner');
|
|
||||||
expect(planner?.reportsTo).toBe('orchestrator');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('loadProfile throws on an unknown id', async () => {
|
|
||||||
await expect(loadProfile('does-not-exist', realLib)).rejects.toThrow(/Unknown profile/);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('parseProfile', () => {
|
|
||||||
it('defaults multiplicity to 1 and omits reports_to for the lead', () => {
|
|
||||||
const yaml = [
|
|
||||||
'id: x',
|
|
||||||
'title: X',
|
|
||||||
'description: a system',
|
|
||||||
'lead: ceo',
|
|
||||||
'floor: [ceo]',
|
|
||||||
'roster:',
|
|
||||||
' - class: ceo',
|
|
||||||
' - class: code',
|
|
||||||
' reports_to: ceo',
|
|
||||||
' multiplicity: 3',
|
|
||||||
'',
|
|
||||||
].join('\n');
|
|
||||||
const profile = parseProfile(yaml);
|
|
||||||
expect(profile.roster[0]).toEqual({ class: 'ceo', multiplicity: 1 });
|
|
||||||
expect(profile.roster[1]).toEqual({ class: 'code', reportsTo: 'ceo', multiplicity: 3 });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects a profile whose id mismatches its filename', () => {
|
|
||||||
expect(() =>
|
|
||||||
parseProfile(
|
|
||||||
'id: other\ntitle: T\ndescription: d\nlead: ceo\nroster: [{class: ceo}]\n',
|
|
||||||
'expected',
|
|
||||||
),
|
|
||||||
).toThrow(/does not match its filename/);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects a non-integer multiplicity', () => {
|
|
||||||
const yaml =
|
|
||||||
'id: x\ntitle: T\ndescription: d\nlead: ceo\nroster:\n - class: ceo\n multiplicity: 1.5\n';
|
|
||||||
expect(() => parseProfile(yaml)).toThrow(/multiplicity/);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('validateProfile', () => {
|
|
||||||
const valid = new Set(['ceo', 'coo', 'code']);
|
|
||||||
|
|
||||||
it('passes a well-formed profile', () => {
|
|
||||||
const profile: FleetProfile = {
|
|
||||||
id: 'x',
|
|
||||||
title: 'X',
|
|
||||||
description: 'd',
|
|
||||||
lead: 'ceo',
|
|
||||||
floor: ['ceo'],
|
|
||||||
roster: [
|
|
||||||
{ class: 'ceo', multiplicity: 1 },
|
|
||||||
{ class: 'coo', reportsTo: 'ceo', multiplicity: 1 },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
expect(validateProfile(profile, valid)).toEqual([]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects an unknown roster class', () => {
|
|
||||||
const profile: FleetProfile = {
|
|
||||||
id: 'x',
|
|
||||||
title: 'X',
|
|
||||||
description: 'd',
|
|
||||||
lead: 'ceo',
|
|
||||||
floor: [],
|
|
||||||
roster: [{ class: 'not-a-real-persona', multiplicity: 1 }],
|
|
||||||
};
|
|
||||||
const problems = validateProfile(profile, valid);
|
|
||||||
expect(problems.some((p) => /not-a-real-persona.*not a known persona class/.test(p))).toBe(
|
|
||||||
true,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects a reports_to that names a class absent from the roster', () => {
|
|
||||||
const profile: FleetProfile = {
|
|
||||||
id: 'x',
|
|
||||||
title: 'X',
|
|
||||||
description: 'd',
|
|
||||||
lead: 'ceo',
|
|
||||||
floor: [],
|
|
||||||
roster: [{ class: 'code', reportsTo: 'coo', multiplicity: 1 }], // coo valid but not in roster
|
|
||||||
};
|
|
||||||
const problems = validateProfile(profile, valid);
|
|
||||||
expect(problems.some((p) => /reports_to.*not present in this roster/.test(p))).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects a reports_to that is not a known persona class at all', () => {
|
|
||||||
const profile: FleetProfile = {
|
|
||||||
id: 'x',
|
|
||||||
title: 'X',
|
|
||||||
description: 'd',
|
|
||||||
lead: 'ceo',
|
|
||||||
floor: [],
|
|
||||||
roster: [
|
|
||||||
{ class: 'ceo', multiplicity: 1 },
|
|
||||||
{ class: 'code', reportsTo: 'ghost', multiplicity: 1 },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
const problems = validateProfile(profile, valid);
|
|
||||||
expect(problems.some((p) => /ghost.*not a known persona class/.test(p))).toBe(true);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('loadProfiles with a temp override dir', () => {
|
|
||||||
let dir: string;
|
|
||||||
beforeEach(async () => {
|
|
||||||
dir = await mkdtemp(join(tmpdir(), 'mosaic-profiles-'));
|
|
||||||
});
|
|
||||||
afterEach(async () => {
|
|
||||||
await rm(dir, { recursive: true, force: true });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('throws when a profile references an unknown class (validated against real roles)', async () => {
|
|
||||||
await writeFile(
|
|
||||||
join(dir, 'bad.yaml'),
|
|
||||||
'id: bad\ntitle: Bad\ndescription: d\nlead: nope-not-real\nroster:\n - class: nope-not-real\n',
|
|
||||||
);
|
|
||||||
await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
|
|
||||||
/is invalid|not a known persona class/,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('throws on duplicate profile ids across files', async () => {
|
|
||||||
const body = 'title: Dup\ndescription: d\nlead: ceo\nroster:\n - class: ceo\n';
|
|
||||||
// Same declared id in two differently-named files -> id mismatches filename
|
|
||||||
// first; use matching filenames+id to force the duplicate-id path instead.
|
|
||||||
await writeFile(join(dir, 'dup.yaml'), `id: dup\n${body}`);
|
|
||||||
await writeFile(join(dir, 'dup.yml'), `id: dup\n${body}`);
|
|
||||||
await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
|
|
||||||
/Duplicate profile id/,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,364 +0,0 @@
|
|||||||
/**
|
|
||||||
* `mosaic fleet profile <list|show>` — system-type profiles (North Star H2).
|
|
||||||
*
|
|
||||||
* A profile is a DECLARATIVE mapping from a "system type" (software-delivery,
|
|
||||||
* personal-assistant, research, business, marketing, …) to a persona roster plus
|
|
||||||
* its org topology. Profiles are DATA, seeded from the framework like roles:
|
|
||||||
* framework/fleet/profiles/*.yaml -> <mosaicHome>/fleet/profiles/*.yaml
|
|
||||||
* so an operator declares a system type and gets the matching roster from the
|
|
||||||
* baseline library with NO code change (NS-9 / AC-NS-6).
|
|
||||||
*
|
|
||||||
* This module loads, parses, and VALIDATES those yaml files. Validation guards
|
|
||||||
* roster/library drift: every persona class a profile references MUST resolve to
|
|
||||||
* a real persona in the role library. Because the library encodes class identity
|
|
||||||
* INLINE in prose (e.g. `` (`class: marketing-lead`) ``) — not YAML frontmatter —
|
|
||||||
* and a few engineering personas (planner/decomposition) carry no marker at all,
|
|
||||||
* the set of valid classes is the UNION of three signals:
|
|
||||||
* 1. inline `` `class: X` `` markers scanned from roles/*.md,
|
|
||||||
* 2. the persona rows in roles/LIBRARY.md (the authoritative index),
|
|
||||||
* 3. the role filenames themselves (roles/<class>.md).
|
|
||||||
* See `listPersonaClasses`.
|
|
||||||
*/
|
|
||||||
|
|
||||||
import { readFile, readdir } from 'node:fs/promises';
|
|
||||||
import { homedir } from 'node:os';
|
|
||||||
import { basename, join } from 'node:path';
|
|
||||||
import type { Command } from 'commander';
|
|
||||||
import YAML from 'yaml';
|
|
||||||
import {
|
|
||||||
defaultOverrideDir,
|
|
||||||
extractClassesFromDir,
|
|
||||||
listPersonaClasses as listOverrideAwarePersonaClasses,
|
|
||||||
} from './fleet-personas.js';
|
|
||||||
|
|
||||||
function defaultMosaicHome(): string {
|
|
||||||
return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Directory holding the seeded profile yaml files. */
|
|
||||||
export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
|
|
||||||
return join(mosaicHome, 'fleet', 'profiles');
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Directory holding the persona role contracts. */
|
|
||||||
export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
|
|
||||||
return join(mosaicHome, 'fleet', 'roles');
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface ProfileRosterEntry {
|
|
||||||
class: string;
|
|
||||||
reportsTo?: string;
|
|
||||||
multiplicity: number;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface FleetProfile {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
description: string;
|
|
||||||
lead: string;
|
|
||||||
floor: string[];
|
|
||||||
roster: ProfileRosterEntry[];
|
|
||||||
notes?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Extract the set of valid persona classes from a single baseline role dir.
|
|
||||||
*
|
|
||||||
* Thin wrapper over the shared {@link extractClassesFromDir} in fleet-personas.ts
|
|
||||||
* — the single source of truth for "what classes exist" (DRY). Kept as a
|
|
||||||
* baseline-only, positional-`rolesDir` helper for backward compatibility; the
|
|
||||||
* override-aware union (baseline ⊕ roles.local) used by roster validation is
|
|
||||||
* {@link listPersonaClassesWithOverrides} below.
|
|
||||||
*/
|
|
||||||
export async function listPersonaClasses(rolesDir = defaultRolesDir()): Promise<Set<string>> {
|
|
||||||
return (await extractClassesFromDir(rolesDir)).classes;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Override-aware valid-class set: baseline roles/ ⊕ override roles.local/. A
|
|
||||||
* profile may legitimately reference a user-customized OR user-ADDED persona, so
|
|
||||||
* roster validation resolves against this union (H4). Delegates to the shared
|
|
||||||
* fleet-personas resolver.
|
|
||||||
*/
|
|
||||||
export async function listPersonaClassesWithOverrides(
|
|
||||||
rolesDir: string,
|
|
||||||
overrideDir: string,
|
|
||||||
): Promise<Set<string>> {
|
|
||||||
return listOverrideAwarePersonaClasses({ rolesDir, overrideDir });
|
|
||||||
}
|
|
||||||
|
|
||||||
function asString(value: unknown, ctx: string): string {
|
|
||||||
if (typeof value !== 'string' || value.trim() === '') {
|
|
||||||
throw new Error(`profile ${ctx} must be a non-empty string`);
|
|
||||||
}
|
|
||||||
return value.trim();
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Parse raw yaml text into a typed FleetProfile. Pure (no IO). Throws a
|
|
||||||
* descriptive error on a malformed profile so the loader/CLI fail loudly.
|
|
||||||
* `sourceId` (typically the filename stem) is used only for error messages and
|
|
||||||
* to validate that the declared `id` matches the file it came from.
|
|
||||||
*/
|
|
||||||
export function parseProfile(rawText: string, sourceId?: string): FleetProfile {
|
|
||||||
const parsed = YAML.parse(rawText) as Record<string, unknown> | null;
|
|
||||||
if (!parsed || typeof parsed !== 'object') {
|
|
||||||
throw new Error(`profile ${sourceId ?? '<?>'} did not parse to a mapping`);
|
|
||||||
}
|
|
||||||
|
|
||||||
const id = asString(parsed['id'], `${sourceId ?? '<?>'}.id`);
|
|
||||||
if (sourceId && id !== sourceId) {
|
|
||||||
throw new Error(`profile id "${id}" does not match its filename "${sourceId}"`);
|
|
||||||
}
|
|
||||||
|
|
||||||
const rawFloor = parsed['floor'] ?? [];
|
|
||||||
if (!Array.isArray(rawFloor)) {
|
|
||||||
throw new Error(`profile ${id}.floor must be an array`);
|
|
||||||
}
|
|
||||||
const floor = rawFloor.map((c, i) => asString(c, `${id}.floor[${i}]`));
|
|
||||||
|
|
||||||
const rawRoster = parsed['roster'];
|
|
||||||
if (!Array.isArray(rawRoster) || rawRoster.length === 0) {
|
|
||||||
throw new Error(`profile ${id}.roster must be a non-empty array`);
|
|
||||||
}
|
|
||||||
const roster: ProfileRosterEntry[] = rawRoster.map((row, i) => {
|
|
||||||
const r = row as Record<string, unknown>;
|
|
||||||
const cls = asString(r?.['class'], `${id}.roster[${i}].class`);
|
|
||||||
const multRaw = r?.['multiplicity'];
|
|
||||||
let multiplicity = 1;
|
|
||||||
if (multRaw !== undefined && multRaw !== null) {
|
|
||||||
if (typeof multRaw !== 'number' || !Number.isInteger(multRaw) || multRaw < 1) {
|
|
||||||
throw new Error(`profile ${id}.roster[${i}].multiplicity must be a positive integer`);
|
|
||||||
}
|
|
||||||
multiplicity = multRaw;
|
|
||||||
}
|
|
||||||
const entry: ProfileRosterEntry = { class: cls, multiplicity };
|
|
||||||
const reportsTo = r?.['reports_to'];
|
|
||||||
if (reportsTo !== undefined && reportsTo !== null) {
|
|
||||||
entry.reportsTo = asString(reportsTo, `${id}.roster[${i}].reports_to`);
|
|
||||||
}
|
|
||||||
return entry;
|
|
||||||
});
|
|
||||||
|
|
||||||
const profile: FleetProfile = {
|
|
||||||
id,
|
|
||||||
title: asString(parsed['title'], `${id}.title`),
|
|
||||||
description: asString(parsed['description'], `${id}.description`),
|
|
||||||
lead: asString(parsed['lead'], `${id}.lead`),
|
|
||||||
floor,
|
|
||||||
roster,
|
|
||||||
};
|
|
||||||
const notes = parsed['notes'];
|
|
||||||
if (notes !== undefined && notes !== null) {
|
|
||||||
profile.notes = asString(notes, `${id}.notes`);
|
|
||||||
}
|
|
||||||
return profile;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Validate a profile against the set of valid persona classes and its own roster.
|
|
||||||
* Returns the list of problems (empty when valid) rather than throwing, so the
|
|
||||||
* loader can aggregate errors across many profiles.
|
|
||||||
*
|
|
||||||
* Checks:
|
|
||||||
* - lead resolves to a real persona class.
|
|
||||||
* - every floor[] entry resolves.
|
|
||||||
* - every roster[].class resolves.
|
|
||||||
* - every roster[].reports_to resolves AND names a class present in THIS roster
|
|
||||||
* (topology edges must point at a seat that exists in the profile).
|
|
||||||
* Cycle detection in the reports_to graph is intentionally out of scope.
|
|
||||||
*/
|
|
||||||
export function validateProfile(profile: FleetProfile, validClasses: Set<string>): string[] {
|
|
||||||
const problems: string[] = [];
|
|
||||||
const rosterClasses = new Set(profile.roster.map((r) => r.class));
|
|
||||||
|
|
||||||
if (!validClasses.has(profile.lead)) {
|
|
||||||
problems.push(`lead "${profile.lead}" is not a known persona class`);
|
|
||||||
}
|
|
||||||
for (const f of profile.floor) {
|
|
||||||
if (!validClasses.has(f)) {
|
|
||||||
problems.push(`floor entry "${f}" is not a known persona class`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
for (const entry of profile.roster) {
|
|
||||||
if (!validClasses.has(entry.class)) {
|
|
||||||
problems.push(`roster class "${entry.class}" is not a known persona class`);
|
|
||||||
}
|
|
||||||
if (entry.reportsTo !== undefined) {
|
|
||||||
if (!validClasses.has(entry.reportsTo)) {
|
|
||||||
problems.push(
|
|
||||||
`roster "${entry.class}" reports_to "${entry.reportsTo}" is not a known persona class`,
|
|
||||||
);
|
|
||||||
} else if (!rosterClasses.has(entry.reportsTo)) {
|
|
||||||
problems.push(
|
|
||||||
`roster "${entry.class}" reports_to "${entry.reportsTo}" which is not present in this roster`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
return problems;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface LoadProfilesOptions {
|
|
||||||
/** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
|
|
||||||
profilesDir?: string;
|
|
||||||
/** Override the roles dir (tests). Defaults to <mosaicHome>/fleet/roles. */
|
|
||||||
rolesDir?: string;
|
|
||||||
/** Persona override dir (tests). Defaults to <mosaicHome>/fleet/roles.local. */
|
|
||||||
overrideDir?: string;
|
|
||||||
mosaicHome?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
function resolveDirs(opts: LoadProfilesOptions): {
|
|
||||||
profilesDir: string;
|
|
||||||
rolesDir: string;
|
|
||||||
overrideDir: string;
|
|
||||||
} {
|
|
||||||
const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
|
|
||||||
return {
|
|
||||||
profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
|
|
||||||
rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
|
|
||||||
overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Load, parse, and validate every profile yaml in the profiles dir. Throws if
|
|
||||||
* any profile is malformed, references an unknown class, or duplicates an id.
|
|
||||||
* Profiles are returned sorted by id for deterministic output.
|
|
||||||
*/
|
|
||||||
export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<FleetProfile[]> {
|
|
||||||
const { profilesDir, rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
let files: string[];
|
|
||||||
try {
|
|
||||||
files = (await readdir(profilesDir)).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
|
|
||||||
} catch {
|
|
||||||
throw new Error(`No fleet profiles directory at ${profilesDir}`);
|
|
||||||
}
|
|
||||||
files.sort();
|
|
||||||
|
|
||||||
// Override-aware: a profile may reference a user-customized or user-ADDED
|
|
||||||
// persona living in the roles.local/ layer (H4), so validate against the
|
|
||||||
// baseline ⊕ override union, not the baseline alone.
|
|
||||||
const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
|
|
||||||
const profiles: FleetProfile[] = [];
|
|
||||||
const seen = new Map<string, string>();
|
|
||||||
|
|
||||||
for (const file of files) {
|
|
||||||
const sourceId = basename(file, file.endsWith('.yaml') ? '.yaml' : '.yml');
|
|
||||||
const rawText = await readFile(join(profilesDir, file), 'utf8');
|
|
||||||
const profile = parseProfile(rawText, sourceId);
|
|
||||||
|
|
||||||
const prior = seen.get(profile.id);
|
|
||||||
if (prior) {
|
|
||||||
throw new Error(`Duplicate profile id "${profile.id}" in ${file} and ${prior}`);
|
|
||||||
}
|
|
||||||
seen.set(profile.id, file);
|
|
||||||
|
|
||||||
const problems = validateProfile(profile, validClasses);
|
|
||||||
if (problems.length > 0) {
|
|
||||||
throw new Error(`Profile ${file} is invalid:\n - ${problems.join('\n - ')}`);
|
|
||||||
}
|
|
||||||
profiles.push(profile);
|
|
||||||
}
|
|
||||||
return profiles;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Load and validate a single profile by id. Throws if not found. */
|
|
||||||
export async function loadProfile(
|
|
||||||
id: string,
|
|
||||||
opts: LoadProfilesOptions = {},
|
|
||||||
): Promise<FleetProfile> {
|
|
||||||
const profiles = await loadProfiles(opts);
|
|
||||||
const match = profiles.find((p) => p.id === id);
|
|
||||||
if (!match) {
|
|
||||||
const known = profiles.map((p) => p.id).join(', ') || '(none)';
|
|
||||||
throw new Error(`Unknown profile "${id}". Known profiles: ${known}`);
|
|
||||||
}
|
|
||||||
return match;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Total seat count of a roster, honoring multiplicity. */
|
|
||||||
function rosterSize(profile: FleetProfile): number {
|
|
||||||
return profile.roster.reduce((sum, entry) => sum + entry.multiplicity, 0);
|
|
||||||
}
|
|
||||||
|
|
||||||
function printProfileList(profiles: FleetProfile[]): void {
|
|
||||||
if (profiles.length === 0) {
|
|
||||||
console.log('(no profiles)');
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
for (const p of profiles) {
|
|
||||||
console.log(`${p.id}\t${p.title}\tlead=${p.lead}\troster=${rosterSize(p)}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function printProfileShow(profile: FleetProfile): void {
|
|
||||||
console.log(`${profile.id} — ${profile.title}`);
|
|
||||||
console.log(profile.description);
|
|
||||||
console.log('');
|
|
||||||
console.log(`lead: ${profile.lead}`);
|
|
||||||
console.log(`floor: ${profile.floor.join(', ') || '-'}`);
|
|
||||||
console.log(`roster (${rosterSize(profile)} seat(s)):`);
|
|
||||||
for (const entry of profile.roster) {
|
|
||||||
const reports = entry.reportsTo ? ` reports_to=${entry.reportsTo}` : '';
|
|
||||||
const mult = entry.multiplicity > 1 ? ` x${entry.multiplicity}` : '';
|
|
||||||
console.log(` - ${entry.class}${mult}${reports}`);
|
|
||||||
}
|
|
||||||
if (profile.notes) {
|
|
||||||
console.log('');
|
|
||||||
console.log(`notes: ${profile.notes}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Register `profile` under an existing `fleet` command. `mosaicHomeFor` resolves
|
|
||||||
* the active --mosaic-home (parent flag) at call time, matching the backlog
|
|
||||||
* subcommand wiring. Validation errors exit non-zero with a readable message.
|
|
||||||
*/
|
|
||||||
export function registerFleetProfileCommand(
|
|
||||||
fleetCmd: Command,
|
|
||||||
mosaicHomeFor: () => string,
|
|
||||||
): Command {
|
|
||||||
const profileCmd = fleetCmd
|
|
||||||
.command('profile')
|
|
||||||
.description('System-type profiles: declarative persona roster + topology (H2)');
|
|
||||||
|
|
||||||
profileCmd
|
|
||||||
.command('list')
|
|
||||||
.description('List available system-type profiles (id, title, lead, roster size)')
|
|
||||||
.option('--json', 'Print JSON')
|
|
||||||
.action(async (opts: { json?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const profiles = await loadProfiles({ mosaicHome: mosaicHomeFor() });
|
|
||||||
if (opts.json) {
|
|
||||||
console.log(JSON.stringify(profiles));
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
printProfileList(profiles);
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
profileCmd
|
|
||||||
.command('show <id>')
|
|
||||||
.description('Show a profile: full roster with reports_to/multiplicity, floor, lead')
|
|
||||||
.option('--json', 'Print JSON')
|
|
||||||
.action(async (id: string, opts: { json?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const profile = await loadProfile(id, { mosaicHome: mosaicHomeFor() });
|
|
||||||
if (opts.json) {
|
|
||||||
console.log(JSON.stringify(profile));
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
printProfileShow(profile);
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return profileCmd;
|
|
||||||
}
|
|
||||||
@@ -1,270 +0,0 @@
|
|||||||
import { access, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
|
|
||||||
import { constants } from 'node:fs';
|
|
||||||
import { tmpdir } from 'node:os';
|
|
||||||
import { dirname, join, resolve } from 'node:path';
|
|
||||||
import { fileURLToPath } from 'node:url';
|
|
||||||
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
|
||||||
import { loadFleetRoster } from './fleet.js';
|
|
||||||
import { generateRoster, runProvision } from './fleet-provision.js';
|
|
||||||
import { loadProfile } from './fleet-profiles.js';
|
|
||||||
|
|
||||||
// These are INTEGRATION tests: each exercises real filesystem I/O — scanning the
|
|
||||||
// committed framework/fleet persona library, rendering YAML, writing to a temp
|
|
||||||
// mosaicHome, and round-tripping through the real roster parser. On a heavily
|
|
||||||
// contended CI runner (the whole monorepo's suites run in parallel) that genuine
|
|
||||||
// I/O can exceed vitest's 5s default even though it completes in ~400ms locally.
|
|
||||||
// Give the legitimately I/O-bound work generous headroom so CI is deterministic.
|
|
||||||
vi.setConfig({ testTimeout: 30_000 });
|
|
||||||
|
|
||||||
// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
|
|
||||||
const frameworkFleet = resolve(
|
|
||||||
dirname(fileURLToPath(import.meta.url)),
|
|
||||||
'..',
|
|
||||||
'..',
|
|
||||||
'framework',
|
|
||||||
'fleet',
|
|
||||||
);
|
|
||||||
const rolesDir = join(frameworkFleet, 'roles');
|
|
||||||
const profilesDir = join(frameworkFleet, 'profiles');
|
|
||||||
|
|
||||||
/** A fresh temp mosaicHome whose fleet/ dir is empty (for write-path tests). */
|
|
||||||
async function freshMosaicHome(): Promise<string> {
|
|
||||||
const home = await mkdtemp(join(tmpdir(), 'mosaic-provision-'));
|
|
||||||
await mkdir(join(home, 'fleet'), { recursive: true });
|
|
||||||
return home;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function fileExists(path: string): Promise<boolean> {
|
|
||||||
try {
|
|
||||||
await access(path, constants.F_OK);
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
describe('provision software-delivery (floor, default)', () => {
|
|
||||||
it('materializes only the floor seats with correct flags + valid scaffold', async () => {
|
|
||||||
const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
|
|
||||||
const { seats, yaml } = await generateRoster(profile, { profilesDir, rolesDir });
|
|
||||||
|
|
||||||
// Floor is orchestrator + enhancer.
|
|
||||||
expect(seats.map((s) => s.name).sort()).toEqual(['enhancer', 'orchestrator']);
|
|
||||||
const orch = seats.find((s) => s.name === 'orchestrator');
|
|
||||||
const enh = seats.find((s) => s.name === 'enhancer');
|
|
||||||
// RULE 2: floor + lead get persistent_persona.
|
|
||||||
expect(orch?.persistentPersona).toBe(true);
|
|
||||||
expect(enh?.persistentPersona).toBe(true);
|
|
||||||
// RULE 3: floor/lead do NOT reset between tasks.
|
|
||||||
expect(orch?.resetBetweenTasks).toBeUndefined();
|
|
||||||
expect(enh?.resetBetweenTasks).toBeUndefined();
|
|
||||||
// RULE 4: default runtime claude.
|
|
||||||
expect(orch?.runtime).toBe('claude');
|
|
||||||
|
|
||||||
// Scaffold round-trips through the real parser.
|
|
||||||
expect(yaml).toContain('version: 1');
|
|
||||||
expect(yaml).toContain('transport: tmux');
|
|
||||||
expect(yaml).toContain('socket_name: mosaic-fleet');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('provision --full', () => {
|
|
||||||
it('expands the entire roster, including multiplicity, deterministically', async () => {
|
|
||||||
const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
|
|
||||||
const { seats } = await generateRoster(profile, { full: true, profilesDir, rolesDir });
|
|
||||||
|
|
||||||
const names = seats.map((s) => s.name);
|
|
||||||
// code multiplicity 2 -> code0/code1 (RULE 1).
|
|
||||||
expect(names).toContain('code0');
|
|
||||||
expect(names).toContain('code1');
|
|
||||||
expect(names).not.toContain('code');
|
|
||||||
// Singleton seats keep the bare class name.
|
|
||||||
expect(names).toContain('planner');
|
|
||||||
expect(names).toContain('merge-gate');
|
|
||||||
|
|
||||||
// Deterministic ordering: profile roster order, multiplicity expanded inline.
|
|
||||||
const codeIdx0 = names.indexOf('code0');
|
|
||||||
expect(names[codeIdx0 + 1]).toBe('code1');
|
|
||||||
|
|
||||||
// RULE 3: a non-floor, non-lead execution seat resets between tasks.
|
|
||||||
const code0 = seats.find((s) => s.name === 'code0');
|
|
||||||
expect(code0?.resetBetweenTasks).toBe(true);
|
|
||||||
expect(code0?.persistentPersona).toBeUndefined();
|
|
||||||
|
|
||||||
// Seat count == sum of multiplicities.
|
|
||||||
const expected = profile.roster.reduce((n, e) => n + e.multiplicity, 0);
|
|
||||||
expect(seats.length).toBe(expected);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('generated roster round-trips through the real parser', () => {
|
|
||||||
it('feeds generated YAML back through loadFleetRoster (key correctness proof)', async () => {
|
|
||||||
const home = await freshMosaicHome();
|
|
||||||
try {
|
|
||||||
const result = await runProvision('software-delivery', {
|
|
||||||
mosaicHome: home,
|
|
||||||
profilesDir,
|
|
||||||
rolesDir,
|
|
||||||
full: true,
|
|
||||||
write: true,
|
|
||||||
});
|
|
||||||
expect(result.wrote).toBe(join(home, 'fleet', 'roster.yaml'));
|
|
||||||
|
|
||||||
const parsed = await loadFleetRoster(result.wrote!);
|
|
||||||
// It parses with no error and carries every seat.
|
|
||||||
const profile = await loadProfile('software-delivery', { profilesDir, rolesDir });
|
|
||||||
const expected = profile.roster.reduce((n, e) => n + e.multiplicity, 0);
|
|
||||||
expect(parsed.agents.length).toBe(expected);
|
|
||||||
// Classes survive the round-trip.
|
|
||||||
expect(parsed.agents.some((a) => a.className === 'orchestrator')).toBe(true);
|
|
||||||
expect(parsed.agents.filter((a) => a.className === 'code').length).toBe(2);
|
|
||||||
// reports_to must NOT have been emitted (parser rejects unknown keys).
|
|
||||||
expect(result.yaml).not.toContain('reports_to');
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('override-aware persona validation', () => {
|
|
||||||
let dir: string;
|
|
||||||
beforeEach(async () => {
|
|
||||||
dir = await mkdtemp(join(tmpdir(), 'mosaic-provision-ov-'));
|
|
||||||
});
|
|
||||||
afterEach(async () => {
|
|
||||||
await rm(dir, { recursive: true, force: true });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('resolves a user-added (roles.local-only) persona without a false unresolved error', async () => {
|
|
||||||
const overrideDir = join(dir, 'roles.local');
|
|
||||||
const customProfilesDir = join(dir, 'profiles');
|
|
||||||
await mkdir(overrideDir, { recursive: true });
|
|
||||||
await mkdir(customProfilesDir, { recursive: true });
|
|
||||||
// A brand-new class that exists ONLY in roles.local.
|
|
||||||
await writeFile(
|
|
||||||
join(overrideDir, 'widget-maker.md'),
|
|
||||||
'# widget-maker\n\nThe widget-maker persona (`class: widget-maker`).\n',
|
|
||||||
);
|
|
||||||
await writeFile(
|
|
||||||
join(customProfilesDir, 'custom.yaml'),
|
|
||||||
[
|
|
||||||
'id: custom',
|
|
||||||
'title: Custom',
|
|
||||||
'description: a custom system',
|
|
||||||
'lead: widget-maker',
|
|
||||||
'floor: [widget-maker]',
|
|
||||||
'roster:',
|
|
||||||
' - class: widget-maker',
|
|
||||||
'',
|
|
||||||
].join('\n'),
|
|
||||||
);
|
|
||||||
|
|
||||||
const result = await runProvision('custom', {
|
|
||||||
mosaicHome: dir,
|
|
||||||
profilesDir: customProfilesDir,
|
|
||||||
// Point baseline rolesDir at a missing dir so resolution depends on override.
|
|
||||||
rolesDir: join(dir, 'no-baseline'),
|
|
||||||
overrideDir,
|
|
||||||
});
|
|
||||||
expect(result.yaml).toContain('class: widget-maker');
|
|
||||||
// It resolved from the override layer.
|
|
||||||
// (generateRoster records personaLayer; the seat is present.)
|
|
||||||
expect(result.summary).toContain('persona=override');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('FAILS with a clear message when a profile references a bogus class', async () => {
|
|
||||||
const customProfilesDir = join(dir, 'profiles');
|
|
||||||
await mkdir(customProfilesDir, { recursive: true });
|
|
||||||
await writeFile(
|
|
||||||
join(customProfilesDir, 'bogus.yaml'),
|
|
||||||
[
|
|
||||||
'id: bogus',
|
|
||||||
'title: Bogus',
|
|
||||||
'description: bad system',
|
|
||||||
'lead: orchestrator',
|
|
||||||
'floor: [orchestrator]',
|
|
||||||
'roster:',
|
|
||||||
' - class: orchestrator',
|
|
||||||
' - class: not-a-real-persona-xyz',
|
|
||||||
' reports_to: orchestrator',
|
|
||||||
'',
|
|
||||||
].join('\n'),
|
|
||||||
);
|
|
||||||
await expect(
|
|
||||||
runProvision('bogus', {
|
|
||||||
mosaicHome: dir,
|
|
||||||
profilesDir: customProfilesDir,
|
|
||||||
rolesDir,
|
|
||||||
overrideDir: join(dir, 'roles.local'),
|
|
||||||
}),
|
|
||||||
).rejects.toThrow(/not-a-real-persona-xyz|not a known persona class/);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('--write protection', () => {
|
|
||||||
it('refuses to clobber an existing roster.yaml without --force', async () => {
|
|
||||||
const home = await freshMosaicHome();
|
|
||||||
try {
|
|
||||||
const rosterPath = join(home, 'fleet', 'roster.yaml');
|
|
||||||
await writeFile(rosterPath, 'version: 1\n# operator customizations\n');
|
|
||||||
await expect(
|
|
||||||
runProvision('software-delivery', { mosaicHome: home, profilesDir, rolesDir, write: true }),
|
|
||||||
).rejects.toThrow(/Refusing to overwrite/);
|
|
||||||
// The original file is untouched.
|
|
||||||
const { readFile } = await import('node:fs/promises');
|
|
||||||
expect(await readFile(rosterPath, 'utf8')).toContain('operator customizations');
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('--write --force overwrites an existing roster', async () => {
|
|
||||||
const home = await freshMosaicHome();
|
|
||||||
try {
|
|
||||||
const rosterPath = join(home, 'fleet', 'roster.yaml');
|
|
||||||
await writeFile(rosterPath, 'version: 1\n# old\n');
|
|
||||||
const result = await runProvision('software-delivery', {
|
|
||||||
mosaicHome: home,
|
|
||||||
profilesDir,
|
|
||||||
rolesDir,
|
|
||||||
write: true,
|
|
||||||
force: true,
|
|
||||||
});
|
|
||||||
expect(result.wrote).toBe(rosterPath);
|
|
||||||
const parsed = await loadFleetRoster(rosterPath);
|
|
||||||
expect(parsed.agents.length).toBeGreaterThan(0);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('--write to a fresh mosaicHome creates the roster file', async () => {
|
|
||||||
const home = await freshMosaicHome();
|
|
||||||
try {
|
|
||||||
const result = await runProvision('software-delivery', {
|
|
||||||
mosaicHome: home,
|
|
||||||
profilesDir,
|
|
||||||
rolesDir,
|
|
||||||
write: true,
|
|
||||||
});
|
|
||||||
expect(await fileExists(result.wrote!)).toBe(true);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('dry run (no --write) writes nothing', async () => {
|
|
||||||
const home = await freshMosaicHome();
|
|
||||||
try {
|
|
||||||
const result = await runProvision('software-delivery', {
|
|
||||||
mosaicHome: home,
|
|
||||||
profilesDir,
|
|
||||||
rolesDir,
|
|
||||||
});
|
|
||||||
expect(result.wrote).toBeUndefined();
|
|
||||||
expect(await fileExists(join(home, 'fleet', 'roster.yaml'))).toBe(false);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,406 +0,0 @@
|
|||||||
/**
|
|
||||||
* `mosaic fleet provision --profile <id>` — turn a declared SYSTEM TYPE (a
|
|
||||||
* profile) into a concrete fleet roster (North Star H3).
|
|
||||||
*
|
|
||||||
* A profile (fleet/profiles/<id>.yaml) is a DECLARATIVE mapping from a system
|
|
||||||
* type to a persona roster + org topology (H2). This command MATERIALIZES that
|
|
||||||
* declaration into the concrete `roster.yaml` shape the live fleet consumes — the
|
|
||||||
* same shape `fleet.ts` parses (version/transport/tmux/defaults/runtimes/agents).
|
|
||||||
*
|
|
||||||
* DRY-RUN-FIRST + REVIEWABLE: with no --write it prints the roster it WOULD
|
|
||||||
* generate plus a topology summary and writes nothing. --write persists it, and
|
|
||||||
* REFUSES to clobber an existing roster.yaml without --force (protects operator
|
|
||||||
* customizations).
|
|
||||||
*
|
|
||||||
* DRY: profile parsing/validation is reused wholesale from fleet-profiles.ts
|
|
||||||
* (loadProfile/validateProfile) and persona resolution from fleet-personas.ts
|
|
||||||
* (resolvePersona, override-aware). This module owns ONLY the profile→roster
|
|
||||||
* generation policy, documented inline below so each default is reviewable.
|
|
||||||
*/
|
|
||||||
|
|
||||||
import { access, mkdir, writeFile } from 'node:fs/promises';
|
|
||||||
import { constants } from 'node:fs';
|
|
||||||
import { homedir } from 'node:os';
|
|
||||||
import { dirname, join } from 'node:path';
|
|
||||||
import type { Command } from 'commander';
|
|
||||||
import YAML from 'yaml';
|
|
||||||
import {
|
|
||||||
loadProfile,
|
|
||||||
validateProfile,
|
|
||||||
type FleetProfile,
|
|
||||||
type ProfileRosterEntry,
|
|
||||||
defaultProfilesDir,
|
|
||||||
defaultRolesDir,
|
|
||||||
listPersonaClassesWithOverrides,
|
|
||||||
} from './fleet-profiles.js';
|
|
||||||
import {
|
|
||||||
defaultOverrideDir,
|
|
||||||
extractClassesFromDir,
|
|
||||||
resolvePersonaFrom,
|
|
||||||
type PersonaLayer,
|
|
||||||
} from './fleet-personas.js';
|
|
||||||
|
|
||||||
function defaultMosaicHome(): string {
|
|
||||||
return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
|
||||||
}
|
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
// GENERATION RULES — each default below is intentionally simple and documented
|
|
||||||
// so a reviewer can ratify or override the policy. See the PR body for the open
|
|
||||||
// runtime-per-class question (RULE 4).
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
/**
|
|
||||||
* RULE 4 — Runtime assignment policy (THE one open design question).
|
|
||||||
*
|
|
||||||
* Default: EVERY seat → `runtime: claude`. Claude runs every persona, so it is
|
|
||||||
* the safe universal default and guarantees a structurally-valid, launchable
|
|
||||||
* roster regardless of how the policy ultimately lands. We deliberately do NOT
|
|
||||||
* hardcode pi / gpt-5.5 per class here. The live roster today runs coders on
|
|
||||||
* pi + openai-codex/gpt-5.5:high — whether provisioning should encode a
|
|
||||||
* class→runtime/model map (and WHERE: the profile schema vs a separate
|
|
||||||
* runtime-policy file) is flagged in the PR body for ratification.
|
|
||||||
*
|
|
||||||
* Centralized so changing the policy is a ONE-edit change. If a future profile
|
|
||||||
* entry (or persona) declares a runtime/model preference, honor it here; until
|
|
||||||
* then everything defaults to claude.
|
|
||||||
*/
|
|
||||||
export const DEFAULT_RUNTIME = 'claude';
|
|
||||||
|
|
||||||
/** Result of applying the runtime policy to one seat. */
|
|
||||||
interface RuntimeChoice {
|
|
||||||
runtime: string;
|
|
||||||
modelHint?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* The single centralized runtime-policy function. Today it returns the universal
|
|
||||||
* `claude` default for every seat. To encode a class→runtime/model map later,
|
|
||||||
* edit ONLY this function (and/or extend the profile schema and read it here).
|
|
||||||
*/
|
|
||||||
export function resolveSeatRuntime(
|
|
||||||
_klass: string,
|
|
||||||
_isFloor: boolean,
|
|
||||||
_isLead: boolean,
|
|
||||||
): RuntimeChoice {
|
|
||||||
return { runtime: DEFAULT_RUNTIME };
|
|
||||||
}
|
|
||||||
|
|
||||||
/** One generated seat, fully resolved for emission + topology display. */
|
|
||||||
export interface GeneratedSeat {
|
|
||||||
name: string;
|
|
||||||
className: string;
|
|
||||||
runtime: string;
|
|
||||||
modelHint?: string;
|
|
||||||
persistentPersona?: boolean;
|
|
||||||
resetBetweenTasks?: boolean;
|
|
||||||
/** Topology edge from the profile (NOT emitted to roster.yaml — see RULE 6). */
|
|
||||||
reportsTo?: string;
|
|
||||||
/** Which persona layer the class resolved from (baseline/override). */
|
|
||||||
personaLayer: PersonaLayer;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface GenerateRosterResult {
|
|
||||||
seats: GeneratedSeat[];
|
|
||||||
/** The roster.yaml text (parser-valid, drop-in). */
|
|
||||||
yaml: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface ProvisionOptions {
|
|
||||||
/** Materialize the entire profile roster (multiplicity expanded). */
|
|
||||||
full?: boolean;
|
|
||||||
mosaicHome?: string;
|
|
||||||
/** Test overrides — mirror fleet-profiles LoadProfilesOptions. */
|
|
||||||
profilesDir?: string;
|
|
||||||
rolesDir?: string;
|
|
||||||
overrideDir?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
function resolveDirs(opts: ProvisionOptions): {
|
|
||||||
mosaicHome: string;
|
|
||||||
profilesDir: string;
|
|
||||||
rolesDir: string;
|
|
||||||
overrideDir: string;
|
|
||||||
} {
|
|
||||||
const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
|
|
||||||
return {
|
|
||||||
mosaicHome,
|
|
||||||
profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
|
|
||||||
rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
|
|
||||||
overrideDir: opts.overrideDir ?? defaultOverrideDir(mosaicHome),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* RULE 1 — Seat naming. multiplicity 1 → name = class (e.g. `planner`).
|
|
||||||
* multiplicity N>1 → `<class>0`,`<class>1`,… (e.g. `code` ×2 → code0/code1).
|
|
||||||
* Names are deterministic, following profile roster order.
|
|
||||||
*/
|
|
||||||
function seatNames(entry: ProfileRosterEntry): string[] {
|
|
||||||
if (entry.multiplicity <= 1) return [entry.class];
|
|
||||||
return Array.from({ length: entry.multiplicity }, (_, i) => `${entry.class}${i}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Generate the concrete seats + roster.yaml for a validated profile.
|
|
||||||
*
|
|
||||||
* Seat selection:
|
|
||||||
* --full → the ENTIRE profile roster, multiplicity expanded.
|
|
||||||
* default → ONLY the `floor` classes (the always-staffed minimum), matching
|
|
||||||
* the profile note "two-agent floor always staffed; every other seat
|
|
||||||
* added on demand."
|
|
||||||
*
|
|
||||||
* Per-seat flags:
|
|
||||||
* RULE 2 persistent_persona: true for floor classes AND the lead; else omitted.
|
|
||||||
* RULE 3 reset_between_tasks: true for non-floor, non-lead execution seats;
|
|
||||||
* floor/lead omit it (mirrors today's coders resetting while the
|
|
||||||
* orchestrator/enhancer do not).
|
|
||||||
* RULE 4 runtime: via resolveSeatRuntime (defaults claude).
|
|
||||||
* RULE 6 reports_to: tracked on the seat for the topology summary but NOT
|
|
||||||
* emitted to roster.yaml — the fleet.ts parser rejects unknown agent
|
|
||||||
* keys, so writing reports_to would break round-trip. Confirmed against
|
|
||||||
* normalizeAgent's allow-list in fleet.ts.
|
|
||||||
*
|
|
||||||
* Persona resolution: every emitted class is resolved override-aware via
|
|
||||||
* resolvePersona so we can (a) record the layer for the summary and (b) refuse
|
|
||||||
* to emit a roster that references a nonexistent persona.
|
|
||||||
*/
|
|
||||||
export async function generateRoster(
|
|
||||||
profile: FleetProfile,
|
|
||||||
opts: ProvisionOptions,
|
|
||||||
): Promise<GenerateRosterResult> {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const floor = new Set(profile.floor);
|
|
||||||
const lead = profile.lead;
|
|
||||||
|
|
||||||
const selected: ProfileRosterEntry[] = opts.full
|
|
||||||
? profile.roster
|
|
||||||
: profile.roster.filter((e) => floor.has(e.class));
|
|
||||||
|
|
||||||
// Scan the persona directories ONCE, then resolve every roster entry against
|
|
||||||
// the in-memory maps. resolvePersona() would otherwise re-scan both dirs per
|
|
||||||
// entry — O(entries × files) redundant reads that push --full provisioning
|
|
||||||
// past the test timeout on slow/contended filesystems.
|
|
||||||
const [base, over] = await Promise.all([
|
|
||||||
extractClassesFromDir(rolesDir),
|
|
||||||
extractClassesFromDir(overrideDir),
|
|
||||||
]);
|
|
||||||
|
|
||||||
const seats: GeneratedSeat[] = [];
|
|
||||||
for (const entry of selected) {
|
|
||||||
const isFloor = floor.has(entry.class);
|
|
||||||
const isLead = entry.class === lead;
|
|
||||||
|
|
||||||
const resolved = await resolvePersonaFrom(entry.class, { rolesDir, overrideDir, base, over });
|
|
||||||
if (!resolved) {
|
|
||||||
// Defensive: validateProfile already guards this, but a class can resolve
|
|
||||||
// for membership yet have no readable file. Fail loudly rather than emit a
|
|
||||||
// roster pointing at a persona we cannot load.
|
|
||||||
throw new Error(
|
|
||||||
`Cannot provision: roster class "${entry.class}" does not resolve to a readable persona.`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
const runtimeChoice = resolveSeatRuntime(entry.class, isFloor, isLead);
|
|
||||||
for (const name of seatNames(entry)) {
|
|
||||||
const seat: GeneratedSeat = {
|
|
||||||
name,
|
|
||||||
className: entry.class,
|
|
||||||
runtime: runtimeChoice.runtime,
|
|
||||||
personaLayer: resolved.layer,
|
|
||||||
};
|
|
||||||
if (runtimeChoice.modelHint) seat.modelHint = runtimeChoice.modelHint;
|
|
||||||
if (isFloor || isLead) seat.persistentPersona = true;
|
|
||||||
if (!isFloor && !isLead) seat.resetBetweenTasks = true;
|
|
||||||
if (entry.reportsTo) seat.reportsTo = entry.reportsTo;
|
|
||||||
seats.push(seat);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
if (seats.length === 0) {
|
|
||||||
throw new Error(
|
|
||||||
`Profile "${profile.id}" produced no seats. ` +
|
|
||||||
(opts.full ? 'Its roster is empty.' : 'No floor seats are defined — try --full.'),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
return { seats, yaml: renderRosterYaml(seats) };
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* RULE 5 — Standard roster scaffolding. We emit the same generic, non-personal
|
|
||||||
* scaffold the committed example presets use (socket_name: mosaic-fleet,
|
|
||||||
* holder_session: _holder, working_directory: ~, claude + pi runtimes) so the
|
|
||||||
* output is a drop-in valid roster. No operator-personal data is copied.
|
|
||||||
*
|
|
||||||
* Built via the `yaml` lib (same serializer the parser uses) so the result
|
|
||||||
* round-trips. reports_to is intentionally NOT included on agents (RULE 6).
|
|
||||||
*/
|
|
||||||
function renderRosterYaml(seats: GeneratedSeat[]): string {
|
|
||||||
const agents = seats.map((s) => {
|
|
||||||
const a: Record<string, unknown> = {
|
|
||||||
name: s.name,
|
|
||||||
runtime: s.runtime,
|
|
||||||
class: s.className,
|
|
||||||
};
|
|
||||||
if (s.persistentPersona) a['persistent_persona'] = true;
|
|
||||||
if (s.modelHint) a['model_hint'] = s.modelHint;
|
|
||||||
if (s.resetBetweenTasks) a['reset_between_tasks'] = true;
|
|
||||||
return a;
|
|
||||||
});
|
|
||||||
|
|
||||||
const doc = {
|
|
||||||
version: 1,
|
|
||||||
transport: 'tmux',
|
|
||||||
tmux: { socket_name: 'mosaic-fleet', holder_session: '_holder' },
|
|
||||||
defaults: { working_directory: '~' },
|
|
||||||
runtimes: {
|
|
||||||
claude: { reset_command: '/clear' },
|
|
||||||
pi: { reset_command: '/new' },
|
|
||||||
},
|
|
||||||
agents,
|
|
||||||
};
|
|
||||||
|
|
||||||
return YAML.stringify(doc);
|
|
||||||
}
|
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
// Validation — reuse fleet-profiles.validateProfile (override-aware classes) and
|
|
||||||
// name any unresolved class clearly. Never generate a roster referencing a
|
|
||||||
// nonexistent persona.
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Validate the profile against the override-aware persona library. Throws with a
|
|
||||||
* clear, class-naming message if any referenced class is unresolved.
|
|
||||||
*/
|
|
||||||
export async function validateProfileForProvision(
|
|
||||||
profile: FleetProfile,
|
|
||||||
opts: ProvisionOptions,
|
|
||||||
): Promise<void> {
|
|
||||||
const { rolesDir, overrideDir } = resolveDirs(opts);
|
|
||||||
const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
|
|
||||||
const problems = validateProfile(profile, validClasses);
|
|
||||||
if (problems.length > 0) {
|
|
||||||
throw new Error(
|
|
||||||
`Profile "${profile.id}" is invalid; cannot provision:\n - ${problems.join('\n - ')}`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
// Topology summary (printed in dry-run and after write).
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
function formatTopologySummary(seats: GeneratedSeat[]): string {
|
|
||||||
const lines: string[] = [];
|
|
||||||
lines.push(`Topology (${seats.length} seat(s)):`);
|
|
||||||
for (const s of seats) {
|
|
||||||
const reports = s.reportsTo ? `reports_to=${s.reportsTo}` : 'reports_to=- (lead)';
|
|
||||||
lines.push(
|
|
||||||
` - ${s.name}\tclass=${s.className}\truntime=${s.runtime}\t${reports}\tpersona=${s.personaLayer}`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
return lines.join('\n');
|
|
||||||
}
|
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
// CLI wiring — mirror registerFleetProfileCommand / registerFleetPersonaCommand.
|
|
||||||
// ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
export interface ProvisionRunResult {
|
|
||||||
yaml: string;
|
|
||||||
summary: string;
|
|
||||||
wrote?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Core provision flow shared by the CLI: load + validate the profile, generate
|
|
||||||
* the roster, optionally write it. Returns the artifacts for printing/testing.
|
|
||||||
*/
|
|
||||||
export async function runProvision(
|
|
||||||
profileId: string,
|
|
||||||
opts: ProvisionOptions & { write?: boolean; force?: boolean },
|
|
||||||
): Promise<ProvisionRunResult> {
|
|
||||||
const dirs = resolveDirs(opts);
|
|
||||||
const profile = await loadProfile(profileId, {
|
|
||||||
mosaicHome: dirs.mosaicHome,
|
|
||||||
profilesDir: dirs.profilesDir,
|
|
||||||
rolesDir: dirs.rolesDir,
|
|
||||||
overrideDir: dirs.overrideDir,
|
|
||||||
});
|
|
||||||
// loadProfile already validates, but re-run with our explicit error wording so
|
|
||||||
// an unresolved class is named clearly even if invoked directly.
|
|
||||||
await validateProfileForProvision(profile, opts);
|
|
||||||
|
|
||||||
const { seats, yaml } = await generateRoster(profile, opts);
|
|
||||||
const summary = formatTopologySummary(seats);
|
|
||||||
|
|
||||||
if (!opts.write) {
|
|
||||||
return { yaml, summary };
|
|
||||||
}
|
|
||||||
|
|
||||||
const rosterPath = join(dirs.mosaicHome, 'fleet', 'roster.yaml');
|
|
||||||
if (!opts.force) {
|
|
||||||
let exists = false;
|
|
||||||
try {
|
|
||||||
await access(rosterPath, constants.F_OK);
|
|
||||||
exists = true;
|
|
||||||
} catch {
|
|
||||||
exists = false;
|
|
||||||
}
|
|
||||||
if (exists) {
|
|
||||||
throw new Error(
|
|
||||||
`Refusing to overwrite existing roster: ${rosterPath}. ` +
|
|
||||||
`Pass --force to overwrite, or edit it by hand.`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
await mkdir(dirname(rosterPath), { recursive: true });
|
|
||||||
await writeFile(rosterPath, yaml, 'utf8');
|
|
||||||
return { yaml, summary, wrote: rosterPath };
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Register `provision` under an existing `fleet` command. `mosaicHomeFor`
|
|
||||||
* resolves the active --mosaic-home (parent flag) at call time, exactly like the
|
|
||||||
* profile/persona/backlog subcommands.
|
|
||||||
*/
|
|
||||||
export function registerFleetProvisionCommand(
|
|
||||||
fleetCmd: Command,
|
|
||||||
mosaicHomeFor: () => string,
|
|
||||||
): Command {
|
|
||||||
const provisionCmd = fleetCmd
|
|
||||||
.command('provision')
|
|
||||||
.description('Materialize a roster.yaml from a system-type profile (H3). DRY-RUN by default.')
|
|
||||||
.requiredOption('--profile <id>', 'System-type profile id to provision')
|
|
||||||
.option('--full', 'Materialize the entire profile roster (default: floor seats only)')
|
|
||||||
.option('--write', 'Write the generated roster to <mosaicHome>/fleet/roster.yaml')
|
|
||||||
.option('--force', 'Overwrite an existing roster.yaml (requires --write)')
|
|
||||||
.action(async (opts: { profile: string; full?: boolean; write?: boolean; force?: boolean }) => {
|
|
||||||
try {
|
|
||||||
const result = await runProvision(opts.profile, {
|
|
||||||
mosaicHome: mosaicHomeFor(),
|
|
||||||
full: opts.full,
|
|
||||||
write: opts.write,
|
|
||||||
force: opts.force,
|
|
||||||
});
|
|
||||||
if (result.wrote) {
|
|
||||||
console.log(`Wrote roster: ${result.wrote}`);
|
|
||||||
console.log('');
|
|
||||||
console.log(result.summary);
|
|
||||||
} else {
|
|
||||||
// DRY RUN: print the roster it WOULD generate + topology, write nothing.
|
|
||||||
console.log('# DRY RUN — no files written. Re-run with --write to persist.');
|
|
||||||
console.log(result.yaml.trimEnd());
|
|
||||||
console.log('');
|
|
||||||
console.log(result.summary);
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return provisionCmd;
|
|
||||||
}
|
|
||||||
@@ -82,9 +82,6 @@ describe('registerFleetCommand', () => {
|
|||||||
'init',
|
'init',
|
||||||
'install',
|
'install',
|
||||||
'install-systemd',
|
'install-systemd',
|
||||||
'persona',
|
|
||||||
'profile',
|
|
||||||
'provision',
|
|
||||||
'ps',
|
'ps',
|
||||||
'remove',
|
'remove',
|
||||||
'restart',
|
'restart',
|
||||||
@@ -95,28 +92,6 @@ describe('registerFleetCommand', () => {
|
|||||||
]);
|
]);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('registers the profile subcommand with list and show', () => {
|
|
||||||
const program = buildProgram();
|
|
||||||
const fleet = program.commands.find((command) => command.name() === 'fleet');
|
|
||||||
const profile = fleet!.commands.find((command) => command.name() === 'profile');
|
|
||||||
|
|
||||||
expect(profile).toBeDefined();
|
|
||||||
expect(profile!.commands.map((command) => command.name()).sort()).toEqual(['list', 'show']);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('registers the persona subcommand with list, show, and customize', () => {
|
|
||||||
const program = buildProgram();
|
|
||||||
const fleet = program.commands.find((command) => command.name() === 'fleet');
|
|
||||||
const persona = fleet!.commands.find((command) => command.name() === 'persona');
|
|
||||||
|
|
||||||
expect(persona).toBeDefined();
|
|
||||||
expect(persona!.commands.map((command) => command.name()).sort()).toEqual([
|
|
||||||
'customize',
|
|
||||||
'list',
|
|
||||||
'show',
|
|
||||||
]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('registers the backlog subcommand with its operations', () => {
|
it('registers the backlog subcommand with its operations', () => {
|
||||||
const program = buildProgram();
|
const program = buildProgram();
|
||||||
const fleet = program.commands.find((command) => command.name() === 'fleet');
|
const fleet = program.commands.find((command) => command.name() === 'fleet');
|
||||||
@@ -247,8 +222,6 @@ describe('fleet roster parsing', () => {
|
|||||||
expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
|
expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
|
||||||
[
|
[
|
||||||
'MOSAIC_AGENT_NAME=coder0',
|
'MOSAIC_AGENT_NAME=coder0',
|
||||||
// Reflects the roster's non-default `class: implementer` (A3a).
|
|
||||||
'MOSAIC_AGENT_CLASS=implementer',
|
|
||||||
'MOSAIC_AGENT_RUNTIME=codex',
|
'MOSAIC_AGENT_RUNTIME=codex',
|
||||||
'MOSAIC_AGENT_MODEL=',
|
'MOSAIC_AGENT_MODEL=',
|
||||||
'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
|
'MOSAIC_AGENT_WORKDIR=/srv/mosaic',
|
||||||
@@ -258,40 +231,6 @@ describe('fleet roster parsing', () => {
|
|||||||
);
|
);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('emits MOSAIC_AGENT_CLASS=worker for an agent that declares no class', async () => {
|
|
||||||
cleanup = await tempDir();
|
|
||||||
const rosterPath = join(cleanup, 'roster.json');
|
|
||||||
await writeFile(
|
|
||||||
rosterPath,
|
|
||||||
JSON.stringify({
|
|
||||||
version: 1,
|
|
||||||
transport: 'tmux',
|
|
||||||
agents: [{ name: 'coder0', runtime: 'codex' }],
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
const roster = await loadFleetRoster(rosterPath);
|
|
||||||
expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toContain(
|
|
||||||
'MOSAIC_AGENT_CLASS=worker\n',
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('shell-escapes MOSAIC_AGENT_CLASS so a launcher reads it verbatim', async () => {
|
|
||||||
cleanup = await tempDir();
|
|
||||||
const rosterPath = join(cleanup, 'roster.json');
|
|
||||||
await writeFile(
|
|
||||||
rosterPath,
|
|
||||||
JSON.stringify({
|
|
||||||
version: 1,
|
|
||||||
transport: 'tmux',
|
|
||||||
agents: [{ name: 'coder0', runtime: 'codex', class: 'orchestrator' }],
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
const roster = await loadFleetRoster(rosterPath);
|
|
||||||
expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toContain(
|
|
||||||
'MOSAIC_AGENT_CLASS=orchestrator\n',
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('preserves site-owned agent EnvironmentFile overrides while refreshing roster keys', () => {
|
it('preserves site-owned agent EnvironmentFile overrides while refreshing roster keys', () => {
|
||||||
const generated = [
|
const generated = [
|
||||||
'MOSAIC_AGENT_NAME=coder0',
|
'MOSAIC_AGENT_NAME=coder0',
|
||||||
@@ -323,28 +262,6 @@ describe('fleet roster parsing', () => {
|
|||||||
);
|
);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('updates (does not duplicate) MOSAIC_AGENT_CLASS on re-launch', () => {
|
|
||||||
const generated = [
|
|
||||||
'MOSAIC_AGENT_NAME=coder0',
|
|
||||||
'MOSAIC_AGENT_CLASS=orchestrator',
|
|
||||||
'MOSAIC_AGENT_RUNTIME=codex',
|
|
||||||
'',
|
|
||||||
].join('\n');
|
|
||||||
const existing = [
|
|
||||||
'MOSAIC_AGENT_NAME=coder0',
|
|
||||||
'MOSAIC_AGENT_CLASS=worker',
|
|
||||||
'MOSAIC_AGENT_RUNTIME=codex',
|
|
||||||
'',
|
|
||||||
].join('\n');
|
|
||||||
|
|
||||||
const merged = mergeAgentEnv(generated, existing);
|
|
||||||
// mergeAgentEnv keys by VAR name, so the regenerated CLASS wins and there is
|
|
||||||
// exactly one MOSAIC_AGENT_CLASS line (no stale worker value left behind).
|
|
||||||
expect(merged).toContain('MOSAIC_AGENT_CLASS=orchestrator');
|
|
||||||
expect(merged).not.toContain('MOSAIC_AGENT_CLASS=worker');
|
|
||||||
expect(merged.match(/^MOSAIC_AGENT_CLASS=/gm)).toHaveLength(1);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('rejects unknown roster fields instead of silently defaulting', async () => {
|
it('rejects unknown roster fields instead of silently defaulting', async () => {
|
||||||
cleanup = await tempDir();
|
cleanup = await tempDir();
|
||||||
const rosterPath = join(cleanup, 'roster.yaml');
|
const rosterPath = join(cleanup, 'roster.yaml');
|
||||||
|
|||||||
@@ -9,9 +9,6 @@ import type { Command } from 'commander';
|
|||||||
import YAML from 'yaml';
|
import YAML from 'yaml';
|
||||||
import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
|
import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
|
||||||
import { registerFleetBacklogCommand } from './fleet-backlog.js';
|
import { registerFleetBacklogCommand } from './fleet-backlog.js';
|
||||||
import { registerFleetPersonaCommand } from './fleet-personas.js';
|
|
||||||
import { registerFleetProfileCommand } from './fleet-profiles.js';
|
|
||||||
import { registerFleetProvisionCommand } from './fleet-provision.js';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A function that spawns a command with inherited stdio (TTY passthrough).
|
* A function that spawns a command with inherited stdio (TTY passthrough).
|
||||||
@@ -491,9 +488,6 @@ export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string
|
|||||||
const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
|
const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
|
||||||
return [
|
return [
|
||||||
`MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
|
`MOSAIC_AGENT_NAME=${shellEnvValue(agent.name)}`,
|
||||||
// Per-agent class → start-agent-session.sh / launcher reads this to inject the
|
|
||||||
// matching persona contract for the agent's class (default `worker`).
|
|
||||||
`MOSAIC_AGENT_CLASS=${shellEnvValue(agent.className)}`,
|
|
||||||
`MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
|
`MOSAIC_AGENT_RUNTIME=${shellEnvValue(agent.runtime)}`,
|
||||||
// Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
|
// Per-agent model hint → start-agent-session.sh appends `--model <hint>` to
|
||||||
// the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
|
// the `mosaic yolo` launch so workers run on the roster's model (e.g. pi on
|
||||||
@@ -1712,19 +1706,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
|||||||
// fleet/ directory as the roster and heartbeats.
|
// fleet/ directory as the roster and heartbeats.
|
||||||
registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
||||||
|
|
||||||
// System-type profiles (H2): declarative persona roster + topology, resolved
|
|
||||||
// from <mosaicHome>/fleet/profiles/*.yaml using the same --mosaic-home flag.
|
|
||||||
registerFleetProfileCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
|
||||||
|
|
||||||
// Update-surviving persona overrides (H4): baseline fleet/roles/ ⊕ the
|
|
||||||
// PRESERVE-protected fleet/roles.local/ override layer, resolved via the same
|
|
||||||
// --mosaic-home flag.
|
|
||||||
registerFleetPersonaCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
|
||||||
|
|
||||||
// Provisioning (H3): materialize a concrete roster.yaml from a system-type
|
|
||||||
// profile. DRY-RUN by default; --write persists under the same --mosaic-home.
|
|
||||||
registerFleetProvisionCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
|
|
||||||
|
|
||||||
return cmd;
|
return cmd;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -20,7 +20,6 @@ import { homedir } from 'node:os';
|
|||||||
import { join, dirname } from 'node:path';
|
import { join, dirname } from 'node:path';
|
||||||
import type { Command } from 'commander';
|
import type { Command } from 'commander';
|
||||||
import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
|
import { readFleetCommsBlock } from '../fleet/comms-onboarding.js';
|
||||||
import { readPersonaContractBlock } from '../fleet/persona-contract.js';
|
|
||||||
|
|
||||||
const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
|
||||||
|
|
||||||
@@ -385,16 +384,6 @@ For required push/merge/issue-close/release actions, execute without routine con
|
|||||||
// Runtime-specific contract
|
// Runtime-specific contract
|
||||||
parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
|
parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
|
||||||
|
|
||||||
// Persona contract (A3b): when this agent was spawned with a class
|
|
||||||
// (MOSAIC_AGENT_CLASS, exported into the pane env by A3a), inject its resolved
|
|
||||||
// role contract so its identity (mandate + boundaries) is resident from the
|
|
||||||
// first turn. Override-aware via the persona resolver: a user-customized
|
|
||||||
// persona in fleet/roles.local/ wins over the baseline (AC-NS-7 launch proof).
|
|
||||||
// Placed BEFORE fleet comms: identity first, then how-to-reach-peers. No-ops
|
|
||||||
// silently when the class is unset/unknown (mirrors the comms block).
|
|
||||||
const persona = readPersonaContractBlock(mosaicHome, process.env['MOSAIC_AGENT_CLASS']);
|
|
||||||
if (persona) parts.push('\n\n' + persona);
|
|
||||||
|
|
||||||
// Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
|
// Fleet onboarding: when this is a spawned fleet agent (MOSAIC_AGENT_NAME set
|
||||||
// and present in the roster), inject a comms cheat-sheet + peer roster so it
|
// and present in the roster), inject a comms cheat-sheet + peer roster so it
|
||||||
// knows how to reach the orchestrator and its peers from its first turn.
|
// knows how to reach the orchestrator and its peers from its first turn.
|
||||||
|
|||||||
@@ -1,106 +0,0 @@
|
|||||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
|
||||||
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
|
|
||||||
import { tmpdir } from 'node:os';
|
|
||||||
import { join } from 'node:path';
|
|
||||||
import { readPersonaContractBlock } from './persona-contract.js';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Persona-contract launch injection (A3b). Asserts the override-aware resolver
|
|
||||||
* is wired so a customized persona in roles.local/ wins at launch (AC-NS-7), and
|
|
||||||
* that any miss (unset/empty/unknown class, missing file) no-ops silently —
|
|
||||||
* never throws — mirroring readFleetCommsBlock's tolerant contract.
|
|
||||||
*/
|
|
||||||
|
|
||||||
const BASELINE_CODER = `# Coder — fleet role definition
|
|
||||||
|
|
||||||
The **coder** persona (\`class: coder\`, \`domain: engineering\`).
|
|
||||||
|
|
||||||
## Mandate
|
|
||||||
|
|
||||||
BASELINE-MANDATE: implement the assigned lane.
|
|
||||||
`;
|
|
||||||
|
|
||||||
const OVERRIDE_CODER = `# Coder — fleet role definition (override)
|
|
||||||
|
|
||||||
The **coder** persona (\`class: coder\`).
|
|
||||||
|
|
||||||
## Mandate
|
|
||||||
|
|
||||||
OVERRIDE-MANDATE: implement the assigned lane, the user's way.
|
|
||||||
`;
|
|
||||||
|
|
||||||
function makeHome(): string {
|
|
||||||
const root = mkdtempSync(join(tmpdir(), 'mosaic-persona-'));
|
|
||||||
return join(root, 'mosaic-home');
|
|
||||||
}
|
|
||||||
|
|
||||||
function seedBaseline(home: string, klass: string, body: string): void {
|
|
||||||
const dir = join(home, 'fleet', 'roles');
|
|
||||||
mkdirSync(dir, { recursive: true });
|
|
||||||
writeFileSync(join(dir, `${klass}.md`), body);
|
|
||||||
}
|
|
||||||
|
|
||||||
function seedOverride(home: string, klass: string, body: string): void {
|
|
||||||
const dir = join(home, 'fleet', 'roles.local');
|
|
||||||
mkdirSync(dir, { recursive: true });
|
|
||||||
writeFileSync(join(dir, `${klass}.md`), body);
|
|
||||||
}
|
|
||||||
|
|
||||||
describe('readPersonaContractBlock — launch-time persona injection (A3b)', () => {
|
|
||||||
let home: string;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
home = makeHome();
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => {
|
|
||||||
// root is the parent of mosaic-home
|
|
||||||
rmSync(join(home, '..'), { recursive: true, force: true });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('injects the baseline persona when the class has a fleet/roles/<class>.md', () => {
|
|
||||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
|
||||||
const block = readPersonaContractBlock(home, 'coder');
|
|
||||||
expect(block).toContain('# Persona Contract (coder)');
|
|
||||||
expect(block).toContain('BASELINE-MANDATE');
|
|
||||||
expect(block).toContain('baseline `fleet/roles/` layer');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('OVERRIDE WINS: roles.local/<class>.md content is injected over the baseline (AC-NS-7)', () => {
|
|
||||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
|
||||||
seedOverride(home, 'coder', OVERRIDE_CODER);
|
|
||||||
const block = readPersonaContractBlock(home, 'coder');
|
|
||||||
expect(block).toContain('# Persona Contract (coder)');
|
|
||||||
expect(block).toContain('OVERRIDE-MANDATE'); // override body present
|
|
||||||
expect(block).not.toContain('BASELINE-MANDATE'); // baseline NOT used
|
|
||||||
expect(block).toContain('roles.local'); // layer note names the override layer
|
|
||||||
});
|
|
||||||
|
|
||||||
it('injects an override-only (user-added) persona with no baseline at all', () => {
|
|
||||||
seedOverride(home, 'reviewer', '# Reviewer\n\n(`class: reviewer`)\n\nCUSTOM-ROLE.\n');
|
|
||||||
const block = readPersonaContractBlock(home, 'reviewer');
|
|
||||||
expect(block).toContain('# Persona Contract (reviewer)');
|
|
||||||
expect(block).toContain('CUSTOM-ROLE');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('no-ops (empty string) when the class is undefined', () => {
|
|
||||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
|
||||||
expect(readPersonaContractBlock(home, undefined)).toBe('');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('no-ops (empty string) when the class is empty/whitespace', () => {
|
|
||||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
|
||||||
expect(readPersonaContractBlock(home, '')).toBe('');
|
|
||||||
expect(readPersonaContractBlock(home, ' ')).toBe('');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('no-ops (empty string) for an unknown class with no role file', () => {
|
|
||||||
seedBaseline(home, 'coder', BASELINE_CODER);
|
|
||||||
expect(readPersonaContractBlock(home, 'nonexistent')).toBe('');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('no-ops (empty string, no throw) when no roles directories exist at all', () => {
|
|
||||||
expect(() => readPersonaContractBlock(home, 'coder')).not.toThrow();
|
|
||||||
expect(readPersonaContractBlock(home, 'coder')).toBe('');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,63 +0,0 @@
|
|||||||
/**
|
|
||||||
* Persona-contract injection at launch (North Star A3b).
|
|
||||||
*
|
|
||||||
* A spawned fleet agent should boot already knowing WHO it is: its class's role
|
|
||||||
* contract (mandate + boundaries). The companion goal A3a exports the agent's
|
|
||||||
* resolved class into the pane env as `MOSAIC_AGENT_CLASS`; here we read that
|
|
||||||
* class at launch (composeContract → system prompt) and inject the resolved
|
|
||||||
* persona contract so the identity is resident from the agent's first turn.
|
|
||||||
*
|
|
||||||
* OVERRIDE-AWARE: resolution goes through fleet-personas' resolver, so a
|
|
||||||
* user-customized persona in the PRESERVE-protected `fleet/roles.local/` layer
|
|
||||||
* WINS over the baseline `fleet/roles/` of the same class. That is the
|
|
||||||
* launch-time proof of AC-NS-7 — a customized persona actually reaches the model
|
|
||||||
* when the agent boots, not just in `mosaic fleet persona show`.
|
|
||||||
*
|
|
||||||
* Tolerant by contract (mirrors readFleetCommsBlock): an empty/missing class, an
|
|
||||||
* unknown class, or a missing role file all yield '' so the launcher no-ops
|
|
||||||
* silently. This MUST never throw during launch.
|
|
||||||
*
|
|
||||||
* Standalone module (no fleet.ts import) to keep launch.ts's prompt path free of
|
|
||||||
* the heavy fleet command module; it depends only on the lightweight persona
|
|
||||||
* resolver.
|
|
||||||
*/
|
|
||||||
|
|
||||||
import {
|
|
||||||
resolvePersonaSync,
|
|
||||||
defaultRolesDir,
|
|
||||||
defaultOverrideDir,
|
|
||||||
} from '../commands/fleet-personas.js';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Resolve `klass`'s persona contract (override-aware) and render it as a
|
|
||||||
* clearly-delimited launch block. Returns '' on any miss (falsy class, unknown
|
|
||||||
* class, missing/unreadable file) so composeContract can push it unconditionally
|
|
||||||
* and have it no-op silently. Never throws.
|
|
||||||
*/
|
|
||||||
export function readPersonaContractBlock(mosaicHome: string, klass: string | undefined): string {
|
|
||||||
if (!klass || !klass.trim()) return '';
|
|
||||||
let resolved: ReturnType<typeof resolvePersonaSync>;
|
|
||||||
try {
|
|
||||||
resolved = resolvePersonaSync(klass.trim(), {
|
|
||||||
rolesDir: defaultRolesDir(mosaicHome),
|
|
||||||
overrideDir: defaultOverrideDir(mosaicHome),
|
|
||||||
});
|
|
||||||
} catch {
|
|
||||||
// Best-effort onboarding: a resolver hiccup must not abort the launch.
|
|
||||||
return '';
|
|
||||||
}
|
|
||||||
if (!resolved) return '';
|
|
||||||
|
|
||||||
const layerNote =
|
|
||||||
resolved.layer === 'override'
|
|
||||||
? '_(resolved from the `fleet/roles.local/` override layer — wins over baseline)_'
|
|
||||||
: '_(resolved from the baseline `fleet/roles/` layer)_';
|
|
||||||
|
|
||||||
return `# Persona Contract (${resolved.klass})
|
|
||||||
|
|
||||||
${layerNote}
|
|
||||||
|
|
||||||
You are operating as the **${resolved.klass}** persona. The role contract below is your identity — its mandate and boundaries govern what you own and what you must not do for this assignment.
|
|
||||||
|
|
||||||
${resolved.content.trim()}`;
|
|
||||||
}
|
|
||||||
Reference in New Issue
Block a user