avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/artifact-receipt-hygiene.js

@@ -0,0 +1,619 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.artifactReceiptHygiene.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/artifact-receipt-hygiene";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const MAX_FILES = 1500;
+const MAX_FINDINGS = 25;
+const MAX_EVIDENCE_REFS_PER_FINDING = 3;
+const MAX_ARTIFACT_SIZE = 256 * 1024; // 256KB
+const OVERSIZED_THRESHOLD = 128 * 1024; // 128KB considered oversized for a single artifact
+const STALE_DAYS = 90;
+
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "coverage", ".next", ".nuxt", ".turbo", ".wasp", "temp",
+]);
+
+// Matches a Windows drive path (C:\ or C:/dir) but NOT a URL scheme like
+// http://, https://, postgresql://, wuz:// — a URL has `://` (two slashes after
+// the colon) and is never an absolute LOCAL path. Excluding it 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})/;
+const SECRET_ASSIGNMENT_RE = /(?:api[_ -]?key|token|password|secret|authorization|credentials?)\s*[:=]\s*["']?[^\s'"]{8,}/i;
+const RAW_LOG_RE = /(?:\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}[.\d]*Z?\s+(?:ERROR|WARN|INFO|DEBUG|TRACE)\b|\[(?:error|warn|info|debug)\])/i;
+const RAW_PROMPT_RE = /(?:system\s*:\s*(?:you are|as an|act as)|<system>|<human>|<assistant>|Human:|Assistant:|<<SYS>>)/i;
+const RAW_TRANSCRIPT_RE = /(?:^\s*(?:Human|Assistant|User|System)\s*:\s*.{20,}$)/m;
+const RAW_CODE_DUMP_RE = /(?:"(?:sourceCode|rawCode|codeContent|fullSource)"\s*:\s*"[\s\S]{500,}")/;
+const PUBLIC_CLAIM_RE = /(?:"publicClaimAllowed"\s*:\s*true)/;
+const VALUE_FIELDS = ["measured", "estimated", "heuristic", "unavailable"];
+const UNSAFE_PUBLIC_CLAIM_RE = /(?:guaranteed|production.ready|guaranteed.secure|guaranteed.savings|launch.ready|published.verified|certified|marketplace|auto.install)/i;
+
+// A claim term is only an UNSUPPORTED public claim when it is asserted as TRUE.
+// The same vocabulary appears constantly in HONEST evidence that DISCLAIMS the
+// claim ("No guaranteed savings claimed", "Does not claim production certified",
+// "Not a marketplace", "Do NOT claim published_verified"), in detection-term
+// lists, and as snake_case enum/identifier values (e.g. `published_verified`,
+// `noGuaranteedRecallClaim`). Flagging those is a false positive — and rewording
+// honest disclaimers to dodge the regex would REDUCE honesty. This context check
+// preserves the original intent (catch positive overclaims) while skipping
+// negated / disclaimed / technical-identifier usages.
+// Disclaimer / detection / exclusion / technical-identifier cues. When any of
+// these share the claim term's line (or nearby context), the term is being
+// disclaimed, screened, deferred, or used as an enum — not asserted.
+const CLAIM_DISCLAIMER_RE = /(?:\bno\b|\bnot\b|\bnon\b|\bnever\b|\bwithout\b|\bcannot\b|can't|won't|don't|doesn't|do not|does not|\bavoid(?:ed|s)?\b|deferred|\bdefer\b|\bfalse\b|premature|absent|\bnone\b|forbidden|disallow|blocked|terms ?checked|unsafeterms|screened|blocked copy|\bexamples?\b|not claim|cannot claim|requires?|ready_to_publish|not_available|not included|out of scope|excluded|non-goals?|separate track|no local|do not say|never say|→ ?never|❌)/i;
+
+function hasUnsupportedPublicClaim(text) {
+  if (!text) return false;
+  const re = new RegExp(UNSAFE_PUBLIC_CLAIM_RE.source, "gi");
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const tok = m[0];
+    const start = m.index;
+    const end = start + tok.length;
+    if (tok.includes("_")) continue;                         // snake_case enum/identifier
+    if (/[A-Za-z0-9_]/.test(text[start - 1] || "")) continue; // embedded in a larger word/identifier
+    if (/[A-Za-z0-9_]/.test(text[end] || "")) continue;       // embedded in a larger word/identifier
+    // Context = a bounded window before the match (catches a preceding section
+    // header such as "does not add:" / "What is not included") PLUS the rest of
+    // the current line (catches a same-line trailing qualifier such as
+    // "(no local evidence)" or "| No network |"). Markdown bullets/tables and
+    // exclusion lists carry the disclaimer in one of these two places.
+    let lineEnd = text.indexOf("\n", end);
+    if (lineEnd === -1) lineEnd = text.length;
+    const before = text.slice(Math.max(0, start - 160), start);
+    const restOfLine = text.slice(end, Math.min(lineEnd, end + 120));
+    if (CLAIM_DISCLAIMER_RE.test(before + " " + restOfLine)) continue; // disclaimed / screened / deferred / technical
+    return true;                                              // a positive, asserted public claim
+  }
+  return false;
+}
+
+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;
+    return (Date.now() - d.getTime()) > (STALE_DAYS * 24 * 60 * 60 * 1000);
+  } catch {
+    return false;
+  }
+}
+
+// ── Walk artifact directories ───────────────────────────────────────────────
+
+function walkArtifactDirs(cwd) {
+  const roots = [
+    "artifacts",
+    ".claude/cco/reports",
+    ".claude/cco/state",
+    "docs/dogfood",
+    "docs/releases",
+  ];
+
+  const files = [];
+  for (const root of roots) {
+    const absRoot = path.join(cwd, root);
+    if (!fs.existsSync(absRoot)) continue;
+    walkDir(absRoot, cwd, files, 5);
+  }
+  return files;
+}
+
+function walkDir(dirPath, cwd, files, maxDepth) {
+  if (maxDepth <= 0 || files.length >= MAX_FILES) return;
+  try {
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+      if (files.length >= MAX_FILES) return;
+      const absPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walkDir(absPath, cwd, files, maxDepth - 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(".json") && !entry.name.endsWith(".md")) continue;
+      const relPath = toPosix(path.relative(cwd, absPath));
+      try {
+        const stat = fs.statSync(absPath);
+        files.push({ absPath, relPath, size: stat.size });
+      } catch {
+        files.push({ absPath, relPath, size: 0 });
+      }
+    }
+  } catch {}
+}
+
+// ── Core analysis ───────────────────────────────────────────────────────────
+
+function buildArtifactReceiptHygieneReport(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 files = walkArtifactDirs(cwd);
+
+  if (files.length === 0) {
+    const emptyReport = buildEmptyReport(limitsApplied);
+    if (options.write !== false) {
+      safeWriteJson(cwd, REPORT_JSON_REL, emptyReport);
+    }
+    return emptyReport;
+  }
+
+  if (files.length >= MAX_FILES) {
+    limitsApplied.push("SCAN_LIMIT_APPLIED");
+    addFinding("warn", "ARTIFACT_HYGIENE_REVIEW_REQUIRED", `Artifact file count reached scan limit (${MAX_FILES})`, "Review artifact directories manually — some files were not inspected.", []);
+  }
+
+  let staleCount = 0;
+  let missingSchemaCount = 0;
+  let unsafeCount = 0;
+  let oversizedCount = 0;
+  let brokenRefCount = 0;
+  let artifactsInspected = 0;
+
+  for (const file of files) {
+    // Skip very large files
+    if (file.size > MAX_ARTIFACT_SIZE) {
+      addFinding("warn", "ARTIFACT_OVERSIZED", `Artifact ${file.relPath} is ${Math.round(file.size / 1024)}KB — exceeds inspection limit`, "Consider splitting or compacting this artifact.", [makeEvidenceRef(file.relPath, "oversized")]);
+      oversizedCount++;
+      continue;
+    }
+
+    // Skip non-JSON for structured checks (md files get text checks only)
+    if (file.relPath.endsWith(".md")) {
+      artifactsInspected++;
+      try {
+        const content = fs.readFileSync(file.absPath, "utf8");
+
+        // Check for absolute paths
+        if (ABSOLUTE_WINDOWS_PATH_RE.test(content) || ABSOLUTE_UNIX_PATH_RE.test(content)) {
+          addFinding("block", "ARTIFACT_ABSOLUTE_PATH_FOUND", `Absolute local path found in ${file.relPath}`, "Replace with repo-relative paths.", [makeEvidenceRef(file.relPath, "absolute path")]);
+          unsafeCount++;
+        }
+
+        // Check for secret patterns
+        if (SECRET_PATTERN_RE.test(content) || SECRET_ASSIGNMENT_RE.test(content)) {
+          addFinding("block", "ARTIFACT_SECRET_PATTERN_FOUND", `Secret-like pattern found in ${file.relPath}`, "Remove or redact secret values.", [makeEvidenceRef(file.relPath, "secret")]);
+          unsafeCount++;
+        }
+
+        // Check for unsafe public claims (asserted, not disclaimed)
+        if (hasUnsupportedPublicClaim(content)) {
+          addFinding("block", "ARTIFACT_PUBLIC_CLAIM_UNSUPPORTED", `Unsupported public claim found in ${file.relPath}`, "Remove or qualify the claim with evidence and caveats.", [makeEvidenceRef(file.relPath, "unsupported claim")]);
+          unsafeCount++;
+        }
+
+        // Check for raw prompts
+        if (RAW_PROMPT_RE.test(content)) {
+          addFinding("block", "ARTIFACT_RAW_PROMPT_FOUND", `Raw prompt/system message found in ${file.relPath}`, "Remove raw prompts from artifacts.", [makeEvidenceRef(file.relPath, "raw prompt")]);
+          unsafeCount++;
+        }
+
+        // Check for oversized threshold
+        if (file.size > OVERSIZED_THRESHOLD) {
+          addFinding("warn", "ARTIFACT_OVERSIZED", `Artifact ${file.relPath} is ${Math.round(file.size / 1024)}KB`, "Consider compacting this artifact.", [makeEvidenceRef(file.relPath, "large")]);
+          oversizedCount++;
+        }
+      } catch {}
+      continue;
+    }
+
+    // JSON artifact checks
+    if (!file.relPath.endsWith(".json")) continue;
+
+    let data;
+    try {
+      const raw = fs.readFileSync(file.absPath, "utf8").replace(/^/, "");
+      data = JSON.parse(raw);
+      artifactsInspected++;
+    } catch {
+      continue;
+    }
+
+    // Check schemaVersion
+    if (!data.schemaVersion) {
+      addFinding("warn", "ARTIFACT_SCHEMA_MISSING", `Artifact ${file.relPath} has no schemaVersion`, "Add schemaVersion to the artifact.", [makeEvidenceRef(file.relPath, "missing schema")]);
+      missingSchemaCount++;
+    } else {
+      addFinding("info", "ARTIFACT_SCHEMA_FOUND", `Schema '${data.schemaVersion}' found in ${file.relPath}`, "No action needed.", [makeEvidenceRef(file.relPath, data.schemaVersion)]);
+    }
+
+    // Check generatedAt
+    if (data.generatedAt) {
+      addFinding("info", "ARTIFACT_GENERATED_AT_FOUND", `generatedAt present in ${file.relPath}`, "No action needed.", [makeEvidenceRef(file.relPath, "timestamp")]);
+      if (isStaleDate(data.generatedAt)) {
+        addFinding("warn", "ARTIFACT_STALE", `Artifact ${file.relPath} generatedAt is older than ${STALE_DAYS} days`, "Re-generate the artifact.", [makeEvidenceRef(file.relPath, "stale")]);
+        staleCount++;
+      }
+    } else if (data.schemaVersion) {
+      // Only warn about missing generatedAt on schema-versioned artifacts
+      addFinding("warn", "ARTIFACT_GENERATED_AT_MISSING", `Schema-versioned artifact ${file.relPath} has no generatedAt`, "Add generatedAt timestamp.", [makeEvidenceRef(file.relPath, "no timestamp")]);
+    }
+
+    // Stringify and check content
+    const rawContent = JSON.stringify(data);
+
+    // Absolute paths
+    if (ABSOLUTE_WINDOWS_PATH_RE.test(rawContent) || ABSOLUTE_UNIX_PATH_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_ABSOLUTE_PATH_FOUND", `Absolute local path found in ${file.relPath}`, "Replace with repo-relative paths.", [makeEvidenceRef(file.relPath, "absolute path")]);
+      unsafeCount++;
+    }
+
+    // Secret patterns
+    if (SECRET_PATTERN_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_SECRET_PATTERN_FOUND", `Secret-like token found in ${file.relPath}`, "Remove or redact secret values.", [makeEvidenceRef(file.relPath, "secret")]);
+      unsafeCount++;
+    }
+
+    // Raw logs
+    if (RAW_LOG_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_RAW_LOG_FOUND", `Raw log entries found in ${file.relPath}`, "Remove raw logs from artifacts.", [makeEvidenceRef(file.relPath, "raw log")]);
+      unsafeCount++;
+    }
+
+    // Raw prompts
+    if (RAW_PROMPT_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_RAW_PROMPT_FOUND", `Raw prompt/system message found in ${file.relPath}`, "Remove raw prompts from artifacts.", [makeEvidenceRef(file.relPath, "raw prompt")]);
+      unsafeCount++;
+    }
+
+    // Raw transcript
+    if (RAW_TRANSCRIPT_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_RAW_TRANSCRIPT_FOUND", `Raw transcript found in ${file.relPath}`, "Remove raw transcripts from artifacts.", [makeEvidenceRef(file.relPath, "raw transcript")]);
+      unsafeCount++;
+    }
+
+    // Raw code dump
+    if (RAW_CODE_DUMP_RE.test(rawContent)) {
+      addFinding("block", "ARTIFACT_RAW_CODE_FOUND", `Raw source code dump found in ${file.relPath}`, "Remove raw code from artifacts.", [makeEvidenceRef(file.relPath, "raw code")]);
+      unsafeCount++;
+    }
+
+    // Unsupported public claim
+    if (PUBLIC_CLAIM_RE.test(rawContent)) {
+      // Check if there's evidence backing it
+      const hasProof = data.valueProof && (data.valueProof.measured === true || data.valueProof.dogfooded === true);
+      if (!hasProof) {
+        addFinding("block", "ARTIFACT_PUBLIC_CLAIM_UNSUPPORTED", `publicClaimAllowed=true without proof support in ${file.relPath}`, "Set publicClaimAllowed to false or add proof evidence.", [makeEvidenceRef(file.relPath, "unsupported claim")]);
+        unsafeCount++;
+      }
+    }
+
+    // Value label check
+    if (data.valueProof && typeof data.valueProof === "object") {
+      const mt = data.valueProof.measurementType;
+      if (!mt || !VALUE_FIELDS.includes(mt)) {
+        addFinding("warn", "ARTIFACT_VALUE_LABEL_MISSING", `Missing or unknown measurementType in ${file.relPath}`, "Add measurementType: measured|estimated|heuristic|unavailable.", [makeEvidenceRef(file.relPath, "value label")]);
+      }
+    }
+
+    // Broken evidence refs
+    if (Array.isArray(data.valueProof?.evidenceRefs)) {
+      for (const ref of data.valueProof.evidenceRefs.slice(0, 5)) {
+        const refPath = String(ref || "").split(" (")[0].split(":")[0];
+        if (refPath && !refPath.startsWith("[") && !fs.existsSync(path.join(cwd, refPath))) {
+          addFinding("warn", "ARTIFACT_BROKEN_EVIDENCE_REF", `Broken evidence ref '${sanitizeText(refPath, 80)}' in ${file.relPath}`, "Update or remove the broken reference.", [makeEvidenceRef(file.relPath, `broken: ${refPath}`)]);
+          brokenRefCount++;
+        }
+      }
+    }
+
+    // Redaction check
+    if (data.redacted === false || (data.privacy && data.privacy.redacted === false)) {
+      addFinding("warn", "ARTIFACT_REDACTION_MISSING", `Artifact ${file.relPath} is not marked as redacted`, "Set redacted: true or ensure content is redacted.", [makeEvidenceRef(file.relPath, "not redacted")]);
+    }
+
+    // Oversized
+    if (file.size > OVERSIZED_THRESHOLD) {
+      addFinding("warn", "ARTIFACT_OVERSIZED", `Artifact ${file.relPath} is ${Math.round(file.size / 1024)}KB`, "Consider compacting this artifact.", [makeEvidenceRef(file.relPath, "large")]);
+      oversizedCount++;
+    }
+
+    // Unsafe public text claim (asserted, not disclaimed)
+    if (hasUnsupportedPublicClaim(rawContent)) {
+      addFinding("block", "ARTIFACT_PUBLIC_CLAIM_UNSUPPORTED", `Unsupported public claim text found in ${file.relPath}`, "Remove or qualify the claim.", [makeEvidenceRef(file.relPath, "unsupported claim text")]);
+      unsafeCount++;
+    }
+  }
+
+  // ── 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, prompts, logs, code dumps, or unsupported claims from artifacts before sharing."
+    : hasWarn
+      ? "Review stale, oversized, or schema-missing artifacts and update accordingly."
+      : "Artifacts and receipts are clean. Safe to proceed.";
+
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      title: "Local Artifact & Receipt Hygiene Guard",
+      text: `${artifactsInspected} artifacts inspected. ${staleCount} stale, ${missingSchemaCount} missing schema, ${unsafeCount} unsafe, ${oversizedCount} oversized.`,
+      findingCounts: { info: infoCount, warn: warnCount, block: blockCount },
+      safeNextAction,
+    },
+    surfaceEvidence: {
+      filesInspected: files.length,
+      artifactsInspected,
+      capabilitiesInspected: 0,
+      limitsApplied,
+    },
+    hygieneCounts: {
+      artifactsInspected,
+      staleCount,
+      missingSchemaCount,
+      unsafeCount,
+      oversizedCount,
+      brokenRefCount,
+    },
+    findings: findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity)),
+    productHome: {
+      cardSource: "artifact-receipt-hygiene",
+      status,
+      found: findings.filter(f => f.severity === "warn" || f.severity === "block").map(f => sanitizeText(f.title, 120)).slice(0, 5),
+      fixedOrPrepared: [],
+      savedOrProved: unsafeCount === 0 && staleCount === 0 ? ["Artifacts and receipts are clean and redacted"] : [],
+      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, "artifact hygiene report")].filter(Boolean),
+      caveat: "Hygiene checks are pattern-based. No exhaustive secret scanning or content 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: "Local Artifact & Receipt Hygiene Guard",
+      text: "No artifacts or receipts found.",
+      findingCounts: { info: 0, warn: 0, block: 0 },
+      safeNextAction: "No artifacts available. Run commands that generate artifacts first.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      capabilitiesInspected: 0,
+      limitsApplied,
+    },
+    hygieneCounts: {
+      artifactsInspected: 0,
+      staleCount: 0,
+      missingSchemaCount: 0,
+      unsafeCount: 0,
+      oversizedCount: 0,
+      brokenRefCount: 0,
+    },
+    findings: [],
+    productHome: {
+      cardSource: "artifact-receipt-hygiene",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "No artifacts 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 generateArtifactReceiptHygiene(cwd = process.cwd(), options = {}) {
+  const report = buildArtifactReceiptHygieneReport(cwd, options);
+  return { report, reportPath: path.join(cwd, REPORT_JSON_REL) };
+}
+
+function loadArtifactReceiptHygiene(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function formatArtifactReceiptHygieneText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Local Artifact & Receipt Hygiene Guard",
+      "Status: NO DATA",
+      "No artifacts or receipts found yet.",
+      "Safe next action: Run commands that generate artifacts first.",
+    ].join("\n");
+  }
+
+  const hc = report.hygieneCounts || {};
+  const lines = [
+    "Avorelo Local Artifact & Receipt Hygiene Guard",
+    `Status: ${String(report.status || "no_data").toUpperCase()} · redacted=${report.redacted === true ? "yes" : "no"}`,
+    `Artifacts: ${hc.artifactsInspected || 0} · stale=${hc.staleCount || 0} · missing-schema=${hc.missingSchemaCount || 0} · unsafe=${hc.unsafeCount || 0} · oversized=${hc.oversizedCount || 0}`,
+    "Notes: local static scan only · no auto-fix · no raw dump",
+  ];
+
+  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 artifact hygiene."}`);
+  return lines.join("\n");
+}
+
+function formatArtifactReceiptHygieneStatusLine(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Artifact hygiene: NOT RUN · run `avorelo artifact-hygiene --text`";
+  }
+  const hc = report.hygieneCounts || {};
+  return `Artifact hygiene: ${String(report.status || "no_data").toUpperCase()}`
+    + ` · artifacts=${hc.artifactsInspected || 0}`
+    + ` · unsafe=${hc.unsafeCount || 0}`
+    + ` · stale=${hc.staleCount || 0}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review artifact hygiene."}`;
+}
+
+function buildArtifactReceiptHygieneSurface(cwd = process.cwd(), options = {}) {
+  const report = loadArtifactReceiptHygiene(cwd) || (options.buildIfMissing ? buildArtifactReceiptHygieneReport(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      artifactsInspected: 0,
+      unsafeCount: 0,
+      staleCount: 0,
+      nextBestAction: "Run `avorelo artifact-hygiene --text` to check artifact hygiene.",
+      statusLine: "Artifact hygiene: NOT RUN · run `avorelo artifact-hygiene --text`",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: ["Local pattern-based scan only. No exhaustive secret scanning."],
+    };
+  }
+
+  const hc = report.hygieneCounts || {};
+  return {
+    status: report.status,
+    artifactsInspected: hc.artifactsInspected || 0,
+    unsafeCount: hc.unsafeCount || 0,
+    staleCount: hc.staleCount || 0,
+    oversizedCount: hc.oversizedCount || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatArtifactReceiptHygieneStatusLine(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: ["Local pattern-based scan only. No exhaustive secret scanning."],
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildArtifactReceiptHygieneReport,
+  generateArtifactReceiptHygiene,
+  loadArtifactReceiptHygiene,
+  formatArtifactReceiptHygieneText,
+  formatArtifactReceiptHygieneStatusLine,
+  buildArtifactReceiptHygieneSurface,
+};