From 92e4ee189a9c7a2a32c6f700e3d44d76facbb3e4 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Wed, 24 Jun 2026 11:11:00 -0500 Subject: [PATCH] feat(fleet): update-surviving persona overrides (roles.local layer, resolver, persona CLI) (H4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a PRESERVE-protected persona override layer at /fleet/roles.local/ that survives `mosaic update` while baseline fleet/roles/ keeps reseeding. - fleet-personas.ts: shared class-extraction (single source of truth, DRY with fleet-profiles.ts), resolvePersona (override wins, baseline fallback), listPersonaClasses (baseline ⊕ override union), personaStatus (baseline/overridden/custom), and the `fleet persona list|show|customize` CLI. - fleet-profiles.ts: roster validation now uses the override-aware union so a profile can reference a user-customized or user-ADDED persona; the old listPersonaClasses(rolesDir) is kept as a thin delegate to the shared helper. - install.sh: add fleet/roles.local to PRESERVE_PATHS (AC-NS-7 guarantee). - specs: override-wins, custom-add, status classification, AC-NS-7 update-survival simulation, and profile-validation-accepts-custom-persona. Co-Authored-By: Claude Opus 4.8 --- packages/mosaic/framework/install.sh | 9 +- .../src/commands/fleet-personas.spec.ts | 210 +++++++++ .../mosaic/src/commands/fleet-personas.ts | 413 ++++++++++++++++++ .../mosaic/src/commands/fleet-profiles.ts | 87 ++-- packages/mosaic/src/commands/fleet.spec.ts | 14 + packages/mosaic/src/commands/fleet.ts | 6 + 6 files changed, 688 insertions(+), 51 deletions(-) create mode 100644 packages/mosaic/src/commands/fleet-personas.spec.ts create mode 100644 packages/mosaic/src/commands/fleet-personas.ts diff --git a/packages/mosaic/framework/install.sh b/packages/mosaic/framework/install.sh index 478d5b0..223b58b 100755 --- a/packages/mosaic/framework/install.sh +++ b/packages/mosaic/framework/install.sh @@ -37,7 +37,14 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}" # packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update # 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. -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 # user must not edit them; a divergent copy is backed up once before overwrite). diff --git a/packages/mosaic/src/commands/fleet-personas.spec.ts b/packages/mosaic/src/commands/fleet-personas.spec.ts new file mode 100644 index 0000000..7421d68 --- /dev/null +++ b/packages/mosaic/src/commands/fleet-personas.spec.ts @@ -0,0 +1,210 @@ +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([]); + }); +}); diff --git a/packages/mosaic/src/commands/fleet-personas.ts b/packages/mosaic/src/commands/fleet-personas.ts new file mode 100644 index 0000000..6d9bc46 --- /dev/null +++ b/packages/mosaic/src/commands/fleet-personas.ts @@ -0,0 +1,413 @@ +/** + * Persona override layer + resolver (North Star H4). + * + * Baseline personas are markdown role contracts seeded by the framework into + * /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: + * /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 { 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; + /** For classes whose file carries a marker, the file + domain that defined it. */ + byClass: Map; +} + +/** + * 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 { + const classes = new Set(); + const byClass = new Map(); + let entries: string[]; + try { + entries = await readdir(dir); + } catch { + return { classes, byClass }; + } + + for (const entry of entries) { + if (!entry.endsWith('.md')) continue; + let text: string; + try { + text = await readFile(join(dir, entry), 'utf8'); + } catch { + continue; + } + if (entry === 'LIBRARY.md') { + for (const m of text.matchAll(LIBRARY_ROW)) { + const name = m[1]; + if (name && name !== 'persona') classes.add(name); + } + continue; + } + // 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) }); + } + } + return { classes, byClass }; +} + +export interface PersonaDirs { + /** Baseline roles dir. Defaults to /fleet/roles. */ + rolesDir?: string; + /** Override dir. Defaults to /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> { + const { rolesDir, overrideDir } = resolveDirs(opts); + const [base, over] = await Promise.all([ + extractClassesFromDir(rolesDir), + extractClassesFromDir(overrideDir), + ]); + const union = new Set(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/.md) as a fallback. + * Returns null if neither layer defines the class. + */ +export async function resolvePersona( + klass: string, + opts: PersonaDirs = {}, +): Promise { + const { rolesDir, overrideDir } = resolveDirs(opts); + const [base, over] = await Promise.all([ + extractClassesFromDir(rolesDir), + extractClassesFromDir(overrideDir), + ]); + + const fromLayer = async ( + dir: string, + extracted: DirClasses, + layer: PersonaLayer, + ): Promise => { + // 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')) + ); +} + +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 { + const { rolesDir, overrideDir } = resolveDirs(opts); + const [base, over] = await Promise.all([ + extractClassesFromDir(rolesDir), + extractClassesFromDir(overrideDir), + ]); + + const all = new Set([...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 ` ─────────────────────── + +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 ') + .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 ') + .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; +} diff --git a/packages/mosaic/src/commands/fleet-profiles.ts b/packages/mosaic/src/commands/fleet-profiles.ts index 0d94741..3a9ecb4 100644 --- a/packages/mosaic/src/commands/fleet-profiles.ts +++ b/packages/mosaic/src/commands/fleet-profiles.ts @@ -25,6 +25,11 @@ 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'); @@ -57,57 +62,29 @@ export interface FleetProfile { } /** - * Extract the set of valid persona classes from the role library. + * Extract the set of valid persona classes from a single baseline role dir. * - * Sources (unioned — see module doc for why each is needed): - * 1. inline `` `class: X` `` markers in every roles/*.md (the primary signal; - * a marker may wrap across a newline, e.g. `` `class:\n support-agent` ``). - * 2. persona-name cells from the LIBRARY.md index tables. - * 3. the role filename stems (roles/.md), covering personas whose file - * documents an alias instead of carrying its own marker (planner -> - * orchestrator, decomposition). - * - * Returns a Set so membership checks in the validator are O(1). Missing dir or - * unreadable files degrade gracefully to whatever was found (an empty set makes - * the validator reject every class, which surfaces a clear error). + * 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> { - const classes = new Set(); - let entries: string[]; - try { - entries = await readdir(rolesDir); - } catch { - return classes; - } - // Match `class: X` even when the value wrapped onto the next line. Allow - // surrounding backtick(s); the value is a single kebab-case token. - const inlineMarker = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g; - // LIBRARY.md persona rows: first table cell is the persona name. - const libraryRow = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm; + return (await extractClassesFromDir(rolesDir)).classes; +} - for (const entry of entries) { - if (!entry.endsWith('.md')) continue; - let text: string; - try { - text = await readFile(join(rolesDir, entry), 'utf8'); - } catch { - continue; - } - if (entry === 'LIBRARY.md') { - for (const m of text.matchAll(libraryRow)) { - const name = m[1]; - // Skip the markdown table divider / header artifacts. - if (name && name !== 'persona') classes.add(name); - } - continue; - } - // Role contract: the filename stem is itself a valid class (covers alias docs). - classes.add(basename(entry, '.md')); - for (const m of text.matchAll(inlineMarker)) { - if (m[1]) classes.add(m[1]); - } - } - return 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> { + return listOverrideAwarePersonaClasses({ rolesDir, overrideDir }); } function asString(value: unknown, ctx: string): string { @@ -227,14 +204,21 @@ export interface LoadProfilesOptions { profilesDir?: string; /** Override the roles dir (tests). Defaults to /fleet/roles. */ rolesDir?: string; + /** Persona override dir (tests). Defaults to /fleet/roles.local. */ + overrideDir?: string; mosaicHome?: string; } -function resolveDirs(opts: LoadProfilesOptions): { profilesDir: string; rolesDir: 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), }; } @@ -244,7 +228,7 @@ function resolveDirs(opts: LoadProfilesOptions): { profilesDir: string; rolesDir * Profiles are returned sorted by id for deterministic output. */ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise { - const { profilesDir, rolesDir } = resolveDirs(opts); + const { profilesDir, rolesDir, overrideDir } = resolveDirs(opts); let files: string[]; try { files = (await readdir(profilesDir)).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml')); @@ -253,7 +237,10 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise(); diff --git a/packages/mosaic/src/commands/fleet.spec.ts b/packages/mosaic/src/commands/fleet.spec.ts index d62786b..731a729 100644 --- a/packages/mosaic/src/commands/fleet.spec.ts +++ b/packages/mosaic/src/commands/fleet.spec.ts @@ -82,6 +82,7 @@ describe('registerFleetCommand', () => { 'init', 'install', 'install-systemd', + 'persona', 'profile', 'ps', 'remove', @@ -102,6 +103,19 @@ describe('registerFleetCommand', () => { 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', () => { const program = buildProgram(); const fleet = program.commands.find((command) => command.name() === 'fleet'); diff --git a/packages/mosaic/src/commands/fleet.ts b/packages/mosaic/src/commands/fleet.ts index 8c57084..b6c8763 100644 --- a/packages/mosaic/src/commands/fleet.ts +++ b/packages/mosaic/src/commands/fleet.ts @@ -9,6 +9,7 @@ import type { Command } from 'commander'; import YAML from 'yaml'; import { resolveCommsBlock } from '../fleet/comms-onboarding.js'; import { registerFleetBacklogCommand } from './fleet-backlog.js'; +import { registerFleetPersonaCommand } from './fleet-personas.js'; import { registerFleetProfileCommand } from './fleet-profiles.js'; /** @@ -1711,6 +1712,11 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps = // from /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); + return cmd; }