@geraldmaron/construct 1.0.0

package/lib/opencode-telemetry.mjs

@@ -0,0 +1,433 @@
+/**
+ * lib/opencode-telemetry.mjs — OpenCode → Langfuse full-fidelity tracing.
+ *
+ * Maintains per-session state, maps OpenCode events/hooks onto Langfuse
+ * trace/generation/span/event observations, and flushes on session.idle.
+ */
+import { randomUUID } from "node:crypto";
+import { createIngestClient } from "./telemetry/langfuse-ingest.mjs";
+
+const SECRET_PATH_PATTERNS = [
+  /(^|\/)\.env(\.|$)/i,
+  /credentials/i,
+  /secrets?\./i,
+  /private.*key/i,
+  /\.pem$/i,
+  /id_rsa/i,
+  /id_ed25519/i,
+];
+
+const LARGE_OUTPUT_CHARS = 20_000;
+
+const sessionTraces = new Map();
+let cachedIngest = null;
+
+export function getIngestClient(env = process.env) {
+  if (cachedIngest) return cachedIngest;
+  cachedIngest = createIngestClient({
+    baseUrl: env.LANGFUSE_BASEURL,
+    publicKey: env.LANGFUSE_PUBLIC_KEY,
+    secretKey: env.LANGFUSE_SECRET_KEY,
+    onError: (err) => {
+      if (env.CONSTRUCT_TRACE_DEBUG === "1") {
+        // eslint-disable-next-line no-console
+        console.error("[construct-telemetry]", err?.message || err);
+      }
+    },
+  });
+  return cachedIngest;
+}
+
+export function resetForTests() {
+  sessionTraces.clear();
+  cachedIngest = null;
+}
+
+function stringifyModel(model) {
+  if (!model) return undefined;
+  if (typeof model === "string") return model;
+  if (model.providerID && model.modelID) return `${model.providerID}/${model.modelID}`;
+  return model.id || model.name || undefined;
+}
+
+function redactToolArgs(tool, args) {
+  if (!args || typeof args !== "object") return args;
+  const filePath = args.filePath || args.file_path || args.path;
+  if (typeof filePath === "string" && SECRET_PATH_PATTERNS.some((re) => re.test(filePath))) {
+    return { _redacted: "sensitive path", filePath };
+  }
+  return args;
+}
+
+function redactToolOutput(output) {
+  if (typeof output !== "string") return output;
+  if (output.length > LARGE_OUTPUT_CHARS) {
+    return `${output.slice(0, LARGE_OUTPUT_CHARS)}…[truncated ${output.length - LARGE_OUTPUT_CHARS} chars]`;
+  }
+  return output;
+}
+
+function extractTextFromParts(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .filter((p) => p && typeof p === "object" && p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text)
+    .join("\n");
+}
+
+function getSessionIdFromEvent(event) {
+  return (
+    event?.properties?.info?.sessionID
+    || event?.properties?.sessionID
+    || event?.properties?.sessionId
+    || event?.session?.id
+    || event?.sessionID
+    || event?.sessionId
+    || event?.data?.sessionId
+    || null
+  );
+}
+
+function getAgentFromEvent(event) {
+  return (
+    event?.properties?.info?.agent
+    || event?.properties?.agent
+    || event?.session?.agent
+    || event?.agent
+    || null
+  );
+}
+
+function sanitizeUsage(tokens, cost) {
+  if (!tokens) return undefined;
+  const input = Number(tokens.input) || 0;
+  const output = Number(tokens.output) || 0;
+  const reasoning = Number(tokens.reasoning) || 0;
+  const total = input + output + reasoning;
+  if (!input && !output && !total) return undefined;
+  const usage = { input, output, total, unit: "TOKENS" };
+  if (Number(cost) > 0) usage.totalCost = Number(cost);
+  return usage;
+}
+
+export function ensureSessionTrace(sessionId, { env = process.env, agent, userId, metadata } = {}) {
+  if (!sessionId) return null;
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return null;
+  let entry = sessionTraces.get(sessionId);
+  if (!entry) {
+    const traceId = sessionId;
+    const startedAt = new Date().toISOString();
+    entry = {
+      traceId,
+      startedAt,
+      generationIdByMessage: new Map(),
+      toolSpanByCallId: new Map(),
+      pendingGenerationId: null,
+      agent: agent || null,
+    };
+    sessionTraces.set(sessionId, entry);
+    ingest.trace({
+      id: traceId,
+      name: agent ? `opencode.${agent}` : "opencode.session",
+      userId: userId || env.USER || env.USERNAME || undefined,
+      sessionId,
+      timestamp: startedAt,
+      tags: ["opencode", "construct", agent ? `agent:${agent}` : null].filter(Boolean),
+      metadata: metadata || undefined,
+    });
+  } else if (agent && !entry.agent) {
+    entry.agent = agent;
+  }
+  return entry;
+}
+
+// ── Hook: chat.message ──────────────────────────────────────────────────────
+export async function onChatMessage(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = input?.sessionID;
+  const entry = ensureSessionTrace(sessionId, { env, agent: input?.agent });
+  if (!entry) return;
+  const text = extractTextFromParts(output?.parts) || output?.message?.content;
+  ingest.event({
+    id: randomUUID(),
+    traceId: entry.traceId,
+    name: "user.message",
+    startTime: new Date().toISOString(),
+    input: { text, messageID: input?.messageID, variant: input?.variant },
+    metadata: {
+      agent: input?.agent,
+      model: stringifyModel(input?.model),
+    },
+  });
+}
+
+// ── Hook: chat.params ───────────────────────────────────────────────────────
+export async function onChatParams(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = input?.sessionID;
+  const entry = ensureSessionTrace(sessionId, { env, agent: input?.agent });
+  if (!entry) return;
+  const generationId = randomUUID();
+  entry.pendingGenerationId = generationId;
+  ingest.generation({
+    id: generationId,
+    traceId: entry.traceId,
+    name: `llm.${input?.agent || "chat"}`,
+    startTime: new Date().toISOString(),
+    model: stringifyModel(input?.model),
+    modelParameters: {
+      temperature: output?.temperature,
+      topP: output?.topP,
+      topK: output?.topK,
+      maxOutputTokens: output?.maxOutputTokens,
+    },
+    input: input?.message,
+    metadata: {
+      agent: input?.agent,
+      provider: input?.provider?.info?.id || input?.model?.providerID,
+    },
+  });
+}
+
+// ── Hook: tool.execute.before ───────────────────────────────────────────────
+export async function onToolBefore(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = input?.sessionID;
+  const entry = ensureSessionTrace(sessionId, { env });
+  if (!entry) return;
+  const spanId = randomUUID();
+  const startedAt = new Date().toISOString();
+  entry.toolSpanByCallId.set(input?.callID, { spanId, startedAt, tool: input?.tool });
+  ingest.span({
+    id: spanId,
+    traceId: entry.traceId,
+    name: `tool.${input?.tool}`,
+    startTime: startedAt,
+    input: redactToolArgs(input?.tool, output?.args),
+    metadata: { tool: input?.tool, callID: input?.callID },
+  });
+}
+
+// ── Hook: tool.execute.after ────────────────────────────────────────────────
+export async function onToolAfter(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const entry = sessionTraces.get(input?.sessionID);
+  const tracked = entry?.toolSpanByCallId.get(input?.callID);
+  if (!entry || !tracked) return;
+  ingest.spanUpdate({
+    id: tracked.spanId,
+    traceId: entry.traceId,
+    endTime: new Date().toISOString(),
+    output: redactToolOutput(output?.output),
+    metadata: {
+      tool: input?.tool,
+      title: output?.title,
+      ...(output?.metadata && typeof output.metadata === "object" ? output.metadata : {}),
+    },
+  });
+  entry.toolSpanByCallId.delete(input?.callID);
+}
+
+// ── Hook: permission.ask ────────────────────────────────────────────────────
+export async function onPermissionAsk(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = input?.sessionID || input?.session?.id;
+  const entry = ensureSessionTrace(sessionId, { env });
+  if (!entry) return;
+  ingest.event({
+    id: randomUUID(),
+    traceId: entry.traceId,
+    name: `permission.${output?.status || "ask"}`,
+    startTime: new Date().toISOString(),
+    input: {
+      type: input?.type,
+      title: input?.title,
+      pattern: input?.pattern,
+      tool: input?.tool,
+    },
+    metadata: { status: output?.status },
+  });
+}
+
+// ── Hook: command.execute.before ────────────────────────────────────────────
+export async function onCommandBefore(input, output, { env = process.env } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = input?.sessionID;
+  const entry = ensureSessionTrace(sessionId, { env });
+  if (!entry) return;
+  ingest.event({
+    id: randomUUID(),
+    traceId: entry.traceId,
+    name: `command.${input?.command}`,
+    startTime: new Date().toISOString(),
+    input: { command: input?.command, arguments: input?.arguments },
+  });
+}
+
+// ── Bus: event ──────────────────────────────────────────────────────────────
+export async function onBusEvent(event, { env = process.env, buildUsage } = {}) {
+  const ingest = getIngestClient(env);
+  if (!ingest.available) return;
+  const sessionId = getSessionIdFromEvent(event);
+  if (!sessionId) return;
+  const agent = getAgentFromEvent(event);
+  const entry = ensureSessionTrace(sessionId, { env, agent });
+  if (!entry) return;
+
+  switch (event.type) {
+    case "message.updated": {
+      const info = event?.properties?.info;
+      if (!info || info.role !== "assistant") return;
+      if (!info.time?.completed) return;
+      const msgId = info.id;
+      const existingGenId = entry.generationIdByMessage.get(msgId);
+      const genId = existingGenId || entry.pendingGenerationId || randomUUID();
+      entry.generationIdByMessage.set(msgId, genId);
+      entry.pendingGenerationId = null;
+
+      const usage = typeof buildUsage === "function"
+        ? buildUsage(event)
+        : sanitizeUsage(info.tokens, info.cost);
+
+      const outputText = extractTextFromParts(info.parts);
+
+      const body = {
+        id: genId,
+        traceId: entry.traceId,
+        name: `llm.${agent || "chat"}`,
+        startTime: info.time?.created ? new Date(info.time.created).toISOString() : undefined,
+        endTime: info.time?.completed ? new Date(info.time.completed).toISOString() : new Date().toISOString(),
+        model: info.modelID && info.providerID ? `${info.providerID}/${info.modelID}` : (info.modelID || undefined),
+        output: outputText || undefined,
+        usage: usage ? {
+          input: usage.input,
+          output: usage.output,
+          total: usage.total,
+          unit: usage.unit,
+          ...(usage.totalCost ? { totalCost: usage.totalCost } : {}),
+        } : undefined,
+        metadata: {
+          agent,
+          provider: info.providerID,
+          ...(info.tokens?.cache ? { cacheTokens: info.tokens.cache } : {}),
+          ...(info.cost ? { costUsd: info.cost } : {}),
+        },
+      };
+      if (existingGenId) ingest.generationUpdate(body);
+      else ingest.generation(body);
+      return;
+    }
+
+    case "message.part.updated": {
+      const part = event?.properties?.part;
+      if (!part) return;
+      if (part.type === "reasoning" && part.text) {
+        ingest.event({
+          id: randomUUID(),
+          traceId: entry.traceId,
+          name: "assistant.reasoning",
+          startTime: new Date().toISOString(),
+          output: part.text,
+        });
+      }
+      return;
+    }
+
+    case "session.error": {
+      const err = event?.error || {};
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: "session.error",
+        startTime: new Date().toISOString(),
+        level: "ERROR",
+        statusMessage: err.message || err.name || "session error",
+        metadata: { code: err.code, status: err.status, provider: err.provider },
+      });
+      return;
+    }
+
+    case "session.idle":
+    case "session.compacted": {
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: event.type,
+        startTime: new Date().toISOString(),
+      });
+      await ingest.flush();
+      return;
+    }
+
+    case "session.created":
+    case "session.updated": {
+      // Trace already created in ensureSessionTrace; record as event for timeline.
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: event.type,
+        startTime: new Date().toISOString(),
+      });
+      return;
+    }
+
+    case "file.edited":
+    case "EventFileEdited": {
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: "file.edited",
+        startTime: new Date().toISOString(),
+        input: event?.properties || {},
+      });
+      return;
+    }
+
+    case "todo.updated":
+    case "EventTodoUpdated": {
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: "todo.updated",
+        startTime: new Date().toISOString(),
+        input: event?.properties || {},
+      });
+      return;
+    }
+
+    case "command.executed":
+    case "EventCommandExecuted": {
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: "command.executed",
+        startTime: new Date().toISOString(),
+        input: event?.properties || {},
+      });
+      return;
+    }
+
+    case "permission.replied":
+    case "permission.updated":
+    case "permission.asked": {
+      ingest.event({
+        id: randomUUID(),
+        traceId: entry.traceId,
+        name: event.type,
+        startTime: new Date().toISOString(),
+        metadata: event?.properties || {},
+      });
+      return;
+    }
+
+    default:
+      return;
+  }
+}

