@geraldmaron/construct 1.2.3 → 1.3.1

package/lib/mcp/tools/orchestration-run.mjs

@@ -1,123 +1,161 @@
 /**
- * lib/mcp/tools/orchestration-run.mjs — MCP client for the local orchestration daemon.
+ * lib/mcp/tools/orchestration-run.mjs — MCP entry for Construct orchestration.
  *
- * Executes a real multi-specialist run by driving the daemon's HTTP API
- * (ADR-0022), so MCP hosts with no subagent primitive — VS Code/Copilot, Cursor —
- * reach orchestrated outcomes through a tool they actually expose: the engine
- * owns orchestration; this tool is the thin client. The daemon URL resolves from
- * dashboard state (else the default loopback port) and the bearer token from
- * ~/.construct/config.env. When the daemon is unreachable the tool fails fast
- * with an actionable error rather than silently degrading to a single-persona
- * pass — the absence of an executable path is made loud, not hidden.
+ * Runs a real multi-specialist orchestration so MCP hosts with no subagent
+ * primitive (VS Code/Copilot, Cursor) reach orchestrated outcomes through a tool
+ * they already expose. The engine is the in-process orchestration runtime
+ * (lib/orchestration/runtime.mjs) — solo runs need no daemon, no port, no token
+ * (ADR-0022: the engine owns orchestration; ADR-0041 owned loop). When
+ * CONSTRUCT_ORCHESTRATION_URL points at a remote/team orchestration service the
+ * same call is proxied over HTTP instead, with the bearer token resolved from the
+ * Construct env (CONSTRUCT_ORCHESTRATION_TOKEN / CONSTRUCT_DASHBOARD_TOKEN), not
+ * from the dashboard server.
  */
 
-import { readDashboardState } from '../../service-manager.mjs';
-import { getDashboardToken } from '../../server/auth.mjs';
+import { runOrchestration, startRun, getRun, getRuns } from '../../orchestration/runtime.mjs';
 
 const TERMINAL = ['completed', 'completed-with-failures', 'cancelled', 'error'];
 
