feat(fleet): add shared role semantics (#768)

2026-07-15 00:53:47 +00:00
parent eb4e14ae5c
commit a5e8e55401
19 changed files with 1650 additions and 177 deletions
--- a/packages/mosaic/framework/fleet/roles/LIBRARY.md
+++ b/packages/mosaic/framework/fleet/roles/LIBRARY.md
@@ -12,19 +12,22 @@ on demand. Engineering personas have no explicit `domain:` marker (they are the
 implicit `engineering` domain); cross-domain personas carry a `domain:` key in
 their intro so tooling can group them.

-> This file is an index only — no code imports it. To add a persona, drop a new
-> `*.md` next to the others (mirroring the existing structure) and add a row here.
+> This file is an index, not an authority source. The fleet persona resolver reads
+> its rows for discovery compatibility, then requires a readable `*.md` contract;
+> authority is derived from canonical class metadata in code, never from this prose.

 ## engineering

 | Persona         | Purpose                                                                        |
 | --------------- | ------------------------------------------------------------------------------ |
 | orchestrator    | Always-on coordinator — runs the supervisor loop, dispatches ready work        |
+| team-leader     | Coordinates only orchestrator-leased capacity for one bounded project          |
 | 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  |
 | decomposition   | Splits FRs into one-PR-each cards wired with `depends_on` edges                |
 | code            | Primary executor — one card, one branch, one PR to green CI                    |
 | review          | Correctness reviewer — judges an open PR on correctness, scope, and coverage   |
+| validator       | Independent final evidence certificate; never approves-to-land or merges       |
 | security-review | Second line of review — secrets, auth, and forbidden-path safety               |
 | site-tester     | Runtime verifier — runs the change and checks behavior vs. acceptance criteria |
 | documentation   | Prose maintainer — keeps human-facing docs and projections in sync             |
@@ -33,6 +36,7 @@ their intro so tooling can group them.
 | operator        | Escalation and control surface — owns exceptions and the fleet pause switch    |
 | session-review  | Post-task retrospective — turns finished work into improvement signals         |
 | enhancer        | Continuous-improvement loop — upgrades the fleet's tools, skills, and harness  |
+| interaction     | Operator request/status surface; routes orchestration and merge decisions      |

 ## executive

--- a/packages/mosaic/framework/fleet/roles/interaction.md
+++ b/packages/mosaic/framework/fleet/roles/interaction.md
@@ -0,0 +1,16 @@
+# Interaction — fleet role definition
+
+The **interaction** role (`class: interaction`) is the operator-facing request and status surface for Mosaic.
+
+## Mandate
+
+1. Receive operator requests and present observable fleet or runtime status.
+2. Route orchestration requests to the orchestrator and merge decisions to the merge-gate.
+3. Report supported actions and their outcomes without claiming another role's authority.
+
+## Boundaries
+
+- Request/status only; it does not orchestrate, issue leases, approve-to-land, or merge.
+- It does not mutate roster configuration, role authority, or credentials.
+- A configured instance name such as Tess is display data, never a class or authority source.
+- `operator-interaction` remains a compatibility alias for this canonical class.
--- a/packages/mosaic/framework/fleet/roles/team-leader.md
+++ b/packages/mosaic/framework/fleet/roles/team-leader.md
@@ -0,0 +1,16 @@
+# Team leader — fleet role definition
+
+The **team-leader** (`class: team-leader`) coordinates a bounded project team using only capacity granted by an orchestrator-issued lease.
+
+## Mandate
+
+1. Direct the leased coder, reviewer, and validator capacity for the assigned project scope.
+2. Track delivery status and return results or blockers to the orchestrator.
+3. Stop using capacity when the lease or assignment ends.
+
+## Boundaries
+
+- Leased capacity only; this role does not issue or expand its own lease.
+- It cannot change fleet roster membership, role authority, fleet configuration, or credentials.
+- It cannot approve-to-land or merge.
+- It does not displace the orchestrator's topology and lease authority.
--- a/packages/mosaic/framework/fleet/roles/validator.md
+++ b/packages/mosaic/framework/fleet/roles/validator.md
@@ -0,0 +1,16 @@
+# Validator — fleet role definition
+
+The **validator** (`class: validator`) is the independent final evidence seat. It examines the accepted requirements, test evidence, review record, and candidate head and may issue a validation certificate for that exact evidence set.
+
+## Mandate
+
+1. Validate acceptance evidence independently from the implementation author.
+2. Issue or withhold a final validation certificate for the reviewed candidate.
+3. Report missing, stale, or contradictory evidence without altering it.
+
+## Boundaries
+
+- **Certificate only:** the validator does not approve-to-land or merge.
+- It does not replace correctness or security review.
+- It does not write product code, mutate the roster, issue leases, or access credentials.
+- A configured instance name such as Ultron is display data, never a class or authority source.
--- a/packages/mosaic/src/commands/fleet-personas.spec.ts
+++ b/packages/mosaic/src/commands/fleet-personas.spec.ts
@@ -1,13 +1,18 @@
-import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import {
+  authorityForCanonicalClass,
+  canonicalizeRoleClass,
  extractClassesFromDir,
+  extractClassesFromDirSync,
  listPersonaClasses,
  personaStatus,
  resolvePersona,
+  resolvePersonaFrom,
+  resolvePersonaSync,
 } from './fleet-personas.js';
 import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';

@@ -54,13 +59,156 @@ afterEach(async () => {
  await rm(tmp, { recursive: true, force: true });
 });

+describe('FCM class canonicalization and authority', () => {
+  it.each([
+    ['implementer', 'code'],
+    ['reviewer', 'review'],
+    ['operator-interaction', 'interaction'],
+  ])('canonicalizes the approved alias %s to %s', (requested: string, canonical: string) => {
+    expect(canonicalizeRoleClass(requested)).toEqual({
+      requestedClass: requested,
+      canonicalClass: canonical,
+    });
+  });
+
+  it.each(['worker', 'analyst', 'canary', 'tess', 'ultron', 'constructor'])(
+    'does not infer an alias for %s',
+    (requested: string) => {
+      expect(canonicalizeRoleClass(requested)).toEqual({
+        requestedClass: requested,
+        canonicalClass: requested,
+      });
+    },
+  );
+
+  it('resolves inherited-property class names without granting protected authority', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'constructor.md'),
+      overridePersona('constructor', 'custom'),
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('constructor', { rolesDir, overrideDir });
+    expect(resolved).toMatchObject({
+      requestedClass: 'constructor',
+      canonicalClass: 'constructor',
+      klass: 'constructor',
+      layer: 'override',
+    });
+    expect(authorityForCanonicalClass('constructor')).toMatchObject({
+      mayMerge: false,
+      mayIssueValidationCertificate: false,
+      mayOrchestrate: false,
+    });
+  });
+
+  it('canonicalizes before override lookup and lets the canonical override win', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'implementer.md'),
+      overridePersona('implementer', 'legacy'),
+      'utf8',
+    );
+    await writeFile(
+      join(overrideDir, 'code.md'),
+      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('implementer', { rolesDir, overrideDir });
+    expect(resolved).toMatchObject({
+      requestedClass: 'implementer',
+      canonicalClass: 'code',
+      klass: 'code',
+      layer: 'override',
+    });
+    expect(resolved?.content).toContain('CANONICAL-OVERRIDE');
+    expect(resolved?.content).not.toContain('legacy');
+  });
+
+  it('keeps sync and async resolution equivalent for aliases and canonical overrides', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'code.md'),
+      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
+      'utf8',
+    );
+
+    const asyncResolution = await resolvePersona('implementer', { rolesDir, overrideDir });
+    const syncResolution = resolvePersonaSync('implementer', { rolesDir, overrideDir });
+    expect(syncResolution).toEqual(asyncResolution);
+  });
+
+  it('derives immutable protected authority only from the canonical class', () => {
+    expect(authorityForCanonicalClass('merge-gate')).toMatchObject({ mayMerge: true });
+    for (const klass of [
+      'validator',
+      'orchestrator',
+      'team-leader',
+      'interaction',
+      'code',
+      'custom-role',
+    ]) {
+      expect(authorityForCanonicalClass(klass).mayMerge).toBe(false);
+    }
+    expect(authorityForCanonicalClass('validator')).toMatchObject({
+      mayIssueValidationCertificate: true,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('orchestrator')).toMatchObject({
+      mayOrchestrate: true,
+      mayIssueLeases: true,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('team-leader')).toMatchObject({
+      leasedCapacityOnly: true,
+      mayMutateRoster: false,
+      mayAccessCredentials: false,
+      mayMerge: false,
+    });
+    expect(authorityForCanonicalClass('interaction')).toMatchObject({
+      requestStatusOnly: true,
+      mayOrchestrate: false,
+      mayMerge: false,
+    });
+    expect(Object.isFrozen(authorityForCanonicalClass('merge-gate'))).toBe(true);
+  });
+});
+
+describe('required FCM role library', () => {
+  it.each([
+    'code',
+    'review',
+    'validator',
+    'orchestrator',
+    'team-leader',
+    'enhancer',
+    'interaction',
+    'merge-gate',
+  ])('resolves %s through the real framework role library', async (klass: string) => {
+    const resolved = await resolvePersona(klass, {
+      rolesDir: realRolesDir,
+      overrideDir: join(tmp, 'none'),
+    });
+    expect(resolved).not.toBeNull();
+    expect(resolved?.canonicalClass).toBe(klass);
+    expect(resolved?.content.trim()).not.toBe('');
+  });
+});
+
 describe('extractClassesFromDir (shared extraction)', () => {
-  it('records class + domain from inline markers and degrades on missing dir', async () => {
+  it('records class + domain and distinguishes scanned from missing directories', async () => {
    const base = await extractClassesFromDir(rolesDir);
+    expect(base.scanState).toBe('scanned');
    expect(base.classes.has('ceo')).toBe(true);
    expect(base.byClass.get('ceo')?.domain).toBe('executive');
-    const missing = await extractClassesFromDir(join(tmp, 'nope'));
+
+    const missingDir = join(tmp, 'nope');
+    const missing = await extractClassesFromDir(missingDir);
+    expect(missing.scanState).toBe('missing');
    expect(missing.classes.size).toBe(0);
+    expect(extractClassesFromDirSync(missingDir).scanState).toBe('missing');
  });
 });

@@ -81,6 +229,287 @@ describe('resolvePersona — override wins', () => {
    expect(resolved?.content).toContain('BASELINE');
  });

+  it('does not let a LIBRARY-only row shadow a readable baseline persona', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'LIBRARY.md'),
+      '| Persona | Purpose |\n| --- | --- |\n| code | Index only |\n',
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('baseline');
+    expect(resolved?.content).toContain('BASELINE');
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not let an incidental later class marker shadow a readable baseline persona', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: code`).\n',
+      'utf8',
+    );
+
+    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
+    expect(resolved?.layer).toBe('baseline');
+    expect(resolved?.content).toContain('BASELINE');
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('mascot')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not advertise an incidental-only class through listing or status APIs', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(
+      join(overrideDir, 'mascot.md'),
+      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: phantom`).\n',
+      'utf8',
+    );
+
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('phantom')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'phantom'),
+    ).toBe(false);
+  });
+
+  it('rejects a canonical filename whose explicit marker names another class', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await writeFile(join(overrideDir, 'merge-gate.md'), overridePersona('mascot', 'fun'), 'utf8');
+    await writeFile(
+      join(rolesDir, 'merge-gate.md'),
+      baselinePersona('merge-gate', 'governance'),
+      'utf8',
+    );
+
+    expect(await resolvePersona('merge-gate', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('merge-gate', { rolesDir, overrideDir })).toBeNull();
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('merge-gate')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'merge-gate'),
+    ).toBe(false);
+  });
+
+  it('fails closed if a marker-defined override becomes unreadable after extraction', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'engineering.md');
+    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await rm(overrideFile);
+    await mkdir(overrideFile);
+
+    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
+  });
+
+  it('fails closed if a marker-defined override changes identity after extraction', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'engineering.md');
+    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
+
+    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
+
+    const classes = await listPersonaClasses({ rolesDir, overrideDir });
+    expect(classes.has('code')).toBe(true);
+    expect(classes.has('mascot')).toBe(true);
+    const status = new Map(
+      (await personaStatus({ rolesDir, overrideDir })).map((entry) => [entry.klass, entry]),
+    );
+    expect(status.get('code')?.status).toBe('baseline');
+    expect(status.get('mascot')?.status).toBe('custom');
+  });
+
+  it('fails closed if a markerless cached override gains a conflicting marker', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const overrideFile = join(overrideDir, 'merge-gate.md');
+    await writeFile(overrideFile, '# markerless merge gate\n', 'utf8');
+    await writeFile(
+      join(rolesDir, 'merge-gate.md'),
+      baselinePersona('merge-gate', 'governance'),
+      'utf8',
+    );
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
+
+    expect(
+      await resolvePersonaFrom('merge-gate', { rolesDir, overrideDir, base, over }),
+    ).toBeNull();
+  });
+
+  it('fails closed asynchronously when the override directory cannot be scanned', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed synchronously when the override directory cannot be scanned', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed asynchronously and synchronously for a dangling override-directory symlink', async () => {
+    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('fails closed asynchronously and synchronously when an override ancestor is a dangling symlink', async () => {
+    const danglingAncestor = join(tmp, 'dangling-ancestor');
+    await symlink(join(tmp, 'missing-ancestor-target'), danglingAncestor, 'dir');
+    overrideDir = join(danglingAncestor, 'nested', 'roles.local');
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('fails closed when dot-dot traversal crosses a dangling override ancestor', async () => {
+    const danglingAncestor = join(tmp, 'dangling-dotdot-ancestor');
+    await symlink(join(tmp, 'missing-dotdot-target'), danglingAncestor, 'dir');
+    overrideDir = `${danglingAncestor}/../roles.local`;
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('fails closed when relative dot-dot traversal crosses a dangling override ancestor', async () => {
+    const danglingAncestor = join(tmp, 'relative-dangling-ancestor');
+    await symlink(join(tmp, 'missing-relative-target'), danglingAncestor, 'dir');
+    overrideDir = `${relative(process.cwd(), danglingAncestor)}/../roles.local`;
+    expect(overrideDir.startsWith('/')).toBe(false);
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('revalidates a cached missing override before baseline fallback', async () => {
+    const cachedOverrideDir = join(tmp, 'mutable-ancestor', 'roles.local');
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(cachedOverrideDir),
+    ]);
+    expect(over.scanState).toBe('missing');
+    await symlink(join(tmp, 'missing-mutable-target'), join(tmp, 'mutable-ancestor'), 'dir');
+
+    expect(
+      await resolvePersonaFrom('code', {
+        rolesDir,
+        overrideDir: cachedOverrideDir,
+        base,
+        over,
+      }),
+    ).toBeNull();
+  });
+
+  it('revalidates a cached scanned override before baseline fallback', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    const [base, over] = await Promise.all([
+      extractClassesFromDir(rolesDir),
+      extractClassesFromDir(overrideDir),
+    ]);
+    expect(over.scanState).toBe('scanned');
+    expect(over.classes.size).toBe(0);
+
+    await writeFile(join(overrideDir, 'engineering.md'), overridePersona('code', 'engineering'));
+
+    const resolved = await resolvePersonaFrom('code', {
+      rolesDir,
+      overrideDir,
+      base,
+      over,
+    });
+    expect(resolved?.layer).toBe('override');
+    expect(resolved?.file).toBe(join(overrideDir, 'engineering.md'));
+  });
+
+  it('falls back to baseline asynchronously and synchronously when override directory is missing', async () => {
+    const asyncResolution = await resolvePersona('code', { rolesDir, overrideDir });
+    const syncResolution = resolvePersonaSync('code', { rolesDir, overrideDir });
+    expect(asyncResolution?.layer).toBe('baseline');
+    expect(syncResolution?.layer).toBe('baseline');
+  });
+
+  it('fails closed asynchronously when the canonical override exists but is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
+  it('does not advertise a shadowed baseline whose canonical override is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'code'),
+    ).toBe(false);
+  });
+
+  it('does not advertise baseline personas when the override directory is unscannable', async () => {
+    await writeFile(overrideDir, 'not a directory', 'utf8');
+
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('does not advertise baseline personas through a dangling override-directory symlink', async () => {
+    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
+
+    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
+    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
+  });
+
+  it('preserves baseline listings when the override directory is missing', async () => {
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
+        ?.status,
+    ).toBe('baseline');
+  });
+
+  it('does not advertise an unreadable custom override as a valid persona class or status', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'ghost.md'));
+
+    const extracted = await extractClassesFromDir(overrideDir);
+    expect(extracted.fileStems.has('ghost')).toBe(true);
+    expect(extracted.classes.has('ghost')).toBe(false);
+    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('ghost')).toBe(false);
+    expect(
+      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'ghost'),
+    ).toBe(false);
+  });
+
+  it('fails closed synchronously when the canonical override exists but is unreadable', async () => {
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(join(overrideDir, 'code.md'));
+
+    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
+  });
+
  it('returns null for an unknown class', async () => {
    expect(await resolvePersona('does-not-exist', { rolesDir, overrideDir })).toBeNull();
  });
--- a/packages/mosaic/src/commands/fleet-personas.ts
+++ b/packages/mosaic/src/commands/fleet-personas.ts
@@ -25,10 +25,10 @@
 * can reference a customized or user-added persona.
 */

-import { readFileSync, readdirSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
+import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { lstat, readFile, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
+import { basename, isAbsolute, join, sep } from 'node:path';
 import type { Command } from 'commander';

 function defaultMosaicHome(): string {
@@ -53,52 +53,136 @@ export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
 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';

+export const ROLE_CLASS_ALIASES = Object.freeze({
+  implementer: 'code',
+  reviewer: 'review',
+  'operator-interaction': 'interaction',
+} as const);
+
+export interface CanonicalRoleClass {
+  readonly requestedClass: string;
+  readonly canonicalClass: string;
+}
+
+/** Canonicalize only the three explicitly approved compatibility aliases. */
+export function canonicalizeRoleClass(requestedClass: string): CanonicalRoleClass {
+  const requested = requestedClass.trim();
+  const canonical = Object.hasOwn(ROLE_CLASS_ALIASES, requested)
+    ? ROLE_CLASS_ALIASES[requested as keyof typeof ROLE_CLASS_ALIASES]
+    : requested;
+  return Object.freeze({ requestedClass: requested, canonicalClass: canonical });
+}
+
+export interface RoleAuthority {
+  readonly mayMerge: boolean;
+  readonly mayIssueValidationCertificate: boolean;
+  readonly mayOrchestrate: boolean;
+  readonly mayManageTopology: boolean;
+  readonly mayIssueLeases: boolean;
+  readonly leasedCapacityOnly: boolean;
+  readonly requestStatusOnly: boolean;
+  readonly mayMutateRoster: boolean;
+  readonly mayMutateConfiguration: boolean;
+  readonly mayAccessCredentials: boolean;
+}
+
+const NO_PROTECTED_AUTHORITY: RoleAuthority = Object.freeze({
+  mayMerge: false,
+  mayIssueValidationCertificate: false,
+  mayOrchestrate: false,
+  mayManageTopology: false,
+  mayIssueLeases: false,
+  leasedCapacityOnly: false,
+  requestStatusOnly: false,
+  mayMutateRoster: false,
+  mayMutateConfiguration: false,
+  mayAccessCredentials: false,
+});
+
+/** Immutable authority contracts keyed only by canonical class identity. */
+export const ROLE_AUTHORITY_BY_CANONICAL_CLASS: Readonly<Record<string, RoleAuthority>> =
+  Object.freeze({
+    'merge-gate': Object.freeze({ ...NO_PROTECTED_AUTHORITY, mayMerge: true }),
+    validator: Object.freeze({
+      ...NO_PROTECTED_AUTHORITY,
+      mayIssueValidationCertificate: true,
+    }),
+    orchestrator: Object.freeze({
+      ...NO_PROTECTED_AUTHORITY,
+      mayOrchestrate: true,
+      mayManageTopology: true,
+      mayIssueLeases: true,
+    }),
+    'team-leader': Object.freeze({ ...NO_PROTECTED_AUTHORITY, leasedCapacityOnly: true }),
+    interaction: Object.freeze({ ...NO_PROTECTED_AUTHORITY, requestStatusOnly: true }),
+  });
+
+/** Return protected authority for an already-canonical class; custom classes get none. */
+export function authorityForCanonicalClass(canonicalClass: string): RoleAuthority {
+  return Object.hasOwn(ROLE_AUTHORITY_BY_CANONICAL_CLASS, canonicalClass)
+    ? ROLE_AUTHORITY_BY_CANONICAL_CLASS[canonicalClass]!
+    : NO_PROTECTED_AUTHORITY;
+}
+
 /** 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;
+  /** True when the first class marker, rather than filename, defined this mapping. */
+  markerDefined?: boolean;
  domain?: string;
 }

+export type DirScanState = 'scanned' | 'missing' | 'error';
+
 /** The set of persona classes a directory of role contracts defines. */
 export interface DirClasses {
-  /** Every class name the dir contributes (markers + filenames + LIBRARY rows). */
+  /** Whether the directory was scanned, absent, or present-but-unscannable. */
+  scanState: DirScanState;
+  /** Every readable class name the directory contributes by filename or first marker. */
  classes: Set<string>;
+  /** Filename stems present on disk, retained even when a markdown entry is unreadable. */
+  fileStems: 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).
+ * Scan one directory of role contracts and extract readable persona identities.
+ * Valid identities come only from a successfully read non-LIBRARY filename and
+ * that file's first `class:` marker. LIBRARY rows and later prose mentions are
+ * index/reference data, not independently readable role contracts.
 *
- * 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.
+ * Missing directories are distinguished from present-but-unscannable paths.
+ * `byClass` records the first marker-defined file+domain so the resolver can map
+ * a class back to its contract; marker-less readable files map by filename.
 */
 export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
-  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
+  const acc: DirClasses = {
+    scanState: 'scanned',
+    classes: new Set<string>(),
+    fileStems: new Set<string>(),
+    byClass: new Map<string, PersonaFile>(),
+  };
  let entries: string[];
  try {
    entries = await readdir(dir);
-  } catch {
+  } catch (error) {
+    acc.scanState = await classifyScanFailure(dir, error);
    return acc;
  }

  for (const entry of entries) {
    if (!entry.endsWith('.md')) continue;
+    // Preserve entry presence separately from valid readable classes. Resolvers
+    // use it to fail closed on an explicit unreadable canonical override without
+    // advertising that override through class listing/status APIs.
+    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
    let text: string;
    try {
      text = await readFile(join(dir, entry), 'utf8');
@@ -117,16 +201,25 @@ export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
 * 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>() };
+  const acc: DirClasses = {
+    scanState: 'scanned',
+    classes: new Set<string>(),
+    fileStems: new Set<string>(),
+    byClass: new Map<string, PersonaFile>(),
+  };
  let entries: string[];
  try {
    entries = readdirSync(dir);
-  } catch {
+  } catch (error) {
+    acc.scanState = classifyScanFailureSync(dir, error);
    return acc;
  }

  for (const entry of entries) {
    if (!entry.endsWith('.md')) continue;
+    // Keep sync extraction equivalent to the async scanner, including unreadable
+    // filename presence kept separate from valid readable classes.
+    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
    let text: string;
    try {
      text = readFileSync(join(dir, entry), 'utf8');
@@ -138,6 +231,74 @@ export function extractClassesFromDirSync(dir: string): DirClasses {
  return acc;
 }

+async function classifyScanFailure(dir: string, error: unknown): Promise<DirScanState> {
+  if (!isMissingPathError(error)) return 'error';
+  return (await hasBrokenSymlinkInPath(dir)) ? 'error' : 'missing';
+}
+
+function classifyScanFailureSync(dir: string, error: unknown): DirScanState {
+  if (!isMissingPathError(error)) return 'error';
+  return hasBrokenSymlinkInPathSync(dir) ? 'error' : 'missing';
+}
+
+function traversalPrefixes(path: string): string[] {
+  const absolute = isAbsolute(path) ? path : `${process.cwd()}${sep}${path}`;
+  const parts = absolute.split(sep);
+  const prefixes: string[] = [];
+  let current: string = sep;
+  for (const part of parts) {
+    if (!part) continue;
+    current = current === sep ? `${sep}${part}` : `${current}${sep}${part}`;
+    prefixes.push(current);
+  }
+  return prefixes;
+}
+
+async function hasBrokenSymlinkInPath(path: string): Promise<boolean> {
+  for (const current of traversalPrefixes(path)) {
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink()) {
+        try {
+          await stat(current);
+        } catch {
+          return true;
+        }
+      }
+    } catch (error) {
+      if (!isMissingPathError(error)) return true;
+    }
+  }
+  return false;
+}
+
+function hasBrokenSymlinkInPathSync(path: string): boolean {
+  for (const current of traversalPrefixes(path)) {
+    try {
+      const entry = lstatSync(current);
+      if (entry.isSymbolicLink()) {
+        try {
+          statSync(current);
+        } catch {
+          return true;
+        }
+      }
+    } catch (error) {
+      if (!isMissingPathError(error)) return true;
+    }
+  }
+  return false;
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === 'ENOENT'
+  );
+}
+
 /**
 * 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
@@ -146,33 +307,26 @@ export function extractClassesFromDirSync(dir: string): DirClasses {
 */
 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).
+  if (entry === 'LIBRARY.md') return;
+
+  // An explicit first marker owns identity. Filename identity is a fallback only
+  // for markerless compatibility contracts such as planner.md.
  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) });
+  const firstMarker = text.matchAll(CLASS_MARKER).next().value as RegExpExecArray | undefined;
+  const markedClassForFile = firstMarker?.[1];
+  if (markedClassForFile) {
+    classes.add(markedClassForFile);
+    byClass.set(markedClassForFile, {
+      klass: markedClassForFile,
+      file: join(dir, entry),
+      markerDefined: true,
+      ...(domain ? { domain } : {}),
+    });
+  } else {
+    classes.add(stem);
+    if (!byClass.has(stem)) byClass.set(stem, { klass: stem, file: join(dir, entry) });
  }
 }

@@ -193,24 +347,19 @@ function resolveDirs(opts: PersonaDirs): { rolesDir: string; overrideDir: string
 }

 /**
- * 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.
+ * Every class with an actually readable winning contract. Discovery applies the
+ * same override shadow/fail-closed semantics as resolution, so callers never
+ * advertise a class that cannot be used.
 */
 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;
+  const { personas } = await collectUsablePersonas(opts);
+  return new Set(personas.keys());
 }

 export type PersonaStatus = 'baseline' | 'overridden' | 'custom';

-export interface PersonaResolution {
+export interface PersonaResolution extends CanonicalRoleClass {
+  /** Compatibility name for the canonical class. */
  klass: string;
  layer: PersonaLayer;
  /** The file the resolved persona was read from (override wins). */
@@ -219,6 +368,118 @@ export interface PersonaResolution {
  domain?: string;
 }

+async function readPersonaFromLayer(
+  requestedClass: string,
+  canonicalClass: string,
+  dir: string,
+  extracted: DirClasses,
+  layer: PersonaLayer,
+): Promise<PersonaResolution | null> {
+  const pf = extracted.byClass.get(canonicalClass);
+  if (!pf) {
+    if (!extracted.classes.has(canonicalClass)) return null;
+    const byName = join(dir, `${canonicalClass}.md`);
+    try {
+      const content = await readFile(byName, 'utf8');
+      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+        | RegExpExecArray
+        | undefined;
+      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+      const dm = DOMAIN_MARKER.exec(content);
+      return {
+        requestedClass,
+        canonicalClass,
+        klass: canonicalClass,
+        layer,
+        file: byName,
+        content,
+        ...(dm?.[1] ? { domain: dm[1] } : {}),
+      };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const content = await readFile(pf.file, 'utf8');
+    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+      | RegExpExecArray
+      | undefined;
+    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+    const dm = DOMAIN_MARKER.exec(content);
+    return {
+      requestedClass,
+      canonicalClass,
+      klass: canonicalClass,
+      layer,
+      file: pf.file,
+      content,
+      ...(dm?.[1] ? { domain: dm[1] } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function overrideShadowsBaseline(over: DirClasses, canonicalClass: string): boolean {
+  return (
+    over.scanState === 'error' ||
+    over.fileStems.has(canonicalClass) ||
+    over.byClass.has(canonicalClass)
+  );
+}
+
+function readPersonaFromLayerSync(
+  requestedClass: string,
+  canonicalClass: string,
+  dir: string,
+  extracted: DirClasses,
+  layer: PersonaLayer,
+): PersonaResolution | null {
+  const pf = extracted.byClass.get(canonicalClass);
+  if (!pf) {
+    if (!extracted.classes.has(canonicalClass)) return null;
+    const byName = join(dir, `${canonicalClass}.md`);
+    try {
+      const content = readFileSync(byName, 'utf8');
+      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+        | RegExpExecArray
+        | undefined;
+      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+      const dm = DOMAIN_MARKER.exec(content);
+      return {
+        requestedClass,
+        canonicalClass,
+        klass: canonicalClass,
+        layer,
+        file: byName,
+        content,
+        ...(dm?.[1] ? { domain: dm[1] } : {}),
+      };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const content = readFileSync(pf.file, 'utf8');
+    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
+      | RegExpExecArray
+      | undefined;
+    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
+    const dm = DOMAIN_MARKER.exec(content);
+    return {
+      requestedClass,
+      canonicalClass,
+      klass: canonicalClass,
+      layer,
+      file: pf.file,
+      content,
+      ...(dm?.[1] ? { domain: dm[1] } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
 * Resolve a persona class to its winning definition: the override file if
 * roles.local/ defines that class, else the baseline. Match by inline `class:`
@@ -245,42 +506,32 @@ export async function resolvePersona(
 * is identical to {@link resolvePersona}: override layer wins, then baseline.
 */
 export async function resolvePersonaFrom(
-  klass: string,
+  requestedClass: string,
  layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
 ): Promise<PersonaResolution | null> {
+  const { requestedClass: requested, canonicalClass: klass } =
+    canonicalizeRoleClass(requestedClass);
  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;
-    }
-  };
+  const override = await readPersonaFromLayer(requested, klass, overrideDir, over, 'override');
+  if (override) return override;
+  // An observed explicit override that cannot resolve/read shadows the baseline.
+  if (overrideShadowsBaseline(over, klass)) return null;

-  return (
-    (await fromLayer(overrideDir, over, 'override')) ??
-    (await fromLayer(rolesDir, base, 'baseline'))
+  // Cached scans are only snapshots. Re-scan immediately before baseline fallback
+  // so a newly created canonical or marker-defined override cannot be skipped.
+  const currentOver = await extractClassesFromDir(overrideDir);
+  const currentOverride = await readPersonaFromLayer(
+    requested,
+    klass,
+    overrideDir,
+    currentOver,
+    'override',
  );
+  if (currentOverride) return currentOverride;
+  if (overrideShadowsBaseline(currentOver, klass)) return null;
+  if (currentOver.scanState === 'error') return null;
+  return readPersonaFromLayer(requested, klass, rolesDir, base, 'baseline');
 }

 /**
@@ -292,40 +543,55 @@ export async function resolvePersonaFrom(
 * one module so the launch-time and command-time resolutions never diverge.
 */
 export function resolvePersonaSync(
-  klass: string,
+  requestedClass: string,
  opts: PersonaDirs = {},
 ): PersonaResolution | null {
+  const { requestedClass: requested, canonicalClass: klass } =
+    canonicalizeRoleClass(requestedClass);
  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;
-    }
-  };
+  const override = readPersonaFromLayerSync(requested, klass, overrideDir, over, 'override');
+  if (override) return override;
+  if (overrideShadowsBaseline(over, klass)) return null;
+  return readPersonaFromLayerSync(requested, klass, rolesDir, base, 'baseline');
+}

-  return fromLayer(overrideDir, over, 'override') ?? fromLayer(rolesDir, base, 'baseline');
+interface UsablePersonaIndex {
+  personas: Map<string, PersonaResolution>;
+  readableBaseline: Set<string>;
+}
+
+async function collectUsablePersonas(opts: PersonaDirs): Promise<UsablePersonaIndex> {
+  const { rolesDir, overrideDir } = resolveDirs(opts);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  if (over.scanState === 'error') {
+    return { personas: new Map(), readableBaseline: new Set() };
+  }
+
+  const candidates = new Set<string>([...base.classes, ...over.classes]);
+  const checked = await Promise.all(
+    [...candidates].map(async (requestedClass) => {
+      const { canonicalClass } = canonicalizeRoleClass(requestedClass);
+      const [persona, baseline] = await Promise.all([
+        resolvePersonaFrom(requestedClass, { rolesDir, overrideDir, base, over }),
+        readPersonaFromLayer(requestedClass, canonicalClass, rolesDir, base, 'baseline'),
+      ]);
+      return { requestedClass, persona, baseline };
+    }),
+  );
+
+  const personas = new Map<string, PersonaResolution>();
+  const readableBaseline = new Set<string>();
+  for (const { requestedClass, persona, baseline } of checked) {
+    if (persona) personas.set(requestedClass, persona);
+    if (baseline) readableBaseline.add(requestedClass);
+  }
+  return { personas, readableBaseline };
 }

 export interface PersonaStatusEntry {
@@ -342,24 +608,20 @@ export interface PersonaStatusEntry {
 * 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 } : {}) });
-  }
+  const { personas, readableBaseline } = await collectUsablePersonas(opts);
+  const entries = [...personas.entries()].map(([klass, persona]): PersonaStatusEntry => {
+    const status: PersonaStatus =
+      persona.layer === 'baseline'
+        ? 'baseline'
+        : readableBaseline.has(klass)
+          ? 'overridden'
+          : 'custom';
+    return {
+      klass,
+      status,
+      ...(persona.domain ? { domain: persona.domain } : {}),
+    };
+  });
  entries.sort((a, b) => a.klass.localeCompare(b.klass));
  return entries;
 }
--- a/packages/mosaic/src/commands/fleet-profiles.spec.ts
+++ b/packages/mosaic/src/commands/fleet-profiles.spec.ts
@@ -203,6 +203,91 @@ describe('loadProfiles with a temp override dir', () => {
    await rm(dir, { recursive: true, force: true });
  });

+  it('canonicalizes approved aliases across lead, floor, roster, and topology', async () => {
+    await writeFile(
+      join(dir, 'aliases.yaml'),
+      [
+        'id: aliases',
+        'title: Aliases',
+        'description: legacy class compatibility',
+        'lead: operator-interaction',
+        'floor: [operator-interaction]',
+        'roster:',
+        '  - class: operator-interaction',
+        '  - class: implementer',
+        '    reports_to: operator-interaction',
+        '  - class: reviewer',
+        '    reports_to: operator-interaction',
+        '',
+      ].join('\n'),
+    );
+
+    const profile = await loadProfile('aliases', {
+      profilesDir: dir,
+      rolesDir,
+      overrideDir: join(dir, 'roles.local'),
+    });
+    expect(profile.lead).toBe('interaction');
+    expect(profile.floor).toEqual(['interaction']);
+    expect(profile.roster).toEqual([
+      { class: 'interaction', multiplicity: 1 },
+      { class: 'code', reportsTo: 'interaction', multiplicity: 1 },
+      { class: 'review', reportsTo: 'interaction', multiplicity: 1 },
+    ]);
+  });
+
+  it('rejects roster entries that collapse to the same canonical class', async () => {
+    await writeFile(
+      join(dir, 'alias-collision.yaml'),
+      [
+        'id: alias-collision',
+        'title: Alias collision',
+        'description: ambiguous canonical topology',
+        'lead: orchestrator',
+        'floor: [orchestrator]',
+        'roster:',
+        '  - class: orchestrator',
+        '  - class: code',
+        '    reports_to: orchestrator',
+        '  - class: implementer',
+        '    reports_to: orchestrator',
+        '',
+      ].join('\n'),
+    );
+
+    await expect(
+      loadProfile('alias-collision', {
+        profilesDir: dir,
+        rolesDir,
+        overrideDir: join(dir, 'roles.local'),
+      }),
+    ).rejects.toThrow(/duplicate classes after canonicalization/);
+  });
+
+  it('allows a readable lead or floor persona that is not itself a roster seat', async () => {
+    await writeFile(
+      join(dir, 'external-topology.yaml'),
+      [
+        'id: external-topology',
+        'title: External topology',
+        'description: structural compatibility',
+        'lead: orchestrator',
+        'floor: [enhancer]',
+        'roster:',
+        '  - class: code',
+        '',
+      ].join('\n'),
+    );
+
+    const profile = await loadProfile('external-topology', {
+      profilesDir: dir,
+      rolesDir,
+      overrideDir: join(dir, 'roles.local'),
+    });
+    expect(profile.lead).toBe('orchestrator');
+    expect(profile.floor).toEqual(['enhancer']);
+  });
+
  it('throws when a profile references an unknown class (validated against real roles)', async () => {
    await writeFile(
      join(dir, 'bad.yaml'),
--- a/packages/mosaic/src/commands/fleet-profiles.ts
+++ b/packages/mosaic/src/commands/fleet-profiles.ts
@@ -29,6 +29,7 @@ import {
  defaultOverrideDir,
  extractClassesFromDir,
  listPersonaClasses as listOverrideAwarePersonaClasses,
+  resolvePersonaFrom,
 } from './fleet-personas.js';

 function defaultMosaicHome(): string {
@@ -199,6 +200,61 @@ export function validateProfile(profile: FleetProfile, validClasses: Set<string>
  return problems;
 }

+export async function resolveProfilePersonas(
+  profile: FleetProfile,
+  rolesDir: string,
+  overrideDir: string,
+): Promise<FleetProfile> {
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  const requestedClasses = new Set<string>([
+    profile.lead,
+    ...profile.floor,
+    ...profile.roster.flatMap((entry: ProfileRosterEntry): string[] =>
+      entry.reportsTo ? [entry.class, entry.reportsTo] : [entry.class],
+    ),
+  ]);
+  const canonicalByRequested = new Map<string, string>();
+  for (const requestedClass of requestedClasses) {
+    const resolved = await resolvePersonaFrom(requestedClass, {
+      rolesDir,
+      overrideDir,
+      base,
+      over,
+    });
+    if (!resolved || resolved.content.trim() === '') {
+      throw new Error(`persona class "${requestedClass}" does not resolve to a readable persona`);
+    }
+    canonicalByRequested.set(requestedClass, resolved.canonicalClass);
+  }
+  const canonical = (requestedClass: string): string =>
+    canonicalByRequested.get(requestedClass) ?? requestedClass;
+  const roster = profile.roster.map(
+    (entry: ProfileRosterEntry): ProfileRosterEntry => ({
+      class: canonical(entry.class),
+      multiplicity: entry.multiplicity,
+      ...(entry.reportsTo ? { reportsTo: canonical(entry.reportsTo) } : {}),
+    }),
+  );
+  const canonicalRosterClasses = roster.map((entry: ProfileRosterEntry): string => entry.class);
+  if (new Set(canonicalRosterClasses).size !== canonicalRosterClasses.length) {
+    throw new Error('profile roster contains duplicate classes after canonicalization');
+  }
+  const resolvedProfile: FleetProfile = {
+    ...profile,
+    lead: canonical(profile.lead),
+    floor: profile.floor.map(canonical),
+    roster,
+  };
+  const problems = validateProfile(resolvedProfile, new Set(canonicalByRequested.values()));
+  if (problems.length > 0) {
+    throw new Error(problems.join('\n  - '));
+  }
+  return resolvedProfile;
+}
+
 export interface LoadProfilesOptions {
  /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
  profilesDir?: string;
@@ -237,10 +293,8 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
  }
  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);
+  // Validation resolves each reference to an actually readable winning persona;
+  // LIBRARY membership alone is not semantic success.
  const profiles: FleetProfile[] = [];
  const seen = new Map<string, string>();

@@ -255,11 +309,14 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
    }
    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  - ')}`);
