@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/demo.mjs

@@ -2,19 +2,23 @@
  * lib/demo.mjs — `construct demo` terminal recordings via VHS `.tape` files.
  *
  * Shipped tapes live in templates/demos/tapes/; project overrides in
- * .cx/demos/tapes/. Built-in scaffolds via `construct demo init --from=`.
- * Default run mode launches construct chat with a demo script; use `record` or
- * --surface=tape for VHS. Dashboard demos delegate to lib/dashboard-demo.mjs.
+ * .cx/demos/tapes/. Built-in scaffolds via `construct demo init --from=`;
+ * `--from-project` scaffolds a project demo plug-in (manifest + script + tape)
+ * under .cx/demos/ seeded from real project signals (see lib/demo-project.mjs).
+ * Default run mode writes or records a VHS tape; use `tour` for a linear
+ * guided walkthrough and `--surface=playwright` for recording manifests.
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve, dirname, basename, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { listDemoScripts } from './demo-script.mjs';
+import { listDemoScripts, loadDemoScript } from './demo-script.mjs';
 import { DEMO_SURFACES } from './demo-surface.mjs';
+import { renderTour } from './demo-tour-renderer.mjs';
 import { listDemoRecordings, loadDemoRecording } from './demo-recording.mjs';
 import { recordPlaywrightDemo } from './playwright-demo.mjs';
