@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/mcp/tools/skills.mjs

@@ -21,8 +21,14 @@ export function listSkills({ ROOT_DIR }) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
-      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
+        // Directory form: <name>/SKILL.md — emit the directory name as the skill id.
+        const skillMd = join(dir, entry.name, 'SKILL.md');
+        if (existsSync(skillMd)) {
+          results.push(`${prefix}${entry.name}`);
+        } else {
+          results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
+        }
+      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md' && entry.name !== 'routing.md') {
         results.push(`${prefix}${entry.name.replace('.md', '')}`);
       }
     }
@@ -37,13 +43,28 @@ export function getSkill(args, { ROOT_DIR }) {
   const { path: skillPath } = args;
   if (!skillPath) return { error: 'Missing path argument' };
 
-  const fullPath = join(ROOT_DIR, 'skills', `${skillPath}.md`);
+  // Primary: flat file form skills/<path>.md
+  // Fallback: directory form skills/<path>/SKILL.md (one minor-release grace period)
+  const candidates = [
+    join(ROOT_DIR, 'skills', `${skillPath}.md`),
+    join(ROOT_DIR, 'skills', skillPath, 'SKILL.md'),
+  ];
 
-  if (!existsSync(fullPath)) {
+  const fullPath = candidates.find(existsSync);
+  if (!fullPath) {
     return { error: `Skill not found: ${skillPath}` };
   }
+  const t0 = Date.now();
   const content = readFileSync(fullPath, 'utf8');
-  logSkillCall({ skillId: skillPath, source: 'mcp' });
+  logSkillCall({
+    skillId: skillPath,
+    source: 'mcp',
+    latencyMs: Date.now() - t0,
+    callerContext: args.callerContext,
+    agentId: args.agentId,
+    sessionId: args.sessionId,
+    tokensReturned: Math.ceil(content.length / 4),
+  });
   return { content };
 }
 
@@ -114,8 +135,8 @@ export async function agentContract(args = {}) {
     getOutgoingContracts,
     getIncomingContracts,
     summarize,
-  } = await import('../../agent-contracts.mjs');
-  const { describePostconditions } = await import('../../agents/postconditions.mjs');
+  } = await import('../../specialist-contracts.mjs');
+  const { describePostconditions } = await import('../../specialists/postconditions.mjs');
   const { id, producer, consumer } = args;
   // Attach binary postconditions to every returned contract so a specialist
   // calling this tool at handoff time sees the hard checks their output