+    let resolvedProfile: FleetProfile;
+    try {
+      resolvedProfile = await resolveProfilePersonas(profile, rolesDir, overrideDir);
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`Profile ${file} is invalid:\n  - ${detail}`);
    }
-    profiles.push(profile);
+    profiles.push(resolvedProfile);
  }
  return profiles;
 }
--- a/packages/mosaic/src/commands/fleet-provision.spec.ts
+++ b/packages/mosaic/src/commands/fleet-provision.spec.ts
@@ -172,6 +172,46 @@ describe('override-aware persona validation', () => {
    expect(result.summary).toContain('persona=override');
  });

+  it('canonicalizes aliased profile classes and topology identities before emission', async () => {
+    const overrideDir = join(dir, 'roles.local');
+    const customProfilesDir = join(dir, 'profiles');
+    await mkdir(overrideDir, { recursive: true });
+    await mkdir(customProfilesDir, { recursive: true });
+    await writeFile(
+      join(customProfilesDir, 'aliases.yaml'),
+      [
+        'id: aliases',
+        'title: Aliases',
+        'description: legacy aliases',
+        'lead: operator-interaction',
+        'floor: [operator-interaction]',
+        'roster:',
+        '  - class: operator-interaction',
+        '  - class: implementer',
+        '    reports_to: operator-interaction',
+        '  - class: reviewer',
+        '    reports_to: operator-interaction',
+        '',
+      ].join('\n'),
+    );
+
+    const result = await runProvision('aliases', {
+      mosaicHome: dir,
+      profilesDir: customProfilesDir,
+      rolesDir,
+      overrideDir,
+      full: true,
+    });
+    expect(result.yaml).toContain('name: interaction');
+    expect(result.yaml).toContain('class: interaction');
+    expect(result.yaml).toContain('name: code');
+    expect(result.yaml).toContain('class: code');
+    expect(result.yaml).toContain('name: review');
+    expect(result.yaml).toContain('class: review');
+    expect(result.yaml).not.toContain('class: implementer');
+    expect(result.summary).toContain('reports_to=interaction');
+  });
+
  it('FAILS with a clear message when a profile references a bogus class', async () => {
    const customProfilesDir = join(dir, 'profiles');
    await mkdir(customProfilesDir, { recursive: true });
--- a/packages/mosaic/src/commands/fleet-provision.ts
+++ b/packages/mosaic/src/commands/fleet-provision.ts
@@ -26,12 +26,11 @@ import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
  loadProfile,
-  validateProfile,
  type FleetProfile,
  type ProfileRosterEntry,
  defaultProfilesDir,
  defaultRolesDir,
-  listPersonaClassesWithOverrides,
+  resolveProfilePersonas,
 } from './fleet-profiles.js';
 import {
  defaultOverrideDir,
@@ -201,18 +200,35 @@ export async function generateRoster(
      );
    }

-    const runtimeChoice = resolveSeatRuntime(entry.class, isFloor, isLead);
-    for (const name of seatNames(entry)) {
+    const canonicalEntry: ProfileRosterEntry = {
+      class: resolved.canonicalClass,
+      multiplicity: entry.multiplicity,
+      ...(entry.reportsTo
+        ? {
+            reportsTo:
+              (
+                await resolvePersonaFrom(entry.reportsTo, {
+                  rolesDir,
+                  overrideDir,
+                  base,
+                  over,
+                })
+              )?.canonicalClass ?? entry.reportsTo,
+          }
+        : {}),
+    };
+    const runtimeChoice = resolveSeatRuntime(resolved.canonicalClass, isFloor, isLead);
+    for (const name of seatNames(canonicalEntry)) {
      const seat: GeneratedSeat = {
        name,
-        className: entry.class,
+        className: resolved.canonicalClass,
        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;
+      if (canonicalEntry.reportsTo) seat.reportsTo = canonicalEntry.reportsTo;
      seats.push(seat);
    }
  }
@@ -279,13 +295,7 @@ export async function validateProfileForProvision(
  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  - ')}`,
-    );
-  }
+  await resolveProfilePersonas(profile, rolesDir, overrideDir);
 }

 // ---------------------------------------------------------------------------