-function resolveDaemon(env = process.env) {
-  const state = readDashboardState();
-  const base = (env.CONSTRUCT_ORCHESTRATION_URL || state?.url || `http://${env.BIND_HOST || '127.0.0.1'}:${env.PORT || '4242'}`).replace(/\/$/, '');
-  return { base, token: getDashboardToken(), daemonRunning: Boolean(state) };
+function shapeRun(run) {
+  return {
+    runId: run.runId,
+    status: run.status,
+    executionMode: run.execution?.executionMode,
+    degraded: run.execution?.degraded ?? false,
+    degradationReason: run.execution?.degradationReason ?? null,
+    intent: run.plan?.intent ?? null,
+    track: run.plan?.track ?? null,
+    suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
+    researchExecutionPolicy: run.plan?.researchExecutionPolicy ?? null,
+    specialists: run.plan?.specialists ?? [],
+    tasks: (run.tasks || []).map((t) => ({
+      id: t.id, role: t.role, status: t.status, executor: t.executor,
+      output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null,
+    })),
+  };
+}
+
+function toRequest(args) {
+  return {
+    request: args.request,
+    workflowType: args.workflow_type,
+    requestedStrategy: args.requested_strategy ?? 'auto',
+    host: args.host,
+    hostModel: args.host_model,
+    hostProvider: args.host_provider,
+    fileCount: args.file_count,
+    moduleCount: args.module_count,
+  };
 }
 
-// A reachability failure is the fail-fast signal MCP hosts need: report how to
-// start the engine instead of letting the host fall back to a manual pass.
+// A remote orchestration service is opt-in: only when CONSTRUCT_ORCHESTRATION_URL
+// is set (team / enterprise). The token comes from the Construct env, not from
+// the dashboard server, so the in-process default path carries no dashboard coupling.
+
+function remoteService(env) {
+  const url = env.CONSTRUCT_ORCHESTRATION_URL;
+  if (!url) return null;
+  const token = env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN || null;
+  return { base: url.replace(/\/$/, ''), token };
+}
 
 function unreachable(base, detail) {
   return {
-    error: `Orchestration daemon not reachable at ${base}: ${detail}. Start it with \`construct dashboard\`, then retry. The engine runs orchestration; this host is a thin client (ADR-0022).`,
-    daemon: base,
+    error: `Remote orchestration service not reachable at ${base}: ${detail}. Unset CONSTRUCT_ORCHESTRATION_URL to run in-process, or start the service and retry.`,
+    service: base,
     failFast: true,
   };
 }
 
-export async function orchestrationRun(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
-  const {
-    request,
-    workflow_type,
-    requested_strategy = 'auto',
-    worker_backend,
-    host,
-    host_model,
-    host_provider,
-    file_count,
-    module_count,
-    wait = true,
-    timeout_ms = 120000,
-  } = args;
-
-  if (!request || typeof request !== 'string') return { error: 'Missing "request" string describing the work to orchestrate.' };
-
-  const { base, token } = resolveDaemon(env);
-  const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
-  const body = JSON.stringify({
-    request,
-    workflowType: workflow_type,
-    requestedStrategy: requested_strategy,
-    workerBackend: worker_backend,
-    host,
-    hostModel: host_model,
-    hostProvider: host_provider,
-    fileCount: file_count,
-    moduleCount: module_count,
-  });
+export async function orchestrationRun(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  const { request, worker_backend, wait = true, timeout_ms = 120000 } = args;
+  if (!request || typeof request !== 'string') {
+    return { error: 'Missing "request" string describing the work to orchestrate.' };
+  }
+
+  const reqObj = toRequest(args);
+  const remote = remoteService(env);
+  if (remote) return runViaService(remote, reqObj, { wait, timeout_ms, workerBackend: worker_backend, fetchImpl });
+
+  const opts = { env, cwd, workerBackend: worker_backend, fetchImpl };
+  try {
+    if (!wait) {
+      const planned = await startRun(reqObj, opts);
+      return { runId: planned.runId, status: planned.status, executionMode: planned.execution?.executionMode, poll: 'orchestration_status with run_id' };
+    }
+    return shapeRun(await runOrchestration(reqObj, opts));
+  } catch (err) {
+    return { error: `Orchestration failed: ${err.message}`, failFast: true };
+  }
+}
+
+export async function orchestrationStatus(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  const { run_id, limit = 20 } = args;
+  const remote = remoteService(env);
+  if (remote) return statusViaService(remote, { run_id, limit }, { fetchImpl });
+  try {
+    if (run_id) {
+      const run = await getRun(cwd, run_id, { env });
+      return run || { error: `No run found with id ${run_id}.` };
+    }
+    return await getRuns(cwd, { env, limit });
+  } catch (err) {
+    return { error: `Failed to read orchestration runs: ${err.message}` };
+  }
+}
+
+// Remote (team / enterprise) HTTP path. Reached only when CONSTRUCT_ORCHESTRATION_URL
+// is set; the wire shape matches the standalone orchestration service's
+// /api/orchestration/runs contract (ADR-0022).
 
+async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend, fetchImpl }) {
+  const { base, token } = remote;
+  const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+  const body = JSON.stringify({ ...reqObj, workerBackend });
   let started;
   try {
     const res = await fetchImpl(`${base}/api/orchestration/runs`, { method: 'POST', headers, body });
     if (res.status === 401 || res.status === 403) {
-      return { error: `Daemon rejected the request (HTTP ${res.status}). The dashboard token is missing or wrong — check CONSTRUCT_DASHBOARD_TOKEN in ~/.construct/config.env.`, daemon: base, failFast: true };
+      return { error: `Remote service rejected the request (HTTP ${res.status}). Set CONSTRUCT_ORCHESTRATION_TOKEN (or CONSTRUCT_DASHBOARD_TOKEN).`, service: base, failFast: true };
     }
     const envelope = await res.json();
-    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
     started = envelope.data;
   } catch (err) {
     return unreachable(base, err.message);
   }
 
   if (!wait) {
-    return { runId: started.runId, status: started.status, executionMode: started.execution?.executionMode, daemon: base, poll: 'orchestration_status with run_id' };
+    return { runId: started.runId, status: started.status, executionMode: started.execution?.executionMode, service: base, poll: 'orchestration_status with run_id' };
   }
 
   const deadline = Date.now() + timeout_ms;
   let run = started;
   while (!TERMINAL.includes(run.status)) {
     if (Date.now() > deadline) {
-      return { runId: started.runId, status: run.status, timedOut: true, daemon: base, note: 'Run is still executing; poll it with orchestration_status.' };
+      return { runId: started.runId, status: run.status, timedOut: true, service: base, note: 'Run is still executing; poll it with orchestration_status.' };
     }
     await new Promise((r) => setTimeout(r, 250));
     try {
       const res = await fetchImpl(`${base}/api/orchestration/runs/${encodeURIComponent(started.runId)}`, { headers });
       const envelope = await res.json();
-      if (!res.ok) return { error: `Daemon error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, daemon: base };
+      if (!res.ok) return { error: `Remote service error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, service: base };
       run = envelope.data;
     } catch (err) {
-      return { error: `Lost connection to the daemon while polling run ${started.runId}: ${err.message}`, runId: started.runId, daemon: base, failFast: true };
+      return { error: `Lost connection to the remote service while polling run ${started.runId}: ${err.message}`, runId: started.runId, service: base, failFast: true };
     }
   }
-
-  return {
-    runId: run.runId,
-    status: run.status,
-    executionMode: run.execution?.executionMode,
-    degraded: run.execution?.degraded ?? false,
-    degradationReason: run.execution?.degradationReason ?? null,
-    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null })),
-    daemon: base,
-  };
+  return { ...shapeRun(run), service: base };
 }
 
