avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/dogfood-evidence-freshness.js

@@ -0,0 +1,567 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.dogfoodEvidenceFreshness.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/dogfood-evidence-freshness";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const MAX_FINDINGS = 25;
+const MAX_EVIDENCE_REFS_PER_FINDING = 3;
+const MAX_ARTIFACT_SIZE = 256 * 1024; // 256KB
+const STALE_DAYS = 90;
+
+// Matches a Windows drive path (C:\ or C:/dir) but NOT a URL scheme like
+// http://, https://, postgresql:// — a URL has `://` (two slashes after the
+// colon) and is never an absolute LOCAL path. Excluding URL schemes removes a
+// false-positive class without weakening local-path detection.
+const ABSOLUTE_WINDOWS_PATH_RE = /[A-Za-z]:(?:\\|\/(?!\/))/;
+const ABSOLUTE_UNIX_PATH_RE = /(?:^|\s)\/(?:Users|home|tmp|var|etc)\//;
+// `sk-` requires a leading non-alphanumeric boundary so it matches real API
+// keys (e.g. "sk-ant-...") but NOT the "sk-" buried inside ordinary words like
+// "ri[sk-]governance" or "ta[sk-]specific". Without the boundary, hyphenated
+// English phrases were flagged as secrets — a false-positive class.
+const SECRET_PATTERN_RE = /(?:(?<![A-Za-z0-9])sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*[^\s'"]{8,})/i;
+// A raw dump is a SINGLE fenced code/log block of 500+ chars. The inner match
+// must not cross a ``` fence — otherwise several small command blocks separated
+// by prose were spuriously joined into one phantom "dump" (a false positive
+// that also flagged legitimate command-example docs).
+const RAW_DUMP_RE = /```(?:json|js|javascript|typescript|ts|bash|sh|log|text)\s*\n(?:(?!```)[\s\S]){500,}?\n```/;
+const PR_REF_RE = /(?:PR|pull request|pull)\s*#?(\d+)/gi;
+const SHA_REF_RE = /\b[0-9a-f]{7,40}\b/g;
+const PASS_COUNT_RE = /(\d+)\s*(?:test|spec|assertion|check)s?\s*(?:pass|passed|passing|green)/i;
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/(?:(?<![A-Za-z0-9])sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16})/g, "[redacted-token]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .trim();
+  if (!text) return null;
+  return text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text;
+}
+
+function sanitizeRef(ref) {
+  const text = toPosix(String(ref || "").trim());
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function makeEvidenceRef(relPath, label) {
+  const base = sanitizeRef(relPath);
+  if (!base) return null;
+  const note = label ? ` (${sanitizeText(label, 80)})` : "";
+  return `${base}${note}`;
+}
+
+function severityRank(severity) {
+  if (severity === "block") return 3;
+  if (severity === "warn") return 2;
+  if (severity === "info") return 1;
+  return 0;
+}
+
+function isStaleDate(isoString) {
+  if (!isoString) return false;
+  try {
+    const d = new Date(isoString);
+    if (isNaN(d.getTime())) return false;
+    const now = Date.now();
+    return (now - d.getTime()) > (STALE_DAYS * 24 * 60 * 60 * 1000);
+  } catch {
+    return false;
+  }
+}
+
+function hasAbsolutePath(text) {
+  return ABSOLUTE_WINDOWS_PATH_RE.test(text) || ABSOLUTE_UNIX_PATH_RE.test(text);
+}
+
+// ── Scan dogfood docs ───────────────────────────────────────────────────────
+
+function scanDogfoodDocs(cwd) {
+  const docs = [];
+  const dogfoodDir = path.join(cwd, "docs", "dogfood");
+  if (!fs.existsSync(dogfoodDir)) return docs;
+
+  try {
+    for (const entry of fs.readdirSync(dogfoodDir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(".md") && !entry.name.endsWith(".json")) continue;
+      const absPath = path.join(dogfoodDir, entry.name);
+      const relPath = toPosix(`docs/dogfood/${entry.name}`);
+      try {
+        const stat = fs.statSync(absPath);
+        if (stat.size > MAX_ARTIFACT_SIZE) {
+          docs.push({ relPath, content: null, oversized: true, size: stat.size });
+          continue;
+        }
+        const content = fs.readFileSync(absPath, "utf8");
+        docs.push({ relPath, content, oversized: false, size: stat.size });
+      } catch {
+        docs.push({ relPath, content: null, oversized: false, size: 0 });
+      }
+    }
+  } catch {}
+  return docs;
+}
+
+// ── Scan artifact dirs ──────────────────────────────────────────────────────
+
+function scanArtifacts(cwd) {
+  const artifacts = [];
+  const dirs = [
+    "artifacts",
+    ".claude/cco/reports",
+    ".claude/cco/state",
+    ".claude/cco/orchestration",
+  ];
+
+  let fileCount = 0;
+  for (const dir of dirs) {
+    const absDir = path.join(cwd, dir);
+    if (!fs.existsSync(absDir)) continue;
+    walkJsonFiles(absDir, cwd, artifacts, fileCount, 4);
+    fileCount = artifacts.length;
+  }
+  return artifacts;
+}
+
+function walkJsonFiles(dirPath, cwd, artifacts, currentCount, maxDepth) {
+  if (maxDepth <= 0 || currentCount >= 200) return;
+  try {
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+      if (artifacts.length >= 200) return;
+      const absPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        walkJsonFiles(absPath, cwd, artifacts, artifacts.length, maxDepth - 1);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const relPath = toPosix(path.relative(cwd, absPath));
+      try {
+        const stat = fs.statSync(absPath);
+        if (stat.size > MAX_ARTIFACT_SIZE) {
+          artifacts.push({ relPath, data: null, oversized: true });
+          continue;
+        }
+        const raw = fs.readFileSync(absPath, "utf8").replace(/^/, "");
+        const data = JSON.parse(raw);
+        artifacts.push({ relPath, data, oversized: false });
+      } catch {
+        artifacts.push({ relPath, data: null, oversized: false });
+      }
+    }
+  } catch {}
+}
+
+// ── Load capability manifest for coverage check ─────────────────────────────
+
+function loadCapabilityManifest(cwd) {
+  try {
+    const reg = require("./capability-registry");
+    if (typeof reg.listCapabilities === "function") return reg.listCapabilities();
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+// ── Core analysis ───────────────────────────────────────────────────────────
+
+function buildDogfoodFreshnessReport(cwd = process.cwd(), options = {}) {
+  const limitsApplied = [];
+  const findings = [];
+  const seenCodes = new Map();
+
+  function addFinding(severity, reasonCode, title, safeNextAction, evidenceRefs) {
+    if (findings.length >= MAX_FINDINGS) {
+      if (!limitsApplied.includes("MAX_FINDINGS_REACHED")) limitsApplied.push("MAX_FINDINGS_REACHED");
+      return;
+    }
+    const key = `${reasonCode}:${(evidenceRefs || [])[0] || ""}`;
+    if (seenCodes.has(key)) return;
+    seenCodes.set(key, true);
+    findings.push({
+      severity,
+      reasonCode,
+      title: sanitizeText(title, 220),
+      safeNextAction: sanitizeText(safeNextAction, 220),
+      evidenceRefs: (evidenceRefs || []).slice(0, MAX_EVIDENCE_REFS_PER_FINDING).filter(Boolean),
+    });
+  }
+
+  const docs = scanDogfoodDocs(cwd);
+  const artifacts = scanArtifacts(cwd);
+  const capabilities = loadCapabilityManifest(cwd);
+
+  if (docs.length === 0 && artifacts.length === 0) {
+    const emptyReport = buildEmptyReport(limitsApplied);
+    if (options.write !== false) {
+      safeWriteJson(cwd, REPORT_JSON_REL, emptyReport);
+    }
+    return emptyReport;
+  }
+
+  let staleRefCount = 0;
+  let missingEvidenceCount = 0;
+  let unsafeEvidenceCount = 0;
+
+  // ── Check each dogfood doc ──
+  for (const doc of docs) {
+    addFinding("info", "DOGFOOD_DOC_FOUND", `Dogfood doc found: ${doc.relPath}`, "No action needed.", [makeEvidenceRef(doc.relPath, "dogfood doc")]);
+
+    if (!doc.content) continue;
+
+    // Check for absolute paths
+    if (hasAbsolutePath(doc.content)) {
+      addFinding("block", "DOGFOOD_ABSOLUTE_PATH_FOUND", `Absolute local path found in ${doc.relPath}`, "Replace absolute paths with repo-relative paths.", [makeEvidenceRef(doc.relPath, "absolute path")]);
+      unsafeEvidenceCount++;
+    }
+
+    // Check for raw dumps
+    if (RAW_DUMP_RE.test(doc.content)) {
+      addFinding("block", "DOGFOOD_RAW_DUMP_FOUND", `Large raw code/log dump found in ${doc.relPath}`, "Replace raw dumps with concise evidence summaries.", [makeEvidenceRef(doc.relPath, "raw dump")]);
+      unsafeEvidenceCount++;
+    }
+
+    // Check for secret patterns
+    if (SECRET_PATTERN_RE.test(doc.content)) {
+      addFinding("block", "DOGFOOD_SECRET_PATTERN_FOUND", `Secret-like pattern found in ${doc.relPath}`, "Remove or redact secret values.", [makeEvidenceRef(doc.relPath, "secret pattern")]);
+      unsafeEvidenceCount++;
+    }
+
+    // Check for stale PR refs
+    const prRefs = doc.content.matchAll(PR_REF_RE);
+    for (const match of prRefs) {
+      const prNum = parseInt(match[1], 10);
+      if (prNum < 100) {
+        addFinding("warn", "DOGFOOD_STALE_PR_REF", `Possibly stale PR #${prNum} reference in ${doc.relPath}`, "Verify PR reference is still relevant.", [makeEvidenceRef(doc.relPath, `PR #${prNum}`)]);
+        staleRefCount++;
+      }
+    }
+
+    // Check for pass counts without test refs
+    const passMatch = doc.content.match(PASS_COUNT_RE);
+    if (passMatch) {
+      addFinding("info", "DOGFOOD_PASS_COUNT_FOUND", `Pass count found in ${doc.relPath}: ${passMatch[0]}`, "Verify pass count is backed by actual test evidence.", [makeEvidenceRef(doc.relPath, "pass count")]);
+
+      // Check if there's a test file reference nearby
+      const hasTestRef = /(?:tests?\/|\.test\.|\.spec\.|test-runner|vitest|jest|mocha)/i.test(doc.content);
+      if (!hasTestRef) {
+        addFinding("warn", "DOGFOOD_PASS_COUNT_UNSUPPORTED", `Pass count in ${doc.relPath} has no visible test file reference`, "Add references to actual test files that produce this count.", [makeEvidenceRef(doc.relPath, "unsupported pass count")]);
+        missingEvidenceCount++;
+      }
+    }
+
+    // Check module refs exist
+    const moduleRefs = doc.content.match(/(?:scripts\/lib\/[a-z0-9-]+\.js|scripts\/[a-z0-9-]+\.js)/gi) || [];
+    for (const ref of [...new Set(moduleRefs)].slice(0, 10)) {
+      if (fs.existsSync(path.join(cwd, ref))) {
+        addFinding("info", "DOGFOOD_MODULE_REF_FOUND", `Module reference '${ref}' exists`, "No action needed.", [makeEvidenceRef(ref, "module")]);
+      } else {
+        addFinding("warn", "DOGFOOD_MISSING_ARTIFACT", `Referenced module '${ref}' not found in ${doc.relPath}`, "Update or remove the stale module reference.", [makeEvidenceRef(doc.relPath, `missing: ${ref}`)]);
+        missingEvidenceCount++;
+      }
+    }
+
+    // Check test file refs exist
+    const testRefs = doc.content.match(/(?:tests\/[a-z0-9-]+\.test\.js)/gi) || [];
+    for (const ref of [...new Set(testRefs)].slice(0, 10)) {
+      if (fs.existsSync(path.join(cwd, ref))) {
+        addFinding("info", "DOGFOOD_TEST_REF_FOUND", `Test reference '${ref}' exists`, "No action needed.", [makeEvidenceRef(ref, "test")]);
+      } else {
+        addFinding("warn", "DOGFOOD_MISSING_ARTIFACT", `Referenced test '${ref}' not found in ${doc.relPath}`, "Update or remove the stale test reference.", [makeEvidenceRef(doc.relPath, `missing: ${ref}`)]);
+        missingEvidenceCount++;
+      }
+    }
+
+    // Check release doc refs
+    const releaseRefs = doc.content.match(/(?:docs\/releases\/[a-z0-9-]+\.md)/gi) || [];
+    for (const ref of [...new Set(releaseRefs)].slice(0, 5)) {
+      if (fs.existsSync(path.join(cwd, ref))) {
+        addFinding("info", "DOGFOOD_RELEASE_REF_FOUND", `Release doc '${ref}' exists`, "No action needed.", [makeEvidenceRef(ref, "release doc")]);
+      } else {
+        addFinding("warn", "DOGFOOD_MISSING_ARTIFACT", `Referenced release doc '${ref}' not found in ${doc.relPath}`, "Update or remove the stale release reference.", [makeEvidenceRef(doc.relPath, `missing: ${ref}`)]);
+        missingEvidenceCount++;
+      }
+    }
+  }
+
+  // ── Check artifacts for freshness ──
+  for (const artifact of artifacts) {
+    if (!artifact.data) continue;
+
+    addFinding("info", "DOGFOOD_ARTIFACT_FOUND", `Artifact found: ${artifact.relPath}`, "No action needed.", [makeEvidenceRef(artifact.relPath, "artifact")]);
+
+    // Schema check
+    if (!artifact.data.schemaVersion) {
+      addFinding("warn", "DOGFOOD_MISSING_SCHEMA", `Artifact ${artifact.relPath} has no schemaVersion`, "Add schemaVersion to the artifact.", [makeEvidenceRef(artifact.relPath, "missing schema")]);
+    }
+
+    // Stale generatedAt
+    if (artifact.data.generatedAt && isStaleDate(artifact.data.generatedAt)) {
+      addFinding("warn", "DOGFOOD_STALE_ARTIFACT", `Artifact ${artifact.relPath} generatedAt is older than ${STALE_DAYS} days`, "Re-generate the artifact to refresh evidence.", [makeEvidenceRef(artifact.relPath, "stale")]);
+      staleRefCount++;
+    }
+  }
+
+  // ── Coverage mismatch ──
+  if (capabilities.length > 0 && docs.length > 0) {
+    const docNames = new Set(docs.map(d => d.relPath.toLowerCase()));
+    let coveredCount = 0;
+    for (const cap of capabilities) {
+      const capId = String(cap.id || cap.name || "").toLowerCase().replace(/_/g, "-");
+      const found = [...docNames].some(d => d.includes(capId));
+      if (found) coveredCount++;
+    }
+    const coverageRatio = capabilities.length > 0 ? coveredCount / capabilities.length : 1;
+    if (coverageRatio < 0.3) {
+      addFinding("warn", "DOGFOOD_COVERAGE_MISMATCH", `Dogfood coverage is low: ${coveredCount}/${capabilities.length} capabilities have matching dogfood docs`, "Add dogfood docs for uncovered capabilities.", []);
+      missingEvidenceCount++;
+    }
+  }
+
+  // ── Determine overall status ──
+  const hasBlock = findings.some(f => f.severity === "block");
+  const hasWarn = findings.some(f => f.severity === "warn");
+  const status = hasBlock ? "blocked" : hasWarn ? "warn" : "pass";
+
+  const warnCount = findings.filter(f => f.severity === "warn").length;
+  const blockCount = findings.filter(f => f.severity === "block").length;
+  const infoCount = findings.filter(f => f.severity === "info").length;
+
+  const safeNextAction = hasBlock
+    ? "Remove raw secrets, absolute paths, or code dumps from dogfood evidence before sharing."
+    : hasWarn
+      ? "Update stale references and add missing evidence links in dogfood docs."
+      : "Dogfood evidence is fresh and connected. Safe to proceed.";
+
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      title: "Dogfood Evidence Freshness Guard",
+      text: `${docs.length} docs inspected, ${artifacts.length} artifacts inspected. ${staleRefCount} stale, ${missingEvidenceCount} missing, ${unsafeEvidenceCount} unsafe.`,
+      findingCounts: { info: infoCount, warn: warnCount, block: blockCount },
+      safeNextAction,
+    },
+    surfaceEvidence: {
+      filesInspected: docs.length + artifacts.length,
+      artifactsInspected: artifacts.length,
+      capabilitiesInspected: capabilities.length,
+      limitsApplied,
+    },
+    freshnessCounts: {
+      docsInspected: docs.length,
+      artifactsInspected: artifacts.length,
+      staleRefCount,
+      missingEvidenceCount,
+      unsafeEvidenceCount,
+    },
+    findings: findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity)),
+    productHome: {
+      cardSource: "dogfood-evidence-freshness",
+      status,
+      found: findings.filter(f => f.severity === "warn" || f.severity === "block").map(f => sanitizeText(f.title, 120)).slice(0, 5),
+      fixedOrPrepared: [],
+      savedOrProved: staleRefCount === 0 && missingEvidenceCount === 0 ? ["Dogfood evidence is fresh and connected"] : [],
+      forReview: findings.filter(f => f.severity === "block").map(f => sanitizeText(f.title, 120)).slice(0, 3),
+      safeNextAction,
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "heuristic",
+      publicClaimAllowed: false,
+      evidenceRefs: [makeEvidenceRef(REPORT_JSON_REL, "freshness report")].filter(Boolean),
+      caveat: "Freshness checks are heuristic-based. No test suite execution or live validation performed.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      registryCalls: false,
+      rawDump: false,
+      autoFix: false,
+    },
+  };
+
+  if (options.write !== false) {
+    safeWriteJson(cwd, REPORT_JSON_REL, report);
+  }
+
+  return report;
+}
+
+function buildEmptyReport(limitsApplied = []) {
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      title: "Dogfood Evidence Freshness Guard",
+      text: "No dogfood evidence found.",
+      findingCounts: { info: 0, warn: 0, block: 0 },
+      safeNextAction: "No dogfood evidence available. Create dogfood docs in docs/dogfood/.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      capabilitiesInspected: 0,
+      limitsApplied,
+    },
+    freshnessCounts: {
+      docsInspected: 0,
+      artifactsInspected: 0,
+      staleRefCount: 0,
+      missingEvidenceCount: 0,
+      unsafeEvidenceCount: 0,
+    },
+    findings: [],
+    productHome: {
+      cardSource: "dogfood-evidence-freshness",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "No dogfood evidence available.",
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "unavailable",
+      publicClaimAllowed: false,
+      evidenceRefs: [],
+      caveat: "No data to measure against.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      registryCalls: false,
+      rawDump: false,
+      autoFix: false,
+    },
+  };
+}
+
+// ── Generate / Load / Format / Surface ──────────────────────────────────────
+
+function generateDogfoodFreshness(cwd = process.cwd(), options = {}) {
+  const report = buildDogfoodFreshnessReport(cwd, options);
+  return { report, reportPath: path.join(cwd, REPORT_JSON_REL) };
+}
+
+function loadDogfoodFreshness(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function formatDogfoodFreshnessText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Dogfood Evidence Freshness Guard",
+      "Status: NO DATA",
+      "No dogfood evidence found yet.",
+      "Safe next action: Create dogfood docs in docs/dogfood/.",
+    ].join("\n");
+  }
+
+  const fc = report.freshnessCounts || {};
+  const lines = [
+    "Avorelo Dogfood Evidence Freshness Guard",
+    `Status: ${String(report.status || "no_data").toUpperCase()} · redacted=${report.redacted === true ? "yes" : "no"}`,
+    `Docs: ${fc.docsInspected || 0} · artifacts: ${fc.artifactsInspected || 0} · stale=${fc.staleRefCount || 0} · missing=${fc.missingEvidenceCount || 0} · unsafe=${fc.unsafeEvidenceCount || 0}`,
+    "Notes: local static scan only · no test execution · no doc mutation",
+  ];
+
+  if (Array.isArray(report.findings) && report.findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const finding of report.findings.slice(0, 5)) {
+      lines.push(`- [${finding.severity}] ${finding.title}${finding.evidenceRefs?.length ? ` · ${finding.evidenceRefs[0]}` : ""}`);
+    }
+    if (report.findings.length > 5) {
+      lines.push(`  ... and ${report.findings.length - 5} more`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`Safe next action: ${report.summary?.safeNextAction || "Review dogfood evidence freshness."}`);
+  return lines.join("\n");
+}
+
+function formatDogfoodFreshnessStatusLine(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Dogfood freshness: NOT RUN · run `avorelo dogfood-freshness --text`";
+  }
+  const fc = report.freshnessCounts || {};
+  return `Dogfood freshness: ${String(report.status || "no_data").toUpperCase()}`
+    + ` · docs=${fc.docsInspected || 0}`
+    + ` · stale=${fc.staleRefCount || 0}`
+    + ` · missing=${fc.missingEvidenceCount || 0}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review dogfood evidence."}`;
+}
+
+function buildDogfoodFreshnessSurface(cwd = process.cwd(), options = {}) {
+  const report = loadDogfoodFreshness(cwd) || (options.buildIfMissing ? buildDogfoodFreshnessReport(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      docsInspected: 0,
+      staleRefCount: 0,
+      missingEvidenceCount: 0,
+      nextBestAction: "Run `avorelo dogfood-freshness --text` to check evidence freshness.",
+      statusLine: "Dogfood freshness: NOT RUN · run `avorelo dogfood-freshness --text`",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: ["Local heuristic analysis only. No test execution."],
+    };
+  }
+
+  const fc = report.freshnessCounts || {};
+  return {
+    status: report.status,
+    docsInspected: fc.docsInspected || 0,
+    staleRefCount: fc.staleRefCount || 0,
+    missingEvidenceCount: fc.missingEvidenceCount || 0,
+    unsafeEvidenceCount: fc.unsafeEvidenceCount || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatDogfoodFreshnessStatusLine(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: ["Local heuristic analysis only. No test execution."],
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildDogfoodFreshnessReport,
+  generateDogfoodFreshness,
+  loadDogfoodFreshness,
+  formatDogfoodFreshnessText,
+  formatDogfoodFreshnessStatusLine,
+  buildDogfoodFreshnessSurface,
+};