@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/orchestration-policy.mjs

@@ -6,19 +6,24 @@
  *   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 specialists/contracts.json and loaded via
- * lib/specialist-contracts.mjs. That file is the source of truth for
- * producer→consumer typed handoffs.
+ * Agent-to-agent contracts are declared in specialists/org
+ * (registry.contracts) and resolved via lib/specialist-contracts.mjs. The
+ * unified registry is the source of truth for producer→consumer typed handoffs.
  *
  * Event ownership, doc-artifact ownership, and watch-condition routing live
- * declaratively on specialist entries in specialists/registry.json and are
+ * declaratively on specialist entries in specialists/org and are
  * resolved by lib/orchestration/routing-tables.mjs. Hardcoded maps here
  * would create a second source of truth.
  */
 import { resolveContractChain } from './specialist-contracts.mjs';
 import { verifyRoute } from './intent-classifier.mjs';
 import { ownerForEvent, ownerForDoc, evaluateWatchConditions, knownDocTypes } from './orchestration/routing-tables.mjs';
-import { getArtifactEntry } from './artifact-manifest.mjs';
+import { getArtifactEntry, resolveArtifactWorkflowContract } from './artifact-manifest.mjs';
+import { loadRegistry } from './registry/loader.mjs';
+import { buildResearchExecutionPolicy } from './research-execution-policy.mjs';
+import { resolveActiveScope } from './scopes/loader.mjs';
+import { scopeTeamsById, resolveIntentTeamForScope, resolveScopeTeamMeta } from './scopes/teams.mjs';
+import { formatOverlayLine } from './roles/flavor-bindings.mjs';
 
 export const EXECUTION_TRACKS = {
   immediate: 'immediate',
@@ -34,6 +39,20 @@ export const INTENT_CLASSES = {
   fix: 'fix',
 };
 
+// RFC-0004 §2: each intent class maps to the team that naturally owns that work.
+// The primary team drives ownership in teamRouting; specialist selection stays
+// flavor-driven. Domain refinements the RFC notes (investigation/fix can fall to
+// operations-group, research to product-group) layer on as the decision matrix
+// grows — the base mapping is deterministic so routing is testable.
+
+export const INTENT_TO_TEAM = Object.freeze({
+  research: 'strategy-team',
+  implementation: 'engineering-team',
+  investigation: 'engineering-team',
+  evaluation: 'quality-team',
+  fix: 'engineering-team',
+});
+
 export const WORK_CATEGORIES = {
   visual: 'visual',
   deep: 'deep',
@@ -44,7 +63,7 @@ export const WORK_CATEGORIES = {
 
 export const TERMINAL_STATES = ['DONE', 'BLOCKED', 'NEEDS_MAIN_INPUT'];
 
-// Event and doc-artifact ownership are resolved from specialists/registry.json
+// Event and doc-artifact ownership are resolved from specialists/org
 // via routing-tables.mjs. Re-exported here so callers that historically
 // imported from this module keep working.
 
@@ -77,7 +96,18 @@ const DOC_AUTHORING_PATTERNS = [
   { pattern: /\bchangelog/i, docType: 'changelog' },
 ];
 
-const AUTHORING_VERBS = /\b(write|writing|draft|drafting|create|creating|author|authoring|produce|producing|compose|composing|prepare|preparing)\b/i;
+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
@@ -205,6 +235,13 @@ const SPECIALIST_MAP = {
   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',
+};
+
 function includesAny(text, patterns) {
   return patterns.some((pattern) => pattern.test(text));
 }
@@ -292,7 +329,7 @@ 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', 'build', 'deploy', 'docker', 'kubernetes', 'terraform', 'helm', 'release pipeline', 'platform tooling', 'developer experience'])) return 'platform';
+  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;
 }
 
@@ -377,28 +414,32 @@ export function isVisualDeliverableRequest(request = '') {
 }
 
 export function classifyRoleFlavors(request = '') {
+  const engineerFlavor = classifyEngineerFlavor(request);
+  const dataEngineerFlavor = classifyDataEngineerFlavor(request);
   return {
-    engineer: classifyEngineerFlavor(request),
+    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: classifyDataEngineerFlavor(request),
+    dataEngineer: dataEngineerFlavor,
+    businessStrategist: isBusinessStrategyRequest(request) ? 'core' : null,
   };
 }
 
 // One line per non-null flavor: "cx-<role>: loaded <role>.<flavor>
-// overlay". Verbose chat surface + cx_trace span attribute; lets a
+// 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 [role, flavor] of Object.entries(roleFlavors)) {
-    if (!flavor) continue;
-    const specialist = `cx-${role.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
-    lines.push(`${specialist}: loaded ${role}.${flavor} overlay`);
+  for (const [classifierKey, flavor] of Object.entries(roleFlavors)) {
+    const line = formatOverlayLine(classifierKey, flavor);
+    if (line) lines.push(line);
   }
   return lines;
 }
@@ -444,8 +485,16 @@ export function determineExecutionTrack({
 } = {}) {
   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 && fileCount <= 1 && moduleCount <= 1) return EXECUTION_TRACKS.immediate;
+  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;
@@ -465,6 +514,36 @@ export function determineExecutionTrack({
   return EXECUTION_TRACKS.focused;
 }
 
+function refineEngineeringSpecialists(specialists, request = '') {
+  const engineerFlavor = classifyEngineerFlavor(request);
+  if (!engineerFlavor || !['ai', 'platform', 'data'].includes(engineerFlavor)) return specialists;
+  const replacement = {
+    ai: 'cx-ai-engineer',
+    platform: 'cx-platform-engineer',
+    data: 'cx-data-engineer',
+  }[engineerFlavor];
+  const set = new Set(specialists);
+  set.delete('cx-engineer');
+  set.add(replacement);
+  return [...set];
+}
+
+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);
@@ -474,6 +553,8 @@ export function selectSpecialists({ request = '', intent, track, riskFlags = det
   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-data-engineer'];
     if (dataAnalysisRequest) return ['cx-data-analyst'];
     if (isLegalComplianceRequest(text)) return ['cx-legal-compliance'];
@@ -482,13 +563,15 @@ export function selectSpecialists({ request = '', intent, track, riskFlags = det
     if (isRdLeadRequest(text)) return ['cx-rd-lead'];
     if (isExplorerRequest(text)) return ['cx-explorer'];
     if (riskFlags.docs) return ['cx-docs-keeper'];
-    if (riskFlags.security && intent === INTENT_CLASSES.evaluation) return ['cx-security'];
-    return SPECIALIST_MAP[intent] || ['cx-engineer'];
+    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');
@@ -496,7 +579,56 @@ export function selectSpecialists({ request = '', intent, track, riskFlags = det
   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));
+  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-devil-advocate')) {
+    list = ['cx-devil-advocate', ...list];
+  }
+  for (const reviewer of artifactReview?.requiredReviewers || []) {
+    if (!list.includes(reviewer)) list = [...list, reviewer];
+  }
+  if (isLegalComplianceRequest(request) && !list.includes('cx-legal-compliance')) {
+    list = ['cx-legal-compliance', ...list];
+  }
+  if (isRdLeadRequest(request) && !list.includes('cx-rd-lead')) {
+    list = ['cx-rd-lead', ...list];
+  }
+  if (isBusinessStrategyRequest(request) && !list.includes('cx-business-strategist')) {
+    list = ['cx-business-strategist', ...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-explorer')) list.unshift('cx-explorer');
+  if (!list.includes('cx-researcher')) list.splice(list.indexOf('cx-explorer') + 1, 0, 'cx-researcher');
+  return Array.from(new Set(list));
 }
 
 /**
@@ -598,7 +730,7 @@ export function requestSignals(request = '', context = {}) {
 // 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/registry.json (watchConditions) and evaluated by
+// specialists/org (watchConditions) and evaluated by
 // orchestration/routing-tables.mjs.
 
 export function proactiveTriggers(signals) {
@@ -667,6 +799,159 @@ function resolveArtifactReviewRequirements(docAuthoring) {
   };
 }
 
+// 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,
+  };
+}
+
 export function routeRequest(options = {}) {
   const intent = classifyIntent(options.request);
   const riskFlags = detectRiskFlags(options.request);
@@ -676,67 +961,65 @@ export function routeRequest(options = {}) {
     : null;
   const workCategory = classifyWorkCategory(options.request, riskFlags);
   const track = determineExecutionTrack({ ...options, riskFlags });
-  let specialists = selectSpecialists({ ...options, intent, track, riskFlags, workCategory });
   const docAuthoring = detectDocAuthoringIntent(options.request);
   const externalResearch = requiresExternalResearch({ request: options.request, workCategory, riskFlags });
   const framingChallenge = requiresFramingChallenge({ request: options.request, workCategory, riskFlags, introducesContract: options.introducesContract });
-
-  // Doc ownership: the owning specialist authors; orchestrator routes.
-  if (docAuthoring?.owner && !specialists.includes(docAuthoring.owner)) {
-    specialists = [docAuthoring.owner, ...specialists];
-  }
-  // External research must precede authoring.
-  if (externalResearch.required && !specialists.includes('cx-researcher')) {
-    specialists = ['cx-researcher', ...specialists];
-  }
-  // Framing challenge must precede scaffolding.
-  if (framingChallenge.required && !specialists.includes('cx-devil-advocate')) {
-    specialists = ['cx-devil-advocate', ...specialists];
-  }
-
   const artifactReview = resolveArtifactReviewRequirements(docAuthoring);
-  for (const reviewer of artifactReview.requiredReviewers) {
-    if (!specialists.includes(reviewer)) specialists = [...specialists, reviewer];
-  }
-  // Pre-dispatch specialists that surface concerns before architecture locks in.
-  // Order matters: business framing → R&D validation → legal/compliance review,
-  // each prepended so it runs earliest in the chain.
-  if (isLegalComplianceRequest(options.request) && !specialists.includes('cx-legal-compliance')) {
-    specialists = ['cx-legal-compliance', ...specialists];
-  }
-  if (isRdLeadRequest(options.request) && !specialists.includes('cx-rd-lead')) {
-    specialists = ['cx-rd-lead', ...specialists];
-  }
-  if (isBusinessStrategyRequest(options.request) && !specialists.includes('cx-business-strategist')) {
-    specialists = ['cx-business-strategist', ...specialists];
-  }
-
-  // Signal-driven proactive triggers — surfaces specialists whose engagement
-  // hinges on structured signals rather than literal keyword matches. The
-  // routing list is union'd with the keyword paths so neither dimension
-  // drops a legitimate dispatch.
-
+  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) {
-    if (!specialists.includes(specialist)) specialists = [specialist, ...specialists];
     reasons[specialist] = reason;
   }
-  specialists = Array.from(new Set(specialists));
+
+  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,
+    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,
@@ -745,6 +1028,8 @@ export function routeRequest(options = {}) {
     productFlavor,
     roleFlavors,
     specialists,
+    policySpecialists,
+    displaySpecialists,
     signals,
     triggers,
     dispatchReasons: reasons,
@@ -752,9 +1037,12 @@ export function routeRequest(options = {}) {
     externalResearch,
     framingChallenge,
     artifactReview,
+    suggestedWorkflowType,
+    researchExecutionPolicy,
     contractChain,
-    dispatchPlan: buildDispatchPlan({ track, intent, specialists }),
-    dispatchSummary: buildDispatchSummary({ specialists, reasons }),
+    teamRouting,
+    dispatchPlan: buildDispatchPlan({ track, intent, specialists: displaySpecialists }),
+    dispatchSummary: buildDispatchSummary({ specialists: displaySpecialists, reasons }),
   };
 
   if (process.env.CONSTRUCT_VERBOSE === '1' && triggers.length > 0) {
@@ -777,7 +1065,7 @@ export function routeRequestVerified(options = {}) {
 }
 
 /**
- * Build the construct→orchestrator contract packet (specialists/contracts.json).
+ * 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 = {}) {
@@ -801,6 +1089,7 @@ export function buildConstructToOrchestratorPacket(options = {}) {
     intent: route.intent,
     workCategory: route.workCategory,
     riskFlags: route.riskFlags || {},
+    suggestedWorkflowType: route.suggestedWorkflowType || null,
     acceptanceCriteria,
   };
 }

package/lib/overrides/resolver.mjs

@@ -1,7 +1,6 @@
 /**
  * lib/overrides/resolver.mjs — single override + backup helper for every
- * user-customizable Construct primitive (personas, skills, rules,
- * contracts, role manifests).
+ * user-customizable Construct primitive (personas, agents, skills, rules).
  *
  * Convention:
  *   - Original lives in the install (`personas/<n>.md`, `skills/.../<n>.md`, …)
@@ -32,8 +31,6 @@ export const SUPPORTED_CATEGORIES = Object.freeze([
   'agents',
   'skills',
   'rules',
-  'contracts',
-  'role-manifests',
 ]);
 
 const CATEGORY_RULES = {
@@ -41,8 +38,6 @@ const CATEGORY_RULES = {
   agents: { originalDir: 'specialists/prompts', defaultExt: '.md' },
   skills: { originalDir: 'skills', defaultExt: '.md' },
   rules: { originalDir: 'rules', defaultExt: '.md' },
-  contracts: { originalDir: 'specialists', defaultExt: '.json', singleFile: 'contracts.json' },
-  'role-manifests': { originalDir: 'specialists', defaultExt: '.json', singleFile: 'role-manifests.json' },
 };
 
 function categoryRule(category) {
@@ -69,18 +64,12 @@ function ensureCxIgnore(projectRoot) {
 
 function originalPath(projectRoot, category, name) {
   const rule = categoryRule(category);
-  if (rule.singleFile) {
-    return path.join(projectRoot, rule.originalDir, rule.singleFile);
-  }
   const ext = name.includes('.') ? '' : rule.defaultExt;
   return path.join(projectRoot, rule.originalDir, `${name}${ext}`);
 }
 
 function overridePath(projectRoot, category, name) {
   const rule = categoryRule(category);
-  if (rule.singleFile) {
-    return path.join(projectRoot, '.cx', category, rule.singleFile);
-  }
   const ext = name.includes('.') ? '' : rule.defaultExt;
   return path.join(projectRoot, '.cx', category, `${name}${ext}`);
 }