--- a/packages/mosaic/src/fleet/persona-contract.spec.ts
+++ b/packages/mosaic/src/fleet/persona-contract.spec.ts
@@ -77,12 +77,25 @@ describe('readPersonaContractBlock — launch-time persona injection (A3b)', ()
  });

  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)');
+    seedOverride(home, 'mascot', '# Mascot\n\n(`class: mascot`)\n\nCUSTOM-ROLE.\n');
+    const block = readPersonaContractBlock(home, 'mascot');
+    expect(block).toContain('# Persona Contract (mascot)');
    expect(block).toContain('CUSTOM-ROLE');
  });

+  it('canonicalizes an approved alias before launch-time override lookup', () => {
+    seedBaseline(home, 'code', '# Code\n\n(`class: code`)\n\nCANONICAL-CODE.\n');
+    seedOverride(
+      home,
+      'implementer',
+      '# Legacy implementer\n\n(`class: implementer`)\n\nLEGACY-OVERRIDE.\n',
+    );
+    const block = readPersonaContractBlock(home, 'implementer');
+    expect(block).toContain('# Persona Contract (code)');
+    expect(block).toContain('CANONICAL-CODE');
+    expect(block).not.toContain('LEGACY-OVERRIDE');
+  });
+
  it('no-ops (empty string) when the class is undefined', () => {
    seedBaseline(home, 'coder', BASELINE_CODER);
    expect(readPersonaContractBlock(home, undefined)).toBe('');
--- a/packages/mosaic/src/fleet/roster-v2.spec.ts
+++ b/packages/mosaic/src/fleet/roster-v2.spec.ts
@@ -1,11 +1,14 @@
-import { readFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import {
  ROSTER_V2_JSON_SCHEMA,
  RosterV2ValidationError,
  parseRosterV2,
  renderRosterV2Yaml,
+  validateRosterV2Semantics,
 } from './roster-v2.js';

 const validRoster = `
@@ -40,6 +43,127 @@ agents:
      yolo: true
 `;

+let semanticTmp: string | undefined;
+
+afterEach(async (): Promise<void> => {
+  if (semanticTmp) await rm(semanticTmp, { recursive: true, force: true });
+  semanticTmp = undefined;
+});
+
+async function semanticDirs(): Promise<{ rolesDir: string; overrideDir: string }> {
+  semanticTmp = await mkdtemp(join(tmpdir(), 'roster-v2-semantics-'));
+  const rolesDir = join(semanticTmp, 'roles');
+  const overrideDir = join(semanticTmp, 'roles.local');
+  await mkdir(rolesDir, { recursive: true });
+  await mkdir(overrideDir, { recursive: true });
+  for (const klass of [
+    'code',
+    'review',
+    'interaction',
+    'orchestrator',
+    'merge-gate',
+    'validator',
+    'team-leader',
+  ]) {
+    await writeFile(join(rolesDir, `${klass}.md`), `# ${klass}\n\n(\`class: ${klass}\`)\n`, 'utf8');
+  }
+  return { rolesDir, overrideDir };
+}
+
+function rosterWithClass(klass: string, toolPolicy = klass): string {
+  return validRoster
+    .replace('class: code', `class: ${klass}`)
+    .replace('tool_policy: code', `tool_policy: ${toolPolicy}`);
+}
+
+describe('roster v2 semantic validation', (): void => {
+  it.each([
+    ['implementer', 'code'],
+    ['reviewer', 'review'],
+    ['operator-interaction', 'interaction'],
+  ])(
+    'canonicalizes requested alias %s while retaining requested and canonical class',
+    async (requested: string, canonical: string) => {
+      const dirs = await semanticDirs();
+      const roster = parseRosterV2(rosterWithClass(requested, requested), 'yaml');
+      const validated = await validateRosterV2Semantics(roster, dirs);
+      expect(validated.agents[0]).toMatchObject({
+        requestedClass: requested,
+        canonicalClass: canonical,
+        canonicalToolPolicy: canonical,
+      });
+    },
+  );
+
+  it.each(['worker', 'analyst', 'canary'])(
+    'rejects %s when no genuine custom role exists',
+    async (klass: string) => {
+      const dirs = await semanticDirs();
+      await expect(
+        validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass), 'yaml'), dirs),
+      ).rejects.toThrow(/unresolved|readable persona/i);
+    },
+  );
+
+  it('accepts a genuine custom roles.local class without protected authority', async () => {
+    const dirs = await semanticDirs();
+    await writeFile(join(dirs.overrideDir, 'worker.md'), '# worker\n\n(`class: worker`)\n', 'utf8');
+    const validated = await validateRosterV2Semantics(
+      parseRosterV2(rosterWithClass('worker'), 'yaml'),
+      dirs,
+    );
+    expect(validated.agents[0]?.authority).toMatchObject({
+      mayMerge: false,
+      mayOrchestrate: false,
+    });
+  });
+
+  it('rejects a LIBRARY-only class with no readable resolved persona', async () => {
+    const dirs = await semanticDirs();
+    await writeFile(
+      join(dirs.rolesDir, 'LIBRARY.md'),
+      '| Persona | Purpose |\n| --- | --- |\n| phantom | Missing |\n',
+      'utf8',
+    );
+    await expect(
+      validateRosterV2Semantics(parseRosterV2(rosterWithClass('phantom'), 'yaml'), dirs),
+    ).rejects.toThrow(/readable persona/i);
+  });
+
+  it('rejects an unreadable resolved persona', async () => {
+    const dirs = await semanticDirs();
+    await mkdir(join(dirs.overrideDir, 'worker.md'));
+    await expect(
+      validateRosterV2Semantics(parseRosterV2(rosterWithClass('worker'), 'yaml'), dirs),
+    ).rejects.toThrow(/readable persona/i);
+  });
+
+  it.each([
+    ['merge-gate', 'code'],
+    ['validator', 'merge-gate'],
+    ['orchestrator', 'interaction'],
+    ['team-leader', 'orchestrator'],
+    ['interaction', 'orchestrator'],
+    ['code', 'merge-gate'],
+    ['worker', 'validator'],
+  ])(
+    'denies protected class/tool-policy mismatch %s with %s',
+    async (klass: string, toolPolicy: string) => {
+      const dirs = await semanticDirs();
+      if (klass === 'worker') {
+        await writeFile(
+          join(dirs.overrideDir, 'worker.md'),
+          '# worker\n\n(`class: worker`)\n',
+          'utf8',
+        );
+      }
+      await expect(
+        validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass, toolPolicy), 'yaml'), dirs),
+      ).rejects.toThrow(/tool policy.*must match|mismatch/i);
+    },
+  );
+});
+
 describe('roster v2 structural compiler', (): void => {
  it('parses YAML into a normalized typed model and renders canonical YAML', (): void => {
    const roster = parseRosterV2(validRoster, 'yaml');
--- a/packages/mosaic/src/fleet/roster-v2.ts
+++ b/packages/mosaic/src/fleet/roster-v2.ts
@@ -1,4 +1,15 @@
 import YAML from 'yaml';
+import {
+  authorityForCanonicalClass,
+  canonicalizeRoleClass,
+  defaultOverrideDir,
+  defaultRolesDir,
+  extractClassesFromDir,
+  resolvePersonaFrom,
+  type PersonaDirs,
+  type PersonaResolution,
+  type RoleAuthority,
+} from '../commands/fleet-personas.js';

 export const ROSTER_V2_SUPPORTED_RUNTIMES = ['claude', 'codex', 'opencode', 'pi'] as const;
 export const ROSTER_V2_REASONING_LEVELS = ['low', 'medium', 'high'] as const;
@@ -58,6 +69,80 @@ export interface FleetRosterV2 {
  readonly agents: readonly FleetRosterV2Agent[];
 }

+export interface SemanticallyValidatedRosterV2Agent extends FleetRosterV2Agent {
+  readonly requestedClass: string;
+  readonly canonicalClass: string;
+  readonly canonicalToolPolicy: string;
+  readonly persona: PersonaResolution;
+  readonly authority: RoleAuthority;
+}
+
+export interface SemanticallyValidatedRosterV2 extends Omit<FleetRosterV2, 'agents'> {
+  readonly agents: readonly SemanticallyValidatedRosterV2Agent[];
+}
+
+const PROTECTED_TOOL_POLICY_CLASSES = new Set([
+  'merge-gate',
+  'validator',
+  'orchestrator',
+  'team-leader',
+  'interaction',
+]);
+
+/**
+ * Validate filesystem-backed roster semantics after synchronous structural parsing.
+ * Directory scans are batched once and every class must resolve to readable content.
+ */
+export async function validateRosterV2Semantics(
+  roster: FleetRosterV2,
+  opts: PersonaDirs = {},
+): Promise<SemanticallyValidatedRosterV2> {
+  const rolesDir = opts.rolesDir ?? defaultRolesDir(opts.mosaicHome);
+  const overrideDir = opts.overrideDir ?? defaultOverrideDir(opts.mosaicHome);
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+
+  const agents: SemanticallyValidatedRosterV2Agent[] = [];
+  for (const agent of roster.agents) {
+    const requestedClass = agent.className;
+    const { canonicalClass } = canonicalizeRoleClass(requestedClass);
+    const canonicalToolPolicy = canonicalizeRoleClass(agent.toolPolicy).canonicalClass;
+    const persona = await resolvePersonaFrom(requestedClass, {
+      rolesDir,
+      overrideDir,
+      base,
+      over,
+    });
+    if (!persona || persona.content.trim() === '') {
+      throw new RosterV2ValidationError(
+        `Roster v2 agent "${agent.name}" class "${requestedClass}" does not resolve to a readable persona.`,
+      );
+    }
+    if (
+      (PROTECTED_TOOL_POLICY_CLASSES.has(canonicalClass) ||
+        PROTECTED_TOOL_POLICY_CLASSES.has(canonicalToolPolicy)) &&
+      canonicalToolPolicy !== canonicalClass
+    ) {
+      throw new RosterV2ValidationError(
+        `Roster v2 agent "${agent.name}" protected class "${canonicalClass}" tool policy must match its canonical class; received "${agent.toolPolicy}".`,
+      );
+    }
+    agents.push(
+      Object.freeze({
+        ...agent,
+        requestedClass,
+        canonicalClass,
+        canonicalToolPolicy,
+        persona,
+        authority: authorityForCanonicalClass(canonicalClass),
+      }),
+    );
+  }
+  return Object.freeze({ ...roster, agents: Object.freeze(agents) });
+}
+
 export class RosterV2ValidationError extends Error {
  constructor(message: string) {
    super(message);