feat(fleet): update-surviving persona overrides (roles.local layer, resolver, persona CLI) (H4)

Add a PRESERVE-protected persona override layer at <mosaicHome>/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 <noreply@anthropic.com>

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

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([]);
+  });
+});

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
+ *   <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 { 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 classes = new Set<string>();
+  const byClass = new Map<string, PersonaFile>();
+  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 <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),
+  ]);
+
+  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'))
+  );
+}
+
+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;
+}

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/<class>.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<Set<string>> {
-  const classes = new Set<string>();
-  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<Set<string>> {
+  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 <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 } {
+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<FleetProfile[]> {
-  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<Flee
   }
   files.sort();
 
-  const validClasses = await listPersonaClasses(rolesDir);
+  // 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>();
 

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');

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 <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);
+
   return cmd;
 }