sentinelayer-cli 0.1.0

package/src/audit/agents/architecture.js

@@ -0,0 +1,180 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function toPosixPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function summarizeSeverity(findings = []) {
+  const summary = { P0: 0, P1: 0, P2: 0, P3: 0 };
+  for (const finding of findings) {
+    const severity = normalizeString(finding.severity).toUpperCase();
+    if (Object.prototype.hasOwnProperty.call(summary, severity)) {
+      summary[severity] += 1;
+    }
+  }
+  summary.blocking = summary.P0 > 0 || summary.P1 > 0;
+  return summary;
+}
+
+function buildHotspots(ingest = {}) {
+  const indexed = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
+  return indexed
+    .filter((file) => Number(file.loc || 0) >= 300)
+    .sort((left, right) => Number(right.loc || 0) - Number(left.loc || 0))
+    .slice(0, 20)
+    .map((file) => ({
+      path: toPosixPath(file.path),
+      language: file.language,
+      loc: Number(file.loc || 0),
+      sizeBytes: Number(file.sizeBytes || 0),
+      risk: Number(file.loc || 0) >= 700 ? "high" : "medium",
+    }));
+}
+
+function deriveArchitectureFindings({ findings = [], hotspots = [] } = {}) {
+  const derived = [];
+  const base = Array.isArray(findings) ? findings : [];
+
+  for (const finding of base) {
+    const message = normalizeString(finding.message).toLowerCase();
+    if (/n\+1|loop|query|component|cleanup|stale|coupling|dependency/.test(message)) {
+      derived.push(finding);
+    }
+  }
+
+  for (const hotspot of hotspots) {
+    const existing = derived.some((finding) => toPosixPath(finding.file) === hotspot.path);
+    if (existing) {
+      continue;
+    }
+    derived.push({
+      severity: hotspot.risk === "high" ? "P1" : "P2",
+      file: hotspot.path,
+      line: 1,
+      message: `Large architectural hotspot detected (${hotspot.loc} LOC).`,
+      excerpt: `${hotspot.language} module at ${hotspot.path}`,
+      ruleId: "SL-ARCH-001",
+      suggestedFix: "Split this module into bounded components with explicit interfaces.",
+      layer: "architecture",
+    });
+  }
+
+  return derived.slice(0, 120);
+}
+
+function estimateCouplingRisk(ingest = {}) {
+  const files = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
+  const byDirectory = new Map();
+  for (const file of files) {
+    const normalizedPath = toPosixPath(file.path);
+    const dir = normalizedPath.includes("/") ? normalizedPath.slice(0, normalizedPath.lastIndexOf("/")) : ".";
+    const existing = byDirectory.get(dir) || 0;
+    byDirectory.set(dir, existing + 1);
+  }
+  const denseDirs = [...byDirectory.entries()].filter((entry) => entry[1] >= 20);
+  return {
+    denseDirectoryCount: denseDirs.length,
+    denseDirectories: denseDirs
+      .sort((left, right) => right[1] - left[1])
+      .slice(0, 12)
+      .map((entry) => ({ directory: entry[0], fileCount: entry[1] })),
+  };
+}
+
+function estimateArchitectureScore(hotspots = [], summary = {}) {
+  const penalty =
+    hotspots.length * 3 +
+    Number(summary.P1 || 0) * 6 +
+    Number(summary.P2 || 0) * 3 +
+    Number(summary.P3 || 0);
+  return Math.max(0, 100 - Math.min(100, penalty));
+}
+
+function buildRecommendations({ hotspots = [], summary = {}, couplingRisk } = {}) {
+  const recommendations = [];
+  if (hotspots.length > 0) {
+    recommendations.push(
+      "Split high-LOC modules into bounded contexts and enforce explicit interface contracts."
+    );
+  }
+  if (Number(summary.P1 || 0) > 0) {
+    recommendations.push("Resolve all P1 architecture findings before onboarding additional feature work.");
+  }
+  if (couplingRisk.denseDirectoryCount > 0) {
+    recommendations.push(
+      "Introduce package-level ownership boundaries for dense directories to reduce cross-module coupling."
+    );
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Architecture signals are stable; continue tracking drift with periodic audits.");
+  }
+  return recommendations;
+}
+
+export function runArchitectureSpecialist({
+  findings = [],
+  ingest = {},
+} = {}) {
+  const hotspots = buildHotspots(ingest);
+  const architectureFindings = deriveArchitectureFindings({
+    findings,
+    hotspots,
+  });
+  const summary = summarizeSeverity(architectureFindings);
+  const couplingRisk = estimateCouplingRisk(ingest);
+  const architectureScore = estimateArchitectureScore(hotspots, summary);
+  const confidence = architectureFindings.length > 0 ? Math.max(0.72, 1 - architectureFindings.length * 0.002) : 0.9;
+
+  return {
+    schemaVersion: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      ...summary,
+      findingCount: architectureFindings.length,
+      architectureScore,
+    },
+    confidence,
+    hotspots,
+    couplingRisk,
+    recommendations: buildRecommendations({
+      hotspots,
+      summary,
+      couplingRisk,
+    }),
+    findings: architectureFindings,
+  };
+}
+
+export function renderArchitectureSpecialistMarkdown(report = {}) {
+  const hotspots = (report.hotspots || [])
+    .map((item) => `- ${item.path} (${item.loc} LOC, risk=${item.risk})`)
+    .join("\n");
+  const couplings = (report.couplingRisk?.denseDirectories || [])
+    .map((item) => `- ${item.directory}: ${item.fileCount} files`)
+    .join("\n");
+  const recommendations = (report.recommendations || []).map((item) => `- ${item}`).join("\n");
+
+  return `# ARCHITECTURE_AGENT_REPORT
+
+Generated: ${report.generatedAt}
+Architecture score: ${report.summary?.architectureScore ?? 0}/100
+Confidence: ${((report.confidence || 0) * 100).toFixed(0)}%
+
+Summary:
+- Findings: P0=${report.summary?.P0 ?? 0} P1=${report.summary?.P1 ?? 0} P2=${report.summary?.P2 ?? 0} P3=${report.summary?.P3 ?? 0}
+- Blocking: ${report.summary?.blocking ? "yes" : "no"}
+- Total findings: ${report.summary?.findingCount ?? 0}
+
+Hotspots:
+${hotspots || "- none"}
+
+Coupling density:
+${couplings || "- none"}
+
+Recommendations:
+${recommendations || "- none"}
+`;
+}
+

