@clue-ai/cli 0.0.16 → 0.0.18

package/src/semantic-ci.mjs

@@ -80,12 +80,25 @@ const ACTUAL_OUTCOME_ACTIONS = new Set([
 ]);
 
 const snakeSegmentPattern = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
-const SEMANTIC_SNAPSHOT_SCHEMA_VERSION = 2;
-const SEMANTIC_ANALYZER_VERSION = "fastapi-route-analyzer-v1";
-const SEMANTIC_ROUTE_PROMPT_CONTRACT_VERSION = "route-semantics-v1";
-const SEMANTIC_REUSE_PROMPT_CONTRACT_VERSION = "route-reuse-v1";
+const SEMANTIC_SNAPSHOT_SCHEMA_VERSION = 3;
+const SEMANTIC_ANALYZER_VERSION = "fastapi-route-analyzer-v2";
+const SEMANTIC_ROUTE_PROMPT_CONTRACT_VERSION = "route-semantics-v2";
+const SEMANTIC_REUSE_PROMPT_CONTRACT_VERSION = "purpose-stability-v1";
 const SEMANTIC_SELECTOR_PROMPT_CONTRACT_VERSION = "semantic-selector-v1";
 const SEMANTIC_PRIVACY_SANITIZER_VERSION = "privacy-sanitizer-v1";
