@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/orchestration/flow-selection.mjs

@@ -0,0 +1,418 @@
+/**
+ * lib/orchestration/flow-selection.mjs — specialist/flow selection for
+ * orchestration routing policy: which specialists run, in what order,
+ * parallel checks, proactive triggers, and the top-level routeRequest/
+ * routeRequestVerified/buildConstructToOrchestratorPacket entry points.
+ *
+ * Extracted from lib/orchestration-policy.mjs (construct-rf26.10). This is
+ * the module that composes classification.mjs (what kind of request) and
+ * gates.mjs (what must be true first) into a concrete dispatch plan.
+ * orchestration-policy.mjs re-exports these unchanged for existing callers.
+ */
+import { resolveContractChain } from '../specialist-contracts.mjs';
+import { verifyRoute } from '../intent-classifier.mjs';
+import { evaluateWatchConditions } from './routing-tables.mjs';
+import { resolveArtifactWorkflowContract } from '../artifact-manifest.mjs';
+import { buildResearchExecutionPolicy } from '../research-execution-policy.mjs';
+import { EXECUTION_TRACKS, INTENT_CLASSES, WORK_CATEGORIES } from './policy-constants.mjs';
+import {
+  classifyEngineerFlavor, isExplorerRequest, isProductIntelligenceRequest,
+  isDataAnalysisRequest, isDataEngineeringRequest, detectDocAuthoringIntent,
+  isLegalComplianceRequest, isBusinessStrategyRequest, isOperationsPlanningRequest,
+  isRdLeadRequest, containsAny, detectRiskFlags, classifyWorkCategory,
+  classifyIntent, classifyRoleFlavors, classifyProductManagerFlavor,
+  isVisualDeliverableRequest, determineExecutionTrack,
+} from './classification.mjs';
+import {
+  requiresExternalResearch, requiresFramingChallenge,
+  resolveArtifactReviewRequirements, teamRoutingForSpecialists,
+} from './gates.mjs';
+
+const SPECIALIST_MAP = {
+  implementation: ['cx-engineer'],
+  investigation: ['cx-debugger', 'cx-engineer'],
+  evaluation: ['cx-reviewer'],
+  fix: ['cx-debugger', 'cx-engineer'],
+  research: ['cx-researcher'],
+};
+
+const WORKFLOW_SKILL_TO_TYPE = {
+  'docs/prd-workflow': 'prd-draft',
+  'docs/adr-workflow': 'architecture-review',
+  'docs/research-workflow': 'research-synthesis',
+  'docs/evidence-ingest-workflow': 'evidence-ingest',
+};
+
+// AI/platform/data engineering are skill bundles on the single cx-engineer
+// specialist, not separate dispatch targets, so specialist selection never
+// substitutes a flavor-specific id here. The engineer flavor is still
+// detected via classifyEngineerFlavor()/classifyRoleFlavors() and drives
+// which skills/roles/*.md overlay loads onto cx-engineer — see
+// lib/roles/flavor-bindings.mjs for that binding.
+function refineEngineeringSpecialists(specialists) {
+  return specialists;
+}
+
+function suggestWorkflowType({ intent, request = '', docAuthoring } = {}) {
+  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 (intent === INTENT_CLASSES.research && !localWalkthrough) {
+    return 'research-synthesis';
+  }
+  if (docAuthoring?.docType) {
+    const contract = resolveArtifactWorkflowContract(docAuthoring.docType);
+    const workflowType = WORKFLOW_SKILL_TO_TYPE[contract?.workflowSkill];
+    if (workflowType) return workflowType;
+  }
+  return null;
+}
+
+export function selectSpecialists({ request = '', intent, track, riskFlags = detectRiskFlags(request), workCategory = classifyWorkCategory(request, riskFlags) } = {}) {
+  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 (workCategory === WORK_CATEGORIES.visual || riskFlags.ui) return ['cx-designer'];
+    if (productRequest) return ['cx-product-manager'];
+    const docAuthoring = detectDocAuthoringIntent(text);
+    if (docAuthoring?.owner) return [docAuthoring.owner];
+    if (dataEngineeringRequest) return ['cx-engineer'];
+    if (dataAnalysisRequest) return ['cx-data-analyst'];
+    if (isLegalComplianceRequest(text)) return ['cx-security'];
+    if (isBusinessStrategyRequest(text)) return ['cx-product-manager'];
+    if (isOperationsPlanningRequest(text)) return ['cx-operations'];
+    if (isRdLeadRequest(text)) return ['cx-architect'];
+    if (isExplorerRequest(text)) return ['cx-researcher'];
+    if (riskFlags.docs) return ['cx-operations'];
+    if (riskFlags.security && intent === INTENT_CLASSES.evaluation) return refineEngineeringSpecialists(['cx-security'], request);
+    return refineEngineeringSpecialists(SPECIALIST_MAP[intent] || ['cx-engineer'], request);
+  }
+
+  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');
+  const docAuthoring = detectDocAuthoringIntent(text);
+  if (docAuthoring?.owner) specialists.push(docAuthoring.owner);
+  if (workCategory === WORK_CATEGORIES.visual || 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-engineer');
+  else if (riskFlags.docs) specialists.push('cx-operations');
+  specialists.push('cx-engineer', 'cx-reviewer', 'cx-qa');
+  if (riskFlags.security || riskFlags.dataIntegrity) specialists.push('cx-security');
+  return refineEngineeringSpecialists(Array.from(new Set(specialists)), request);
+}
+
+export function augmentSpecialists(
+  specialists = [],
+  {
+    request = '',
+    docAuthoring = null,
+    externalResearch = null,
+    framingChallenge = null,
+    artifactReview = null,
+    triggers = [],
+  } = {},
+) {
+  let list = [...specialists];
+  if (docAuthoring?.owner && !list.includes(docAuthoring.owner)) {
+    list = [docAuthoring.owner, ...list];
+  }
+  if (externalResearch?.required && !list.includes('cx-researcher')) {
+    list = ['cx-researcher', ...list];
+  }
+  if (framingChallenge?.required && !list.includes('cx-reviewer')) {
+    list = ['cx-reviewer', ...list];
+  }
+  for (const reviewer of artifactReview?.requiredReviewers || []) {
+    if (!list.includes(reviewer)) list = [...list, reviewer];
+  }
+  if (isLegalComplianceRequest(request) && !list.includes('cx-security')) {
+    list = ['cx-security', ...list];
+  }
+  if (isRdLeadRequest(request) && !list.includes('cx-architect')) {
+    list = ['cx-architect', ...list];
+  }
+  if (isBusinessStrategyRequest(request) && !list.includes('cx-product-manager')) {
+    list = ['cx-product-manager', ...list];
+  }
+  for (const { specialist } of triggers) {
+    if (!list.includes(specialist)) list = [specialist, ...list];
+  }
+  return Array.from(new Set(list));
+}
+
+function enrichPolicyForProjectQuestion(request, policySpecialists = []) {
+  if (!/\b(what is this (project|repo|codebase)|what('s| is) this (project|repo|codebase)|describe this (project|repo|codebase))\b/i.test(String(request))) {
+    return policySpecialists;
+  }
+  const list = [...policySpecialists];
+  if (!list.includes('cx-researcher')) list.unshift('cx-researcher');
+  return Array.from(new Set(list));
+}
+
+/**
+ * Identify specialists that can run in parallel with implementation.
+ * Returns an array of specialist names that should execute concurrently
+ * rather than sequentially. This reduces latency for independent checks.
+ * 
+ * Parallel execution is safe when:
+ * - The specialist only reads/analyzes (doesn't mutate)
+ * - Their output doesn't depend on implementation completing first
+ * - They provide early feedback that can shape implementation
+ */
+export function identifyParallelChecks({ request = '', riskFlags = detectRiskFlags(request), workCategory = classifyWorkCategory(request, riskFlags) } = {}) {
+  const parallelChecks = [];
+  const text = String(request).toLowerCase();
+  
+  // Security review can run parallel to implementation for early threat detection
+  if (riskFlags.security || containsAny(text, ['auth', 'permission', 'secret', 'payment', 'pii'])) {
+    parallelChecks.push('cx-security');
+  }
+  
+  // Accessibility review can run parallel for UI work
+  if (workCategory === WORK_CATEGORIES.visual || riskFlags.ui || containsAny(text, ['ui', 'ux', 'interface', 'component'])) {
+    parallelChecks.push('cx-designer');
+  }
+
+  // Performance review for data-intensive operations
+  if (containsAny(text, ['performance', 'latency', 'throughput', 'scale', 'optimization'])) {
+    parallelChecks.push('cx-operations');
+  }
+
+  // Legal compliance for regulated domains — same specialist as the security
+  // check above (legal-compliance folded into cx-security), so dedupe.
+  if (isLegalComplianceRequest(request) && !parallelChecks.includes('cx-security')) {
+    parallelChecks.push('cx-security');
+  }
+
+
+  return parallelChecks;
+}
+
+// Structured request signals computed once and fed to both selectSpecialists
+// and the proactive-trigger pass. Centralises every cheap signal so specialists
+// don't each re-derive them from raw text. Returned shape is stable — additive
+// only.
+
+export function requestSignals(request = '', context = {}) {
+  const text = String(request).toLowerCase();
+  const riskFlags = detectRiskFlags(request);
+  const intent = classifyIntent(request);
+  const workCategory = classifyWorkCategory(request, riskFlags);
+
+  const ambiguityIndicators = [
+    'maybe', 'something like', 'figure out', 'somehow', 'sort of', 'kind of', 'idea', 'rough', 'tbd',
+    'we should probably', 'not sure', 'thinking about',
+  ];
+  const namedConstraintIndicators = [
+    'must not', 'cannot exceed', 'has to', 'deadline', 'budget', 'within', 'no later than',
+    'maximum', 'minimum', 'sla', 'p95', 'p99',
+  ];
+  const blastRadiusWide = [
+    'all users', 'every user', 'global', 'org-wide', 'company-wide', 'breaking change',
+    'migration', 'mass update', 'backfill', 'destructive',
+  ];
+  const blastRadiusMedium = [
+    'feature flag', 'beta cohort', 'experiment', 'rollout', 'shadow',
+  ];
+
+  const ambiguityHits = ambiguityIndicators.filter((kw) => text.includes(kw)).length;
+  const ambiguityScore = Math.min(1, ambiguityHits / 3);
+
+  let blastRadius = 'narrow';
+  if (containsAny(text, blastRadiusWide)) blastRadius = 'wide';
+  else if (containsAny(text, blastRadiusMedium)) blastRadius = 'medium';
+
+  return {
+    intent,
+    workCategory,
+    riskFlags,
+    ambiguityScore,
+    hasSuccessMetric: containsAny(text, ['success metric', 'kpi', 'target metric', 'goal metric', 'acceptance criteria']),
+    hasNamedConstraints: containsAny(text, namedConstraintIndicators),
+    blastRadius,
+    authOrPayments: containsAny(text, ['auth', 'authentication', 'authorization', 'payment', 'pii', 'personal data', 'compliance']),
+    visualDeliverable: isVisualDeliverableRequest(text),
+    namedUsers: context?.namedUsers || [],
+  };
+}
+
+// Signal-driven proactive triggers. Returns a list of { specialist, reason }
+// pairs for specialists that should engage PRE-DISPATCH based on signals —
+// separate from the keyword-only paths in selectSpecialists. The watch
+// predicates and their specialist owners are declared in
+// specialists/org (watchConditions) and evaluated by
+// orchestration/routing-tables.mjs.
+
+export function proactiveTriggers(signals) {
+  return evaluateWatchConditions(signals).map(({ specialist, reason }) => ({ specialist, reason }));
+}
+
+// Format active flavor overlays into a one-line trace, e.g.
+//   "Overlays: architect=platform (matched kubernetes, infra), engineer=ai (matched llm, agent)"
+
+export function formatOverlayTrace(roleFlavors = {}, request = '') {
+  const text = String(request).toLowerCase();
+  const active = Object.entries(roleFlavors).filter(([, flavor]) => flavor);
+  if (active.length === 0) return '';
+  const FLAVOR_KEYWORDS = {
+    architect: ['agent', 'rag', 'retrieval', 'embedding', 'integration', 'webhook', 'warehouse', 'schema', 'sso', 'rbac', 'platform', 'kubernetes', 'infra'],
+    productManager: ['platform', 'api', 'enterprise', 'ai product', 'agent', 'growth', 'activation'],
+    qa: ['agent', 'prompt', 'api', 'sdk', 'pipeline', 'etl', 'ui', 'ux', 'accessibility'],
+    security: ['prompt injection', 'privacy', 'pii', 'dependency', 'cloud', 'iam', 'auth', 'xss', 'csrf'],
+    dataAnalyst: ['experiment', 'a/b', 'telemetry', 'metric', 'funnel'],
+    dataEngineer: ['vector', 'embedding', 'warehouse', 'pipeline', 'etl', 'pgvector'],
+    engineer: ['llm', 'agent', 'rag', 'kubernetes', 'k8s', 'terraform', 'infra', 'docker', 'pipeline', 'etl', 'data model'],
+  };
+  const parts = active.map(([role, flavor]) => {
+    const kws = (FLAVOR_KEYWORDS[role] || []).filter((kw) => text.includes(kw));
+    const matched = kws.slice(0, 3).join(', ');
+    return matched ? `${role}=${flavor} (matched ${matched})` : `${role}=${flavor}`;
+  });
+  return `Overlays: ${parts.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 docAuthoring = detectDocAuthoringIntent(options.request);
+  const externalResearch = requiresExternalResearch({ request: options.request, workCategory, riskFlags });
+  const framingChallenge = requiresFramingChallenge({ request: options.request, workCategory, riskFlags, introducesContract: options.introducesContract });
+  const artifactReview = resolveArtifactReviewRequirements(docAuthoring);
+  const suggestedWorkflowType = suggestWorkflowType({ intent, request: options.request, docAuthoring });
+  const researchExecutionPolicy = intent === INTENT_CLASSES.research || externalResearch?.required
+    ? buildResearchExecutionPolicy({ request: options.request })
+    : null;
+  const signals = requestSignals(options.request, options.context);
+  const triggers = proactiveTriggers(signals);
+  const reasons = {};
+  for (const { specialist, reason } of triggers) {
+    reasons[specialist] = reason;
+  }
+
+  const augmentOpts = {
+    request: options.request,
+    docAuthoring,
+    externalResearch,
+    framingChallenge,
+    artifactReview,
+    triggers,
+  };
+
+  let specialists = augmentSpecialists(
+    selectSpecialists({ ...options, intent, track, riskFlags, workCategory }),
+    augmentOpts,
+  );
+
+  const policyTrack = track === EXECUTION_TRACKS.immediate ? EXECUTION_TRACKS.focused : track;
+  let policySpecialists = augmentSpecialists(
+    selectSpecialists({ ...options, intent, track: policyTrack, riskFlags, workCategory }),
+    augmentOpts,
+  );
+  policySpecialists = enrichPolicyForProjectQuestion(options.request, policySpecialists);
+
+  const displaySpecialists = specialists.length ? specialists : policySpecialists;
+
+  const contractChain = resolveContractChain({
+    intent,
+    workCategory,
+    track,
+    riskFlags,
+    specialists: displaySpecialists,
+    framingChallenge,
+    externalResearch,
+    docAuthoring,
+    artifactReview,
+  });
+
+  // Team-aware routing: analyze specialist-to-team mapping and identify
+  // team involvement, primary owner, required approvals, and escalation paths.
+  const teamRouting = teamRoutingForSpecialists(displaySpecialists, {
+    intent,
+    request: options.request,
+    cwd: options.cwd ?? null,
+    docAuthoring,
+  });
+
+  const route = {
+    intent,
+    workCategory,
+    track,
+    riskFlags,
+    productFlavor,
+    roleFlavors,
+    specialists,
+    policySpecialists,
+    displaySpecialists,
+    signals,
+    triggers,
+    dispatchReasons: reasons,
+    docAuthoring,
+    externalResearch,
+    framingChallenge,
+    artifactReview,
+    suggestedWorkflowType,
+    researchExecutionPolicy,
+    contractChain,
+    teamRouting,
+  };
+
+  if (process.env.CONSTRUCT_VERBOSE === '1' && triggers.length > 0) {
+    for (const { specialist, reason } of triggers) {
+      console.error(`[route] proactive: ${specialist} (${reason})`);
+    }
+  }
+
+  return route;
+}
+
+// Sync wrapper that returns the keyword route immediately and fires the
+// LLM intent verifier in the background. The verifier writes its verdict
+// to ~/.cx/intent-verifications.jsonl for offline tuning; the dispatched
+// route never waits on a model round-trip. Disable the background call
+// entirely with CONSTRUCT_INTENT_VERIFY=off — see lib/intent-classifier.mjs.
+export function routeRequestVerified(options = {}) {
+  const route = routeRequest(options);
+  return verifyRoute(route, { request: options.request, modelCaller: options.modelCaller });
+}
+
+/**
+ * Build the construct→orchestrator contract packet (specialists/org).
+ * Callers must pass this object to agent_contract — not a bare goal string.
+ */
+export function buildConstructToOrchestratorPacket(options = {}) {
+  const request = String(options.request || '');
+  const route = options.route || routeRequest({
+    request,
+    fileCount: options.fileCount ?? 0,
+    moduleCount: options.moduleCount ?? 0,
+    introducesContract: options.introducesContract ?? false,
+    explicitDrive: options.explicitDrive ?? false,
+  });
+  if (route.track === EXECUTION_TRACKS.immediate) return null;
+
+  const goal = String(options.goal || request || '').trim() || 'User-requested work';
+  const acceptanceCriteria = Array.isArray(options.acceptanceCriteria) && options.acceptanceCriteria.length
+    ? options.acceptanceCriteria
+    : ['Dispatch plan emitted with specialists in sequence', 'Acceptance criteria verified before close'];
+
+  return {
+    goal,
+    intent: route.intent,
+    workCategory: route.workCategory,
+    riskFlags: route.riskFlags || {},
+    suggestedWorkflowType: route.suggestedWorkflowType || null,
+    acceptanceCriteria,
+  };
+}

package/lib/orchestration/gates.mjs

@@ -0,0 +1,244 @@
+/**
+ * lib/orchestration/gates.mjs — gate evaluation for orchestration routing
+ * policy: research/framing/executive-approval gates, artifact review
+ * requirements, and team-aware routing (blocked-decision escalation).
+ *
+ * Extracted from lib/orchestration-policy.mjs (construct-rf26.10). Every
+ * function here answers "must this be true before work starts / who must
+ * approve" — as distinct from classification.mjs (what kind of request is
+ * this) and flow-selection.mjs (which specialists/chain run it).
+ * orchestration-policy.mjs re-exports these unchanged for existing callers.
+ */
+import { getArtifactEntry } from '../artifact-manifest.mjs';
+import { loadRegistry } from '../registry/loader.mjs';
+import { resolveActiveScope } from '../scopes/loader.mjs';
+import { scopeTeamsById, resolveIntentTeamForScope, resolveScopeTeamMeta } from '../scopes/teams.mjs';
+import { WORK_CATEGORIES, INTENT_TO_TEAM } from './policy-constants.mjs';
+import {
+  classifyWorkCategory, detectRiskFlags, requiresLiveWebAccess,
+  extractNamedEntities, classifyResearchShape, isProductIntelligenceRequest,
+  detectDocAuthoringIntent,
+} from './classification.mjs';
+
+/**
+ * Returns whether external research is required before scaffolding, with the
+ * reason. Triggered by named entities not in the project glossary, by
+ * architecture / writing / docs work, or by research-shaped intent regardless of
+ * entities.
+ */
+export function requiresExternalResearch({ request = '', workCategory, riskFlags } = {}) {
+  const entities = extractNamedEntities(request);
+  const category = workCategory ?? classifyWorkCategory(request);
+  const flags = riskFlags ?? detectRiskFlags(request);
+  if (requiresLiveWebAccess(request)) {
+    return { required: true, reason: 'web-access' };
+  }
+  if (entities.length > 0) {
+    return { required: true, reason: 'named-entities', entities };
+  }
+  if (category === WORK_CATEGORIES.writing || flags.architecture || flags.docs) {
+    return { required: true, reason: 'writing-or-architecture' };
+  }
+  // Research-shaped intent (compare, landscape, market, standards, …) fires even
+  // without a named entity, since the answer is external. Bare research intent
+  // does not: a code walkthrough ("explain how X works", "understand the
+  // retrieval path") carries none of these terms and stays answered from local
+  // context — the distinction that keeps the gate from firing on every prompt.
+  const shape = classifyResearchShape(request);
+  if (shape) {
+    return { required: true, reason: 'research-shaped', shape };
+  }
+  return { required: false };
+}
+
+/**
+ * Returns whether the request must pass a framing challenge
+ * (cx-reviewer's plan-challenge mode or cx-architect problem-reframing) before scaffolding.
+ * Fires for architecture work, documentation sets, and any research-driven
+ * artifact. Fail-closed: when in doubt, require the challenge.
+ */
+export function requiresFramingChallenge({ request = '', workCategory, riskFlags, introducesContract = false } = {}) {
+  const category = workCategory ?? classifyWorkCategory(request);
+  const flags = riskFlags ?? detectRiskFlags(request);
+  if (flags.architecture || introducesContract) return { required: true, reason: 'architecture-or-contract' };
+  if (category === WORK_CATEGORIES.writing && flags.docs) return { required: true, reason: 'documentation-set' };
+  if (isProductIntelligenceRequest(request)) return { required: true, reason: 'product-intelligence' };
+  if (detectDocAuthoringIntent(request)) return { required: true, reason: 'typed-document' };
+  return { required: false };
+}
+
+export function requiresExecutiveApproval({
+  scopeChange = false,
+  productDecision = false,
+  riskAcceptance = false,
+  irreversibleAction = false,
+  blockedDependency = false,
+} = {}) {
+  return Boolean(scopeChange || productDecision || riskAcceptance || irreversibleAction || blockedDependency);
+}
+
+export function resolveArtifactReviewRequirements(docAuthoring) {
+  if (!docAuthoring?.docType) {
+    return { requiredReviewers: [], optionalReviewers: [], releaseGate: null };
+  }
+  const entry = getArtifactEntry(docAuthoring.docType);
+  const gate = entry?.releaseGate ?? {};
+  return {
+    requiredReviewers: gate.requiredReviewers ?? [],
+    optionalReviewers: gate.optionalReviewers ?? [],
+    releaseGate: gate,
+  };
+}
+
+// Map a free-text request to the decision names that gate it. Keyed against the
+// union of every team's forbiddenDecisions so a BLOCKED status fires only when
+// the request actually asks for a decision the primary team cannot make. Ordered
+// most-specific-first (deployment-timing before deployment) so the narrow match
+// wins.
+
+const REQUESTED_DECISION_PATTERNS = [
+  [/\bsecurity[ -]?override\b|\boverride\s+(the\s+)?security\b/i, 'security-override'],
+  [/\bdeployment[ -]?timing\b|\bwhen\s+to\s+deploy\b|\bdeploy\s+(?:immediately|now)\b/i, 'deployment-timing'],
+  [/\bdeployment[ -]?readiness\b/i, 'deployment-readiness'],
+  [/\bdeploy(?:ment|ing|s)?\b|\brelease\s+to\s+prod/i, 'deployment'],
+  [/\binfra(?:structure)?[ -]?change\b|\bchange\s+(?:the\s+)?infra/i, 'infra-change'],
+  [/\bscope[ -]?change\b|\bchange\s+(?:the\s+)?scope\b|\bre-?scope\b/i, 'scope-change'],
+  [/\bproduct[ -]?scope\b/i, 'product-scope'],
+  [/\buser[ -]?research\s+method/i, 'user-research-methods'],
+  [/\buser[ -]?research\b/i, 'user-research'],
+  [/\bimplementation[ -]?approach\b/i, 'implementation-approach'],
+  [/\bimplementation[ -]?detail/i, 'implementation-details'],
+  [/\bsecurity[ -]?policy\b/i, 'security-policy'],
+  [/\bops[ -]?procedure|operational\s+procedure/i, 'ops-procedures'],
+  [/\barchitect/i, 'architecture'],
+];
+
+function detectRequestedDecisions(request = '') {
+  const text = String(request || '');
+  const found = new Set();
+  for (const [pattern, decision] of REQUESTED_DECISION_PATTERNS) {
+    if (pattern.test(text)) found.add(decision);
+  }
+  return Array.from(found);
+}
+
+/**
+ * Build team-aware routing metadata (RFC-0004 §2).
+ * Returns { primaryTeam, involvedTeams, requiredApprovals, escalationPath, blockedStatus }.
+ *
+ * The primary team is intent-driven (INTENT_TO_TEAM), falling back to the first
+ * specialist's team when the intent has no mapping. involvedTeams unions the
+ * primary team with every selected specialist's team. blockedStatus fires when
+ * the primary team's forbiddenDecisions intersect the decisions the request asks
+ * for; escalation walks the primary team's path first. Team membership and team
+ * metadata resolve from specialists/org.
+ */
+export function teamRoutingForSpecialists(specialists = [], { intent = null, request = '', cwd = null, docAuthoring = null } = {}) {
+  let registry = null;
+  try {
+    registry = loadRegistry();
+  } catch {
+    return {
+      primaryTeam: null,
+      involvedTeams: [],
+      requiredApprovals: [],
+      escalationPath: [],
+      blockedStatus: null,
+    };
+  }
+
+  const profile = cwd ? resolveActiveScope(cwd) : null;
+  const profileTeams = scopeTeamsById(profile);
+
+  const teams = new Map();
+  const involvedTeamIds = new Set();
+  const addTeam = (teamId) => {
+    if (!teamId) return;
+    involvedTeamIds.add(teamId);
+    if (teams.has(teamId)) return;
+    const profileTeam = profileTeams ? resolveScopeTeamMeta(teamId, profile) : null;
+    teams.set(teamId, profileTeam || registry.teams?.[teamId] || null);
+  };
+
+  for (const specialistId of specialists) {
+    const cxId = specialistId.startsWith('cx-') ? specialistId : `cx-${specialistId}`;
+    const specialist = registry.specialists?.[cxId];
+    if (specialist?.team) addTeam(specialist.team);
+  }
+
+  // RFC-0004 §2 step 2: intent selects the primary owning team. It always counts
+  // as involved even if no selected specialist sits on it yet.
+  const profileIntentTeam = resolveIntentTeamForScope(intent, profile);
+  const intentTeam = profileIntentTeam
+    ?? (intent && INTENT_TO_TEAM[intent] ? INTENT_TO_TEAM[intent] : null);
+  addTeam(intentTeam);
+
+  const involvedTeams = Array.from(involvedTeamIds).sort();
+  let primaryTeam = intentTeam || (involvedTeams.length > 0 ? involvedTeams[0] : null);
+
+  if (docAuthoring?.owner) {
+    const cxId = docAuthoring.owner.startsWith('cx-') ? docAuthoring.owner : `cx-${docAuthoring.owner}`;
+    const ownerTeam = registry.specialists?.[cxId]?.team;
+    if (ownerTeam) {
+      addTeam(ownerTeam);
+      primaryTeam = ownerTeam;
+    }
+  }
+
+  // Collect required approvals from involved teams' decision rights.
+  const requiredApprovals = new Set();
+  for (const teamId of involvedTeamIds) {
+    const team = teams.get(teamId);
+    if (team?.decisionRights) {
+      for (const decision of team.decisionRights) requiredApprovals.add(decision);
+    }
+  }
+
+  // RFC-0004 §2 step 5: BLOCKED when the primary team forbids a decision the
+  // request actually asks for. Escalate via that team's path.
+  let blockedStatus = null;
+  const primaryTeamObj = primaryTeam ? (teams.get(primaryTeam) || registry.teams?.[primaryTeam]) : null;
+  if (Array.isArray(primaryTeamObj?.forbiddenDecisions)) {
+    const blocked = detectRequestedDecisions(request)
+      .filter((decision) => primaryTeamObj.forbiddenDecisions.includes(decision));
+    if (blocked.length > 0) {
+      blockedStatus = {
+        team: primaryTeam,
+        forbiddenDecisions: blocked,
+        escalationPath: primaryTeamObj.escalationPath || [],
+      };
+    }
+  }
+
+  // Concatenate escalation paths, primary team first, de-duplicated.
+  const escalationPath = [];
+  const seen = new Set();
+  const orderedTeams = primaryTeam
+    ? [primaryTeam, ...involvedTeams.filter((t) => t !== primaryTeam)]
+    : involvedTeams;
+  for (const teamId of orderedTeams) {
+    const team = teams.get(teamId) || registry.teams?.[teamId];
+    if (Array.isArray(team?.escalationPath)) {
+      for (const role of team.escalationPath) {
+        if (!seen.has(role)) {
+          escalationPath.push(role);
+          seen.add(role);
+        }
+      }
+    }
+  }
+
+  const squadId = primaryTeamObj?.kind === 'squad' ? primaryTeam : null;
+  const groupId = primaryTeamObj?.kind === 'group' ? primaryTeam : (primaryTeamObj?.groupId ?? null);
+
+  return {
+    primaryTeam,
+    squadId,
+    groupId,
+    collaborators: primaryTeamObj?.collaborators || [],
+    involvedTeams,
+    requiredApprovals: Array.from(requiredApprovals).sort(),
+    escalationPath,
+    blockedStatus,
+  };
+}