feat(fleet): update-surviving persona customization (H4) (#661)

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;
+}