+const PURPOSE_STABILITY_CONFIDENCE_THRESHOLD = 0.75;
+
+const PURPOSE_CHANGE_STATES = new Set([
+  "same_purpose",
+  "purpose_added",
+  "purpose_changed",
+  "purpose_removed",
+  "insufficient_evidence",
+  "new_route",
+]);
+
+const shouldPurposeRecheckAllRoutes = (env) =>
+  env.CLUE_SEMANTIC_PURPOSE_RECHECK_ALL === "1";
 
 const semanticSnapshotHashScope = (request) =>
   [
@@ -176,6 +189,92 @@ const fallbackSemantics = (route, reason, hashScope) => ({
   confidence_reason: reason,
 });
 
+const redactAiInputSource = (value) =>
+  String(value ?? "")
+    .slice(0, 6000)
+    .replace(
+      /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY)\b(?:\s*=\s*["']?[^"'\s,;}]+)?/g,
+      "[secret]",
+    )
+    .replace(/\bBearer\s+(?!\[secret\])[A-Za-z0-9._~+/-]+=*/gi, "Bearer [secret]")
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[secret]");
+
+const lastCallSegment = (target) =>
+  String(target ?? "")
+    .split(".")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .at(-1) ?? "";
+
+const callActionHints = (route) =>
+  [
+    ...new Set(
+      safeArray(route.ai_context?.code_structure?.call_targets)
+        .map(lastCallSegment)
+        .map((segment) => normalizeSnakeSegment(segment))
+        .filter((segment) => segment && EFFECT_ACTION_TOKENS.has(segment)),
+    ),
+  ].slice(0, 12);
+
+const buildEvidencePacketSummary = (route) => {
+  const callTargets = safeArray(route.ai_context?.code_structure?.call_targets);
+  const dependencyHints = safeArray(route.ai_context?.code_structure?.dependency_hints);
+  const actionHints = callActionHints(route);
+  return {
+    contract_summary: `${route.method ?? "UNKNOWN"} ${route.path_template ?? "/"} operation source contract.`,
+    behavior_summary:
+      callTargets.length > 0
+        ? `Handler has ${callTargets.length} bounded call target(s) that may describe domain behavior.`
+        : "No bounded domain call targets were detected in the route handler.",
+    data_effect_hints: actionHints,
+    side_effect_hints: callTargets
+      .map(lastCallSegment)
+      .map((segment) => normalizeSnakeSegment(segment))
+      .filter((segment) =>
+        ["send", "publish", "emit", "schedule", "enqueue", "notify"].includes(
+          segment,
+        ),
+      )
+      .slice(0, 12),
+    validation_hints: safeArray(
+      route.ai_context?.code_structure?.parameter_annotations,
+    )
+      .map((hint) => sanitizeText(String(hint), route))
+      .slice(0, 12),
+    auth_hints: dependencyHints
+      .map((hint) => sanitizeText(String(hint), route))
+      .slice(0, 12),
+    missing_context:
+      callTargets.length === 0
+        ? ["No local dependency call evidence was detected."]
+        : [],
+  };
+};
+
+const buildRouteEvidencePacket = (route, hashScope) => ({
+  contract: {
+    operation_source_key: route.operation_source_key,
+    method: route.method,
+    path_template: route.path_template,
+    router_prefix: route.ai_context?.router_prefix ?? null,
+    include_prefix: route.ai_context?.include_prefix ?? null,
+  },
+  code_context: {
+    handler_name: route.ai_context?.handler_name ?? null,
+    handler_source_excerpt: redactAiInputSource(route.ai_context?.source_snippet),
+    code_structure: route.ai_context?.code_structure ?? {},
+  },
+  stored_summary_preview: buildEvidencePacketSummary(route),
+  evidence_summaries: buildSourceEvidenceRefs(route, hashScope).map(
+    (entry, index) => ({
+      evidence_index: index,
+      kind: entry.kind,
+      summary: entry.summary,
+      evidence_strength: entry.evidence_strength,
+    }),
+  ),
+});
+
 const buildAiPrompt = ({ routes, generationContract, agentSkills }) =>
   JSON.stringify({
     ...semanticAgentPromptEnvelope({
@@ -187,8 +286,8 @@ const buildAiPrompt = ({ routes, generationContract, agentSkills }) =>
     rules: [
       "Do not create operation_source_key values; only copy the provided keys.",
       "Do not create ids, refs, hashes, source fingerprints, or field paths.",
-      "Do not include raw source code, raw SQL, file paths, function names, class names, prompts, or completions in the output.",
-      "Use the provided privacy-safe evidence summaries only.",
+      "You may use handler_source_excerpt and bounded dependency evidence to understand route purpose, but never copy raw source code, raw SQL, file paths, function names, class names, prompts, or completions into the output.",
+      "Use the provided route_evidence_packet to infer purpose-level business semantics and operation effects.",
       "Return operation_effect_candidates only when source evidence supports a schema-valid target object and effect action.",
       "Keep multiple effects separate when one route produces multiple meaningful effects.",
       "Do not encode actual outcomes such as completed, failed, blocked, validation_error, or abandoned into operation_effect_key or expected_domain_effect.",
@@ -228,6 +327,7 @@ const buildAiPrompt = ({ routes, generationContract, agentSkills }) =>
       method: route.method,
       path_template: route.path_template,
       evidence_summaries: route.evidence_summaries,
+      route_evidence_packet: route.route_evidence_packet,
     })),
   });
 
@@ -243,24 +343,30 @@ const buildAiReuseDecisionPrompt = ({
       bundle: agentSkills,
       roleId: SEMANTIC_AGENT_ROLE_IDS.reuseJudge,
     }),
-    task: "Decide whether previous privacy-safe route semantics still apply after a route source change. Return JSON only.",
+    task: "Decide whether previous privacy-safe route semantics still apply at the customer-visible purpose level after a route source change. Return JSON only.",
     generation_contract: generationContract,
     rules: [
       "Only decide for the provided operation_source_key.",
-      "Return decision as reuse_previous, regenerate, or needs_review.",
-      "Choose reuse_previous only when the customer-visible route meaning, operation effects, and value interpretation remain the same.",
-      "Choose regenerate when the route appears to create, update, delete, read, send, schedule, call, or validate a different business object or effect.",
-      "Choose needs_review when evidence is insufficient or conflicting.",
+      "First decide purpose_change_state as same_purpose, purpose_added, purpose_changed, purpose_removed, or insufficient_evidence.",
+      "Use same_purpose when implementation details or wording changed but the customer-visible purpose and operation effects are unchanged.",
+      "Use purpose_added when the previous purpose still applies and the current route adds a new customer-visible purpose or operation effect.",
+      "Use purpose_changed when a previous purpose or primary operation effect is replaced with a different business object or effect.",
+      "Use purpose_removed when a previous purpose or operation effect is no longer present.",
+      "Use insufficient_evidence when evidence is sparse, conflicting, or cannot prove a purpose-level change.",
+      "Return legacy decision as reuse_previous for same_purpose, regenerate for purpose_added/purpose_changed/purpose_removed, and needs_review for insufficient_evidence.",
+      "Never recommend changing active semantics for wording drift alone.",
       "Do not include raw source code, raw SQL, file paths, function names, class names, prompts, completions, secrets, ids, or hashes except the provided hashes.",
     ],
     output_shape: {
       decisions: [
         {
           operation_source_key: "route.POST./reports",
+          purpose_change_state: "same_purpose",
           decision: "reuse_previous",
           confidence: 0.82,
           reason:
             "The source changed but the privacy-safe evidence still supports the previous reports.create meaning.",
+          missing_context: [],
         },
       ],
     },
@@ -273,6 +379,7 @@ const buildAiReuseDecisionPrompt = ({
       previous_semantics: previousRoute.semantics,
       previous_operation_effects: previousRoute.operation_effects ?? [],
       current_evidence_summaries: route.evidence_summaries,
+      current_route_evidence_packet: route.route_evidence_packet,
     },
   });
 
@@ -280,8 +387,10 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
   if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.decisions)) {
     return {
       decision: "needs_review",
+      purpose_change_state: "insufficient_evidence",
       confidence: 0,
       reason: "AI reuse decision did not return the required decisions array.",
+      missing_context: ["AI reuse decision did not return a usable response."],
     };
   }
   const unknownDecision = parsed.decisions.find(
@@ -295,8 +404,10 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
   if (unknownDecision) {
     return {
       decision: "needs_review",
+      purpose_change_state: "insufficient_evidence",
       confidence: 0,
       reason: "AI reuse decision returned an unexpected route key.",
+      missing_context: ["AI reuse decision returned an unexpected route key."],
     };
   }
   const decision = safeArray(parsed?.decisions).find(
@@ -305,8 +416,10 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
   if (!decision || typeof decision !== "object") {
     return {
       decision: "needs_review",
+      purpose_change_state: "insufficient_evidence",
       confidence: 0,
       reason: "AI reuse decision omitted this changed route.",
+      missing_context: ["AI reuse decision omitted this changed route."],
     };
   }
   const normalizedDecision = [
@@ -316,8 +429,27 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
   ].includes(decision.decision)
     ? decision.decision
     : "needs_review";
+  const explicitPurposeState = PURPOSE_CHANGE_STATES.has(
+    decision.purpose_change_state,
+  )
+    ? decision.purpose_change_state
+    : null;
+  const purposeChangeState =
+    explicitPurposeState ??
+    {
+      reuse_previous: "same_purpose",
+      regenerate: "purpose_changed",
+      needs_review: "insufficient_evidence",
+    }[normalizedDecision];
+  const decisionFromPurpose =
+    purposeChangeState === "same_purpose"
+      ? "reuse_previous"
+      : purposeChangeState === "insufficient_evidence"
+        ? "needs_review"
+        : "regenerate";
   return {
-    decision: normalizedDecision,
+    decision: decisionFromPurpose,
+    purpose_change_state: purposeChangeState,
     confidence: Number.isFinite(Number(decision.confidence))
       ? Math.max(0, Math.min(1, Number(decision.confidence)))
       : 0,
@@ -325,6 +457,9 @@ const normalizeReuseDecision = ({ parsed, operationSourceKey }) => {
       typeof decision.reason === "string" && decision.reason.trim()
         ? decision.reason.trim()
         : "AI reuse decision did not include a reason.",
+    missing_context: stringArray(decision.missing_context, {
+      ai_context: {},
+    }),
   };
 };
 
@@ -367,10 +502,12 @@ const callAiReuseDecisionProvider = async ({
         : null;
     return {
       decision: "needs_review",
+      purpose_change_state: "insufficient_evidence",
       confidence: 0,
       reason: providerStatusMatch?.groups?.status
         ? `AI reuse decision failed: provider_${providerStatusMatch.groups.status}.`
         : "AI reuse decision returned malformed JSON.",
+      missing_context: ["AI reuse decision failed or returned malformed JSON."],
     };
   }
 };
@@ -1373,6 +1510,7 @@ const buildOperationAssignmentCollections = ({
   routeEvidenceRefs,
   catalogByGroup,
   aiSelectionDecisions,
+  existingEffectKeys = [],
 }) => {
   const operationEffects = [];
   const unresolvedOperationEffects = [];
@@ -1380,7 +1518,8 @@ const buildOperationAssignmentCollections = ({
   const mappings = [];
   const aiInferenceEvidence = [];
   const semanticMeaningCandidates = [];
-  const emittedEffectKeys = new Set();
+  const existingEffectKeySet = new Set(existingEffectKeys);
+  const emittedEffectKeys = new Set(existingEffectKeys);
 
   const candidates = normalizeAiOperationEffectCandidates(aiRoute);
   for (
@@ -1569,6 +1708,9 @@ const buildOperationAssignmentCollections = ({
       continue;
     }
     if (emittedEffectKeys.has(operationEffectKey)) {
+      if (existingEffectKeySet.has(operationEffectKey)) {
+        continue;
+      }
       unresolvedOperationEffects.push(
         unresolvedEffect({
           route,
@@ -1787,7 +1929,9 @@ const buildSnapshot = ({
   for (const [operationSourceKey, plan] of routePlans.entries()) {
     if (
       plan.origin === "unchanged_route_reused" ||
-      plan.origin === "changed_route_semantic_reused"
+      plan.origin === "changed_route_semantic_reused" ||
+      plan.active_semantic_source === "previous_kept_pending_review" ||
+      plan.purpose_change_state === "purpose_added"
     ) {
       reusedRouteKeys.push(operationSourceKey);
     }
@@ -1813,6 +1957,10 @@ const buildSnapshot = ({
     };
     const plan = routePlans.get(route.operation_source_key) ?? {
       origin: "new_route_ai_generated",
+      purpose_change_state: "new_route",
+      active_semantic_source: "new_confirmed",
+      stability_confidence: 1,
+      stability_missing_context: [],
       route_input_hash: routeInputHash(route),
     };
     const routeEvidenceRefs = buildSourceEvidenceRefs(
@@ -1821,15 +1969,17 @@ const buildSnapshot = ({
     );
     sourceEvidenceRefs.push(...routeEvidenceRefs);
     if (
-      (plan.origin === "unchanged_route_reused" ||
-        plan.origin === "changed_route_semantic_reused") &&
-      plan.previous_route
+      plan.previous_route &&
+      (plan.active_semantic_source === "previous_reused" ||
+        plan.active_semantic_source === "previous_kept_pending_review") &&
+      plan.purpose_change_state !== "purpose_added"
     ) {
       return rebasePreviousRoute({
         previousRoute: plan.previous_route,
         currentRoute: route,
         semanticSnapshotVersion: provisionalSemanticSnapshotVersion,
         plan,
+        routeEvidenceRefs,
       });
     }
     const aiRoute = aiRoutes.get(route.operation_source_key);
@@ -1869,6 +2019,12 @@ const buildSnapshot = ({
       routeEvidenceRefs,
       catalogByGroup,
       aiSelectionDecisions,
+      existingEffectKeys:
+        plan.purpose_change_state === "purpose_added"
+          ? safeArray(plan.previous_route?.operation_effects).map(
+              (effect) => effect.operation_effect_key,
+            )
+          : [],
     });
     targetObjectProfiles.push(...assignmentCollections.profiles);
     targetObjectMappings.push(...assignmentCollections.mappings);
@@ -1876,29 +2032,67 @@ const buildSnapshot = ({
     semanticMeaningCandidates.push(
       ...assignmentCollections.semanticMeaningCandidates,
     );
-    return {
-      ...baseRoute,
-      operation_effects: assignmentCollections.operationEffects,
-      unresolved_operation_effects:
-        assignmentCollections.unresolvedOperationEffects,
-      source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
-      route_input_hash: plan.route_input_hash,
-      previous_route_input_hash: plan.previous_route_input_hash,
-      previous_route_semantic_hash: plan.previous_route_semantic_hash,
-      semantic_origin:
-        plan.origin === "changed_route_needs_review" && aiRoute?.semantics
-          ? "changed_route_needs_review"
-          : plan.origin,
-      semantic_change_reason: plan.semantic_change_reason,
-      previous_semantic_snapshot_version:
-        plan.previous_route?.semantic_snapshot_version,
-      route_semantic_hash: routeSemanticHash({
+    if (plan.purpose_change_state === "purpose_added" && plan.previous_route) {
+      const rebasedPrevious = rebasePreviousRoute({
+        previousRoute: plan.previous_route,
+        currentRoute: route,
+        semanticSnapshotVersion: provisionalSemanticSnapshotVersion,
+        plan,
+        routeEvidenceRefs,
+      });
+      const previousEffectKeys = new Set(
+        safeArray(rebasedPrevious.operation_effects).map(
+          (effect) => effect.operation_effect_key,
+        ),
+      );
+      const appendedEffects = assignmentCollections.operationEffects.filter(
+        (effect) => !previousEffectKeys.has(effect.operation_effect_key),
+      );
+      const mergedRoute = {
+        ...rebasedPrevious,
+        operation_effects: [
+          ...safeArray(rebasedPrevious.operation_effects),
+          ...appendedEffects,
+        ],
+        unresolved_operation_effects: [
+          ...safeArray(rebasedPrevious.unresolved_operation_effects),
+          ...assignmentCollections.unresolvedOperationEffects,
+        ],
+        semantic_change_reason: plan.semantic_change_reason,
+      };
+      return {
+        ...mergedRoute,
+        route_semantic_hash: routeSemanticHash(mergedRoute),
+      };
+    }
+
+    return withStabilityMetadata({
+      currentRoute: route,
+      plan,
+      route: {
         ...baseRoute,
         operation_effects: assignmentCollections.operationEffects,
         unresolved_operation_effects:
           assignmentCollections.unresolvedOperationEffects,
-      }),
-    };
+        source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
+        route_input_hash: plan.route_input_hash,
+        previous_route_input_hash: plan.previous_route_input_hash,
+        previous_route_semantic_hash: plan.previous_route_semantic_hash,
+        semantic_origin:
+          plan.origin === "changed_route_needs_review" && aiRoute?.semantics
+            ? "changed_route_needs_review"
+            : plan.origin,
+        semantic_change_reason: plan.semantic_change_reason,
+        previous_semantic_snapshot_version:
+          plan.previous_route?.semantic_snapshot_version,
+        route_semantic_hash: routeSemanticHash({
+          ...baseRoute,
+          operation_effects: assignmentCollections.operationEffects,
+          unresolved_operation_effects:
+            assignmentCollections.unresolvedOperationEffects,
+        }),
+      },
+    });
   });
   addUniqueBy(
     targetObjectProfiles,
@@ -1942,7 +2136,7 @@ const buildSnapshot = ({
     idempotency_key: sha256(
       `${request.project_key}:${request.repository.repository_id}:${request.repository.merge_commit}:${request.repository.workflow_run_id ?? generatedAt}`,
     ),
-    schema_version: 2,
+    schema_version: SEMANTIC_SNAPSHOT_SCHEMA_VERSION,
     semantic_snapshot_version: semanticSnapshotVersion,
     generation_contract: generationContract,
     ai_runtime: aiRuntime,
@@ -1984,6 +2178,24 @@ const buildSnapshot = ({
         (route) =>
           route.semantic_origin === "changed_route_semantic_regenerated",
       ).length,
+      same_purpose_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "same_purpose",
+      ).length,
+      purpose_added_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "purpose_added",
+      ).length,
+      purpose_changed_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "purpose_changed",
+      ).length,
+      purpose_removed_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "purpose_removed",
+      ).length,
+      insufficient_evidence_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "insufficient_evidence",
+      ).length,
+      new_route_purpose_routes: versionedSnapshotRoutes.filter(
+        (route) => route.purpose_change_state === "new_route",
+      ).length,
     },
     routes: versionedSnapshotRoutes,
     target_object_profiles: targetObjectProfiles,
@@ -2228,10 +2440,87 @@ const hasReusablePreviousRouteSemantics = (route) =>
   Number(route?.semantics?.route_confidence ?? 0) > 0 &&
   route?.semantics?.route_summary !== "unknown";
 
+const normalizeRoutePathForPolicy = (path) => {
+  const trimmed = String(path ?? "").trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withSlash.replace(/\/{2,}/g, "/").replace(/\/$/g, "") || "/";
+};
+
+const isReservedClueBrowserTokenPath = (path) =>
+  /^\/(?:api\/(?:v[0-9]+\/)?)?clue\/browser-tokens?$/i.test(
+    normalizeRoutePathForPolicy(path),
+  );
+
+const routeSourceForPolicy = (route) =>
+  [
+    route?.ai_context?.route_decorator,
+    route?.ai_context?.source_snippet,
+    safeArray(route?.ai_context?.code_structure?.call_targets).join("\n"),
+  ]
+    .filter((entry) => typeof entry === "string")
+    .join("\n");
+
+const classifyClueInfrastructureRoute = (route) => {
+  const source = routeSourceForPolicy(route);
+  const reservedPath = isReservedClueBrowserTokenPath(route.path_template);
+  const proxiesToClueBrowserTokenApi =
+    /\/(?:api\/v[0-9]+\/)?ingest\/browser-tokens\b/i.test(source);
+  const usesServerSideClueApiKey = /\bCLUE_API_KEY\b|x-clue-api-key/i.test(
+    source,
+  );
+  if (
+    route.method === "POST" &&
+    reservedPath &&
+    proxiesToClueBrowserTokenApi &&
+    usesServerSideClueApiKey
+  ) {
+    return {
+      excluded: true,
+      reason:
+        "Clue SDK browser-token proxy route detected by reserved Clue path, Clue browser-token API proxy call, and server-side Clue API key usage.",
+      evidence: {
+        reserved_clue_path: true,
+        proxies_to_clue_browser_token_api: true,
+        uses_server_side_clue_api_key: true,
+      },
+    };
+  }
+  return {
+    excluded: false,
+    reason: null,
+    evidence: {
+      reserved_clue_path: reservedPath,
+      proxies_to_clue_browser_token_api: proxiesToClueBrowserTokenApi,
+      uses_server_side_clue_api_key: usesServerSideClueApiKey,
+    },
+  };
+};
+
+const splitSemanticProductRoutes = (routes) => {
+  const productRoutes = [];
+  const excludedInfrastructureRoutes = [];
+  for (const route of routes) {
+    const classification = classifyClueInfrastructureRoute(route);
+    if (classification.excluded) {
+      excludedInfrastructureRoutes.push({
+        operation_source_key: route.operation_source_key,
+        method: route.method,
+        path_template: route.path_template,
+        reason: classification.reason,
+        evidence: classification.evidence,
+      });
+      continue;
+    }
+    productRoutes.push(route);
+  }
+  return { productRoutes, excludedInfrastructureRoutes };
+};
+
 const buildRouteEvidencePromptEntry = ({ route, hashScope }) => ({
   operation_source_key: route.operation_source_key,
   method: route.method,
   path_template: route.path_template,
+  route_evidence_packet: buildRouteEvidencePacket(route, hashScope),
   evidence_summaries: buildSourceEvidenceRefs(route, hashScope).map(
     (entry, index) => ({
       evidence_index: index,
@@ -2251,6 +2540,7 @@ const classifyRoutesForSnapshot = async ({
   hashScope,
   generationContract,
   agentSkills,
+  purposeRecheckAllRoutes = false,
 }) => {
   const previousRoutes = previousRouteMap(previousSnapshot);
   const plans = new Map();
@@ -2262,6 +2552,10 @@ const classifyRoutesForSnapshot = async ({
     if (!previousRoute) {
       plans.set(route.operation_source_key, {
         origin: "new_route_ai_generated",
+        purpose_change_state: "new_route",
+        active_semantic_source: "new_confirmed",
+        stability_confidence: 1,
+        stability_missing_context: [],
         route_input_hash: currentHash,
       });
       routesRequiringGeneration.push(route);
@@ -2272,8 +2566,86 @@ const classifyRoutesForSnapshot = async ({
       previousRoute.route_input_hash === currentHash &&
       hasReusablePreviousRouteSemantics(previousRoute)
     ) {
+      if (purposeRecheckAllRoutes) {
+        const decision = await callAiReuseDecisionProvider({
+          request,
+          env,
+          apiKey: aiProviderApiKey,
+          route: buildRouteEvidencePromptEntry({ route, hashScope }),
+          previousRoute,
+          currentHash,
+          generationContract,
+          agentSkills,
+        });
+        if (
+          decision.purpose_change_state === "same_purpose" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "unchanged_route_reused",
+            purpose_change_state: "same_purpose",
+            active_semantic_source: "previous_reused",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            route_input_hash: currentHash,
+            previous_route: previousRoute,
+            previous_route_input_hash: previousRoute.route_input_hash,
+            previous_route_semantic_hash:
+              previousRoute.route_semantic_hash ??
+              routeSemanticHash(previousRoute),
+            semantic_change_reason: sanitizeText(
+              `Periodic full purpose check confirmed previous semantics still apply: ${decision.reason}`,
+              route,
+            ),
+          });
+          continue;
+        }
+        if (
+          decision.decision === "regenerate" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "changed_route_semantic_regenerated",
+            purpose_change_state: decision.purpose_change_state,
+            active_semantic_source: "new_confirmed",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            route_input_hash: currentHash,
+            previous_route: previousRoute,
+            previous_route_input_hash: previousRoute.route_input_hash,
+            previous_route_semantic_hash:
+              previousRoute.route_semantic_hash ??
+              routeSemanticHash(previousRoute),
+            semantic_change_reason: sanitizeText(decision.reason, route),
+          });
+          routesRequiringGeneration.push(route);
+          continue;
+        }
+        plans.set(route.operation_source_key, {
+          origin: "changed_route_needs_review",
+          purpose_change_state: "insufficient_evidence",
+          active_semantic_source: "previous_kept_pending_review",
+          stability_confidence: decision.confidence,
+          stability_missing_context: decision.missing_context,
+          route_input_hash: currentHash,
+          previous_route: previousRoute,
+          previous_route_input_hash: previousRoute.route_input_hash,
+          previous_route_semantic_hash:
+            previousRoute.route_semantic_hash ??
+            routeSemanticHash(previousRoute),
+          semantic_change_reason: sanitizeText(
+            `Periodic full purpose check could not prove a purpose-level change: ${decision.reason}`,
+            route,
+          ),
+        });
+        continue;
+      }
       plans.set(route.operation_source_key, {
         origin: "unchanged_route_reused",
+        purpose_change_state: "same_purpose",
+        active_semantic_source: "previous_reused",
+        stability_confidence: 1,
+        stability_missing_context: [],
         route_input_hash: currentHash,
         previous_route: previousRoute,
         previous_route_input_hash: previousRoute.route_input_hash,
@@ -2288,6 +2660,12 @@ const classifyRoutesForSnapshot = async ({
     if (previousRoute.route_input_hash === currentHash) {
       plans.set(route.operation_source_key, {
         origin: "changed_route_semantic_regenerated",
+        purpose_change_state: "new_route",
+        active_semantic_source: "new_confirmed",
+        stability_confidence: 0,
+        stability_missing_context: [
+          "Previous route semantic confidence was too low for stable reuse.",
+        ],
         route_input_hash: currentHash,
         previous_route: previousRoute,
         previous_route_input_hash: previousRoute.route_input_hash,
@@ -2310,9 +2688,16 @@ const classifyRoutesForSnapshot = async ({
       generationContract,
       agentSkills,
     });
-    if (decision.decision === "reuse_previous" && decision.confidence >= 0.75) {
+    if (
+      decision.purpose_change_state === "same_purpose" &&
+      decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+    ) {
       plans.set(route.operation_source_key, {
         origin: "changed_route_semantic_reused",
+        purpose_change_state: "same_purpose",
+        active_semantic_source: "previous_reused",
+        stability_confidence: decision.confidence,
+        stability_missing_context: decision.missing_context,
         route_input_hash: currentHash,
         previous_route: previousRoute,
         previous_route_input_hash: previousRoute.route_input_hash,
@@ -2322,9 +2707,16 @@ const classifyRoutesForSnapshot = async ({
       });
       continue;
     }
-    if (decision.decision === "reuse_previous") {
+    if (
+      decision.purpose_change_state === "same_purpose" ||
+      decision.purpose_change_state === "insufficient_evidence"
+    ) {
       plans.set(route.operation_source_key, {
         origin: "changed_route_needs_review",
+        purpose_change_state: "insufficient_evidence",
+        active_semantic_source: "previous_kept_pending_review",
+        stability_confidence: decision.confidence,
+        stability_missing_context: decision.missing_context,
         route_input_hash: currentHash,
         previous_route: previousRoute,
         previous_route_input_hash: previousRoute.route_input_hash,
@@ -2337,9 +2729,16 @@ const classifyRoutesForSnapshot = async ({
       });
       continue;
     }
-    if (decision.decision === "regenerate") {
+    if (
+      decision.decision === "regenerate" &&
+      decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+    ) {
       plans.set(route.operation_source_key, {
         origin: "changed_route_semantic_regenerated",
+        purpose_change_state: decision.purpose_change_state,
+        active_semantic_source: "new_confirmed",
+        stability_confidence: decision.confidence,
+        stability_missing_context: decision.missing_context,
         route_input_hash: currentHash,
         previous_route: previousRoute,
         previous_route_input_hash: previousRoute.route_input_hash,
@@ -2352,6 +2751,10 @@ const classifyRoutesForSnapshot = async ({
     }
     plans.set(route.operation_source_key, {
       origin: "changed_route_needs_review",
+      purpose_change_state: "insufficient_evidence",
+      active_semantic_source: "previous_kept_pending_review",
+      stability_confidence: decision.confidence,
+      stability_missing_context: decision.missing_context,
       route_input_hash: currentHash,
       previous_route: previousRoute,
       previous_route_input_hash: previousRoute.route_input_hash,
@@ -2380,7 +2783,14 @@ const rebasePreviousRoute = ({
   currentRoute,
   semanticSnapshotVersion,
   plan,
+  routeEvidenceRefs = [],
 }) => {
+  const sourceEvidenceRefs = [
+    ...new Set([
+      ...safeArray(previousRoute.source_evidence_refs),
+      ...routeEvidenceRefs.map((entry) => entry.id),
+    ]),
+  ];
   const route = {
     ...previousRoute,
     operation_source_key: currentRoute.operation_source_key,
@@ -2395,6 +2805,11 @@ const rebasePreviousRoute = ({
     previous_route_semantic_hash: plan.previous_route_semantic_hash,
     semantic_origin: plan.origin,
     semantic_change_reason: plan.semantic_change_reason,
+    purpose_change_state: plan.purpose_change_state,
+    active_semantic_source: plan.active_semantic_source,
+    semantic_stability: buildSemanticStability(plan),
+    evidence_packet_summary: buildEvidencePacketSummary(currentRoute),
+    source_evidence_refs: sourceEvidenceRefs,
   };
   return {
     ...route,
@@ -2402,6 +2817,42 @@ const rebasePreviousRoute = ({
   };
 };
 
+const buildSemanticStability = (plan) => ({
+  purpose_change_state: plan.purpose_change_state ?? "new_route",
+  confidence:
+    typeof plan.stability_confidence === "number"
+      ? Math.max(0, Math.min(1, plan.stability_confidence))
+      : plan.purpose_change_state === "new_route"
+        ? 1
+        : 0,
+  reason:
+    plan.semantic_change_reason ??
+    (plan.purpose_change_state === "new_route"
+      ? "No previous route semantic existed, so a new active semantic was generated."
+      : "Semantic purpose stability was evaluated for this route."),
+  ...(plan.previous_route_input_hash
+    ? { previous_route_input_hash: plan.previous_route_input_hash }
+    : {}),
+  ...(plan.previous_route_semantic_hash
+    ? { previous_route_semantic_hash: plan.previous_route_semantic_hash }
+    : {}),
+  ...(plan.previous_route?.semantic_snapshot_version
+    ? {
+        previous_semantic_snapshot_version:
+          plan.previous_route.semantic_snapshot_version,
+      }
+    : {}),
+  missing_context: safeArray(plan.stability_missing_context),
+});
+
+const withStabilityMetadata = ({ route, currentRoute, plan }) => ({
+  ...route,
+  purpose_change_state: plan.purpose_change_state,
+  active_semantic_source: plan.active_semantic_source,
+  semantic_stability: buildSemanticStability(plan),
+  evidence_packet_summary: buildEvidencePacketSummary(currentRoute),
+});
+
 const fieldPathMatchesKeys = ({
   fieldPath,
   routeKeys,
@@ -2813,6 +3264,10 @@ const assertSemanticSnapshotAudit = ({
   const routeByKey = new Map(
     routes.map((route) => [route.operation_source_key, route]),
   );
+  const previousActiveSources = new Set([
+    "previous_reused",
+    "previous_kept_pending_review",
+  ]);
   const allowedOrigins = new Set([
     "new_route_ai_generated",
     "unchanged_route_reused",
@@ -2843,6 +3298,56 @@ const assertSemanticSnapshotAudit = ({
         `semantic snapshot audit found stale route_semantic_hash: ${route.operation_source_key}`,
       );
     }
+    if (auditedSnapshot.schema_version >= 3) {
+      if (route.semantic_stability.purpose_change_state !== route.purpose_change_state) {
+        throw new Error(
+          `semantic snapshot audit found mismatched purpose stability metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        (!route.previous_route_input_hash ||
+          !route.previous_route_semantic_hash ||
+          !route.previous_semantic_snapshot_version)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found incomplete previous active semantic metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        route.route_semantic_hash !== route.previous_route_semantic_hash
+      ) {
+        throw new Error(
+          `semantic snapshot audit found changed active semantics for previous-backed route: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_kept_pending_review" &&
+        (route.purpose_change_state !== "insufficient_evidence" ||
+          route.semantic_origin !== "changed_route_needs_review")
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent pending-review semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_reused" &&
+        route.purpose_change_state !== "same_purpose"
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent reused semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.purpose_change_state === "purpose_added" &&
+        (!route.previous_route_input_hash || !route.previous_route_semantic_hash)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found missing previous metadata for added purpose: ${route.operation_source_key}`,
+        );
+      }
+    }
     if (
       (route.semantic_origin === "unchanged_route_reused" ||
         route.semantic_origin === "changed_route_semantic_reused") &&
@@ -2883,10 +3388,12 @@ export const runSemanticCi = async ({
     allowedSourcePaths: request.allowed_source_paths,
     excludedSourcePaths: request.excluded_source_paths,
   });
-  const routes = await analyzeFastApiRoutes({ repoRoot, files });
+  const discoveredRoutes = await analyzeFastApiRoutes({ repoRoot, files });
+  const { productRoutes: routes, excludedInfrastructureRoutes } =
+    splitSemanticProductRoutes(discoveredRoutes);
   if (routes.length === 0) {
     throw new Error(
-      "semantic CI discovered zero routes; check framework, backend root path, and allowed_source_paths",
+      "semantic CI discovered zero routes after infrastructure exclusions; check framework, backend root path, allowed_source_paths, and infrastructure route exclusions",
     );
   }
   if (!env.CLUE_API_KEY) {
@@ -2897,12 +3404,14 @@ export const runSemanticCi = async ({
       ? await fetchLatestSnapshot({ request, env })
       : validatePreviousSnapshotForReuse(providedPreviousSnapshot);
   const previousRoutes = previousRouteMap(previousSnapshot);
+  const purposeRecheckAllRoutes = shouldPurposeRecheckAllRoutes(env);
   const routeNeedsAi = routes.some((route) => {
     const previousRoute = previousRoutes.get(route.operation_source_key);
     return (
       !previousRoute ||
       previousRoute.route_input_hash !== routeInputHash(route) ||
-      !hasReusablePreviousRouteSemantics(previousRoute)
+      !hasReusablePreviousRouteSemantics(previousRoute) ||
+      purposeRecheckAllRoutes
     );
   });
   if (routeNeedsAi && !env.CLUE_AI_PROVIDER_API_KEY) {
@@ -2935,6 +3444,7 @@ export const runSemanticCi = async ({
     hashScope,
     generationContract,
     agentSkills,
+    purposeRecheckAllRoutes,
   });
   const promptRoutes = routesRequiringGeneration.map((route) =>
     buildRouteEvidencePromptEntry({ route, hashScope }),
@@ -2989,6 +3499,7 @@ export const runSemanticCi = async ({
   return {
     accepted: upload.accepted === true,
     route_count: snapshot.routes.length,
+    excluded_infrastructure_routes: excludedInfrastructureRoutes,
     upload,
   };
 };
@@ -2999,10 +3510,12 @@ export const runSemanticInventory = async ({ repoRoot, request }) => {
     allowedSourcePaths: request.allowed_source_paths,
     excludedSourcePaths: request.excluded_source_paths,
   });
-  const routes = await analyzeFastApiRoutes({ repoRoot, files });
+  const discoveredRoutes = await analyzeFastApiRoutes({ repoRoot, files });
+  const { productRoutes: routes, excludedInfrastructureRoutes } =
+    splitSemanticProductRoutes(discoveredRoutes);
   if (routes.length === 0) {
     throw new Error(
-      "semantic inventory discovered zero routes; check framework, backend root path, and allowed_source_paths",
+      "semantic inventory discovered zero routes after infrastructure exclusions; check framework, backend root path, allowed_source_paths, and infrastructure route exclusions",
     );
   }
   return {
@@ -3010,7 +3523,9 @@ export const runSemanticInventory = async ({ repoRoot, request }) => {
     service_key: request.service_key,
     allowed_source_paths: request.allowed_source_paths,
     excluded_source_paths: request.excluded_source_paths,
+    discovered_route_count: discoveredRoutes.length,
     route_count: routes.length,
+    excluded_infrastructure_routes: excludedInfrastructureRoutes,
     operation_source_keys: routes.map((route) => route.operation_source_key),
     routes: routes.map((route) => ({
       operation_source_key: route.operation_source_key,