avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/observability-recovery-guard.js

@@ -0,0 +1,1030 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.observabilityRecoveryGuard.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/observability-recovery-guard";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const TEXT_FILE_RE = /\.(cjs|cts|env|ini|js|json|jsx|md|mjs|mts|prisma|sql|toml|ts|tsx|txt|yaml|yml)$/i;
+const SKIP_DIRS = new Set([
+  ".claude",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".wasp",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+// --- Detection patterns ---
+
+const LOGGING_RE = /\b(winston|pino|bunyan|log4js?|morgan|logger|logging|console\.(log|error|warn|info|debug)|createLogger|getLogger|log\.info|log\.error|log\.warn|log\.debug)\b/i;
+const METRICS_RE = /\b(prometheus|prom-client|statsd|datadog|dd-trace|metrics|collectDefaultMetrics|Counter|Histogram|Gauge|Summary|register\.metrics)\b/i;
+const TRACING_RE = /\b(opentelemetry|otel|@opentelemetry|tracing|jaeger|zipkin|TracerProvider|trace\.getTracer|SpanKind|startSpan|endSpan|W3CTraceContextPropagator)\b/i;
+const ERROR_HANDLING_RE = /\b(ErrorBoundary|error[_-]?boundary|errorHandler|error[_-]?handler|Sentry|captureException|captureMessage|reportError|onError|handleError|process\.on\s*\(\s*["']uncaughtException|process\.on\s*\(\s*["']unhandledRejection)\b/i;
+const HEALTHCHECK_RE = /\b(\/health|\/healthz|\/healthcheck|health[_-]?check|healthCheck|healthEndpoint)\b/i;
+const READINESS_RE = /\b(\/ready|\/readyz|\/readiness|\/liveness|\/livez|readiness[_-]?check|liveness[_-]?check|readinessProbe|livenessProbe)\b/i;
+const ROLLBACK_DOC_RE = /\b(rollback|roll[_-]?back)\b/i;
+const RECOVERY_DOC_RE = /\b(recovery|runbook|incident[_-]?response|disaster[_-]?recovery|backup[_-]?plan)\b/i;
+const AUDIT_EVENT_RE = /\b(audit|audit[_-]?log|audit[_-]?event|audit[_-]?trail|auditLog|auditEvent)\b/i;
+const RETRY_RECOVERY_RE = /\b(retry|retries|exponential[_-]?backoff|circuit[_-]?breaker|fallback|graceful[_-]?degradation|dead[_-]?letter|dlq|compensating[_-]?transaction)\b/i;
+
+const SUPPORT_BUNDLE_PATH_RE = /(^|\/)\.claude\/cco\/support\b/i;
+const RECEIPT_PATH_RE = /(^|\/)\.claude\/cco\/receipts?\b/i;
+const VALIDATION_ARTIFACT_PATH_RE = /(^|\/)\.claude\/cco\/reports\b/i;
+const CI_WORKFLOW_PATH_RE = /(^|\/)\.github\/workflows\/.+\.(yml|yaml)$/i;
+const TEST_FILE_PATH_RE = /(^|\/)(test|tests|__tests__|spec|__spec__|\.test\.|\.spec\.)\b/i;
+
+// --- Utility functions (same pattern as existing guards) ---
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/(?: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 = String(ref || "").trim().replace(/\\/g, "/");
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function makeEvidenceRef(relPath, lineNumber, label) {
+  const base = sanitizeRef(relPath);
+  if (!base) return null;
+  const suffix = Number.isFinite(lineNumber) && lineNumber > 0 ? `:${lineNumber}` : "";
+  const note = label ? ` (${sanitizeText(label, 80)})` : "";
+  return `${base}${suffix}${note}`;
+}
+
+// --- Workspace walking ---
+
+function walkWorkspace(cwd) {
+  const files = [];
+
+  function visit(current, depth) {
+    if (depth > 8 || files.length >= 2200) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (files.length >= 2200) return;
+      const absPath = path.join(current, entry.name);
+      const relPath = toPosix(path.relative(cwd, absPath));
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        visit(absPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      files.push({
+        absPath,
+        relPath,
+        text: undefined,
+      });
+    }
+  }
+
+  visit(cwd, 0);
+  return files;
+}
+
+function readText(file) {
+  if (file.text !== undefined) return file.text;
+  if (!TEXT_FILE_RE.test(file.relPath)) {
+    file.text = null;
+    return file.text;
+  }
+  try {
+    const stat = fs.statSync(file.absPath);
+    if (stat.size > 256 * 1024) {
+      file.text = null;
+      return file.text;
+    }
+    file.text = fs.readFileSync(file.absPath, "utf8");
+    return file.text;
+  } catch {
+    file.text = null;
+    return file.text;
+  }
+}
+
+function findLineNumber(text, index) {
+  const prefix = text.slice(0, index);
+  return prefix.split(/\r?\n/).length;
+}
+
+function collectPatternRefs(file, regex, options = {}) {
+  const text = readText(file);
+  if (!text) return [];
+  const limit = options.limit || 5;
+  const refs = [];
+  const flags = regex.flags.includes("g") ? regex.flags : `${regex.flags}g`;
+  const matcher = new RegExp(regex.source, flags);
+  let match;
+  while ((match = matcher.exec(text)) && refs.length < limit) {
+    const lineNumber = findLineNumber(text, match.index);
+    refs.push(makeEvidenceRef(file.relPath, lineNumber, options.label ? options.label(match) : null));
+    if (match.index === matcher.lastIndex) matcher.lastIndex += 1;
+  }
+  return refs.filter(Boolean);
+}
+
+function collectLineRefs(file, matcher, options = {}) {
+  const text = readText(file);
+  if (!text) return [];
+  const limit = options.limit || 5;
+  const refs = [];
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index < lines.length && refs.length < limit; index += 1) {
+    const line = lines[index];
+    const value = typeof matcher === "function" ? matcher(line, index + 1) : (matcher.test(line) ? true : false);
+    if (!value) continue;
+    const label = typeof value === "string"
+      ? value
+      : options.label
+        ? options.label(line, index + 1)
+        : null;
+    refs.push(makeEvidenceRef(file.relPath, index + 1, label));
+  }
+  return refs.filter(Boolean);
+}
+
+// --- Severity helpers ---
+
+function severityRank(severity) {
+  if (severity === "block") return 3;
+  if (severity === "warn") return 2;
+  return 1;
+}
+
+// --- Finding counter ---
+
+let findingCounter = 0;
+
+function nextFindingId() {
+  findingCounter += 1;
+  return `obs-rec-${String(findingCounter).padStart(3, "0")}`;
+}
+
+function resetFindingCounter() {
+  findingCounter = 0;
+}
+
+// --- Report builder ---
+
+function buildEmptyReport() {
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      title: "Observability & Recovery Guard",
+      text: "No observability or recovery evidence detected.",
+      findingCounts: { info: 0, warn: 0, block: 0 },
+      safeNextAction: "Add observability or recovery evidence before trusting this change.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      changedFilesConsidered: 0,
+      surfacesDetected: [],
+      limitsApplied: [],
+    },
+    findings: [],
+    productHome: {
+      cardSource: "observabilityRecoveryGuard",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "Add observability or recovery evidence before trusting this change.",
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "heuristic",
+      publicClaimAllowed: false,
+      evidenceRefs: [],
+      caveat: "Local static scan only. No external observability API calls.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      rawLogDump: false,
+      rawPromptDump: false,
+      rawCodeDump: false,
+      secretDump: false,
+      autoFix: false,
+    },
+    overhead: {
+      durationMs: 0,
+      filesInspected: 0,
+      artifactsInspected: 0,
+      limitsApplied: [],
+    },
+  };
+}
+
+function addFinding(report, finding) {
+  report.findings.push({
+    id: finding.id,
+    severity: finding.severity,
+    reasonCode: finding.reasonCode,
+    title: sanitizeText(finding.title, 120),
+    message: sanitizeText(finding.message, 220),
+    evidenceRefs: (finding.evidenceRefs || []).map((ref) => ({
+      path: sanitizeRef(ref.path),
+      kind: ref.kind || "file",
+      selector: sanitizeText(ref.selector, 120) || null,
+      redacted: true,
+    })).filter((ref) => ref.path),
+    safeNextAction: sanitizeText(finding.safeNextAction, 220) || "Review the evidence before shipping.",
+  });
+}
+
+// --- Detection surfaces ---
+
+function detectLogging(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, LOGGING_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectMetrics(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, METRICS_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectTracing(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, TRACING_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectErrorHandling(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, ERROR_HANDLING_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectHealthChecks(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, HEALTHCHECK_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectReadinessLiveness(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, READINESS_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectRollbackDocs(files) {
+  const refs = [];
+  for (const file of files) {
+    if (ROLLBACK_DOC_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "rollback doc"));
+      if (refs.length >= 8) break;
+      continue;
+    }
+    const text = readText(file);
+    if (!text) continue;
+    if (/\.md$/i.test(file.relPath) && ROLLBACK_DOC_RE.test(text)) {
+      const found = collectPatternRefs(file, ROLLBACK_DOC_RE, { limit: 1 });
+      refs.push(...found);
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.filter(Boolean).slice(0, 8);
+}
+
+function detectRecoveryDocs(files) {
+  const refs = [];
+  for (const file of files) {
+    if (RECOVERY_DOC_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "recovery doc"));
+      if (refs.length >= 8) break;
+      continue;
+    }
+    const text = readText(file);
+    if (!text) continue;
+    if (/\.md$/i.test(file.relPath) && RECOVERY_DOC_RE.test(text)) {
+      const found = collectPatternRefs(file, RECOVERY_DOC_RE, { limit: 1 });
+      refs.push(...found);
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.filter(Boolean).slice(0, 8);
+}
+
+function detectSupportBundle(files) {
+  const refs = [];
+  for (const file of files) {
+    if (SUPPORT_BUNDLE_PATH_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "support bundle"));
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.slice(0, 8);
+}
+
+function detectReceipts(files) {
+  const refs = [];
+  for (const file of files) {
+    if (RECEIPT_PATH_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "receipt"));
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.slice(0, 8);
+}
+
+function detectAuditEvents(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, AUDIT_EVENT_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectValidationArtifacts(files) {
+  const refs = [];
+  for (const file of files) {
+    if (VALIDATION_ARTIFACT_PATH_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "validation artifact"));
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.slice(0, 8);
+}
+
+function detectCiEvidence(files) {
+  const refs = [];
+  for (const file of files) {
+    if (CI_WORKFLOW_PATH_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "CI workflow"));
+      if (refs.length >= 8) break;
+    }
+  }
+  return refs.slice(0, 8);
+}
+
+function detectTestEvidence(files) {
+  const refs = [];
+  for (const file of files) {
+    if (TEST_FILE_PATH_RE.test(file.relPath)) {
+      refs.push(makeEvidenceRef(file.relPath, null, "test file"));
+      if (refs.length >= 6) break;
+    }
+  }
+  return refs.slice(0, 6);
+}
+
+function detectErrorBoundaries(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, /\b(ErrorBoundary|error[_-]?boundary)\b/i, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+function detectRetryRecovery(files) {
+  const refs = [];
+  for (const file of files) {
+    const found = collectPatternRefs(file, RETRY_RECOVERY_RE, { limit: 2 });
+    refs.push(...found);
+    if (refs.length >= 8) break;
+  }
+  return refs.slice(0, 8);
+}
+
+// --- Main builder ---
+
+function buildObservabilityRecoveryGuard(cwd = process.cwd(), options = {}) {
+  const startTime = Date.now();
+  resetFindingCounter();
+
+  const report = buildEmptyReport();
+  const files = walkWorkspace(cwd);
+  const limitsApplied = [];
+
+  if (files.length >= 2200) {
+    limitsApplied.push("file-count-limit-2200");
+  }
+
+  // Source files for content-based detection
+  const sourceFiles = files.filter((file) => /\.(cjs|cts|js|jsx|mjs|mts|ts|tsx)$/i.test(file.relPath));
+  // All text files including md, yaml, etc. for doc-based detection
+  const allTextFiles = files.filter((file) => TEXT_FILE_RE.test(file.relPath));
+
+  // Run detection surfaces
+  const loggingRefs = detectLogging(sourceFiles);
+  const metricsRefs = detectMetrics(sourceFiles);
+  const tracingRefs = detectTracing(sourceFiles);
+  const errorHandlingRefs = detectErrorHandling(sourceFiles);
+  const healthCheckRefs = detectHealthChecks(allTextFiles);
+  const readinessRefs = detectReadinessLiveness(allTextFiles);
+  const rollbackDocRefs = detectRollbackDocs(allTextFiles);
+  const recoveryDocRefs = detectRecoveryDocs(allTextFiles);
+  const supportBundleRefs = detectSupportBundle(files);
+  const receiptRefs = detectReceipts(files);
+  const auditEventRefs = detectAuditEvents(sourceFiles);
+  const validationArtifactRefs = detectValidationArtifacts(files);
+  const ciEvidenceRefs = detectCiEvidence(files);
+  const testEvidenceRefs = detectTestEvidence(files);
+  const errorBoundaryRefs = detectErrorBoundaries(sourceFiles);
+  const retryRecoveryRefs = detectRetryRecovery(sourceFiles);
+
+  // Track detected surfaces
+  const surfacesDetected = [];
+  let artifactsInspected = 0;
+
+  // --- Emit findings for each detected surface ---
+
+  if (loggingRefs.length > 0) {
+    surfacesDetected.push("logging");
+    artifactsInspected += loggingRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_LOGGING_FOUND",
+      title: "Logging setup detected",
+      message: `Found ${loggingRefs.length} logging reference(s) in the workspace.`,
+      evidenceRefs: loggingRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep logging configuration current as the codebase evolves.",
+    });
+  }
+
+  if (metricsRefs.length > 0) {
+    surfacesDetected.push("metrics");
+    artifactsInspected += metricsRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_METRICS_FOUND",
+      title: "Metrics setup detected",
+      message: `Found ${metricsRefs.length} metrics reference(s) in the workspace.`,
+      evidenceRefs: metricsRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep metrics instrumentation aligned with production surfaces.",
+    });
+  }
+
+  if (tracingRefs.length > 0) {
+    surfacesDetected.push("tracing");
+    artifactsInspected += tracingRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_TRACING_FOUND",
+      title: "Tracing or OpenTelemetry setup detected",
+      message: `Found ${tracingRefs.length} tracing reference(s) in the workspace.`,
+      evidenceRefs: tracingRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep tracing configuration aligned with deployed service boundaries.",
+    });
+  }
+
+  if (errorHandlingRefs.length > 0) {
+    surfacesDetected.push("error-handling");
+    artifactsInspected += errorHandlingRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_ERROR_BOUNDARY_FOUND",
+      title: "Error handling patterns detected",
+      message: `Found ${errorHandlingRefs.length} error handling reference(s) in the workspace.`,
+      evidenceRefs: errorHandlingRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep error handling coverage aligned with critical code paths.",
+    });
+  }
+
+  if (healthCheckRefs.length > 0) {
+    surfacesDetected.push("health-checks");
+    artifactsInspected += healthCheckRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_HEALTHCHECK_FOUND",
+      title: "Health check endpoint detected",
+      message: `Found ${healthCheckRefs.length} health check reference(s) in the workspace.`,
+      evidenceRefs: healthCheckRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep health check endpoints exercised and monitored in production.",
+    });
+  }
+
+  if (readinessRefs.length > 0) {
+    surfacesDetected.push("readiness-liveness");
+    artifactsInspected += readinessRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_READINESS_FOUND",
+      title: "Readiness or liveness check detected",
+      message: `Found ${readinessRefs.length} readiness/liveness reference(s) in the workspace.`,
+      evidenceRefs: readinessRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep readiness and liveness probes aligned with deployment configuration.",
+    });
+  }
+
+  if (rollbackDocRefs.length > 0) {
+    surfacesDetected.push("rollback-docs");
+    artifactsInspected += rollbackDocRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_ROLLBACK_DOC_FOUND",
+      title: "Rollback documentation detected",
+      message: `Found ${rollbackDocRefs.length} rollback doc reference(s) in the workspace.`,
+      evidenceRefs: rollbackDocRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "doc" })),
+      safeNextAction: "Keep rollback documentation current with the latest deployment path.",
+    });
+  }
+
+  if (recoveryDocRefs.length > 0) {
+    surfacesDetected.push("recovery-docs");
+    artifactsInspected += recoveryDocRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_RECOVERY_DOC_FOUND",
+      title: "Recovery documentation detected",
+      message: `Found ${recoveryDocRefs.length} recovery doc reference(s) in the workspace.`,
+      evidenceRefs: recoveryDocRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "doc" })),
+      safeNextAction: "Keep recovery runbooks current with the latest architecture.",
+    });
+  }
+
+  if (supportBundleRefs.length > 0) {
+    surfacesDetected.push("support-bundle");
+    artifactsInspected += supportBundleRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_SUPPORT_BUNDLE_FOUND",
+      title: "Support bundle detected",
+      message: `Found ${supportBundleRefs.length} support bundle artifact(s).`,
+      evidenceRefs: supportBundleRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Keep the support bundle generation process exercised.",
+    });
+  }
+
+  if (receiptRefs.length > 0) {
+    surfacesDetected.push("receipts");
+    artifactsInspected += receiptRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_RECEIPT_FOUND",
+      title: "Receipts detected",
+      message: `Found ${receiptRefs.length} receipt artifact(s).`,
+      evidenceRefs: receiptRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Keep receipt generation aligned with deployment and guard runs.",
+    });
+  }
+
+  if (auditEventRefs.length > 0) {
+    surfacesDetected.push("audit-events");
+    artifactsInspected += auditEventRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_AUDIT_EVENT_FOUND",
+      title: "Audit event patterns detected",
+      message: `Found ${auditEventRefs.length} audit event reference(s).`,
+      evidenceRefs: auditEventRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep audit event coverage aligned with sensitive operations.",
+    });
+  }
+
+  if (validationArtifactRefs.length > 0) {
+    surfacesDetected.push("validation-artifacts");
+    artifactsInspected += validationArtifactRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_VALIDATION_ARTIFACT_FOUND",
+      title: "Validation artifacts detected",
+      message: `Found ${validationArtifactRefs.length} validation artifact(s) in .claude/cco/reports.`,
+      evidenceRefs: validationArtifactRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Keep validation artifacts current with the latest guard runs.",
+    });
+  }
+
+  const ciAndTestRefs = [...ciEvidenceRefs, ...testEvidenceRefs];
+  if (ciAndTestRefs.length > 0) {
+    surfacesDetected.push("ci-test-evidence");
+    artifactsInspected += ciAndTestRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_CI_EVIDENCE_FOUND",
+      title: "CI and test evidence detected",
+      message: `Found ${ciEvidenceRefs.length} CI workflow(s) and ${testEvidenceRefs.length} test file(s).`,
+      evidenceRefs: ciAndTestRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Keep CI workflows and test coverage aligned with deployment confidence.",
+    });
+  }
+
+  if (errorBoundaryRefs.length > 0 && !surfacesDetected.includes("error-handling")) {
+    surfacesDetected.push("error-boundaries");
+    artifactsInspected += errorBoundaryRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_ERROR_BOUNDARY_FOUND",
+      title: "Error boundary components detected",
+      message: `Found ${errorBoundaryRefs.length} error boundary reference(s).`,
+      evidenceRefs: errorBoundaryRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep error boundaries covering critical user-facing routes.",
+    });
+  }
+
+  if (retryRecoveryRefs.length > 0) {
+    surfacesDetected.push("retry-recovery");
+    artifactsInspected += retryRecoveryRefs.length;
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_RETRY_RECOVERY_FOUND",
+      title: "Retry and recovery patterns detected",
+      message: `Found ${retryRecoveryRefs.length} retry/recovery reference(s).`,
+      evidenceRefs: retryRecoveryRefs.slice(0, 3).map((ref) => ({ path: ref, kind: "pattern-match" })),
+      safeNextAction: "Keep retry and recovery patterns aligned with external dependency boundaries.",
+    });
+  }
+
+  // --- Warn/block findings for missing surfaces ---
+
+  const hasDeploymentEvidence = ciEvidenceRefs.length > 0
+    || files.some((file) => /(^|\/)vercel\.json$/i.test(file.relPath)
+      || /(^|\/)netlify\.toml$/i.test(file.relPath)
+      || /(^|\/)fly\.toml$/i.test(file.relPath)
+      || /(^|\/)railway\.json$/i.test(file.relPath)
+      || /(^|\/)(dockerfile|docker-compose\.ya?ml)$/i.test(file.relPath));
+
+  if (hasDeploymentEvidence && rollbackDocRefs.length === 0 && recoveryDocRefs.length === 0) {
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "warn",
+      reasonCode: "OBS_REC_MISSING_RECOVERY_PATH",
+      title: "Missing recovery documentation for deployment-facing change",
+      message: "Deployment configuration exists but no rollback or recovery documentation was found.",
+      evidenceRefs: ciEvidenceRefs.slice(0, 1).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Add recovery or rollback documentation before trusting this deployment path.",
+    });
+  }
+
+  if (hasDeploymentEvidence && supportBundleRefs.length === 0) {
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "warn",
+      reasonCode: "OBS_REC_MISSING_SUPPORT_BUNDLE",
+      title: "Missing support bundle for deployment-facing workspace",
+      message: "Deployment configuration exists but no .claude/cco/support bundle was found.",
+      evidenceRefs: [],
+      safeNextAction: "Generate a support bundle to improve recovery confidence.",
+    });
+  }
+
+  if (hasDeploymentEvidence && receiptRefs.length === 0) {
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "warn",
+      reasonCode: "OBS_REC_MISSING_RECEIPT",
+      title: "Missing receipts for deployment-facing workspace",
+      message: "Deployment configuration exists but no .claude/cco/receipts were found.",
+      evidenceRefs: [],
+      safeNextAction: "Generate guard receipts to create audit trail for deployment confidence.",
+    });
+  }
+
+  // Check for stale validation artifacts
+  for (const file of files.filter((f) => VALIDATION_ARTIFACT_PATH_RE.test(f.relPath) && /\.json$/i.test(f.relPath))) {
+    try {
+      const stat = fs.statSync(file.absPath);
+      const ageMs = Date.now() - stat.mtimeMs;
+      const ageDays = ageMs / (1000 * 60 * 60 * 24);
+      if (ageDays > 7) {
+        addFinding(report, {
+          id: nextFindingId(),
+          severity: "warn",
+          reasonCode: "OBS_REC_STALE_VALIDATION",
+          title: "Stale validation artifact detected",
+          message: `Validation artifact ${toPosix(path.relative(cwd, file.absPath))} is ${Math.floor(ageDays)} days old.`,
+          evidenceRefs: [{ path: makeEvidenceRef(file.relPath, null, "stale artifact"), kind: "artifact" }],
+          safeNextAction: "Re-run guards to refresh stale validation artifacts.",
+        });
+        break; // Only report one stale finding
+      }
+    } catch {
+      // Skip files we can't stat
+    }
+  }
+
+  // Check for corrupt state artifacts
+  for (const file of files.filter((f) => VALIDATION_ARTIFACT_PATH_RE.test(f.relPath) && /\.json$/i.test(f.relPath))) {
+    const text = readText(file);
+    if (text === null) continue;
+    if (text.trim().length > 0) {
+      try {
+        JSON.parse(text);
+      } catch {
+        addFinding(report, {
+          id: nextFindingId(),
+          severity: "block",
+          reasonCode: "OBS_REC_CORRUPT_STATE_ARTIFACT",
+          title: "Corrupt state artifact detected",
+          message: `Validation artifact ${toPosix(path.relative(cwd, file.absPath))} contains invalid JSON.`,
+          evidenceRefs: [{ path: makeEvidenceRef(file.relPath, null, "corrupt artifact"), kind: "artifact" }],
+          safeNextAction: "Delete and regenerate the corrupt validation artifact before trusting guard results.",
+        });
+        break; // Only report one corrupt finding
+      }
+    }
+  }
+
+  // High-risk change with no recovery path
+  if (hasDeploymentEvidence
+    && loggingRefs.length === 0
+    && metricsRefs.length === 0
+    && tracingRefs.length === 0
+    && errorHandlingRefs.length === 0
+    && healthCheckRefs.length === 0
+    && rollbackDocRefs.length === 0
+    && recoveryDocRefs.length === 0) {
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "block",
+      reasonCode: "OBS_REC_HIGH_RISK_NO_RECOVERY",
+      title: "Deployment-facing workspace with no observability or recovery evidence",
+      message: "Deployment configuration exists but no logging, metrics, tracing, error handling, health checks, or recovery docs were found.",
+      evidenceRefs: ciEvidenceRefs.slice(0, 1).map((ref) => ({ path: ref, kind: "artifact" })),
+      safeNextAction: "Add observability and recovery evidence before trusting this deployment path.",
+    });
+  }
+
+  // No evidence at all
+  if (surfacesDetected.length === 0) {
+    addFinding(report, {
+      id: nextFindingId(),
+      severity: "info",
+      reasonCode: "OBS_REC_NO_EVIDENCE",
+      title: "No observability or recovery evidence found",
+      message: "No logging, metrics, tracing, error handling, health checks, recovery docs, or deployment artifacts detected.",
+      evidenceRefs: [],
+      safeNextAction: "Add observability or recovery evidence as the project matures.",
+    });
+  }
+
+  // --- Finalize report ---
+
+  const infos = report.findings.filter((f) => f.severity === "info");
+  const warns = report.findings.filter((f) => f.severity === "warn");
+  const blocks = report.findings.filter((f) => f.severity === "block");
+
+  report.findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+
+  // Determine status
+  if (surfacesDetected.length === 0) {
+    report.status = "no_data";
+  } else if (blocks.length > 0) {
+    report.status = "blocked";
+  } else if (warns.length > 0) {
+    report.status = "warn";
+  } else {
+    report.status = "pass";
+  }
+
+  // Determine safeNextAction
+  let safeNextAction = "Keep observability and recovery evidence current as the codebase evolves.";
+  if (blocks.length > 0) {
+    safeNextAction = blocks[0].safeNextAction;
+  } else if (warns.length > 0) {
+    safeNextAction = warns[0].safeNextAction;
+  } else if (surfacesDetected.length === 0) {
+    safeNextAction = "Add observability or recovery evidence before trusting this change.";
+  }
+
+  // Summary text
+  const summaryParts = [];
+  if (surfacesDetected.length > 0) {
+    summaryParts.push(`${surfacesDetected.length} surface(s) detected`);
+  }
+  if (infos.length > 0) summaryParts.push(`${infos.length} info`);
+  if (warns.length > 0) summaryParts.push(`${warns.length} warn`);
+  if (blocks.length > 0) summaryParts.push(`${blocks.length} block`);
+  if (summaryParts.length === 0) summaryParts.push("no evidence found");
+
+  report.summary = {
+    title: "Observability & Recovery Guard",
+    text: summaryParts.join(" · "),
+    findingCounts: { info: infos.length, warn: warns.length, block: blocks.length },
+    safeNextAction,
+  };
+
+  report.surfaceEvidence = {
+    filesInspected: files.length,
+    artifactsInspected,
+    changedFilesConsidered: 0,
+    surfacesDetected: unique(surfacesDetected),
+    limitsApplied,
+  };
+
+  // productHome
+  report.productHome = {
+    cardSource: "observabilityRecoveryGuard",
+    status: report.status,
+    found: unique(surfacesDetected),
+    fixedOrPrepared: [],
+    savedOrProved: infos.map((f) => f.title).slice(0, 6),
+    forReview: [...warns, ...blocks].map((f) => f.title).slice(0, 6),
+    safeNextAction,
+  };
+
+  // valueProof
+  report.valueProof.evidenceRefs = unique(surfacesDetected.map((s) => `surface:${s}`));
+
+  // overhead
+  const durationMs = Date.now() - startTime;
+  report.overhead = {
+    durationMs,
+    filesInspected: files.length,
+    artifactsInspected,
+    limitsApplied,
+  };
+
+  report.generatedAt = nowIso();
+
+  if (options.write === true) {
+    ensureCcoDirs(cwd);
+    safeWriteJson(cwd, REPORT_JSON_REL, report);
+  }
+
+  return report;
+}
+
+function generateObservabilityRecoveryGuard(cwd = process.cwd(), options = {}) {
+  const report = buildObservabilityRecoveryGuard(cwd, { ...options, write: options.write !== false });
+  return {
+    report,
+    reportPath: path.join(cwd, REPORT_JSON_REL),
+  };
+}
+
+function loadObservabilityRecoveryGuard(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function formatObservabilityRecoveryGuardText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Observability & Recovery Guard",
+      "Status: NO DATA",
+      "No observability or recovery evidence was detected yet.",
+      "Safe next action: Re-run after adding observability or recovery configuration.",
+    ].join("\n");
+  }
+
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+  const surfaces = report.surfaceEvidence?.surfacesDetected?.length || 0;
+
+  const lines = [
+    "Avorelo Observability & Recovery Guard",
+    `Status: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()} · redacted=${report.redacted === true ? "yes" : "no"}`,
+    `Surfaces: ${surfaces} · info=${counts.info} · warn=${counts.warn} · block=${counts.block}`,
+    "Notes: local static scan only · no external observability API calls",
+  ];
+
+  const findings = Array.isArray(report.findings) ? report.findings.slice(0, 6) : [];
+  if (findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const finding of findings) {
+      const refPath = finding.evidenceRefs?.[0]?.path || "";
+      lines.push(`- [${finding.severity}] ${finding.title}${refPath ? ` · ${refPath}` : ""}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`Safe next action: ${report.summary?.safeNextAction || "Review the evidence before shipping."}`);
+  return lines.join("\n");
+}
+
+function formatObservabilityRecoveryGuardStatusLineFromReport(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Observability guard: NOT RUN · run observability-recovery-guard";
+  }
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+  return `Observability guard: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()}`
+    + ` · warn=${counts.warn}`
+    + ` · block=${counts.block}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review observability evidence."}`;
+}
+
+function buildObservabilityRecoveryGuardSurface(cwd = process.cwd(), options = {}) {
+  const report = loadObservabilityRecoveryGuard(cwd) || (options.buildIfMissing ? buildObservabilityRecoveryGuard(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      blockerCount: 0,
+      needsReviewCount: 0,
+      surfacesInspected: 0,
+      nextBestAction: "Run the observability-recovery-guard before trusting deployment confidence.",
+      statusLine: "Observability guard: NOT RUN · run observability-recovery-guard",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: [
+        "Local static scan only. No external observability API calls.",
+      ],
+    };
+  }
+
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+
+  return {
+    status: report.status,
+    blockerCount: counts.block,
+    needsReviewCount: counts.warn,
+    surfacesInspected: report.surfaceEvidence?.surfacesDetected?.length || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatObservabilityRecoveryGuardStatusLineFromReport(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: [
+      "Local static scan only. No external observability API calls.",
+      "Absence of evidence stays bounded and reason-coded.",
+    ],
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildObservabilityRecoveryGuard,
+  generateObservabilityRecoveryGuard,
+  loadObservabilityRecoveryGuard,
+  formatObservabilityRecoveryGuardText,
+  formatObservabilityRecoveryGuardStatusLineFromReport,
+  buildObservabilityRecoveryGuardSurface,
+};