@geraldmaron/construct 1.0.7 → 1.0.8

package/lib/telemetry/otel-tracer.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/telemetry/otel-tracer.mjs — OTel API tracer factory with graceful no-op fallback.
+ *
+ * When @opentelemetry/api is installed and an SDK is configured, returns a real
+ * TracerProvider-backed tracer.  When the SDK is absent (default solo install),
+ * returns a no-op tracer so call sites compile and run without change.
+ *
+ * GenAI attribute constants follow the stable OTel GenAI semantic conventions
+ * (gen_ai_latest_experimental opt-in, May 2026).  Use GenAiAttrs.* at every
+ * LLM and embedding call site.
+ *
+ * W3C trace context propagation: inject() / extract() use the standard
+ * W3CTraceContextPropagator.  MCP callers inject into params._meta;
+ * MCP handlers extract from params._meta to create child spans.
+ *
+ * Environment variables:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT   — enables real SDK + OTLP HTTP export
+ *   OTEL_SERVICE_NAME              — overrides default 'construct'
+ *   OTEL_SEMCONV_STABILITY_OPT_IN — 'gen_ai_latest_experimental' (default)
+ *
+ * Disable with CONSTRUCT_OTEL=off.
+ */
+
+// GenAI semantic convention attribute names (stable + experimental opt-in).
+export const GenAiAttrs = {
+  SYSTEM:                'gen_ai.system',
+  OPERATION_NAME:        'gen_ai.operation.name',
+  REQUEST_MODEL:         'gen_ai.request.model',
+  RESPONSE_MODEL:        'gen_ai.response.model',
+  USAGE_INPUT_TOKENS:    'gen_ai.usage.input_tokens',
+  USAGE_OUTPUT_TOKENS:   'gen_ai.usage.output_tokens',
+  RESPONSE_FINISH_REASONS: 'gen_ai.response.finish_reasons',
+  TOOL_NAME:             'gen_ai.tool.name',
+  TOOL_CALL_ID:          'gen_ai.tool.call.id',
+
+  // MCP-specific (SEP-414 / OTel MCP semconv)
+  MCP_METHOD:            'mcp.method.name',
+  MCP_TRANSPORT:         'mcp.transport',
+};
+
+// W3C propagation header names used in MCP params._meta.
+export const TRACEPARENT_KEY = 'traceparent';
+export const TRACESTATE_KEY  = 'tracestate';
+
+// Singleton holder — module-level so `getTracer` always returns the same instance.
+let _tracer = null;
+let _propagator = null;
+let _sdkAvailable = null;
+
+async function _tryLoadSdk() {
+  if (_sdkAvailable !== null) return _sdkAvailable;
+  try {
+    const api = await import('@opentelemetry/api');
+    _tracer = api.trace.getTracer(
+      process.env.OTEL_SERVICE_NAME || 'construct',
+      process.env.npm_package_version || '0.0.0',
+    );
+    _propagator = api.propagation;
+    _sdkAvailable = true;
+  } catch {
+    _sdkAvailable = false;
+  }
+  return _sdkAvailable;
+}
+
+// Synchronous no-op span — safe to call .setAttribute, .setStatus, .end, etc.
+const _noopSpan = {
+  setAttribute: () => _noopSpan,
+  setAttributes: () => _noopSpan,
+  setStatus: () => _noopSpan,
+  addEvent: () => _noopSpan,
+  recordException: () => _noopSpan,
+  end: () => {},
+  isRecording: () => false,
+  spanContext: () => ({ traceId: '0'.repeat(32), spanId: '0'.repeat(16), traceFlags: 0 }),
+};
+
+const _noopTracer = {
+  startSpan: () => _noopSpan,
+  startActiveSpan: (_name, optsFnOrFn, ctxOrFn, fn) => {
+    const callback = fn || ctxOrFn || optsFnOrFn;
+    if (typeof callback === 'function') return callback(_noopSpan);
+  },
+};
+
+const _noopPropagator = {
+  inject: () => {},
+  extract: (_ctx) => _ctx,
+  fields: () => [],
+};
+
+/**
+ * Return the active OTel tracer (real or no-op).  Call sites import this once.
+ * If CONSTRUCT_OTEL=off or SDK not installed, always returns the no-op tracer.
+ */
+export async function getTracer() {
+  if (process.env.CONSTRUCT_OTEL === 'off') return _noopTracer;
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return _noopTracer;
+  await _tryLoadSdk();
+  return _tracer || _noopTracer;
+}
+
+/** Synchronous version — returns no-op immediately if SDK not yet loaded. */
+export function getTracerSync() {
+  return _tracer || _noopTracer;
+}
+
+/** Return the propagator for W3C trace context injection/extraction. */
+export async function getPropagator() {
+  if (process.env.CONSTRUCT_OTEL === 'off') return _noopPropagator;
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return _noopPropagator;
+  await _tryLoadSdk();
+  return _propagator || _noopPropagator;
+}
+
+/**
+ * Inject W3C trace context into a metadata dict (used for MCP params._meta).
+ * Returns the same dict mutated in place.
+ */
+export async function injectTraceContext(meta = {}) {
+  const propagator = await getPropagator();
+  propagator.inject({}, meta, { set: (carrier, key, val) => { carrier[key] = val; } });
+  return meta;
+}
+
+/**
+ * Extract W3C trace context from a metadata dict (used in MCP handlers).
+ * Returns an OTel Context object, or null when SDK is absent.
+ */
+export async function extractTraceContext(meta = {}) {
+  if (_sdkAvailable === false) return null;
+  const propagator = await getPropagator();
+  let ctx = null;
+  try {
+    const api = await import('@opentelemetry/api');
+    ctx = propagator.extract(api.ROOT_CONTEXT, meta, {
+      get: (carrier, key) => carrier[key],
+      keys: (carrier) => Object.keys(carrier),
+    });
+  } catch { /* SDK not available */ }
+  return ctx;
+}
+
+/**
+ * Convenience wrapper: start a gen_ai.client span, run fn(span), end the span.
+ * Attributes passed at start; fn receives the span for dynamic attrs.
+ *
+ * @param {string} operationName  e.g. 'chat', 'embeddings'
+ * @param {object} attrs          Initial GenAiAttrs.*
+ * @param {function} fn           (span) => result — may be async
+ * @param {object|null} [parentCtx] OTel Context from extractTraceContext (MCP handlers)
+ */
+export async function withGenAiSpan(operationName, attrs, fn, parentCtx = null) {
+  const tracer = await getTracer();
+  const spanName = `gen_ai ${operationName}`;
+
+  const startOpts = {
+    kind: 1 /* SpanKind.CLIENT */,
+    attributes: {
+      [GenAiAttrs.OPERATION_NAME]: operationName,
+      ...attrs,
+    },
+  };
+  if (parentCtx) startOpts.parent = parentCtx;
+
+  let span = _noopSpan;
+  try {
+    span = tracer.startSpan ? tracer.startSpan(spanName, startOpts) : _noopSpan;
+  } catch { /* no-op path */ }
+
+  const t0 = Date.now();
+  try {
+    const result = await fn(span);
+    span.setAttribute('construct.duration_ms', Date.now() - t0);
+    span.setStatus({ code: 1 /* OK */ });
+    return result;
+  } catch (err) {
+    span.setStatus({ code: 2 /* ERROR */, message: err?.message });
+    span.recordException(err);
+    throw err;
+  } finally {
+    span.end();
+  }
+}

