sdd-agent-platform 0.4.2 → 0.5.1

package/node_modules/@sdd-agent-platform/core/src/router/route-sdd-task.ts

@@ -1,3 +1,3 @@
-export * from './runtime-inspection.js';
-export * from './runtime-validation.js';
+export * from './runtime-inspection.js';
+export * from './runtime-validation.js';
 export * from './routing.js';

package/node_modules/@sdd-agent-platform/core/src/router/routing-rules.ts

@@ -1,73 +1,73 @@
-import type { SddTask } from '../sdd-docs/task-parser.js';
-import type { AgentRuntimeRoutingRule } from './agent-runtime.js';
-import type { AgentSkillRuntimeRegistry } from './runtime-registry.js';
-
-export function matchRoutingRules(task: SddTask, registry: AgentSkillRuntimeRegistry): AgentRuntimeRoutingRule[] {
-  return registry.routingRules.filter((rule) => taskMatchesRoutingRule(task, rule));
-}
-
-function taskMatchesRoutingRule(task: SddTask, rule: AgentRuntimeRoutingRule): boolean {
-  const text = taskSearchText(task);
-  const keywordMatched = rule.when.keywords.some((keyword) => text.includes(keyword.toLowerCase()));
-  const fileMatched = rule.when.affectedFileGlobs.some((glob) => task.affectedFiles.some((filePath) => globMatchesPath(glob, filePath)));
-  return keywordMatched || fileMatched;
-}
-
-function taskSearchText(task: SddTask): string {
-  const metadataValues: string[] = [];
-  for (const value of Object.values(task.rawMetadata)) {
-    if (Array.isArray(value)) {
-      metadataValues.push(...value);
-    } else {
-      metadataValues.push(value);
-    }
-  }
-  return [
-    task.id,
-    task.title ?? '',
-    task.boundary ?? '',
-    task.implementationNotes ?? '',
-    ...task.risk,
-    ...task.validation,
-    ...task.acceptance,
-    ...task.acceptanceRefs,
-    ...task.planRefs,
-    ...task.fileOwnership,
-    ...task.agentFit,
-    ...task.allowedAgents,
-    ...task.requiredArtifacts,
-    ...metadataValues
-  ].join('\n').toLowerCase();
-}
-
-function globMatchesPath(glob: string, filePath: string): boolean {
-  return new RegExp(globToRegExpPattern(glob.replace(/\\/g, '/'))).test(filePath.replace(/\\/g, '/'));
-}
-
-function globToRegExpPattern(glob: string): string {
-  let pattern = '^';
-  for (let index = 0; index < glob.length; index += 1) {
-    const char = glob[index];
-    const next = glob[index + 1];
-    if (char === '*' && next === '*') {
-      if (glob[index + 2] === '/') {
-        pattern += '(?:.*/)?';
-        index += 2;
-      } else {
-        pattern += '.*';
-        index += 1;
-      }
-      continue;
-    }
-    if (char === '*') {
-      pattern += '[^/]*';
-      continue;
-    }
-    if (char === '?') {
-      pattern += '[^/]';
-      continue;
-    }
-    pattern += /[.+^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
-  }
-  return `${pattern}$`;
-}
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import type { AgentRuntimeRoutingRule } from './agent-runtime.js';
+import type { AgentSkillRuntimeRegistry } from './runtime-registry.js';
+
+export function matchRoutingRules(task: SddTask, registry: AgentSkillRuntimeRegistry): AgentRuntimeRoutingRule[] {
+  return registry.routingRules.filter((rule) => taskMatchesRoutingRule(task, rule));
+}
+
+function taskMatchesRoutingRule(task: SddTask, rule: AgentRuntimeRoutingRule): boolean {
+  const text = taskSearchText(task);
+  const keywordMatched = rule.when.keywords.some((keyword) => text.includes(keyword.toLowerCase()));
+  const fileMatched = rule.when.affectedFileGlobs.some((glob) => task.affectedFiles.some((filePath) => globMatchesPath(glob, filePath)));
+  return keywordMatched || fileMatched;
+}
+
+function taskSearchText(task: SddTask): string {
+  const metadataValues: string[] = [];
+  for (const value of Object.values(task.rawMetadata)) {
+    if (Array.isArray(value)) {
+      metadataValues.push(...value);
+    } else {
+      metadataValues.push(value);
+    }
+  }
+  return [
+    task.id,
+    task.title ?? '',
+    task.boundary ?? '',
+    task.implementationNotes ?? '',
+    ...task.risk,
+    ...task.validation,
+    ...task.acceptance,
+    ...task.acceptanceRefs,
+    ...task.planRefs,
+    ...task.fileOwnership,
+    ...task.agentFit,
+    ...task.allowedAgents,
+    ...task.requiredArtifacts,
+    ...metadataValues
+  ].join('\n').toLowerCase();
+}
+
+function globMatchesPath(glob: string, filePath: string): boolean {
+  return new RegExp(globToRegExpPattern(glob.replace(/\\/g, '/'))).test(filePath.replace(/\\/g, '/'));
+}
+
+function globToRegExpPattern(glob: string): string {
+  let pattern = '^';
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    const next = glob[index + 1];
+    if (char === '*' && next === '*') {
+      if (glob[index + 2] === '/') {
+        pattern += '(?:.*/)?';
+        index += 2;
+      } else {
+        pattern += '.*';
+        index += 1;
+      }
+      continue;
+    }
+    if (char === '*') {
+      pattern += '[^/]*';
+      continue;
+    }
+    if (char === '?') {
+      pattern += '[^/]';
+      continue;
+    }
+    pattern += /[.+^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+  }
+  return `${pattern}$`;
+}

package/node_modules/@sdd-agent-platform/core/src/router/routing.ts

@@ -1,224 +1,190 @@
-import {
-  AGENT_ROUTER_CONTRACT_VERSION,
-  ROUTE_CACHE_CONTRACT_VERSION
-} from '../contracts.js';
-import { parseSddBranch } from '../sdd-docs/task-parser.js';
-import { resolveSddContext } from '../sdd-docs/context.js';
-import { inspectSddTask } from '../sdd-docs/task-inspection.js';
-import { readRouteCache, routeCacheKey, runtimeProfileSpan, writeRouteCache } from './route-cache.js';
-import type { RuntimeProfileSpan, TeamModeActivation } from './route-cache.js';
-import { buildAgentSkillRuntimeRegistry } from './runtime-registry.js';
-import { buildTeamModePolicy, resolveTeamModeActivation } from './team-mode.js';
-import { matchRoutingRules } from './routing-rules.js';
-import { chooseRecommendedProfile, deriveAllowedProfiles, toAgentProfileId } from './profile-resolution.js';
-import { adapterMappingForProfile, buildAgentCapabilityRouteDecision, buildRejectedProfiles, buildToolPermissionSpec, modelPolicyForProfile, quarantineWarningsForSources, routeCategory, routeRegistrySources, selectRequiredSkillCapabilities } from './route-projection.js';
-import { lifecycleAutonomyCeilingFromDecision, resolveStageLocalLifecycleRiskDecision } from '../orchestration/runtime.js';
-import { taskAutonomyCeiling } from './risk-policy.js';
-import { evaluateTaskWorkflowGate } from '../risk.js';
-import { bindStageRouteForModel, recordStageRouteBindingProjection, type StageRouteBinding } from './stage-route-binding.js';
-import { nextDependencyTaskId, resolveTaskDependencyReadiness } from '../workflow-state/dependencies.js';
-import { selectLatestEligibleRunsByTask, type LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
-import { readAllRunStates } from '../run-state/run-state.js';
-import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
-import { inspectAgentCapabilityCatalog } from '../registries/agent-capability-catalog.js';
-import type {
-  AgentRouterDecision,
-  TeamModePolicy
-} from './agent-runtime.js';
-
-
-
-export async function inspectTeamModePolicy(projectRoot: string, options: { taskId?: string; branch?: string; enabled?: boolean; teamModeActivation?: TeamModeActivation } = {}): Promise<TeamModePolicy> {
-  const registry = await buildAgentSkillRuntimeRegistry(projectRoot);
-  const activation = resolveTeamModeActivation({ teamModeEnabled: options.enabled, teamModeActivation: options.teamModeActivation }, options.taskId ? 'auto' : 'off');
-  if (!options.taskId) {
-    return buildTeamModePolicy({ activation });
-  }
-  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
-  const model = await parseSddBranch(projectRoot, branch);
-  const inspected = inspectSddTask(model, options.taskId);
-  const task = inspected.task;
-  const blockingGap = inspected.gaps.find((gap) => gap.severity === 'blocking');
-  const matchedRules = task && !blockingGap ? matchRoutingRules(task, registry) : [];
-  const allowedProfiles = task && !blockingGap ? deriveAllowedProfiles(task, registry, matchedRules).profiles : [];
-  const category = task ? routeCategory(task, blockingGap, allowedProfiles, matchedRules) : 'blocked';
-  const autonomyCeiling = task ? taskAutonomyCeiling(task) : 'research_before_implementation';
-  return buildTeamModePolicy({ activation, task, category, risk: task?.risk ?? [], autonomyCeiling, blockedReason: blockingGap?.message ?? null });
-}
-
-export async function routeSddTask(projectRoot: string, options: { taskId: string; branch?: string; agent?: string; teamModeEnabled?: boolean; teamModeActivation?: TeamModeActivation; profile?: boolean; cache?: boolean; approved?: boolean } = { taskId: '' }): Promise<AgentRouterDecision> {
-  const profileSpans: RuntimeProfileSpan[] = [];
-  const routeStart = Date.now();
-  const routeStartedAt = new Date(routeStart).toISOString();
-  const registry = await buildAgentSkillRuntimeRegistry(projectRoot);
-  const capabilityCatalog = await inspectAgentCapabilityCatalog(projectRoot);
-  profileSpans.push(runtimeProfileSpan('agent_runtime_registry', routeStart));
-  const branchStart = Date.now();
-  const context = await resolveSddContext(projectRoot, { branch: options.branch, branchSource: options.branch ? 'cli_option' : undefined });
-  const branch = context.partition;
-  const model = await parseSddBranch(projectRoot, branch);
-  const binding = await bindStageRouteForModel(projectRoot, { branch, model, entry: 'sdd:do', userText: options.taskId });
-  await recordStageRouteBindingProjection(projectRoot, binding);
-  const routedTaskId = binding.status === 'bound' && binding.targetId ? binding.targetId : options.taskId;
-  const states = await readAllRunStates(projectRoot);
-  const runtimeByTask = latestRuntimeTaskStates(selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch }), states);
-  profileSpans.push(runtimeProfileSpan('document_parse', branchStart));
-  const cacheKey = routeCacheKey({ taskId: routedTaskId, branch, agent: options.agent ?? null, teamModeActivation: resolveTeamModeActivation(options, 'auto'), approved: options.approved, documents: model.documents });
-  const cachedDecision = options.cache ? await readRouteCache<AgentRouterDecision>(projectRoot, cacheKey) : null;
-  if (cachedDecision) {
-    return {
-      ...cachedDecision,
-      taskId: routedTaskId,
-      stageRouteBinding: binding,
-      cache: { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'hit', source: 'content_addressed_derived_route', authoritative: false },
-      profile: options.profile ? [...(cachedDecision.profile ?? []), runtimeProfileSpan('route_total', routeStart, routeStartedAt)] : undefined
-    };
-  }
-  const computeStart = Date.now();
-  const inspected = inspectSddTask(model, routedTaskId);
-  const task = inspected.task;
-  const blockingGap = inspected.gaps.find((gap) => gap.severity === 'blocking');
-  const matchedRules = task && !blockingGap ? matchRoutingRules(task, registry) : [];
-  const profileSelection = task && !blockingGap ? deriveAllowedProfiles(task, registry, matchedRules) : { profiles: [], resolvedAliases: [] };
-  const delegatedProfile = task && !blockingGap && options.agent ? toAgentProfileId(options.agent, registry) : null;
-  const allowedProfiles = delegatedProfile && !profileSelection.profiles.includes(delegatedProfile) ? [...profileSelection.profiles, delegatedProfile] : profileSelection.profiles;
-  const lifecycle = task && binding.status === 'bound' ? await resolveStageLocalLifecycleRiskDecision(projectRoot, model, { branch }) : null;
-  const riskDecision = lifecycle?.decision ?? null;
-  const gateRiskDecision = lifecycle && lifecycle.status !== 'fresh' ? lifecycle.decision : null;
-  const workflowGate = evaluateTaskWorkflowGate({ task, taskId: routedTaskId, riskDecision: gateRiskDecision, approved: options.approved });
-  const lifecycleBlockedReason = lifecycle && lifecycle.status !== 'fresh'
-    ? lifecycle.reasons[0] ?? workflowGate.primaryReason
-    : workflowGate.blocksRoute
-      ? workflowGate.primaryReason
-      : null;
-  const bindingBlockedReason = binding.status === 'bound' ? null : binding.reasons[0] ?? 'Stage route binding did not resolve to an executable target.';
-  const dependencyReadiness = task ? resolveTaskDependencyReadiness(model, routedTaskId, { runtimeByTask }) : null;
-  const dependencyBlockedReason = dependencyReadiness?.blockingReasons[0] ?? null;
-  const dependencyTaskId = task ? nextDependencyTaskId(model, routedTaskId, { runtimeByTask }) : null;
-  const taskRecommendedProfile = task && !blockingGap && !dependencyBlockedReason && !lifecycleBlockedReason ? chooseRecommendedProfile(task, allowedProfiles, registry, matchedRules) : null;
-  const recommendedProfile = dependencyBlockedReason || lifecycleBlockedReason ? null : delegatedProfile ?? taskRecommendedProfile;
-  const category = task ? routeCategory(task, blockingGap, allowedProfiles, matchedRules) : 'blocked';
-  const autonomyCeiling = gateRiskDecision ? lifecycleAutonomyCeilingFromDecision(gateRiskDecision) : task ? taskAutonomyCeiling(task) : 'research_before_implementation';
-  const requiredCapabilities = task && recommendedProfile ? selectRequiredSkillCapabilities(task, recommendedProfile, registry, matchedRules) : [];
-  const sourceCapability = requiredCapabilities[0] ?? null;
-  const sourceCapabilityContract = sourceCapability ? registry.skillCapabilities.find((capability) => capability.id === sourceCapability) ?? null : null;
-  const blockedReason = bindingBlockedReason ?? (!task ? `Task ${routedTaskId} was not found.` : blockingGap?.message ?? dependencyBlockedReason ?? lifecycleBlockedReason);
-  const routedCategory = blockedReason ? 'blocked' : category;
-  const registrySources = routeRegistrySources(registry, recommendedProfile, requiredCapabilities);
-  const adapterMapping = recommendedProfile ? adapterMappingForProfile(registry, recommendedProfile) : null;
-  const capabilityDecision = buildAgentCapabilityRouteDecision(task ?? null, routedCategory, autonomyCeiling, registry, capabilityCatalog);
-  const decision: AgentRouterDecision = {
-    version: AGENT_ROUTER_CONTRACT_VERSION,
-    taskId: routedTaskId,
-    branch,
-    category: routedCategory,
-    recommendedProfile,
-    allowedProfiles,
-    rejectedProfiles: buildRejectedProfiles(allowedProfiles, blockedReason, registry),
-    requiredCapabilities,
-    sourceCapability,
-    reuseDecision: sourceCapabilityContract?.reuseDecision ?? null,
-    toolPermission: task && recommendedProfile ? buildToolPermissionSpec(task, recommendedProfile, autonomyCeiling, registry) : null,
-    modelPolicy: modelPolicyForProfile(recommendedProfile, registry),
-    teamMode: buildTeamModePolicy({
-      activation: resolveTeamModeActivation(options, 'auto'),
-      task: task ?? null,
-      category: routedCategory,
-      risk: task?.risk ?? [],
-      autonomyCeiling,
-      blockedReason
-    }),
-    autonomyCeiling,
-    lifecycleGate: workflowGate.lifecycleGate,
-    lifecycleProfile: workflowGate.lifecycleProfile,
-    approvalPolicy: workflowGate.approvalPolicy,
-    requiredStages: workflowGate.requiredStages,
-    primaryReason: workflowGate.primaryReason,
-    requiredArtifacts: task?.requiredArtifacts ?? [],
-    blockedReason,
-    nextAction: routeNextAction({ taskId: routedTaskId, taskExists: Boolean(task), bindingNextAction: stageBindingNextAction(binding), hasBlockingGap: Boolean(blockingGap), dependencyTaskId, blockedReason, workflowGateNextAction: workflowGate.nextAction, recommendedProfile, requiredCapabilities }),
-    stageRouteBinding: binding,
-    capabilityDecision,
-    registrySources,
-    resolvedAliases: profileSelection.resolvedAliases,
-    routingRuleHits: matchedRules.map((rule) => rule.id),
-    quarantineWarnings: quarantineWarningsForSources(registrySources),
-    adapterMapping,
-    cache: options.cache ? { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'miss', source: 'content_addressed_derived_route', authoritative: false } : undefined
-  };
-  profileSpans.push(runtimeProfileSpan('route_compute', computeStart));
-  if (options.cache) {
-    await writeRouteCache(projectRoot, cacheKey, decision);
-    decision.cache = { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'stored', source: 'content_addressed_derived_route', authoritative: false };
-  }
-  if (options.profile) {
-    decision.profile = [...profileSpans, runtimeProfileSpan('route_total', routeStart, routeStartedAt)];
-  }
-  return decision;
-}
-
-function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], states: RunState[]): Map<string, RunStateTaskRuntime> {
-  const stateByRunId = new Map(states.map((state) => [state.runId, state]));
-  const result = new Map<string, RunStateTaskRuntime>();
-  for (const selection of selections) {
-    const selected = selection.selected;
-    if (!selected) {
-      continue;
-    }
-    const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
-    if (taskState) {
-      result.set(selected.taskId, taskState);
-    }
-  }
-  return result;
-}
-
-function routeNextAction(input: {
-  taskId: string;
-  taskExists: boolean;
-  bindingNextAction: string | null;
-  hasBlockingGap: boolean;
-  dependencyTaskId: string | null;
-  blockedReason: string | null;
-  workflowGateNextAction: string;
-  recommendedProfile: string | null;
-  requiredCapabilities: string[];
-}): string {
-  if (input.bindingNextAction) {
-    return input.bindingNextAction;
-  }
-  if (!input.taskExists) {
-    return `Create or restore task ${input.taskId} before routing.`;
-  }
-  if (input.hasBlockingGap) {
-    return `Fix task gaps before routing ${input.taskId}.`;
-  }
-  if (input.dependencyTaskId) {
-    return input.blockedReason?.includes('has not passed required verification')
-      ? `Run sdd test task-${input.dependencyTaskId} before routing ${input.taskId}.`
-      : `Run sdd do task ${input.dependencyTaskId} before routing ${input.taskId}.`;
-  }
-  if (input.workflowGateNextAction) {
-    return input.workflowGateNextAction;
-  }
-  if (input.recommendedProfile) {
-    return `Use ${input.recommendedProfile} with ${input.requiredCapabilities.join(',') || 'no extra capability'} and preserve required artifacts before verify.`;
-  }
-  return `Declare a routable profile before routing ${input.taskId}.`;
-}
-
-function stageBindingNextAction(binding: StageRouteBinding): string | null {
-  if (binding.status === 'bound') {
-    return null;
-  }
-  if (binding.nextAction === 'route_to_lifecycle_decision') {
-    return 'Run /sdd or /sdd:spec to create or refresh the lifecycle decision, then return to /sdd:do.';
-  }
-  if (binding.nextAction === 'ask_clarification') {
-    return binding.reasons[0] ?? 'Clarify the target task id or task title before running /sdd:do.';
-  }
-  if (binding.nextAction === 'runtime_repair_required') {
-    return binding.reasons[0] ?? 'Repair stale upstream runtime state before running /sdd:do.';
-  }
-  return binding.reasons[0] ?? 'Stage route binding blocked this local entry.';
+import {
+  AGENT_ROUTER_CONTRACT_VERSION,
+  ROUTE_CACHE_CONTRACT_VERSION
+} from '../contracts.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { readRouteCache, routeCacheKey, runtimeProfileSpan, writeRouteCache } from './route-cache.js';
+import type { RuntimeProfileSpan, TeamModeActivation } from './route-cache.js';
+import { buildAgentSkillRuntimeRegistry } from './runtime-registry.js';
+import { buildTeamModePolicy, resolveTeamModeActivation } from './team-mode.js';
+import { matchRoutingRules } from './routing-rules.js';
+import { chooseRecommendedProfile, deriveAllowedProfiles, toAgentProfileId } from './profile-resolution.js';
+import { adapterMappingForProfile, buildAgentCapabilityRouteDecision, buildRejectedProfiles, buildToolPermissionSpec, modelPolicyForProfile, quarantineWarningsForSources, routeCategory, routeRegistrySources, selectRequiredSkillCapabilities } from './route-projection.js';
+import { lifecycleAutonomyCeilingFromDecision, ensureLifecycleRiskDecision } from '../orchestration/runtime.js';
+import { taskAutonomyCeiling } from './risk-policy.js';
+import { evaluateTaskWorkflowGate } from '../risk.js';
+import { nextDependencyTaskId, resolveTaskDependencyReadiness } from '../workflow-state/dependencies.js';
+import { selectLatestEligibleRunsByTask, type LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
+import { readAllRunStates } from '../run-state/run-state.js';
+import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
+import { inspectAgentCapabilityCatalog } from '../registries/agent-capability-catalog.js';
+import type {
+  AgentRouterDecision,
+  TeamModePolicy
+} from './agent-runtime.js';
+
+
+
+export async function inspectTeamModePolicy(projectRoot: string, options: { taskId?: string; branch?: string; enabled?: boolean; teamModeActivation?: TeamModeActivation } = {}): Promise<TeamModePolicy> {
+  const registry = await buildAgentSkillRuntimeRegistry(projectRoot);
+  const activation = resolveTeamModeActivation({ teamModeEnabled: options.enabled, teamModeActivation: options.teamModeActivation }, options.taskId ? 'auto' : 'off');
+  if (!options.taskId) {
+    return buildTeamModePolicy({ activation });
+  }
+  const branch = options.branch ?? (await resolveSddContext(projectRoot)).branch;
+  const model = await parseSddBranch(projectRoot, branch);
+  const inspected = inspectSddTask(model, options.taskId);
+  const task = inspected.task;
+  const blockingGap = inspected.gaps.find((gap) => gap.severity === 'blocking');
+  const matchedRules = task && !blockingGap ? matchRoutingRules(task, registry) : [];
+  const allowedProfiles = task && !blockingGap ? deriveAllowedProfiles(task, registry, matchedRules).profiles : [];
+  const category = task ? routeCategory(task, blockingGap, allowedProfiles, matchedRules) : 'blocked';
+  const autonomyCeiling = task ? taskAutonomyCeiling(task) : 'research_before_implementation';
+  return buildTeamModePolicy({ activation, task, category, risk: task?.risk ?? [], autonomyCeiling, blockedReason: blockingGap?.message ?? null });
+}
+
+export async function routeSddTask(projectRoot: string, options: { taskId: string; branch?: string; agent?: string; teamModeEnabled?: boolean; teamModeActivation?: TeamModeActivation; profile?: boolean; cache?: boolean; approved?: boolean } = { taskId: '' }): Promise<AgentRouterDecision> {
+  const profileSpans: RuntimeProfileSpan[] = [];
+  const routeStart = Date.now();
+  const routeStartedAt = new Date(routeStart).toISOString();
+  const registry = await buildAgentSkillRuntimeRegistry(projectRoot);
+  const capabilityCatalog = await inspectAgentCapabilityCatalog(projectRoot);
+  profileSpans.push(runtimeProfileSpan('agent_runtime_registry', routeStart));
+  const branchStart = Date.now();
+  const context = await resolveSddContext(projectRoot, { branch: options.branch, branchSource: options.branch ? 'cli_option' : undefined });
+  const branch = context.partition;
+  const model = await parseSddBranch(projectRoot, branch);
+  const states = await readAllRunStates(projectRoot);
+  const runtimeByTask = latestRuntimeTaskStates(selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch }), states);
+  profileSpans.push(runtimeProfileSpan('document_parse', branchStart));
+  const cacheKey = routeCacheKey({ taskId: options.taskId, branch, agent: options.agent ?? null, teamModeActivation: resolveTeamModeActivation(options, 'auto'), approved: options.approved, documents: model.documents });
+  const cachedDecision = options.cache ? await readRouteCache<AgentRouterDecision>(projectRoot, cacheKey) : null;
+  if (cachedDecision) {
+    return {
+      ...cachedDecision,
+      cache: { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'hit', source: 'content_addressed_derived_route', authoritative: false },
+      profile: options.profile ? [...(cachedDecision.profile ?? []), runtimeProfileSpan('route_total', routeStart, routeStartedAt)] : undefined
+    };
+  }
+  const computeStart = Date.now();
+  const inspected = inspectSddTask(model, options.taskId);
+  const task = inspected.task;
+  const blockingGap = inspected.gaps.find((gap) => gap.severity === 'blocking');
+  const matchedRules = task && !blockingGap ? matchRoutingRules(task, registry) : [];
+  const profileSelection = task && !blockingGap ? deriveAllowedProfiles(task, registry, matchedRules) : { profiles: [], resolvedAliases: [] };
+  const delegatedProfile = task && !blockingGap && options.agent ? toAgentProfileId(options.agent, registry) : null;
+  const allowedProfiles = delegatedProfile && !profileSelection.profiles.includes(delegatedProfile) ? [...profileSelection.profiles, delegatedProfile] : profileSelection.profiles;
+  const riskDecision = task ? await ensureLifecycleRiskDecision(projectRoot, model, { branch, task }) : null;
+  const workflowGate = evaluateTaskWorkflowGate({ task, taskId: options.taskId, riskDecision, approved: options.approved });
+  const lifecycleBlockedReason = workflowGate.blocksRoute
+    ? workflowGate.primaryReason
+    : null;
+  const dependencyReadiness = task ? resolveTaskDependencyReadiness(model, options.taskId, { runtimeByTask }) : null;
+  const dependencyBlockedReason = dependencyReadiness?.blockingReasons[0] ?? null;
+  const dependencyTaskId = task ? nextDependencyTaskId(model, options.taskId, { runtimeByTask }) : null;
+  const taskRecommendedProfile = task && !blockingGap && !dependencyBlockedReason && !lifecycleBlockedReason ? chooseRecommendedProfile(task, allowedProfiles, registry, matchedRules) : null;
+  const recommendedProfile = dependencyBlockedReason || lifecycleBlockedReason ? null : delegatedProfile ?? taskRecommendedProfile;
+  const category = task ? routeCategory(task, blockingGap, allowedProfiles, matchedRules) : 'blocked';
+  const autonomyCeiling = riskDecision ? lifecycleAutonomyCeilingFromDecision(riskDecision) : task ? taskAutonomyCeiling(task) : 'research_before_implementation';
+  const requiredCapabilities = task && recommendedProfile ? selectRequiredSkillCapabilities(task, recommendedProfile, registry, matchedRules) : [];
+  const sourceCapability = requiredCapabilities[0] ?? null;
+  const sourceCapabilityContract = sourceCapability ? registry.skillCapabilities.find((capability) => capability.id === sourceCapability) ?? null : null;
+  const blockedReason = !task ? `Task ${options.taskId} was not found.` : blockingGap?.message ?? dependencyBlockedReason ?? lifecycleBlockedReason;
+  const routedCategory = blockedReason ? 'blocked' : category;
+  const registrySources = routeRegistrySources(registry, recommendedProfile, requiredCapabilities);
+  const adapterMapping = recommendedProfile ? adapterMappingForProfile(registry, recommendedProfile) : null;
+  const capabilityDecision = buildAgentCapabilityRouteDecision(task ?? null, routedCategory, autonomyCeiling, registry, capabilityCatalog);
+  const decision: AgentRouterDecision = {
+    version: AGENT_ROUTER_CONTRACT_VERSION,
+    taskId: options.taskId,
+    branch,
+    category: routedCategory,
+    recommendedProfile,
+    allowedProfiles,
+    rejectedProfiles: buildRejectedProfiles(allowedProfiles, blockedReason, registry),
+    requiredCapabilities,
+    sourceCapability,
+    reuseDecision: sourceCapabilityContract?.reuseDecision ?? null,
+    toolPermission: task && recommendedProfile ? buildToolPermissionSpec(task, recommendedProfile, autonomyCeiling, registry) : null,
+    modelPolicy: modelPolicyForProfile(recommendedProfile, registry),
+    teamMode: buildTeamModePolicy({
+      activation: resolveTeamModeActivation(options, 'auto'),
+      task: task ?? null,
+      category: routedCategory,
+      risk: task?.risk ?? [],
+      autonomyCeiling,
+      blockedReason
+    }),
+    autonomyCeiling,
+    lifecycleGate: workflowGate.lifecycleGate,
+    lifecycleProfile: workflowGate.lifecycleProfile,
+    approvalPolicy: workflowGate.approvalPolicy,
+    requiredStages: workflowGate.requiredStages,
+    primaryReason: workflowGate.primaryReason,
+    requiredArtifacts: task?.requiredArtifacts ?? [],
+    blockedReason,
+    nextAction: routeNextAction({ taskId: options.taskId, taskExists: Boolean(task), hasBlockingGap: Boolean(blockingGap), dependencyTaskId, blockedReason, workflowGateNextAction: workflowGate.nextAction, recommendedProfile, requiredCapabilities }),
+    capabilityDecision,
+    registrySources,
+    resolvedAliases: profileSelection.resolvedAliases,
+    routingRuleHits: matchedRules.map((rule) => rule.id),
+    quarantineWarnings: quarantineWarningsForSources(registrySources),
+    adapterMapping,
+    cache: options.cache ? { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'miss', source: 'content_addressed_derived_route', authoritative: false } : undefined
+  };
+  profileSpans.push(runtimeProfileSpan('route_compute', computeStart));
+  if (options.cache) {
+    await writeRouteCache(projectRoot, cacheKey, decision);
+    decision.cache = { contract: ROUTE_CACHE_CONTRACT_VERSION, key: cacheKey, status: 'stored', source: 'content_addressed_derived_route', authoritative: false };
+  }
+  if (options.profile) {
+    decision.profile = [...profileSpans, runtimeProfileSpan('route_total', routeStart, routeStartedAt)];
+  }
+  return decision;
+}
+
+function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], states: RunState[]): Map<string, RunStateTaskRuntime> {
+  const stateByRunId = new Map(states.map((state) => [state.runId, state]));
+  const result = new Map<string, RunStateTaskRuntime>();
+  for (const selection of selections) {
+    const selected = selection.selected;
+    if (!selected) {
+      continue;
+    }
+    const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
+    if (taskState) {
+      result.set(selected.taskId, taskState);
+    }
+  }
+  return result;
+}
+
+function routeNextAction(input: {
+  taskId: string;
+  taskExists: boolean;
+  hasBlockingGap: boolean;
+  dependencyTaskId: string | null;
+  blockedReason: string | null;
+  workflowGateNextAction: string;
+  recommendedProfile: string | null;
+  requiredCapabilities: string[];
+}): string {
+  if (!input.taskExists) {
+    return `Create or restore task ${input.taskId} before routing.`;
+  }
+  if (input.hasBlockingGap) {
+    return `Fix task gaps before routing ${input.taskId}.`;
+  }
+  if (input.dependencyTaskId) {
+    return `Complete dependency ${input.dependencyTaskId} through sdd execute before routing ${input.taskId}.`;
+  }
+  if (input.workflowGateNextAction) {
+    return input.workflowGateNextAction;
+  }
+  if (input.recommendedProfile) {
+    return `Use ${input.recommendedProfile} with ${input.requiredCapabilities.join(',') || 'no extra capability'} and preserve completion evidence for execute.`;
+  }
+  return `Declare a routable profile before routing ${input.taskId}.`;
 }