@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/gates/build-minutes-fanout.mjs

@@ -0,0 +1,73 @@
+// Build Minutes climb on monorepos when Turborepo cache is bypassed or every project rebuilds on every commit.
+// Threshold: Build Minutes line > 15% of total bill OR scanner emits any turbo-force-bypass finding (even at lower share).
+// Account-scoped because the lever is project-settings (Ignored Build Step, Elastic Build Machines), not code.
+export const metadata = {
+  id: "build_minutes_fanout",
+  threshold: "Build Minutes share > 0.15 OR turbo-force-bypass finding present",
+  billingDimension: "build",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Build Minutes line dominates the bill or Turborepo cache is bypassed. On monorepos, unchanged work should be skipped through Vercel skip-unaffected behavior, a verified Ignored Build Step, and a complete Turbo cache contract.",
+};
+
+const BUILD_RE = /^Build (CPU )?Minutes$/i;
+const SCANNER_PATTERN = "turbo-force-bypass";
+const SHARE_FLOOR = 0.15;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  const total = Array.isArray(services)
+    ? services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+  const buildBilled = Array.isArray(services)
+    ? services
+        .filter((s) => BUILD_RE.test(String(s?.name ?? "")))
+        .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+
+  const buildShare = total > 0 ? buildBilled / total : 0;
+
+  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
+
+  if (buildShare <= SHARE_FLOOR && findings.length === 0) return [];
+
+  const subtypes = unique(findings.map((f) => f.subtype).filter(Boolean));
+  const sampleFiles = unique(findings.map((f) => f.file).filter(Boolean)).slice(0, 4);
+
+  const reason =
+    findings.length > 0
+      ? buildShare > SHARE_FLOOR
+        ? "Build Minutes share is high and Turborepo cache bypass detected in repo"
+        : "Turborepo cache bypass detected in repo"
+      : "Build Minutes line exceeds 15% of total billed cost";
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: sampleFiles,
+      priority: findings.length > 0 ? 65 : 50,
+      confidence: findings.length > 0 ? 0.86 : 0.74,
+      o11ySignal: `build_minutes_share=${(buildShare * 100).toFixed(0)}% scanner_findings=${findings.length}`,
+      reason,
+      question:
+        findings.length > 0
+          ? `Turborepo cache bypass detected (${subtypes.join(", ")}). Which build pipeline forces a rebuild on every commit, and can Ignored Build Step + cache re-enable cut the project fan-out?`
+          : "Build Minutes exceed 15% of the bill. Is Ignored Build Step configured? Is Turborepo cache active across builds? Would Elastic Build Machines reduce duration on hot builds?",
+      evidence: {
+        metric: "usage.services",
+        buildBilled,
+        totalBilled: total,
+        buildShare,
+        scannerFindings: findings.length,
+        scannerSubtypes: subtypes,
+        sampleFiles,
+      },
+    },
+  ];
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}

package/skills/craft/vercel-optimize/lib/gates/cold-start.mjs

@@ -0,0 +1,72 @@
+// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
+// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
+// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
+export const metadata = {
+  id: "cold_start",
+  threshold: "coldPct > 0.4 AND total >= 1000",
+  billingDimension: "function-duration",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.",
+};
+
+export function gate(signals) {
+  const cs = extractColdStarts(signals);
+  return cs
+    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
+    .map((r) => ({
+      kind: metadata.id,
+      scope: "route",
+      route: r.route,
+      files: [],
+      priority: Math.round(r.total * r.coldPct),
+      confidence: 0.92,
+      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
+      reason: "high cold-start rate on hot route",
+      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
+      evidence: {
+        metric: "fnStartTypeByRoute",
+        route: r.route,
+        coldPct: r.coldPct,
+        total: r.total,
+        coldCount: r.coldCount ?? null,
+      },
+    }));
+}
+
+function extractColdStarts(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute;
+  if (Array.isArray(live?.rows) && live.rows.some((r) => "coldCount" in r || "coldPct" in r)) {
+    return live.rows
+      .filter((r) => r.route)
+      .map((r) => ({
+        route: r.route,
+        total: r.total ?? 0,
+        coldCount: r.coldCount ?? 0,
+        coldPct: r.coldPct ?? 0,
+      }));
+  }
+
+  // Legacy fixture: pre-derived coldStartByRoute rows.
+  const direct = signals.metrics?.coldStartByRoute;
+  if (Array.isArray(direct?.rows)) {
+    return direct.rows
+      .filter((r) => r.route)
+      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
+  }
+
+  // Older legacy fixture: series + summary shape.
+  const legacy = signals.metrics?.coldStarts;
+  if (Array.isArray(legacy?.series)) {
+    return legacy.series
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route);
+  }
+
+  return [];
+}

