@oriro/orirocli 0.1.8 → 0.1.11

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

@@ -1,122 +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()];
-}
+// 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

@@ -1,170 +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 };
-}
+// 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 };
+}