package/lib/telemetry/skill-calls.mjs

@@ -1,15 +1,17 @@
 /**
  * lib/telemetry/skill-calls.mjs — measure which skill files actually get loaded.
  *
- * Appends one JSON line per skill load to ~/.cx/skill-calls.jsonl so a future
- * `construct skills:audit` can answer two questions: which skills have no
- * load events in a 30-day window (pruning candidates), and which skills
- * receive load events from many sources (hot paths). Without this signal
- * the 131-file skills tree grows without a pruning gate.
+ * Appends one JSON line per skill load to ~/.cx/skill-calls.jsonl so
+ * `construct skills usage/orphans/hot/correlate-quality` can answer:
+ * which skills have no load events in a 30-day window (pruning candidates),
+ * which skills are loaded from many agents (hot paths), and which skills
+ * correlate with high-quality sessions.
  *
- * Disable with `CONSTRUCT_SKILL_TELEMETRY=off` for users who don't want the
- * append-only log. Errors here are non-fatal — telemetry must never break the
- * skill load it is observing.
+ * Extended payload (Workstream H): latencyMs, agentId, sessionId, tokensReturned
+ * are all optional and backward-compatible with earlier log files.
+ *
+ * Disable with `CONSTRUCT_SKILL_TELEMETRY=off`.
+ * Errors here are non-fatal — telemetry must never break the skill load.
  */
 
 import fs from 'node:fs';
