@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/orchestration/classification.mjs

@@ -0,0 +1,434 @@
+/**
+ * lib/orchestration/classification.mjs — text classifiers for orchestration
+ * routing policy: intent, work category, risk flags, execution track, role
+ * flavor overlays, doc-authoring detection, named-entity/research-shape/live-
+ * web-access signals.
+ *
+ * Extracted from lib/orchestration-policy.mjs (construct-rf26.10). Every
+ * function here is a pure classifier over request text (or over another
+ * classifier's output) — no gate evaluation (requires*) and no
+ * specialist/flow selection lives in this module. orchestration-policy.mjs
+ * re-exports these unchanged for existing callers.
+ */
+import { ownerForDoc } from './routing-tables.mjs';
+import { formatOverlayLine } from '../roles/flavor-bindings.mjs';
+import { EXECUTION_TRACKS, WORK_CATEGORIES, INTENT_CLASSES } from './policy-constants.mjs';
+
+export function includesAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+export function containsAny(text, words) {
+  return words.some((word) => text.includes(word));
+}
+
+const DOC_AUTHORING_PATTERNS = [
+  { pattern: /\b(adr|architecture decision record)s?\b/i, docType: 'adr' },
+  { pattern: /\bmeta[\s-]prd\b/i, docType: 'meta-prd' },
+  { pattern: /\bplatform prd\b/i, docType: 'prd-platform' },
+  { pattern: /\bbusiness prd\b/i, docType: 'prd-business' },
+  { pattern: /\bprd\b|\bproduct requirements? document/i, docType: 'prd' },
+  { pattern: /\bprfaq\b|\bpress release.*faq/i, docType: 'prfaq' },
+  { pattern: /\bone[\s-]pager\b/i, docType: 'one-pager' },
+  { pattern: /\bbacklog proposal/i, docType: 'backlog-proposal' },
+  { pattern: /\bcustomer profile/i, docType: 'customer-profile' },
+  { pattern: /\brfc\b|\brequest for comments?\b/i, docType: 'rfc' },
+  { pattern: /\barchitecture overview/i, docType: 'architecture-overview' },
+  { pattern: /\bsystem design/i, docType: 'system-design' },
+  { pattern: /\bresearch brief/i, docType: 'research-brief' },
+  { pattern: /\bevidence brief/i, docType: 'evidence-brief' },
+  { pattern: /\bsignal brief/i, docType: 'signal-brief' },
+  { pattern: /\bproduct intelligence report/i, docType: 'product-intelligence-report' },
+  { pattern: /\brunbook/i, docType: 'runbook' },
+  { pattern: /\bincident report/i, docType: 'incident-report' },
+  { pattern: /\bpostmortem|\bpost[\s-]mortem/i, docType: 'postmortem' },
+  { pattern: /\btest plan/i, docType: 'test-plan' },
+  { pattern: /\bqa strategy/i, docType: 'qa-strategy' },
+  { pattern: /\bthreat model/i, docType: 'threat-model' },
+  { pattern: /\bsecurity review/i, docType: 'security-review' },
+  { pattern: /\bchangelog/i, docType: 'changelog' },
+];
+
+const AUTHORING_VERBS = /\b(write|writing|draft|drafting|create|creating|author|authoring|produce|producing|compose|composing|prepare|preparing|generate|generating)\b/i;
+
+/**
+ * Resolves a document type mentioned in text without requiring an authoring verb.
+ */
+export function resolveDocTypeMention(request = '') {
+  const text = String(request);
+  for (const { pattern, docType } of DOC_AUTHORING_PATTERNS) {
+    if (pattern.test(text)) return docType;
+  }
+  return null;
+}
+
+/**
+ * Detects whether the request is asking for authorship of a typed document
+ * that has a canonical owner. Returns `{ docType, owner }` when matched,
+ * or null otherwise.
+ */
+export function detectDocAuthoringIntent(request = '') {
+  const text = String(request);
+  if (!AUTHORING_VERBS.test(text)) return null;
+  for (const { pattern, docType } of DOC_AUTHORING_PATTERNS) {
+    if (pattern.test(text)) {
+      return { docType, owner: ownerForDoc(docType) };
+    }
+  }
+  return null;
+}
+
+const PROPER_NOUN_STOPLIST = new Set([
+  'I', 'A', 'An', 'The', 'This', 'That', 'These', 'Those', 'My', 'Our', 'Your',
+  'We', 'They', 'He', 'She', 'It', 'Please', 'Thanks', 'Hi', 'Hello',
+  'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday',
+  'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August',
+  'September', 'October', 'November', 'December',
+  'Construct', 'Claude', 'GPT', 'OpenAI', 'Anthropic', 'GitHub', 'Google', 'Microsoft',
+]);
+
+/**
+ * Extracts proper-noun candidates from a request — capitalized tokens that are
+ * not common English words, day/month names, or known product/company names.
+ * Detects named entities that likely require external research.
+ */
+export function extractNamedEntities(request = '') {
+  const text = String(request);
+  const tokens = new Set();
+  // CamelCase single words (e.g. "ProjectIverson")
+  for (const match of text.matchAll(/\b[A-Z][a-z]+[A-Z][A-Za-z]+\b/g)) tokens.add(match[0]);
+  // Capitalized multi-word sequences (e.g. "Project Iverson")
+  for (const match of text.matchAll(/\b([A-Z][a-z]{2,})(?:\s+([A-Z][a-z]{2,})){1,4}\b/g)) tokens.add(match[0]);
+  // Single capitalized words not at sentence start
+  for (const match of text.matchAll(/(?<=[a-z,;:]\s)[A-Z][a-z]{3,}\b/g)) tokens.add(match[0]);
+  return Array.from(tokens).filter((token) => {
+    const head = token.split(/\s+/)[0];
+    return !PROPER_NOUN_STOPLIST.has(head);
+  });
+}
+
+// Research-shaped intent is the vocabulary of external and landscape research —
+// where the answer lives in papers, vendor docs, standards, or the market, not
+// in the local code. Grouped by shape so the matched kind rides on the gate
+// result and the decision is traceable. A false positive here is cheap (it only
+// offers the cx-researcher specialist, with no routing latency and no heavy-flow
+// coupling), so the set is tuned for recall; the precision floor is that a
+// code-walkthrough of the user's own system ("explain how X works") carries none
+// of these terms and stays answered from local context.
+const RESEARCH_SHAPE_PATTERNS = [
+  ['comparative', [/\bcompare\b/, /\bcomparison\b/, /\bcompared to\b/, /\bversus\b/, /\bhead[\s-]?to[\s-]?head\b/, /\btrade[\s-]?offs?\b/, /\bpros and cons\b/, /\balternatives\b/, /\balternative to\b/]],
+  ['selection', [/\bbest (approach(es)?|option|tool|library|framework|pattern|way to|method)\b/, /\bwhich\b.{0,40}\b(should|to)\b.{0,15}\b(use|choose|pick|adopt|go with)\b/, /\brecommend(ed|ation)?\b.{0,30}\b(tool|library|framework|approach|stack|way|practice)\b/, /\boptions for\b/]],
+  ['landscape', [/\blandscape\b/, /\bstate[\s-]of[\s-]the[\s-]art\b/, /\bsurvey of\b/, /\boverview of\b/, /\becosystem\b/, /\bprior art\b/, /\bliterature\b/, /\bexisting (solutions|approaches|tools|work)\b/, /\bwhat'?s out there\b/]],
+  ['market', [/\bmarket (research|analysis|share|size|landscape|trends?)\b/, /\bcompetitive (analysis|landscape)\b/, /\bcompetitors?\b/, /\bindustry (standard|trends?|benchmarks?)\b/, /\bpricing (comparison|models?|tiers?)\b/, /\badoption (rate|trends?)\b/]],
+  ['benchmark', [/\bbenchmarks?\b/, /\bbenchmarking\b/, /\bevaluate (options|alternatives|tools|approaches)\b/, /\bperformance comparison\b/]],
+  ['standards', [/\bbest practices?\b/, /\bindustry standard\b/, /\bconventions? for\b/, /\brecommended (way|approach|practice)\b/, /\brfc\s?\d+\b/, /\bspecification for\b/]],
+];
+
+/**
+ * Classify a request's research shape, or null when it carries none. The
+ * returned category names which kind of external research the prompt implies.
+ */
+export function classifyResearchShape(request = '') {
+  const text = String(request).toLowerCase();
+  for (const [category, patterns] of RESEARCH_SHAPE_PATTERNS) {
+    if (includesAny(text, patterns)) return category;
+  }
+  return null;
+}
+
+// Live web access is distinct from research-shape: a bare "connect to the
+// internet" or "fetch example.com" carries none of the comparative/landscape
+// vocabulary, so without this it falls to the immediate track and the
+// orchestrator — which holds no network tools — refuses instead of dispatching
+// the web-capable cx-researcher. A literal URL, an explicit online/internet
+// phrase, or a fetch/scrape verb paired with a web object is the signal.
+
+const WEB_VERB = '(?:fetch|download|open|load|read|scrape|crawl|retrieve|pull|grab|access|visit|hit|reach)';
+const WEB_OBJECT = '(?:url|link|web\\s?page|web\\s?site|site|page|online|internet|web|endpoint|api)';
+const LIVE_WEB_ACCESS_PATTERNS = [
+  /https?:\/\/\S+/i,
+  /\bwww\.[a-z0-9-]+\.[a-z]{2,}/i,
+  /\b(?:connect|connecting|connection)\s+to\s+the\s+(?:internet|web|network)\b/i,
+  /\binternet\s+(?:access|connection|connectivity)\b/i,
+  /\b(?:go|get|getting|going)\s+online\b/i,
+  /\b(?:browse|browsing|surf)\b[\s\S]{0,20}\b(?:web|internet|site|page|url)\b/i,
+  /\b(?:curl|wget|ping)\b/i,
+  /\b(?:is|are)\b[\s\S]{0,40}\b(?:online|offline|reachable|unreachable|responding)\b/i,
+  new RegExp(`\\b${WEB_VERB}\\b[\\s\\S]{0,40}\\b${WEB_OBJECT}\\b`, 'i'),
+  new RegExp(`\\b${WEB_VERB}\\b[\\s\\S]{0,40}\\b[a-z0-9-]+\\.(?:com|org|net|io|dev|ai|gov|edu|co|app|info|xyz)\\b`, 'i'),
+];
+
+/**
+ * Whether a request needs live external web/network access the orchestrator
+ * cannot perform itself (it is a read-only router with no network tools), so it
+ * must be routed to cx-researcher rather than answered immediately.
+ */
+export function requiresLiveWebAccess(request = '') {
+  const text = String(request);
+  return LIVE_WEB_ACCESS_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+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 classifyEngineerFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['llm', 'agent', 'prompt', 'eval', 'hallucination', 'rag', 'model behavior', 'model routing'])) return 'ai';
+  if (containsAny(text, ['vector', 'embedding', 'retrieval', 'warehouse', 'etl', 'elt', 'pipeline', 'streaming', 'data contract'])) return 'data';
+  if (containsAny(text, ['ci/cd', ' ci ', 'build pipeline', 'build system', 'deploy', 'docker', 'kubernetes', 'terraform', 'helm', 'release pipeline', 'platform tooling', 'developer experience'])) return 'platform';
+  return null;
+}
+
+export function isDataAnalysisRequest(request = '') {
+  return Boolean(classifyDataAnalystFlavor(request));
+}
+
+export function isDataEngineeringRequest(request = '') {
+  return Boolean(classifyDataEngineerFlavor(request));
+}
+
+// Activation detectors for specialists without a flavor classifier. Each maps
+// a request to a keyword signature; an empty match leaves the specialist
+// dormant unless an event in EVENT_OWNERSHIP fires.
+
+export function isLegalComplianceRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'legal review', 'compliance review', 'regulatory', 'gdpr', 'ccpa', 'hipaa',
+    'soc 2', 'soc2', 'data processing agreement', 'dpa', 'terms of service',
+    'license compliance', 'open-source license', 'attribution requirement',
+    'privacy policy', 'consent flow', 'data residency', 'export control',
+  ]);
+}
+
+export function isBusinessStrategyRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'go-to-market', 'gtm strategy', 'market positioning', 'competitive analysis',
+    'business case', 'value proposition', 'pricing strategy', 'market segmentation',
+    'investment thesis', 'strategic direction',
+  ]);
+}
+
+export function isOperationsPlanningRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'dependency sequencing', 'critical path', 'milestone plan',
+    'resource allocation', 'capacity planning', 'roadmap sequencing',
+    'cross-team dependency', 'multi-quarter plan', 'rollout sequencing',
+  ]);
+}
+
+export function isRdLeadRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'hypothesis', 'falsifiable', 'research question', 'experimental design',
+    'technology spike', 'feasibility study', 'proof of concept', 'r&d',
+  ]);
+}
+
+export function isExplorerRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'explore the', 'spike', 'walkthrough', 'code walk', 'scoping pass',
+    'recon', 'reconnaissance', 'survey the code', 'orient me',
+  ]);
+}
+
+export function isVisualDeliverableRequest(request = '') {
+  const text = String(request).toLowerCase();
+  return containsAny(text, [
+    'wireframe',
+    'diagram',
+    'flowchart',
+    'mermaid',
+    'sequence diagram',
+    'state diagram',
+    'er diagram',
+    'mockup',
+    'storyboard',
+    'deck',
+    'slide deck',
+    'slides',
+    'presentation',
+    'powerpoint',
+    'ppt',
+    'pptx',
+    'walkthrough video',
+    'demo video',
+  ]);
+}
+
+export function classifyRoleFlavors(request = '') {
+  const engineerFlavor = classifyEngineerFlavor(request);
+  const dataEngineerFlavor = classifyDataEngineerFlavor(request);
+  return {
+    engineer: engineerFlavor && !['ai', 'platform', 'data'].includes(engineerFlavor) ? engineerFlavor : null,
+    aiEngineer: engineerFlavor === 'ai' ? 'core' : null,
+    platformEngineer: engineerFlavor === 'platform' ? 'core' : null,
+    architect: classifyArchitectFlavor(request),
+    productManager: isProductIntelligenceRequest(request) ? classifyProductManagerFlavor(request) : null,
+    qa: classifyQaFlavor(request),
+    security: classifySecurityFlavor(request),
+    dataAnalyst: classifyDataAnalystFlavor(request),
+    dataEngineer: dataEngineerFlavor,
+    businessStrategist: isBusinessStrategyRequest(request) ? 'core' : null,
+  };
+}
+
+// One line per non-null flavor: "cx-<role>: loaded <role>.<flavor>
+// overlay". Verbose host surfaces + cx_trace span attribute; lets a
+// post-hoc reviewer see which overlays drove a given dispatch.
+
+export function formatOverlaySelection(roleFlavors) {
+  if (!roleFlavors || typeof roleFlavors !== 'object') return [];
+  const lines = [];
+  for (const [classifierKey, flavor] of Object.entries(roleFlavors)) {
+    const line = formatOverlayLine(classifierKey, flavor);
+    if (line) lines.push(line);
+  }
+  return lines;
+}
+
+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', 'terraform', 'infrastructure', 'iac', 'provisioning', 'blast radius', 'rollout', 'deployment strategy']),
+    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization', 'credential', 'oidc', 'iam', 'access token']),
+    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state', 'tfstate', 'drift']),
+    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 || isVisualDeliverableRequest(text)) 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);
+  const workCategory = classifyWorkCategory(request, riskFlags);
+  const text = String(request).toLowerCase();
+  const localWalkthrough = isExplorerRequest(request)
+    || /\b(?:explain|understand|what does|what is)\b[\s\S]{0,60}\b(?:how\b|do\b|does\b|works?\b|flow\b|path\b|layer\b|module\b|implementation\b|code\b|function\b)/i.test(text)
+    || /\bhow\b[\s\S]{0,40}\bworks?\b/i.test(text);
+  if (explicitDrive) return EXECUTION_TRACKS.orchestrated;
+  if (intent === INTENT_CLASSES.research) {
+    if (localWalkthrough && fileCount <= 1 && moduleCount <= 1) return EXECUTION_TRACKS.immediate;
+    if (fileCount <= 1 && moduleCount <= 1) return EXECUTION_TRACKS.focused;
+    return EXECUTION_TRACKS.orchestrated;
+  }
+  if (introducesContract || fileCount >= 3 || moduleCount >= 2) return EXECUTION_TRACKS.orchestrated;
+  if (riskFlags.architecture || riskFlags.security || riskFlags.dataIntegrity || riskFlags.ai) return EXECUTION_TRACKS.orchestrated;
+  if (workCategory === WORK_CATEGORIES.visual) return EXECUTION_TRACKS.focused;
+  // A keyword that names a specialist should activate that specialist even
+  // for small-scope work — otherwise the immediate-track fallback below
+  // silently drops the request to "answer directly," losing the specialty.
+  if (
+    isLegalComplianceRequest(request)
+    || isBusinessStrategyRequest(request)
+    || isOperationsPlanningRequest(request)
+    || isRdLeadRequest(request)
+    || isExplorerRequest(request)
+    || requiresLiveWebAccess(request)
+  ) {
+    return EXECUTION_TRACKS.focused;
+  }
+  if (fileCount <= 1 && moduleCount <= 1 && !includesAny(String(request).toLowerCase(), [/end to end/, /ship/, /full/])) return EXECUTION_TRACKS.immediate;
+  return EXECUTION_TRACKS.focused;
+}

