opencode-skills-collection 3.0.35 → 3.0.37

package/bundled-skills/vercel-optimize/lib/verify-claim.mjs

@@ -0,0 +1,1296 @@
+// Pure async claim verifier. No LLM, no network — fs + grep only.
+
+import { readFile, access, readdir } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { dirname, isAbsolute, join, normalize } from 'node:path';
+import { promisify } from 'node:util';
+import { isKnownUrl, sanitizeCitations } from './citations.mjs';
+import { findRecContradictions } from './project-facts.mjs';
+import { canonicalizeRoute } from './route-normalize.mjs';
+
+const execFileP = promisify(execFile);
+const cacheInvalidationFileCache = new Map();
+
+// Bad inputs surface as `unsupported` — never throws.
+export async function verifyClaim(claim) {
+  if (!claim || typeof claim !== 'object') {
+    return { disposition: 'unverifiable', reason: 'claim is not an object' };
+  }
+  switch (claim.type) {
+    case 'file_exists':                  return verifyFileExists(claim);
+    case 'pattern_count':                return verifyPatternCount(claim);
+    case 'pattern_exists':               return verifyPatternExists(claim);
+    case 'pattern_absent':               return verifyPatternAbsent(claim);
+    case 'code_snippet':                 return verifyCodeSnippet(claim);
+    case 'repo_count':                   return verifyRepoCount(claim);
+    case 'citation_in_library':          return verifyCitationInLibrary(claim);
+    case 'citation_applies_to_version':  return verifyCitationAppliesToVersion(claim);
+    case 'cache_vary_matches_dynamic_inputs': return verifyCacheVaryMatchesDynamicInputs(claim);
+    case 'cache_vary_cardinality_safe': return verifyCacheVaryCardinalitySafe(claim);
+    case 'next_cached_not_found_causal_support': return verifyNextCachedNotFoundCausalSupport(claim);
+    case 'next_stable_cache_api_for_version': return verifyNextStableCacheApiForVersion(claim);
+    case 'next_runtime_cache_api_for_version': return verifyNextRuntimeCacheApiForVersion(claim);
+    case 'next_cache_components_runtime_cache_preference': return verifyNextCacheComponentsRuntimeCachePreference(claim);
+    case 'next_cache_life_single_execution': return verifyNextCacheLifeSingleExecution(claim);
+    case 'next_cache_lifetime_freshness_supported': return verifyNextCacheLifetimeFreshnessSupported(claim);
+    case 'next_cache_components_route_chain_file': return verifyNextCacheComponentsRouteChainFile(claim);
+    case 'next_cache_life_cdn_header_semantics': return verifyNextCacheLifeCdnHeaderSemantics(claim);
+    case 'image_response_headers_citation': return verifyImageResponseHeadersCitation(claim);
+    case 'next_image_priority_api_for_version': return verifyNextImagePriorityApiForVersion(claim);
+    case 'next_cache_components_route_segment_config': return verifyNextCacheComponentsRouteSegmentConfig(claim);
+    case 'next_route_revalidate_static_prereq': return verifyNextRouteRevalidateStaticPrereq(claim);
+    case 'next_cache_tag_invalidation_supported': return verifyNextCacheTagInvalidationSupported(claim);
+    case 'cache_rec_not_error_dominated_or_acknowledged': return verifyCacheRecNotErrorDominatedOrAcknowledged(claim);
+    case 'cache_control_header_syntax': return verifyCacheControlHeaderSyntax(claim);
+    case 'cache_control_headers_citation': return verifyCacheControlHeadersCitation(claim);
+    case 'cache_policy_positive_or_no_ready_rec': return verifyCachePolicyPositiveOrNoReadyRec(claim);
+    case 'cache_404_long_ttl_safety': return verifyCache404LongTtlSafety(claim);
+    case 'route_error_not_found_status_and_scope': return verifyRouteErrorNotFoundStatusAndScope(claim);
+    case 'immutable_dynamic_route_safety': return verifyImmutableDynamicRouteSafety(claim);
+    case 'auth_guard_parallelization_safety': return verifyAuthGuardParallelizationSafety(claim);
+    case 'parallelization_impact_not_overclaimed': return verifyParallelizationImpactNotOverclaimed(claim);
+    case 'parallelization_not_cpu_bound_work': return verifyParallelizationNotCpuBoundWork(claim);
+    case 'runtime_error_cause_supported': return verifyRuntimeErrorCauseSupported(claim);
+    case 'vercel_ignore_command_project_state': return verifyVercelIgnoreCommandProjectState(claim);
+    case 'turbo_build_cache_safety': return verifyTurboBuildCacheSafety(claim);
+    case 'does_not_contradict_project_config': return verifyNoProjectConfigContradiction(claim);
+    default:
+      return { disposition: 'unverifiable', reason: `unknown claim type: ${claim.type}` };
+  }
+}
+
+// Catches "enable fluid compute" recs that the brief negative-space filter let through.
+async function verifyNoProjectConfigContradiction({ rec, projectFacts }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'no rec attached to claim' };
+  if (!Array.isArray(projectFacts) || projectFacts.length === 0) {
+    return { disposition: 'unverifiable', reason: 'no project facts available' };
+  }
+  const hits = findRecContradictions(rec, projectFacts);
+  if (hits.length === 0) {
+    return { disposition: 'verified', reason: 'rec does not contradict any already-on project setting' };
+  }
+  const ids = hits.map((h) => h.id).join(', ');
+  return {
+    disposition: 'failed',
+    reason: `rec contradicts project config: recommends toggling on already-enabled ${ids}`,
+  };
+}
+
+async function verifyFileExists(claim) {
+  const { file } = claim;
+  if (!file) return { disposition: 'unsupported', reason: 'file_exists requires file' };
+  try {
+    await firstAccessiblePath(claim);
+    return { disposition: 'verified', reason: `${file} exists` };
+  } catch {
+    return { disposition: 'failed', reason: `${file} does not exist` };
+  }
+}
+
+async function verifyPatternCount(claim) {
+  const { file, pattern, expected } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'pattern_count requires file + pattern' };
+  let content;
+  try { ({ content } = await readClaimFile(claim)); }
+  catch { return { disposition: 'failed', reason: `cannot read ${file}` }; }
+
+  // "42" alone (from `filename:42`) is a line number, not a pattern.
+  if (/^\d+$/.test(pattern.trim())) {
+    return { disposition: 'unsupported', reason: 'pattern looks like a line number, not a pattern' };
+  }
+
+  const re = compilePattern(pattern, 'g');
+  const matches = content.match(re) ?? [];
+  const actual = matches.length;
+  return actual === expected
+    ? { disposition: 'verified', actual, expected, reason: 'exact count match' }
+    : { disposition: 'failed', actual, expected, reason: `count mismatch: claim=${expected}, actual=${actual}` };
+}
+
+async function verifyPatternExists(claim) {
+  const { file, pattern } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'pattern_exists requires file + pattern' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const found = compilePattern(pattern, '').test(content);
+    return { disposition: found ? 'verified' : 'failed', reason: found ? 'pattern present' : 'pattern not found' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyPatternAbsent(claim) {
+  const { file, pattern } = claim;
+  if (!file || !pattern) return { disposition: 'unsupported', reason: 'prose-of-absence: claim requires file + pattern to verify' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const found = compilePattern(pattern, '').test(content);
+    return { disposition: !found ? 'verified' : 'failed', reason: !found ? 'pattern absent as claimed' : 'pattern present despite claim of absence' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyCodeSnippet(claim) {
+  const { file, snippet, repoRoot = '.' } = claim;
+  if (!file || !snippet) return { disposition: 'unsupported', reason: 'code_snippet requires file + snippet' };
+  try {
+    const { content } = await readClaimFile(claim);
+    const norm = (s) => s.replace(/\s+/g, ' ').trim();
+    if (norm(content).includes(norm(snippet))) {
+      return { disposition: 'verified', reason: 'snippet found in cited file' };
+    }
+    const elsewhere = await snippetFoundElsewhere(repoRoot, snippet, file);
+    if (elsewhere) {
+      return { disposition: 'unsupported', reason: `snippet exists in ${elsewhere}, not in cited ${file}` };
+    }
+    return { disposition: 'failed', reason: 'snippet not found in cited file or repo' };
+  } catch {
+    return { disposition: 'failed', reason: `cannot read ${file}` };
+  }
+}
+
+async function verifyRepoCount({ pattern, expected, repoRoot = '.' }) {
+  if (!pattern || expected == null) return { disposition: 'unsupported', reason: 'repo_count requires pattern + expected' };
+  let actual = 0;
+  const re = compilePattern(pattern, '');
+  for await (const path of walkFiles(repoRoot)) {
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (re.test(content)) actual++;
+    } catch {}
+  }
+  return actual === expected
+    ? { disposition: 'verified', actual, expected, reason: 'exact file count match' }
+    : { disposition: 'failed', actual, expected, reason: `file count: claim=${expected}, actual=${actual}` };
+}
+
+async function verifyCitationInLibrary({ url }) {
+  if (!url) return { disposition: 'unsupported', reason: 'citation_in_library requires url' };
+  if (/^[\w-]+:[\w-]+$/.test(url)) {
+    return { disposition: 'verified', reason: 'skill-rule reference format (allowed)' };
+  }
+  const known = await isKnownUrl(url);
+  return known
+    ? { disposition: 'verified', reason: 'URL in curated library' }
+    : { disposition: 'failed', reason: 'URL not in curated library — likely hallucination' };
+}
+
+async function verifyCitationAppliesToVersion({ url, framework, frameworkVersion }) {
+  if (!url || !framework || !frameworkVersion) {
+    return { disposition: 'unsupported', reason: 'requires url + framework + frameworkVersion' };
+  }
+  const fakeRec = { citations: [url] };
+  const { rec, strippedVersion, strippedUnknown } = await sanitizeCitations(fakeRec, framework, frameworkVersion);
+  if (strippedUnknown.length > 0) {
+    return { disposition: 'failed', reason: 'URL not in library' };
+  }
+  if (strippedVersion.length > 0) {
+    return { disposition: 'failed', reason: `URL not applicable to ${framework}@${frameworkVersion}` };
+  }
+  return rec.citations.length > 0
+    ? { disposition: 'verified', reason: `URL applies to ${framework}@${frameworkVersion}` }
+    : { disposition: 'unsupported', reason: 'sanitizer stripped all citations for unknown reason' };
+}
+
+async function verifyCacheVaryMatchesDynamicInputs({ rec, files, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec || !Array.isArray(files) || files.length === 0) {
+    return { disposition: 'unsupported', reason: 'cache_vary_matches_dynamic_inputs requires rec + files' };
+  }
+
+  let usesVercelGeo = false;
+  for (const file of files) {
+    try {
+      const { content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      if (/\bgeolocation\s*\(/.test(content) ||
+          /\b\w+\.geo\??\./.test(content) ||
+          /['"]x-vercel-ip-(?:country|country-region|city|latitude|longitude|postal-code|timezone)['"]/i.test(content)) {
+        usesVercelGeo = true;
+        break;
+      }
+    } catch {}
+  }
+  if (!usesVercelGeo) {
+    return { disposition: 'verified', reason: 'cache rec does not touch Vercel geolocation inputs' };
+  }
+
+  const text = [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior, rec.verify]
+    .filter(Boolean)
+    .join('\n');
+  const hasCoarseGeoVary = hasHeaderValue(text, 'Vary', /(?:^|,\s*)X-Vercel-IP-(?:Country|Country-Region|City)(?:\s*,|$)/i);
+  if (hasCoarseGeoVary) {
+    return { disposition: 'verified', reason: 'cache rec varies by a coarse Vercel geolocation header for geolocation-dependent output' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache rec touches Vercel geolocation but does not vary by a coarse Vercel geolocation header such as X-Vercel-IP-Country, X-Vercel-IP-Country-Region, or X-Vercel-IP-City',
+  };
+}
+
+async function verifyCacheVaryCardinalitySafe({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_vary_cardinality_safe requires rec' };
+  const text = recText(rec);
+  const varyValues = extractHeaderValues(text, 'Vary').join(', ');
+  if (!varyValues) {
+    return { disposition: 'verified', reason: 'no concrete Vary header value detected' };
+  }
+  if (/\bX-Vercel-IP-(?:Latitude|Longitude|Postal-Code)\b/i.test(varyValues)) {
+    return {
+      disposition: 'failed',
+      reason: 'Vary on X-Vercel-IP-Latitude, X-Vercel-IP-Longitude, or X-Vercel-IP-Postal-Code creates very high-cardinality CDN cache keys; use a coarser geography header when safe, or leave the response uncached',
+    };
+  }
+  return { disposition: 'verified', reason: 'Vary header avoids known high-cardinality geolocation headers' };
+}
+
+async function verifyNextCachedNotFoundCausalSupport({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cached_not_found_causal_support requires rec' };
+  const text = recText(rec);
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  const hasSpecificCitation = /nextjs\.org\/docs\/app\/api-reference\/functions\/not-found/i.test(citations) &&
+    /nextjs\.org\/docs\/app\/api-reference\/directives\/use-cache/i.test(citations);
+  const hasRuntimeStack = /\b(?:stack|logs?|trace)\b[\s\S]{0,120}\b(?:NEXT_|notFound|NEXT_HTTP_ERROR_FALLBACK|Error:)\b/i.test(text);
+  if (hasSpecificCitation || hasRuntimeStack) {
+    return { disposition: 'verified', reason: 'cached notFound causal claim has Next-specific citation or runtime stack evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'notFound() inside use cache was claimed as a 5xx cause without Next-specific citation or runtime stack evidence',
+  };
+}
+
+async function verifyNextStableCacheApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_stable_cache_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'stable Next.js 16 cache API requirement does not apply' };
+  }
+  const text = recText(rec);
+  if (/\bunstable_(?:cacheLife|cacheTag)\b/.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 rec uses unstable cache API; use cacheLife/cacheTag from next/cache',
+    };
+  }
+  if (/\brevalidateTag\s*\([^)]*['"`][^'"`]+['"`]\s*\)/.test(text) &&
+      !/\brevalidateTag\s*\([^)]*['"`][^'"`]+['"`]\s*,/.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 revalidateTag examples must include the cache-life profile argument',
+    };
+  }
+  return { disposition: 'verified', reason: 'Next.js 16 cache API usage matches stable names' };
+}
+
+async function verifyNextRuntimeCacheApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_runtime_cache_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Next.js 16 Runtime Cache API requirement does not apply' };
+  }
+  const text = recText(rec);
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/\bunstable_cache\b/.test(text) &&
+      (/\bRuntime Cache\b/i.test(text) || /vercel\.com\/docs\/caching\/runtime-cache/i.test(citations))) {
+    return {
+      disposition: 'failed',
+      reason: 'Next.js 16 Runtime Cache recommendations must use use cache: remote or fetch with force-cache, not unstable_cache',
+    };
+  }
+  return { disposition: 'verified', reason: 'Next.js Runtime Cache API usage matches project version' };
+}
+
+async function verifyNextCacheComponentsRuntimeCachePreference({ rec, framework, cacheComponents }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_runtime_cache_preference requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const text = recText(rec);
+  if (/\buse cache:\s*remote\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'recommendation uses framework-native remote cache for Cache Components project' };
+  }
+  if (/\b(?:fallback|only if|when Cache Components (?:is|are) unavailable|if cacheComponents is false)\b[^.\n]{0,180}\b(?:Runtime Cache|@vercel\/functions|getCache\s*\()/i.test(text)) {
+    return { disposition: 'verified', reason: 'Runtime Cache is framed as a fallback, not the primary Cache Components path' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Next.js Cache Components is enabled; prefer `use cache: remote` before recommending lower-level Runtime Cache APIs',
+  };
+}
+
+async function verifyNextCacheLifeSingleExecution({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_life_single_execution requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Next.js 16 cacheLife execution rule does not apply' };
+  }
+  const text = recText(rec);
+  const calls = [...text.matchAll(/\bcacheLife\s*\(/g)].map((m) => m.index ?? -1).filter((i) => i >= 0);
+  if (calls.length <= 1) {
+    return { disposition: 'verified', reason: 'at most one cacheLife() call appears in the recommendation' };
+  }
+  for (let i = 0; i < calls.length - 1; i++) {
+    const between = text.slice(calls[i], calls[i + 1]);
+    if (/\b(?:if|else|switch|case)\b|[?:]/.test(between)) continue;
+    return {
+      disposition: 'failed',
+      reason: 'multiple cacheLife() calls appear on one recommended code path; only one should execute per function invocation',
+    };
+  }
+  return { disposition: 'verified', reason: 'multiple cacheLife() calls appear only in separate control-flow branches' };
+}
+
+async function verifyNextCacheLifetimeFreshnessSupported({ rec, files, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_lifetime_freshness_supported requires rec' };
+  const text = recText(rec);
+  if (!/\bcacheLife\s*\(/.test(text)) {
+    return { disposition: 'verified', reason: 'no cacheLife() lifetime change detected' };
+  }
+
+  const tags = dedupeCacheTags([
+    ...extractCacheTags(text),
+    ...await extractCacheTagsFromFiles(files, repoRoot, projectRootDirectory),
+  ]);
+  if (tags.length === 0) {
+    if (cacheLifeNeedsContentFreshnessProof(text)) {
+      return {
+        disposition: 'failed',
+        reason: 'cacheLife() lengthens content-derived data without cacheTag/revalidateTag evidence; add invalidation evidence or keep the finding out of the ready-to-apply list',
+      };
+    }
+    return { disposition: 'unverifiable', reason: 'cacheLife() rec has no cacheTag evidence to verify against invalidation' };
+  }
+
+  const recTextAsFile = [{ path: '<recommendation>', content: text }];
+  const invalidationFiles = [
+    ...recTextAsFile,
+    ...await readCacheInvalidationFiles(repoRoot, projectRootDirectory),
+  ];
+  const missing = tags.filter((tag) => !tagHasMatchingInvalidation(tag, invalidationFiles));
+  if (missing.length === 0) {
+    return { disposition: 'verified', reason: 'cacheLife() freshness change has matching cache tag invalidation evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `cacheLife() would lengthen tagged content without matching revalidateTag/updateTag evidence for: ${missing.map((t) => t.label).join(', ')}`,
+  };
+}
+
+async function verifyNextCacheComponentsRouteChainFile({ rec, framework, frameworkVersion, cacheComponents, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_route_chain_file requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Cache Components route-chain check does not apply' };
+  }
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const targetRoute = routeFromCandidateRef(rec.candidateRef);
+  if (!targetRoute) {
+    return { disposition: 'unverifiable', reason: 'Cache Components layout recommendation has no route candidateRef' };
+  }
+  const routeRows = Array.isArray(signals?.codebase?.routes) ? signals.codebase.routes : [];
+  if (routeRows.length === 0) {
+    return { disposition: 'unverifiable', reason: 'codebase route map unavailable for layout route-chain check' };
+  }
+  const layoutFiles = recommendationFilesFromRec(rec)
+    .filter((file) => /(^|\/)layout\.(?:tsx?|jsx?)$/.test(String(file)));
+  if (layoutFiles.length === 0) {
+    return { disposition: 'verified', reason: 'no layout files named in recommendation' };
+  }
+  const layoutRoutes = routeRows.filter((route) =>
+    route?.type === 'layout' &&
+    route?.file &&
+    layoutFiles.some((file) => pathSuffixMatches(file, route.file))
+  );
+  if (layoutRoutes.length === 0) {
+    return {
+      disposition: 'failed',
+      reason: 'Cache Components recommendation cites a layout file that is not present in the scanned route map',
+    };
+  }
+  const target = normalizeRouteForLayoutMatch(targetRoute);
+  const matchingLayout = layoutRoutes.find((layout) =>
+    layoutAppliesToCandidateRoute(layout.routePath, target)
+  );
+  if (matchingLayout) {
+    return {
+      disposition: 'verified',
+      reason: `layout ${matchingLayout.file} is in the observed route chain for ${targetRoute}`,
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Cache Components recommendation cites a layout file outside the observed route chain for this candidate route',
+  };
+}
+
+async function verifyNextCacheLifeCdnHeaderSemantics({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_life_cdn_header_semantics requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 15) {
+    return { disposition: 'verified', reason: 'Cache Components cacheLife semantics do not apply to this Next.js version' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cacheLife() controls the Cache Components lifetime and defaults to the default profile when omitted; do not claim it emits CDN Cache-Control headers or that missing cacheLife alone makes a route run per request without production header evidence',
+  };
+}
+
+async function verifyImageResponseHeadersCitation({ rec, framework }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'image_response_headers_citation requires rec' };
+  if (framework && framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/nextjs\.org\/docs\/app\/api-reference\/functions\/image-response/i.test(citations)) {
+    return { disposition: 'verified', reason: 'ImageResponse header option is backed by the ImageResponse API reference' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'ImageResponse header changes need the ImageResponse API reference citation',
+  };
+}
+
+async function verifyNextImagePriorityApiForVersion({ rec, framework, frameworkVersion }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_image_priority_api_for_version requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'next/image priority deprecation does not apply before Next.js 16' };
+  }
+  const text = recText(rec);
+  if (/\b(?:preload|fetchPriority|loading\s*=\s*['"`]eager['"`]|loading:\s*['"`]eager['"`])\b/.test(text) &&
+      !/<Image\b[^>]*\bpriority(?:\s|=|>)/i.test(text)) {
+    return { disposition: 'verified', reason: 'Next.js 16 image preload guidance uses the replacement API' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Next.js 16 deprecates next/image priority; use preload, fetchPriority, or loading="eager" based on the image loading intent',
+  };
+}
+
+async function verifyNextCacheComponentsRouteSegmentConfig({ rec, framework, frameworkVersion, cacheComponents }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_components_route_segment_config requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  const major = parseInt(String(frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  if (!Number.isFinite(major) || major < 16) {
+    return { disposition: 'verified', reason: 'Cache Components route segment config restriction does not apply' };
+  }
+  if (cacheComponents !== true) {
+    return { disposition: 'verified', reason: 'Cache Components not detected as enabled' };
+  }
+  const text = recText(rec);
+  if (/\broute segment config options?\b[^.\n]{0,120}\b(?:Route Handlers?|handlers?)\b[^.\n]{0,120}\b(?:no longer apply|do not apply|removed)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'Route Segment Config still has Route Handler options; with Cache Components only dynamic, revalidate, and fetchCache are removed',
+    };
+  }
+  const blocked = [
+    /\bdynamicParams\b/.test(text) ? 'dynamicParams' : null,
+    /\bfetchCache\b/.test(text) ? 'fetchCache' : null,
+    /\bexport\s+const\s+dynamic\b/.test(text) ? 'dynamic' : null,
+    /\bexport\s+const\s+revalidate\b/.test(text) ? 'revalidate' : null,
+  ].filter(Boolean);
+  if (blocked.length === 0) {
+    return { disposition: 'verified', reason: 'no removed route segment config option detected' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `Next.js ${major} project has Cache Components enabled; route segment config option(s) ${blocked.join(', ')} are removed and must not be recommended`,
+  };
+}
+
+async function verifyNextRouteRevalidateStaticPrereq({ rec, framework, cacheComponents, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_route_revalidate_static_prereq requires rec' };
+  if (framework !== 'next') return { disposition: 'verified', reason: 'not a Next.js project' };
+  if (cacheComponents === true) {
+    return { disposition: 'verified', reason: 'Cache Components route-segment restrictions are handled separately' };
+  }
+  const files = recommendationFilesFromRec(rec)
+    .filter((file) => /(^|\/)app\/.+\/(?:page|layout|template)\.(?:tsx?|jsx?)$/.test(String(file)) ||
+      /(^|\/)(?:page|layout|template)\.(?:tsx?|jsx?)$/.test(String(file)));
+  if (files.length === 0) {
+    return { disposition: 'verified', reason: 'route-level revalidate recommendation does not target a page/layout/template file' };
+  }
+
+  const dynamicHits = [];
+  for (const file of files) {
+    const routeChain = await readNextRouteChainFiles(file, repoRoot, projectRootDirectory);
+    if (routeChain.length === 0) {
+      return { disposition: 'unverifiable', reason: `could not inspect route chain for ${file}` };
+    }
+    for (const entry of routeChain) {
+      const hit = firstDynamicRouteChainReason(entry.content);
+      if (hit) dynamicHits.push(`${entry.relative}:${hit}`);
+    }
+  }
+  if (dynamicHits.length > 0) {
+    return {
+      disposition: 'failed',
+      reason: `route-level revalidate can be defeated by request-time APIs or auth helpers in the route chain (${dynamicHits.slice(0, 3).join(', ')}); prove the route is ISR/static from next build output or move the dynamic read out before recommending revalidate`,
+    };
+  }
+  return { disposition: 'verified', reason: 'no request-time API or common auth helper detected in the recommended route chain' };
+}
+
+async function verifyNextCacheTagInvalidationSupported({ rec, repoRoot = '.', projectRootDirectory = null }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'next_cache_tag_invalidation_supported requires rec' };
+  const tags = extractCacheTags(recText(rec));
+  if (tags.length === 0) {
+    return { disposition: 'unsupported', reason: 'cache invalidation claim did not include parseable cacheTag() values' };
+  }
+
+  let files;
+  try {
+    files = await readCacheInvalidationFiles(repoRoot, projectRootDirectory);
+  } catch {
+    return { disposition: 'unverifiable', reason: 'could not scan repo for matching revalidateTag/updateTag calls' };
+  }
+
+  const missing = [];
+  for (const tag of tags) {
+    if (!tagHasMatchingInvalidation(tag, files)) missing.push(tag.label);
+  }
+  if (missing.length === 0) {
+    return { disposition: 'verified', reason: 'every claimed cacheTag has a matching revalidateTag/updateTag path' };
+  }
+  return {
+    disposition: 'failed',
+    reason: `cache invalidation was claimed for tag(s) without matching revalidateTag/updateTag evidence: ${missing.join(', ')}`,
+  };
+}
+
+async function verifyCacheRecNotErrorDominatedOrAcknowledged({ rec, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_rec_not_error_dominated_or_acknowledged requires rec' };
+  const route = routeFromCandidateRef(rec.candidateRef);
+  if (!route) return { disposition: 'unverifiable', reason: 'cache recommendation has no route candidateRef' };
+  const status = functionStatusForRoute(signals, route);
+  if (!status || status.total <= 0) {
+    return { disposition: 'unverifiable', reason: 'no function status metrics available for cache route' };
+  }
+  const errorRate = status.errors / status.total;
+  if (errorRate <= 0.2) {
+    return { disposition: 'verified', reason: `function 5xx rate is not dominant (${formatPct(errorRate)})` };
+  }
+  const text = recText(rec);
+  if (/\b(?:5xx|500|errors?|error-rate|non-error|successful|2xx|after\s+(?:fixing|resolving)\s+errors?)\b/i.test(text)) {
+    return { disposition: 'verified', reason: `cache recommendation acknowledges high 5xx share (${formatPct(errorRate)})` };
+  }
+  return {
+    disposition: 'failed',
+    reason: `route has high function 5xx share (${formatPct(errorRate)}); cache impact must exclude or acknowledge error traffic`,
+  };
+}
+
+async function verifyCacheControlHeaderSyntax({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_control_header_syntax requires rec' };
+  const values = [
+    ...extractHeaderValues(recText(rec), 'Cache-Control'),
+    ...extractHeaderValues(recText(rec), 'CDN-Cache-Control'),
+    ...extractHeaderValues(recText(rec), 'Vercel-CDN-Cache-Control'),
+  ];
+  if (values.length === 0) {
+    return { disposition: 'unverifiable', reason: 'no parseable Cache-Control header value in recommendation' };
+  }
+  const invalid = values.find((value) => hasEmptyCacheDirective(value));
+  if (invalid) {
+    return {
+      disposition: 'failed',
+      reason: `Cache-Control header contains an empty directive: ${invalid}`,
+    };
+  }
+  return { disposition: 'verified', reason: 'cache header directives are syntactically non-empty' };
+}
+
+async function verifyCacheControlHeadersCitation({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_control_headers_citation requires rec' };
+  const citations = Array.isArray(rec.citations) ? rec.citations.join('\n') : '';
+  if (/vercel\.com\/docs\/caching\/(?:cache-control-headers|cdn-cache)/i.test(citations)) {
+    return { disposition: 'verified', reason: 'Cache-Control change is backed by Vercel cache documentation' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'Cache-Control header changes need Vercel cache documentation citation',
+  };
+}
+
+async function verifyCachePolicyPositiveOrNoReadyRec({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_policy_positive_or_no_ready_rec requires rec' };
+  const text = recText(rec);
+  const positivePolicy = /\b(?:s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control|Cache-Control:\s*public|next:\s*\{\s*revalidate|revalidate\s*[:=]\s*\d|cacheLife\s*\(|cacheTag\s*\(|['"`]use cache(?::\s*remote)?['"`]|Runtime Cache|getCache\s*\(|force-cache)\b/i.test(text);
+  if (positivePolicy) {
+    return { disposition: 'verified', reason: 'cache recommendation names a positive cache policy' };
+  }
+  if (/\b(?:no-store|no-cache|cache:\s*['"`]no-store['"`])\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'cache candidates must not ship a no-store-only recommendation; if no-store is correct, report no change instead',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache candidate recommendation does not name a cache policy; specify CDN headers, framework cache, Runtime Cache, or report no change',
+  };
+}
+
+async function verifyCache404LongTtlSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'cache_404_long_ttl_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:leave|keep|leaving|keeping)\b[^.\n]{0,120}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,120}\b(?:uncached|no-store|no-cache|short|separate)\b/i.test(text) ||
+      /\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,120}\b(?:uncached|no-store|no-cache|short|separate)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'recommendation keeps 404/not-found caching separate or uncached' };
+  }
+  if (/\b(?:both|all)\b[^.\n]{0,120}\bResponse\b[^.\n]{0,120}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b/i.test(text) ||
+      /\b(?:add|set|include)\b[^.\n]{0,160}\b(?:Cache-Control|s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control)\b[^.\n]{0,220}\b(?:each|every|all|both|\d+|four)\b[^.\n]{0,120}\bResponse\b[^.\n]{0,160}\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b/i.test(text) ||
+      /\b(?:404|not[- ]found|notFound|not found branch|not-found branch)\b[^.\n]{0,160}\b(?:s-maxage|stale-while-revalidate|CDN-Cache-Control|Vercel-CDN-Cache-Control)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'long shared caching for 404/not-found branches needs explicit freshness evidence; leave those branches uncached or short-lived',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'cache recommendation mentions a 404/not-found branch without explicitly keeping that branch uncached or short-lived',
+  };
+}
+
+async function verifyRouteErrorNotFoundStatusAndScope({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'route_error_not_found_status_and_scope requires rec' };
+  const text = recText(rec);
+  const hasExplicit404 = /\bstatus\s*:\s*404\b/i.test(text);
+  if (!hasExplicit404) {
+    return {
+      disposition: 'failed',
+      reason: 'not-found error handling must set an explicit 404 status; a markdown/body-only Response defaults to 200',
+    };
+  }
+  if (routeErrorFixExplicitlyConvertsUnexpectedErrorsToNotFound(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'route-error 404 fixes must not convert unexpected exceptions into not-found responses; classify expected misses and preserve 5xx behavior for unknown errors',
+    };
+  }
+  const classifiesKnownMiss = /\b(?:known|expected|missing|not[- ]found|not found|ENOENT|NoSuchKey|content[- ]miss|file[- ]miss)\b[^.\n]{0,160}\b(?:only|separate|classif|branch|guard|case)\b/i.test(text) ||
+    /\b(?:only|separate|classif|branch|guard|case)\b[^.\n]{0,160}\b(?:known|expected|missing|not[- ]found|not found|ENOENT|NoSuchKey|content[- ]miss|file[- ]miss)\b/i.test(text);
+  const preservesUnknownErrors = /\b(?:unknown|unexpected|all other|other)\b[^.\n]{0,180}\b(?:rethrow|throw|500|5xx|surface|preserv|remain visible|do not convert)\b/i.test(text) ||
+    /\b(?:rethrow|throw|500|5xx|surface|preserv|remain visible|do not convert)\b[^.\n]{0,180}\b(?:unknown|unexpected|all other|other)\b/i.test(text);
+  if (classifiesKnownMiss && preservesUnknownErrors) {
+    return { disposition: 'verified', reason: 'catch path separates expected misses from unknown errors and sets status 404' };
+  }
+  if (routeErrorFixBroadlyCatchesNotFound(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'route-error 404 fixes must classify expected misses before returning not-found and must not turn generic catch blocks into 404 responses',
+    };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'route-error 404 fixes must classify expected misses separately and preserve logging or 5xx behavior for unknown errors',
+  };
+}
+
+function routeErrorFixExplicitlyConvertsUnexpectedErrorsToNotFound(text) {
+  return /\bunexpected\s+exceptions?\b[^.\n]{0,180}\b(?:degrade|convert|return|become|map)\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text) ||
+    /\b(?:404|not[- ]found|not found|notFound)\b[^.\n]{0,160}\b(?:for|on)\b[^.\n]{0,80}\b(?:any|all|unexpected|unknown)\b[^.\n]{0,80}\bexceptions?\b/i.test(text) ||
+    /\b(?:any|all|unexpected|unknown)\b[^.\n]{0,80}\bexceptions?\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text);
+}
+
+function routeErrorFixBroadlyCatchesNotFound(text) {
+  return /\b(?:catch|catch\s*\([^)]*\))\b[^.\n]{0,220}\b(?:return|respond|degrade|convert)\b[^.\n]{0,160}\b(?:404|not[- ]found|not found|notFound)\b/i.test(text);
+}
+
+async function verifyImmutableDynamicRouteSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'immutable_dynamic_route_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:content[- ]hash(?:ed)?|hashed|fingerprint(?:ed)?|versioned\s+URL|URL\s+changes\s+when\s+bytes\s+change)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'immutable cache header is tied to a byte-versioned URL' };
+  }
+  if (/\bVercel-CDN-Cache-Control\b/i.test(text) && !/(?:^|[^A-Za-z-])Cache-Control\s*:\s*[^.\n]*\bimmutable\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'immutable directive is scoped away from browser Cache-Control' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'immutable browser caching on a dynamic route requires a content-hashed or otherwise byte-versioned URL',
+  };
+}
+
+async function verifyAuthGuardParallelizationSafety({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'auth_guard_parallelization_safety requires rec' };
+  const text = recText(rec);
+  if (/\b(?:query|lookup|fetch)\b[^.\n]{0,120}\b(?:constrained|scoped|filtered)\b[^.\n]{0,120}\b(?:email|user|owner|ownership|session|account|tenant|permission|auth)/i.test(text) ||
+      /\b(?:preserve|keep|retain)\b[^.\n]{0,120}\b(?:auth|authorization|ownership|permission|access)\s+(?:check|guard|gate)\b[^.\n]{0,120}\b(?:before|ahead of|prior to|sequential|not parallel)/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization recommendation preserves the auth/ownership guard' };
+  }
+  if (/\bPromise\.all\s*\([\s\S]{0,500}(?:private|secret|token|registrant|ticket|payment|account|user)\w*[\s\S]{0,500}(?:owns|owner|ownership|authorize|auth|permission|access)\w*/i.test(text) ||
+      /\bPromise\.all\s*\([\s\S]{0,500}(?:owns|owner|ownership|authorize|auth|permission|access)\w*[\s\S]{0,500}(?:private|secret|token|registrant|ticket|payment|account|user)\w*/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'parallelization may fetch private data before the ownership/auth check has passed; combine the authorized query or keep the guard sequential',
+    };
+  }
+  return {
+    disposition: 'unverifiable',
+    reason: 'auth-sensitive parallelization needs explicit evidence that private data is not fetched before authorization',
+  };
+}
+
+async function verifyParallelizationImpactNotOverclaimed({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'parallelization_impact_not_overclaimed requires rec' };
+  const text = recText(rec);
+  if (/\b(?:measured|trace|span|profile|instrumented)\b[^.\n]{0,120}\b(?:duration|round[- ]trip|query|helper|await)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization impact claim cites measured helper/span duration' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'parallelization impact promises a helper/round-trip-sized drop without measured helper or span timing',
+  };
+}
+
+async function verifyParallelizationNotCpuBoundWork({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'parallelization_not_cpu_bound_work requires rec' };
+  const text = recText(rec);
+  if (/\b(?:measured|trace|span|profile|instrumented)\b[^.\n]{0,160}\b(?:wait|I\/O|io|network|fetch|database|query|CMS|API)\b/i.test(text)) {
+    return { disposition: 'verified', reason: 'parallelization target cites measured wait/I/O time' };
+  }
+  if (/\b(?:cpu\.p95|CPU p95|cpu p95|CPU-bound|compute-bound|in-process compute|compileMDX|MDX compilation|compilation|render compute)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'parallelization targets CPU/compile work without measured independent wait time; Promise.all is not a safe latency fix for CPU-bound work',
+    };
+  }
+  return { disposition: 'verified', reason: 'parallelization target is not described as CPU-bound work' };
+}
+
+async function verifyRuntimeErrorCauseSupported({ rec }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'runtime_error_cause_supported requires rec' };
+  const text = recText(rec);
+  const hasRuntimeStack = /\b(?:stack|logs?|trace)\b[\s\S]{0,220}\b(?:Error:|ENOENT|ETIMEDOUT|ECONNRESET|NEXT_|at\s+[\w./[\]()-]+(?::\d+)?)/i.test(text);
+  if (hasRuntimeStack) {
+    return { disposition: 'verified', reason: 'runtime error cause is backed by logs or stack evidence' };
+  }
+  return {
+    disposition: 'failed',
+    reason: 'runtime error root cause was claimed without runtime logs or stack evidence',
+  };
+}
+
+async function verifyVercelIgnoreCommandProjectState({ rec, signals }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'vercel_ignore_command_project_state requires rec' };
+  const project = signals?.project;
+  if (!project || typeof project !== 'object') {
+    return { disposition: 'unverifiable', reason: 'project configuration unavailable for Ignored Build Step check' };
+  }
+  const text = recText(rec);
+  if (typeof project.commandForIgnoringBuildStep === 'string' && project.commandForIgnoringBuildStep.trim() !== '') {
+    return {
+      disposition: 'failed',
+      reason: 'project already has an Ignored Build Step command configured; do not recommend adding another without evidence the current command is insufficient',
+    };
+  }
+  if (project.enableAffectedProjectsDeployments === true &&
+      /\b(?:Ignored Build Step|ignoreCommand|turbo-ignore|skip unaffected|unaffected projects?)\b/i.test(text)) {
+    return {
+      disposition: 'failed',
+      reason: 'project already has Vercel skip-unaffected deployments enabled; do not recommend another build-skipping change without evidence that automatic skipping is unavailable or insufficient',
+    };
+  }
+  return { disposition: 'verified', reason: 'project config does not contradict Ignored Build Step recommendation' };
+}
+
+async function verifyTurboBuildCacheSafety({ rec, files, repoRoot = '.', projectRootDirectory = null, framework }) {
+  if (!rec) return { disposition: 'unsupported', reason: 'turbo_build_cache_safety requires rec' };
+  const candidateFiles = Array.isArray(files) ? files : [];
+  const turboFiles = candidateFiles.filter((file) => /(^|\/)turbo\.json$/.test(String(file)));
+  if (turboFiles.length === 0) {
+    return { disposition: 'unverifiable', reason: 'Turbo build-cache recommendation has no turbo.json file to inspect' };
+  }
+
+  const text = recText(rec);
+  for (const turboFile of turboFiles) {
+    let turbo;
+    try {
+      const { content } = await readClaimFile({ file: turboFile, repoRoot, projectRootDirectory });
+      turbo = parseJsonLike(content);
+    } catch {
+      return { disposition: 'unverifiable', reason: `cannot parse ${turboFile} for Turbo cache safety` };
+    }
+    const buildTask = turbo?.tasks?.build ?? turbo?.pipeline?.build ?? null;
+    const outputs = Array.isArray(buildTask?.outputs) ? buildTask.outputs.map(String) : [];
+    const pkgFile = siblingPackageJson(turboFile);
+    const pkg = await readOptionalJsonFile({ file: pkgFile, repoRoot, projectRootDirectory });
+    const buildScript = typeof pkg?.scripts?.build === 'string' ? pkg.scripts.build : '';
+    const hasNext = framework === 'next' || Boolean(pkg?.dependencies?.next || pkg?.devDependencies?.next);
+
+    if (buildScriptHasMigrationSideEffect(buildScript) && !recSeparatesTurboBuildSideEffects(text)) {
+      return {
+        disposition: 'failed',
+        reason: 'Turbo build caching is unsafe for this build task because the package build script runs migrations or other side effects; split those steps before caching the build output',
+      };
+    }
+
+    if (hasNext && outputs.length > 0 && !outputs.some((output) => /\.next(?:\/|\*\*)/.test(output))) {
+      return {
+        disposition: 'failed',
+        reason: 'Turbo build cache outputs do not include Next.js build output (`.next/**`); fix the output contract before enabling build caching',
+      };
+    }
+  }
+
+  return { disposition: 'verified', reason: 'Turbo build cache recommendation does not conflict with local build scripts or outputs' };
+}
+
+function siblingPackageJson(file) {
+  return join(dirname(String(file)), 'package.json');
+}
+
+async function readOptionalJsonFile(claim) {
+  try {
+    const { content } = await readClaimFile(claim);
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function parseJsonLike(content) {
+  return JSON.parse(
+    String(content)
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:])\/\/.*$/gm, '$1')
+      .replace(/,\s*([}\]])/g, '$1')
+  );
+}
+
+function buildScriptHasMigrationSideEffect(script) {
+  return /\b(?:payload\s+migrate|prisma\s+migrate|knex\s+migrate|sequelize\s+db:migrate|db:migrate|migrate(?::|\s|$)|migration)\b/i.test(String(script));
+}
+
+function recSeparatesTurboBuildSideEffects(text) {
+  return /\b(?:split|separate|move|keep)\b[^.\n]{0,180}\b(?:migrations?|side effects?|payload migrate|prisma migrate)\b[^.\n]{0,180}\b(?:outside|before|uncached|separate)\b/i.test(text) ||
+    /\b(?:cache|enable caching for)\b[^.\n]{0,120}\b(?:buildonly|pure build|next build)\b[^.\n]{0,180}\b(?:not|without|after separating)\b[^.\n]{0,120}\b(?:migrations?|side effects?)\b/i.test(text);
+}
+
+function recText(rec) {
+  return [rec?.what, rec?.why, rec?.fix, rec?.currentBehavior, rec?.desiredBehavior, rec?.verify]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function extractHeaderValues(text, header) {
+  const escaped = escapeRegExp(header);
+  const values = [];
+  const quotedKey = new RegExp(`['"\`]${escaped}['"\`]\\s*:\\s*['"\`]([^'"\`\\n]+)['"\`]`, 'gi');
+  for (const m of text.matchAll(quotedKey)) values.push(m[1].trim());
+  const bareKey = new RegExp(`\\b${escaped}\\b\\s*:\\s*['"\`]?([^'"\`\\n]+)['"\`]?`, 'gi');
+  for (const m of text.matchAll(bareKey)) values.push(cleanHeaderValue(m[1]));
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function hasHeaderValue(text, header, valuePattern) {
+  return extractHeaderValues(text, header).some((value) => valuePattern.test(value));
+}
+
+function cleanHeaderValue(value) {
+  return String(value)
+    .replace(/[).;]+$/g, '')
+    .replace(/\s+and\s+.*$/i, '')
+    .trim();
+}
+
+function hasEmptyCacheDirective(value) {
+  return String(value).split(',').some((part) => part.trim() === '');
+}
+
+function extractCacheTags(text) {
+  const tags = [];
+  const callRe = /\bcacheTag\s*\(([^)]*)\)/gs;
+  for (const call of text.matchAll(callRe)) {
+    const args = call[1] ?? '';
+    for (const m of args.matchAll(/['"]([^'"]+)['"]/g)) {
+      tags.push({ kind: 'exact', value: m[1], label: m[1] });
+    }
+    for (const m of args.matchAll(/`([^`]+)`/g)) {
+      const raw = m[1];
+      const prefix = raw.split('${')[0];
+      if (raw.includes('${') && prefix) {
+        tags.push({ kind: 'prefix', value: prefix, label: raw });
+      } else if (!raw.includes('${')) {
+        tags.push({ kind: 'exact', value: raw, label: raw });
+      }
+    }
+  }
+  const seen = new Set();
+  return tags.filter((tag) => {
+    const key = `${tag.kind}\u0000${tag.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function extractCacheTagsFromFiles(files, repoRoot, projectRootDirectory) {
+  const out = [];
+  if (!Array.isArray(files)) return out;
+  for (const file of files) {
+    try {
+      const { content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      out.push(...extractCacheTags(content));
+    } catch {}
+  }
+  return out;
+}
+
+function dedupeCacheTags(tags) {
+  const seen = new Set();
+  return tags.filter((tag) => {
+    const key = `${tag.kind}\u0000${tag.value}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function readCacheInvalidationFiles(repoRoot, projectRootDirectory) {
+  const cacheKey = `${normalize(repoRoot || '.')}\u0000${normalizeProjectRootDirectory(projectRootDirectory) ?? ''}`;
+  if (cacheInvalidationFileCache.has(cacheKey)) return cacheInvalidationFileCache.get(cacheKey);
+  const baseRoot = normalize(repoRoot || '.');
+  const projectRoot = normalizeProjectRootDirectory(projectRootDirectory);
+  const root = projectRoot ? join(baseRoot, projectRoot) : baseRoot;
+  try {
+    await access(root);
+  } catch {
+    cacheInvalidationFileCache.set(cacheKey, []);
+    return [];
+  }
+  const rgFiles = await rgRelevantFiles(root);
+  if (Array.isArray(rgFiles)) {
+    const files = [];
+    for (const path of rgFiles.slice(0, 500)) {
+      try {
+        files.push({ path, content: await readFile(path, 'utf-8') });
+      } catch {}
+    }
+    cacheInvalidationFileCache.set(cacheKey, files);
+    return files;
+  }
+  const files = [];
+  for await (const path of walkFiles(root)) {
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (!/\b(?:revalidateTag|updateTag)\s*\(|\btags\s*:/.test(content)) continue;
+      files.push({ path, content });
+    } catch {}
+  }
+  cacheInvalidationFileCache.set(cacheKey, files);
+  return files;
+}
+
+async function rgRelevantFiles(root) {
+  try {
+    const { stdout } = await execFileP('rg', [
+      '-l',
+      '--glob', '!node_modules/**',
+      '--glob', '!.next/**',
+      '--glob', '!.vercel/**',
+      '--glob', '!.turbo/**',
+      '--glob', '!dist/**',
+      '--glob', '!build/**',
+      '--glob', '!coverage/**',
+      '--glob', '!content/**',
+      '--glob', '!fixtures/**',
+      '--glob', '!migrations/**',
+      '--glob', '!public/**',
+      '--glob', '*.{ts,tsx,js,jsx,mjs,cjs}',
+      String.raw`\b(?:revalidateTag|updateTag)\s*\(|\btags\s*:`,
+      root,
+    ], { maxBuffer: 10 * 1024 * 1024 });
+    return stdout.split(/\r?\n/).filter(Boolean);
+  } catch (err) {
+    if (err?.code === 1) return [];
+    return null;
+  }
+}
+
+function tagHasMatchingInvalidation(tag, files) {
+  return files.some(({ content }) => {
+    if (hasLiteralInvalidation(content, tag)) return true;
+    return hasConfigDrivenInvalidation(content, tag, files);
+  });
+}
+
+function hasLiteralInvalidation(content, tag) {
+  if (tag.kind === 'exact') {
+    const escaped = escapeRegExp(tag.value);
+    return new RegExp(`\\b(?:revalidateTag|updateTag)\\s*\\(\\s*['"\`]${escaped}['"\`]`).test(content);
+  }
+  const escaped = escapeRegExp(tag.value);
+  return new RegExp(`\\b(?:revalidateTag|updateTag)\\s*\\(\\s*\`?${escaped}`).test(content);
+}
+
+function hasConfigDrivenInvalidation(content, tag, files) {
+  if (!/\brevalidateTag\s*\(\s*\w+/.test(content)) return false;
+  return files.some((file) => configContainsTag(file.content, tag));
+}
+
+function configContainsTag(content, tag) {
+  if (tag.kind === 'exact') {
+    const escaped = escapeRegExp(tag.value);
+    return new RegExp(`\\btags\\s*:\\s*\\[[^\\]]*['"\`]${escaped}['"\`]`, 's').test(content);
+  }
+  const escaped = escapeRegExp(tag.value);
+  return new RegExp(`\\btags\\s*:\\s*\\[[^\\]]*\`?${escaped}`, 's').test(content);
+}
+
+function routeFromCandidateRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const idx = ref.indexOf(':');
+  if (idx < 0) return null;
+  const route = ref.slice(idx + 1);
+  return route && route !== '<account>' && !route.startsWith('<account>#') ? route : null;
+}
+
+function functionStatusForRoute(signals, route) {
+  const rows = signals?.metrics?.fnStatusByRoute?.rows;
+  if (!Array.isArray(rows)) return null;
+  const target = canonicalizeRoute(route);
+  let total = 0;
+  let errors = 0;
+  for (const row of rows) {
+    const rowRoute = row?.route ?? row?.path;
+    if (!rowRoute || canonicalizeRoute(rowRoute) !== target) continue;
+    const value = numberValue(row?.value);
+    if (value == null) continue;
+    total += value;
+    if (/^5/.test(String(row?.http_status ?? ''))) errors += value;
+  }
+  return total > 0 ? { total, errors } : null;
+}
+
+function numberValue(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value.replace(/,/g, ''));
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function asArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+function formatPct(n) {
+  return `${(n * 100).toFixed(1)}%`;
+}
+
+function cacheLifeNeedsContentFreshnessProof(text) {
+  return /\bcacheLife\s*\(\s*['"`](?:hours|days|weeks|max)['"`]\s*\)/i.test(text) &&
+    /\b(?:CMS|Contentful|Payload|Sanity|WordPress|docs?|guides?|navigation|nav|content|article|blog|OpenAPI|metadata|get[A-Z][\w]*(?:By|For|From)?\w*)\b/.test(text);
+}
+
+function recommendationFilesFromRec(rec) {
+  return Array.from(new Set([
+    ...asArray(rec?.affectedFiles),
+    ...asArray(rec?.findingRefs).map((ref) => String(ref).match(/^(.+?):\d+$/)?.[1]).filter(Boolean),
+  ]));
+}
+
+async function readNextRouteChainFiles(file, repoRoot, projectRootDirectory) {
+  const normalized = normalizeProjectRootDirectory(file);
+  if (!normalized) return [];
+  const appIdx = normalized.split('/').lastIndexOf('app');
+  if (appIdx === -1) {
+    try {
+      const { path, content } = await readClaimFile({ file, repoRoot, projectRootDirectory });
+      return [{ path, relative: normalized, content }];
+    } catch {
+      return [];
+    }
+  }
+
+  const parts = normalized.split('/');
+  const appParts = parts.slice(0, appIdx + 1);
+  const routeDirs = parts.slice(appIdx + 1, -1);
+  const candidates = new Set([normalized]);
+  for (let depth = 0; depth <= routeDirs.length; depth++) {
+    const dir = [...appParts, ...routeDirs.slice(0, depth)].join('/');
+    for (const base of ['layout', 'template']) {
+      for (const ext of ['tsx', 'ts', 'jsx', 'js']) candidates.add(`${dir}/${base}.${ext}`);
+    }
+  }
+
+  const out = [];
+  for (const candidate of candidates) {
+    try {
+      const { path, content } = await readClaimFile({ file: candidate, repoRoot, projectRootDirectory });
+      out.push({ path, relative: candidate, content });
+    } catch {}
+  }
+  return out;
+}
+
+function firstDynamicRouteChainReason(content) {
+  const text = String(content ?? '');
+  const direct = text.match(/\b(cookies|headers|draftMode|connection)\s*\(/);
+  if (direct) return `${direct[1]}()`;
+  const helper = text.match(/\b(withAuth|getServerSession|auth|currentUser)\s*\(/);
+  if (helper) return `${helper[1]}()`;
+  if (/from\s+['"]next\/headers['"]/.test(text)) return 'next/headers import';
+  return null;
+}
+
+function pathSuffixMatches(candidateFile, routeFile) {
+  const candidate = normalizeProjectRootDirectory(candidateFile);
+  const route = normalizeProjectRootDirectory(routeFile);
+  if (!candidate || !route) return false;
+  return candidate === route || candidate.endsWith(`/${route}`) || route.endsWith(`/${candidate}`);
+}
+
+function normalizeRouteForLayoutMatch(route) {
+  const normalized = canonicalizeRoute(String(route ?? ''));
+  return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+
+function layoutAppliesToCandidateRoute(layoutPath, targetRoute) {
+  if (typeof layoutPath !== 'string' || typeof targetRoute !== 'string') return false;
+  const layout = normalizeRouteForLayoutMatch(layoutPath);
+  const target = normalizeRouteForLayoutMatch(targetRoute);
+  if (layout === '/') return true;
+
+  let layoutTokens = layout.split('/').filter(Boolean);
+  const targetTokens = target.split('/').filter(Boolean);
+  if (layoutTokens.length > targetTokens.length && isDynamicPlaceholder(layoutTokens[0])) {
+    layoutTokens = layoutTokens.slice(1);
+  } else if (layoutTokens.length > 0 &&
+      targetTokens.length > 0 &&
+      isDynamicPlaceholder(layoutTokens[0]) &&
+      layoutTokens[1] === targetTokens[0]) {
+    layoutTokens = layoutTokens.slice(1);
+  }
+  if (layoutTokens.length === 0) return true;
+  if (layoutTokens.length > targetTokens.length) return false;
+
+  let literalMatches = 0;
+  for (let i = 0; i < layoutTokens.length; i++) {
+    const layoutToken = layoutTokens[i];
+    const targetToken = targetTokens[i];
+    if (isCatchAllPlaceholder(layoutToken)) return literalMatches > 0;
+    if (layoutToken === targetToken) {
+      literalMatches += 1;
+      continue;
+    }
+    if (isDynamicPlaceholder(layoutToken)) continue;
+    return false;
+  }
+  return literalMatches > 0;
+}
+
+function isDynamicPlaceholder(segment) {
+  return /^\[(?:\.{3})?.+\]$/.test(String(segment ?? ''));
+}
+
+function isCatchAllPlaceholder(segment) {
+  return /^\[\[?\.{3}.+\]?\]$/.test(String(segment ?? ''));
+}
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Supports `/pattern/flags` literal-regex form OR plain escaped string. Caller flags merge with embedded flags via Set dedup.
+function compilePattern(pattern, flags) {
+  const m = pattern.match(/^\/(.+)\/([gimsu]*)$/);
+  if (m) {
+    const mergedFlags = [...new Set(((m[2] || '') + (flags || '')).split(''))].join('');
+    return new RegExp(m[1], mergedFlags);
+  }
+  return new RegExp(pattern.replace(/[.+^${}()|[\]\\?*]/g, '\\$&'), flags);
+}
+
+async function readClaimFile(claim) {
+  const path = await firstAccessiblePath(claim);
+  return { path, content: await readFile(path, 'utf-8') };
+}
+
+async function firstAccessiblePath({ repoRoot = '.', file, projectRootDirectory = null }) {
+  let lastErr;
+  for (const p of repoPaths(repoRoot, file, projectRootDirectory)) {
+    try {
+      await access(p);
+      return p;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw lastErr ?? new Error(`cannot access ${file}`);
+}
+
+function repoPaths(repoRoot, file, projectRootDirectory = null) {
+  if (!file) return [];
+  if (isAbsolute(file)) return [file];
+  const out = [join(repoRoot, file)];
+  const projectRoot = normalizeProjectRootDirectory(projectRootDirectory);
+  const normalizedFile = normalizeProjectRootDirectory(file);
+  if (projectRoot && normalizedFile && !normalizedFile.startsWith(`${projectRoot}/`)) {
+    out.push(join(repoRoot, projectRoot, file));
+  }
+  return Array.from(new Set(out.map((p) => normalize(p))));
+}
+
+function normalizeProjectRootDirectory(value) {
+  if (typeof value !== 'string' || value.trim() === '') return null;
+  return value.replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+async function* walkFiles(root, skip = new Set([
+  'node_modules',
+  '.next',
+  '.vercel',
+  '.turbo',
+  'dist',
+  'build',
+  'coverage',
+  '.git',
+  'content',
+  'fixtures',
+  'migrations',
+  'public',
+])) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const path = join(root, e.name);
+    if (e.isDirectory()) {
+      if (skip.has(e.name)) continue;
+      yield* walkFiles(path, skip);
+      continue;
+    }
+    if (!e.isFile()) continue;
+    if (!/\.(tsx?|jsx?|mjs|cjs)$/.test(e.name)) continue;
+    yield path;
+  }
+}
+
+async function snippetFoundElsewhere(root, snippet, exceptFile) {
+  const norm = (s) => s.replace(/\s+/g, ' ').trim();
+  const target = norm(snippet);
+  if (target.length < 20) return null;
+  for await (const path of walkFiles(root)) {
+    if (path.endsWith(exceptFile)) continue;
+    try {
+      const content = await readFile(path, 'utf-8');
+      if (norm(content).includes(target)) return path;
+    } catch {}
+  }
+  return null;
+}