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

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