package/src/audit/agents/compliance.js

@@ -0,0 +1,179 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function toPosixPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function summarizeSeverity(findings = []) {
+  const summary = { P0: 0, P1: 0, P2: 0, P3: 0 };
+  for (const finding of findings) {
+    const severity = normalizeString(finding.severity).toUpperCase();
+    if (Object.prototype.hasOwnProperty.call(summary, severity)) {
+      summary[severity] += 1;
+    }
+  }
+  summary.blocking = summary.P0 > 0 || summary.P1 > 0;
+  return summary;
+}
+
+function classifyControl(finding = {}) {
+  const haystack = `${normalizeString(finding.message)} ${normalizeString(finding.ruleId)} ${normalizeString(
+    finding.file
+  )}`.toLowerCase();
+  if (/secret|token|credential|key|jwt/.test(haystack)) {
+    return { framework: "SOC2-CC6", control: "Secrets Management", severity: "P1" };
+  }
+  if (/auth|session|revoke|ttl|role|permission/.test(haystack)) {
+    return { framework: "SOC2-CC6", control: "Access Controls", severity: "P2" };
+  }
+  if (/telemetry|log|trace|audit/.test(haystack)) {
+    return { framework: "SOC2-CC7", control: "Auditability", severity: "P2" };
+  }
+  if (/data|pii|encryption|tls|privacy|retention/.test(haystack)) {
+    return { framework: "SOC2-CC8", control: "Data Protection", severity: "P1" };
+  }
+  if (/workflow|deploy|release|supply|dependency/.test(haystack)) {
+    return { framework: "SOC2-CC9", control: "Change Management", severity: "P2" };
+  }
+  return { framework: "SOC2-CC3", control: "Governance", severity: "P3" };
+}
+
+function buildComplianceFindings({ findings = [], ingest = {} } = {}) {
+  const derived = [];
+  const scoped = Array.isArray(findings) ? findings : [];
+  for (const finding of scoped) {
+    const control = classifyControl(finding);
+    if (control.severity === "P3" && normalizeString(finding.severity).toUpperCase() === "P3") {
+      continue;
+    }
+    derived.push({
+      ...finding,
+      severity: normalizeString(finding.severity) ? finding.severity : control.severity,
+      complianceFramework: control.framework,
+      complianceControl: control.control,
+      layer: "compliance",
+    });
+  }
+
+  const riskSurfaces = Array.isArray(ingest.riskSurfaces) ? ingest.riskSurfaces : [];
+  for (const surface of riskSurfaces.slice(0, 20)) {
+    const normalizedSurface = normalizeString(surface.surface);
+    if (!normalizedSurface) {
+      continue;
+    }
+    const representativePath = toPosixPath(surface.filePath || surface.path || ".");
+    const exists = derived.some((finding) => toPosixPath(finding.file) === representativePath);
+    if (exists) {
+      continue;
+    }
+    const control =
+      normalizedSurface === "secrets"
+        ? { framework: "SOC2-CC6", control: "Secrets Management", severity: "P1" }
+        : { framework: "SOC2-CC7", control: "Auditability", severity: "P2" };
+    derived.push({
+      severity: control.severity,
+      file: representativePath,
+      line: 1,
+      message: `Compliance risk surface detected for ${normalizedSurface}.`,
+      excerpt: `${normalizedSurface} surface observed in ingest`,
+      ruleId: "SL-COMP-001",
+      suggestedFix: "Document control ownership and enforce deterministic remediation evidence.",
+      complianceFramework: control.framework,
+      complianceControl: control.control,
+      layer: "compliance",
+    });
+  }
+
+  return derived.slice(0, 120);
+}
+
+function summarizeControls(findings = []) {
+  const controlMap = new Map();
+  for (const finding of findings) {
+    const framework = normalizeString(finding.complianceFramework || "SOC2-CC3");
+    const control = normalizeString(finding.complianceControl || "Governance");
+    const key = `${framework}::${control}`;
+    const existing = controlMap.get(key) || { framework, control, count: 0 };
+    existing.count += 1;
+    controlMap.set(key, existing);
+  }
+  return [...controlMap.values()].sort((left, right) => right.count - left.count);
+}
+
+function estimateComplianceScore(summary = {}, controlSummary = []) {
+  const penalty =
+    Number(summary.P1 || 0) * 8 +
+    Number(summary.P2 || 0) * 4 +
+    Number(summary.P3 || 0) +
+    controlSummary.length;
+  return Math.max(0, 100 - Math.min(100, penalty));
+}
+
+function buildRecommendations(summary = {}, controlSummary = []) {
+  const recommendations = [];
+  if (Number(summary.P1 || 0) > 0) {
+    recommendations.push("Close P1 compliance findings before release and attach evidence in run artifacts.");
+  }
+  if (controlSummary.some((item) => item.framework === "SOC2-CC6")) {
+    recommendations.push("Strengthen credential/access controls and verify rotation/revocation procedures.");
+  }
+  if (controlSummary.some((item) => item.framework === "SOC2-CC7")) {
+    recommendations.push("Improve audit telemetry coverage for remediation and production change traces.");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Compliance posture is stable; keep continuous evidence capture in each audit run.");
+  }
+  return recommendations;
+}
+
+export function runComplianceSpecialist({ findings = [], ingest = {} } = {}) {
+  const complianceFindings = buildComplianceFindings({
+    findings,
+    ingest,
+  });
+  const summary = summarizeSeverity(complianceFindings);
+  const controlSummary = summarizeControls(complianceFindings);
+  const complianceScore = estimateComplianceScore(summary, controlSummary);
+  const confidence = complianceFindings.length > 0 ? Math.max(0.76, 1 - complianceFindings.length * 0.002) : 0.9;
+
+  return {
+    schemaVersion: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      ...summary,
+      findingCount: complianceFindings.length,
+      complianceScore,
+    },
+    confidence,
+    controlSummary,
+    recommendations: buildRecommendations(summary, controlSummary),
+    findings: complianceFindings,
+  };
+}
+
+export function renderComplianceSpecialistMarkdown(report = {}) {
+  const controls = (report.controlSummary || [])
+    .map((item) => `- ${item.framework} :: ${item.control} (${item.count} findings)`)
+    .join("\n");
+  const recommendations = (report.recommendations || []).map((item) => `- ${item}`).join("\n");
+
+  return `# COMPLIANCE_AGENT_REPORT
+
+Generated: ${report.generatedAt}
+Compliance score: ${report.summary?.complianceScore ?? 0}/100
+Confidence: ${((report.confidence || 0) * 100).toFixed(0)}%
+
+Summary:
+- Findings: P0=${report.summary?.P0 ?? 0} P1=${report.summary?.P1 ?? 0} P2=${report.summary?.P2 ?? 0} P3=${report.summary?.P3 ?? 0}
+- Blocking: ${report.summary?.blocking ? "yes" : "no"}
+- Total findings: ${report.summary?.findingCount ?? 0}
+
+Control mapping:
+${controls || "- none"}
+
+Recommendations:
+${recommendations || "- none"}
+`;
+}