package/lib/orchestration-policy.mjs

@@ -0,0 +1,258 @@
+/**
+ * lib/orchestration-policy.mjs — provider-agnostic routing and escalation policy.
+ */
+
+export const EXECUTION_TRACKS = {
+  immediate: 'immediate',
+  focused: 'focused',
+  orchestrated: 'orchestrated',
+};
+
+export const INTENT_CLASSES = {
+  research: 'research',
+  implementation: 'implementation',
+  investigation: 'investigation',
+  evaluation: 'evaluation',
+  fix: 'fix',
+};
+
+export const WORK_CATEGORIES = {
+  visual: 'visual',
+  deep: 'deep',
+  quick: 'quick',
+  writing: 'writing',
+  analysis: 'analysis',
+};
+
+export const TERMINAL_STATES = ['DONE', 'BLOCKED', 'NEEDS_MAIN_INPUT'];
+
+const SPECIALIST_MAP = {
+  implementation: ['cx-engineer'],
+  investigation: ['cx-debugger', 'cx-engineer'],
+  evaluation: ['cx-reviewer'],
+  fix: ['cx-debugger', 'cx-engineer'],
+  research: ['cx-researcher'],
+};
+
+function includesAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function containsAny(text, words) {
+  return words.some((word) => text.includes(word));
+}
+
+export function isProductIntelligenceRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'requirements',
+    'prd',
+    'prfaq',
+    'product brief',
+    'signal brief',
+    'customer notes',
+    'customer profile',
+    'product intelligence',
+    'backlog proposal',
+    'jira proposal',
+    'linear proposal',
+    'field notes',
+    'product spec',
+    'meta prd',
+  ]);
+}
+
+export function classifyProductManagerFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['platform', 'api', 'sdk', 'developer experience', 'devex', 'integration', 'migration', 'compatibility', 'admin', 'tenant'])) return 'platform';
+  if (containsAny(text, ['enterprise', 'procurement', 'compliance', 'security review', 'audit', 'sso', 'soc2', 'soc 2', 'rbac'])) return 'enterprise';
+  if (containsAny(text, ['ai product', 'agent', 'eval', 'evaluation loop', 'model behavior', 'prompt', 'llm', 'human review'])) return 'ai-product';
+  if (containsAny(text, ['growth', 'activation', 'conversion', 'funnel', 'packaging', 'pricing', 'gtm', 'go-to-market'])) return 'growth';
+  return 'product';
+}
+
+export function classifyArchitectFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['agent', 'rag', 'retrieval', 'embedding', 'eval loop', 'model behavior', 'tool use', 'llm'])) return 'ai-systems';
+  if (containsAny(text, ['integration', 'webhook', 'sync', 'third-party', 'oauth', 'reconciliation', 'idempotency'])) return 'integration';
+  if (containsAny(text, ['warehouse', 'schema', 'migration', 'retention', 'index', 'backfill', 'data model'])) return 'data';
+  if (containsAny(text, ['enterprise', 'sso', 'rbac', 'audit', 'data residency', 'procurement', 'tenant isolation'])) return 'enterprise';
+  if (containsAny(text, ['platform', 'api', 'sdk', 'developer experience', 'devex', 'admin', 'tenant', 'compatibility'])) return 'platform';
+  return null;
+}
+
+export function classifyQaFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['agent', 'prompt', 'model', 'eval', 'rag', 'retrieval', 'golden trace'])) return 'ai-eval';
+  if (containsAny(text, ['api', 'sdk', 'contract', 'status code', 'error body', 'openapi', 'consumer'])) return 'api-contract';
+  if (containsAny(text, ['pipeline', 'etl', 'elt', 'backfill', 'freshness', 'data quality', 'warehouse'])) return 'data-pipeline';
+  if (containsAny(text, ['ui', 'ux', 'screen', 'browser', 'playwright', 'responsive', 'keyboard', 'accessibility', 'visual'])) return 'web-ui';
+  return null;
+}
+
+export function classifySecurityFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['prompt injection', 'agent', 'rag', 'retrieval', 'embedding', 'model', 'tool scoping'])) return 'ai';
+  if (containsAny(text, ['privacy', 'pii', 'retention', 'deletion', 'consent', 'telemetry', 'trace', 'export'])) return 'privacy';
+  if (containsAny(text, ['dependency', 'package', 'supply chain', 'sbom', 'provenance', 'ci permission', 'signing'])) return 'supply-chain';
+  if (containsAny(text, ['cloud', 'iam', 'bucket', 'network policy', 'encryption', 'public access', 'drift'])) return 'cloud';
+  if (containsAny(text, ['auth', 'authorization', 'xss', 'csrf', 'ssrf', 'injection', 'input validation', 'jwt'])) return 'appsec';
+  return null;
+}
+
+export function classifyDataAnalystFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['customer signal', 'customer notes', 'evidence brief', 'product intelligence', 'field notes', 'signal brief'])) return 'product-intelligence';
+  if (containsAny(text, ['experiment', 'a/b', 'ab test', 'randomization', 'sample size', 'mde'])) return 'experiment';
+  if (containsAny(text, ['telemetry', 'trace', 'logs', 'dashboard', 'observability', 'denominator'])) return 'telemetry';
+  if (containsAny(text, ['metric', 'funnel', 'activation', 'adoption', 'retention', 'conversion', 'guardrail'])) return 'product';
+  return null;
+}
+
+export function classifyDataEngineerFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['vector', 'embedding', 'retrieval', 'hybrid search', 'semantic search', 'pgvector'])) return 'vector-retrieval';
+  if (containsAny(text, ['warehouse', 'metric layer', 'semantic layer', 'dimensional', 'partition', 'incremental model'])) return 'warehouse';
+  if (containsAny(text, ['pipeline', 'etl', 'elt', 'streaming', 'backfill', 'idempotent', 'data contract'])) return 'pipeline';
+  return null;
+}
+
+export function isDataAnalysisRequest(request = '') {
+  return Boolean(classifyDataAnalystFlavor(request));
+}
+
+export function isDataEngineeringRequest(request = '') {
+  return Boolean(classifyDataEngineerFlavor(request));
+}
+
+export function classifyRoleFlavors(request = '') {
+  return {
+    architect: classifyArchitectFlavor(request),
+    productManager: isProductIntelligenceRequest(request) ? classifyProductManagerFlavor(request) : null,
+    qa: classifyQaFlavor(request),
+    security: classifySecurityFlavor(request),
+    dataAnalyst: classifyDataAnalystFlavor(request),
+    dataEngineer: classifyDataEngineerFlavor(request),
+  };
+}
+
+export function detectRiskFlags(request = '') {
+  const text = String(request).toLowerCase();
+  return {
+    architecture: containsAny(text, ['architecture', 'interface contract', 'api contract', 'dependency', 'module boundary', 'data model', 'indexing', 'retrieval design']),
+    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization']),
+    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state']),
+    ui: containsAny(text, ['ui', 'ux', 'design system', 'screen', 'layout', 'visual', 'onboarding']) && !containsAny(text, ['requirements']),
+    docs: containsAny(text, ['docs', 'readme', 'runbook', 'adr']),
+    ai: containsAny(text, ['llm', ' agent', 'prompt', 'rag', 'model behavior', 'retrieval', 'embedding', 'vector']),
+  };
+}
+
+export function classifyIntent(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['fix', 'bug', 'regression', 'broken', 'repair'])) return INTENT_CLASSES.fix;
+  if (includesAny(text, [/debug/, /investigate/, /trace/, /root cause/, /why .* fail/])) return INTENT_CLASSES.investigation;
+  if (isProductIntelligenceRequest(text)) return INTENT_CLASSES.implementation;
+  if (includesAny(text, [/review/, /audit/, /validate/, /ready to ship/, /check/])) return INTENT_CLASSES.evaluation;
+  if (includesAny(text, [/research/, /explore/, /compare/, /what does/, /explain/, /understand/, /docs?/])) return INTENT_CLASSES.research;
+  return INTENT_CLASSES.implementation;
+}
+
+export function classifyWorkCategory(request = '', riskFlags = detectRiskFlags(request)) {
+  const text = String(request).toLowerCase();
+  if (riskFlags.ui) return WORK_CATEGORIES.visual;
+  if (riskFlags.docs || containsAny(text, ['write', 'rewrite', 'document', 'spec', 'requirements'])) return WORK_CATEGORIES.writing;
+  if (includesAny(text, [/analy[sz]e/, /measure/, /metrics/, /score/, /evaluate/])) return WORK_CATEGORIES.analysis;
+  if (riskFlags.architecture || riskFlags.ai || includesAny(text, [/plan/, /strategy/, /system/, /refactor/, /orchestr/])) return WORK_CATEGORIES.deep;
+  return WORK_CATEGORIES.quick;
+}
+
+export function determineExecutionTrack({
+  request = '',
+  fileCount = 0,
+  moduleCount = 0,
+  introducesContract = false,
+  explicitDrive = false,
+  riskFlags = detectRiskFlags(request),
+} = {}) {
+  const intent = classifyIntent(request);
+  if (explicitDrive) return EXECUTION_TRACKS.orchestrated;
+  if (intent === INTENT_CLASSES.research && fileCount <= 1 && moduleCount <= 1) return EXECUTION_TRACKS.immediate;
+  if (introducesContract || fileCount >= 3 || moduleCount >= 2) return EXECUTION_TRACKS.orchestrated;
+  if (riskFlags.architecture || riskFlags.security || riskFlags.dataIntegrity || riskFlags.ai) return EXECUTION_TRACKS.orchestrated;
+  if (fileCount <= 1 && moduleCount <= 1 && !includesAny(String(request).toLowerCase(), [/end to end/, /ship/, /full/])) return EXECUTION_TRACKS.immediate;
+  return EXECUTION_TRACKS.focused;
+}
+
+export function selectSpecialists({ request = '', intent, track, riskFlags = detectRiskFlags(request) } = {}) {
+  const text = String(request).toLowerCase();
+  const productRequest = isProductIntelligenceRequest(text);
+  const dataAnalysisRequest = isDataAnalysisRequest(text);
+  const dataEngineeringRequest = isDataEngineeringRequest(text);
+  if (track === EXECUTION_TRACKS.immediate) return [];
+  if (track === EXECUTION_TRACKS.focused) {
+    if (riskFlags.ui) return ['cx-designer'];
+    if (productRequest) return ['cx-product-manager'];
+    if (dataEngineeringRequest) return ['cx-data-engineer'];
+    if (dataAnalysisRequest) return ['cx-data-analyst'];
+    if (riskFlags.docs) return ['cx-docs-keeper'];
+    if (riskFlags.security && intent === INTENT_CLASSES.evaluation) return ['cx-security'];
+    return SPECIALIST_MAP[intent] || ['cx-engineer'];
+  }
+
+  const specialists = ['cx-architect'];
+  if (intent === INTENT_CLASSES.fix || intent === INTENT_CLASSES.investigation) specialists.push('cx-debugger');
+  if (intent === INTENT_CLASSES.research) specialists.push('cx-researcher');
+  if (riskFlags.ui) specialists.push('cx-designer');
+  if (productRequest) specialists.push('cx-product-manager');
+  if (dataAnalysisRequest) specialists.push('cx-data-analyst');
+  if (dataEngineeringRequest) specialists.push('cx-data-engineer');
+  else if (riskFlags.docs) specialists.push('cx-docs-keeper');
+  specialists.push('cx-engineer', 'cx-reviewer', 'cx-qa');
+  if (riskFlags.security || riskFlags.dataIntegrity) specialists.push('cx-security');
+  return Array.from(new Set(specialists));
+}
+
+export function requiresExecutiveApproval({
+  scopeChange = false,
+  productDecision = false,
+  riskAcceptance = false,
+  irreversibleAction = false,
+  blockedDependency = false,
+} = {}) {
+  return Boolean(scopeChange || productDecision || riskAcceptance || irreversibleAction || blockedDependency);
+}
+
+export function buildDispatchPlan({ track, intent, specialists = [] }) {
+  if (track === EXECUTION_TRACKS.immediate) return 'Plan: respond directly.';
+  if (track === EXECUTION_TRACKS.focused) return `Plan: ${specialists.join(' → ')}.`;
+
+  const phases = ['cx-architect'];
+  if (intent === INTENT_CLASSES.fix || intent === INTENT_CLASSES.investigation) phases.push('cx-debugger');
+  phases.push('cx-engineer');
+  const validators = specialists.filter((name) => ['cx-reviewer', 'cx-qa', 'cx-security'].includes(name));
+  if (validators.length) phases.push(validators.join(' + '));
+  return `Plan: ${phases.join(' → ')}.`;
+}
+
+export function routeRequest(options = {}) {
+  const intent = classifyIntent(options.request);
+  const riskFlags = detectRiskFlags(options.request);
+  const roleFlavors = classifyRoleFlavors(options.request);
+  const productFlavor = isProductIntelligenceRequest(options.request)
+    ? classifyProductManagerFlavor(options.request)
+    : null;
+  const workCategory = classifyWorkCategory(options.request, riskFlags);
+  const track = determineExecutionTrack({ ...options, riskFlags });
+  const specialists = selectSpecialists({ ...options, intent, track, riskFlags });
+  return {
+    intent,
+    workCategory,
+    track,
+    riskFlags,
+    productFlavor,
+    roleFlavors,
+    specialists,
+    dispatchPlan: buildDispatchPlan({ track, intent, specialists }),
+  };
+}