@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/service-manager.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/service-manager.mjs — start, stop, and describe Construct runtime services.
  *
- * Manages the dashboard process, memory server (cm), and OpenCode. 
+ * Manages the memory server (cm), OpenCode, and other runtime services.
  * startServices() is the single entry point for `construct dev` —
  * spawns whatever is available and returns a result per service.
  */
@@ -23,18 +23,12 @@ import { heartbeatPath } from './oracle/index.mjs';
 import { stateDir } from './config/xdg.mjs';
 import { doctorRoot } from './config/xdg.mjs';
 
-const DASHBOARD_STATE_FILE = 'dashboard.json';
-
 const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 function runtimeStateDir(homeDir = os.homedir()) {
   return path.join(stateDir(homeDir), 'runtime');
 }
 
-function dashboardStatePath(homeDir = os.homedir()) {
-  return path.join(runtimeStateDir(homeDir), DASHBOARD_STATE_FILE);
-}
-
 function readJson(filePath) {
   if (!fs.existsSync(filePath)) return null;
   try {
@@ -149,10 +143,6 @@ async function probeRuntimeHttp(url, {
   }
 }
 
-async function isDashboardRunning(port) {
-  return probeRuntimeHttp(`http://127.0.0.1:${port}/`, { timeoutMs: 1000 });
-}
-
 async function isMemoryRunning(port) {
   const mcpReady = await probeRuntimeHttp(`http://127.0.0.1:${port}/`, {
     method: 'POST',
@@ -187,35 +177,6 @@ function spawnDetached(command, args, homeDir, logFile, options = {}) {
   return { child, logPath };
 }
 
-export function readDashboardState(homeDir = os.homedir()) {
-  const state = readJson(dashboardStatePath(homeDir));
-  if (!state) return null;
-  if (!processExists(state.pid)) return null;
-  return state;
-}
-
-export function clearDashboardState(homeDir = os.homedir()) {
-  const filePath = dashboardStatePath(homeDir);
-  if (fs.existsSync(filePath)) fs.rmSync(filePath, { force: true });
-}
-
-export function stopDashboard(homeDir = os.homedir()) {
-  const state = readJson(dashboardStatePath(homeDir));
-  if (!state?.pid) {
-    clearDashboardState(homeDir);
-    return { stopped: false, reason: 'not-running' };
-  }
-
-  if (!processExists(state.pid)) {
-    clearDashboardState(homeDir);
-    return { stopped: false, reason: 'stale-state' };
-  }
-
-  process.kill(Number(state.pid), 'SIGTERM');
-  clearDashboardState(homeDir);
-  return { stopped: true, pid: Number(state.pid), port: state.port };
-}
-
 function doctorStatePath(homeDir) {
   return path.join(stateDir(homeDir), 'doctor.json');
 }
@@ -273,67 +234,11 @@ export function startOracle({ rootDir, homeDir = os.homedir(), projectDir = root
   return { started: true, logPath };
 }
 
-export async function startDashboard({ rootDir, homeDir = os.homedir(), preferredPort = 4242 } = {}) {
-  const existing = readDashboardState(homeDir);
-  if (existing && await isDashboardRunning(existing.port)) {
-    return { started: false, reused: true, pid: existing.pid, port: existing.port, url: existing.url };
-  }
-
-  if (existing) clearDashboardState(homeDir);
-
-  const port = await findAvailablePort(preferredPort);
-  const outPath = path.join(runtimeStateDir(homeDir), 'dashboard.log');
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  const out = fs.openSync(outPath, 'a');
-  const err = fs.openSync(outPath, 'a');
-
-  // Opt-in: with CONSTRUCT_OP_ENV_FILE set, launch the daemon under `op run` so
-  // 1Password op:// refs resolve once at startup into its env. The biometric
-  // unlock prompt makes first launch slower, so widen the readiness window then.
-  const { command, args, wrapped } = wrapWithOpRun(
-    process.execPath,
-    [path.join(INSTALL_ROOT, 'lib', 'server', 'index.mjs')],
-    { env: process.env },
-  );
-  const child = spawn(command, args, {
-    detached: true,
-    stdio: ['ignore', out, err],
-    env: { ...process.env, PORT: String(port) },
-  });
-  child.unref();
-
-  let ready = false;
-  const maxTries = wrapped ? 150 : 30;
-  for (let i = 0; i < maxTries; i += 1) {
-    if (await probeRuntimePort(port)) { ready = true; break; }
-    await new Promise((resolve) => setTimeout(resolve, 200));
-  }
-
-  if (!ready) {
-    let logTail = '';
-    try { logTail = fs.readFileSync(outPath, 'utf8').split('\n').slice(-12).join('\n'); } catch { /* log unreadable */ }
-    const window = wrapped ? '30s (op run awaits 1Password unlock)' : '6s';
-    return { started: false, failed: true, port, logPath: outPath, error: `dashboard did not bind 127.0.0.1:${port} within ${window}`, logTail };
-  }
-
-  const state = {
-    pid: child.pid,
-    port,
-    url: `http://127.0.0.1:${port}`,
-    startedAt: new Date().toISOString(),
-    logPath: outPath,
-  };
-  writeJson(dashboardStatePath(homeDir), state);
-  return { started: true, reused: false, ...state };
-}
-
 export async function getRuntimePorts(homeDir = os.homedir(), {
-  dashboardProbeFn = isDashboardRunning,
   memoryProbeFn = isMemoryRunning,
   openCodeProbeFn = isBridgeRunning,
   findAvailablePortFn = findAvailablePort,
 } = {}) {
-  const dashboard = readDashboardState(homeDir);
   const existing = parseEnvFile(getUserEnvPath(homeDir));
 
   async function resolvePort(key, fallback, probe = async (port) => probeRuntimePort(port)) {
@@ -345,7 +250,6 @@ export async function getRuntimePorts(homeDir = os.homedir(), {
   }
 
   return {
-    dashboard: dashboard?.port ?? await resolvePort('DASHBOARD_PORT', 4242, dashboardProbeFn),
     memory: await resolvePort('MEMORY_PORT', derivedMemoryPort(), memoryProbeFn),
     bridge: await resolvePort('BRIDGE_PORT', 5173, openCodeProbeFn),
     copilotBridge: await resolvePort('COPILOT_BRIDGE_PORT', 5174, probeRuntimePort),
@@ -370,7 +274,6 @@ export async function describeRuntimeSupport() {
 }
 
 export const SELECTABLE_SERVICES = Object.freeze([
-  { key: 'dashboard', label: 'Dashboard', description: 'Local operations dashboard on http://127.0.0.1:4242.' },
   { key: 'telemetry', label: 'Telemetry', description: 'Trace export / local JSONL traces.' },
   { key: 'memory', label: 'Memory (cm)', description: 'Persistent memory service (cm).' },
   { key: 'opencode', label: 'OpenCode', description: 'OpenCode bridge server.' },
@@ -393,7 +296,6 @@ export async function startServices({
   selected = null,
   describeRuntimeSupportFn = describeRuntimeSupport,
   getRuntimePortsFn = getRuntimePorts,
-  startDashboardFn = startDashboard,
   loadConstructEnvFn = loadConstructEnv,
   spawnDetachedFn = spawnDetached,
   memoryProbeFn = isMemoryRunning,
@@ -407,7 +309,6 @@ export async function startServices({
   const wants = (key) => selected === null || selected.has(key);
 
   writeEnvValues(envPath, {
-    DASHBOARD_PORT: String(ports.dashboard),
     MEMORY_PORT: String(ports.memory),
     BRIDGE_PORT: String(ports.bridge),
     COPILOT_BRIDGE_PORT: String(ports.copilotBridge),
@@ -429,14 +330,6 @@ export async function startServices({
     });
   }
 
-  // Dashboard
-  if (wants('dashboard')) {
-    const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
-    results.push(dashboard.failed
-      ? { name: 'Dashboard', status: 'failed', note: `${dashboard.error} — see ${dashboard.logPath}` }
-      : { name: 'Dashboard', url: dashboard.url, status: dashboard.reused ? 'reused' : 'started' });
-  }
-
   const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
   const traceBackend = resolveTraceBackend(liveEnv);
   if (wants('telemetry')) {
@@ -590,15 +483,6 @@ export async function stopServices({
     results.push({ name: 'Doctor', status: 'cleaned', note: 'stale state file removed' });
   }
 
-  const dashboard = stopDashboard(homeDir);
-  if (dashboard.stopped) {
-    results.push({ name: 'Dashboard', status: 'stopped', note: `pid ${dashboard.pid}, port ${dashboard.port}` });
-  } else if (dashboard.reason === 'stale-state') {
-    results.push({ name: 'Dashboard', status: 'cleaned', note: 'stale state file removed (process already gone)' });
-  } else {
-    results.push({ name: 'Dashboard', status: 'not-running' });
-  }
-
   const envPath = getUserEnvPath(homeDir);
   const envValues = parseEnvFile(envPath);
   const memoryPort = Number(envValues.MEMORY_PORT) || derivedMemoryPort();

package/lib/setup-prompts.mjs

@@ -13,7 +13,7 @@
  *   4. non-TTY            → false  (CI / scripts — caller can use --yes to opt in)
  *   5. interactive        → prompt [Y/n], cache the answer
  *
- * Consent is stored as BOOTSTRAP_<NAME>=yes|no in ~/.construct/config.env
+ * Consent is stored as BOOTSTRAP_<NAME>=yes|no in ~/.config/construct/config.env
  * so subsequent runs of `construct init` don't re-prompt for the same
  * services. Pass `force = true` to skip the cache and re-prompt.
  */

package/lib/setup.mjs

@@ -3,8 +3,8 @@
  * lib/setup.mjs — Machine-scoped first-run setup wizard for Construct.
  *
  * Installs cm/cass, configures managed defaults, pre-warms the embedding model,
- * wires MCP integrations, and writes ~/.construct/config.env. 
- * Invoked by `construct install` and by lib/install/first-invocation.mjs 
+ * wires MCP integrations, and writes the XDG user config (~/.config/construct/config.env).
+ * Invoked by `construct install` and by lib/install/first-invocation.mjs
  * when a TTY user is missing resources.
  *
  * Project-scoped scaffolding (`.cx/`, AGENTS.md, plan.md, adapters) lives
@@ -22,6 +22,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { ensureUserConfigDir, getUserEnvPath, writeEnvValues } from './env-config.mjs';
+import { migrateLegacyModelConfig, migrateLegacyCredentialConfig } from './config/legacy-config-migration.mjs';
 import { configDir, stateDir, doctorRoot } from './config/xdg.mjs';
 import { DEFAULT_WORKSPACE_PATH, WORKSPACE_DOCS_LANES } from './embed/config.mjs';
 import {
@@ -34,8 +35,6 @@ import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embedding
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
 import { cleanupLegacyGlobalConstruct } from './install/legacy-global-cleanup.mjs';
-import { downloadDesktopBinary } from './install/desktop-binary-download.mjs';
-import { buildDesktopBinary, hasDesktopSource } from './chat/desktop-build.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -65,7 +64,7 @@ Flags:
                       before setup; does not uninstall a global construct CLI
 
 What --scope=user does:
-  - creates ~/.construct/config.env
+  - creates ~/.config/construct/config.env
   - ensures OpenCode config exists
   - configures managed defaults for local vector retrieval (LanceDB)
   - checks required runtime tools and installs cm and cass when available
@@ -354,7 +353,6 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupL
   console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
   console.log('\nWould check / install runtime tooling:');
   console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
-  console.log(`  · construct-chat desktop binary (from GitHub releases → ${path.join(stateDir(homeDir), 'bin')})`);
   console.log('\nWould reach the network / external services:');
   console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
   if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
@@ -408,6 +406,19 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
+  // Forward-migrate model tier overrides stranded in the pre-XDG legacy config
+  // before any legacy-global cleanup deletes ~/.construct, so an upgrade keeps
+  // the user's tier selection without a manual copy.
+  const modelMigration = migrateLegacyModelConfig({ homeDir });
+  if (modelMigration.performed) {
+    console.log(`Migrated ${Object.keys(modelMigration.migrated).join(', ')} from ${modelMigration.legacyPath} → ${modelMigration.xdgPath}`);
+  }
+
+  const credentialMigration = migrateLegacyCredentialConfig({ homeDir });
+  if (credentialMigration.performed) {
+    console.log(`Migrated credentials ${Object.keys(credentialMigration.migrated).join(', ')} from ${credentialMigration.legacyPath} → ${credentialMigration.xdgPath}`);
+  }
+
   if (cleanupLegacyGlobal) {
     runLegacyGlobalCleanup({ homeDir, dryRun: false });
     if (scope === 'project') {
@@ -457,28 +468,6 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     if (cassInstall.installCommand) console.log(`  Install with: ${cassInstall.installCommand}`);
   }
 
-  try {
-    if (hasDesktopSource(ROOT_DIR)) {
-      const built = buildDesktopBinary({ repoRoot: ROOT_DIR, env: process.env });
-      if (built.ok) {
-        console.log(`Desktop binary: built from source → ${built.binaryPath}`);
-      } else {
-        console.log(`Desktop binary: build skipped (${built.reason}) — runs on first \`construct chat\``);
-      }
-    } else {
-      const desktop = await downloadDesktopBinary({ homeDir, env: process.env });
-      if (desktop.status === 'downloaded') {
-        console.log(`Desktop binary: ${desktop.version} → ${desktop.dest}`);
-      } else if (desktop.status === 'failed') {
-        console.log(`Desktop binary: download failed (${desktop.reason}) — run \`construct install --scope=user\` again to retry`);
-      } else {
-        console.log(`Desktop binary: ${desktop.reason}`);
-      }
-    }
-  } catch (err) {
-    console.log(`Desktop binary: skipped (${err?.message || 'unknown error'})`);
-  }
-
   const telemetryResult = process.env.CONSTRUCT_TELEMETRY_URL
     ? { status: 'configured', note: `remote export configured (${process.env.CONSTRUCT_TELEMETRY_URL})` }
     : { status: 'local', note: 'local JSONL traces in .cx/traces; remote export optional' };

package/lib/skills/composition-graph.mjs

@@ -0,0 +1,98 @@
+/**
+ * lib/skills/composition-graph.mjs — Skill routing and workflow composition audit.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadRegistry } from '../registry/loader.mjs';
+import { listScopes } from '../scopes/loader.mjs';
+
+const GET_SKILL_RE = /get_skill\("([^"]+)"\)/g;
+
+function walkSkills(skillsDir, prefix = '') {
+  const out = new Set();
+  if (!fs.existsSync(skillsDir)) return out;
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const full = path.join(skillsDir, entry.name);
+    if (entry.isDirectory()) {
+      for (const s of walkSkills(full, rel)) out.add(s);
+    } else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+      out.add(rel.replace(/\.md$/, ''));
+    }
+  }
+  return out;
+}
+
+function collectRegistrySkills(registry) {
+  const set = new Set();
+  for (const agent of Object.values(registry.specialists || {})) {
+    for (const s of agent.skills || []) set.add(s);
+  }
+  return set;
+}
+
+function collectRoutingTargets(root) {
+  const set = new Set();
+  const jsonPath = path.join(root, 'skills', 'routing.json');
+  if (fs.existsSync(jsonPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+      for (const route of data.routes || data || []) {
+        const target = route.path || route.skill || route.skillId || route.target;
+        if (target) set.add(target.replace(/^skills\//, ''));
+      }
+    } catch { /* skip */ }
+  }
+  return set;
+}
+
+function collectWorkflowRefs(root) {
+  const set = new Set();
+  const docsDir = path.join(root, 'skills', 'docs');
+  if (!fs.existsSync(docsDir)) return set;
+  for (const f of fs.readdirSync(docsDir)) {
+    if (!f.endsWith('-workflow.md')) continue;
+    const body = fs.readFileSync(path.join(docsDir, f), 'utf8');
+    for (const m of body.matchAll(GET_SKILL_RE)) set.add(m[1]);
+  }
+  return set;
+}
+
+export function auditSkillComposition({ rootDir } = {}) {
+  const root = rootDir || path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+  const allOnDisk = walkSkills(path.join(root, 'skills'));
+  const registry = loadRegistry({ rootDir: root });
+  const entitled = collectRegistrySkills(registry);
+  const routed = collectRoutingTargets(root);
+  const workflowRefs = collectWorkflowRefs(root);
+
+  const reachable = new Set([...entitled, ...routed, ...workflowRefs]);
+  for (const id of entitled) {
+    if (id.startsWith('roles/')) reachable.add(id);
+  }
+
+  const unreachable = [...allOnDisk].filter((id) => {
+    if (id.startsWith('roles/')) return false;
+    if (id.startsWith('brand/')) return false;
+    return !reachable.has(id);
+  });
+
+  const blocking = [];
+  for (const id of unreachable) {
+    if (id.startsWith('docs/') && id.endsWith('-workflow')) continue;
+    blocking.push(`unreachable skill: ${id} (not in registry, routing.json, or workflow chain)`);
+  }
+
+  return {
+    pass: blocking.length === 0,
+    blocking,
+    stats: {
+      onDisk: allOnDisk.size,
+      entitled: entitled.size,
+      routed: routed.size,
+      workflowRefs: workflowRefs.size,
+      unreachable: unreachable.length,
+    },
+  };
+}

package/lib/skills/router.mjs

@@ -0,0 +1,80 @@
+/**
+ * lib/skills/router.mjs — keyword + entitlement skill suggestion for agents.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRegistry } from '../registry/loader.mjs';
+import { loadArtifactManifest } from '../artifact-manifest.mjs';
+import { resolveActiveScope } from '../scopes/loader.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+
+let _routes = null;
+
+function loadRoutes(rootDir = ROOT) {
+  if (_routes) return _routes;
+  const p = path.join(rootDir, 'skills', 'routing.json');
+  _routes = JSON.parse(fs.readFileSync(p, 'utf8')).routes || [];
+  return _routes;
+}
+
+function tokenize(text) {
+  return String(text || '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+function scoreRoute(route, tokens) {
+  let score = route.priority || 1;
+  for (const kw of route.keywords || []) {
+    const parts = kw.toLowerCase().split(/\s+/);
+    if (parts.every((p) => tokens.some((t) => t.includes(p) || p.includes(t)))) score += 10;
+    else if (parts.some((p) => tokens.includes(p))) score += 4;
+  }
+  return score;
+}
+
+export function suggestSkills({ intent = '', specialistId = null, limit = 5, rootDir = ROOT, cwd = null } = {}) {
+  const routes = loadRoutes(rootDir);
+  const tokens = tokenize(intent);
+  const scored = routes
+    .map((route) => ({ ...route, score: scoreRoute(route, tokens) }))
+    .filter((r) => r.score > (r.priority || 1))
+    .sort((a, b) => b.score - a.score);
+
+  let entitled = null;
+  if (specialistId) {
+    const registry = loadRegistry({ rootDir });
+    const id = specialistId.startsWith('cx-') ? specialistId : `cx-${specialistId}`;
+    entitled = new Set(registry.specialists?.[id]?.skills || []);
+  }
+
+  const profile = cwd ? resolveActiveScope(cwd) : null;
+  const baseline = new Set(profile?.defaultSkills || []);
+
+  const manifest = loadArtifactManifest({ rootDir });
+  for (const entry of Object.values(manifest.artifacts || {})) {
+    if (entry.workflowSkill && tokens.some((t) => t.includes('prd') || t.includes('adr'))) {
+      scored.push({ path: entry.workflowSkill, domain: 'workflow', score: 12, priority: 12 });
+    }
+  }
+
+  const merged = new Map();
+  for (const item of scored) {
+    const prev = merged.get(item.path);
+    if (!prev || item.score > prev.score) merged.set(item.path, item);
+  }
+
+  const results = [...merged.values()]
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((r) => ({
+      path: r.path,
+      domain: r.domain,
+      score: r.score,
+      entitled: entitled ? entitled.has(r.path) || baseline.has(r.path) : true,
+    }));
+
+  return { intent, suggestions: results };
+}

package/lib/specialist-contracts.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/specialist-contracts.mjs — loader + query layer for specialists/contracts.json.
+ * lib/specialist-contracts.mjs — loader + query layer for specialists/org contracts.
  *
  * Agent contracts are explicit service contracts between Construct roles —
  * "when cx-product-manager hands off to cx-architect, the packet MUST contain
@@ -14,27 +14,15 @@
  *     to introspect their inputs and expected outputs at handoff time.
  *   - future: handoff validators that check packet shape before dispatch.
  */
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = resolve(MODULE_DIR, '..');
-const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
+import { loadRegistry } from './registry/loader.mjs';
 
 let _cache = null;
 
 function loadRaw() {
   if (_cache) return _cache;
-  if (!existsSync(CONTRACTS_PATH)) {
-    _cache = { version: 0, contracts: [] };
-    return _cache;
-  }
-  try {
-    _cache = JSON.parse(readFileSync(CONTRACTS_PATH, 'utf8'));
-  } catch (err) {
-    _cache = { version: 0, contracts: [], parseError: err?.message || String(err) };
-  }
+  const registry = loadRegistry();
+  const contracts = Object.values(registry.contracts || {});
+  _cache = { version: 2, contracts };
   return _cache;
 }
 
@@ -46,6 +34,13 @@ export function getContractById(id) {
   return getAllContracts().find((c) => c.id === id) || null;
 }
 
+export function getContractSkillHints(contractOrId) {
+  const contract = typeof contractOrId === 'string'
+    ? getContractById(contractOrId)
+    : contractOrId;
+  return Array.isArray(contract?.skillHints) ? [...contract.skillHints] : [];
+}
+
 /**
  * Returns the contract for a specific producer→consumer pair. If multiple
  * contracts match (e.g. wildcard producer "*"), returns the most specific one.
@@ -152,7 +147,11 @@ export function resolveContractChain(ctx = {}) {
     const stage = contract.trigger?.postConsumer ? 'followup'
       : contract.producer === 'user' ? 'precheck'
       : 'handoff';
-    chain.push({ contract, stage });
+    chain.push({
+      contract,
+      stage,
+      skillHints: getContractSkillHints(contract),
+    });
   }
   return chain;
 }

package/lib/specialists/postconditions.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/specialists/postconditions.mjs — hard binary postconditions per producer persona.
  *
- * `specialists/contracts.json` carries free-text postconditions for documentation
+ * `specialists/org` carries free-text postconditions for documentation
  * purposes. This module adds binary, programmatically-validated assertions
  * that the persona's output packet must satisfy before a handoff is allowed
  * to proceed. Failure throws `ContractViolationError` with reason
@@ -40,7 +40,7 @@ function isLaterOrEqual(a, b) {
 }
 
 /**
- * Rule table. Keyed by producer name (matching specialists/registry.json).
+ * Rule table. Keyed by producer name (matching specialists/org).
  * Each rule:
  *   id          — stable identifier for violation logs
  *   description — single-line documentation

package/lib/specialists/prompt-schema.mjs

@@ -17,6 +17,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
+import { loadRegistry as loadRuntimeRegistry } from '../registry/loader.mjs';
 
 export const REQUIRED_FRONTMATTER = ['name', 'role', 'version', 'perspective'];
 export const PERSPECTIVE_FIELDS = ['bias', 'tension', 'openingQuestion', 'failureMode'];
@@ -124,8 +125,8 @@ export function validatePromptFiles({ rootDir = process.cwd(), registry } = {})
   let total = 0;
   let converted = 0;
 
-  const reg = registry ?? loadRegistry(rootDir);
-  const specialists = Array.isArray(reg?.specialists) ? reg.specialists : [];
+  const reg = registry ?? loadPromptRegistry(rootDir);
+  const specialists = Array.isArray(reg?.specialists) ? reg.specialists : Object.values(reg?.specialists || {});
   const byName = new Map(specialists.map((s) => [s.name, s]));
 
   const seen = new Set();
@@ -145,9 +146,9 @@ export function validatePromptFiles({ rootDir = process.cwd(), registry } = {})
   return { errors, warnings, total, converted };
 }
 
-function loadRegistry(rootDir) {
+function loadPromptRegistry(rootDir) {
   try {
-    return JSON.parse(fs.readFileSync(path.join(rootDir, 'specialists', 'registry.json'), 'utf8'));
+    return loadRuntimeRegistry({ rootDir });
   } catch {
     return { specialists: [] };
   }
@@ -159,7 +160,7 @@ function loadRegistry(rootDir) {
  * @returns {object|null}
  */
 export function resolvePerspectiveFromPrompt(agentName, { rootDir = process.cwd(), registry } = {}) {
-  const reg = registry ?? loadRegistry(rootDir);
+  const reg = registry ?? loadPromptRegistry(rootDir);
   const normalized = String(agentName ?? '').trim().replace(/^cx-/, '');
   const entry = (reg.specialists ?? []).find((s) => s.name === normalized);
   if (!entry?.promptFile) return null;

package/lib/specialists/roster.mjs

@@ -6,17 +6,10 @@
  * than inlined into synced orchestrator prompts. Each catalog entry carries id and
  * whenToUse for routing discovery without an always-on prompt block.
  */
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { loadRegistry } from '../registry/loader.mjs';
 
-const REGISTRY_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'specialists', 'registry.json');
-
-function loadRegistry(rootDir = null) {
-  const path = rootDir
-    ? join(rootDir, 'specialists', 'registry.json')
-    : REGISTRY_PATH;
-  return JSON.parse(readFileSync(path, 'utf8'));
+function loadRegistryForRoot(rootDir = null) {
+  return loadRegistry(rootDir ? { rootDir } : {});
 }
 
 /**
@@ -24,9 +17,11 @@ function loadRegistry(rootDir = null) {
  * the cx-prefixed id and the routing hint (when_to_use when present, else description).
  */
 export function buildSpecialistCatalog({ rootDir = null, includeInternal = true } = {}) {
-  const registry = loadRegistry(rootDir);
+  const registry = loadRegistryForRoot(rootDir);
   const prefix = registry.prefix || 'cx';
-  const specialists = Array.isArray(registry.specialists) ? registry.specialists : [];
+  const specialists = Array.isArray(registry.specialists)
+    ? registry.specialists
+    : Object.values(registry.specialists || {});
   return specialists
     .filter((s) => includeInternal || !s.internal)
     .map((s) => ({