package/src/audit/agents/documentation.js

@@ -0,0 +1,165 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function toPosixPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function summarizeSeverity(findings = []) {
+  const summary = { P0: 0, P1: 0, P2: 0, P3: 0 };
+  for (const finding of findings) {
+    const severity = normalizeString(finding.severity).toUpperCase();
+    if (Object.prototype.hasOwnProperty.call(summary, severity)) {
+      summary[severity] += 1;
+    }
+  }
+  summary.blocking = summary.P0 > 0 || summary.P1 > 0;
+  return summary;
+}
+
+function buildDocumentationInventory(ingest = {}) {
+  const indexed = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
+  const normalized = indexed.map((file) => ({
+    path: toPosixPath(file.path),
+    loc: Number(file.loc || 0),
+    language: file.language,
+  }));
+  const docFiles = normalized.filter((file) => /(^|\/)(docs?|guides?|adr|readme)/i.test(file.path));
+  const codeFiles = normalized.filter(
+    (file) => file.loc > 0 && !/(^|\/)(docs?|guides?|adr|readme)/i.test(file.path)
+  );
+  const docDensity = codeFiles.length > 0 ? docFiles.length / codeFiles.length : 0;
+  const undocumentedHotspots = codeFiles
+    .filter((file) => file.loc >= 320)
+    .filter((file) => {
+      const dir = file.path.includes("/") ? file.path.slice(0, file.path.lastIndexOf("/")) : ".";
+      return !docFiles.some((doc) => doc.path.startsWith(dir));
+    })
+    .sort((left, right) => right.loc - left.loc)
+    .slice(0, 20)
+    .map((file) => ({
+      path: file.path,
+      loc: file.loc,
+      language: file.language,
+      severity: file.loc >= 800 ? "P1" : "P2",
+    }));
+
+  return {
+    docFileCount: docFiles.length,
+    codeFileCount: codeFiles.length,
+    docDensity,
+    undocumentedHotspots,
+  };
+}
+
+function buildDocumentationFindings({ findings = [], inventory = {} } = {}) {
+  const scoped = Array.isArray(findings) ? findings : [];
+  const derived = [];
+  for (const finding of scoped) {
+    const haystack = `${normalizeString(finding.message)} ${normalizeString(finding.ruleId)} ${normalizeString(
+      finding.file
+    )}`.toLowerCase();
+    if (/doc|documentation|spec|guide|readme|runbook|playbook|adr/.test(haystack)) {
+      derived.push(finding);
+    }
+  }
+
+  for (const hotspot of inventory.undocumentedHotspots || []) {
+    const exists = derived.some((finding) => toPosixPath(finding.file) === hotspot.path);
+    if (exists) {
+      continue;
+    }
+    derived.push({
+      severity: hotspot.severity,
+      file: hotspot.path,
+      line: 1,
+      message: `Large module lacks nearby documentation coverage (${hotspot.loc} LOC).`,
+      excerpt: `${hotspot.language || "code"} module at ${hotspot.path}`,
+      ruleId: "SL-DOC-001",
+      suggestedFix: "Add a runbook/spec section describing responsibilities, dependencies, and failure modes.",
+      layer: "documentation",
+    });
+  }
+
+  return derived.slice(0, 120);
+}
+
+function estimateDocumentationScore(inventory = {}, summary = {}) {
+  const densityScore = Math.min(70, Math.round(Number(inventory.docDensity || 0) * 100));
+  const penalty = Number(summary.P1 || 0) * 8 + Number(summary.P2 || 0) * 4 + Number(summary.P3 || 0);
+  return Math.max(0, Math.min(100, densityScore + 30 - penalty));
+}
+
+function buildRecommendations(inventory = {}, summary = {}) {
+  const recommendations = [];
+  if (Number(summary.P1 || 0) > 0) {
+    recommendations.push("Close P1 documentation gaps for critical modules before release.");
+  }
+  if (inventory.undocumentedHotspots?.length > 0) {
+    recommendations.push("Create runbooks/spec addenda for high-LOC modules lacking nearby docs.");
+  }
+  if (Number(inventory.docDensity || 0) < 0.2) {
+    recommendations.push("Increase docs-to-code density with ADRs and operator-oriented troubleshooting guides.");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Documentation posture is stable; maintain drift checks between code and specs.");
+  }
+  return recommendations;
+}
+
+export function runDocumentationSpecialist({ findings = [], ingest = {} } = {}) {
+  const inventory = buildDocumentationInventory(ingest);
+  const documentationFindings = buildDocumentationFindings({
+    findings,
+    inventory,
+  });
+  const summary = summarizeSeverity(documentationFindings);
+  const documentationScore = estimateDocumentationScore(inventory, summary);
+  const confidence =
+    documentationFindings.length > 0 ? Math.max(0.72, 1 - documentationFindings.length * 0.0025) : 0.9;
+
+  return {
+    schemaVersion: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      ...summary,
+      findingCount: documentationFindings.length,
+      documentationScore,
+    },
+    confidence,
+    inventory,
+    recommendations: buildRecommendations(inventory, summary),
+    findings: documentationFindings,
+  };
+}
+
+export function renderDocumentationSpecialistMarkdown(report = {}) {
+  const hotspots = (report.inventory?.undocumentedHotspots || [])
+    .map((item) => `- ${item.path} (${item.loc} LOC, severity=${item.severity})`)
+    .join("\n");
+  const recommendations = (report.recommendations || []).map((item) => `- ${item}`).join("\n");
+
+  return `# DOCUMENTATION_AGENT_REPORT
+
+Generated: ${report.generatedAt}
+Documentation score: ${report.summary?.documentationScore ?? 0}/100
+Confidence: ${((report.confidence || 0) * 100).toFixed(0)}%
+
+Summary:
+- Findings: P0=${report.summary?.P0 ?? 0} P1=${report.summary?.P1 ?? 0} P2=${report.summary?.P2 ?? 0} P3=${report.summary?.P3 ?? 0}
+- Blocking: ${report.summary?.blocking ? "yes" : "no"}
+- Total findings: ${report.summary?.findingCount ?? 0}
+
+Documentation inventory:
+- doc files: ${report.inventory?.docFileCount ?? 0}
+- code files: ${report.inventory?.codeFileCount ?? 0}
+- doc density: ${((report.inventory?.docDensity || 0) * 100).toFixed(1)}%
+
+Undocumented hotspots:
+${hotspots || "- none"}
+
+Recommendations:
+${recommendations || "- none"}
+`;
+}