@@ -382,8 +403,8 @@ export async function workerRun(args = {}) {
 }
 
 export function listTeams({ ROOT_DIR }) {
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  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'));
   return {
     teams: Object.entries(templates).map(([name, t]) => ({
@@ -400,8 +421,8 @@ export function listTeams({ ROOT_DIR }) {
 export function getTeam(args, { ROOT_DIR }) {
   const { name } = args;
   if (!name) return { error: 'Missing name argument' };
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  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) };

package/lib/mcp/tools/workflow.mjs

@@ -96,6 +96,31 @@ export function workflowValidate(args) {
   return { cwd, ...result };
 }
 
+/**
+ * Validate a producer→consumer handoff against specialists/contracts.json.
+ *
+ * Args:
+ *   producer    — agent or persona name producing the artifact
+ *   consumer    — agent or persona name receiving it
+ *   id          — optional contract id (overrides producer/consumer lookup)
+ *   artifact    — the handoff payload to validate
+ *   enforcement — 'warn' (default) or 'block'; 'block' returns ok:false on
+ *                 violation so the workflow can refuse to advance
+ *
+ * Returns { ok, status?, errors?, warnings?, contract } where status is set
+ * to 'BLOCKED_CONTRACT' on enforced violations.
+ */
+export async function workflowContractValidate(args) {
+  const { validateHandoff } = await import('../../contracts/validate.mjs');
+  return validateHandoff({
+    producer: args.producer,
+    consumer: args.consumer,
+    id: args.id,
+    artifact: args.artifact,
+    enforcement: args.enforcement || process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+  });
+}
+
 export function workflowImportPlan(args) {
   const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
   const markdown = args.markdown ?? '';

package/lib/mcp-catalog.json

@@ -55,21 +55,25 @@
       "id": "memory",
       "name": "Memory",
       "category": "optional",
-      "description": "cass-memory over HTTP. Persistent cross-session and cross-agent memory for decisions, findings, and handoffs.",
-      "type": "url",
-      "url": "http://127.0.0.1:8765/",
-      "env": {},
+      "description": "cass-memory persistent cross-session and cross-agent memory, fronted by the Construct stdio MCP bridge so editors get a full MCP handshake.",
+      "command": "node",
+      "args": [
+        "__CX_TOOLKIT_DIR__/lib/mcp/memory-bridge.mjs"
+      ],
+      "env": {
+        "CONSTRUCT_MEMORY_BRIDGE_URL": "http://127.0.0.1:__MEMORY_PORT__/"
+      },
       "requiredEnv": [],
       "setupModes": [
         "auto",
         "manual"
       ],
       "hostSupport": {
-        "claude": { "mode": "unsupported", "label": "construct-mcp (project .mcp.json)" },
-        "opencode": { "mode": "unsupported", "label": "construct-mcp (stdio)" },
-        "codex": { "mode": "unsupported", "label": "construct-mcp / local observation tools" }
+        "claude": { "mode": "managed" },
+        "opencode": { "mode": "managed" },
+        "codex": { "mode": "managed" }
       },
-      "setupNote": "Claude Code and Codex reject the cass-memory HTTP endpoint because `cm serve` skips the MCP `initialize` handshake. On Claude, memory tools (memory_search, memory_add_observations, memory_recent, memory_create_entities) are exposed through the project-local construct-mcp stdio server in .mcp.json. OpenCode does not support the cass-memory HTTP endpoint (SSE transport fails with 405) — use construct-mcp stdio server instead, which wraps memory tools correctly.",
+      "setupNote": "Memory is wired as a stdio MCP bridge (lib/mcp/memory-bridge.mjs). The bridge answers the MCP handshake locally (initialize, ping, notifications/initialized) and forwards tools/list, tools/call, resources/list, resources/read to cm at CONSTRUCT_MEMORY_BRIDGE_URL. cm itself never sees the handshake calls that v0.2.x cannot answer.",
       "usedBy": [
         "construct",
         "cx-docs-keeper",

package/lib/mcp-platform-config.mjs

@@ -48,13 +48,21 @@ function buildRemoteHeaders(mcpDef, resolvedValues) {
   return stripUnresolvedValues(resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues));
 }
 
+function withMemoryDefaults(id, values) {
+  if (id !== "memory") return values;
+  if (values.MEMORY_PORT) return values;
+  return { ...values, MEMORY_PORT: "8765" };
+}
+
 export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
+  const values = withMemoryDefaults(id, { CX_TOOLKIT_DIR: ROOT_DIR, ...resolvedValues });
+
   if (mcpDef.type === "url") {
-    const headers = buildRemoteHeaders(mcpDef, resolvedValues);
+    const headers = buildRemoteHeaders(mcpDef, values);
     const url =
-      id === "memory" && resolvedValues.MEMORY_PORT
-        ? `http://127.0.0.1:${resolvedValues.MEMORY_PORT}/`
-        : resolveTemplateString(mcpDef.url, resolvedValues);
+      id === "memory" && values.MEMORY_PORT
+        ? `http://127.0.0.1:${values.MEMORY_PORT}/`
+        : resolveTemplateString(mcpDef.url, values);
     return {
       type: "http",
       url,
@@ -62,19 +70,19 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
     };
   }
 
-  const env = buildLocalEnvironment(mcpDef, resolvedValues);
+  const env = buildLocalEnvironment(mcpDef, values);
   return {
     command: mcpDef.command,
-    args: resolveArgs(mcpDef.args, resolvedValues),
+    args: resolveArgs(mcpDef.args, values),
     ...(Object.keys(env).length > 0 ? { env } : {}),
   };
 }
 
 export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
-  const runtimeValues = {
+  const runtimeValues = withMemoryDefaults(id, {
     CX_TOOLKIT_DIR: ROOT_DIR,
     ...resolvedValues,
-  };
+  });
   const openCodeId = getOpenCodeMcpId(id);
 
   if (mcpDef.type === "url") {

package/lib/migrations/index.mjs

@@ -0,0 +1,106 @@
+/**
+ * lib/migrations/index.mjs — Schema migration registry and runner.
+ *
+ * Construct's machine-readable artifacts (specialists/registry.json, contracts.json,
+ * role-manifests.json, .cx/config.json, profile JSON) carry an integer
+ * `version` field. When the installed binary's expected schema version is
+ * higher than the on-disk version, migrations apply in order. When the on-disk
+ * version is higher, the runner refuses to load and instructs the operator to
+ * upgrade.
+ *
+ * Each migration is a module under lib/migrations/ that exports:
+ *   - from: integer
+ *   - to: integer
+ *   - apply(artifactPath, options): Promise<{ changed, summary }>
+ *
+ * v1 is the baseline — no migration needed. The registry below is the contract
+ * between the installed binary and migration authors.
+ */
+
+import v1Baseline from './v1-baseline.mjs';
+
+const REGISTRY = [
+  v1Baseline,
+];
+
+export const CURRENT_SCHEMA_VERSION = Math.max(...REGISTRY.map((m) => m.to));
+
+/**
+ * Compute the migration path from `fromVersion` to CURRENT_SCHEMA_VERSION.
+ * Returns an array of migrations to apply in order, or null if no path exists.
+ */
+export function planMigrations(fromVersion, toVersion = CURRENT_SCHEMA_VERSION) {
+  if (fromVersion === toVersion) return [];
+  if (fromVersion > toVersion) return null;
+  const steps = [];
+  let cursor = fromVersion;
+  while (cursor < toVersion) {
+    const step = REGISTRY.find((m) => m.from === cursor);
+    if (!step) return null;
+    steps.push(step);
+    cursor = step.to;
+  }
+  return steps;
+}
+
+/**
+ * Apply a planned migration sequence. Each step receives the artifact path
+ * and any options. Returns a summary including every step's outcome.
+ *
+ * When dryRun is true, steps must not write to disk; they only report what
+ * they would change.
+ */
+export async function runMigrations({ artifactPath, fromVersion, toVersion = CURRENT_SCHEMA_VERSION, dryRun = false }) {
+  const plan = planMigrations(fromVersion, toVersion);
+  if (plan === null) {
+    return {
+      ok: false,
+      error: `no migration path from version ${fromVersion} to ${toVersion}`,
+      applied: [],
+    };
+  }
+  if (plan.length === 0) {
+    return { ok: true, applied: [], summary: 'no migrations needed' };
+  }
+
+  const applied = [];
+  for (const step of plan) {
+    try {
+      const result = await step.apply(artifactPath, { dryRun });
+      applied.push({ from: step.from, to: step.to, ...result });
+    } catch (err) {
+      return {
+        ok: false,
+        error: `migration ${step.from}→${step.to} failed: ${err.message}`,
+        applied,
+      };
+    }
+  }
+  return { ok: true, applied, summary: `applied ${applied.length} migration(s)` };
+}
+
+/**
+ * Check artifact compatibility. Returns:
+ *   { compatible: true }                              — versions match
+ *   { compatible: false, needsMigration: true,  ... } — on-disk is older
+ *   { compatible: false, needsUpgrade: true, ... }   — on-disk is newer
+ */
+export function checkCompatibility(artifactVersion, expected = CURRENT_SCHEMA_VERSION) {
+  if (artifactVersion === expected) return { compatible: true };
+  if (artifactVersion < expected) {
+    return {
+      compatible: false,
+      needsMigration: true,
+      fromVersion: artifactVersion,
+      toVersion: expected,
+      message: `artifact schema version ${artifactVersion} is older than expected ${expected}; run 'construct migrate'`,
+    };
+  }
+  return {
+    compatible: false,
+    needsUpgrade: true,
+    fromVersion: artifactVersion,
+    toVersion: expected,
+    message: `artifact schema version ${artifactVersion} is newer than this binary supports (${expected}); run 'construct upgrade'`,
+  };
+}

package/lib/migrations/v1-baseline.mjs

@@ -0,0 +1,33 @@
+/**
+ * lib/migrations/v1-baseline.mjs — No-op baseline migration.
+ *
+ * Marks v0 (pre-versioned artifacts) as compatible with v1 by stamping the
+ * artifact with `version: 1` when absent. Schema bumps after v1 will add new
+ * migrations rather than modifying this one.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+export default {
+  from: 0,
+  to: 1,
+  description: 'Stamp pre-versioned artifacts with version: 1 (no shape changes)',
+  async apply(artifactPath, { dryRun = false } = {}) {
+    if (!existsSync(artifactPath)) {
+      return { changed: false, summary: `${artifactPath}: not present (skip)` };
+    }
+    let data;
+    try { data = JSON.parse(readFileSync(artifactPath, 'utf8')); }
+    catch (err) { throw new Error(`failed to parse ${artifactPath}: ${err.message}`); }
+
+    if (data && typeof data === 'object' && data.version === 1) {
+      return { changed: false, summary: `${artifactPath}: already at v1` };
+    }
+
+    const next = { ...data, version: 1 };
+    if (!dryRun) {
+      writeFileSync(artifactPath, JSON.stringify(next, null, 2) + '\n');
+    }
+    return { changed: true, summary: `${artifactPath}: stamped version: 1` };
+  },
+};

package/lib/model-registry.mjs

@@ -19,7 +19,7 @@ import path from 'node:path';
  * RESOLUTION ORDER (highest to lowest):
  * 1. Environment variables (CX_MODEL_*): Emergency overrides
  * 2. User config (~/.construct/config.env): Personal defaults
- * 3. Registry (agents/registry.json): Project recommendations
+ * 3. Registry (specialists/registry.json): Project recommendations
  * 4. Built-in defaults: Last resort fallbacks
  * 
  * Primary resolution path. All code must use this function.

package/lib/observation-store.mjs

@@ -19,6 +19,7 @@ import { embedSync as embedText } from './storage/embeddings-legacy.mjs';
 import { embedText as embedTextEngine } from './storage/embeddings-engine.mjs';
 import { VectorClient } from './storage/vector-client.mjs';
 import { withFileLockSync } from './storage/file-lock.mjs';
+import { ensureCxDir } from './project-init-shared.mjs';
 
 const OBS_DIR = '.cx/observations';
 const INDEX_FILE = 'index.json';
@@ -36,7 +37,10 @@ const VALID_CATEGORIES = new Set([
   'pattern', 'anti-pattern', 'dependency', 'decision', 'insight', 'session-summary',
 ]);
 
-function ensureDir(dir) {
+function ensureDir(dir, rootDir = null) {
+  // Preserves the construct context invariant: any code that creates a .cx/
+  // subdirectory also initializes context.md from the project template.
+  if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
@@ -91,6 +95,7 @@ function logCapDrop(rootDir, kind, dropped, total) {
   if (dropped <= 0) return;
   try {
     const logPath = path.join(rootDir, '.cx', 'observation-cap-warnings.jsonl');
+    ensureCxDir(rootDir);
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     const entry = JSON.stringify({
       ts: new Date().toISOString(),
@@ -105,7 +110,7 @@ function logCapDrop(rootDir, kind, dropped, total) {
 }
 
 function writeIndex(rootDir, entries) {
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX);
   if (entries.length > MAX_INDEX) {
     logCapDrop(rootDir, 'observation-index', entries.length - MAX_INDEX, entries.length);
@@ -124,7 +129,7 @@ function readVectors(rootDir) {
 }
 
 function writeVectors(rootDir, records) {
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   if (records.length > MAX_INDEX) {
     logCapDrop(rootDir, 'observation-vectors', records.length - MAX_INDEX, records.length);
   }
@@ -177,7 +182,7 @@ export async function addObservation(rootDir, {
   // Lock the per-store index so concurrent writers (CLI + hooks) cannot
   // corrupt the index/vectors JSON pair. The observation JSON file is
   // unique-per-id and doesn't need the lock; the shared structures do.
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(obsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + '\n',

package/lib/opencode-runtime-plugin.mjs

@@ -415,7 +415,7 @@ function buildHostConstraints() {
 
 function readRegistryModels(rootDir) {
   try {
-    const registryPath = join(rootDir, "agents", "registry.json");
+    const registryPath = join(rootDir, "specialists", "registry.json");
     if (!existsSync(registryPath)) return {};
     const registry = JSON.parse(readFileSync(registryPath, "utf8"));
     return registry?.models ?? {};

package/lib/orchestration-policy.mjs

@@ -6,14 +6,14 @@
  *   2. framing/research/doc-ownership gates  (what must be true before work starts)
  *   3. contract chain (resolveContractChain)  (what the typed handoffs are)
  *
- * Agent-to-agent contracts are defined in agents/contracts.json and loaded via
- * lib/agent-contracts.mjs. That file is the single source of truth for
+ * Agent-to-agent contracts are defined in specialists/contracts.json and loaded via
+ * lib/specialist-contracts.mjs. That file is the single source of truth for
  * producer→consumer expectations, replacing the scattered DOC_OWNERSHIP map,
  * SPECIALIST_MAP, and informal "collaborators" lists for anything contract-
  * shaped. The older maps remain for quick lookups but defer to contracts.json
  * for authoritative semantics.
  */
-import { resolveContractChain } from './agent-contracts.mjs';
+import { resolveContractChain } from './specialist-contracts.mjs';
 import { verifyRoute } from './intent-classifier.mjs';
 
 export const EXECUTION_TRACKS = {
@@ -80,7 +80,7 @@ export const DOC_OWNERSHIP = {
 // Event ownership for the role framework (lib/roles/**). When a hook emits
 // an event of one of these types, the gateway routes the invocation to the
 // listed persona. Empty owners mean the event is recorded but no persona
-// fires until onboarded. Keep in sync with agents/role-manifests.json.
+// fires until onboarded. Keep in sync with specialists/role-manifests.json.
 
 export const EVENT_OWNERSHIP = {
   'push_gate.fail': 'cx-sre',

package/lib/outcomes/record.mjs

@@ -16,6 +16,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { withFileLockSync } from '../storage/file-lock.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const ROTATE_AT = 10_000;
 const MAX_NOTES = 500;
@@ -65,6 +66,7 @@ function countLines(file) {
 export function recordOutcome(cwd, payload) {
   if (!cwd || !payload || typeof payload.success !== 'boolean') return null;
   try {
+    ensureCxDir(cwd);
     fs.mkdirSync(outcomesDir(cwd), { recursive: true });
     const file = activeFile(cwd, payload.role);
 

package/lib/overrides/resolver.mjs

@@ -38,11 +38,11 @@ export const SUPPORTED_CATEGORIES = Object.freeze([
 
 const CATEGORY_RULES = {
   personas: { originalDir: 'personas', defaultExt: '.md' },
-  agents: { originalDir: 'agents/prompts', defaultExt: '.md' },
+  agents: { originalDir: 'specialists/prompts', defaultExt: '.md' },
   skills: { originalDir: 'skills', defaultExt: '.md' },
   rules: { originalDir: 'rules', defaultExt: '.md' },
-  contracts: { originalDir: 'agents', defaultExt: '.json', singleFile: 'contracts.json' },
-  'role-manifests': { originalDir: 'agents', defaultExt: '.json', singleFile: 'role-manifests.json' },
+  contracts: { originalDir: 'specialists', defaultExt: '.json', singleFile: 'contracts.json' },
+  'role-manifests': { originalDir: 'specialists', defaultExt: '.json', singleFile: 'role-manifests.json' },
 };
 
 function categoryRule(category) {

package/lib/parity.mjs

@@ -3,7 +3,7 @@
  *
  * After `construct sync` writes adapters to multiple surfaces (Claude Code,
  * OpenCode, Codex, Copilot, VS Code, Cursor), the module diffs each surface's actual state against the
- * canonical `agents/registry.json`. Backs `construct doctor` for surfacing
+ * canonical `specialists/registry.json`. Backs `construct doctor` for surfacing
  * silent divergence — for instance, an agent added to the registry that
  * never made it to OpenCode because of a sync regression.
  *
@@ -31,7 +31,7 @@ const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(MODULE_DIR, '..');
 
 function loadRegistry(rootDir = ROOT_DIR) {
-  const file = path.join(rootDir, 'agents', 'registry.json');
+  const file = path.join(rootDir, 'specialists', 'registry.json');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
@@ -42,8 +42,8 @@ function adapterName(entry, prefix) {
 function entriesForSurface(registry, surface) {
   const prefix = registry.prefix || 'cx';
   const entries = [
-    ...(registry.personas || []).map((p) => ({ ...p, isPersona: true })),
-    ...(registry.agents || []).map((a) => ({ ...a, isPersona: false })),
+    ...(registry.orchestrator ? [{ ...registry.orchestrator, isPersona: true }] : []),
+    ...(registry.specialists || []).map((s) => ({ ...s, isPersona: false })),
   ];
 
   return entries

package/lib/policy/engine.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/policy/engine.mjs — role-based policy decisions for tool / action access.
  *
- * Reads role permissions from `agents/role-manifests.json` and decides
+ * Reads role permissions from `specialists/role-manifests.json` and decides
  * whether a given (role, project, tool, action, risk) tuple is allowed,
  * needs approval, or is denied outright. Powers the MCP broker for team
  * and enterprise deployments; solo mode leaves the broker off so this
@@ -20,7 +20,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'agents', 'role-manifests.json');
+const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'specialists', 'role-manifests.json');
 
 const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
 

package/lib/profiles/lifecycle.mjs

@@ -76,7 +76,7 @@ Goal: define the role set and how it interlocks with the curated cx-* registry.
   reuse-existing (name the cx-* agent), create-new (specify scope), or compose-overlay (which base role + which flavor).
 - Identify cross-role handoffs. Where can ambiguity stall the loop? Name the orchestrator role.
 - Validate against the per-role cap (max 6 flavors per role per profile).
-- Acceptance: every declared role either exists in agents/registry.json or has a written scope statement.
+- Acceptance: every declared role either exists in specialists/registry.json or has a written scope statement.
 
 ## 4. Validation (cx-evaluator)
 

package/lib/profiles/rebrand.mjs

@@ -0,0 +1,46 @@
+/**
+ * lib/profiles/rebrand.mjs — Profile-aware language helper.
+ *
+ * Each curated profile carries a `rebrand` block: how the active profile
+ * wants the intake queue and individual signal items named in user-facing
+ * surfaces (CLI output, daemon logs, session-start prelude). The helper
+ * centralises that lookup so every consumer goes through one path with
+ * safe defaults instead of hardcoding "intake queue" / "signal" / "intake".
+ *
+ * Defaults match the legacy strings so behaviour is unchanged for the rnd
+ * profile and for any environment where profile resolution fails.
+ */
+
+import { resolveActiveProfile } from './loader.mjs';
+
+export const DEFAULT_REBRAND = Object.freeze({
+  intakeQueueLabel: 'Intake queue',
+  signalNoun: 'signal',
+});
+
+/**
+ * Return the active profile's rebrand labels.
+ *
+ * @param {string} [rootDir] - project root where profile.json / construct.config.json live.
+ * @returns {{ intakeQueueLabel: string, signalNoun: string }}
+ *
+ * Returns defaults when `rootDir` is missing, when the profile cannot be
+ * loaded, or when the profile omits its `rebrand` block. Never throws.
+ */
+export function getRebrand(rootDir) {
+  if (!rootDir || typeof rootDir !== 'string') return { ...DEFAULT_REBRAND };
+  try {
+    const profile = resolveActiveProfile(rootDir);
+    const rb = profile?.rebrand;
+    if (!rb || typeof rb !== 'object') return { ...DEFAULT_REBRAND };
+    const intakeQueueLabel = typeof rb.intakeQueueLabel === 'string' && rb.intakeQueueLabel.trim()
+      ? rb.intakeQueueLabel.trim()
+      : DEFAULT_REBRAND.intakeQueueLabel;
+    const signalNoun = typeof rb.signalNoun === 'string' && rb.signalNoun.trim()
+      ? rb.signalNoun.trim()
+      : DEFAULT_REBRAND.signalNoun;
+    return { intakeQueueLabel, signalNoun };
+  } catch {
+    return { ...DEFAULT_REBRAND };
+  }
+}

package/lib/project-init-shared.mjs

@@ -235,6 +235,18 @@ Describe the current objective in one clear sentence.
 `;
 }
 
+export function ensureCxDir(rootDir) {
+  const cxDir = path.join(rootDir, '.cx');
+  const contextPath = path.join(cxDir, 'context.md');
+  if (!fs.existsSync(cxDir)) {
+    fs.mkdirSync(cxDir, { recursive: true });
+  }
+  if (!fs.existsSync(contextPath)) {
+    fs.writeFileSync(contextPath, buildContextMarkdown(), 'utf8');
+  }
+  return cxDir;
+}
+
 export function buildContextMarkdown() {
   return `<!--
 .cx/context.md — concise resumable project context for human and agent handoff.

package/lib/prompt-metadata.mjs

@@ -25,9 +25,9 @@ function normalizeName(name) {
 function findEntry(registry, agentName) {
   const normalized = normalizeName(agentName);
   const entries = [
-    ...(registry.personas ?? []),
-    ...(registry.agents ?? []),
-  ];
+    registry.orchestrator,
+    ...(registry.specialists ?? []),
+  ].filter(Boolean);
   return entries.find((entry) => {
     const entryName = normalizeName(entry.name);
     return entryName === normalized || `cx-${entryName}` === String(agentName ?? '').trim().toLowerCase();
@@ -36,7 +36,7 @@ function findEntry(registry, agentName) {
 
 export function resolvePromptEntry(agentName, { rootDir = process.cwd(), registry } = {}) {
   if (!agentName) return null;
-  const loadedRegistry = registry ?? readJson(path.join(rootDir, 'agents', 'registry.json'));
+  const loadedRegistry = registry ?? readJson(path.join(rootDir, 'specialists', 'registry.json'));
   if (!loadedRegistry) return null;
   return findEntry(loadedRegistry, agentName);
 }