+import { scaffoldProjectDemo } from './demo-project.mjs';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -219,7 +223,7 @@ export function initConstructCockpitRecording(name, { cwd, repoRoot = REPO_ROOT
     ...reference,
     name,
     title: reference.title,
-    output: { format: 'mp4', path: `.cx/demos/dashboard/${name}.mp4` },
+    output: { format: 'mp4', path: `.cx/demos/${name}.mp4` },
     _reference: 'agentic-platforms-prd',
   };
   delete recording.sourcePath;
@@ -228,7 +232,7 @@ export function initConstructCockpitRecording(name, { cwd, repoRoot = REPO_ROOT
   return {
     ok: true,
     recordingPath: recPath,
-    message: `Scaffolded Construct cockpit recording ${recPath} (references apps/dashboard spec)`,
+    message: `Scaffolded Construct cockpit recording ${recPath}`,
   };
 }
 
@@ -306,10 +310,6 @@ export function listProjectTapes({ cwd = process.cwd(), repoRoot = REPO_ROOT } =
 }
 
 export function resolveTapeSource(name, { cwd, repoRoot = REPO_ROOT, artifactPath } = {}) {
-  if (name.startsWith('dashboard:')) {
-    return { kind: 'dashboard', name: name.slice('dashboard:'.length) };
-  }
-
   const tapePath = resolveTapeFile(name, { cwd, repoRoot });
   if (tapePath) {
     let source = readFileSync(tapePath, 'utf8');
@@ -402,10 +402,6 @@ export function runDemoRecord(name, {
   required = false,
   surface = null,
 } = {}) {
-  if (name.startsWith('dashboard:')) {
-    return { ok: false, name, message: 'Use recordDashboardDemo for dashboard: demos' };
-  }
-
   const recording = loadDemoRecording(name, { cwd, repoRoot });
   const usePlaywright = surface !== 'tape'
     && (surface === 'playwright' || (recording && recording.engine === 'playwright'));
@@ -506,28 +502,28 @@ export function printHelp() {
 Commands:
   list                     List tapes, recordings, and demo scripts
   init <name> [--from=T]     Scaffold tape or Playwright recording
+  init <name> --from-project Scaffold a project demo plug-in under .cx/demos/
   record <name>              Record VHS tape or Playwright demo manifest
-  <name>                     Run guided demo (default: construct chat)
+  tour [name]                Linear, screen-reader-friendly guided tour
+  <name>                     Record or print the demo (default: tape)
 
-Default run uses construct chat with a demo script (templates/demos/scripts/).
-Falls back to web chat, VHS tape, Playwright, dashboard, or printed steps.
+Default run uses VHS tape templates and falls back to printed script steps.
 
 Options:
   --surface=<s>  ${surfaces}
-  --model <id>   Pin model for chat demo
-  --web          Open web chat (/chat/) instead of terminal
-  --plain        Linear chat renderer
-  --free         OpenRouter free-router mode
+  --accessible   Screen-reader-friendly linear renderer (tour)
+  --skip-input   Tour: auto-advance without waiting for Enter (headless/CI)
   --format <f>   gif (default) | mp4 | webm
   --out <path>   Output path (recording)
+  --from-project  init: scaffold a project demo plug-in under .cx/demos/
   --source-only  Tape: write .tape only; skip recording
   -h, --help     Show this message
 
 Examples:
   construct demo agentic-platforms-prd
+  construct demo tour agentic-platforms-prd --accessible
   construct demo record agentic-platforms-prd --format mp4
   construct demo init marketing --from=nextjs-static
-  construct demo dashboard:cockpit-tour
 `);
 }
 
@@ -539,22 +535,19 @@ function parseArgs(argv) {
     from: 'quickstart',
     command: null,
     name: null,
-    surface: 'chat',
-    model: null,
-    plain: false,
+    surface: 'tape',
     accessible: false,
-    web: false,
-    free: false,
+    skipInput: false,
+    fromProject: false,
   };
   const positional = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--from-project') { options.fromProject = true; continue; }
     if (arg === '--source-only') { options.sourceOnly = true; continue; }
-    if (arg === '--plain') { options.plain = true; continue; }
     if (arg === '--accessible') { options.accessible = true; continue; }
-    if (arg === '--web') { options.web = true; continue; }
-    if (arg === '--free') { options.free = true; continue; }
+    if (arg === '--skip-input') { options.skipInput = true; continue; }
     if (arg === '--format') { options.format = argv[++i]; continue; }
     if (arg.startsWith('--format=')) { options.format = arg.slice(9); continue; }
     if (arg === '--out') { options.out = argv[++i]; continue; }
@@ -563,13 +556,12 @@ function parseArgs(argv) {
     if (arg.startsWith('--from=')) { options.from = arg.slice(7); continue; }
     if (arg === '--surface') { options.surface = argv[++i]; continue; }
     if (arg.startsWith('--surface=')) { options.surface = arg.slice(10); continue; }
-    if (arg === '--model') { options.model = argv[++i]; continue; }
-    if (arg.startsWith('--model=')) { options.model = arg.slice(8); continue; }
     positional.push(arg);
   }
   if (positional[0] === 'list') options.command = 'list';
   else if (positional[0] === 'init') { options.command = 'init'; options.name = positional[1]; }
   else if (positional[0] === 'record') { options.command = 'record'; options.name = positional[1]; }
+  else if (positional[0] === 'tour') { options.command = 'tour'; options.name = positional[1] || null; }
   else options.name = positional[0] || null;
   return options;
 }
@@ -591,7 +583,7 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     console.log('\nPlaywright recordings (.cx/demos/recordings/ overrides templates/demos/recordings/):');
     if (!recordings.length) console.log('  (none — run `construct demo init <name> --from=nextjs-static`)');
     else for (const r of recordings) console.log(`  ${r}`);
-    console.log('\nDemo scripts (chat-guided; templates/demos/scripts/):');
+    console.log('\nDemo scripts (tour steps; templates/demos/scripts/):');
     if (!scripts.length) console.log('  (none)');
     else for (const s of scripts) console.log(`  ${s}`);
     console.log(`\nScaffold templates: ${RECORDING_INIT_TEMPLATES.join(', ')}`);
@@ -599,8 +591,21 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
   }
 
   if (options.command === 'init') {
+    if (options.fromProject) {
+      if (!options.name) {
+        console.error('Usage: construct demo init <name> --from-project');
+        process.exit(1);
+      }
+      const result = scaffoldProjectDemo(options.name, { cwd, repoRoot });
+      if (!result.ok) {
+        console.error(result.message);
+        process.exit(1);
+      }
+      console.log(result.message);
+      return;
+    }
     if (!options.name) {
-      console.error(`Usage: construct demo init <name> [--from=${RECORDING_INIT_TEMPLATES.join('|')}]`);
+      console.error(`Usage: construct demo init <name> [--from=${RECORDING_INIT_TEMPLATES.join('|')}] | --from-project`);
       process.exit(1);
     }
     const result = initProjectRecording(options.name, { cwd, from: options.from, repoRoot });
@@ -612,28 +617,45 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     return;
   }
 
-  const demoName = options.command === 'record' ? options.name : options.name;
-  if (!demoName) {
-    printHelp();
-    process.exit(1);
-  }
-
-  if (demoName.startsWith('dashboard:')) {
-    const { recordDashboardDemo } = await import('./dashboard-demo.mjs');
-    const result = recordDashboardDemo(demoName.slice('dashboard:'.length), { cwd, repoRoot });
+  if (options.command === 'tour') {
+    const scripts = listDemoScripts({ cwd, repoRoot });
+    const tourName = options.name || scripts[0] || null;
+    if (!tourName) {
+      console.error('No demo scripts found. Add one under templates/demos/scripts/ or .cx/demos/scripts/.');
+      process.exit(1);
+    }
+    const script = loadDemoScript(tourName, { cwd, repoRoot });
+    if (!script) {
+      console.error(`Unknown demo: ${tourName}. Run \`construct demo list\` to see available scripts.`);
+      process.exit(1);
+    }
+    // A non-TTY stdout (pipe, file, CI) advances on its own even without --skip-input.
+    const skipInput = options.skipInput || !process.stdout.isTTY;
+    const result = await renderTour({
+      script,
+      output: process.stdout,
+      input: process.stdin,
+      env: process.env,
+      accessible: options.accessible,
+      skipInput,
+    });
     if (!result.ok) {
       console.error(result.message);
-      process.exit(result.missing?.length ? 2 : 1);
+      process.exit(1);
     }
-    console.log(result.message);
-    for (const v of result.videos || []) console.log(`  ${v}`);
     return;
   }
 
+  const demoName = options.command === 'record' ? options.name : options.name;
+  if (!demoName) {
+    printHelp();
+    process.exit(1);
+  }
+
   const preferPlaywright = options.surface === 'playwright'
     || (options.command === 'record' && loadDemoRecording(demoName, { cwd, repoRoot })?.engine === 'playwright');
   const useTape = options.surface === 'tape'
-    || (options.command === 'record' && !preferPlaywright && options.surface !== 'dashboard');
+    || (options.command === 'record' && !preferPlaywright);
   if (useTape || (options.command === 'record' && preferPlaywright)) {
     const result = runDemoRecord(demoName, {
       cwd,
@@ -669,11 +691,7 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
     format: options.format,
     out: options.out,
     sourceOnly: options.sourceOnly,
-    model: options.model,
-    plain: options.plain,
     accessible: options.accessible,
-    web: options.web,
-    free: options.free,
   });
 
   if (!result.ok) {
@@ -684,9 +702,6 @@ export async function runDemoCli(argv = [], { cwd = process.cwd(), repoRoot } =
   if (result.notices?.length) {
     for (const n of result.notices) console.error(`note: ${n}`);
   }
-  if (result.surface === 'chat' || result.surface === 'web') {
-    return;
-  }
   if (result.artifactPath) {
     console.log(`Demo (${demoName}) [${result.surface}] recorded to:`);
     console.log(`  ${result.artifactPath}`);

package/lib/diagram-export.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const ICON_DIR = path.join(REPO_ROOT, 'templates', 'distribution', 'icons');
+const MERMAID_PPTR_CONFIG = path.join(REPO_ROOT, 'templates', 'distribution', 'mermaid-puppeteer.json');
 
 // Monochrome diagram palette, mirroring the ink ramp in construct-brand.typ so
 // embedded diagrams and surrounding body share one design language.
@@ -36,9 +37,9 @@ export const DISTRIBUTION_D2_SCALE = '0.72';
 export const DISTRIBUTION_D2_SKETCH = '1';
 export const DISTRIBUTION_D2_FONT_SIZE = '14';
 export const DISTRIBUTION_MERMAID_MIME = 'image/png';
-export const DISTRIBUTION_MERMAID_WIDTH = '480';
-export const DISTRIBUTION_MERMAID_SCALE = '1';
-export const DISTRIBUTION_FIGURE_MAX_WIDTH = '58%';
+export const DISTRIBUTION_MERMAID_WIDTH = '2400';
+export const DISTRIBUTION_MERMAID_SCALE = '2';
+export const DISTRIBUTION_FIGURE_MAX_WIDTH = '92%';
 
 // Handwritten font for Mermaid labels so its hand-drawn look matches D2 sketch
 // mode. Caveat ships bundled (templates/distribution/fonts/handwritten) and is
@@ -51,6 +52,9 @@ const MERMAID_INIT = `%%{init: {
   'theme': 'base',
   'look': 'handDrawn',
   'fontFamily': '${MERMAID_FONT}',
+  'flowchart': {
+    'htmlLabels': false
+  },
   'themeVariables': {
     'fontFamily': '${MERMAID_FONT}',
     'fontSize': '19px',
@@ -86,17 +90,8 @@ const MERMAID_INIT = `%%{init: {
   }
 }}%%`;
 
-const CHROME_CANDIDATES = [
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-];
-
-export function resolvePuppeteerExecutable(env = process.env) {
-  if (env.PUPPETEER_EXECUTABLE_PATH) return env.PUPPETEER_EXECUTABLE_PATH;
-  for (const candidate of CHROME_CANDIDATES) {
+function firstExistingPath(paths = []) {
+  for (const candidate of paths) {
     try {
       if (fs.existsSync(candidate)) return candidate;
     } catch {
@@ -106,6 +101,59 @@ export function resolvePuppeteerExecutable(env = process.env) {
   return null;
 }
 
+function playwrightChromeCandidates(home = process.env.HOME || '') {
+  if (!home) return [];
+  const cacheRoot = path.join(home, 'Library', 'Caches', 'ms-playwright');
+  let entries = [];
+  try {
+    entries = fs.readdirSync(cacheRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  entries = entries
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => {
+      const aHeadless = a.name.startsWith('chromium_headless_shell-') ? 0 : 1;
+      const bHeadless = b.name.startsWith('chromium_headless_shell-') ? 0 : 1;
+      if (aHeadless !== bHeadless) return aHeadless - bHeadless;
+      const aVer = Number((a.name.match(/-(\d+)/) || [])[1] || 0);
+      const bVer = Number((b.name.match(/-(\d+)/) || [])[1] || 0);
+      return bVer - aVer;
+    });
+  const candidates = [];
+  for (const entry of entries) {
+    const base = path.join(cacheRoot, entry.name);
+    if (entry.name.startsWith('chromium_headless_shell-')) {
+      candidates.push(path.join(base, 'chrome-headless-shell-mac-arm64', 'chrome-headless-shell'));
+      candidates.push(path.join(base, 'chrome-headless-shell-mac', 'chrome-headless-shell'));
+    }
+    if (entry.name.startsWith('chromium-')) {
+      candidates.push(path.join(base, 'chrome-mac-arm64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
+      candidates.push(path.join(base, 'chrome-mac-arm64', 'chrome'));
+      candidates.push(path.join(base, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
+      candidates.push(path.join(base, 'chrome-mac', 'chrome'));
+    }
+  }
+  return candidates;
+}
+
+function chromeCandidates(env = process.env) {
+  return [
+    ...playwrightChromeCandidates(env.HOME),
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+  ];
+}
+
+export function resolvePuppeteerExecutable(env = process.env) {
+  if (env.PUPPETEER_EXECUTABLE_PATH) return env.PUPPETEER_EXECUTABLE_PATH;
+  return firstExistingPath(chromeCandidates(env));
+}
+
 export function injectMermaidBrandTheme(code) {
   const body = String(code || '').trim();
   if (!body) return body;
@@ -170,6 +218,7 @@ export function buildDistributionDiagramEnv(baseEnv = process.env) {
     CONSTRUCT_MERMAID_WIDTH: DISTRIBUTION_MERMAID_WIDTH,
     CONSTRUCT_MERMAID_SCALE: DISTRIBUTION_MERMAID_SCALE,
   };
+  if (fs.existsSync(MERMAID_PPTR_CONFIG)) env.CONSTRUCT_MERMAID_PPTR_CONFIG = MERMAID_PPTR_CONFIG;
   const chrome = resolvePuppeteerExecutable(baseEnv);
   if (chrome) env.PUPPETEER_EXECUTABLE_PATH = chrome;
   return env;

package/lib/doctor/source-checkout.mjs

@@ -2,8 +2,8 @@
  * lib/doctor/source-checkout.mjs — distinguish Construct source tree vs npm install.
  *
  * `isConstructPackageRepo` is true for both checkouts and consumer installs.
- * Source-only doctor checks (dashboard static export, certification role cards)
- * should run only when this returns true.
+ * Source-only doctor checks (certification role cards) should run only when this
+ * returns true.
  */
 
 import fs from 'node:fs';
@@ -11,6 +11,5 @@ import path from 'node:path';
 
 export function isConstructSourceCheckout(rootDir) {
   const root = path.resolve(rootDir);
-  return fs.existsSync(path.join(root, 'apps', 'dashboard'))
-    || fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
+  return fs.existsSync(path.join(root, 'tests', 'certification', 'specialists'));
 }

package/lib/doctor/watchers/consistency.mjs

@@ -7,11 +7,11 @@
  *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
  *      dispatch resolves to an imported function, and every exported tool
  *      function in lib/mcp/tools/*.mjs is wired into the dispatch.
- *   3. Roles ↔ registry: every persona key in specialists/role-manifests.json
- *      resolves to a persona or agent name in specialists/registry.json.
+ *   3. Roles ↔ registry: every persona key in specialists/org
+ *      resolves to a persona or agent name in specialists/org.
  *   4. Persona promptFiles: every registry.personas[].promptFile and
  *      registry.agents[].promptFile exists on disk.
- *   5. Contracts ↔ schemas: specialists/contracts.json passes validateContractsFile
+ *   5. Contracts ↔ schemas: specialists/org passes validateContractsFile
  *      (cross-file refs, producer/consumer names, schema paths).
  *
  * Each violation produces an audit record. Blocking severity escalates to a
@@ -20,6 +20,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { loadRegistry } from '../../registry/loader.mjs';
 import { join, dirname, resolve } from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -89,6 +90,10 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   const hosts = checkHostSurfaces({ repoRoot });
   collect(hosts, findings, passed, 'host-surfaces');
 
+  const { runCredentialParityChecks } = await import('./credential-parity.mjs');
+  const credentials = await runCredentialParityChecks({ rootDir: repoRoot });
+  collect(credentials, findings, passed, 'credential-parity');
+
   return { findings, passed };
 }
 
@@ -219,22 +224,75 @@ function camelToSnake(s) {
   return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
 }
 
+function readRegistrySnapshot(repoRoot) {
+  const registryPath = join(repoRoot, 'specialists', 'org');
+  if (!existsSync(registryPath)) return null;
+  const stat = statSync(registryPath);
+  if (stat.isDirectory()) return loadRegistry({ rootDir: repoRoot });
+  return JSON.parse(readFileSync(registryPath, 'utf8'));
+}
+
+function personaKeysFromRegistry(registry) {
+  const keys = new Set();
+
+  for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
+    if (specId) keys.add(specId.replace(/^cx-/, ''));
+    if (spec?.name) keys.add(String(spec.name).replace(/^cx-/, ''));
+  }
+
+  if (Array.isArray(registry?.specialists)) {
+    for (const spec of registry.specialists) {
+      if (spec?.id) keys.add(String(spec.id).replace(/^cx-/, ''));
+      if (spec?.name) keys.add(String(spec.name).replace(/^cx-/, ''));
+    }
+  }
+
+  if (registry?.orchestrator?.id) keys.add(String(registry.orchestrator.id).replace(/^cx-/, ''));
+  if (registry?.orchestrator?.name) keys.add(String(registry.orchestrator.name).replace(/^cx-/, ''));
+
+  return [...keys].sort();
+}
+
+function personaOwnersFromRegistry(registry) {
+  const owners = new Map();
+
+  function addOwner(rawId, owner) {
+    if (!rawId) return;
+    const personaId = String(rawId).replace(/^cx-/, '');
+    if (!owners.has(personaId)) owners.set(personaId, new Set());
+    owners.get(personaId).add(owner);
+  }
+
+  for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
+    addOwner(specId, `specialist:${specId}`);
+    addOwner(spec?.name, `specialist:${specId}:name`);
+  }
+
+  if (Array.isArray(registry?.specialists)) {
+    for (const spec of registry.specialists) {
+      const owner = `specialist:${spec?.id || spec?.name || 'unknown'}`;
+      addOwner(spec?.id, owner);
+      addOwner(spec?.name, `${owner}:name`);
+    }
+  }
+
+  addOwner(registry?.orchestrator?.id, 'orchestrator:id');
+  addOwner(registry?.orchestrator?.name, 'orchestrator:name');
+  return owners;
+}
+
 // ── Check 3: roles ↔ registry ──────────────────────────────────────────────
 
 function checkRolesDrift({ repoRoot }) {
   const violations = [];
-  const manifestsPath = join(repoRoot, 'specialists', 'role-manifests.json');
-  const registryPath = join(repoRoot, 'specialists', 'registry.json');
-
-  if (!existsSync(manifestsPath) || !existsSync(registryPath)) {
-    return { summary: 'role manifests or registry missing', violations: [] };
+  if (!existsSync(join(repoRoot, 'specialists', 'org'))) {
+    return { summary: 'registry missing', violations: [] };
   }
 
-  const manifests = JSON.parse(readFileSync(manifestsPath, 'utf8'));
-  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  const registry = readRegistrySnapshot(repoRoot);
 
   const known = new Set();
-  for (const s of registry.specialists || []) {
+  for (const s of Object.values(registry.specialists || {})) {
     if (s?.name) { known.add(s.name); known.add(`cx-${s.name}`); }
   }
   if (registry.orchestrator?.name) {
@@ -242,35 +300,43 @@ function checkRolesDrift({ repoRoot }) {
     known.add(`cx-${registry.orchestrator.name}`);
   }
 
-  const personaKeys = Object.keys(manifests.personas || manifests || {});
+  const personaKeys = personaKeysFromRegistry(registry);
+  const personaOwners = personaOwnersFromRegistry(registry);
   for (const key of personaKeys) {
-    if (key === 'version' || key === 'description' || key === 'schemaVersion') continue;
     if (!known.has(key) && !known.has(`cx-${key}`)) {
       violations.push({
         category: 'roles-drift',
         severity: 'warning',
         target: key,
-        summary: `role-manifests persona '${key}' does not resolve to a registry persona/agent`,
+        summary: `role manifest '${key}' does not resolve to a registry persona/agent`,
       });
     }
   }
 
-  return { summary: `roles: ${personaKeys.length} manifest keys, ${violations.length} drift`, violations };
+  for (const [personaId, owners] of personaOwners.entries()) {
+    if (owners.size <= 1) continue;
+    violations.push({
+      category: 'roles-drift',
+      severity: 'warning',
+      target: personaId,
+      summary: `role manifest '${personaId}' is ambiguous after normalization: ${[...owners].join(', ')}`,
+    });
+  }
+
+  return { summary: `roles: ${personaKeys.length} personas, ${violations.length} drift`, violations };
 }
 
 // ── Check 4: persona promptFile existence ──────────────────────────────────
 
 function checkPersonaPrompts({ repoRoot }) {
   const violations = [];
-  const registryPath = join(repoRoot, 'specialists', 'registry.json');
-  if (!existsSync(registryPath)) return { summary: 'registry missing', violations: [] };
-
-  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  const registry = readRegistrySnapshot(repoRoot);
+  if (!registry) return { summary: 'registry missing', violations: [] };
   let checked = 0;
 
   for (const list of [
     registry.orchestrator ? [registry.orchestrator] : [],
-    registry.specialists || [],
+    Object.values(registry.specialists || {}),
   ]) {
     for (const entry of list) {
       const ref = entry?.promptFile;
@@ -297,7 +363,9 @@ async function checkContractsDrift({ repoRoot }) {
   const violations = [];
   try {
     const { validateContractsFile } = await import('../../contracts/validate.mjs');
-    const result = validateContractsFile({ repoRoot });
+    const legacyContractsPath = join(repoRoot, 'specialists', 'contracts.json');
+    const opts = existsSync(legacyContractsPath) ? { contractsPath: legacyContractsPath, repoRoot } : { repoRoot };
+    const result = validateContractsFile(opts);
     if (!result.ok) {
       for (const err of result.errors) {
         violations.push({
@@ -327,7 +395,7 @@ function getVSCodeSettingsDir(homeDir) {
   return join(appData, 'Code', 'User');
 }
 
-function checkHostSurfaces({ repoRoot }) {
+function checkHostSurfaces({ repoRoot: _repoRoot }) {
   const violations = [];
   const homeDir = os.homedir();
   const surfaces = [