package/skills/craft/vercel-optimize/lib/gates/contract.mjs

@@ -0,0 +1,82 @@
+const VALID_SCOPES = new Set(["route", "file", "account"]);
+
+export class CandidateContractError extends Error {
+  constructor(errors) {
+    super(`gate candidate contract failed:\n${errors.map((e) => `- ${e}`).join("\n")}`);
+    this.name = "CandidateContractError";
+    this.errors = errors;
+  }
+}
+
+export function validateCandidates(candidates, ctx = {}) {
+  if (!Array.isArray(candidates)) {
+    throw new CandidateContractError([`${ctx.source ?? "gate"}: expected candidate array`]);
+  }
+  const errors = [];
+  for (let i = 0; i < candidates.length; i++) {
+    errors.push(...validateCandidate(candidates[i], { ...ctx, index: i }).errors);
+  }
+  if (errors.length > 0) throw new CandidateContractError(errors);
+  return candidates;
+}
+
+export function validateCandidate(candidate, ctx = {}) {
+  const label = candidateLabel(candidate, ctx);
+  const errors = [];
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return { ok: false, errors: [`${label}: candidate must be an object`] };
+  }
+
+  if (!nonEmptyString(candidate.kind)) errors.push(`${label}: kind must be a non-empty string`);
+  if (!VALID_SCOPES.has(candidate.scope)) {
+    errors.push(`${label}: scope must be one of route, file, account`);
+  }
+  if (!Number.isFinite(candidate.priority))
+    errors.push(`${label}: priority must be a finite number`);
+  if (!Number.isFinite(candidate.confidence))
+    errors.push(`${label}: confidence must be a finite number`);
+  if (Array.isArray(candidate.files)) {
+    if (!candidate.files.every((f) => typeof f === "string" && f.length > 0)) {
+      errors.push(`${label}: files must contain only non-empty strings`);
+    }
+  } else {
+    errors.push(`${label}: files must be an array`);
+  }
+  if (!nonEmptyString(candidate.reason)) errors.push(`${label}: reason must be a non-empty string`);
+  if (!nonEmptyString(candidate.question))
+    errors.push(`${label}: question must be a non-empty string`);
+
+  if (candidate.scope === "route") {
+    const hasRoute = nonEmptyString(candidate.route);
+    const hasHostname = nonEmptyString(candidate.hostname);
+    if (!hasRoute && !hasHostname) {
+      errors.push(`${label}: route-scoped candidates must set route or hostname`);
+    }
+  }
+  if (candidate.scope === "file") {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: file-scoped candidates must not set route or hostname`);
+    }
+    if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
+      errors.push(`${label}: file-scoped candidates must include at least one file`);
+    }
+  }
+  if (candidate.scope === "account") {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: account-scoped candidates must not set route or hostname`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function candidateLabel(candidate, ctx) {
+  const source = ctx.source ?? "gate";
+  const index = ctx.index == null ? "?" : ctx.index;
+  const kind = candidate?.kind ?? "?";
+  return `${source}[${index}] ${kind}`;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/skills/craft/vercel-optimize/lib/gates/cwv-poor.mjs

@@ -0,0 +1,95 @@
+// Thresholds are Google's "Poor" band (https://web.dev/articles/vitals): LCP p75 > 2500ms, INP > 200ms, CLS > 0.1.
+// When Speed Insights isn't wired up the metrics come back empty and the gate is a no-op.
+import { withRouteShapeWarnings } from "../route-normalize.mjs";
+
+export const metadata = {
+  id: "cwv_poor",
+  threshold: "LCP p75>2500 OR INP p75>200 OR CLS p75>0.1, AND speed_insights count > 50",
+  billingDimension: "speed-insights",
+  scope: "route",
+  sourceCitation: "https://web.dev/articles/vitals",
+  description:
+    'Routes where Core Web Vitals fall into Google\'s "Poor" band on real-user traffic. LCP > 2500ms, INP > 200ms, or CLS > 0.1 each hurt SEO and conversion. Surfaces one candidate per (route, metric) pair to keep recommendations focused.',
+};
+
+// Below this floor p75 is too noisy to act on.
+const MIN_PER_ROUTE_SAMPLES = 50;
+
+export function gate(signals) {
+  const totalSamples = sumRows(signals.metrics?.cwvCount?.rows);
+  if (totalSamples === 0) return [];
+
+  const countByRoute = byRoute(signals.metrics?.cwvCountByRoute?.rows);
+  const lcpBy = byRoute(signals.metrics?.cwvLcpByRoute?.rows);
+  const inpBy = byRoute(signals.metrics?.cwvInpByRoute?.rows);
+  const clsBy = byRoute(signals.metrics?.cwvClsByRoute?.rows);
+
+  const routes = new Set([...lcpBy.keys(), ...inpBy.keys(), ...clsBy.keys()]);
+  const out = [];
+  for (const route of routes) {
+    const routeSamples = countByRoute.get(route) ?? 0;
+    if (routeSamples < MIN_PER_ROUTE_SAMPLES) continue;
+    const lcp = lcpBy.get(route);
+    const inp = inpBy.get(route);
+    const cls = clsBy.get(route);
+    const issues = [];
+    if (lcp != null && lcp > 2500)
+      issues.push({ metric: "LCP", value: Math.round(lcp), threshold: 2500, unit: "ms" });
+    if (inp != null && inp > 200)
+      issues.push({ metric: "INP", value: Math.round(inp), threshold: 200, unit: "ms" });
+    if (cls != null && cls > 0.1)
+      issues.push({ metric: "CLS", value: round2(cls), threshold: 0.1, unit: "" });
+    if (issues.length === 0) continue;
+
+    const summary = issues.map((i) => `${i.metric}=${i.value}${i.unit}`).join(",");
+    out.push(
+      withRouteShapeWarnings(
+        {
+          kind: metadata.id,
+          scope: "route",
+          route,
+          files: [],
+          priority: issues.reduce((s, i) => s + ratioOverThreshold(i), 0) * 10,
+          confidence: 0.82,
+          o11ySignal: summary,
+          reason: "real-user Core Web Vitals in poor band",
+          question: `On ${route}, ${summary}. Which client-side work (bundle weight, blocking scripts, layout shifts, hydration) is responsible, and which change would land first?`,
+          evidence: {
+            metric: "cwv",
+            route,
+            lcpMs: lcp != null ? Math.round(lcp) : null,
+            inpMs: inp != null ? Math.round(inp) : null,
+            cls: cls != null ? round2(cls) : null,
+            issues,
+            totalSpeedInsightsSamples: totalSamples,
+            routeSpeedInsightsSamples: routeSamples,
+          },
+        },
+        signals,
+      ),
+    );
+  }
+  return out;
+}
+
+function byRoute(rows) {
+  const m = new Map();
+  for (const r of rows ?? []) {
+    if (!r.route || r.value == null) continue;
+    m.set(r.route, r.value);
+  }
+  return m;
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function ratioOverThreshold(i) {
+  return i.value / (i.threshold || 1);
+}

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

@@ -0,0 +1,60 @@
+// Volume floor pairs p75 with call_count so a single 5s cron/day doesn't fire the gate.
+const MIN_CALL_COUNT = 500;
+
+export const metadata = {
+  id: "external_api_slow",
+  threshold: `p75Ms > 2000 AND callCount >= ${MIN_CALL_COUNT}`,
+  billingDimension: "function-duration",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "External API hostnames with p75 latency above 2 seconds AND at least 500 calls in the window. External API latency is a primary driver of function duration cost when the upstream is on a hot path; a single slow stale call isn't worth recommending against.",
+};
+
+export function gate(signals) {
+  const apis = extractExternalApis(signals);
+  const calls = extractCallCounts(signals);
+  return apis
+    .map((a) => ({ ...a, callCount: calls.get(a.hostname) ?? 0 }))
+    .filter((a) => a.p75Ms > 2000 && a.callCount >= MIN_CALL_COUNT)
+    .map((a) => ({
+      kind: metadata.id,
+      scope: "route",
+      route: null,
+      files: [],
+      hostname: a.hostname,
+      // Weight by latency × call volume so 100k-call/2.1s outranks 1k-call/8s.
+      priority: Math.round((a.p75Ms * a.callCount) / 1000),
+      confidence: 0.88,
+      o11ySignal: `host=${a.hostname},p75=${a.p75Ms}ms,calls=${a.callCount}`,
+      reason: "slow external dependency on hot path",
+      question: `Which routes call ${a.hostname} (p75=${a.p75Ms}ms across ${a.callCount} calls), and can the call be parallelized, cached, or moved off the critical path?`,
+      evidence: {
+        metric: "externalApiP75",
+        hostname: a.hostname,
+        p75Ms: a.p75Ms,
+        callCount: a.callCount,
+      },
+    }));
+}
+
+function extractExternalApis(signals) {
+  const m = signals.metrics?.externalApiP75;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+  return (m?.rows ?? [])
+    .map((r) => ({
+      hostname: r.origin_hostname,
+      p75Ms: Math.round(r.value ?? 0),
+    }))
+    .filter((a) => a.hostname);
+}
+
+function extractCallCounts(signals) {
+  const m = signals.metrics?.externalApiCount;
+  const out = new Map();
+  if (!m) return out;
+  for (const r of m.rows ?? []) {
+    if (r?.origin_hostname) out.set(r.origin_hostname, r.value ?? 0);
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/gates/hard-gates.mjs

@@ -0,0 +1,70 @@
+import { canonicalizeRoute } from "../route-normalize.mjs";
+
+export const FLAGS_ENDPOINT = "/.well-known/vercel/flags";
+export const VERCEL_FLAGS_PACKAGES = [
+  "@vercel/flags",
+  "@vercel/flags/next",
+  "@vercel/flags/sveltekit",
+  "@vercel/flags/nuxt",
+];
+export const WORKFLOW_ENDPOINT_PREFIXES = ["/.well-known/workflow", "/api/.well-known/workflow"];
+
+export function applyHardGates(candidates, signals = {}) {
+  const allowed = [];
+  const gated = [];
+  for (const candidate of candidates) {
+    if (isFlagsEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: flagsEndpointReason(signals),
+      });
+      continue;
+    }
+    if (isWorkflowRuntimeEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: workflowEndpointReason(signals),
+      });
+      continue;
+    }
+    allowed.push(candidate);
+  }
+  return { allowed, gated };
+}
+
+export function isFlagsEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === "account") return false;
+  const route = normalizeRoute(candidate.route);
+  return route === FLAGS_ENDPOINT;
+}
+
+export function isWorkflowRuntimeEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === "account") return false;
+  const route = normalizeRoute(candidate.route);
+  if (!route) return false;
+  return WORKFLOW_ENDPOINT_PREFIXES.some(
+    (prefix) => route === prefix || route.startsWith(`${prefix}/`),
+  );
+}
+
+function normalizeRoute(route) {
+  if (typeof route !== "string") return null;
+  const normalized = canonicalizeRoute(route).replace(/\/+$/, "");
+  return normalized === "" ? "/" : normalized;
+}
+
+function flagsEndpointReason(signals) {
+  const packages = signals.stack?.vercelFlagsPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint (${packages.join(", ")} detected), not an optimization target`;
+  }
+  return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint, not an optimization target`;
+}
+
+function workflowEndpointReason(signals) {
+  const packages = signals.stack?.workflowPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: Vercel Workflow runtime endpoint (${packages.join(", ")} detected); long-running step/flow requests are expected orchestration, not an app-route optimization target`;
+  }
+  return "hardGated: Vercel Workflow runtime endpoint; long-running step/flow requests are expected orchestration, not an app-route optimization target";
+}

package/skills/craft/vercel-optimize/lib/gates/index.mjs

@@ -0,0 +1,45 @@
+import * as buildMinutesFanout from "./build-minutes-fanout.mjs";
+import * as coldStart from "./cold-start.mjs";
+import * as cwvPoor from "./cwv-poor.mjs";
+import * as externalApiSlow from "./external-api-slow.mjs";
+import * as isrOverrevalidation from "./isr-overrevalidation.mjs";
+import * as middlewareHeavy from "./middleware-heavy.mjs";
+import * as observabilityEventsAttribution from "./observability-events-attribution.mjs";
+import * as platformBotProtection from "./platform-bot-protection.mjs";
+import * as platformFluidCompute from "./platform-fluid-compute.mjs";
+import * as regionMisconfig from "./region-misconfig.mjs";
+import * as routeErrors from "./route-errors.mjs";
+import * as scannerDriven from "./scanner-driven.mjs";
+import * as slowRoute from "./slow-route.mjs";
+import * as uncachedRoute from "./uncached-route.mjs";
+import * as usageSpikeTriage from "./usage-spike-triage.mjs";
+
+// Intentionally NOT registered:
+//   - `oversized_memory`: Fluid Compute floor is 2GB; per-route memory right-sizing isn't a customer lever.
+//   - `deploy_regression`: overlaps Vercel Agent Investigations; `vercel inspect` 404s across teams. slow_route deep-dive already carries per-deployment p95 trend.
+export const gates = [
+  uncachedRoute,
+  slowRoute,
+  routeErrors,
+  coldStart,
+  isrOverrevalidation,
+  cwvPoor,
+  externalApiSlow,
+  scannerDriven,
+  // Account-scoped last so platform-scoped sort doesn't dilute code-scoped priority ordering during budget application.
+  platformFluidCompute,
+  platformBotProtection,
+  middlewareHeavy,
+  observabilityEventsAttribution,
+  usageSpikeTriage,
+  buildMinutesFanout,
+  regionMisconfig,
+];
+
+// Overridable via `--max-candidates N` or `VERCEL_OPTIMIZE_MAX_CANDIDATES` (accepts `all`).
+// `MAX_CODE_CANDIDATES` is a back-compat alias for tests importing the old name.
+export const DEFAULT_MAX_CODE_CANDIDATES = 6;
+export const MAX_CODE_CANDIDATES = DEFAULT_MAX_CODE_CANDIDATES;
+
+// Bump on any threshold change so report + iteration baselines can detect gate-logic drift.
+export const GATE_VERSION = "1.8.0";

package/skills/craft/vercel-optimize/lib/gates/isr-overrevalidation.mjs

@@ -0,0 +1,62 @@
+// ISR writes re-execute the page render. A w/r ratio above 0.5 means writes are
+// happening at least once for every two reads — high enough for the default
+// audit to spend investigation budget. writes>100 avoids flapping on quiet routes.
+export const metadata = {
+  id: "isr_overrevalidation",
+  threshold: "writes/reads > 0.5 AND writes > 100",
+  billingDimension: "isr",
+  scope: "route",
+  sourceCitation: "https://vercel.com/docs/incremental-static-regeneration",
+  description:
+    "ISR routes with > 1 write per 2 reads. The revalidate interval is too aggressive relative to read traffic — many reads pay to regenerate. Investigate whether the page can tolerate a longer revalidate window or on-demand revalidation via revalidateTag.",
+};
+
+export function gate(signals) {
+  const rows = extractRows(signals);
+  return rows
+    .filter((r) => r.writes > 100 && r.reads > 0 && r.writes / r.reads > 0.5)
+    .map((r) => {
+      const ratio = r.writes / r.reads;
+      return {
+        kind: metadata.id,
+        scope: "route",
+        route: r.route,
+        files: [],
+        priority: Math.round(r.writes),
+        confidence: 0.88,
+        o11ySignal: `writes=${r.writes},reads=${r.reads},w/r=${ratio.toFixed(2)}`,
+        reason: "ISR revalidating faster than read traffic justifies",
+        question: `On ${r.route}, ${r.writes} ISR writes against ${r.reads} reads (${(ratio * 100).toFixed(0)} writes per 100 reads) — what is the current revalidate interval and can it be lengthened or switched to on-demand?`,
+        evidence: {
+          metric: "isrWritesByRoute",
+          route: r.route,
+          writes: r.writes,
+          reads: r.reads,
+          ratio,
+        },
+      };
+    });
+}
+
+function extractRows(signals) {
+  const writes = signals.metrics?.isrWritesByRoute?.rows ?? [];
+  const reads = signals.metrics?.isrReadsByRoute?.rows ?? [];
+
+  const writeByRoute = new Map();
+  for (const r of writes) {
+    if (!r.route) continue;
+    writeByRoute.set(r.route, (writeByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+  const readByRoute = new Map();
+  for (const r of reads) {
+    if (!r.route) continue;
+    readByRoute.set(r.route, (readByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+
+  const routes = new Set([...writeByRoute.keys(), ...readByRoute.keys()]);
+  return [...routes].map((route) => ({
+    route,
+    writes: writeByRoute.get(route) ?? 0,
+    reads: readByRoute.get(route) ?? 0,
+  }));
+}

package/skills/craft/vercel-optimize/lib/gates/middleware-heavy.mjs

@@ -0,0 +1,53 @@
+// Middleware runs in front of every matching request and is billed as edge invocations.
+// If >50% of traffic hits middleware, the matcher is probably broader than necessary.
+export const metadata = {
+  id: "middleware_heavy",
+  threshold: "middlewareInv/totalInv > 0.5 AND middlewareInv > 1000",
+  billingDimension: "edge-requests",
+  scope: "account",
+  sourceCitation: "https://nextjs.org/docs/app/building-your-application/routing/middleware",
+  description:
+    "Middleware invocations cover > 50% of total requests at non-trivial volume. The matcher is probably broader than necessary; narrow it to the paths that actually need auth/rewrites/headers.",
+};
+
+export function gate(signals) {
+  const middlewareInv = sumRows(signals.metrics?.middlewareCount?.rows);
+  if (middlewareInv < 1000) return [];
+
+  const totalInv = sumRows(signals.metrics?.requestsByRouteCache?.rows);
+  if (totalInv === 0) return [];
+
+  const ratio = middlewareInv / totalInv;
+  if (ratio <= 0.5) return [];
+
+  const top = [...(signals.metrics?.middlewareCount?.rows ?? [])]
+    .filter((r) => r.request_path)
+    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))
+    .slice(0, 5)
+    .map((r) => ({ request_path: r.request_path, count: r.value ?? 0 }));
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority: Math.round(middlewareInv / 1000),
+      confidence: 0.84,
+      o11ySignal: `middleware_inv=${middlewareInv},total_req=${totalInv},ratio=${(ratio * 100).toFixed(0)}%`,
+      reason: "middleware ran on more than half of all requests",
+      question: `Middleware invocations (${middlewareInv}) are ${(ratio * 100).toFixed(0)}% of all requests (${totalInv}). Which paths in middleware.ts require interception, and can the matcher be narrowed to exclude static assets, images, and routes that do not need rewriting?`,
+      evidence: {
+        metric: "middlewareCount",
+        middlewareInv,
+        totalInv,
+        ratio,
+        topPaths: top,
+      },
+    },
+  ];
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}

package/skills/craft/vercel-optimize/lib/gates/observability-events-attribution.mjs

@@ -0,0 +1,58 @@
+// Observability Events is the metered SKU under Observability Plus.
+// Threshold at >20% surfaces material spend; >30% is the critical band.
+// Drivers correlate with low cache hit rate, high middleware invocation, and high custom-span cardinality.
+export const metadata = {
+  id: "observability_events_attribution",
+  threshold: "observabilityEventsShare > 0.20 (critical at > 0.30)",
+  billingDimension: "observability-events",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Observability Events line item exceeds 20% of total billed cost. High share usually traces to low cache hit rate, middleware-heavy traffic, or unconstrained custom-span cardinality. No sampling lever exists for Observability Plus; reduce upstream invocations instead.",
+};
+
+const EVENTS_RE = /^Observability Events$/i;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  if (!Array.isArray(services) || services.length === 0) return [];
+
+  const total = sumBilled(services);
+  if (total <= 0) return [];
+
+  const eventsBilled = services
+    .filter((s) => EVENTS_RE.test(String(s?.name ?? "")))
+    .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+  if (eventsBilled <= 0) return [];
+
+  const share = eventsBilled / total;
+  if (share <= 0.2) return [];
+
+  const critical = share > 0.3;
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: [],
+      priority: critical ? 70 : 55,
+      confidence: 0.82,
+      o11ySignal: `observability_events_share=${(share * 100).toFixed(0)}%`,
+      reason: critical
+        ? "observability events exceed 30% of total billed cost"
+        : "observability events exceed 20% of total billed cost",
+      question: `Observability Events are ${(share * 100).toFixed(0)}% of the bill. Which routes drive event volume — low-cache-hit traffic, broad middleware invocation, or high custom-span cardinality — and can event volume be reduced upstream of the meter?`,
+      evidence: {
+        metric: "usage.services",
+        eventsBilled,
+        totalBilled: total,
+        observabilityEventsShare: share,
+        critical,
+      },
+    },
+  ];
+}
+
+function sumBilled(services) {
+  return services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+}