@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/gates/slow-route.mjs

@@ -0,0 +1,97 @@
+// Primary threshold (p95>500 AND inv>=1400) WHY: 1.4k/14d is the floor where p95 stabilizes statistically
+// and a 3-5x performance win still pays for engineering time. Secondary (p95>1500 AND inv>=250) catches "catastrophically
+// slow at any volume" — usually a broken sync call or cold-start chain the customer wants to know about.
+//
+// 5xx disqualifier: when error rate >50% the route is failing, not slow — latency reflects crash time,
+// not work time. route_errors covers it independently; we disqualify here so budget isn't spent on a
+// sub-agent that will correctly abstain.
+
+import { withRouteShapeWarnings } from "../route-normalize.mjs";
+
+const ERROR_RATE_DISQUALIFY_THRESHOLD = 0.5;
+
+export const metadata = {
+  id: "slow_route",
+  threshold:
+    "(p95 > 500 AND inv >= 1400) OR (p95 > 1500 AND inv >= 250); disqualified when 5xx rate > 50%; Vercel Workflow runtime endpoints are hard-gated",
+  billingDimension: "function-duration",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Routes with p95 function duration above 500ms at meaningful traffic (>=1,400 invocations in window), OR catastrophically slow routes (>1500ms p95 at any volume >=250). High duration drives both function-duration cost and user-perceived latency. Investigate sequential awaits, slow external APIs, missing caching, N+1 patterns. Routes with >50% 5xx rate are disqualified — those are reliability problems, not performance tuning targets, and surface via route_errors instead. Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`) are hard-gated before launch because long-running step/flow requests are expected orchestration, not app-route bottlenecks.",
+};
+
+export function gate(signals) {
+  const routes = extractFunctionRoutes(signals);
+  const errorRates = extractErrorRatesByRoute(signals);
+  return routes
+    .filter(
+      (r) => (r.p95Ms > 500 && r.invocations >= 1400) || (r.p95Ms > 1500 && r.invocations >= 250),
+    )
+    .map((r) => {
+      const errorRate = errorRates.get(r.route);
+      const candidate = {
+        kind: metadata.id,
+        scope: "route",
+        route: r.route,
+        files: [],
+        priority: Math.round((r.p95Ms * Math.max(r.invocations, 1)) / 1000),
+        confidence: 0.94,
+        o11ySignal: `inv=${r.invocations},p95=${r.p95Ms}ms${errorRate != null ? `,5xx=${(errorRate * 100).toFixed(0)}%` : ""}`,
+        reason: "slow high-traffic route",
+        question: `What is the concrete bottleneck in ${r.route} (p95=${r.p95Ms}ms over ${r.invocations} invocations), and which file-level change would reduce it?`,
+        evidence: {
+          metric: "fnDurationP95ByRoute",
+          route: r.route,
+          p95Ms: r.p95Ms,
+          invocations: r.invocations,
+          errorRate,
+        },
+      };
+      if (errorRate != null && errorRate > ERROR_RATE_DISQUALIFY_THRESHOLD) {
+        candidate.disqualified = true;
+        candidate.disqualifyReason = `high error rate (${(errorRate * 100).toFixed(0)}% 5xx — reliability issue, not performance; covered by route_errors gate)`;
+      }
+      return withRouteShapeWarnings(candidate, signals);
+    });
+}
+
+// Routes without status data are absent from the map → gate falls back to "no disqualification".
+function extractErrorRatesByRoute(signals) {
+  const m = signals.metrics?.fnStatusByRoute;
+  const out = new Map();
+  if (!Array.isArray(m?.rows)) return out;
+  const perRoute = new Map();
+  for (const row of m.rows) {
+    if (!row?.route) continue;
+    const v = row.value ?? 0;
+    const prior = perRoute.get(row.route) ?? { errors5xx: 0, total: 0 };
+    if (/^5/.test(String(row.http_status ?? ""))) prior.errors5xx += v;
+    prior.total += v;
+    perRoute.set(row.route, prior);
+  }
+  for (const [route, r] of perRoute) {
+    if (r.total > 0) out.set(route, r.errors5xx / r.total);
+  }
+  return out;
+}
+
+function extractFunctionRoutes(signals) {
+  const dur = signals.metrics?.fnDurationP95ByRoute;
+  if (!dur?.ok && !Array.isArray(dur?.rows)) return [];
+  const req = signals.metrics?.requestsByRouteCache;
+
+  const invByRoute = new Map();
+  for (const row of req?.rows ?? []) {
+    if (!row.route) continue;
+    invByRoute.set(row.route, (invByRoute.get(row.route) ?? 0) + (row.value ?? 0));
+  }
+
+  return (dur?.rows ?? [])
+    .filter((r) => r.route)
+    .map((r) => ({
+      route: r.route,
+      p95Ms: Math.round(r.value ?? 0),
+      invocations: invByRoute.get(r.route) ?? 0,
+    }));
+}

package/skills/craft/vercel-optimize/lib/gates/types.d.ts

@@ -0,0 +1,38 @@
+export type CandidateScope = "route" | "file" | "account";
+
+export interface GateMetadata {
+  id: string;
+  threshold: string;
+  billingDimension: string;
+  scope: CandidateScope | "mixed";
+  sourceCitation?: string;
+  description?: string;
+}
+
+export interface Candidate {
+  kind: string;
+  scope: CandidateScope;
+  route?: string | null;
+  hostname?: string | null;
+  files: string[];
+  priority: number;
+  confidence: number;
+  o11ySignal?: string;
+  reason: string;
+  question: string;
+  evidence?: Record<string, unknown>;
+  disqualified?: boolean;
+  disqualifyReason?: string;
+  warnings?: string[];
+}
+
+export interface Signals {
+  metrics?: Record<string, unknown>;
+  codebase?: {
+    findings?: Array<Record<string, unknown>>;
+    routes?: Array<Record<string, unknown>>;
+  };
+  project?: Record<string, unknown>;
+  usage?: Record<string, unknown>;
+  stack?: Record<string, unknown>;
+}

package/skills/craft/vercel-optimize/lib/gates/uncached-route.mjs

@@ -0,0 +1,103 @@
+// getShare>0.20 filter WHY: a route that's >80% POST/PUT/DELETE is a mutation endpoint
+// where 0% cache is correct — recommending caching there is wrong.
+// cache_result values STALE/REVALIDATED/BYPASS fold into "total but not HIT" — matches the "uncached" framing.
+
+import { withRouteShapeWarnings } from "../route-normalize.mjs";
+
+const MIN_GET_SHARE = 0.2;
+
+/** @type {import('./types.d.ts').GateMetadata} */
+export const metadata = {
+  id: "uncached_route",
+  threshold: `requests > 500 AND hitRate < 0.5 AND getShare > ${MIN_GET_SHARE} (missing getShare is gated)`,
+  billingDimension: "edge-requests",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Routes serving > 500 requests/period at < 50% cache hit AND at least 20% GET traffic. Each uncached GET request reaches the function, costing edge requests + function duration. Routes that are mostly POST/PUT/DELETE (Server Actions, mutations) are skipped — 0% cache is correct behavior there. Routes with missing method-share data are gated instead of launched. Auth-gated routes are disqualified separately.",
+};
+
+/**
+ * @param {import('./types.d.ts').Signals} signals
+ * @returns {import('./types.d.ts').Candidate[]}
+ */
+export function gate(signals) {
+  const rates = extractCacheHitRates(signals);
+  const methods = extractMethodShares(signals);
+  return rates
+    .map((r) => ({ ...r, getShare: methods.get(r.route) ?? null }))
+    .filter((r) => r.requests > 500 && r.hitRate < 0.5)
+    .filter((r) => r.getShare === null || r.getShare > MIN_GET_SHARE)
+    .map((r) => {
+      const candidate = withRouteShapeWarnings(
+        {
+          kind: metadata.id,
+          scope: "route",
+          route: r.route,
+          files: [],
+          priority: Math.round(r.requests * (1 - r.hitRate)),
+          confidence: r.getShare === null ? 0.5 : 0.92,
+          o11ySignal: `requests=${r.requests},cache=${(r.hitRate * 100).toFixed(0)}%${r.getShare !== null ? `,get=${(r.getShare * 100).toFixed(0)}%` : ""}`,
+          reason: "uncached high-traffic route",
+          question: `Why does ${r.route} have ${(r.hitRate * 100).toFixed(0)}% cache hit rate on ${r.requests} requests in this metrics window, and is it safe to cache at the edge?`,
+          evidence: {
+            metric: "requestsByRouteCache",
+            route: r.route,
+            requests: r.requests,
+            hitRate: r.hitRate,
+            getShare: r.getShare,
+          },
+        },
+        signals,
+      );
+      if (r.getShare !== null) return candidate;
+      return {
+        ...candidate,
+        disqualified: true,
+        disqualifyReason:
+          "missing GET-share data — route method mix is required before recommending edge caching",
+        warnings: [...new Set([...(candidate.warnings ?? []), "method-share:missing"])],
+      };
+    });
+}
+
+function extractCacheHitRates(signals) {
+  const m = signals.metrics?.requestsByRouteCache;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+
+  const perRoute = new Map();
+  for (const row of m?.rows ?? []) {
+    const route = row.route;
+    if (!route) continue;
+    const value = row.value ?? 0;
+    const prior = perRoute.get(route) ?? { route, hits: 0, total: 0 };
+    if (row.cache_result === "HIT") prior.hits += value;
+    prior.total += value;
+    perRoute.set(route, prior);
+  }
+
+  return [...perRoute.values()].map((r) => ({
+    route: r.route,
+    requests: r.total,
+    hitRate: r.total > 0 ? r.hits / r.total : 0,
+  }));
+}
+
+function extractMethodShares(signals) {
+  const m = signals.metrics?.requestsByRouteMethod;
+  const out = new Map();
+  if (!Array.isArray(m?.rows)) return out;
+  const perRoute = new Map();
+  for (const row of m.rows) {
+    if (!row?.route) continue;
+    const v = row.value ?? 0;
+    const prior = perRoute.get(row.route) ?? { gets: 0, total: 0 };
+    if ((row.request_method ?? "").toUpperCase() === "GET") prior.gets += v;
+    prior.total += v;
+    perRoute.set(row.route, prior);
+  }
+  for (const [route, r] of perRoute) {
+    if (r.total > 0) out.set(route, r.gets / r.total);
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/gates/usage-spike-triage.mjs

@@ -0,0 +1,122 @@
+// Detects per-day billing spikes by inspecting usage.breakdown.data[] (daily granularity).
+// Fires when any single day's total bill > 2× the window mean, OR a single SKU's day value > 3× its window mean.
+// Emits one candidate per spiking SKU (or 'total' when the spike is broad).
+// Degrades gracefully when daily data is unavailable — common path because the skill prefers --group-by project, which omits daily breakdown.
+export const metadata = {
+  id: "usage_spike_triage",
+  threshold: "any-day total > 2x mean OR any-day SKU > 3x SKU mean",
+  billingDimension: "mixed",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "A single day in the billing window deviates sharply from the window baseline. Triage branches: bot or AI crawler spike, viral moment, pricing-model migration (legacy SKU → new), code regression. Without daily-granularity data, this gate stays dormant.",
+};
+
+const TOTAL_MULTIPLIER = 2;
+const SKU_MULTIPLIER = 3;
+const MIN_BILLED_FLOOR = 5; // skip spikes whose absolute value is too small to matter
+
+export function gate(signals) {
+  const days = signals?.usage?.breakdown?.data;
+  if (!Array.isArray(days) || days.length < 3) return [];
+
+  const dayTotals = days.map(dayTotal);
+  const mean = dayTotals.reduce((a, b) => a + b, 0) / dayTotals.length;
+  if (mean <= MIN_BILLED_FLOOR) return [];
+
+  const totalSpikeDays = dayTotals
+    .map((value, idx) => ({ idx, value }))
+    .filter((d) => d.value > mean * TOTAL_MULTIPLIER && d.value > MIN_BILLED_FLOOR);
+
+  const skuStats = aggregateSkuStats(days);
+  const skuSpikes = [];
+  for (const stat of skuStats) {
+    if (stat.mean <= MIN_BILLED_FLOOR) continue;
+    for (const sample of stat.samples) {
+      if (sample.value > stat.mean * SKU_MULTIPLIER && sample.value > MIN_BILLED_FLOOR) {
+        skuSpikes.push({
+          name: stat.name,
+          dayIndex: sample.idx,
+          dayValue: sample.value,
+          skuMean: stat.mean,
+          multiplier: stat.mean > 0 ? sample.value / stat.mean : null,
+        });
+      }
+    }
+  }
+
+  if (totalSpikeDays.length === 0 && skuSpikes.length === 0) return [];
+
+  const candidates = [];
+  if (totalSpikeDays.length > 0) {
+    const peak = totalSpikeDays.reduce((a, b) => (a.value > b.value ? a : b));
+    candidates.push({
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority: 60,
+      confidence: 0.78,
+      o11ySignal: `total_spike day_idx=${peak.idx} day_billed=${peak.value.toFixed(2)} window_mean=${mean.toFixed(2)} mult=${(peak.value / mean).toFixed(1)}x`,
+      reason: "total billed cost on one day exceeds 2× the window mean",
+      question:
+        "Which workload generated the day-over-day spike — bot or AI-crawler traffic on a cacheable route, a viral event, a pricing-model migration, or a code regression?",
+      evidence: {
+        metric: "usage.breakdown.data.total",
+        spikeDay: peak.idx,
+        spikeBilled: peak.value,
+        windowMean: mean,
+        multiplier: peak.value / mean,
+        skuName: "total",
+      },
+    });
+  }
+  // Up to 3 SKU-specific candidates; the rest fold into 'multiple SKUs spiking' framing.
+  const orderedSkuSpikes = skuSpikes.sort((a, b) => b.dayValue - a.dayValue).slice(0, 3);
+  for (const spike of orderedSkuSpikes) {
+    candidates.push({
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority: 55,
+      confidence: 0.78,
+      o11ySignal: `sku_spike sku="${spike.name}" day_idx=${spike.dayIndex} day_billed=${spike.dayValue.toFixed(2)} sku_mean=${spike.skuMean.toFixed(2)} mult=${spike.multiplier.toFixed(1)}x`,
+      reason: `${spike.name} on one day exceeds 3× its window mean`,
+      question: `${spike.name} spiked ${spike.multiplier.toFixed(1)}× on day ${spike.dayIndex}. Which event (bot traffic, viral content, deploy regression, integration sync) drove it, and is the spiking SKU one the skill already covers?`,
+      evidence: {
+        metric: "usage.breakdown.data.services",
+        skuName: spike.name,
+        spikeDay: spike.dayIndex,
+        spikeBilled: spike.dayValue,
+        skuMean: spike.skuMean,
+        multiplier: spike.multiplier,
+      },
+    });
+  }
+  return candidates;
+}
+
+function dayTotal(day) {
+  if (Array.isArray(day?.services)) {
+    return day.services.reduce((a, s) => a + Number(s.billedCost ?? s.cost ?? 0), 0);
+  }
+  return Number(day?.billedCost ?? day?.cost ?? 0);
+}
+
+function aggregateSkuStats(days) {
+  const byName = new Map();
+  days.forEach((day, idx) => {
+    const services = Array.isArray(day?.services) ? day.services : [];
+    for (const svc of services) {
+      const name = String(svc?.name ?? "").trim();
+      if (!name) continue;
+      const value = Number(svc.billedCost ?? svc.cost ?? 0);
+      if (!byName.has(name)) byName.set(name, { name, samples: [] });
+      byName.get(name).samples.push({ idx, value });
+    }
+  });
+  for (const stat of byName.values()) {
+    const sum = stat.samples.reduce((a, s) => a + s.value, 0);
+    stat.mean = stat.samples.length > 0 ? sum / stat.samples.length : 0;
+  }
+  return [...byName.values()];
+}

package/skills/craft/vercel-optimize/lib/grade-recommendation.mjs

@@ -0,0 +1,170 @@
+// 4-axis rubric (specificity, actionability, grounding, evidence) → bucket. See references/recommendations.md.
+// Account-scope (platform_*) recs use a separate grounding/evidence pair — they structurally cannot produce file:line.
+
+const HEDGE_WORDS = /\b(consider|might|may|could|perhaps|maybe|likely|probably)\b/gi;
+const VERB_OPENERS =
+  /^\s*(?:[-*]\s+|\d+[.)]\s+|[*_]+)?(?:add|set|enable|disable|replace|remove|move|wrap|cache|defer|parallelize|introduce|configure|update|change|switch|opt[-\s]?in|opt[-\s]?out|export|import|install|run|delete|rename)/im;
+const COUNT_WORDS_RE =
+  /\b(errors?|queries|invocations|requests|reads|writes|bytes|fetch(?:es)?|calls?|hits?|misses?|seconds?|images?|deployments?|cold[- ]?starts?|users?)\b/gi;
+const UNIT_RE =
+  /\b\d[\d.,]*\s*(?:%|ms|s|sec|seconds?|min|minutes?|h|hours?|GB|MB|KB|K|M|B|rps|qps|req\/s|reqs?\/min)\b/gi;
+const CODE_FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`\n]{10,}`/g;
+const FILE_LINE_RE = /[\w/.\-()\[\]]+\.\w+:\d+/g;
+
+// Grounding + evidence are lie-detectors — weighted higher than specificity/actionability, which LLMs can game with fluff.
+const W = { grounding: 0.35, evidence: 0.3, specificity: 0.2, actionability: 0.15 };
+
+export function gradeRecommendation(rec, ctx = {}) {
+  const accountScope = isAccountScope(rec);
+  const specificity = scoreSpecificity(rec);
+  const actionability = scoreActionability(rec);
+  const grounding = accountScope ? scoreGroundingAccount(rec) : scoreGrounding(rec, ctx);
+  const evidence = accountScope ? scoreEvidenceAccount(rec) : scoreEvidence(rec);
+  const overall = roundTo(
+    grounding * W.grounding +
+      evidence * W.evidence +
+      specificity * W.specificity +
+      actionability * W.actionability,
+    4,
+  );
+  return {
+    specificity,
+    actionability,
+    grounding,
+    evidence,
+    overall,
+    grade: grade(overall),
+    scope: accountScope ? "account" : "route",
+  };
+}
+
+function isAccountScope(rec) {
+  if (rec?.scope === "account") return true;
+  const ref = rec?.candidateRef;
+  if (typeof ref === "string" && ref.startsWith("platform_")) return true;
+  return false;
+}
+
+function grade(overall) {
+  if (overall >= 0.85) return "Excellent";
+  if (overall >= 0.7) return "Good";
+  if (overall >= 0.55) return "Fair";
+  return "Poor";
+}
+
+function scoreSpecificity(rec) {
+  let s = 0;
+  const codeText = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((x) => typeof x === "string")
+    .join("\n");
+  const hasFence = CODE_FENCE_RE.test(codeText);
+  CODE_FENCE_RE.lastIndex = 0;
+  if (hasFence) s += 0.5;
+  if (INLINE_CODE_RE.test(codeText)) s += 0.2;
+  INLINE_CODE_RE.lastIndex = 0;
+  if (Array.isArray(rec.affectedFiles) && rec.affectedFiles.length > 0) s += 0.2;
+  if (Array.isArray(rec.findingRefs) && rec.findingRefs.some((r) => /:\d+/.test(r))) s += 0.3;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function scoreActionability(rec) {
+  const text = typeof rec.fix === "string" ? rec.fix : "";
+  if (!text) return 0;
+  let s = 0;
+  if (VERB_OPENERS.test(text)) s += 0.35;
+  const stepCount = (text.match(/(?:^|\n)\s*(?:\d+[.)]\s+|[-*]\s+)/g) ?? []).length;
+  if (stepCount >= 2) s += 0.35;
+  else if (stepCount === 1) s += 0.15;
+  const hedges = (text.match(HEDGE_WORDS) ?? []).length;
+  HEDGE_WORDS.lastIndex = 0;
+  s -= Math.min(0.3, hedges * 0.1);
+  // Baseline so a verb-only one-liner still scores.
+  s += 0.3;
+  return Math.max(0, Math.min(1, roundTo(s, 4)));
+}
+
+function scoreGrounding(rec, ctx) {
+  let s = 0;
+  const knownFindings = Array.isArray(ctx.knownFindings) ? ctx.knownFindings : [];
+  const findingKeys = new Set(knownFindings.map((f) => `${f.file}:${f.line}`));
+  const refs = Array.isArray(rec.findingRefs) ? rec.findingRefs : [];
+  const matched = refs.filter((r) => findingKeys.has(r));
+  if (matched.length > 0) s += 0.5;
+  else if (refs.length > 0) s += 0.25;
+  if (Array.isArray(rec.affectedFiles) && rec.affectedFiles.length > 0) s += 0.25;
+  const fenceText = [rec.currentBehavior, rec.desiredBehavior]
+    .filter((x) => typeof x === "string")
+    .join("\n");
+  if (CODE_FENCE_RE.test(fenceText)) s += 0.25;
+  CODE_FENCE_RE.lastIndex = 0;
+  if (typeof rec.candidateRef === "string" && rec.candidateRef.length > 0) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function scoreEvidence(rec) {
+  const text = [rec.what, rec.why, rec.fix, rec.verify]
+    .filter((x) => typeof x === "string")
+    .join("\n");
+  if (!text) return 0;
+  const counts = (text.match(COUNT_WORDS_RE) ?? []).length;
+  COUNT_WORDS_RE.lastIndex = 0;
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  const filelines = (text.match(FILE_LINE_RE) ?? []).length;
+  FILE_LINE_RE.lastIndex = 0;
+  // file:line is the gold standard.
+  let s =
+    Math.min(0.5, filelines * 0.2) + Math.min(0.3, units * 0.075) + Math.min(0.2, counts * 0.05);
+  return Math.min(1, roundTo(s, 4));
+}
+
+// No findingRefs/code fences possible — grade structural tie to gate + signal-quoting.
+function scoreGroundingAccount(rec) {
+  let s = 0;
+  if (typeof rec.candidateRef === "string" && rec.candidateRef.startsWith("platform_")) s += 0.4;
+  else if (typeof rec.candidateRef === "string" && rec.candidateRef.length > 0) s += 0.2;
+  // Quoting deep-dive data in why/fix is the account-scope equivalent of citing file:line.
+  const text = [rec.why, rec.fix, rec.verify].filter((x) => typeof x === "string").join("\n");
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  if (units >= 3) s += 0.4;
+  else if (units >= 1) s += 0.2;
+  const citations = Array.isArray(rec.citations) ? rec.citations.length : 0;
+  if (citations >= 2) s += 0.2;
+  else if (citations >= 1) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+// Heavily weighted toward magnitude quoting — vague platform recs should score low.
+function scoreEvidenceAccount(rec) {
+  const text = [rec.what, rec.why, rec.fix, rec.verify]
+    .filter((x) => typeof x === "string")
+    .join("\n");
+  if (!text) return 0;
+  const counts = (text.match(COUNT_WORDS_RE) ?? []).length;
+  COUNT_WORDS_RE.lastIndex = 0;
+  const units = (text.match(UNIT_RE) ?? []).length;
+  UNIT_RE.lastIndex = 0;
+  // Higher weight than route-scope variant — file:line gold standard isn't available.
+  let s = Math.min(0.55, units * 0.15) + Math.min(0.35, counts * 0.08);
+  if (typeof rec.o11ySignal === "string" && rec.o11ySignal.length > 0) s += 0.1;
+  return Math.min(1, roundTo(s, 4));
+}
+
+function roundTo(n, d) {
+  const f = 10 ** d;
+  return Math.round(n * f) / f;
+}
+
+// 0.55 = Poor/Fair boundary. Recommending Poor-graded items erodes trust faster than the marginal recall benefit.
+export function applyQualityFloor(recs, floor = 0.55) {
+  const kept = [];
+  const dropped = [];
+  for (const rec of recs) {
+    const o = rec?.quality?.overall ?? 0;
+    if (o < floor) dropped.push({ rec, reason: `quality.overall=${o} < floor=${floor}` });
+    else kept.push(rec);
+  }
+  return { kept, dropped };
+}

package/skills/craft/vercel-optimize/lib/impact-label.mjs

@@ -0,0 +1,128 @@
+import { impactMagnitude } from "./impact-magnitude.mjs";
+
+const SLOW_ROUTE_P95_THRESHOLD_MS = 500;
+const CACHE_HIT_THRESHOLD_PCT = 50;
+const COLD_START_THRESHOLD_PCT = 40;
+const RELIABILITY_TARGET_PCT = 0.1;
+
+export function computeImpactLabel(rec, signals = {}) {
+  const il = rec?.impactLabel ?? {};
+  if (il.performance) return il.performance;
+  if (il.costPhrase) return il.costPhrase;
+
+  if (typeof rec?.estimatedSavingsUsd === "number" && rec.impactTier) {
+    const magnitude = impactMagnitude({
+      currentCost: rec.estimatedSavingsUsd,
+      impactTier: rec.impactTier,
+    });
+    return magnitude.phrase;
+  }
+
+  return synthesizeImpactFromSignal(rec, signals);
+}
+
+export function synthesizeImpactFromSignal(rec, signals = {}) {
+  const tier = rec?.impactTier;
+  const sig =
+    [rec?.o11ySignal, rec?.evidence?.o11ySignal, rec?.why, rec?.what]
+      .filter((v) => typeof v === "string" && v.trim())
+      .join("\n") || null;
+  if (!sig || !tier) return null;
+  const m = String(sig);
+  const inv = parseSigNumber(m, /inv=([\d,]+)/);
+  const p95 = parseSigNumber(m, /p95=([\d,]+)ms/);
+  const cachePct = parseSigNumber(m, /cache=([\d.]+)%/);
+  const coldPct = parseSigNumber(m, /cold=([\d.]+)%/);
+  const buildSharePct =
+    parseSigNumber(m, /build_minutes_share=([\d.]+)%/i) ??
+    parseSigNumber(m, /build(?: CPU)? minutes share:?\s*([\d.]+)%/i);
+  const errors = parseSigNumber(m, /errs=([\d,]+)/);
+  const errorRatePct = parseSigNumber(m, /rate=([\d.]+)%/);
+  const writes = parseSigNumber(m, /writes=([\d,]+)/);
+  const reads = parseSigNumber(m, /reads=([\d,]+)/);
+  const cwvIssues = [
+    cwvIssue("LCP", parseSigNumber(m, /LCP=([\d.]+)ms/i), 2500, "ms"),
+    cwvIssue("INP", parseSigNumber(m, /INP=([\d.]+)ms/i), 200, "ms"),
+    cwvIssue("CLS", parseSigNumber(m, /CLS=([\d.]+)/i), 0.1, ""),
+  ].filter(Boolean);
+
+  if (cwvIssues.length > 0) {
+    return `${tier} impact — bring ${joinEnglish(cwvIssues.map(formatCwvIssue))}.`;
+  }
+  if (errors != null && errorRatePct != null) {
+    const reductionPct = Math.ceil(Math.max(0, (1 - RELIABILITY_TARGET_PCT / errorRatePct) * 100));
+    return `${tier} impact — cut 5xx rate by ~${reductionPct}% to get below ${RELIABILITY_TARGET_PCT}% (current ${errorRatePct}%, ${formatInteger(errors)} errors in this window).`;
+  }
+  if (errors != null) {
+    return `${tier} impact — resolve ${formatInteger(errors)} billed 5xx errors in this window.`;
+  }
+  if (cachePct != null && inv != null) {
+    if (cachePct < CACHE_HIT_THRESHOLD_PCT) {
+      return `${tier} impact — current cache hit rate is ${cachePct}% across ${formatInteger(inv)} requests in this window; the gate fires below ${CACHE_HIT_THRESHOLD_PCT}%.`;
+    }
+    if (p95 == null) {
+      return `${tier} impact — current cache hit rate is ${cachePct}% across ${formatInteger(inv)} requests in this window; this recommendation targets the remaining uncached traffic.`;
+    }
+  }
+  if (writes != null && reads != null) {
+    const ratio = reads > 0 ? writes / reads : null;
+    return ratio == null
+      ? `${tier} impact — ${formatInteger(writes)} ISR write units with no recorded read units in this window.`
+      : `${tier} impact — ${formatInteger(writes)} ISR write units vs ${formatInteger(reads)} read units in this window (${round2(ratio)} writes per read).`;
+  }
+  if (p95 != null && inv != null) {
+    const multiple = p95 / SLOW_ROUTE_P95_THRESHOLD_MS;
+    return `${tier} impact — current 95th percentile duration is ${formatInteger(p95)}ms across ${formatInteger(inv)} function invocations in this window (${round1(multiple)}x the ${formatInteger(SLOW_ROUTE_P95_THRESHOLD_MS)}ms slow-route threshold).`;
+  }
+  if (coldPct != null) {
+    return `${tier} impact — current cold-start share is ${coldPct}%; the gate fires above ${COLD_START_THRESHOLD_PCT}%.`;
+  }
+  if (
+    rec?.candidateRef?.startsWith("build_minutes_fanout:") ||
+    rec?.kind === "build_minutes_fanout"
+  ) {
+    return buildSharePct != null
+      ? `${tier} impact — Build CPU Minutes account for ${buildSharePct}% of observed billed cost in this window.`
+      : `${tier} impact — Build CPU Minutes exceeded the gate threshold in this window.`;
+  }
+  return `${tier} impact — see follow-up metrics for magnitude.`;
+}
+
+function cwvIssue(metric, value, threshold, unit) {
+  if (value == null || value <= threshold) return null;
+  return { metric, value, threshold, unit };
+}
+
+function formatCwvIssue(i) {
+  const current = i.metric === "CLS" ? round2(i.value) : Math.round(i.value);
+  if (i.unit === "ms") {
+    return `${i.metric} below ${formatInteger(i.threshold)}ms (current ${formatInteger(current)}ms)`;
+  }
+  return `${i.metric} below ${i.threshold}${i.unit} (current ${current}${i.unit})`;
+}
+
+function joinEnglish(parts) {
+  if (parts.length <= 1) return parts[0] ?? "";
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+  return `${parts.slice(0, -1).join(", ")}, and ${parts.at(-1)}`;
+}
+
+function parseSigNumber(s, re) {
+  const m = re.exec(s);
+  if (!m) return null;
+  const n = Number(String(m[1]).replace(/,/g, ""));
+  return Number.isFinite(n) ? n : null;
+}
+
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function formatInteger(n) {
+  if (!Number.isFinite(n)) return String(n);
+  return Math.round(n).toLocaleString("en-US");
+}