@@ -40,6 +42,10 @@ export function logSkillCall(event, opts = {}) {
     skillId: event.skillId,
     source: event.source,
     ...(event.callerContext ? { callerContext: event.callerContext } : {}),
+    ...(event.latencyMs != null ? { latencyMs: event.latencyMs } : {}),
+    ...(event.agentId ? { agentId: event.agentId } : {}),
+    ...(event.sessionId ? { sessionId: event.sessionId } : {}),
+    ...(event.tokensReturned != null ? { tokensReturned: event.tokensReturned } : {}),
   };
 
   try {
@@ -53,26 +59,81 @@ export function logSkillCall(event, opts = {}) {
 
 /**
  * Read every event from a skill-calls log and roll it up into per-skill stats:
- * load count, distinct sources, most-recent timestamp.
+ * load count, distinct sources, most-recent timestamp, latency percentiles,
+ * distinct agents, distinct sessions.
  */
-export function summarizeSkillCalls({ logPath = DEFAULT_LOG_PATH } = {}) {
+export function summarizeSkillCalls({ logPath = DEFAULT_LOG_PATH, since, agentId: filterAgent, source: filterSource } = {}) {
   if (!fs.existsSync(logPath)) return { totalEvents: 0, skills: {} };
   const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean);
+  const sinceTs = since ? _parseSince(since) : null;
   const skills = {};
   for (const line of lines) {
     let entry;
     try { entry = JSON.parse(line); } catch { continue; }
     if (!entry?.skillId) continue;
-    const slot = skills[entry.skillId] ||= { calls: 0, sources: new Set(), lastCalledAt: null };
+    if (sinceTs && entry.ts && entry.ts < sinceTs) continue;
+    if (filterAgent && entry.agentId !== filterAgent) continue;
+    if (filterSource && entry.source !== filterSource) continue;
+    const slot = skills[entry.skillId] ||= {
+      calls: 0,
+      sources: new Set(),
+      agents: new Set(),
+      sessions: new Set(),
+      latencies: [],
+      lastCalledAt: null,
+    };
     slot.calls += 1;
     if (entry.source) slot.sources.add(entry.source);
+    if (entry.agentId) slot.agents.add(entry.agentId);
+    if (entry.sessionId) slot.sessions.add(entry.sessionId);
+    if (entry.latencyMs != null) slot.latencies.push(entry.latencyMs);
     if (entry.ts && (!slot.lastCalledAt || entry.ts > slot.lastCalledAt)) {
       slot.lastCalledAt = entry.ts;
     }
   }
   const result = {};
   for (const [id, slot] of Object.entries(skills)) {
-    result[id] = { calls: slot.calls, sources: [...slot.sources].sort(), lastCalledAt: slot.lastCalledAt };
+    result[id] = {
+      calls: slot.calls,
+      sources: [...slot.sources].sort(),
+      agents: [...slot.agents].sort(),
+      sessions: slot.sessions.size,
+      lastCalledAt: slot.lastCalledAt,
+      ...(slot.latencies.length ? _latencyStats(slot.latencies) : {}),
+    };
   }
   return { totalEvents: lines.length, skills: result };
 }
+
+/**
+ * Return skills that have zero load events in the given window — pruning candidates.
+ */
+export function findOrphanSkills({ logPath = DEFAULT_LOG_PATH, since = '30d', allSkillIds = [] } = {}) {
+  const { skills } = summarizeSkillCalls({ logPath, since });
+  const active = new Set(Object.keys(skills));
+  return allSkillIds.filter(id => !active.has(id));
+}
+
+/**
+ * Return the top-K hottest skills by call count in the window.
+ */
+export function hotSkills({ logPath = DEFAULT_LOG_PATH, since = '30d', limit = 20 } = {}) {
+  const { skills } = summarizeSkillCalls({ logPath, since });
+  return Object.entries(skills)
+    .sort((a, b) => b[1].calls - a[1].calls)
+    .slice(0, limit)
+    .map(([id, stats]) => ({ skillId: id, ...stats }));
+}
+
+function _parseSince(since) {
+  const m = String(since).match(/^(\d+)(d|h|m)$/);
+  if (!m) return null;
+  const ms = parseInt(m[1], 10) * ({ d: 86400000, h: 3600000, m: 60000 }[m[2]]);
+  return new Date(Date.now() - ms).toISOString();
+}
+
+function _latencyStats(arr) {
+  const sorted = [...arr].sort((a, b) => a - b);
+  const p = (pct) => sorted[Math.floor((pct / 100) * (sorted.length - 1))];
+  return { p50LatencyMs: p(50), p95LatencyMs: p(95) };
+}

package/lib/uninstall/uninstall.mjs

@@ -400,7 +400,7 @@ function unmergeSettings(filePath) {
 
 function constructMcpKeys() {
   try {
-    const registry = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'agents', 'registry.json'), 'utf8'));
+    const registry = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'specialists', 'registry.json'), 'utf8'));
     return Object.keys(registry.mcpServers || {});
   } catch { return []; }
 }

