@olives/devos 2.1.0

package/.agents/skills/vercel-optimize/lib/repo-root.mjs

@@ -0,0 +1,86 @@
+// Auto-detect repo-root for claim verification. Priority: Vercel API rootDirectory > --repo-root > walk-up.
+// In a monorepo the sub-agent emits paths like `apps/<app>/src/...` and the verifier needs the prefix root, not the app dir.
+
+import { access } from 'node:fs/promises';
+import { join, dirname, resolve, normalize } from 'node:path';
+
+// Prefer affectedFiles[0] over findingRefs — findingRefs often share the same file.
+export function pickProbeFile(recs) {
+  for (const r of (recs ?? [])) {
+    if (r?.abstain) continue;
+    const af = Array.isArray(r?.affectedFiles) ? r.affectedFiles[0] : null;
+    if (typeof af === 'string' && af.length > 0) return af;
+    const ref = Array.isArray(r?.findingRefs) ? r.findingRefs[0] : null;
+    if (typeof ref === 'string' && ref.length > 0) {
+      const m = ref.match(/^(.+?):\d+$/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+export async function fileResolvesAt(root, file) {
+  try {
+    await access(join(root, file));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function detectRepoRoot(probeFile, startDir, maxDepth = 10) {
+  let dir = resolve(startDir);
+  for (let depth = 0; depth < maxDepth; depth++) {
+    if (await fileResolvesAt(dir, probeFile)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+// rootDirectory "apps/fixture-site" + cwd .../monorepo/apps/fixture-site → repo root .../monorepo.
+export function deriveRootFromSignals(signals, cwd = process.cwd()) {
+  const dir = signals?.project?.rootDirectory;
+  if (!dir || typeof dir !== 'string') return null;
+  const offset = normalize(dir).replace(/^\.\/?/, '').replace(/\/$/, '');
+  if (!offset) return null;
+  const cwdAbs = resolve(cwd);
+  // Match `<root>/<offset>` OR `<root>/<offset>/<more>` — orchestrator may run from a subdir.
+  const parts = cwdAbs.split('/');
+  const offsetParts = offset.split('/');
+  for (let start = parts.length - offsetParts.length; start >= 0; start--) {
+    const slice = parts.slice(start, start + offsetParts.length).join('/');
+    if (slice === offset) {
+      const root = parts.slice(0, start).join('/');
+      return root || '/';
+    }
+  }
+  return null;
+}
+
+export async function resolveRepoRoot(recs, suppliedRoot, cwd = process.cwd(), signals = null) {
+  if (signals) {
+    const apiRoot = deriveRootFromSignals(signals, cwd);
+    if (apiRoot) {
+      return { root: apiRoot, source: 'api', probe: null, apiOffset: signals?.project?.rootDirectory ?? null };
+    }
+  }
+
+  const probe = pickProbeFile(recs);
+  if (!probe) {
+    return { root: suppliedRoot ?? '.', source: suppliedRoot ? 'supplied' : 'default', probe: null };
+  }
+  if (suppliedRoot && await fileResolvesAt(suppliedRoot, probe)) {
+    return { root: suppliedRoot, source: 'supplied', probe };
+  }
+  const detected = await detectRepoRoot(probe, suppliedRoot ?? cwd);
+  if (detected) {
+    return {
+      root: detected,
+      source: suppliedRoot ? 'corrected' : 'auto-detected',
+      probe,
+    };
+  }
+  return { root: suppliedRoot ?? '.', source: suppliedRoot ? 'supplied' : 'default', probe };
+}

package/.agents/skills/vercel-optimize/lib/route-normalize.mjs

@@ -0,0 +1,220 @@
+// Canonicalize Next.js 16 segment-tree metric route paths so gate dedup doesn't burn budget on N copies of the same source file.
+//
+// Next.js folds flag state into base64 prefix, dynamic placeholders into `$d$X`, route groups into `!K..p`, cache-lifecycle leaves into `__PAGE__.segment` / `_tree.segment` / `_index.segment`. ~4-10x dupes per page without canonicalization.
+//
+// This module is the ONLY place we touch Next.js metric path encoding — every gate calls canonicalizeRoute before aggregating.
+
+export const ROUTE_SHAPE_RE = /(?:^.{200,}$)|[\s'"`,;&=<>(){}!\\^|\u0000-\u001F]|%(?:22|5B|5C|7B|7D|20|3C|3E|26)|localhost:|https?:\/|\/\/(?!$)|[:,\$\s]$|\.segments?\/|__PAGE__|@[a-z]/i;
+
+export function isSegmentTreePath(route) {
+  if (typeof route !== 'string') return false;
+  return /\.segments(\/|$)/.test(route);
+}
+
+export function canonicalizeRoute(route) {
+  if (typeof route !== 'string' || route.length === 0) return route;
+  if (!isSegmentTreePath(route)) return stripRouteGroups(replaceBase64WithDynamic(route));
+
+  // Discard prefix (flag-state + dynamic value, both noise). Tail is the segment-tree node.
+  const idx = route.indexOf('.segments');
+  if (idx < 0) return route;
+  const segmentTail = route.slice(idx + '.segments'.length).replace(/^\//, '');
+
+  // _tree.segment / _index.segment have no per-segment tail — fall back to static head of prefix.
+  if (segmentTail === '_tree.segment' || segmentTail === '_index.segment') {
+    return canonicalizeBranchPrefix(route, idx);
+  }
+
+  const parts = segmentTail.split('/').filter((p) => p && !isMetricLeaf(p));
+  if (parts.length === 0) return canonicalizeBranchPrefix(route, idx);
+  const decoded = parts.map(decodeSegmentToken).filter(Boolean);
+  if (decoded.length === 0) return canonicalizeBranchPrefix(route, idx);
+  // scan-codebase's routePath enumeration drops route groups — match it or the route→file lookup breaks.
+  return stripRouteGroups('/' + decoded.join('/'));
+}
+
+function canonicalizeBranchPrefix(route, segmentsIdx) {
+  const prefix = route.slice(0, segmentsIdx);
+  const parts = prefix.split('/').filter(Boolean);
+  // Drop trailing dynamic value (e.g. "london") and base64 flag-state — neither is a route segment.
+  const cleaned = parts
+    .filter((p) => !isBase64FlagState(p))
+    .slice(0, -1);
+  if (cleaned.length === 0) return prefix || '/';
+  return '/' + cleaned.join('/');
+}
+
+function isMetricLeaf(token) {
+  return (
+    token === '__PAGE__.segment' ||
+    token === '_tree.segment' ||
+    token === '_index.segment' ||
+    token === '__page__.segment' ||
+    token.endsWith('.segment') && token.startsWith('_')
+  );
+}
+
+// Conservative heuristic for `eyJoYXNTZXNzaW9uIjpmYWxzZX0`-shape tokens: URL-safe base64 alphabet, length ≥16, mixed case.
+function isBase64FlagState(token) {
+  if (typeof token !== 'string') return false;
+  if (token.length < 16) return false;
+  return /^[A-Za-z0-9_-]+$/.test(token) && /[A-Z]/.test(token) && /[a-z]/.test(token);
+}
+
+// `/event/<base64>/teaser` → `/event/[*]/teaser`. Stripping entirely (old behavior) corrupted segment count and broke route→file lookup.
+function replaceBase64WithDynamic(route) {
+  if (typeof route !== 'string' || !route.startsWith('/')) return route;
+  const parts = route.split('/');
+  let mutated = false;
+  const replaced = parts.map((p, i) => {
+    if (i === 0) return p;
+    if (isBase64FlagState(p)) { mutated = true; return '[*]'; }
+    return p;
+  });
+  if (!mutated) return route;
+  return replaced.join('/') || '/';
+}
+
+// Route groups `(default)` never appear in rendered URLs — scan-codebase drops them, so canonical form must match.
+function stripRouteGroups(route) {
+  if (typeof route !== 'string' || !route.includes('(')) return route;
+  const parts = route.split('/');
+  const kept = parts.filter((p) => !/^\([^)]+\)$/.test(p));
+  const joined = kept.join('/');
+  return joined.startsWith('/') ? (joined || '/') : '/' + joined;
+}
+
+// $d$X → [X] · $oc$X → [[...X]] · $c$X → [...X] · !K…p → (group) · metric-leaves → dropped.
+function decodeSegmentToken(token) {
+  if (isMetricLeaf(token)) return '';
+
+  let t = token.endsWith('.segment') ? token.slice(0, -'.segment'.length) : token;
+
+  if (/^\$d\$/.test(t)) return `[${t.slice(3)}]`;
+  if (/^\$oc\$/.test(t)) return `[[...${t.slice(4)}]]`;
+  if (/^\$c\$/.test(t)) return `[...${t.slice(3)}]`;
+
+  // `!` is segment-tree marker; body is base64 of `(default)` etc. Accept only when decoded looks like `(name)`.
+  if (t.startsWith('!') && t.length > 1) {
+    const body = t.slice(1);
+    try {
+      const decoded = Buffer.from(body, 'base64').toString('utf-8');
+      if (/^\(.*\)$/.test(decoded)) return decoded;
+    } catch {
+      /* fall through on decode failure */
+    }
+  }
+
+  return t;
+}
+
+export function candidateKey(candidate) {
+  const route = candidate?.route ?? candidate?.hostname ?? null;
+  const kind = candidate?.kind ?? '?';
+  const canonical = route ? canonicalizeRoute(route) : '<account>';
+  return `${kind}::${canonical}`;
+}
+
+// Records alternates so the brief shows "all 4 cities collapse here" rather than a single per-city dupe.
+export function mergeCandidates(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const winner = (b.priority ?? 0) > (a.priority ?? 0) ? b : a;
+  const loser = winner === a ? b : a;
+  const altRoutes = new Set([
+    ...(Array.isArray(winner.aliasRoutes) ? winner.aliasRoutes : []),
+    ...(Array.isArray(loser.aliasRoutes) ? loser.aliasRoutes : []),
+  ]);
+  if (loser.route && loser.route !== winner.route) altRoutes.add(loser.route);
+  return {
+    ...winner,
+    // Canonicalize so briefs/reports/deep-dives see the clean path.
+    route: canonicalizeRoute(winner.route),
+    aliasRoutes: [...altRoutes].sort(),
+    mergedCount: (winner.mergedCount ?? 1) + (loser.mergedCount ?? 1),
+  };
+}
+
+// Input assumed sorted priority desc; output preserves that order. Account-scope pass through unchanged.
+export function dedupeCandidates(candidates) {
+  const byKey = new Map();
+  const order = [];
+  const dropped = [];
+  for (const c of candidates) {
+    if (!c || c.scope === 'account' || (!c.route && !c.hostname)) {
+      order.push(c);
+      continue;
+    }
+    const key = candidateKey(c);
+    if (byKey.has(key)) {
+      const merged = mergeCandidates(byKey.get(key), c);
+      byKey.set(key, merged);
+      dropped.push({
+        candidate: c,
+        mergedInto: key,
+        reason: 'duplicate of higher-priority sibling (same source route after canonicalization)',
+      });
+    } else {
+      byKey.set(key, { ...c, route: c.route ? canonicalizeRoute(c.route) : c.route });
+      order.push({ __key: key });
+    }
+  }
+  const deduped = order.map((c) => (c && c.__key ? byKey.get(c.__key) : c));
+  return { deduped, dropped };
+}
+
+export function isLikelyNextRouteShape(route) {
+  return typeof route === 'string' && route.length > 0 && !ROUTE_SHAPE_RE.test(route);
+}
+
+export function routeShapeWarning(route, signals = {}) {
+  return routeShapeWarnings(route, signals)[0] ?? null;
+}
+
+export function routeShapeWarnings(route, signals = {}) {
+  if (typeof route !== 'string' || route.length === 0) return [];
+  const warnings = [];
+  if (ROUTE_SHAPE_RE.test(route)) warnings.push('route-shape:suspicious-metric-label');
+  const first = firstRouteSegment(canonicalizeRoute(route));
+  if (first && shouldWarnUnknownFirstSegment(first, signals)) {
+    warnings.push(`route-shape:unknown-first-segment:${first}`);
+  }
+  return warnings;
+}
+
+export function withRouteShapeWarnings(candidate, signals = {}) {
+  const warnings = routeShapeWarnings(candidate?.route, signals);
+  if (warnings.length === 0) return candidate;
+  return {
+    ...candidate,
+    warnings: [...new Set([...(Array.isArray(candidate.warnings) ? candidate.warnings : []), ...warnings])],
+  };
+}
+
+function firstRouteSegment(route) {
+  if (typeof route !== 'string') return null;
+  return route.split('/').filter(Boolean)[0] ?? null;
+}
+
+function shouldWarnUnknownFirstSegment(first, signals) {
+  const exempt = new Set(['_next', '_vercel', 'api', '.well-known']);
+  if (exempt.has(first)) return false;
+  const known = knownFirstSegments(signals);
+  if (known.size === 0) return false;
+  if ([...known].some(isDynamicPlaceholder)) return false;
+  return !known.has(first);
+}
+
+function knownFirstSegments(signals) {
+  const out = new Set();
+  const routes = signals.codebase?.routes ?? [];
+  for (const route of routes) {
+    const first = firstRouteSegment(route?.routePath);
+    if (first) out.add(first);
+  }
+  return out;
+}
+
+function isDynamicPlaceholder(segment) {
+  return /^\[.*\]$/.test(segment);
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/bot-protection-certainty.mjs

@@ -0,0 +1,38 @@
+// Bot Protection evidence is usually account-level summary data. Avoid turning
+// observed bot traffic into unsupported statements about exact WAF rule state.
+
+export const metadata = {
+  id: 'bot-protection-certainty',
+  description: 'Soften unsupported Bot Protection / WAF certainty and require a staged rollout caveat.',
+};
+
+const STRING_FIELDS = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify'];
+
+export function apply(rec) {
+  if (!String(rec?.candidateRef ?? '').startsWith('platform_bot_protection:')) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    let after = before
+      .replace(/\bno\s+(?:firewall\s+)?bot_filter\s+rule\b/gi, 'the collected firewall summary did not show an enforced bot-filter rule')
+      .replace(/\b(?:bots?|bot traffic)\s+(?:is|are)\s+the\s+cause\b/gi, 'bot traffic is a likely contributor')
+      .replace(/\bwithout\s+false[- ]positive\s+risk\b/gi, 'with false-positive risk monitored during rollout')
+      .replace(/\bno\s+false[- ]positive\s+risk\b/gi, 'false-positive risk still needs rollout monitoring');
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`bot-protection-certainty:${field}`);
+    }
+  }
+
+  const text = STRING_FIELDS.map((field) => rec?.[field]).filter((s) => typeof s === 'string').join('\n');
+  if (/\b(?:Bot Protection|BotID|bot_filter|WAF)\b/i.test(text) &&
+      !/\bstaged\b[\s\S]{0,80}\b(?:log|allowlist|exclusions?)\b/i.test(text)) {
+    const caveat = ' Use a staged rollout that starts in Log mode where available, then moves to the appropriate Challenge or Deny action only after allowlist/exclusion review for known monitoring and partner clients.';
+    if (typeof rec.fix === 'string') rec.fix += caveat;
+    else rec.fix = caveat.trim();
+    tags.push('bot-protection-certainty:staged-rollout');
+  }
+
+  return tags.length > 0 ? { tags, needsReview: true } : {};
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/cache-tag-invalidation-certainty.mjs

@@ -0,0 +1,30 @@
+// A cacheTag() in the cached function is not proof that CMS edits invalidate it.
+// The report must not claim "existing tags preserve instant updates" unless the
+// investigation verifies matching revalidateTag/updateTag paths.
+
+export const metadata = {
+  id: 'cache-tag-invalidation-certainty',
+  description: 'Remove unsupported certainty that existing cache tags already preserve CMS/on-demand invalidation.',
+};
+
+const STRING_FIELDS = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify'];
+const UNSUPPORTED_TAG_CERTAINTY =
+  /\b(?:existing|current)\s+(?:cache\s+)?tags?\b[^.!?\n]{0,160}\b(?:preserve|keep|cover|maintain|ensure)\b[^.!?\n]{0,160}\b(?:instant|on-demand|CMS|content|publish|update|updates|invalidation|revalidation)\b[^.!?\n]*(?:[.!?]|$)/gi;
+const SAFE_REPLACEMENT =
+  'Confirm a matching revalidateTag() or updateTag() path for each cacheTag() before increasing the cache lifetime.';
+
+export function apply(rec) {
+  const text = STRING_FIELDS.map((field) => rec?.[field]).filter((s) => typeof s === 'string').join('\n');
+  if (!/\bcache(?:Life|Tag)\b/.test(text)) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = before.replace(UNSUPPORTED_TAG_CERTAINTY, SAFE_REPLACEMENT);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`cache-tag-invalidation-certainty:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags, needsReview: true } : {};
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/count-correct.mjs

@@ -0,0 +1,52 @@
+// Rewrite verifier-failed count claims to ground truth (or "a number of"
+// when actual isn't numeric) so we don't ship false precision.
+
+import { escapeRegex } from '../util.mjs';
+
+export const metadata = {
+  id: 'count-correct',
+  description: 'Rewrite count claims to verified ground truth (count-correct) or "a number of" (count-strip) when verifier disagrees.',
+};
+
+const COUNT_CLAIM_TYPES = new Set(['pattern_count', 'repo_count', 'cited_count_literal']);
+
+export function apply(rec, ctx = {}) {
+  const results = ctx.verifyResults ?? rec.verifyResults ?? rec.verification?.failed ?? null;
+  if (!Array.isArray(results) || results.length === 0) return {};
+
+  const tags = [];
+
+  for (const r of results) {
+    if (!r) continue;
+    const type = r.type ?? r.claimType;
+    if (!COUNT_CLAIM_TYPES.has(type)) continue;
+    const disp = r.disposition ?? (r.actual !== r.expected ? 'failed' : 'verified');
+    if (disp !== 'failed') continue;
+    const expected = r.expected;
+    const actual = r.actual;
+    const token = r.token ?? r.text ?? expected;
+    if (expected == null || token == null) continue;
+
+    if (typeof actual === 'number' && Number.isFinite(actual)) {
+      rewriteCount(rec, token, expected, `~${actual}`);
+      tags.push(`count-correct:${token}:${expected}->${actual}`);
+    } else {
+      rewriteCount(rec, token, expected, 'a number of');
+      tags.push(`count-strip:${token}`);
+    }
+  }
+
+  if (tags.length === 0) return {};
+  return { tags };
+}
+
+function rewriteCount(rec, token, oldCount, replacement) {
+  const fields = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior'];
+  // Matches "60", "~60", and "60+" — LLM commonly writes "60+ icons".
+  const oldEsc = escapeRegex(String(oldCount));
+  const re = new RegExp(`\\b~?${oldEsc}\\+?\\s+${escapeRegex(token)}\\b`, 'g');
+  for (const f of fields) {
+    if (typeof rec[f] !== 'string') continue;
+    rec[f] = rec[f].replace(re, `${replacement} ${token}`);
+  }
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/function-duration-invocations.mjs

@@ -0,0 +1,38 @@
+// A function-duration optimization can reduce p95/CPU/GB-hr. It does not by
+// itself reduce function invocation count unless the fix also adds CDN/static
+// response caching.
+
+export const metadata = {
+  id: 'function-duration-invocations',
+  description: 'Remove false claims that slow-route data-cache fixes reduce function invocation count.',
+};
+
+const STRING_FIELDS = [
+  'what',
+  'why',
+  'fix',
+  'currentBehavior',
+  'desiredBehavior',
+  'verify',
+];
+
+const BAD_INVOCATION_CLAIM =
+  /\bfunction invocations?\b[^.!?\n]{0,120}\b(?:drop|drops|fall|falls|decrease|decreases|decline|declines|reduce|reduces|reduced|cut|cuts)\b[^.!?\n]*(?:[.!?]|$)|\b(?:drop|drops|fall|falls|decrease|decreases|decline|declines|reduce|reduces|reduced|cut|cuts)\b[^.!?\n]{0,120}\bfunction invocations?\b[^.!?\n]*(?:[.!?]|$)/gi;
+
+const SAFE_REPLACEMENT =
+  '95th percentile duration should drop; function invocation count may stay flat unless a separate CDN or static-rendering change is made.';
+
+export function apply(rec) {
+  if (!String(rec?.candidateRef ?? '').startsWith('slow_route:')) return {};
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = before.replace(BAD_INVOCATION_CLAIM, SAFE_REPLACEMENT);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`function-duration-invocations:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags } : {};
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/index.mjs

@@ -0,0 +1,79 @@
+// Sanitizer orchestrator. Order matters: citation strippers must run
+// before missing-citation so an emptied citations[] still drops the rec.
+
+import { applyDollarStrip } from '../impact-magnitude.mjs';
+import { sanitizeCitations } from '../citations.mjs';
+import * as vercelDirectiveStrip from './vercel-directive-strip.mjs';
+import * as rateLimit from './rate-limit.mjs';
+import * as preRelease from './pre-release.mjs';
+import * as middlewareConflict from './middleware-conflict.mjs';
+import * as undeclaredDep from './undeclared-dep.mjs';
+import * as countCorrect from './count-correct.mjs';
+import * as renderingModeMislabel from './rendering-mode-mislabel.mjs';
+import * as windowUnits from './window-units.mjs';
+import * as functionDurationInvocations from './function-duration-invocations.mjs';
+import * as botProtectionCertainty from './bot-protection-certainty.mjs';
+import * as cacheTagInvalidationCertainty from './cache-tag-invalidation-certainty.mjs';
+import * as missingCitation from './missing-citation.mjs';
+
+export const SANITIZERS = [
+  vercelDirectiveStrip,
+  rateLimit,
+  preRelease,
+  middlewareConflict,
+  undeclaredDep,
+  countCorrect,
+  renderingModeMislabel,
+  windowUnits,
+  functionDurationInvocations,
+  botProtectionCertainty,
+  cacheTagInvalidationCertainty,
+];
+
+export function recordSanitizer(rec, tag) {
+  rec.sanitizerTrail = rec.sanitizerTrail ?? [];
+  rec.sanitizerTrail.push(tag);
+}
+
+export async function applySanitizers(rec, ctx = {}) {
+  applyDollarStrip(rec);
+
+  for (const s of SANITIZERS) {
+    const result = s.apply(rec, ctx) ?? {};
+    const tags = result.tags ?? (result.tag ? [result.tag] : []);
+    for (const t of tags) recordSanitizer(rec, t);
+    if (result.needsReview) rec.needsReview = true;
+    if (result.dropped) {
+      return { kept: false, rec, dropReason: tags[0] ?? `dropped-by:${s.metadata?.id ?? 'unknown'}` };
+    }
+  }
+
+  if (ctx.framework && ctx.version) {
+    const before = (rec.citations ?? []).slice();
+    const { strippedUnknown, strippedVersion } = await sanitizeCitations(rec, ctx.framework, ctx.version);
+    for (const u of strippedUnknown) recordSanitizer(rec, `unknown-citation:${u}`);
+    for (const u of strippedVersion) recordSanitizer(rec, `version-mismatch:${u}`);
+    const lostAny = strippedUnknown.length > 0 || strippedVersion.length > 0;
+    const lostAll = lostAny && (rec.citations ?? []).length === 0 && before.length > 0;
+    if (lostAll) rec.needsReview = true;
+  }
+
+  // missing-citation runs LAST so citation strippers above can starve a rec.
+  const missing = missingCitation.apply(rec, ctx) ?? {};
+  if (missing.dropped) {
+    return { kept: false, rec, dropReason: missing.tag ?? 'missing-citation' };
+  }
+
+  return { kept: true, rec };
+}
+
+export async function applySanitizersBatch(recs, ctx = {}) {
+  const kept = [];
+  const dropped = [];
+  for (const rec of recs) {
+    const r = await applySanitizers(rec, ctx);
+    if (r.kept) kept.push(r.rec);
+    else dropped.push({ rec: r.rec, dropReason: r.dropReason });
+  }
+  return { kept, dropped };
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/middleware-conflict.mjs

@@ -0,0 +1,36 @@
+// Append a caveat when a rec targets a route covered by middleware: e.g.
+// middleware setting Set-Cookie downstream poisons cache headers the rec
+// adds. Trusts finding.routesCovered rather than re-implementing Next's
+// matcher algorithm.
+
+import { extractRoute } from '../util.mjs';
+
+export const metadata = {
+  id: 'middleware-conflict',
+  description: 'Append caveat when rec targets a route covered by middleware.',
+};
+
+export function apply(rec, ctx = {}) {
+  const findings = ctx?.signals?.codebase?.findings ?? [];
+  const middlewareFinding = findings.find((f) => f?.scannerId === 'middleware-broad-matcher' || f?.id === 'middleware-broad-matcher');
+  if (!middlewareFinding) return {};
+
+  const route = extractRoute(rec);
+  if (!route) return {};
+
+  const matcher = middlewareFinding.detail?.matcher
+    ?? middlewareFinding.matcher
+    ?? '(unspecified matcher)';
+  const middlewareFile = middlewareFinding.file ?? middlewareFinding.path ?? 'middleware.ts';
+
+  const covered = middlewareFinding.detail?.routesCovered ?? middlewareFinding.routesCovered;
+  if (Array.isArray(covered) && covered.length > 0 && !covered.includes(route)) {
+    return {};
+  }
+
+  const tag = `middleware-conflict:${matcher}`;
+  const caveat = `\n\n_Caveat: Middleware at \`${middlewareFile}\` (matcher: \`${matcher}\`) may intercept \`${route}\` and alter request/response before this fix takes effect. Verify the middleware does not set headers (e.g. \`Set-Cookie\`) that would invalidate caching._`;
+
+  if (typeof rec.fix === 'string') rec.fix += caveat;
+  return { tag, needsReview: true };
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/missing-citation.mjs

@@ -0,0 +1,16 @@
+// Final-gate sanitizer: drops a rec with no citations left after
+// unknown-citation + version-mismatch have run. Every rec must carry ≥1
+// citation.
+
+export const metadata = {
+  id: 'missing-citation',
+  description: 'Drop rec when citations[] is empty after other sanitizers.',
+};
+
+export function apply(rec, _ctx = {}) {
+  const cites = Array.isArray(rec.citations) ? rec.citations : [];
+  if (cites.length === 0) {
+    return { dropped: true, tag: 'missing-citation' };
+  }
+  return {};
+}

package/.agents/skills/vercel-optimize/lib/sanitizers/pre-release.mjs

@@ -0,0 +1,74 @@
+// Append a caveat (don't drop — customer may opt in to canary) when a
+// fix needs a canary/rc/beta dep version.
+
+import { matchesFrameworkVersion } from '../citations.mjs';
+
+const PRE_RELEASE_FEATURES = [
+  {
+    match: /\bppr\b|partial[- ]?prerendering/i,
+    requires: 'next@canary',
+    message: 'PPR is experimental — verify your Next.js version supports it as stable',
+  },
+  {
+    match: /\buse cache['"]?\s*directive\b|"use cache"|'use cache'/i,
+    requires: 'next@>=15.0.0',
+    message: 'use cache directive is stable in 15+',
+  },
+  {
+    match: /\bcacheLife\(/i,
+    requires: 'next@>=15.0.0',
+    message: 'cacheLife is stable in 15+',
+  },
+  {
+    match: /\bcacheTag\(/i,
+    requires: 'next@>=15.0.0',
+    message: 'cacheTag is stable in 15+',
+  },
+];
+
+const SEMVER_PRE_RELEASE_RE = /\b([\w-]+)@(\d+\.\d+\.\d+-(?:rc|beta|canary|alpha|next|exp)[\w.-]*)/g;
+
+export const metadata = {
+  id: 'pre-release',
+  description: 'Append caveat when fix targets a canary/rc/beta feature.',
+};
+
+export function apply(rec, ctx = {}) {
+  const text = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  if (!text) return {};
+
+  const tags = [];
+  const caveats = [];
+
+  for (const feat of PRE_RELEASE_FEATURES) {
+    if (feat.match.test(text)) {
+      if (featureAvailableForStack(feat, ctx)) continue;
+      const tag = `pre-release:${feat.requires}`;
+      if (!tags.includes(tag)) {
+        tags.push(tag);
+        caveats.push(`Requires ${feat.requires} (${feat.message}).`);
+      }
+    }
+  }
+
+  for (const m of text.matchAll(SEMVER_PRE_RELEASE_RE)) {
+    const [, pkg, version] = m;
+    const tag = `pre-release:${pkg}@${version}`;
+    if (!tags.includes(tag)) {
+      tags.push(tag);
+      caveats.push(`Requires pre-release version: \`${pkg}@${version}\`.`);
+    }
+  }
+
+  if (tags.length === 0) return {};
+  const caveatBlock = '\n\n_Note: ' + caveats.join(' ') + '_';
+  if (typeof rec.fix === 'string') rec.fix += caveatBlock;
+  return { tags, needsReview: true };
+}
+
+function featureAvailableForStack(feat, ctx) {
+  if (!ctx?.framework || !ctx?.version) return false;
+  return matchesFrameworkVersion(feat.requires, ctx.framework, ctx.version);
+}