package/lib/orchestration/delegation-flow.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/orchestration/delegation-flow.mjs — flow-engine delegation chain for
+ * orchestration-policy routes (ADR-0067, construct-rf26.9).
+ *
+ * Converts a resolved orchestration-policy route (lib/orchestration-policy.mjs's
+ * routeRequest()) into a deterministic, checkpointable flow: one step per
+ * specialist in route.specialists' (or route.displaySpecialists') order, each
+ * step's run() producing exactly the delegation spec — role, reason,
+ * handoffContract — that lib/orchestration/runtime.mjs's buildTasks() already
+ * computes per task. This mirrors the one-task-at-a-time granularity that path
+ * already gets right rather than inventing a new delegation shape; it is the
+ * sequencing itself (which specialist is current, and when the chain ends)
+ * that moves from freeform dispatchPlan/dispatchSummary prose into a real
+ * engine-held state machine.
+ *
+ * advanceDelegation() is the caller-facing entry point: it rebuilds the flow
+ * fresh from the route on every call — routeRequest is a pure function of its
+ * inputs, so the flow it implies is fully reproducible — and checkpoints
+ * progress under runId via lib/flows/checkpoint.mjs. A caller (an MCP tool, a
+ * CLI, a persona driving its own dispatch loop) receives exactly the current
+ * step's delegation, never the whole chain, and can resume across separate
+ * process/turn boundaries by calling again with the same runId.
+ *
+ * A route with no specialists (the immediate track, or a focused/orchestrated
+ * route that happened to resolve to none) still yields a load-valid flow: a
+ * single terminal step whose delegation is null, so building the flow never
+ * throws on an empty chain.
+ */
+
+import { defineFlow } from '../flows/define.mjs';
+import { TERMINAL, RUN_STATUS } from '../flows/constants.mjs';
+import { tickCheckpointed } from '../flows/checkpoint.mjs';
+
+const STATE_SCHEMA = {
+  type: 'object',
+  properties: {
+    currentDelegation: { type: ['object', 'null'] },
+  },
+};
+
+// Mirrors lib/orchestration/runtime.mjs's buildTasks(): the actual dispatch
+// order is route.specialists, not route.displaySpecialists (the latter is a
+// display-only fallback for an immediate-track route's contractChain/
+// teamRouting computation — it is never what gets dispatched).
+
+function resolveSpecialists(route) {
+  return route.specialists || [];
+}
+
+// Mirrors lib/orchestration/runtime.mjs's buildTasks(): the first contract
+// chain edge for a given producer is the handoff contract that specialist
+// hands off under. Recomputed here rather than imported so this module has
+// no runtime dependency beyond the route object itself.
+
+function handoffContractsByProducer(route) {
+  const byProducer = new Map();
+  for (const edge of route.contractChain || []) {
+    const producer = edge.contract?.producer;
+    if (producer && !byProducer.has(producer)) byProducer.set(producer, edge.contract.id);
+  }
+  return byProducer;
+}
+
+/**
+ * Build (not run) the flow definition implied by a route. Pure function of
+ * `route` — same route in, same flow shape out — so a caller never needs to
+ * persist the flow itself, only the runId tracking progress through it.
+ */
+export function buildDelegationFlow(route, { id } = {}) {
+  const specialists = resolveSpecialists(route);
+  const reasons = route.dispatchReasons || {};
+  const handoffByProducer = handoffContractsByProducer(route);
+  const flowId = id ?? `delegation-${route.intent ?? 'unknown'}-${route.track ?? 'unknown'}`;
+
+  if (specialists.length === 0) {
+    return defineFlow({
+      id: flowId,
+      stateSchema: STATE_SCHEMA,
+      startStep: 'none',
+      steps: {
+        none: { workerBackend: 'inline', run: () => ({ state: { currentDelegation: null } }), router: () => TERMINAL },
+      },
+    });
+  }
+
+  const names = specialists.map((_, i) => `step_${i}`);
+  const steps = {};
+  specialists.forEach((role, i) => {
+    const nextName = names[i + 1] ?? null;
+    steps[names[i]] = {
+      workerBackend: 'host',
+      run: () => ({
+        state: {
+          currentDelegation: {
+            role,
+            reason: reasons[role] || null,
+            handoffContract: handoffByProducer.get(role.replace(/^cx-/, '')) || null,
+            index: i,
+            total: specialists.length,
+          },
+        },
+      }),
+      router: () => nextName ?? TERMINAL,
+    };
+  });
+
+  return defineFlow({ id: flowId, stateSchema: STATE_SCHEMA, startStep: names[0], steps });
+}
+
+/**
+ * Advance a route's implied delegation chain by exactly one step, checkpointed
+ * under runId. First call (no checkpoint yet) starts the run and executes its
+ * first step in the same tick, so the caller always gets a real delegation
+ * back rather than an empty "not started" state. Every subsequent call with
+ * the same runId advances to the next specialist. `done: true` once the chain
+ * is exhausted; `currentDelegation` is null only for an immediate-track route
+ * that resolved to no specialists at all.
+ */
+export async function advanceDelegation(cwd, runId, route) {
+  const flow = buildDelegationFlow(route);
+  const run = await tickCheckpointed(cwd, runId, flow, {});
+  const specialists = resolveSpecialists(route);
+  return {
+    runId,
+    flowId: flow.id,
+    status: run.status,
+    done: run.status !== RUN_STATUS.RUNNING,
+    currentDelegation: run.state?.currentDelegation ?? null,
+    stepsCompleted: run.completed.size,
+    totalSteps: specialists.length,
+  };
+}