-export async function orchestrationStatus(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
-  const { run_id, limit = 20 } = args;
-  const { base, token } = resolveDaemon(env);
+async function statusViaService(remote, { run_id, limit }, { fetchImpl }) {
+  const { base, token } = remote;
   const headers = token ? { Authorization: `Bearer ${token}` } : {};
   const path = run_id ? `/api/orchestration/runs/${encodeURIComponent(run_id)}` : `/api/orchestration/runs?limit=${encodeURIComponent(limit)}`;
   try {
     const res = await fetchImpl(`${base}${path}`, { headers });
     const envelope = await res.json();
-    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
     return envelope.data;
   } catch (err) {
     return unreachable(base, err.message);

package/lib/mcp/tools/project.mjs

@@ -5,13 +5,14 @@
  * All tools are synchronous except where noted. Requires ROOT_DIR and homedir from the caller.
  */
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { loadRegistry } from '../../registry/loader.mjs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { loadConstructEnv } from '../../env-config.mjs';
 import { inspectContextState } from '../../context-state.mjs';
 import { loadWorkflow, summarizeWorkflow, inspectWorkflowHealth } from '../../workflow-state.mjs';
-import { readCurrentModels, resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../../model-router.mjs';
+import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../../model-router.mjs';
 import { buildPublicHealthSurface } from '../../status.mjs';
 import { doctorRoot } from '../../config/xdg.mjs';
 
@@ -282,7 +283,7 @@ export function projectContext(args, { ROOT_DIR }) {
   const has_context_file = contextInspection.hasFile;
   const workflow = loadWorkflow(cwd);
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
+  const registry = loadRegistry({ rootDir: ROOT_DIR });
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},
@@ -324,7 +325,7 @@ export function workflowStatus(args, { ROOT_DIR }) {
   const workflow = loadWorkflow(cwd);
   const workflowHealth = inspectWorkflowHealth(workflow, { cwd });
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
+  const registry = loadRegistry({ rootDir: ROOT_DIR });
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},

package/lib/mcp/tools/{profile.mjs → scope.mjs}

@@ -1,7 +1,7 @@
 /**
- * lib/mcp/tools/profile.mjs — MCP wrappers for the org-profile + learning surfaces.
+ * lib/mcp/tools/scope.mjs — MCP wrappers for the org-scope + learning surfaces.
  *
- * Bridges PR #67 capabilities (profiles, outcomes, sandboxes, knowledge_add,
+ * Bridges PR #67 capabilities (scopes, outcomes, sandboxes, knowledge_add,
  * learning status) so subagents talking through the construct-mcp server can
  * read the same state the CLI exposes. Operator-only surfaces (optimize_apply,
  * optimize_rollback) remain CLI-only and are not registered here.
@@ -9,7 +9,7 @@
  * Pattern: each export is a thin schema-validated wrapper around the existing
  * lib/* function the CLI already uses. Errors return `{ error: string }` so
  * the MCP dispatcher hands a structured failure back instead of crashing.
- * Destructive operations (profile_archive) require `confirm: true`, matching
+ * Destructive operations (scope_archive) require `confirm: true`, matching
  * the storage_reset / delete_ingested_artifacts pattern in tools/storage.mjs.
  */
 import { resolve } from 'node:path';
@@ -17,17 +17,17 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
-  loadProfile,
-  listProfiles,
-  loadCustomProfile,
-  resolveActiveProfile,
-} from '../../profiles/loader.mjs';
+  loadScope,
+  listScopes,
+  loadCustomScope,
+  resolveActiveScope,
+} from '../../scopes/loader.mjs';
 import {
-  createDraftProfile,
+  createDraftScope,
   listDrafts,
-  archiveProfile,
-  profileHealth,
-} from '../../profiles/lifecycle.mjs';
+  archiveScope,
+  scopeHealth,
+} from '../../scopes/lifecycle.mjs';
 import { recordOutcome } from '../../outcomes/record.mjs';
 import { aggregateOutcomes, readSummary } from '../../outcomes/aggregate.mjs';
 import { addResearchFinding } from '../../knowledge/research-store.mjs';
@@ -38,73 +38,75 @@ function cwdOf(args) {
   return args && args.cwd ? resolve(String(args.cwd)) : process.cwd();
 }
 
-// Read-only: active profile.
+// Read-only: active scope.
 
-export function profileShow(args = {}) {
+export function scopeShow(args = {}) {
   const cwd = cwdOf(args);
-  const profile = resolveActiveProfile(cwd, args.id ? String(args.id) : null);
+  const scope = resolveActiveScope(cwd, args.id ? String(args.id) : null);
   return {
-    id: profile.id,
-    displayName: profile.displayName ?? profile.id,
-    tagline: profile.tagline ?? null,
-    custom: profile.custom === true,
-    roles: Array.isArray(profile.roles) ? profile.roles : [],
-    departments: Array.isArray(profile.departments)
-      ? profile.departments.map((d) => ({ id: d.id, displayName: d.displayName, roleCount: Array.isArray(d.roles) ? d.roles.length : 0 }))
+    id: scope.id,
+    displayName: scope.displayName ?? scope.id,
+    tagline: scope.tagline ?? null,
+    custom: scope.custom === true,
+    roles: Array.isArray(scope.roles) ? scope.roles : [],
+    teams: Array.isArray(scope.teams)
+      ? scope.teams.map((t) => ({ id: t.id, name: t.name, roleCount: Array.isArray(t.roles) ? t.roles.length : 0 }))
       : [],
+    experimental: scope.experimental === true,
     intake: {
-      types: profile.intake?.types ?? [],
-      stages: profile.intake?.stages ?? [],
+      types: scope.intake?.types ?? [],
+      stages: scope.intake?.stages ?? [],
     },
-    docTemplates: profile.docTemplates ?? [],
-    hooks: profile.hooks ?? null,
-    rebrand: profile.rebrand ?? null,
+    docTemplates: scope.docTemplates ?? [],
+    hooks: scope.hooks ?? null,
+    rebrand: scope.rebrand ?? null,
   };
 }
 
 // Read-only: catalog summary.
 
-export function profileList() {
+export function scopeList() {
   return {
-    profiles: listProfiles().map((id) => {
-      const p = loadProfile(id);
+    scopes: listScopes().map((id) => {
+      const p = loadScope(id);
       return p
         ? {
             id: p.id,
             displayName: p.displayName ?? p.id,
             tagline: p.tagline ?? null,
             roleCount: Array.isArray(p.roles) ? p.roles.length : 0,
-            departmentCount: Array.isArray(p.departments) ? p.departments.length : 0,
+            teamCount: Array.isArray(p.teams) ? p.teams.length : 0,
+            experimental: p.experimental === true,
           }
         : { id, error: 'failed to parse' };
     }),
   };
 }
 
-// Read-only: drafts + custom profile under .cx/.
+// Read-only: drafts + custom scope under .cx/.
 
-export function profileDrafts(args = {}) {
+export function scopeDrafts(args = {}) {
   const cwd = cwdOf(args);
   const drafts = listDrafts(cwd).map((d) => ({
     id: d.id,
     dir: d.dir,
-    hasProfile: d.hasProfile,
+    hasScope: d.hasScope,
     hasBrief: d.hasBrief,
   }));
-  const custom = loadCustomProfile(cwd);
+  const custom = loadCustomScope(cwd);
   return {
     drafts,
     custom: custom ? { id: custom.id, displayName: custom.displayName ?? custom.id } : null,
   };
 }
 
-// Read-only: per-profile health rollup.
+// Read-only: per-scope health rollup.
 
-export function profileHealthTool(args = {}) {
+export function scopeHealthTool(args = {}) {
   const cwd = cwdOf(args);
-  const id = args.id ? String(args.id) : resolveActiveProfile(cwd).id;
+  const id = args.id ? String(args.id) : resolveActiveScope(cwd).id;
   const windowDays = Number.isFinite(args.window_days) ? Number(args.window_days) : 30;
-  return { id, windowDays, ...profileHealth(cwd, id, { windowDays }) };
+  return { id, windowDays, ...scopeHealth(cwd, id, { windowDays }) };
 }
 
 // Read-only: outcomes rollup. Optional aggregate=true rebuilds _summary.json.
@@ -129,7 +131,7 @@ export function outcomesRecord(args = {}) {
   if (!args.role || typeof args.success !== 'boolean') {
     return { error: 'outcomes_record requires role:string and success:boolean' };
   }
-  const profile = args.profile ? String(args.profile) : resolveActiveProfile(cwd)?.id;
+  const profile = args.profile ? String(args.profile) : resolveActiveScope(cwd)?.id;
   const file = recordOutcome(cwd, {
     role: String(args.role),
     intakeId: args.intake_id ? String(args.intake_id) : null,
@@ -167,16 +169,16 @@ export async function knowledgeAdd(args = {}) {
   }
 }
 
-// Mutating, gated: scaffold a draft profile.
+// Mutating, gated: scaffold a draft scope.
 
-export function profileCreate(args = {}) {
+export function scopeCreate(args = {}) {
   if (args.confirm !== true) {
-    return { error: 'profile_create requires confirm=true to scaffold files' };
+    return { error: 'scope_create requires confirm=true to scaffold files' };
   }
   const cwd = cwdOf(args);
-  if (!args.id) return { error: 'profile_create requires id:string' };
+  if (!args.id) return { error: 'scope_create requires id:string' };
   try {
-    const res = createDraftProfile({
+    const res = createDraftScope({
       cwd,
       id: String(args.id),
       displayName: args.display_name ? String(args.display_name) : undefined,
@@ -196,17 +198,17 @@ export function profileCreate(args = {}) {
   }
 }
 
-// Mutating, gated, destructive: archive a curated profile.
+// Mutating, gated, destructive: archive a curated scope.
 
-export function profileArchive(args = {}) {
+export function scopeArchive(args = {}) {
   if (args.confirm !== true) {
-    return { error: 'profile_archive requires confirm=true (destructive: moves files into archive/profiles/)' };
+    return { error: 'scope_archive requires confirm=true (destructive: moves files into archive/scopes/)' };
   }
   if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
-    return { error: 'profile_archive requires id:string and reason:string (>=8 chars)' };
+    return { error: 'scope_archive requires id:string and reason:string (>=8 chars)' };
   }
   try {
-    return { ok: true, ...archiveProfile({ id: String(args.id), reason: String(args.reason) }) };
+    return { ok: true, ...archiveScope({ id: String(args.id), reason: String(args.reason) }) };
   } catch (err) {
     return { error: err.message ?? String(err) };
   }
@@ -258,11 +260,11 @@ export function learningStatus(args = {}) {
     }
   } catch { /* best effort */ }
 
-  const profile = resolveActiveProfile(cwd);
+  const scope = resolveActiveScope(cwd);
   const outcomes = readSummary(cwd) || { roles: {} };
 
   return {
-    profile: { id: profile.id, displayName: profile.displayName ?? profile.id, custom: profile.custom === true },
+    scope: { id: scope.id, displayName: scope.displayName ?? scope.id, custom: scope.custom === true },
     observations,
     research: { count: researchCount },
     outcomes,

package/lib/mcp/tools/skills.mjs

@@ -19,6 +19,9 @@ import { buildTaskPacketFromIntent } from '../../workflow-state.mjs';
 import { logSkillCall } from '../../telemetry/skill-calls.mjs';
 import { templateMetadata } from '../../artifact-manifest.mjs';
 import { buildSpecialistCatalog } from '../../specialists/roster.mjs';
+import { loadRegistry } from '../../registry/loader.mjs';
+import { listGroupsHierarchical } from '../../registry/assemble.mjs';
+import { suggestSkills } from '../../skills/router.mjs';
 
 export function listSkills({ ROOT_DIR }) {
   const skillsDir = join(ROOT_DIR, 'skills');
@@ -48,9 +51,22 @@ export function listSkills({ ROOT_DIR }) {
 }
 
 export function getSkill(args, { ROOT_DIR }) {
-  const { path: skillPath } = args;
+  const { path: skillPath, specialistId, agentId } = args;
   if (!skillPath) return { error: 'Missing path argument' };
 
+  const strict = process.env.CONSTRUCT_STRICT_SKILLS === '1';
+  const specId = specialistId || agentId;
+  let entitlementWarning = null;
+  if (specId) {
+    const registry = loadRegistry({ rootDir: ROOT_DIR, skipValidation: true });
+    const id = String(specId).startsWith('cx-') ? specId : `cx-${specId}`;
+    const entitled = new Set(registry.specialists?.[id]?.skills || []);
+    if (entitled.size > 0 && !entitled.has(skillPath)) {
+      entitlementWarning = `Skill ${skillPath} is not in ${id} entitlement list`;
+      if (strict) return { error: entitlementWarning };
+    }
+  }
+
   // Primary: flat file form skills/<path>.md
   // Fallback: directory form skills/<path>/SKILL.md (one minor-release grace period)
   const candidates = [
@@ -73,7 +89,7 @@ export function getSkill(args, { ROOT_DIR }) {
     sessionId: args.sessionId,
     tokensReturned: Math.ceil(content.length / 4),
   });
-  return { content };
+  return { content, ...(entitlementWarning ? { warning: entitlementWarning } : {}) };
 }
 
 export function searchSkills(args, { ROOT_DIR }) {
@@ -434,29 +450,30 @@ export async function workerRun(args = {}) {
   return { ...result, ...(evidence ? { evidence } : {}) };
 }
 
-export function listTeams({ ROOT_DIR }) {
-  const teamsPath = join(ROOT_DIR, 'specialists', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'specialists/teams.json not found' };
-  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
+export function suggestSkillsTool(args, { ROOT_DIR, cwd } = {}) {
+  const intent = args?.intent || args?.query || '';
+  return suggestSkills({
+    intent,
+    specialistId: args?.specialistId || args?.agentId,
+    limit: args?.limit || 5,
+    rootDir: ROOT_DIR,
+    cwd: cwd || ROOT_DIR,
+  });
+}
+
+export function listTeams({ ROOT_DIR } = {}) {
+  const registry = loadRegistry({ rootDir: ROOT_DIR, skipValidation: true });
   return {
-    teams: Object.entries(templates).map(([name, t]) => ({
-      name,
-      description: t.description,
-      members: t.members,
-      focus: t.focus,
-      skills: t.skills,
-      promotionGates: t.promotionGates,
-    })),
+    groups: listGroupsHierarchical(registry),
+    teams: Object.entries(registry.teams || {}).map(([id, t]) => ({ id, ...t })),
   };
 }
 
-export function getTeam(args, { ROOT_DIR }) {
-  const { name } = args;
+export function getTeam(args, { ROOT_DIR } = {}) {
+  const name = args?.name || args?.id;
   if (!name) return { error: 'Missing name argument' };
-  const teamsPath = join(ROOT_DIR, 'specialists', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'specialists/teams.json not found' };
-  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
-  const team = templates[name];
-  if (!team) return { error: `Team not found: ${name}`, available: Object.keys(templates) };
-  return { name, ...team };
+  const registry = loadRegistry({ rootDir: ROOT_DIR, skipValidation: true });
+  const team = registry.teams?.[name];
+  if (!team) return { error: `Team not found: ${name}`, available: Object.keys(registry.teams || {}) };
+  return { id: name, ...team };
 }

package/lib/mcp/tools/telemetry.mjs

@@ -6,6 +6,7 @@
  * adapter when configured; local JSONL remains available by default.
  */
 import { join, resolve } from 'node:path';
+import { loadRegistry } from '../../registry/loader.mjs';
 import { homedir } from 'node:os';
 import { readFileSync, existsSync } from 'node:fs';
 import { createTelemetryClient } from '../../telemetry/client.mjs';
@@ -71,7 +72,7 @@ function resolveSessionContext() {
 
 export async function cxTrace(args, { ROOT_DIR }) {
   const ctx = resolveSessionContext();
-  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
+  const registry = loadRegistry({ rootDir: ROOT_DIR });
   const registryModels = registry.models ?? {};
   const currentModels = readCurrentModels(join(ROOT_DIR, '.env'), registryModels, process.env);
   const route = typeof args.input === 'string' ? routeRequest({ request: args.input }) : null;

package/lib/mcp/tools/workflow.mjs

@@ -97,7 +97,7 @@ export function workflowValidate(args) {
 }
 
 /**
- * Validate a producer→consumer handoff against specialists/contracts.json.
+ * Validate a producer→consumer handoff against specialists/org.
  *
  * Args:
  *   producer    — agent or persona name producing the artifact

package/lib/mcp-platform-config.mjs

@@ -14,16 +14,16 @@ export function getOpenCodeMcpId(id) {
   return id;
 }
 
-function resolveTemplateString(value, resolvedValues) {
-  return value.replace(/__([A-Z0-9_]+)__/g, (_, name) => resolvedValues[name] ?? `__${name}__`);
+function resolveTemplateString(value, resolvedValues, fallback = (name) => `__${name}__`) {
+  return value.replace(/__([A-Z0-9_]+)__/g, (_, name) => resolvedValues[name] ?? fallback(name));
 }
 
-function resolveTemplateObject(input, resolvedValues) {
+function resolveTemplateObject(input, resolvedValues, fallback) {
   if (!input || typeof input !== "object" || Array.isArray(input)) return {};
   return Object.fromEntries(
     Object.entries(input).map(([key, value]) => [
       key,
-      typeof value === "string" ? resolveTemplateString(value, resolvedValues) : value,
+      typeof value === "string" ? resolveTemplateString(value, resolvedValues, fallback) : value,
     ]),
   );
 }
@@ -45,7 +45,9 @@ function buildLocalEnvironment(mcpDef, resolvedValues) {
 }
 
 function buildRemoteHeaders(mcpDef, resolvedValues) {
-  return stripUnresolvedValues(resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues));
+  return stripUnresolvedValues(
+    resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues, (name) => `{env:${name}}`),
+  );
 }
 
 function withMemoryDefaults(id, values) {