package/lib/update.mjs

@@ -30,7 +30,7 @@ export function isConstructSourceRoot(dir) {
   return pkg.name === PACKAGE_NAME
     && pkg.bin?.construct === 'bin/construct'
     && fs.existsSync(path.join(dir, 'bin', 'construct'))
-    && fs.existsSync(path.join(dir, 'scripts', 'sync-agents.mjs'))
+    && fs.existsSync(path.join(dir, 'scripts', 'sync-specialists.mjs'))
     && fs.existsSync(path.join(dir, 'lib', 'cli-commands.mjs'));
 }
 

package/lib/validator.mjs

@@ -59,18 +59,18 @@ export function validateRegistry(reg, options = {}) {
   if (!reg.system) errors.push('registry: system is missing');
   if (!reg.prefix) errors.push('registry: prefix is missing');
 
-  if (!Array.isArray(reg.agents) || reg.agents.length === 0) {
-    errors.push('registry: agents must be a non-empty array');
+  if (!Array.isArray(reg.specialists) || reg.specialists.length === 0) {
+    errors.push('registry: specialists must be a non-empty array');
   }
-  if (!Array.isArray(reg.personas) || reg.personas.length === 0) {
-    errors.push('registry: personas must be a non-empty array');
+  if (!reg.orchestrator || typeof reg.orchestrator !== 'object') {
+    errors.push('registry: orchestrator must be a non-empty object');
   }
 
-  const agents = Array.isArray(reg.agents) ? reg.agents : [];
-  const personas = Array.isArray(reg.personas) ? reg.personas : [];
+  const specialists = Array.isArray(reg.specialists) ? reg.specialists : [];
+  const orchestrator = reg.orchestrator && typeof reg.orchestrator === 'object' ? reg.orchestrator : null;
 
   const allIds = new Set();
-  const agentNames = new Set(agents.map((agent) => agent?.name).filter(Boolean));
+  const specialistNames = new Set(specialists.map((s) => s?.name).filter(Boolean));
 
   function validateIdentity(entry, kind) {
     const n = entry.name;
@@ -78,7 +78,7 @@ export function validateRegistry(reg, options = {}) {
       errors.push(`${kind}: name must be a non-empty string`);
       return '(unnamed)';
     }
-    if (allIds.has(n)) errors.push(`${n}: duplicate id across agents/personas`);
+    if (allIds.has(n)) errors.push(`${n}: duplicate id across specialists/orchestrator`);
     allIds.add(n);
     if (!/^[a-z][a-z0-9-]*$/.test(n)) {
       errors.push(`${n}: id must be lowercase kebab-case`);
@@ -86,99 +86,99 @@ export function validateRegistry(reg, options = {}) {
     return n;
   }
 
-  for (const agent of agents) {
-    const label = validateIdentity(agent, 'agent');
+  for (const specialist of specialists) {
+    const label = validateIdentity(specialist, 'specialist');
 
-    if (!agent.description || typeof agent.description !== 'string') {
+    if (!specialist.description || typeof specialist.description !== 'string') {
       errors.push(`${label}: description must be a non-empty string`);
-    } else if (agent.description.length > DESCRIPTION_MAX_CHARS) {
-      errors.push(`${label}: description exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${agent.description.length})`);
+    } else if (specialist.description.length > DESCRIPTION_MAX_CHARS) {
+      errors.push(`${label}: description exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${specialist.description.length})`);
     }
-    if (agent.prompt !== undefined && typeof agent.prompt !== 'string') {
+    if (specialist.prompt !== undefined && typeof specialist.prompt !== 'string') {
       errors.push(`${label}: prompt must be a string when present`);
     }
-    if (agent.promptFile !== undefined && typeof agent.promptFile !== 'string') {
+    if (specialist.promptFile !== undefined && typeof specialist.promptFile !== 'string') {
       errors.push(`${label}: promptFile must be a string when present`);
     }
-    if (!agent.prompt && !agent.promptFile) {
+    if (!specialist.prompt && !specialist.promptFile) {
       errors.push(`${label}: must define prompt or promptFile`);
-    } else if (agent.promptFile && !existsSync(join(rootDir, agent.promptFile))) {
-      errors.push(`${label}: promptFile does not exist (${agent.promptFile})`);
+    } else if (specialist.promptFile && !existsSync(join(rootDir, specialist.promptFile))) {
+      errors.push(`${label}: promptFile does not exist (${specialist.promptFile})`);
     }
-    const promptText = typeof agent.prompt === 'string'
-      ? agent.prompt
-      : loadPromptContent(rootDir, agent.promptFile);
+    const promptText = typeof specialist.prompt === 'string'
+      ? specialist.prompt
+      : loadPromptContent(rootDir, specialist.promptFile);
     if (promptText) {
-      const cap = Number.isInteger(agent.wordCapOverride) && agent.wordCapOverride > 0
-        ? agent.wordCapOverride
+      const cap = Number.isInteger(specialist.wordCapOverride) && specialist.wordCapOverride > 0
+        ? specialist.wordCapOverride
         : PROMPT_HARD_CAP_WORDS;
       const words = wordCount(promptText);
       if (words > cap) {
         errors.push(`${label}: prompt is ${words} words, exceeds cap of ${cap} (set wordCapOverride if intentional)`);
       }
     }
-    if (!agent.model && !agent.modelTier) {
+    if (!specialist.model && !specialist.modelTier) {
       errors.push(`${label}: must define model or modelTier`);
     }
-    if (agent.modelTier && !VALID_TIERS.has(agent.modelTier)) {
-      errors.push(`${label}: modelTier must be reasoning|standard|fast, got '${agent.modelTier}'`);
+    if (specialist.modelTier && !VALID_TIERS.has(specialist.modelTier)) {
+      errors.push(`${label}: modelTier must be reasoning|standard|fast, got '${specialist.modelTier}'`);
     }
-    if (agent.model && !hasProviderModelShape(agent.model)) {
+    if (specialist.model && !hasProviderModelShape(specialist.model)) {
       errors.push(`${label}: model must be provider/model-id format`);
     }
-    if (agent.reasoningEffort && !VALID_REASONING_EFFORTS.has(agent.reasoningEffort)) {
+    if (specialist.reasoningEffort && !VALID_REASONING_EFFORTS.has(specialist.reasoningEffort)) {
       errors.push(`${label}: reasoningEffort must be low|medium|high|xhigh`);
     }
-    if ('claudeTools' in agent && (!agent.claudeTools || typeof agent.claudeTools !== 'string')) {
+    if ('claudeTools' in specialist && (!specialist.claudeTools || typeof specialist.claudeTools !== 'string')) {
       errors.push(`${label}: claudeTools must be a non-empty string when present`);
     }
-    validateStringArray(errors, agent.chain, `${label}.chain`, agentNames);
-    validateStringArray(errors, agent.alsoInvokes, `${label}.alsoInvokes`, agentNames);
+    validateStringArray(errors, specialist.chain, `${label}.chain`, specialistNames);
+    validateStringArray(errors, specialist.alsoInvokes, `${label}.alsoInvokes`, specialistNames);
   }
 
-  for (const persona of personas) {
-    const label = validateIdentity(persona, 'persona');
+  if (orchestrator) {
+    const label = validateIdentity(orchestrator, 'orchestrator');
 
-    if (!persona.description || typeof persona.description !== 'string') {
+    if (!orchestrator.description || typeof orchestrator.description !== 'string') {
       errors.push(`${label}: description must be a non-empty string`);
-    } else if (persona.description.length > DESCRIPTION_MAX_CHARS) {
-      errors.push(`${label}: description exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${persona.description.length})`);
+    } else if (orchestrator.description.length > DESCRIPTION_MAX_CHARS) {
+      errors.push(`${label}: description exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${orchestrator.description.length})`);
     }
-    if (persona.displayName && persona.displayName.length > DISPLAY_NAME_MAX_CHARS) {
-      errors.push(`${label}: displayName exceeds ${DISPLAY_NAME_MAX_CHARS} chars (got ${persona.displayName.length})`);
+    if (orchestrator.displayName && orchestrator.displayName.length > DISPLAY_NAME_MAX_CHARS) {
+      errors.push(`${label}: displayName exceeds ${DISPLAY_NAME_MAX_CHARS} chars (got ${orchestrator.displayName.length})`);
     }
-    if (!persona.role || typeof persona.role !== 'string') {
+    if (!orchestrator.role || typeof orchestrator.role !== 'string') {
       errors.push(`${label}: role must be a non-empty string`);
     }
-    if (!persona.promptFile || typeof persona.promptFile !== 'string') {
+    if (!orchestrator.promptFile || typeof orchestrator.promptFile !== 'string') {
       errors.push(`${label}: promptFile must be a non-empty string`);
-    } else if (!existsSync(join(rootDir, persona.promptFile))) {
-      errors.push(`${label}: promptFile does not exist (${persona.promptFile})`);
+    } else if (!existsSync(join(rootDir, orchestrator.promptFile))) {
+      errors.push(`${label}: promptFile does not exist (${orchestrator.promptFile})`);
     }
-    const personaPromptText = loadPromptContent(rootDir, persona.promptFile);
-    if (personaPromptText) {
-      const cap = Number.isInteger(persona.wordCapOverride) && persona.wordCapOverride > 0
-        ? persona.wordCapOverride
+    const oPromptText = loadPromptContent(rootDir, orchestrator.promptFile);
+    if (oPromptText) {
+      const cap = Number.isInteger(orchestrator.wordCapOverride) && orchestrator.wordCapOverride > 0
+        ? orchestrator.wordCapOverride
         : PROMPT_HARD_CAP_WORDS;
-      const words = wordCount(personaPromptText);
+      const words = wordCount(oPromptText);
       if (words > cap) {
         errors.push(`${label}: prompt is ${words} words, exceeds cap of ${cap} (set wordCapOverride if intentional)`);
       }
     }
-    if (!persona.model && !persona.modelTier) {
+    if (!orchestrator.model && !orchestrator.modelTier) {
       errors.push(`${label}: must define model or modelTier`);
     }
-    if (persona.modelTier && !VALID_TIERS.has(persona.modelTier)) {
-      errors.push(`${label}: modelTier must be reasoning|standard|fast, got '${persona.modelTier}'`);
+    if (orchestrator.modelTier && !VALID_TIERS.has(orchestrator.modelTier)) {
+      errors.push(`${label}: modelTier must be reasoning|standard|fast, got '${orchestrator.modelTier}'`);
     }
-    if (persona.model && !hasProviderModelShape(persona.model)) {
+    if (orchestrator.model && !hasProviderModelShape(orchestrator.model)) {
       errors.push(`${label}: model must be provider/model-id format`);
     }
-    if (persona.reasoningEffort && !VALID_REASONING_EFFORTS.has(persona.reasoningEffort)) {
+    if (orchestrator.reasoningEffort && !VALID_REASONING_EFFORTS.has(orchestrator.reasoningEffort)) {
       errors.push(`${label}: reasoningEffort must be low|medium|high|xhigh`);
     }
-    validateStringArray(errors, persona.chain, `${label}.chain`, agentNames);
-    validateStringArray(errors, persona.alsoInvokes, `${label}.alsoInvokes`, agentNames);
+    validateStringArray(errors, orchestrator.chain, `${label}.chain`, specialistNames);
+    validateStringArray(errors, orchestrator.alsoInvokes, `${label}.alsoInvokes`, specialistNames);
   }
 
   if (!reg.models || typeof reg.models !== 'object') {
@@ -210,14 +210,15 @@ export function validateRegistry(reg, options = {}) {
     }
   }
 
-  const summary = `${personas.length} personas, ${agents.length} agents`;
+  const specialistCount = specialists.length;
+  const summary = `1 orchestrator, ${specialistCount} specialists`;
   return { valid: errors.length === 0, errors, summary };
 }
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  const reg = JSON.parse(readFileSync(join(__dirname, '..', 'agents', 'registry.json'), 'utf8'));
+  const reg = JSON.parse(readFileSync(join(__dirname, '..', 'specialists', 'registry.json'), 'utf8'));
   const result = validateRegistry(reg);
   if (result.valid) {
     console.log(`✓ Registry valid (${result.summary})`);