opencode-skills-collection 3.0.35 → 3.0.36

package/bundled-skills/vercel-optimize/lib/render-report.mjs

@@ -0,0 +1,955 @@
+// Deterministic markdown renderer. Same inputs → byte-identical output (modulo caller-supplied generatedAt).
+
+import { createHash } from 'node:crypto';
+import { computeImpactLabel } from './impact-label.mjs';
+import { deriveProjectFacts } from './project-facts.mjs';
+import { canonicalizeRoute } from './route-normalize.mjs';
+import { computeCostCoverage, renderCostCoverageMarkdown } from './cost-coverage.mjs';
+import { gates as registeredGates } from './gates/index.mjs';
+import { formatCandidateLabel, formatKind, formatPublicText, formatRoute, formatSignal } from './display-labels.mjs';
+import { splitCustomerSafeObservations } from './observation-safety.mjs';
+
+const PLATFORM_CAP = 3;
+const GATED_TARGET_PREVIEW = 5;
+
+export function renderReport({ recommendations = [], gated = [], abstentions = [], observations = [], signals = {}, candidates = [], opts = {} } = {}) {
+  const safety = splitCustomerSafeObservations(observations, abstentions, signals);
+  observations = safety.observations;
+  abstentions = [...abstentions, ...safety.heldBackObservations];
+  assertValidObservations(observations);
+
+  const projectName = opts.projectName ?? signals.project?.name ?? '<project>';
+  const stack = signals.stack ?? signals.codebase?.stack ?? {};
+  const usage = signals.usage ?? null;
+  const plan = signals.plan ?? { plan: 'unknown', reason: '(not detected)' };
+
+  // Sub-agents don't always propagate o11ySignal/aliasRoutes — look them up by candidateRef and canonicalize the displayed ref.
+  recommendations = recommendations.map((r) => enrichRecFromCandidates(r, candidates));
+  const { needsEvidenceRows, noChangeRows } = splitInvestigationOutcomes(abstentions);
+
+  const lines = [];
+  lines.push(`# Vercel Optimization Report — ${projectName}`);
+  lines.push('');
+  lines.push(renderMetadataLine(stack, plan, usage, signals));
+  const coverageLine = renderCoverageLine(candidates, recommendations, signals, {
+    abstentions,
+    heldBackCount: opts.heldBackCount,
+    noChangeCount: opts.noChangeCount,
+  });
+  if (coverageLine) lines.push(coverageLine);
+  if (opts.generatedAt) {
+    lines.push('');
+    lines.push(`_Generated ${opts.generatedAt}_`);
+  }
+  lines.push('');
+
+  lines.push(...renderCostHeader(signals));
+  lines.push('');
+  lines.push(...renderCostBreakdown(usage, signals));
+  if (usage) {
+    const coverage = computeCostCoverage(usage, registeredGates);
+    lines.push(...renderCostCoverageMarkdown(coverage));
+  }
+  lines.push('');
+
+  const platformRecs = recommendations.filter(isPlatformScope).slice(0, PLATFORM_CAP);
+  const codeRecs = recommendations.filter((r) => !isPlatformScope(r));
+  const sorted = sortRecs(codeRecs);
+  const high = sorted.filter((r) => r.impactTier === 'high');
+  const medium = sorted.filter((r) => r.impactTier === 'medium');
+  const low = sorted.filter((r) => r.impactTier === 'low' || !r.impactTier);
+  lines.push('## Highest-impact recommendations');
+  lines.push('');
+  if (sorted.length === 0) {
+    lines.push('_No recommendations are ready to apply from this run._');
+  } else {
+    const top = sorted.slice(0, 5);
+    top.forEach((rec, i) => {
+      const candidate = candidateForDisplay(rec);
+      const signal = formatSignal(rec.o11ySignal ?? signalFromRec(rec) ?? '', candidate);
+      lines.push(`${i + 1}. **${formatCandidateLabel(candidate)}** — ${signal}`);
+      lines.push(`   - **What to do**: ${formatRecommendationText(rec.what ?? '')}`);
+      lines.push(`   - **Impact**: ${formatRecommendationText(impactString(rec, signals))}`);
+      if (rec.effort) lines.push(`   - **Effort**: ${rec.effort}`);
+      const cites = asArray(rec.citations);
+      if (cites.length > 0) lines.push(`   - **Citations**: ${cites.join(', ')}`);
+    });
+  }
+  lines.push('');
+
+  lines.push('## Recommendations');
+  lines.push('');
+  lines.push('### High impact');
+  lines.push('');
+  lines.push(...renderRecTable(high, signals));
+  lines.push('');
+  lines.push('### Medium impact');
+  lines.push('');
+  lines.push(...renderRecTable(medium, signals));
+  lines.push('');
+  if (low.length > 0) {
+    lines.push('### Low impact');
+    lines.push('');
+    lines.push(...renderRecTable(low, signals));
+    lines.push('');
+  }
+
+  lines.push('## Detailed recommendations');
+  lines.push('');
+  if (sorted.length === 0) {
+    lines.push('_No recommendations are ready to apply from this run._');
+  } else {
+    for (const [i, rec] of sorted.entries()) {
+      lines.push(...renderRecDetail(rec, i + 1, { signals }));
+    }
+  }
+  lines.push('');
+
+  lines.push('## Platform recommendations');
+  lines.push('');
+  if (platformRecs.length === 0) {
+    lines.push('_(none — the gate did not surface any platform-scope recommendations)_');
+  } else {
+    for (const [i, rec] of platformRecs.entries()) {
+      lines.push(...renderRecDetail(rec, i + 1, { compact: true, signals }));
+    }
+  }
+  lines.push('');
+
+  // Observations carry actionable signal discovered during investigation.
+  if (observations.length > 0) {
+    lines.push('## Observations from investigation');
+    lines.push('');
+    lines.push('These are real signals from the audit, but they are not ready-to-apply recommendations.');
+    lines.push('');
+    lines.push('| Candidate | Observation | Evidence | Suggested action | Kind |');
+    lines.push('|---|---|---|---|---|');
+    for (const o of observations) {
+      const ref = o.candidateRef ?? '(unspecified)';
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(formatEvidenceText(o.summary))} | ${escape(formatEvidenceText(o.evidence ?? '_(none recorded)_'))} | ${escape(formatEvidenceText(o.suggestedAction ?? '_(none recorded)_'))} | ${escape(formatKind(o.kind ?? 'other'))} |`);
+    }
+    lines.push('');
+  }
+
+  // Trust mechanism: customer sees what was investigated and why no rec emerged.
+  if (needsEvidenceRows.length > 0) {
+    lines.push('## Needs more evidence');
+    lines.push('');
+    lines.push('These candidates were investigated, but automated checks kept the change out of the ready-to-apply list.');
+    lines.push('');
+    lines.push('| Candidate | Why it was held back |');
+    lines.push('|---|---|');
+    for (const a of needsEvidenceRows) {
+      const ref = a.candidateRef ?? '(unspecified)';
+      const reason = publicNoRecommendationReason(a.reason ?? '(no reason recorded)');
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(reason)} |`);
+    }
+    lines.push('');
+  }
+
+  if (noChangeRows.length > 0) {
+    lines.push('## Investigated, no change recommended');
+    lines.push('');
+    lines.push('These candidates were checked and did not produce a supported change.');
+    lines.push('');
+    lines.push('| Candidate | Why no recommendation shipped |');
+    lines.push('|---|---|');
+    for (const a of noChangeRows) {
+      const ref = a.candidateRef ?? '(unspecified)';
+      const reason = publicNoRecommendationReason(a.reason ?? '(no reason recorded)');
+      lines.push(`| ${escape(displayCandidateRef(ref))} | ${escape(reason)} |`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Not investigated in this run');
+  lines.push('');
+  lines.push(...renderGatedTable(gated));
+  lines.push('');
+
+  lines.push('## Strengths');
+  lines.push('');
+  lines.push(...renderStrengths(signals));
+  lines.push('');
+
+  const configNotes = renderConfigurationNotes(signals);
+  if (configNotes.length > 0) {
+    lines.push('## Configuration notes');
+    lines.push('');
+    lines.push(...configNotes);
+    lines.push('');
+  }
+
+  lines.push('## Data gaps');
+  lines.push('');
+  lines.push(...renderDataGaps(signals));
+
+  return lines.join('\n');
+}
+
+function assertValidObservations(observations) {
+  if (!Array.isArray(observations)) {
+    throw new TypeError('renderReport observations must be an array');
+  }
+  for (const [i, o] of observations.entries()) {
+    if (!o || typeof o !== 'object') {
+      throw new TypeError(`renderReport observations[${i}] must be an object`);
+    }
+    if (typeof o.summary !== 'string' || o.summary.trim() === '') {
+      throw new TypeError(`renderReport observations[${i}].summary is required`);
+    }
+  }
+}
+
+export function buildFinalReportMessage({ reportPath, markdown, recommendations = [], signals = {}, maxRecommendations = 10 } = {}) {
+  const destination = reportPath || 'report.md';
+  const coverageLine = extractCoverageLine(markdown);
+  const lines = [`Report saved: ${destination}`];
+  if (coverageLine) {
+    lines.push('');
+    lines.push(stripDetailsLink(coverageLine));
+  } else {
+    lines.push('');
+    lines.push('Open the report for details. No coverage summary was available.');
+  }
+  const readyPreview = renderFinalRecommendationPreview(recommendations, signals, maxRecommendations);
+  if (readyPreview.length > 0) {
+    lines.push('');
+    lines.push(...readyPreview);
+  }
+  const body = lines.join('\n');
+  return {
+    body,
+    lineCount: lines.length,
+    sha256: createHash('sha256').update(body).digest('hex'),
+    reportPath: destination,
+    coverageLine: coverageLine ?? null,
+    recommendationsShown: readyPreview.filter((line) => /^\d+\./.test(line)).length,
+  };
+}
+
+function renderFinalRecommendationPreview(recommendations, signals, maxRecommendations) {
+  const ready = Array.isArray(recommendations)
+    ? sortRecs(recommendations.filter((r) => r && r.abstain !== true))
+    : [];
+  if (ready.length === 0) return [];
+  const max = Math.max(1, Math.min(Number.isInteger(maxRecommendations) ? maxRecommendations : 5, 10));
+  const shown = ready.slice(0, max);
+  const lines = ['Ready recommendations:'];
+  for (const [i, rec] of shown.entries()) {
+    lines.push(`${i + 1}. ${compactFinalText(rec.what ?? displayCandidate(rec))}`);
+    const impact = impactString(rec, signals);
+    if (impact && !/^_\(no impact framing recorded\)_$/.test(impact)) {
+      lines.push(`   Impact: ${compactFinalText(impact)}`);
+    }
+  }
+  const hidden = ready.length - shown.length;
+  if (hidden > 0) {
+    lines.push(`Open the report for ${hidden} more ready recommendation${hidden === 1 ? '' : 's'} and the full evidence.`);
+  }
+  return lines;
+}
+
+function compactFinalText(value) {
+  const text = formatRecommendationText(String(value ?? ''))
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= 220) return text;
+  return `${text.slice(0, 217).trimEnd()}...`;
+}
+
+function extractCoverageLine(markdown) {
+  if (typeof markdown !== 'string') return null;
+  return markdown
+    .split('\n')
+    .find((line) => line.startsWith('**Coverage**:')) ?? null;
+}
+
+function stripDetailsLink(line) {
+  return String(line).replace(/\s*·\s*\[details\]\(#not-investigated-in-this-run\)\s*$/, '');
+}
+
+// Hidden when no candidates exist (e.g., observability blocker — nothing to cover).
+function renderCoverageLine(candidates, recommendations, signals, opts = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  const launched = candidates.filter((c) => !c.gatedReason && !c.disqualified && c.scope !== 'account');
+  const skippedByBudget = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason.startsWith('skippedByBudget')
+  );
+  const coveredByDedup = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason.startsWith('coveredBy')
+  );
+  const disqualified = candidates.filter(
+    (c) => typeof c.gatedReason === 'string' && c.gatedReason === c.disqualifyReason
+  );
+  const total = launched.length + skippedByBudget.length;
+  if (total === 0) return null;
+  const parts = [];
+  parts.push(`Found **${total}** potential issue${total === 1 ? '' : 's'} to check`);
+  parts.push(`${launched.length} investigated`);
+  if (skippedByBudget.length > 0) {
+    parts.push(`${skippedByBudget.length} left for a larger run — re-run with \`--max-candidates all\` to see the rest`);
+  }
+  if (coveredByDedup.length > 0) {
+    parts.push(`${coveredByDedup.length} similar route variant${coveredByDedup.length === 1 ? '' : 's'} grouped`);
+  }
+  const recCount = (recommendations ?? []).filter((r) => !r.abstain && !isPlatformScope(r)).length;
+  parts.push(`${recCount} recommendation${recCount === 1 ? '' : 's'} ready`);
+  const rawHeldBackCount = Number.isInteger(opts.heldBackCount)
+    ? opts.heldBackCount
+    : (Array.isArray(opts.abstentions) ? opts.abstentions.filter((a) => a?.needsEvidence === true).length : 0);
+  const heldBackCount = Math.min(rawHeldBackCount, Math.max(0, launched.length - recCount));
+  if (heldBackCount > 0) {
+    parts.push(`${heldBackCount} need more evidence`);
+  }
+  const rawNoChangeCount = Number.isInteger(opts.noChangeCount)
+    ? opts.noChangeCount
+    : (Array.isArray(opts.abstentions) ? opts.abstentions.length : 0);
+  const noChangeCount = Math.min(rawNoChangeCount, Math.max(0, launched.length - recCount - heldBackCount));
+  if (noChangeCount > 0) {
+    parts.push(`${noChangeCount} investigated, no change recommended`);
+  }
+  return `**Coverage**: ${parts.join('  ·  ')} · [details](#not-investigated-in-this-run)`;
+}
+
+function renderMetadataLine(stack, plan, usage, signals = {}) {
+  const fw = `${stack.framework ?? 'unknown'}@${stack.frameworkVersion ?? '?'}`;
+  const router = stack.hasAppRouter ? 'app-router' : stack.hasPagesRouter ? 'pages-router' : null;
+  const orm = stack.orm && stack.orm !== 'none' ? stack.orm : null;
+  const stackParts = [fw, router, orm].filter(Boolean).join(' | ');
+  const period = usage?.period
+    ? `${usage.period.from ?? '?'} → ${usage.period.to ?? '?'}`
+    : '(unavailable)';
+  const oplusLabel = observabilityLabel(signals, usage);
+  // Plan-inference reason is debug detail — only surface when plan is uncertain.
+  const planLabel = plan.plan === 'uncertain'
+    ? `${plan.plan} (${plan.reason ?? 'no signal'})`
+    : (plan.plan ?? 'unknown');
+  return `**Stack**: ${stackParts}  ·  **Plan**: ${planLabel}  ·  **Period**: ${period}  ·  **Observability**: ${oplusLabel}`;
+}
+
+function observabilityLabel(signals, usage) {
+  if (signals.observabilityPlusUsable === true) {
+    return 'Observability Plus enabled — per-route metrics included';
+  }
+  if (signals.observabilityPlusUsable === false) {
+    if (usage) {
+      return 'Per-route metrics unavailable — analysis based on billing + scanner findings';
+    }
+    if (signals.usageError === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+      return 'Per-route metrics unavailable — audit paused before metric-backed route ranking';
+    }
+    return 'Per-route metrics unavailable — limited analysis based on scanner findings';
+  }
+  if (signals.observabilityPlus === true) {
+    return 'Observability Plus enabled — per-route metrics included';
+  }
+  if (signals.usageError === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return 'Not checked — audit paused at unsupported-framework preflight';
+  }
+  if (signals.usageError === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+    return 'Per-route metrics unavailable — audit paused before metric-backed route ranking';
+  }
+  if (usage) {
+    return 'Not enabled — analysis based on billing + scanner findings';
+  }
+  if (signals.observabilityPlus === false) {
+    return 'Not enabled — limited analysis only';
+  }
+  return 'Not checked — limited analysis only';
+}
+
+function renderCostHeader(signals) {
+  const scope = signals.usageScope;
+  if (scope === 'project') {
+    return ['## Cost breakdown (this project)'];
+  }
+  if (scope === 'team' && signals.usage) {
+    return [
+      '## Cost breakdown (team-wide — `vercel usage` has no per-project filter)',
+      '',
+      '_The Vercel CLI\'s `vercel usage` reports team-wide billing without a project filter (verified May 2026). This breakdown is the whole team\'s bill for the window. Per-route metrics in the rest of this report are project-scoped via `vercel metrics`._',
+    ];
+  }
+  return ['## Cost breakdown'];
+}
+
+function renderCostBreakdown(usage, signals) {
+  const lines = [];
+  const services = Array.isArray(usage?.services) ? usage.services : null;
+  if (services && services.length > 0) {
+    const chargedRows = services.filter((s) => {
+      const cost = serviceCost(s);
+      return cost === null || costRoundsToCents(cost) > 0;
+    });
+    if (chargedRows.length > 0) {
+      return renderServiceCostRows(chargedRows, {
+        costLabel: 'Billed cost',
+        costOf: serviceCost,
+        omittedZeroRows: services.length - chargedRows.length,
+        total: usage.totals?.billedCost,
+        totalLabel: 'Total billed',
+        totalSuffix: ' _(precise observed cost; future-savings framing is magnitude, never precise)_',
+      });
+    }
+
+    const effectiveRows = services.filter((s) => costRoundsToCents(serviceEffectiveCost(s)) > 0);
+    if (effectiveRows.length > 0) {
+      lines.push('_Net billed cost is $0.00 after included credits or allotments. Showing effective usage cost so active cost drivers are still visible._');
+      lines.push('');
+      return [
+        ...lines,
+        ...renderServiceCostRows(effectiveRows, {
+          costLabel: 'Effective cost',
+          costOf: serviceEffectiveCost,
+          omittedZeroRows: services.length - effectiveRows.length,
+          total: usage.totals?.effectiveCost,
+          totalLabel: 'Total effective cost',
+          totalSuffix: ' _(usage cost before included-credit or allotment offsets)_',
+        }),
+      ];
+    }
+
+    if (chargedRows.length === 0) {
+      const scope = signals.usageScope === 'team' ? 'team-wide ' : '';
+      lines.push(`_\`vercel usage\` returned a ${scope}billing payload, but every reported service cost was $0.00 for this window._`);
+      return lines;
+    }
+  }
+
+  // Fallback to o11y-derived ranking when usage payload missing.
+  const gbHr = signals.metrics?.fnGbHrByRoute?.rows ?? [];
+  const usageGap = missingUsageSentence(signals);
+  if (gbHr.length === 0) {
+    lines.push(`_${usageGap} Without per-route function GB-hour data, this report cannot rank cost drivers._`);
+    return lines;
+  }
+  const top = groupGbHoursByCanonicalRoute(gbHr)
+    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))
+    .slice(0, 10);
+  lines.push(`_${usageGap} Ranking by \`function_duration_gbhr\` instead. These do not translate to dollars directly, but they show which routes consume billable units._`);
+  lines.push('');
+  lines.push('| Route | GB-hr (sum, 14d) |');
+  lines.push('|---|---|');
+  for (const r of top) {
+    lines.push(`| ${escape(r.route ?? '(unnamed)')} | ${(r.value ?? 0).toFixed(4)} |`);
+  }
+  return lines;
+}
+
+function renderServiceCostRows(services, { costLabel, costOf, omittedZeroRows = 0, total = null, totalLabel, totalSuffix = '' }) {
+  const lines = [];
+  const rows = services.slice().sort((a, b) => (costOf(b) ?? 0) - (costOf(a) ?? 0));
+  // Drop Usage column when every cell is "(unspecified)" — happens when CLI emits pricingUnit=USD.
+  const usageCells = rows.map((s) => formatUsage(s));
+  const hasRealUsage = usageCells.some((c) => c !== '(unspecified)');
+  if (hasRealUsage) {
+    lines.push(`| Service | Usage | ${costLabel} |`);
+    lines.push('|---|---|---|');
+    for (let i = 0; i < rows.length; i++) {
+      const s = rows[i];
+      const costValue = costOf(s);
+      const cost = typeof costValue === 'number' ? `$${costValue.toFixed(2)}` : '(n/a)';
+      lines.push(`| ${escape(s.name ?? '(unnamed)')} | ${escape(usageCells[i])} | ${cost} |`);
+    }
+  } else {
+    lines.push(`| Service | ${costLabel} |`);
+    lines.push('|---|---|');
+    for (const s of rows) {
+      const costValue = costOf(s);
+      const cost = typeof costValue === 'number' ? `$${costValue.toFixed(2)}` : '(n/a)';
+      lines.push(`| ${escape(s.name ?? '(unnamed)')} | ${cost} |`);
+    }
+  }
+  if (omittedZeroRows > 0) {
+    lines.push('');
+    lines.push(`_${omittedZeroRows} zero-cost service ${omittedZeroRows === 1 ? 'row was' : 'rows were'} omitted._`);
+  }
+  if (typeof total === 'number') {
+    lines.push('');
+    lines.push(`**${totalLabel}: $${total.toFixed(2)}**${totalSuffix}`);
+  }
+  return lines;
+}
+
+function serviceCost(service) {
+  if (typeof service?.billedCost === 'number') return service.billedCost;
+  if (typeof service?.cost === 'number') return service.cost;
+  return null;
+}
+
+function serviceEffectiveCost(service) {
+  if (typeof service?.effectiveCost === 'number') return service.effectiveCost;
+  if (typeof service?.pricingQuantity === 'number' && service?.pricingUnit === 'USD') return service.pricingQuantity;
+  return 0;
+}
+
+function costRoundsToCents(cost) {
+  if (typeof cost !== 'number' || !Number.isFinite(cost)) return 0;
+  return Math.round(cost * 100) / 100;
+}
+
+function renderRecTable(recs, signals = {}) {
+  if (recs.length === 0) return ['_(none)_'];
+  const lines = [];
+  lines.push('| # | Bucket | What | Impact | Effort | Citations |');
+  lines.push('|---|---|---|---|---|---|');
+  recs.forEach((r, i) => {
+    const cites = asArray(r.citations).slice(0, 2).join('<br>');
+    lines.push(`| ${i + 1} | ${r.bucket ?? '?'} | ${escape(formatRecommendationText(r.what ?? ''))} | ${escape(formatRecommendationText(impactString(r, signals)))} | ${r.effort ?? '?'} | ${cites} |`);
+  });
+  return lines;
+}
+
+function renderRecDetail(rec, index, { compact = false, signals = {} } = {}) {
+  const lines = [];
+  lines.push(`### ${index}. ${formatRecommendationText(rec.what ?? '(no `what`)')}`);
+  lines.push('');
+  const meta = [
+    rec.bucket ? `**${rec.bucket}**` : null,
+    rec.effort ? `effort: ${rec.effort}` : null,
+    rec.impactTier ? `impact tier: ${rec.impactTier}` : null,
+    rec.candidateRef ? `candidate: ${displayCandidate(rec)}` : null,
+    rec.corroborationCount > 1 ? `corroborated: ${rec.corroborationCount}` : null,
+  ].filter(Boolean);
+  if (meta.length > 0) lines.push(`_${meta.join(' · ')}_`);
+  lines.push('');
+  const appliesAlsoTo = asArray(rec.appliesAlsoTo);
+  if (appliesAlsoTo.length > 0) {
+    const refs = appliesAlsoTo
+      .map((a) => a?.candidateRef)
+      .filter(Boolean)
+      .slice(0, 4);
+    if (refs.length > 0) {
+      const suffix = appliesAlsoTo.length > refs.length ? `, +${appliesAlsoTo.length - refs.length} more` : '';
+      lines.push(`_Also applies to: ${refs.map(displayCandidateRef).join(', ')}${suffix}._`);
+      lines.push('');
+    }
+  }
+  if (rec.why) {
+    lines.push('**Why**');
+    lines.push('');
+    lines.push(formatRecommendationText(rec.why));
+    lines.push('');
+  }
+  lines.push('**Impact**');
+  lines.push('');
+  lines.push(formatRecommendationText(impactString(rec, signals)));
+  lines.push('');
+  if (!compact && rec.fix) {
+    lines.push('**Fix**');
+    lines.push('');
+    lines.push(rec.fix);
+    lines.push('');
+  }
+  if (!compact && rec.currentBehavior) {
+    lines.push('**Before**');
+    lines.push('');
+    lines.push(rec.currentBehavior);
+    lines.push('');
+  }
+  if (!compact && rec.desiredBehavior) {
+    lines.push('**After**');
+    lines.push('');
+    lines.push(rec.desiredBehavior);
+    lines.push('');
+  }
+  if (rec.verify) {
+    lines.push('**Verify**');
+    lines.push('');
+    lines.push(formatRecommendationText(rec.verify));
+    lines.push('');
+  }
+  const cites = asArray(rec.citations);
+  if (cites.length > 0) {
+    lines.push('**Citations**');
+    lines.push('');
+    for (const c of cites) lines.push(`- \`${c}\``);
+    lines.push('');
+  }
+  lines.push('');
+  return lines;
+}
+
+function renderGatedTable(gated) {
+  if (!Array.isArray(gated) || gated.length === 0) {
+    return ['_(no candidates were held back)_'];
+  }
+  const groups = groupGatedCandidates(gated);
+  const lines = [];
+  lines.push('| Candidate type | Why not investigated | Targets | Count |');
+  lines.push('|---|---|---|---:|');
+  for (const group of groups) {
+    lines.push(`| ${escape(group.kind)} | ${escape(group.reason)} | ${formatGatedTargets(group.targets, group.count)} | ${group.count} |`);
+  }
+  return lines;
+}
+
+function formatGatedTargets(targets, count) {
+  const unique = [...new Set(targets.map((t) => String(t)))];
+  const shown = unique.slice(0, GATED_TARGET_PREVIEW).map((target) => escape(target));
+  const hidden = Math.max(0, count - shown.length);
+  if (hidden > 0) shown.push(`+${hidden} more`);
+  return shown.join('<br>');
+}
+
+function groupGatedCandidates(gated) {
+  const byKey = new Map();
+  for (const g of gated) {
+    const kind = formatKind(g.kind ?? '?');
+    const reason = publicGatedReason(g.gatedReason ?? g.disqualifyReason ?? '(no reason recorded)');
+    const target = formatRoute(g);
+    const key = `${kind}\u0000${reason}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      existing.count += 1;
+      existing.targets.push(String(target));
+    } else {
+      byKey.set(key, { kind: String(kind), reason: String(reason), targets: [String(target)], count: 1 });
+    }
+  }
+  return Array.from(byKey.values());
+}
+
+function publicNoRecommendationReason(reason) {
+  return formatEvidenceText(String(reason))
+    .replace(/\bDropped at render:\s*/gi, '')
+    .replace(/\bverifier flagged for regen, but no regen happened\b/gi, 'needs stronger evidence before it is safe to apply')
+    .replace(/\bRe-run with a refreshed brief\.?/gi, 'Re-run the investigation after refreshing the evidence.')
+    .replace(/\bregen\b/gi, 're-check')
+    .replace(/\bverifier\b/gi, 'verification')
+    .replace(/\brec\b/gi, 'recommendation')
+    .replace(/\bsub[- ]agent\b/gi, 'investigation')
+    .replace(/\babstentions?\b/gi, 'no-change findings')
+    .replace(/\babstaining\b/gi, 'not recommending a change')
+    .replace(/\babstain(?:ed)?\b/gi, 'found no supported change')
+    .replace(/\bquality\s*\+\s*verification\b/gi, 'verification')
+    .replace(/\bquality\b/gi, 'review')
+    .replace(/\bsanitizers?\b/gi, 'checks');
+}
+
+function splitInvestigationOutcomes(abstentions) {
+  const rows = Array.isArray(abstentions) ? abstentions : [];
+  return {
+    needsEvidenceRows: rows.filter((a) => a?.needsEvidence === true),
+    noChangeRows: rows.filter((a) => a?.needsEvidence !== true),
+  };
+}
+
+function publicGatedReason(reason) {
+  return formatPublicText(String(reason))
+    .replace(/\bhardGated:\s*/gi, '')
+    .replace(/skippedByBudget\s*\(max-candidates=([^);]+)(?:;[^)]*)?\)/i, 'left for a larger run (max candidates: $1)')
+    .replace(/skippedByBudget\b/gi, 'left for a larger run')
+    .replace(/\s*;\s*raise with --max-candidates N or =all/gi, '')
+    .replace(/=all/g, 'all')
+    .replace(/\bcoveredBy\b/gi, 'covered by a higher-priority candidate')
+    .replace(/\bdisqualified\b/gi, 'not eligible');
+}
+
+function formatEvidenceText(value) {
+  const expanded = formatPublicText(value)
+    .replace(/\bdeepDive\b/gi, 'follow-up metric')
+    .replace(/\bdeep-dive\b/gi, 'follow-up metric')
+    .replace(/\blatency p95\b/gi, '95th percentile latency')
+    .replace(/\bttfb p95\b/gi, '95th percentile TTFB')
+    .replace(/\bcpu p95\b/gi, '95th percentile CPU time')
+    .replace(/\bp95\b/gi, '95th percentile')
+    .replace(/\bgate signal\b/gi, 'broad metric signal')
+    .replace(/\bo11ySignal\b/gi, 'observed signal')
+    .replace(/\bperDeployment\b/gi, 'per-deployment')
+    .replace(/\bstartTypeSplit\b/gi, 'start-type breakdown')
+    .replace(/\bstatusDistribution\b/gi, 'status distribution')
+    .replace(/\bcacheBreakdown\b/gi, 'cache breakdown')
+    .replace(/\bfunctionRoutes\b/gi, 'function routes')
+    .replace(/\bfnGbHrByRoute\b/gi, 'function duration by route');
+  return formatPublicText(expanded);
+}
+
+function formatRecommendationText(value) {
+  return formatEvidenceText(value)
+    .replace(/\bthe gate fires\b/gi, 'this audit flags the signal')
+    .replace(/\bships immediately\b/gi, 'can ship sooner');
+}
+
+function displayCandidate(value) {
+  return formatCandidateLabel(candidateForDisplay(value));
+}
+
+function candidateForDisplay(value) {
+  const parsed = parseCandidateRef(value?.candidateRef);
+  return parsed
+    ? displayCandidateObject(value, parsed)
+    : value;
+}
+
+function displayCandidateRef(ref) {
+  const parsed = parseCandidateRef(ref);
+  if (!parsed) return String(ref ?? '(unspecified)');
+  return formatCandidateLabel(displayCandidateObject({}, parsed));
+}
+
+function parseCandidateRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const [kind, ...rest] = ref.split(':');
+  const target = rest.join(':');
+  if (!kind || !target) return null;
+  return { kind, target };
+}
+
+function displayCandidateObject(base, parsed) {
+  if (parsed.target.startsWith('<account>#')) {
+    return { ...base, kind: parsed.kind, files: [parsed.target.slice('<account>#'.length)] };
+  }
+  if (parsed.target === '<account>') {
+    return { ...base, kind: parsed.kind };
+  }
+  return { ...base, kind: parsed.kind, route: parsed.target };
+}
+
+function groupGbHoursByCanonicalRoute(rows) {
+  const byRoute = new Map();
+  for (const row of rows) {
+    const route = row?.route ? canonicalizeRoute(row.route) : '(unnamed)';
+    byRoute.set(route, (byRoute.get(route) ?? 0) + (row?.value ?? 0));
+  }
+  return [...byRoute.entries()].map(([route, value]) => ({ route, value }));
+}
+
+function renderStrengths(signals) {
+  const lines = [];
+
+  // Stops agent from emitting "verify Fluid is on" recs. Source: defaultResourceConfig from project API.
+  const projectFacts = deriveProjectFacts(signals);
+  for (const f of projectFacts) {
+    if (String(f.id ?? '').startsWith('memory_')) continue;
+    lines.push(`- ${f.strength}`);
+  }
+
+  const cache = signals.metrics?.fdtByCache?.rows ?? [];
+  const hit = cache.find((r) => r.cache_result === 'HIT' || r.cache_result === 'STALE');
+  const miss = cache.find((r) => r.cache_result === 'MISS' || r.cache_result === 'BYPASS');
+  if (hit && miss && (hit.value ?? 0) > (miss.value ?? 0)) {
+    lines.push(`- Cache hit-rate is healthy at the bandwidth tier — HIT/STALE bandwidth (${formatBytes(hit.value)}) exceeds MISS/BYPASS (${formatBytes(miss.value)}).`);
+  }
+  const cold = signals.metrics?.fnStartTypeByRoute?.rows ?? [];
+  const totalInv = cold.reduce((s, r) => s + (r.total ?? 0), 0);
+  const totalCold = cold.reduce((s, r) => s + (r.coldCount ?? 0), 0);
+  if (totalInv > 1000) {
+    const coldPct = totalCold / totalInv;
+    if (coldPct < 0.02) lines.push(`- Cold-start rate is very low (${(coldPct * 100).toFixed(2)}%) — Fluid Compute or warm-instance reuse is doing its job.`);
+  }
+  const errors = signals.metrics?.requestsByRouteStatus?.rows ?? [];
+  const total5xx = errors.filter((r) => /^5/.test(r.http_status ?? '')).reduce((s, r) => s + (r.value ?? 0), 0);
+  const totalReq = errors.reduce((s, r) => s + (r.value ?? 0), 0);
+  if (totalReq > 1000) {
+    const rate = total5xx / totalReq;
+    if (rate < 0.001) lines.push(`- 5xx rate is very low (${(rate * 100).toFixed(3)}%) on ${formatNum(totalReq)} requests.`);
+  }
+  if (lines.length === 0) lines.push('_(no headline strengths to call out — see the gated table for signals we considered)_');
+  return lines;
+}
+
+function renderConfigurationNotes(signals) {
+  const projectFacts = deriveProjectFacts(signals);
+  return projectFacts
+    .filter((f) => String(f.id ?? '').startsWith('memory_'))
+    .map((f) => `- ${f.strength}`);
+}
+
+function renderDataGaps(signals) {
+  const lines = [];
+  const observabilityGap = observabilityDataGap(signals);
+  if (observabilityGap) lines.push(observabilityGap);
+  if (!signals.usage) lines.push(`- ${missingUsageSentence(signals)}`);
+  const cwvMetric = metricState(signals, 'cwvCount');
+  if (cwvMetric.failed) {
+    lines.push(`- Speed Insights metrics were not usable (\`${cwvMetric.code}\`), so LCP/INP/CLS analysis was skipped.`);
+  } else if (cwvMetric.collected) {
+    const cwv = cwvMetric.rows?.[0]?.value ?? 0;
+    if (cwv === 0) lines.push('- No Speed Insights measurements — Core Web Vitals analysis dormant. Wire up Speed Insights to enable LCP/INP/CLS recommendations.');
+  }
+  const isrMetric = metricState(signals, 'isrReadsByRoute');
+  if (isrMetric.collected) {
+    const isrR = isrMetric.rows ?? [];
+    if (isrR.length === 0) lines.push('- No ISR activity observed — either the project does not use ISR or no eligible routes had traffic in the window.');
+  }
+  const imageMetric = metricState(signals, 'imageCount');
+  if (imageMetric.collected) {
+    const images = imageMetric.rows?.[0]?.value ?? 0;
+    if (images === 0) lines.push('- No image transformations observed — either `next/image` is not used or no images served in the window.');
+  }
+  const middlewareMetric = metricState(signals, 'middlewareCount');
+  if (middlewareMetric.collected) {
+    const middleware = middlewareMetric.rows ?? [];
+    if (middleware.length === 0) lines.push('- No middleware invocations — either no `middleware.ts` is shipped or its matcher excludes all observed traffic.');
+  }
+  if (lines.length === 0) lines.push('_(no relevant gaps — every signal had data)_');
+  return lines;
+}
+
+function observabilityDataGap(signals = {}) {
+  if (signals.usageError === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return '- Observability Plus was not checked because the audit paused at the unsupported-framework preflight.';
+  }
+  if (signals.observabilityPlusUsable === false) {
+    const blocker = signals.observabilityPlusBlocker;
+    if (blocker === 'project_disabled') {
+      return '- Per-route metrics unavailable — Observability Plus is disabled for this project.';
+    }
+    if (blocker === 'forbidden' || blocker === 'project_not_found') {
+      return '- Per-route metrics unavailable — the authenticated Vercel scope cannot read this project.';
+    }
+    if (blocker === 'not_linked') {
+      return '- Per-route metrics unavailable — the app directory is not linked to the Vercel project.';
+    }
+    if (blocker === 'no_oplus_probe') {
+      return '- Per-route metrics unavailable — Observability Plus was not detected for this scope.';
+    }
+    if (blocker === 'payment_required') {
+      return '- Per-route metrics unavailable — Observability Plus metrics were not usable for this scope.';
+    }
+    if (blocker === 'daily_quota_exceeded') {
+      return '- Per-route metrics unavailable — the Observability Plus query quota is exhausted for today.';
+    }
+    if (blocker === 'no_traffic') {
+      return '- Per-route metrics sparse — no route-level traffic was returned in the metrics window.';
+    }
+    if (blocker === 'all_failed_other') {
+      return '- Per-route metrics unavailable — all Observability Plus metric queries failed.';
+    }
+    if (blocker) {
+      return `- Per-route metrics unavailable — Observability Plus metrics returned \`${blocker}\`.`;
+    }
+    return '- Per-route metrics unavailable — Observability Plus data was not usable for this run.';
+  }
+  if (signals.observabilityPlus === false) {
+    return '- Observability Plus not enabled — per-route latency / cache-hit / cold-start metrics unavailable.';
+  }
+  return null;
+}
+
+function missingUsageSentence(signals = {}) {
+  const code = signals.usageError;
+  if (code === 'NOT_COLLECTED_OBSERVABILITY_BLOCKED') {
+    return '`vercel usage` was not collected because the audit paused before billing collection on the Observability Plus blocker.';
+  }
+  if (code === 'NOT_COLLECTED_UNSUPPORTED_FRAMEWORK') {
+    return '`vercel usage` was not collected because the audit paused at the unsupported-framework preflight.';
+  }
+  if (code === 'USAGE_CONTEXT_MISMATCH') {
+    return '`vercel usage` returned data for a different team context, so the billing breakdown was not used.';
+  }
+  if (code === 'USAGE_UNAVAILABLE') {
+    return '`vercel usage` returned `USAGE_UNAVAILABLE`; no billing breakdown was available from the Vercel CLI.';
+  }
+  if (typeof code === 'string' && code.trim() !== '') {
+    return `\`vercel usage\` returned \`${code}\`; no billing breakdown was available from the Vercel CLI.`;
+  }
+  return '`vercel usage` did not return a billing payload.';
+}
+
+function metricState(signals, id) {
+  const metrics = signals.metrics ?? {};
+  if (!Object.prototype.hasOwnProperty.call(metrics, id)) {
+    return { collected: false, failed: false, rows: null, code: null };
+  }
+  const metric = metrics[id] ?? {};
+  const failed = metric.ok === false;
+  return {
+    collected: !failed,
+    failed,
+    rows: Array.isArray(metric.rows) ? metric.rows : [],
+    code: metric.code ?? 'UNKNOWN',
+  };
+}
+
+function sortRecs(recs) {
+  return recs.slice().sort((a, b) => priorityScore(b) - priorityScore(a));
+}
+
+function priorityScore(rec) {
+  return typeof rec.priority === 'number' ? rec.priority : tierScore(rec.impactTier);
+}
+function tierScore(t) { return ({ high: 100, medium: 50, low: 10 })[t] ?? 0; }
+
+function isPlatformScope(rec) {
+  const k = String(rec.candidateRef ?? '').split(':')[0];
+  return k.startsWith('platform_') || rec.scope === 'account';
+}
+
+function impactString(rec, signals = {}) {
+  const label = computeImpactLabel(rec, signals);
+  if (label) return label;
+  return '_(no impact framing recorded)_';
+}
+
+function signalFromRec(rec) {
+  return rec.findingRefs?.[0] ?? null;
+}
+
+function formatUsage(s) {
+  if (typeof s.usage === 'string') return s.usage;
+  if (typeof s.usage === 'number') return formatNum(s.usage) + (s.unit ? ` ${s.unit}` : '');
+  return '(unspecified)';
+}
+
+function formatNum(n) {
+  if (!Number.isFinite(n)) return String(n);
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(2) + 'K';
+  return String(n);
+}
+
+function formatBytes(b) {
+  if (!Number.isFinite(b)) return '(n/a)';
+  if (b >= 1e12) return (b / 1e12).toFixed(2) + ' TB';
+  if (b >= 1e9) return (b / 1e9).toFixed(2) + ' GB';
+  if (b >= 1e6) return (b / 1e6).toFixed(2) + ' MB';
+  if (b >= 1e3) return (b / 1e3).toFixed(2) + ' KB';
+  return Math.round(b) + ' B';
+}
+
+function escape(s) {
+  if (typeof s !== 'string') return String(s ?? '');
+  return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+function asArray(v) { return Array.isArray(v) ? v : []; }
+
+function enrichRecFromCandidates(rec, candidates) {
+  if (!rec || typeof rec !== 'object') return rec;
+  if (!Array.isArray(candidates) || candidates.length === 0) return rec;
+  const ref = rec.candidateRef ?? null;
+  // Match on raw OR canonical kind:route so pre-dedup-canonicalization refs still resolve.
+  let match = null;
+  if (ref) {
+    const [kind, route] = String(ref).split(':');
+    const canonical = route ? canonicalizeRoute(route) : null;
+    match = candidates.find((c) => {
+      if (!c || c.kind !== kind) return false;
+      const cRoute = c.route ?? c.hostname ?? '<account>';
+      return cRoute === route || cRoute === canonical || canonicalizeRoute(cRoute) === canonical;
+    });
+  }
+  const canonicalRef = ref ? canonicalRefOf(ref) : ref;
+  const merged = { ...rec, candidateRef: canonicalRef };
+  if (match) {
+    if (!merged.o11ySignal && match.o11ySignal) merged.o11ySignal = match.o11ySignal;
+    if (!merged.displayRoute && match.displayRoute) merged.displayRoute = match.displayRoute;
+    if (!merged.aliasRoutes && Array.isArray(match.aliasRoutes) && match.aliasRoutes.length > 0) {
+      merged.aliasRoutes = match.aliasRoutes;
+    }
+    if (!merged.mergedCount && typeof match.mergedCount === 'number') {
+      merged.mergedCount = match.mergedCount;
+    }
+  }
+  return merged;
+}
+
+function canonicalRefOf(ref) {
+  const [kind, ...rest] = String(ref).split(':');
+  const route = rest.join(':');
+  if (!route) return ref;
+  return `${kind}:${canonicalizeRoute(route)}`;
+}