@clue-ai/cli 0.0.15 → 0.0.17

package/src/semantic-ci.mjs

@@ -80,12 +80,22 @@ 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 semanticSnapshotHashScope = (request) =>
   [
@@ -176,6 +186,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 +283,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 +324,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 +340,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 +376,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 +384,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 +401,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 +413,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 +426,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 +454,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 +499,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 +1507,7 @@ const buildOperationAssignmentCollections = ({
   routeEvidenceRefs,
   catalogByGroup,
   aiSelectionDecisions,
+  existingEffectKeys = [],
 }) => {
   const operationEffects = [];
   const unresolvedOperationEffects = [];
@@ -1380,7 +1515,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 +1705,9 @@ const buildOperationAssignmentCollections = ({
       continue;
     }
     if (emittedEffectKeys.has(operationEffectKey)) {
+      if (existingEffectKeySet.has(operationEffectKey)) {
+        continue;
+      }
       unresolvedOperationEffects.push(
         unresolvedEffect({
           route,
@@ -1787,7 +1926,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 +1954,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 +1966,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 +2016,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,7 +2029,44 @@ const buildSnapshot = ({
     semanticMeaningCandidates.push(
       ...assignmentCollections.semanticMeaningCandidates,
     );
-    return {
+    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:
@@ -1898,7 +2088,8 @@ const buildSnapshot = ({
         unresolved_operation_effects:
           assignmentCollections.unresolvedOperationEffects,
       }),
-    };
+      },
+    });
   });
   addUniqueBy(
     targetObjectProfiles,
@@ -1942,7 +2133,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 +2175,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 +2437,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,
@@ -2262,6 +2548,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);
@@ -2274,6 +2564,10 @@ const classifyRoutesForSnapshot = async ({
     ) {
       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 +2582,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 +2610,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 +2629,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 +2651,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 +2673,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 +2705,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 +2727,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 +2739,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,
@@ -2452,7 +2825,7 @@ const reusablePreviousContext = ({ previousSnapshot, reusedRouteKeys }) => {
         ),
       ),
   ]);
-  const catalogs = safeArray(previousSnapshot?.target_object_catalog).filter(
+  const catalogCandidates = safeArray(previousSnapshot?.target_object_catalog).filter(
     (entry) => catalogKeys.has(entry.target_object_key),
   );
   const matches = (fieldPath) =>
@@ -2508,11 +2881,6 @@ const reusablePreviousContext = ({ previousSnapshot, reusedRouteKeys }) => {
   for (const mapping of mappings) {
     sourceEvidenceIds.add(mapping.grouping_evidence_ref);
   }
-  for (const catalog of catalogs) {
-    for (const ref of safeArray(catalog.grouping_evidence_refs)) {
-      sourceEvidenceIds.add(ref);
-    }
-  }
   for (const evidence of aiInferenceEvidence) {
     for (const ref of safeArray(evidence.input_source_evidence_refs)) {
       sourceEvidenceIds.add(ref);
@@ -2526,6 +2894,21 @@ const reusablePreviousContext = ({ previousSnapshot, reusedRouteKeys }) => {
       sourceEvidenceIds.add(ref);
     }
   }
+  const catalogs = catalogCandidates
+    .map((entry) => ({
+      ...entry,
+      raw_target_object_profile_refs: safeArray(
+        entry.raw_target_object_profile_refs,
+      ).filter((ref) => profileIds.has(ref)),
+      grouping_evidence_refs: safeArray(entry.grouping_evidence_refs).filter(
+        (ref) => sourceEvidenceIds.has(ref),
+      ),
+    }))
+    .filter(
+      (entry) =>
+        entry.raw_target_object_profile_refs.length > 0 &&
+        entry.grouping_evidence_refs.length > 0,
+    );
   const sourceEvidenceRefs = safeArray(
     previousSnapshot?.source_evidence_refs,
   ).filter((entry) => sourceEvidenceIds.has(entry.id));
@@ -2873,10 +3256,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) {
@@ -2979,6 +3364,7 @@ export const runSemanticCi = async ({
   return {
     accepted: upload.accepted === true,
     route_count: snapshot.routes.length,
+    excluded_infrastructure_routes: excludedInfrastructureRoutes,
     upload,
   };
 };
@@ -2989,10 +3375,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 {
@@ -3000,7 +3388,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,