sdd-agent-platform 0.4.1 → 0.5.0

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

@@ -1,154 +1,154 @@
-import type { SddTask } from '../sdd-docs/task-parser.js';
-import type {
-  AgentProfileContract,
-  AgentProfileId,
-  AgentRuntimeAliasResolution,
-  AgentRuntimeRoutingRule
-} from './agent-runtime.js';
-import { BUILT_IN_AGENT_PROFILES, type AgentSkillRuntimeRegistry } from './runtime-registry.js';
-import { hasExternalUnknownRisk, hasSecurityRisk } from './risk-policy.js';
-
-export interface AgentRouteProfileSelection {
-  profiles: AgentProfileId[];
-  resolvedAliases: AgentRuntimeAliasResolution[];
-}
-
-interface AgentProfileTokenResolution {
-  profile: AgentProfileId | null;
-  alias: AgentRuntimeAliasResolution | null;
-}
-
-export function deriveAllowedProfiles(task: SddTask, registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentRouteProfileSelection {
-  const profiles = new Set<AgentProfileId>();
-  const resolvedAliases: AgentRuntimeAliasResolution[] = [];
-  for (const value of [...task.allowedAgents, ...task.agentFit]) {
-    for (const token of value.split(/[\s,\/]+/).filter(Boolean)) {
-      const resolution = resolveAgentProfileToken(token, registry);
-      if (resolution.profile) {
-        profiles.add(resolution.profile);
-      }
-      appendAliasResolution(resolvedAliases, resolution.alias);
-    }
-  }
-  for (const rule of matchedRules) {
-    const resolution = resolveAgentProfileToken(rule.preferProfile, registry);
-    if (resolution.profile) {
-      profiles.add(resolution.profile);
-    }
-    appendAliasResolution(resolvedAliases, resolution.alias);
-  }
-  if (profiles.size === 0) {
-    for (const profile of fallbackProfilesForTask(task)) {
-      addRegisteredProfile(profiles, profile, registry);
-    }
-  }
-  return { profiles: [...profiles], resolvedAliases };
-}
-
-export function toAgentProfileId(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileId | null {
-  return resolveAgentProfileToken(value, registry).profile;
-}
-
-export function resolveAgentProfileToken(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileTokenResolution {
-  const directProfile = registry ? findRegisteredProfile(value, registry) : findBuiltInProfile(value);
-  if (directProfile) {
-    return { profile: directProfile.id, alias: null };
-  }
-  const builtInAlias = builtInProfileAliasTarget(value);
-  const builtInProfile = builtInAlias ? registry ? findRegisteredProfile(builtInAlias, registry) : findBuiltInProfile(builtInAlias) : null;
-  if (builtInProfile) {
-    return { profile: builtInProfile.id, alias: { input: value, resolved: builtInProfile.id, source: 'built_in' } };
-  }
-  if (registry) {
-    for (const [alias, target] of Object.entries(registry.aliases)) {
-      if (normalizeAgentToken(alias) !== normalizeAgentToken(value)) {
-        continue;
-      }
-      const aliasTarget = findRegisteredProfile(target, registry) ?? (builtInProfileAliasTarget(target) ? findRegisteredProfile(builtInProfileAliasTarget(target)!, registry) : null);
-      if (aliasTarget) {
-        return { profile: aliasTarget.id, alias: { input: value, resolved: aliasTarget.id, source: 'project_config' } };
-      }
-    }
-  }
-  return { profile: null, alias: null };
-}
-
-export function findRegisteredProfile(value: string, registry: AgentSkillRuntimeRegistry): AgentProfileContract | null {
-  const normalized = normalizeAgentToken(value);
-  return registry.profiles.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
-}
-
-export function findBuiltInProfile(value: string): AgentProfileContract | null {
-  const normalized = normalizeAgentToken(value);
-  return BUILT_IN_AGENT_PROFILES.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
-}
-
-export function chooseRecommendedProfile(task: SddTask, allowedProfiles: AgentProfileId[], registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentProfileId {
-  if (hasSecurityRisk(task.risk)) {
-    return allowedProfiles.includes('security') ? 'security' : allowedProfiles[0] ?? 'security';
-  }
-  if (hasExternalUnknownRisk(task.risk)) {
-    return allowedProfiles.includes('researcher') ? 'researcher' : allowedProfiles[0] ?? 'researcher';
-  }
-  if (task.status === 'completed') {
-    return allowedProfiles.includes('validator') ? 'validator' : allowedProfiles[0] ?? 'validator';
-  }
-  const preferredByRule = matchedRules.map((rule) => resolveAgentProfileToken(rule.preferProfile, registry).profile).find((profile): profile is AgentProfileId => Boolean(profile));
-  if (preferredByRule && allowedProfiles.includes(preferredByRule)) {
-    return preferredByRule;
-  }
-  if (allowedProfiles.includes('implementer')) {
-    return 'implementer';
-  }
-  return allowedProfiles[0] ?? 'implementer';
-}
-
-function appendAliasResolution(resolvedAliases: AgentRuntimeAliasResolution[], alias: AgentRuntimeAliasResolution | null): void {
-  if (!alias) {
-    return;
-  }
-  if (!resolvedAliases.some((candidate) => candidate.input === alias.input && candidate.resolved === alias.resolved && candidate.source === alias.source)) {
-    resolvedAliases.push(alias);
-  }
-}
-
-function builtInProfileAliasTarget(value: string): AgentProfileId | null {
-  const normalized = normalizeAgentToken(value);
-  if (normalized === 'scout') {
-    return 'researcher';
-  }
-  if (normalized === 'debugger') {
-    return 'implementer';
-  }
-  if (normalized === 'spec_reviewer') {
-    return 'reviewer';
-  }
-  if (normalized === 'domain') {
-    return 'domain_expert';
-  }
-  return null;
-}
-
-function addRegisteredProfile(profiles: Set<AgentProfileId>, profileId: AgentProfileId, registry: AgentSkillRuntimeRegistry): void {
-  const profile = findRegisteredProfile(profileId, registry);
-  if (profile) {
-    profiles.add(profile.id);
-  }
-}
-
-function fallbackProfilesForTask(task: SddTask): AgentProfileId[] {
-  if (hasSecurityRisk(task.risk)) {
-    return ['security', 'reviewer'];
-  }
-  if (hasExternalUnknownRisk(task.risk)) {
-    return ['researcher', 'architect'];
-  }
-  if (task.status === 'completed') {
-    return ['validator', 'reviewer'];
-  }
-  return ['implementer', 'reviewer', 'validator'];
-}
-
-function normalizeAgentToken(value: string): string {
-  return value.trim().toLowerCase().replace(/-/g, '_');
-}
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import type {
+  AgentProfileContract,
+  AgentProfileId,
+  AgentRuntimeAliasResolution,
+  AgentRuntimeRoutingRule
+} from './agent-runtime.js';
+import { BUILT_IN_AGENT_PROFILES, type AgentSkillRuntimeRegistry } from './runtime-registry.js';
+import { hasExternalUnknownRisk, hasSecurityRisk } from './risk-policy.js';
+
+export interface AgentRouteProfileSelection {
+  profiles: AgentProfileId[];
+  resolvedAliases: AgentRuntimeAliasResolution[];
+}
+
+interface AgentProfileTokenResolution {
+  profile: AgentProfileId | null;
+  alias: AgentRuntimeAliasResolution | null;
+}
+
+export function deriveAllowedProfiles(task: SddTask, registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentRouteProfileSelection {
+  const profiles = new Set<AgentProfileId>();
+  const resolvedAliases: AgentRuntimeAliasResolution[] = [];
+  for (const value of [...task.allowedAgents, ...task.agentFit]) {
+    for (const token of value.split(/[\s,\/]+/).filter(Boolean)) {
+      const resolution = resolveAgentProfileToken(token, registry);
+      if (resolution.profile) {
+        profiles.add(resolution.profile);
+      }
+      appendAliasResolution(resolvedAliases, resolution.alias);
+    }
+  }
+  for (const rule of matchedRules) {
+    const resolution = resolveAgentProfileToken(rule.preferProfile, registry);
+    if (resolution.profile) {
+      profiles.add(resolution.profile);
+    }
+    appendAliasResolution(resolvedAliases, resolution.alias);
+  }
+  if (profiles.size === 0) {
+    for (const profile of fallbackProfilesForTask(task)) {
+      addRegisteredProfile(profiles, profile, registry);
+    }
+  }
+  return { profiles: [...profiles], resolvedAliases };
+}
+
+export function toAgentProfileId(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileId | null {
+  return resolveAgentProfileToken(value, registry).profile;
+}
+
+export function resolveAgentProfileToken(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileTokenResolution {
+  const directProfile = registry ? findRegisteredProfile(value, registry) : findBuiltInProfile(value);
+  if (directProfile) {
+    return { profile: directProfile.id, alias: null };
+  }
+  const builtInAlias = builtInProfileAliasTarget(value);
+  const builtInProfile = builtInAlias ? registry ? findRegisteredProfile(builtInAlias, registry) : findBuiltInProfile(builtInAlias) : null;
+  if (builtInProfile) {
+    return { profile: builtInProfile.id, alias: { input: value, resolved: builtInProfile.id, source: 'built_in' } };
+  }
+  if (registry) {
+    for (const [alias, target] of Object.entries(registry.aliases)) {
+      if (normalizeAgentToken(alias) !== normalizeAgentToken(value)) {
+        continue;
+      }
+      const aliasTarget = findRegisteredProfile(target, registry) ?? (builtInProfileAliasTarget(target) ? findRegisteredProfile(builtInProfileAliasTarget(target)!, registry) : null);
+      if (aliasTarget) {
+        return { profile: aliasTarget.id, alias: { input: value, resolved: aliasTarget.id, source: 'project_config' } };
+      }
+    }
+  }
+  return { profile: null, alias: null };
+}
+
+export function findRegisteredProfile(value: string, registry: AgentSkillRuntimeRegistry): AgentProfileContract | null {
+  const normalized = normalizeAgentToken(value);
+  return registry.profiles.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
+}
+
+export function findBuiltInProfile(value: string): AgentProfileContract | null {
+  const normalized = normalizeAgentToken(value);
+  return BUILT_IN_AGENT_PROFILES.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
+}
+
+export function chooseRecommendedProfile(task: SddTask, allowedProfiles: AgentProfileId[], registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentProfileId {
+  if (hasSecurityRisk(task.risk)) {
+    return allowedProfiles.includes('security') ? 'security' : allowedProfiles[0] ?? 'security';
+  }
+  if (hasExternalUnknownRisk(task.risk)) {
+    return allowedProfiles.includes('researcher') ? 'researcher' : allowedProfiles[0] ?? 'researcher';
+  }
+  if (task.status === 'completed') {
+    return allowedProfiles.includes('validator') ? 'validator' : allowedProfiles[0] ?? 'validator';
+  }
+  const preferredByRule = matchedRules.map((rule) => resolveAgentProfileToken(rule.preferProfile, registry).profile).find((profile): profile is AgentProfileId => Boolean(profile));
+  if (preferredByRule && allowedProfiles.includes(preferredByRule)) {
+    return preferredByRule;
+  }
+  if (allowedProfiles.includes('implementer')) {
+    return 'implementer';
+  }
+  return allowedProfiles[0] ?? 'implementer';
+}
+
+function appendAliasResolution(resolvedAliases: AgentRuntimeAliasResolution[], alias: AgentRuntimeAliasResolution | null): void {
+  if (!alias) {
+    return;
+  }
+  if (!resolvedAliases.some((candidate) => candidate.input === alias.input && candidate.resolved === alias.resolved && candidate.source === alias.source)) {
+    resolvedAliases.push(alias);
+  }
+}
+
+function builtInProfileAliasTarget(value: string): AgentProfileId | null {
+  const normalized = normalizeAgentToken(value);
+  if (normalized === 'scout') {
+    return 'researcher';
+  }
+  if (normalized === 'debugger') {
+    return 'implementer';
+  }
+  if (normalized === 'spec_reviewer') {
+    return 'reviewer';
+  }
+  if (normalized === 'domain') {
+    return 'domain_expert';
+  }
+  return null;
+}
+
+function addRegisteredProfile(profiles: Set<AgentProfileId>, profileId: AgentProfileId, registry: AgentSkillRuntimeRegistry): void {
+  const profile = findRegisteredProfile(profileId, registry);
+  if (profile) {
+    profiles.add(profile.id);
+  }
+}
+
+function fallbackProfilesForTask(task: SddTask): AgentProfileId[] {
+  if (hasSecurityRisk(task.risk)) {
+    return ['security', 'reviewer'];
+  }
+  if (hasExternalUnknownRisk(task.risk)) {
+    return ['researcher', 'architect'];
+  }
+  if (task.status === 'completed') {
+    return ['validator', 'reviewer'];
+  }
+  return ['implementer', 'reviewer', 'validator'];
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/-/g, '_');
+}

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

@@ -1,33 +1,33 @@
-import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
-import type { SddTask } from '../sdd-docs/task-parser.js';
-import { buildTaskRiskProfile } from '../task-risk-profile.js';
-
-export function taskAutonomyCeiling(task: SddTask): LifecycleAutonomyCeiling {
-  const declared = task.autonomy?.trim();
-  if (declared === 'direct_execution_allowed' || declared === 'compact_boundary_only' || declared === 'full_sdd_with_checkpoint' || declared === 'research_before_implementation') {
-    return declared;
-  }
-  const profile = buildTaskRiskProfile(task);
-  if (profile.externalUnknown) {
-    return 'research_before_implementation';
-  }
-  if (profile.riskLevel === 'high') {
-    return 'full_sdd_with_checkpoint';
-  }
-  if (profile.riskLevel === 'medium') {
-    return 'compact_boundary_only';
-  }
-  return 'direct_execution_allowed';
-}
-
-export function hasSecurityRisk(risk: string[]): boolean {
-  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).securitySensitive;
-}
-
-export function hasExternalUnknownRisk(risk: string[]): boolean {
-  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).externalUnknown;
-}
-
-export function isHighRiskValues(risk: string[]): boolean {
-  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).riskLevel === 'high';
-}
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+
+export function taskAutonomyCeiling(task: SddTask): LifecycleAutonomyCeiling {
+  const declared = task.autonomy?.trim();
+  if (declared === 'direct_execution_allowed' || declared === 'compact_boundary_only' || declared === 'full_sdd_with_checkpoint' || declared === 'research_before_implementation') {
+    return declared;
+  }
+  const profile = buildTaskRiskProfile(task);
+  if (profile.externalUnknown) {
+    return 'research_before_implementation';
+  }
+  if (profile.riskLevel === 'high') {
+    return 'full_sdd_with_checkpoint';
+  }
+  if (profile.riskLevel === 'medium') {
+    return 'compact_boundary_only';
+  }
+  return 'direct_execution_allowed';
+}
+
+export function hasSecurityRisk(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).securitySensitive;
+}
+
+export function hasExternalUnknownRisk(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).externalUnknown;
+}
+
+export function isHighRiskValues(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).riskLevel === 'high';
+}

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

@@ -1,100 +1,100 @@
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import {
-  ACCEPTANCE_POLICY_RULESET_VERSION,
-  AGENT_ROUTER_CONTRACT_VERSION,
-  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
-  ROUTE_CACHE_CONTRACT_VERSION,
-  RUNTIME_PROFILE_CONTRACT_VERSION,
-  TEAM_MODE_POLICY_VERSION
-} from '../contracts.js';
-import { getRouteCachePath } from '../runtime-paths.js';
-import { exists } from '../storage/json-io.js';
-import { TOOL_CAPABILITY_REGISTRY_VERSION } from '../registries/tool-capabilities.js';
-import { TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION } from '../registries/tool-plugins.js';
-import { WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION } from '../registries/worker-adapters.js';
-export type TeamModeActivation = 'auto' | 'force' | 'off';
-
-export interface RouteCacheMetadata {
-  contract: typeof ROUTE_CACHE_CONTRACT_VERSION;
-  key: string;
-  status: 'hit' | 'miss' | 'stored';
-  source: 'content_addressed_derived_route';
-  authoritative: false;
-}
-
-export interface RuntimeProfileSpan {
-  contract: typeof RUNTIME_PROFILE_CONTRACT_VERSION;
-  name: string;
-  startedAt: string;
-  endedAt: string;
-  durationMs: number;
-}
-
-export interface RouteCacheDocuments {
-  specHash?: string | null;
-  planHash?: string | null;
-  tasksHash?: string | null;
-  planBasedOnSpecHash?: string | null;
-  tasksBasedOnPlanHash?: string | null;
-}
-
-export interface CacheableRouteDecision {
-  version: typeof AGENT_ROUTER_CONTRACT_VERSION;
-  cache?: RouteCacheMetadata;
-  profile?: RuntimeProfileSpan[];
-}
-
-export function runtimeProfileSpan(name: string, startedAtMs: number, startedAt = new Date(startedAtMs).toISOString()): RuntimeProfileSpan {
-  const endedAtMs = Date.now();
-  return {
-    contract: RUNTIME_PROFILE_CONTRACT_VERSION,
-    name,
-    startedAt,
-    endedAt: new Date(endedAtMs).toISOString(),
-    durationMs: Math.max(0, endedAtMs - startedAtMs)
-  };
-}
-
-export function routeCacheKey(input: { taskId: string; branch: string; agent: string | null; teamModeActivation: TeamModeActivation; approved?: boolean; documents: RouteCacheDocuments }): string {
-  return createHash('sha256')
-    .update(JSON.stringify({
-      contract: ROUTE_CACHE_CONTRACT_VERSION,
-      router: AGENT_ROUTER_CONTRACT_VERSION,
-      teamMode: TEAM_MODE_POLICY_VERSION,
-      policy: ACCEPTANCE_POLICY_RULESET_VERSION,
-      runtime: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
-      capabilities: TOOL_CAPABILITY_REGISTRY_VERSION,
-      plugins: TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION,
-      workers: WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION,
-      taskId: input.taskId,
-      branch: input.branch,
-      agent: input.agent,
-      teamModeActivation: input.teamModeActivation,
-      approved: input.approved === true,
-      specHash: input.documents.specHash ?? null,
-      planHash: input.documents.planHash ?? null,
-      tasksHash: input.documents.tasksHash ?? null,
-      planBasedOnSpecHash: input.documents.planBasedOnSpecHash ?? null,
-      tasksBasedOnPlanHash: input.documents.tasksBasedOnPlanHash ?? null
-    }))
-    .digest('hex')
-    .slice(0, 32);
-}
-
-export async function readRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string): Promise<TDecision | null> {
-  const cachePath = getRouteCachePath(projectRoot, key);
-  if (!await exists(cachePath)) {
-    return null;
-  }
-  const parsed = JSON.parse(await readFile(cachePath, 'utf8')) as TDecision;
-  return parsed.version === AGENT_ROUTER_CONTRACT_VERSION ? parsed : null;
-}
-
-export async function writeRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string, decision: TDecision): Promise<void> {
-  const cachePath = getRouteCachePath(projectRoot, key);
-  await mkdir(path.dirname(cachePath), { recursive: true });
-  const { cache: _cache, profile: _profile, ...cacheable } = decision;
-  await writeFile(cachePath, `${JSON.stringify(cacheable, null, 2)}\n`, 'utf8');
-}
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  ACCEPTANCE_POLICY_RULESET_VERSION,
+  AGENT_ROUTER_CONTRACT_VERSION,
+  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+  ROUTE_CACHE_CONTRACT_VERSION,
+  RUNTIME_PROFILE_CONTRACT_VERSION,
+  TEAM_MODE_POLICY_VERSION
+} from '../contracts.js';
+import { getRouteCachePath } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { TOOL_CAPABILITY_REGISTRY_VERSION } from '../registries/tool-capabilities.js';
+import { TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION } from '../registries/tool-plugins.js';
+import { WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION } from '../registries/worker-adapters.js';
+export type TeamModeActivation = 'auto' | 'force' | 'off';
+
+export interface RouteCacheMetadata {
+  contract: typeof ROUTE_CACHE_CONTRACT_VERSION;
+  key: string;
+  status: 'hit' | 'miss' | 'stored';
+  source: 'content_addressed_derived_route';
+  authoritative: false;
+}
+
+export interface RuntimeProfileSpan {
+  contract: typeof RUNTIME_PROFILE_CONTRACT_VERSION;
+  name: string;
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+}
+
+export interface RouteCacheDocuments {
+  specHash?: string | null;
+  planHash?: string | null;
+  tasksHash?: string | null;
+  planBasedOnSpecHash?: string | null;
+  tasksBasedOnPlanHash?: string | null;
+}
+
+export interface CacheableRouteDecision {
+  version: typeof AGENT_ROUTER_CONTRACT_VERSION;
+  cache?: RouteCacheMetadata;
+  profile?: RuntimeProfileSpan[];
+}
+
+export function runtimeProfileSpan(name: string, startedAtMs: number, startedAt = new Date(startedAtMs).toISOString()): RuntimeProfileSpan {
+  const endedAtMs = Date.now();
+  return {
+    contract: RUNTIME_PROFILE_CONTRACT_VERSION,
+    name,
+    startedAt,
+    endedAt: new Date(endedAtMs).toISOString(),
+    durationMs: Math.max(0, endedAtMs - startedAtMs)
+  };
+}
+
+export function routeCacheKey(input: { taskId: string; branch: string; agent: string | null; teamModeActivation: TeamModeActivation; approved?: boolean; documents: RouteCacheDocuments }): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      contract: ROUTE_CACHE_CONTRACT_VERSION,
+      router: AGENT_ROUTER_CONTRACT_VERSION,
+      teamMode: TEAM_MODE_POLICY_VERSION,
+      policy: ACCEPTANCE_POLICY_RULESET_VERSION,
+      runtime: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+      capabilities: TOOL_CAPABILITY_REGISTRY_VERSION,
+      plugins: TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION,
+      workers: WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION,
+      taskId: input.taskId,
+      branch: input.branch,
+      agent: input.agent,
+      teamModeActivation: input.teamModeActivation,
+      approved: input.approved === true,
+      specHash: input.documents.specHash ?? null,
+      planHash: input.documents.planHash ?? null,
+      tasksHash: input.documents.tasksHash ?? null,
+      planBasedOnSpecHash: input.documents.planBasedOnSpecHash ?? null,
+      tasksBasedOnPlanHash: input.documents.tasksBasedOnPlanHash ?? null
+    }))
+    .digest('hex')
+    .slice(0, 32);
+}
+
+export async function readRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string): Promise<TDecision | null> {
+  const cachePath = getRouteCachePath(projectRoot, key);
+  if (!await exists(cachePath)) {
+    return null;
+  }
+  const parsed = JSON.parse(await readFile(cachePath, 'utf8')) as TDecision;
+  return parsed.version === AGENT_ROUTER_CONTRACT_VERSION ? parsed : null;
+}
+
+export async function writeRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string, decision: TDecision): Promise<void> {
+  const cachePath = getRouteCachePath(projectRoot, key);
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const { cache: _cache, profile: _profile, ...cacheable } = decision;
+  await writeFile(cachePath, `${JSON.stringify(cacheable, null, 2)}\n`, 'utf8');
+}