test(fleet): validate shipped artifact dispositions (#770 )

feat(fleet): add shared role semantics (#768 )
2026-07-15 01:37:12 +00:00 · 2026-07-15 00:53:47 +00:00
24 changed files with 1952 additions and 178 deletions
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -53,10 +53,10 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.

 | id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                                    |
-| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
-| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | M0 exit: approved docs; every shipped example/profile/service preset classified; docs-only PR                    |
-| FCM-M1-001 | not-started | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | codex  | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | No lifecycle, remote, connector, secret, channel, or gateway work                                                |
-| FCM-M1-002 | not-started | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | codex  | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Validator is certificate-only; merge-gate remains sole merge authority                                           |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                           |
+| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation                       |
+| FCM-M1-002 | in-progress | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Started 2026-07-14 from `aa5b43b`; one shared resolver only; validator certificate-only; merge-gate sole merge authority |
 | FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | Every shipped artifact must validate, be versioned v1, or be retired with replacement                                    |
 | FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | No arbitrary command compatibility path; diagnostics expose key names/hashes only                                        |
 | FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | Fresh create persists stopped unless explicit persisted start                                                            |
--- a/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md
+++ b/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md
@@ -7,7 +7,8 @@ The v2 compiler may not silently accept an unresolved class. Before M1 exits, ev
 below must be either migrated and executable, retained as an explicitly versioned v1 fixture, or
 retired with a replacement/deprecation note. Class resolution must use the existing
 profile/persona/provision baseline-plus-`roles.local` resolver; this inventory does not create a
-parallel resolver.
+parallel resolver. The current executable implementation and per-artifact outcomes are recorded in
+[the disposition evidence](./migration/example-profile-disposition.md).

 ## Examples

--- a/docs/fleet/how-to/customize-roles.md
+++ b/docs/fleet/how-to/customize-roles.md
@@ -0,0 +1,54 @@
+# Customize Fleet Roles
+
+Mosaic resolves persona contracts through two layers:
+
+1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
+2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
+
+The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
+and launch-time persona injection.
+
+## Override a baseline role
+
+Create a readable Markdown contract under `roles.local` with the canonical filename and class marker:
+
+```markdown
+# Code — local role definition
+
+The local code role (`class: code`) follows the operator's repository conventions.
+```
+
+Save it as `fleet/roles.local/code.md`. Do not edit generated or seeded baseline assets when the goal
+is a durable local customization.
+
+Legacy aliases canonicalize before lookup. Therefore `roles.local/implementer.md` does not override
+`code`; use `roles.local/code.md`. See [Legacy Fleet Class Aliases](../migration/legacy-class-aliases.md).
+
+## Add a custom class
+
+A custom class remains supported when a readable contract exists for the exact identifier:
+
+```markdown
+# Release notes — local role definition
+
+The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
+```
+
+Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
+`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
+
+Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
+contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
+
+## Validation and authority boundaries
+
+Semantic validation reads the winning contract and rejects missing, unreadable, or empty files.
+Protected authority is derived from canonical class metadata in code, never from role prose. A custom
+contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.
+
+Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
+or when an unprotected class claims a protected tool policy. The legacy `operator-interaction` policy
+canonicalizes to `interaction`.
+
+Role customization does not issue leases, store validation certificates, mutate credentials, or
+change lifecycle state.
--- a/docs/fleet/migration/example-profile-disposition.md
+++ b/docs/fleet/migration/example-profile-disposition.md
@@ -0,0 +1,52 @@
+# Executable Fleet Example, Profile, and Service-Preset Dispositions
+
+**Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence
+
+This document records the executable disposition for every currently shipped fleet YAML artifact.
+The authoritative baseline classification remains the
+[legacy inventory](../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md). The executable guard is
+`packages/mosaic/src/fleet/example-profile-dispositions.ts`; its test fails if a shipped YAML
+artifact is added, removed, or left without one of the dispositions below.
+
+## Disposition rules
+
+- **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
+  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
+  roster or given inferred aliases.
+- **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
+  baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
+- **Canonical service policy:** the artifact is loaded through the operator-interaction service
+  policy reader and provisioned with a generic supplied identity. It validates its runtime, model,
+  reasoning, and legacy tool-policy compatibility without hardcoding a product identity.
+
+No artifact is retired in this card. A later retirement requires both a replacement link and a
+visible deprecation note; the executable guard must then record the new disposition before the
+artifact can be removed.
+
+## Shipped artifacts
+
+| Artifact                             | Disposition              | Executable path                   | Compatibility notes                                                                              |
+| ------------------------------------ | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `examples/coding.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains approved `implementer` and `reviewer` compatibility inputs.                              |
+| `examples/general.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains unresolved `worker` without an inferred canonical role.                                  |
+| `examples/hybrid.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains `implementer`, `reviewer`, and resolver-dependent `researcher`.                          |
+| `examples/local-canary.yaml`         | Explicit v1 fixture      | v1 roster parser                  | Retains the local-tmux canary topology.                                                          |
+| `examples/minimal.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains `canary` without an inferred canonical role.                                             |
+| `examples/operator-interaction.yaml` | Explicit v1 fixture      | v1 roster parser                  | Keeps Tess only as an example instance name; `operator-interaction` remains compatibility input. |
+| `examples/research.yaml`             | Explicit v1 fixture      | v1 roster parser                  | Retains resolver-dependent `researcher` and `analyst`.                                           |
+| `profiles/business.yaml`             | Canonical profile        | shared profile/persona resolver   | Every referenced business class must resolve to a readable contract.                             |
+| `profiles/marketing.yaml`            | Canonical profile        | shared profile/persona resolver   | Every referenced marketing class must resolve to a readable contract.                            |
+| `profiles/personal-assistant.yaml`   | Canonical profile        | shared profile/persona resolver   | No interaction equivalence is inferred.                                                          |
+| `profiles/research.yaml`             | Canonical profile        | shared profile/persona resolver   | Every research class must resolve to a readable contract.                                        |
+| `profiles/software-delivery.yaml`    | Canonical profile        | shared profile/persona resolver   | Retains the governance profile; authority validation remains FCM-M1-002 evidence.                |
+| `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess.             |
+
+## Running the guard
+
+```bash
+pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
+```
+
+The guard is intentionally limited to shipped assets and validation. It does not generate
+environment files, mutate a roster, reconcile a fleet, migrate an installed roster, or launch an
+agent.
--- a/docs/fleet/migration/legacy-class-aliases.md
+++ b/docs/fleet/migration/legacy-class-aliases.md
@@ -0,0 +1,40 @@
+# Legacy Fleet Class Aliases
+
+Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy
+class names and converts them to canonical classes before persona lookup:
+
+| Legacy value           | Canonical value | Migration action                                                                                                       |
+| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `implementer`          | `code`          | Replace class and tool-policy references with `code`.                                                                  |
+| `reviewer`             | `review`        | Replace class and tool-policy references with `review`.                                                                |
+| `operator-interaction` | `interaction`   | Replace class and roster-v2 tool-policy references with `interaction`. The legacy service artifact remains compatible. |
+
+Alias support preserves existing inputs while provisioning and typed semantic output use canonical
+identities. Requested and canonical class values remain separately observable during semantic
+validation.
+
+## Lookup and override behavior
+
+Canonicalization precedes baseline and `roles.local` lookup. A legacy-named override such as
+`roles.local/implementer.md` is not a separate authority and is not selected for an `implementer`
+request. Customize the canonical role instead, for example `roles.local/code.md`.
+
+The compatibility file `operator-interaction.md` remains shipped, but `interaction` is the canonical
+role class. Tess is an example display name only.
+
+## Unresolved and custom classes
+
+No names are inferred from historical usage, instance names, or similar wording. `worker`, `analyst`,
+`canary`, Tess, and Ultron are not aliases. An otherwise unknown class is accepted only if the shared
+resolver can read an actual baseline or `roles.local` contract for that exact class. A `LIBRARY.md`
+row without a readable contract fails semantic validation.
+
+Custom classes receive no protected authority implicitly. Protected class/tool-policy mismatches
+fail closed.
+
+## Retirement guidance
+
+New configuration should emit canonical values. Existing inputs may use the three aliases during the
+compatibility period, but operators should migrate class and tool-policy fields together. Do not
+create new legacy-named role overrides; move their intended content to the canonical filename and
+validate the roster/profile before removing the old artifact.
--- a/docs/fleet/reference/role-classes.md
+++ b/docs/fleet/reference/role-classes.md
@@ -0,0 +1,45 @@
+# Fleet Role Classes and Authority
+
+A fleet role class is a machine identity resolved from the persona library. Resolution uses the
+canonical class before consulting the baseline `fleet/roles/` and operator `fleet/roles.local/`
+layers. A readable role contract is required; an index entry alone is not semantic success.
+
+## Canonicalization
+
+Only these legacy class aliases are recognized:
+
+| Requested class        | Canonical class |
+| ---------------------- | --------------- |
+| `implementer`          | `code`          |
+| `reviewer`             | `review`        |
+| `operator-interaction` | `interaction`   |
+
+No other alias is inferred. In particular, `worker`, `analyst`, and `canary` are custom classes only
+when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
+names, not classes. `agents[].alias` is display-only and cannot grant authority.
+
+Canonicalization happens before role lookup. For example, requesting `implementer` resolves
+`code.md`; a separate `roles.local/implementer.md` cannot redefine the legacy alias. A canonical
+`roles.local/code.md` still overrides the baseline `roles/code.md` contract.
+
+## Protected authority
+
+Protected authority is immutable metadata derived only from canonical class. Role prose, instance
+name, display alias, tool policy, runtime, and custom role files cannot grant it.
+
+| Canonical class   | Granted authority                                  | Explicit limits                                                                   |
+| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `merge-gate`      | Sole approve-to-land and merge authority           | No authority is inferred by similarly named custom roles or policies.             |
+| `validator`       | May issue a validation certificate                 | Cannot approve-to-land or merge.                                                  |
+| `orchestrator`    | May orchestrate, manage topology, and issue leases | Cannot approve-to-land or merge.                                                  |
+| `team-leader`     | May use orchestrator-leased capacity               | Cannot issue leases or mutate roster, configuration, credentials, or merge state. |
+| `interaction`     | Request and status surface                         | Cannot orchestrate, issue leases, mutate roster/configuration, or merge.          |
+| all other classes | No protected authority implicitly                  | Custom contracts do not acquire protected powers from prose.                      |
+
+Roster-v2 semantic validation requires a protected class and its canonical tool policy to match. It
+also rejects an unprotected class paired with a protected tool policy. The legacy tool-policy name
+`operator-interaction` canonicalizes to `interaction`.
+
+This mapping describes authority metadata only. Lease issuance, validation-certificate storage or
+workflow, lifecycle reconciliation, credentials, roster mutation, and merge execution are outside
+this resolver contract.
--- a/docs/fleet/reference/roster-v2-fields.md
+++ b/docs/fleet/reference/roster-v2-fields.md
@@ -81,6 +81,35 @@ agents:
 | `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                               |
 | `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                 |

+## Semantic handoff
+
+`parseRosterV2` and `normalizeRosterV2` remain synchronous and structural. After structural success,
+call the asynchronous `validateRosterV2Semantics` handoff before using persona identity or authority.
+That validator batches the baseline `fleet/roles/` and operator `fleet/roles.local/` scans, then
+delegates every agent to the shared persona resolver.
+
+Semantic validation:
+
+- requires the winning role contract to be readable and non-empty; `LIBRARY.md` membership alone does
+  not resolve a class;
+- retains `requestedClass` separately from `canonicalClass` in typed output;
+- canonicalizes only `implementer` to `code`, `reviewer` to `review`, and
+  `operator-interaction` to `interaction`;
+- canonicalizes `tool_policy` with the same exact alias table;
+- rejects protected class/tool-policy mismatches in either direction, while accepting
+  `class: operator-interaction` with `tool_policy: operator-interaction` as canonical
+  `interaction`;
+- derives immutable protected authority only from canonical class; and
+- accepts custom baseline or `roles.local` classes without granting protected authority.
+
+`agents[].alias` remains display-only. Tess and Ultron are instance names, never semantic classes.
+Canonicalization happens before role-layer lookup, so a legacy-named override cannot redefine an
+alias as separate authority. See [Role Classes and Authority](./role-classes.md) and
+[Customize Fleet Roles](../how-to/customize-roles.md).
+
+This handoff performs no filesystem, systemd, tmux, roster, credential, lease, certificate, or
+lifecycle mutation.
+
 ## Fail-closed boundary

 Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,
--- a/docs/scratchpads/758-fcm-m1-002-shared-role-resolution.md
+++ b/docs/scratchpads/758-fcm-m1-002-shared-role-resolution.md
@@ -0,0 +1,148 @@
+# FCM-M1-002 — Shared role resolution
+
+- **Task:** `FCM-M1-002`
+- **Issue:** `mosaicstack/stack#758`
+- **Branch:** `feat/758-shared-role-resolution`
+- **Starting head:** `32e75c67b094de443d37fe7d5ff8d25cdfc8b39d`
+- **Role:** implementation worker; independent review and merge remain outside this worker
+
+## Objective
+
+Reuse the existing baseline-plus-`roles.local` persona resolver as the sole class authority for roster-v2 semantics, profile validation, provisioning, and launch/persona resolution. Add exact approved alias canonicalization, fail-closed semantic validation, immutable canonical-class authority contracts, required baseline roles, and operator documentation without implementing lifecycle, mutation, credentials, certificate workflow, or later FCM cards.
+
+## Budget
+
+- Soft budget: **25K tokens**.
+- Strategy: inspect once, implement in small TDD units, run focused suites before the full package gate, and avoid unrelated refactors or M1-003/M2/M4 scope.
+
+## Plan
+
+1. Map the existing persona resolver, roster-v2 compiler, profile/provision consumers, launch resolution, role library, and focused tests.
+2. Write denial/invariant tests first for aliases, canonicalization-before-override, unreadable roles, authority boundaries, policy mismatch, canonical provision output, and resolver parity.
+3. Run the focused suites and record the expected red evidence.
+4. Implement one shared canonical resolution and authority contract in/through `fleet-personas.ts`; delegate roster semantic validation and profile/provision paths to it.
+5. Add baseline `validator`, `team-leader`, and `interaction` role contracts plus `LIBRARY.md` entries while retaining `operator-interaction` compatibility.
+6. Add the required role reference, alias migration, customization guide, and roster-v2 semantic handoff documentation.
+7. Run focused tests, the full `@mosaicstack/mosaic` suite, typecheck, lint, Prettier, `git diff --check`, situational verification, independent code/security review, and remediation.
+8. Commit with the required co-author trailer, run the CI queue guard, push the existing branch, and create/update exactly one PR to `main` with `Refs #758`.
+
+## TDD evidence
+
+### Red
+
+After installing worktree-local dependencies and building `@mosaicstack/db`, the pre-implementation
+focused run collected the intended tests and failed as expected:
+
+```text
+2 test files failed; 32 tests failed; 32 tests passed
+```
+
+Expected failures named the missing `canonicalizeRoleClass`,
+`authorityForCanonicalClass`, and `validateRosterV2Semantics` APIs, absent requested/canonical typed
+output, and unresolved required canonical role contracts. An earlier run that failed before test
+collection on an unresolved `yaml` dependency was treated as environment setup, not TDD evidence.
+
+### Green
+
+Focused role-resolution and affected service fixtures:
+
+```text
+6 test files passed; 109 tests passed
+```
+
+The focused set covers personas, profiles, provision, launch persona contract, roster-v2 semantics,
+and the operator-interaction service fixture. The final profile tests also cover readable lead/floor
+compatibility and canonical collision denial.
+
+## Tests and gates
+
+- Focused suites: pass, **6 files / 109 tests**.
+- Full `@mosaicstack/mosaic` suite: pass, **50 files / 713 tests**. Workspace package build outputs
+  were prepared first because a clean worktree has no dependency `dist` entries.
+- `pnpm --filter @mosaicstack/mosaic typecheck`: pass.
+- `pnpm --filter @mosaicstack/mosaic lint`: pass.
+- Prettier check over every changed file: pass.
+- `git diff --check`: pass.
+- Runtime/file-boundary evidence: real role library, profile/provision filesystem integration,
+  launch-time synchronous contract injection, v1 roster parser round-trip, roster-v2 semantic
+  filesystem checks, and operator-interaction service fixtures all pass without live mutation.
+- Independent code review: **APPROVE**, no blocking or non-blocking findings; reviewed complete
+  tracked/untracked delta including the canonical collision guard. Residual: roster-v2 semantic
+  validation is an explicit async handoff with production caller wiring owned by later work.
+- Independent security review: **APPROVE**, no verified authority/security findings on the final
+  delta.
+
+### Post-PR fail-closed remediation
+
+Independent rereview found resolver fail-open edges that the original green PR head did not cover. The
+remediation remained uncommitted until every finding was reproduced red-first and the same reviewer
+approved the complete two-file delta.
+
+Final regression evidence:
+
+```text
+persona resolver: 47/47
+focused affected suites: 6 files / 138 tests
+root-container resolver suites: 86/86
+full canonical run: 42/42 Turbo tasks; Mosaic 50 files / 733 tests
+```
+
+DB migration, typecheck, lint, Prettier, and `git diff --check` also passed. Coverage now proves:
+
+- unreadable, unscannable, direct-dangling, ancestor-dangling, and literal `..` traversal override paths
+  fail closed across async, sync, listing, and status APIs;
+- genuinely missing override directories still permit baseline fallback;
+- cached missing scans are revalidated before fallback;
+- marker-defined identity and domain metadata are revalidated on the second read;
+- `LIBRARY.md` rows and incidental later markers cannot define, shadow, or advertise personas.
+
+Exact-head pipeline `1819` passed for rebased head `4d990eee…`, but the independent reviewer-of-record
+returned **REQUEST CHANGES** after reproducing three additional edge failures: a canonical filename could
+inherit protected authority despite a conflicting explicit first marker, cached `scanned` absence could
+miss an override created before baseline fallback, and inherited plain-object names such as `constructor`
+could corrupt alias/authority lookup. Merge remained held.
+
+Each failure was reproduced red-first in the persona suite (4 failing assertions), then remediated without
+expanding card scope. Explicit first markers now own identity and filename fallback applies only to
+markerless contracts; every second read rejects a newly introduced conflicting marker regardless of
+cached classification; cached async resolution re-scans the override layer immediately before every
+baseline fallback; alias and authority registries require own-property matches. Current uncommitted
+evidence is persona **52/52**, focused affected suites **6 files / 143 tests**, and full Mosaic package
+**50 files / 738 tests**, plus typecheck, lint, Prettier, and `git diff --check`. Independent
+finding-specific rereview **APPROVED** the complete uncommitted three-file remediation after direct
+adversarial reproduction of all three findings and the follow-up markerless TOCTOU. All post-commit
+exact-head gates remain required.
+
+## Risks and boundaries
+
+- **Security-sensitive authority:** authority must derive only from canonical class, never role prose, aliases, display names, or tool-policy text.
+- **Resolver divergence:** no second regex, registry, scanner, or prose parser may be introduced.
+- **Alias capture:** aliases must canonicalize before baseline/`roles.local` lookup so local files cannot redefine legacy aliases as separate authority.
+- **Readable persona requirement:** semantic success requires a resolved readable persona, not class-set membership.
+- **Scope control:** no roster mutation, lifecycle, lease issuance, certificate workflow/storage, credentials, remote reconciliation, provision-v2 conversion, or shipped-example disposition execution.
+- **Coordination:** `docs/TASKS.md` is read-only and remains orchestrator-owned.
+
+## Acceptance-evidence mapping
+
+| Requirement / criterion | Verification evidence |
+| --- | --- |
+| `FCM-REQ-02` shared semantic resolver | Async/sync resolver parity; roster-v2 delegates batched scans and resolution; profiles/provision and launch reuse `fleet-personas.ts`; no second scanner or class-marker regex added. |
+| `FCM-REQ-07` canonical classes and authority boundaries | Exact alias and non-alias tests; immutable authority invariant tests; all required canonical contracts resolve through the real role library. |
+| `AC-FCM-01` structural + semantic roster validation | Synchronous parser/normalizer tests remain intact; async semantic tests cover aliases, custom roles, unreadable/unresolved roles, `LIBRARY`-only rejection, and bidirectional protected policy mismatch. |
+| `AC-FCM-07` protected authority invariants | Denial tests prove merge-gate-only merge, validator certificate-only, orchestrator/team-leader/interaction limits, no implicit custom-role authority, and canonical tool-policy matching. |
+
+## Documentation
+
+- `docs/fleet/reference/role-classes.md`
+- `docs/fleet/migration/legacy-class-aliases.md`
+- `docs/fleet/how-to/customize-roles.md`
+- `docs/fleet/reference/roster-v2-fields.md` semantic handoff
+- Baseline role contracts and `LIBRARY.md` rows for `validator`, `team-leader`, and `interaction`
+
+## Residual risks
+
+- Provisioning remains intentionally v1 and does not emit `reports_to`; canonical topology is retained
+  in its typed seat/summary path only, matching the existing v1 parser boundary.
+- Alias support remains for compatibility; new configuration should emit canonical identities.
+- This card defines authority metadata and validation only. Enforcement workflows for leases,
+  certificates, lifecycle, and mutation remain owned by later FCM cards.
--- a/docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md
+++ b/docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md
@@ -0,0 +1,37 @@
+# FCM-M1-003 — Executable example/profile/service-preset dispositions
+
+- **Task / issue:** FCM-M1-003 / #758
+- **Branch / base:** `test/758-example-profile-dispositions` from `origin/main` `a5e8e554012f27898e035d2882a8e47e1a02fe97`
+- **Objective:** Make every artifact in the M0 legacy disposition inventory executable evidence: it must validate canonically, be explicitly retained as a v1 fixture, or be retired with a replacement/deprecation link.
+- **Scope:** Validation and explicit version/retirement metadata only for shipped examples, profiles, and the operator-interaction service preset. Reuse the central resolver and existing v2 roster compiler.
+- **Out of scope:** Generated environment boundaries, CRUD, reconciliation/apply, migration, live fleet mutation, and `docs/TASKS.md`.
+- **Budget:** 20K card allocation; use focused package tests before full package validation.
+
+## Plan
+
+1. Inventory exact shipped artifacts and existing compiler/resolver/profile tests.
+2. Add failing behavior tests covering all listed artifacts and their documented disposition.
+3. Implement minimal declarative fixture/disposition validation; do not add a role/class resolver.
+4. Run focused and package quality gates; obtain independent code and security review.
+5. Commit, queue-guard, push, open one `main` PR with `Refs #758`.
+
+## Progress
+
+- Intake complete: verified no branch, worktree, or open PR for this card before creating this isolated worktree.
+- Requirements read: FCM PRD, FCM-M1-003 task row, M0 disposition inventory, delivery/QA/documentation guides.
+- TDD: RED recorded with `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` failing because the new module did not exist; GREEN recorded after the minimal guard implementation. The focused suite now has 4 passing tests, including undeclared-artifact and missing-explicit-v1-version denials.
+- Independent review: initial code review found the service policy path was hardcoded; remediation iterates declared `canonical-service-policy` artifacts. Exact-head code review approved and exact-head security review found no issues.
+
+## Risks / decisions
+
+- The M0 inventory permits unresolved legacy roles only when explicitly v1-versioned or retired. Do not infer aliases beyond the three approved by FCM-M1-002.
+- `docs/TASKS.md` is orchestrator-owned and will not be edited.
+
+## Verification evidence
+
+- Focused TDD guard: `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` — PASS (4 tests).
+- Full package suite: `pnpm --filter @mosaicstack/mosaic test` — PASS (51 files, 742 tests).
+- Static gates: `pnpm --filter @mosaicstack/mosaic typecheck`, `pnpm --filter @mosaicstack/mosaic lint`, and `pnpm format:check` — PASS.
+- Diff gate: `git diff --check` — PASS.
+- Exact-head reviews: `codex-code-review.sh --uncommitted` — APPROVE; `codex-security-review.sh --uncommitted` — no findings.
+- Delivery: committed as `9a9ad1a`, pushed after `ci-queue-wait.sh --purpose push`, and opened PR [#770](https://git.mosaicstack.dev/mosaicstack/stack/pulls/770) to `main` with `Refs #758`. `pr-ci-wait.sh -n 770` reported terminal-green Woodpecker pipeline [#1823](https://ci.mosaicstack.dev/repos/47/pipeline/1823/1).
--- 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/example-profile-dispositions.spec.ts
+++ b/packages/mosaic/src/fleet/example-profile-dispositions.spec.ts
@@ -0,0 +1,90 @@
+import { cp, mkdtemp, readFile, 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, describe, expect, it } from 'vitest';
+import {
+  SHIPPED_FLEET_ARTIFACT_DISPOSITIONS,
+  validateShippedFleetArtifactDispositions,
+} from './example-profile-dispositions.js';
+
+const frameworkFleet = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'framework',
+  'fleet',
+);
+
+const EXPECTED_DISPOSITIONS = [
+  'examples/coding.yaml:v1-fixture',
+  'examples/general.yaml:v1-fixture',
+  'examples/hybrid.yaml:v1-fixture',
+  'examples/local-canary.yaml:v1-fixture',
+  'examples/minimal.yaml:v1-fixture',
+  'examples/operator-interaction.yaml:v1-fixture',
+  'examples/research.yaml:v1-fixture',
+  'profiles/business.yaml:canonical-profile',
+  'profiles/marketing.yaml:canonical-profile',
+  'profiles/personal-assistant.yaml:canonical-profile',
+  'profiles/research.yaml:canonical-profile',
+  'profiles/software-delivery.yaml:canonical-profile',
+  'services/operator-interaction.yaml:canonical-service-policy',
+];
+
+const declared = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(
+  ({ path, disposition }): string => `${path}:${disposition}`,
+);
+
+describe('shipped fleet example/profile/service disposition validation', (): void => {
+  it('enumerates every inventory artifact with an explicit executable disposition', (): void => {
+    expect(declared).toEqual(EXPECTED_DISPOSITIONS);
+  });
+
+  it('validates every shipped artifact through its declared v1 or canonical path', async (): Promise<void> => {
+    const results = await validateShippedFleetArtifactDispositions({ frameworkFleet });
+
+    expect(results.map(({ path, disposition }): string => `${path}:${disposition}`)).toEqual(
+      EXPECTED_DISPOSITIONS,
+    );
+    expect(results.filter(({ disposition }): boolean => disposition === 'v1-fixture')).toHaveLength(
+      7,
+    );
+    expect(
+      results.filter(({ disposition }): boolean => disposition === 'canonical-profile'),
+    ).toHaveLength(5);
+    expect(
+      results.find(({ path }): boolean => path === 'services/operator-interaction.yaml'),
+    ).toMatchObject({
+      disposition: 'canonical-service-policy',
+    });
+  });
+
+  let temporaryFleet: string | undefined;
+  afterEach(async (): Promise<void> => {
+    if (temporaryFleet) await rm(temporaryFleet, { recursive: true, force: true });
+    temporaryFleet = undefined;
+  });
+
+  it('fails closed when a shipped artifact lacks a declared disposition', async (): Promise<void> => {
+    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
+    await cp(frameworkFleet, temporaryFleet, { recursive: true });
+    await writeFile(join(temporaryFleet, 'examples', 'undeclared.yaml'), 'version: 1\n');
+
+    await expect(
+      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
+    ).rejects.toThrow(/undeclared shipped fleet artifact.*examples\/undeclared.yaml/i);
+  });
+
+  it('rejects a v1 fixture when its explicit version declaration is removed', async (): Promise<void> => {
+    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
+    await cp(frameworkFleet, temporaryFleet, { recursive: true });
+    const fixturePath = join(temporaryFleet, 'examples', 'coding.yaml');
+    const fixture = await readFile(fixturePath, 'utf8');
+    await writeFile(fixturePath, fixture.replace(/^version: 1\n/, ''));
+
+    await expect(
+      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
+    ).rejects.toThrow(/Fleet roster version must be 1/);
+  });
+});
--- a/packages/mosaic/src/fleet/example-profile-dispositions.ts
+++ b/packages/mosaic/src/fleet/example-profile-dispositions.ts
@@ -0,0 +1,121 @@
+import { readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { loadFleetRoster } from '../commands/fleet.js';
+import { loadProfiles } from '../commands/fleet-profiles.js';
+import {
+  provisionInteractionService,
+  readInteractionServiceProfile,
+} from './interaction-service-profile.js';
+
+export type FleetArtifactDisposition =
+  | 'v1-fixture'
+  | 'canonical-profile'
+  | 'canonical-service-policy';
+
+export interface ShippedFleetArtifactDisposition {
+  readonly path: string;
+  readonly disposition: FleetArtifactDisposition;
+}
+
+export interface ValidateShippedFleetArtifactDispositionsOptions {
+  readonly frameworkFleet: string;
+  readonly rolesDir?: string;
+  readonly overrideDir?: string;
+}
+
+/**
+ * The M0 inventory in executable form. Every shipped fleet YAML asset is either
+ * a deliberately retained v1 fixture or validated through its canonical loader.
+ */
+export const SHIPPED_FLEET_ARTIFACT_DISPOSITIONS: readonly ShippedFleetArtifactDisposition[] = [
+  { path: 'examples/coding.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/general.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/hybrid.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/local-canary.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/minimal.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/operator-interaction.yaml', disposition: 'v1-fixture' },
+  { path: 'examples/research.yaml', disposition: 'v1-fixture' },
+  { path: 'profiles/business.yaml', disposition: 'canonical-profile' },
+  { path: 'profiles/marketing.yaml', disposition: 'canonical-profile' },
+  { path: 'profiles/personal-assistant.yaml', disposition: 'canonical-profile' },
+  { path: 'profiles/research.yaml', disposition: 'canonical-profile' },
+  { path: 'profiles/software-delivery.yaml', disposition: 'canonical-profile' },
+  { path: 'services/operator-interaction.yaml', disposition: 'canonical-service-policy' },
+];
+
+/**
+ * Fail closed when a fleet YAML asset is added or removed without a disposition.
+ * This keeps legacy v1 compatibility explicit instead of silently accepting new
+ * unresolved classes outside the shared resolver.
+ */
+export async function validateShippedFleetArtifactDispositions(
+  options: ValidateShippedFleetArtifactDispositionsOptions,
+): Promise<readonly ShippedFleetArtifactDisposition[]> {
+  await assertEveryShippedArtifactIsDeclared(options.frameworkFleet);
+
+  const examples = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
+    ({ disposition }): boolean => disposition === 'v1-fixture',
+  );
+  for (const artifact of examples) {
+    const roster = await loadFleetRoster(join(options.frameworkFleet, artifact.path));
+    if (roster.version !== 1) {
+      throw new Error(`v1 fixture ${artifact.path} must declare version: 1`);
+    }
+  }
+
+  const profilesDir = join(options.frameworkFleet, 'profiles');
+  const profiles = await loadProfiles({
+    profilesDir,
+    rolesDir: options.rolesDir ?? join(options.frameworkFleet, 'roles'),
+    overrideDir: options.overrideDir ?? join(options.frameworkFleet, 'roles.local'),
+  });
+  const declaredProfiles = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
+    ({ disposition }): boolean => disposition === 'canonical-profile',
+  ).map(({ path }): string => basename(path, '.yaml'));
+  const resolvedProfiles = new Set(profiles.map(({ id }): string => id));
+  for (const profileId of declaredProfiles) {
+    if (!resolvedProfiles.has(profileId)) {
+      throw new Error(`declared canonical profile ${profileId} did not resolve`);
+    }
+  }
+
+  const servicePolicies = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
+    ({ disposition }): boolean => disposition === 'canonical-service-policy',
+  );
+  for (const artifact of servicePolicies) {
+    const serviceProfile = await readInteractionServiceProfile(
+      join(options.frameworkFleet, artifact.path),
+    );
+    provisionInteractionService(serviceProfile, { agentName: 'interaction-example' });
+  }
+
+  return SHIPPED_FLEET_ARTIFACT_DISPOSITIONS;
+}
+
+async function assertEveryShippedArtifactIsDeclared(frameworkFleet: string): Promise<void> {
+  const declared = new Set(SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(({ path }): string => path));
+  const shipped = await listShippedFleetArtifactPaths(frameworkFleet);
+
+  for (const path of shipped) {
+    if (!declared.has(path)) {
+      throw new Error(`undeclared shipped fleet artifact: ${path}`);
+    }
+  }
+  for (const path of declared) {
+    if (!shipped.has(path)) {
+      throw new Error(`declared shipped fleet artifact is missing: ${path}`);
+    }
+  }
+}
+
+async function listShippedFleetArtifactPaths(frameworkFleet: string): Promise<Set<string>> {
+  const directories = ['examples', 'profiles', 'services'];
+  const paths = new Set<string>();
+  for (const directory of directories) {
+    const files = await readdir(join(frameworkFleet, directory));
+    for (const file of files) {
+      if (file.endsWith('.yaml') || file.endsWith('.yml')) paths.add(`${directory}/${file}`);
+    }
+  }
+  return paths;
+}
--- 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);
Author	SHA1	Message	Date
jason.woltje	e9c4aa3e8b	test(fleet): validate shipped artifact dispositions (#770 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details	2026-07-15 01:37:12 +00:00
jason.woltje	a5e8e55401	feat(fleet): add shared role semantics (#768 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details	2026-07-15 00:53:47 +00:00