package/src/audit/agents/performance.js

@@ -0,0 +1,145 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function toPosixPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function summarizeSeverity(findings = []) {
+  const summary = { P0: 0, P1: 0, P2: 0, P3: 0 };
+  for (const finding of findings) {
+    const severity = normalizeString(finding.severity).toUpperCase();
+    if (Object.prototype.hasOwnProperty.call(summary, severity)) {
+      summary[severity] += 1;
+    }
+  }
+  summary.blocking = summary.P0 > 0 || summary.P1 > 0;
+  return summary;
+}
+
+function buildRuntimeHotspots(ingest = {}) {
+  const indexed = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
+  return indexed
+    .filter((file) => Number(file.loc || 0) >= 280)
+    .sort((left, right) => Number(right.loc || 0) - Number(left.loc || 0))
+    .slice(0, 20)
+    .map((file) => ({
+      path: toPosixPath(file.path),
+      loc: Number(file.loc || 0),
+      language: file.language,
+      severity: Number(file.loc || 0) >= 900 ? "P1" : "P2",
+    }));
+}
+
+function buildPerformanceFindings({ findings = [], runtimeHotspots = [] } = {}) {
+  const scoped = Array.isArray(findings) ? findings : [];
+  const derived = [];
+  for (const finding of scoped) {
+    const haystack = `${normalizeString(finding.message)} ${normalizeString(finding.ruleId)} ${normalizeString(
+      finding.file
+    )}`.toLowerCase();
+    if (/latency|loop|n\+1|query|performance|cache|hot path|throughput|timeout/.test(haystack)) {
+      derived.push(finding);
+    }
+  }
+
+  for (const hotspot of runtimeHotspots) {
+    const exists = derived.some((finding) => toPosixPath(finding.file) === hotspot.path);
+    if (exists) {
+      continue;
+    }
+    derived.push({
+      severity: hotspot.severity,
+      file: hotspot.path,
+      line: 1,
+      message: `Runtime hotspot candidate detected (${hotspot.loc} LOC).`,
+      excerpt: `${hotspot.language || "code"} module at ${hotspot.path}`,
+      ruleId: "SL-PERF-001",
+      suggestedFix: "Profile this path and split heavy loops/queries into bounded units with caching.",
+      layer: "performance",
+    });
+  }
+
+  return derived.slice(0, 120);
+}
+
+function estimatePerformanceScore(runtimeHotspots = [], summary = {}) {
+  const penalty =
+    runtimeHotspots.length * 2 +
+    Number(summary.P1 || 0) * 8 +
+    Number(summary.P2 || 0) * 4 +
+    Number(summary.P3 || 0);
+  return Math.max(0, 100 - Math.min(100, penalty));
+}
+
+function buildRecommendations({ runtimeHotspots = [], summary = {} } = {}) {
+  const recommendations = [];
+  if (Number(summary.P1 || 0) > 0) {
+    recommendations.push("Resolve P1 performance findings and add regression benchmarks before merge.");
+  }
+  if (runtimeHotspots.length > 0) {
+    recommendations.push("Profile top hotspot modules and document expected p95/p99 behavior for each.");
+  }
+  if (Number(summary.P2 || 0) >= 4) {
+    recommendations.push("Introduce staged load checks for high-change paths to prevent latency drift.");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Performance posture is stable; continue periodic profiling on critical paths.");
+  }
+  return recommendations;
+}
+
+export function runPerformanceSpecialist({ findings = [], ingest = {} } = {}) {
+  const runtimeHotspots = buildRuntimeHotspots(ingest);
+  const performanceFindings = buildPerformanceFindings({
+    findings,
+    runtimeHotspots,
+  });
+  const summary = summarizeSeverity(performanceFindings);
+  const performanceScore = estimatePerformanceScore(runtimeHotspots, summary);
+  const confidence =
+    performanceFindings.length > 0 ? Math.max(0.74, 1 - performanceFindings.length * 0.0025) : 0.9;
+
+  return {
+    schemaVersion: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      ...summary,
+      findingCount: performanceFindings.length,
+      performanceScore,
+    },
+    confidence,
+    runtimeHotspots,
+    recommendations: buildRecommendations({
+      runtimeHotspots,
+      summary,
+    }),
+    findings: performanceFindings,
+  };
+}
+
+export function renderPerformanceSpecialistMarkdown(report = {}) {
+  const hotspots = (report.runtimeHotspots || [])
+    .map((item) => `- ${item.path} (${item.loc} LOC, severity=${item.severity})`)
+    .join("\n");
+  const recommendations = (report.recommendations || []).map((item) => `- ${item}`).join("\n");
+
+  return `# PERFORMANCE_AGENT_REPORT
+
+Generated: ${report.generatedAt}
+Performance score: ${report.summary?.performanceScore ?? 0}/100
+Confidence: ${((report.confidence || 0) * 100).toFixed(0)}%
+
+Summary:
+- Findings: P0=${report.summary?.P0 ?? 0} P1=${report.summary?.P1 ?? 0} P2=${report.summary?.P2 ?? 0} P3=${report.summary?.P3 ?? 0}
+- Blocking: ${report.summary?.blocking ? "yes" : "no"}
+- Total findings: ${report.summary?.findingCount ?? 0}
+
+Runtime hotspots:
+${hotspots || "- none"}
+
+Recommendations:
+${recommendations || "- none"}
+`;
+}