avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/browser-proof-governed-workflow.js

@@ -0,0 +1,1020 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const {
+  buildGovernedActionExposureReport,
+  LATEST_REPORT_REL: BOUNDARY_REPORT_REL,
+} = require("./governed-action-exposure-primitives");
+const { buildBrowserCapabilitySurface } = require("./browser-capability");
+const { VISUAL_QA_REPORT_REL_PATH } = require("./visual-qa");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.browserProofWorkflow.v1";
+const SCHEMA_VERSION = 1;
+const REPORT_DIR_REL = ".claude/cco/reports/browser-proof";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+const RECEIPT_REL = ".claude/cco/evidence/browser-proof/latest-receipt.json";
+const SKILLS_REPORT_REL = ".claude/cco/skills/latest-report.json";
+const WORKSPACE_REPORT_REL = ".claude/cco/orchestration/governed-workspace-hygiene/latest-report.json";
+const LEARNING_REPORT_REL = ".claude/cco/learning-experimentation/latest-report.json";
+const PRODUCTION_CONFIDENCE_REPORT_REL = ".claude/cco/reports/production-confidence/latest-report.json";
+const PROOF_OUTCOME_REL = ".claude/cco/orchestration/seamless-outcome/latest-proof-outcome-evidence.json";
+const DOGFOOD_COMMANDS = Object.freeze([
+  "node bin/avorelo support --json",
+  "node bin/avorelo support --text",
+  "node bin/avorelo outcome-evidence --json",
+  "node bin/avorelo outcome-evidence --text",
+  "node bin/avorelo workspace-hygiene --json",
+  "node bin/avorelo workspace-hygiene --text",
+  "node bin/avorelo learning --json",
+  "node bin/avorelo learning --text",
+  "node bin/avorelo production-confidence --json",
+  "node bin/avorelo production-confidence --text",
+  "node bin/avorelo skills --json",
+  "node bin/avorelo skills --text",
+  "node bin/avorelo boundary --json",
+  "node bin/avorelo boundary --text",
+  "node bin/avorelo browser-proof --json",
+  "node bin/avorelo browser-proof --text",
+  "node bin/avorelo status --text",
+  "node bin/avorelo open --json",
+  "node bin/avorelo package-audit --json",
+  "node bin/avorelo package-smoke --json",
+  "node bin/avorelo install-claims --json",
+  "node bin/avorelo public-distribution --json",
+]);
+
+const PRODUCTION_HOST_SUFFIXES = [
+  ".vercel.app",
+  ".netlify.app",
+  ".onrender.com",
+  ".railway.app",
+  ".herokuapp.com",
+  ".fly.dev",
+  ".pages.dev",
+  ".firebaseapp.com",
+  ".web.app",
+];
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort((left, right) => left.localeCompare(right))
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function hashId(prefix, payload) {
+  return `${prefix}-${sha256(stableStringify(payload)).slice(0, 12)}`;
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function sanitizeText(value, maxChars = 180) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/sk-[A-Za-z0-9_-]{16,}/g, "[redacted-openai-key]")
+    .replace(/gh[ps]_[A-Za-z0-9]{20,}/g, "[redacted-github-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .trim();
+  if (!text) return null;
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+function toRelativePath(cwd, value) {
+  if (!value) return null;
+  const absolute = path.isAbsolute(value) ? value : path.resolve(cwd, value);
+  const relative = path.relative(cwd, absolute).replace(/\\/g, "/");
+  if (!relative || relative === "") return ".";
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return "<outside-repo>";
+  return relative;
+}
+
+function redactUrl(value) {
+  if (!value) return null;
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  if (raw.startsWith("file://")) {
+    return "file://<redacted-local-file>";
+  }
+  const candidate = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  try {
+    const parsed = new URL(candidate);
+    if (isLocalHostname(parsed.hostname)) {
+      const port = parsed.port ? `:${parsed.port}` : "";
+      return `${parsed.protocol}//${parsed.hostname}${port}/<redacted>`;
+    }
+    return `${parsed.protocol}//${parsed.hostname}/<redacted>`;
+  } catch {
+    return sanitizeText(raw, 80) || "<redacted-target>";
+  }
+}
+
+function redactScreenshotPath(relPath) {
+  if (!relPath || relPath === "<outside-repo>") return "<redacted-local-screenshot>";
+  const normalized = relPath.replace(/\\/g, "/");
+  const ext = path.extname(normalized) || ".png";
+  const dir = path.posix.dirname(normalized);
+  return dir && dir !== "."
+    ? `${dir}/<redacted-screenshot>${ext}`
+    : `<redacted-screenshot>${ext}`;
+}
+
+function isLocalHostname(hostname) {
+  const value = String(hostname || "").toLowerCase().replace(/^\[|\]$/g, "");
+  return value === "localhost"
+    || value === "127.0.0.1"
+    || value === "0.0.0.0"
+    || value === "::1";
+}
+
+function isProductionHostname(hostname) {
+  const value = String(hostname || "").toLowerCase();
+  if (!value || isLocalHostname(value)) return false;
+  if (PRODUCTION_HOST_SUFFIXES.some((suffix) => value.endsWith(suffix))) return true;
+  if (/^(prod|production)[.-]/i.test(value)) return true;
+  if (/[.-](prod|production)(?:[.-]|$)/i.test(value)) return true;
+  return false;
+}
+
+function fileUrlToPath(value) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed.startsWith("file://")) return null;
+  try {
+    return decodeURIComponent(trimmed.replace(/^file:\/\//i, ""));
+  } catch {
+    return trimmed.replace(/^file:\/\//i, "");
+  }
+}
+
+function classifyBrowserTarget(cwd, targetInput) {
+  const raw = String(targetInput || "").trim();
+  if (!raw) {
+    return {
+      targetType: "unknown",
+      urlRedacted: null,
+      sourceTrust: "unknown",
+      boundaryDecision: "warn",
+      reasonCodes: ["NO_TARGET_PROVIDED"],
+      hostname: null,
+      localPath: null,
+    };
+  }
+
+  const filePathFromUrl = fileUrlToPath(raw);
+  if (filePathFromUrl) {
+    const localPath = toRelativePath(cwd, filePathFromUrl);
+    return {
+      targetType: "local_file",
+      urlRedacted: "file://<redacted-local-file>",
+      sourceTrust: "trusted",
+      boundaryDecision: "warn",
+      reasonCodes: ["LOCAL_FILE_TARGET"],
+      hostname: null,
+      localPath,
+    };
+  }
+
+  const directLocalPath = (() => {
+    const maybePath = path.isAbsolute(raw)
+      || raw.startsWith(".")
+      || raw.startsWith("/")
+      || /^[A-Za-z]:[\\/]/.test(raw);
+    if (!maybePath) return null;
+    const resolved = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+    return fs.existsSync(resolved) ? resolved : null;
+  })();
+  if (directLocalPath) {
+    return {
+      targetType: "local_file",
+      urlRedacted: "file://<redacted-local-file>",
+      sourceTrust: "trusted",
+      boundaryDecision: "warn",
+      reasonCodes: ["LOCAL_FILE_TARGET"],
+      hostname: null,
+      localPath: toRelativePath(cwd, directLocalPath),
+    };
+  }
+
+  const candidate = /^https?:\/\//i.test(raw)
+    ? raw
+    : /^(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1)(:\d+)?(\/|$)/i.test(raw)
+      ? `http://${raw}`
+      : raw;
+
+  try {
+    const parsed = new URL(candidate);
+    const hostname = String(parsed.hostname || "").toLowerCase();
+    if (isLocalHostname(hostname)) {
+      return {
+        targetType: "localhost",
+        urlRedacted: redactUrl(candidate),
+        sourceTrust: "trusted",
+        boundaryDecision: "warn",
+        reasonCodes: ["LOCALHOST_TARGET"],
+        hostname,
+        localPath: null,
+      };
+    }
+    if (isProductionHostname(hostname)) {
+      return {
+        targetType: "production_url",
+        urlRedacted: redactUrl(candidate),
+        sourceTrust: "unknown",
+        boundaryDecision: "block",
+        reasonCodes: ["PRODUCTION_URL_DETECTED"],
+        hostname,
+        localPath: null,
+      };
+    }
+    return {
+      targetType: "external_url",
+      urlRedacted: redactUrl(candidate),
+      sourceTrust: "unknown",
+      boundaryDecision: "approval_required",
+      reasonCodes: ["EXTERNAL_URL_TARGET"],
+      hostname,
+      localPath: null,
+    };
+  } catch {
+    return {
+      targetType: "unknown",
+      urlRedacted: sanitizeText(raw, 80) || "<redacted-target>",
+      sourceTrust: "unknown",
+      boundaryDecision: "warn",
+      reasonCodes: ["TARGET_CLASSIFICATION_UNKNOWN"],
+      hostname: null,
+      localPath: null,
+    };
+  }
+}
+
+function readEvidenceFile(evidenceFile) {
+  try {
+    if (!evidenceFile) return null;
+    const raw = fs.readFileSync(evidenceFile, "utf8").replace(/^\uFEFF/, "");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeEvidence(cwd, options = {}) {
+  const fileEvidence = readEvidenceFile(options.evidenceFile);
+  const inline = options.evidence && typeof options.evidence === "object" ? options.evidence : {};
+  const visualQa = safeReadJson(cwd, VISUAL_QA_REPORT_REL_PATH, null);
+  const merged = {
+    ...(fileEvidence && typeof fileEvidence === "object" ? fileEvidence : {}),
+    ...inline,
+  };
+
+  const target = String(options.target || merged.target || merged.url || visualQa?.target || "").trim() || null;
+  const screenshot = merged.screenshot && typeof merged.screenshot === "object"
+    ? merged.screenshot
+    : visualQa?.screenshotsCaptured
+      ? {
+        path: visualQa.evidenceStoredAt || null,
+        localOnly: true,
+        capturedAt: visualQa.generatedAt || null,
+      }
+      : null;
+  const visualHint = merged.visualHint && typeof merged.visualHint === "object"
+    ? merged.visualHint
+    : visualQa
+      ? {
+        checked: true,
+        pageRendered: visualQa.screenshotsCaptured === true,
+        obviousFailure: Array.isArray(visualQa.lookedBrokenOrRisky) && visualQa.lookedBrokenOrRisky.length > 0,
+        summary: Array.isArray(visualQa.lookedBrokenOrRisky) && visualQa.lookedBrokenOrRisky.length > 0
+          ? visualQa.lookedBrokenOrRisky[0]
+          : visualQa.screenshotsCaptured
+            ? "Local screenshot-backed visual hint is available."
+            : "Visual QA runner metadata exists, but no screenshot proof was captured.",
+      }
+      : null;
+
+  return {
+    target,
+    reachability: merged.reachability && typeof merged.reachability === "object" ? merged.reachability : null,
+    dom: merged.dom && typeof merged.dom === "object" ? merged.dom : null,
+    console: merged.console && typeof merged.console === "object" ? merged.console : null,
+    network: merged.network && typeof merged.network === "object" ? merged.network : null,
+    screenshot,
+    visualHint,
+    workflowIntent: merged.workflowIntent && typeof merged.workflowIntent === "object" ? merged.workflowIntent : {},
+    evidenceFileUsed: options.evidenceFile ? toRelativePath(cwd, options.evidenceFile) : null,
+    visualQaUsed: visualQa ? VISUAL_QA_REPORT_REL_PATH : null,
+  };
+}
+
+function detectSkillsBrowserGate(skillsReport) {
+  const selected = Array.isArray(skillsReport?.routing?.selected) ? skillsReport.routing.selected : [];
+  const phrases = selected.flatMap((item) => [
+    item?.id,
+    ...(Array.isArray(item?.verificationGates) ? item.verificationGates : []),
+    ...(Array.isArray(item?.evidenceRequirements) ? item.evidenceRequirements : []),
+  ]).filter(Boolean).join(" \n ");
+  const required = /\b(browser|runtime|frontend|ui|dom|console|network|screenshot|visual)\b/i.test(phrases);
+  return {
+    required,
+    reasonCodes: required ? ["SKILL_BROWSER_VERIFICATION_GATE"] : [],
+    refs: skillsReport ? [SKILLS_REPORT_REL] : [],
+  };
+}
+
+function loadIntegrationReports(cwd) {
+  return {
+    skillsReport: safeReadJson(cwd, SKILLS_REPORT_REL, null),
+    workspaceReport: safeReadJson(cwd, WORKSPACE_REPORT_REL, null),
+    learningReport: safeReadJson(cwd, LEARNING_REPORT_REL, null),
+    productionReport: safeReadJson(cwd, PRODUCTION_CONFIDENCE_REPORT_REL, null),
+    boundaryReport: safeReadJson(cwd, BOUNDARY_REPORT_REL, null),
+  };
+}
+
+function buildBrowserCapabilityRisk(cwd) {
+  try {
+    const surface = buildBrowserCapabilitySurface(cwd);
+    return surface || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildBoundaryCandidates(classification, evidence, skillsGate) {
+  const baseScope = classification.targetType === "local_file"
+    ? {
+      paths: classification.localPath ? [classification.localPath] : [],
+      visibility: "repo_internal",
+    }
+    : classification.hostname
+      ? {
+        domains: [classification.hostname],
+        visibility: classification.targetType === "localhost"
+          ? "local_only"
+          : classification.targetType === "production_url"
+            ? "production_deploy"
+            : "browser_external",
+      }
+      : {};
+  const sourceTrust = classification.sourceTrust;
+  const candidates = [
+    {
+      id: "browser-reachability",
+      actionType: "browser_action",
+      browserActionCategory: "page_reachability_check",
+      browserTargetType: classification.targetType,
+      intent: "Review whether the local page can be reached.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+    {
+      id: "browser-dom",
+      actionType: "browser_action",
+      browserActionCategory: "dom_presence_check",
+      browserTargetType: classification.targetType,
+      intent: "Review whether bounded DOM evidence is present.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+    {
+      id: "browser-console",
+      actionType: "browser_action",
+      browserActionCategory: "console_summary_check",
+      browserTargetType: classification.targetType,
+      intent: "Review whether bounded browser console evidence is clean.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+    {
+      id: "browser-network",
+      actionType: "browser_action",
+      browserActionCategory: "network_summary_check",
+      browserTargetType: classification.targetType,
+      intent: "Review whether bounded local network evidence is clean.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+    {
+      id: "browser-screenshot",
+      actionType: "browser_action",
+      browserActionCategory: "screenshot_reference",
+      browserTargetType: classification.targetType,
+      intent: "Review whether a local redacted screenshot reference is safe to include.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+    {
+      id: "browser-visual-hint",
+      actionType: "browser_action",
+      browserActionCategory: "visual_hint",
+      browserTargetType: classification.targetType,
+      intent: "Review whether a bounded local visual hint can be included without overclaiming.",
+      sourceTrust,
+      requestedScope: baseScope,
+    },
+  ];
+
+  if (classification.targetType === "external_url") {
+    candidates.push({
+      id: "browser-external-request",
+      actionType: "browser_action",
+      browserActionCategory: "external_browse_request",
+      browserTargetType: classification.targetType,
+      intent: "Model an external browser browse request only.",
+      sourceTrust,
+      requestedScope: baseScope,
+    });
+  }
+  if (classification.targetType === "production_url") {
+    candidates.push({
+      id: "browser-production-request",
+      actionType: "browser_action",
+      browserActionCategory: "production_browse",
+      browserTargetType: classification.targetType,
+      intent: "Model a production browser request only.",
+      sourceTrust,
+      requestedScope: baseScope,
+    });
+  }
+  if (evidence.workflowIntent?.credentialFlow === true || evidence.workflowIntent?.loginFlow === true) {
+    candidates.push({
+      id: "browser-credential-flow",
+      actionType: "browser_action",
+      browserActionCategory: "credential_flow",
+      browserTargetType: classification.targetType,
+      intent: "Model a credential or login flow only.",
+      sourceTrust,
+      requestedScope: baseScope,
+      skillBinding: skillsGate.required
+        ? { verificationGates: ["Browser verification gate is active."], sourceTrust }
+        : undefined,
+    });
+  }
+  if (evidence.workflowIntent?.formSubmit === true) {
+    candidates.push({
+      id: "browser-form-submit",
+      actionType: "browser_action",
+      browserActionCategory: "form_submit",
+      browserTargetType: classification.targetType,
+      intent: "Model a form submit flow only.",
+      sourceTrust,
+      requestedScope: baseScope,
+    });
+  }
+  return candidates;
+}
+
+function strongestDecision(decisions) {
+  const order = {
+    allow: 0,
+    warn: 1,
+    auto_limit: 2,
+    approval_required: 3,
+    block: 4,
+  };
+  return (decisions || []).reduce((current, next) =>
+    order[next] > order[current] ? next : current, "allow");
+}
+
+function summarizeTargetDecision(classification, boundaryDecisions) {
+  const relevantDecisions = (boundaryDecisions || []).filter((decision) =>
+    decision
+    && !["browser-screenshot", "browser-visual-hint"].includes(decision.id));
+  const strongest = strongestDecision(relevantDecisions.map((decision) => decision.decision));
+  if (strongest === "allow" && classification.boundaryDecision && classification.boundaryDecision !== "warn") {
+    return classification.boundaryDecision;
+  }
+  return strongest === "allow"
+    ? (classification.targetType === "unknown" ? "warn" : "allow")
+    : strongest;
+}
+
+function summarizeConsole(consoleEvidence) {
+  if (!consoleEvidence || consoleEvidence.checked !== true) {
+    return { checked: false, criticalCount: 0, warningCount: 0, headline: "No bounded console summary is available." };
+  }
+  const criticalCount = Number(consoleEvidence.criticalCount || consoleEvidence.errorCount || 0);
+  const warningCount = Number(consoleEvidence.warningCount || 0);
+  const headline = criticalCount > 0
+    ? `${criticalCount} critical console issue(s) detected.`
+    : warningCount > 0
+      ? `${warningCount} console warning(s) detected.`
+      : "No critical console issues detected.";
+  return { checked: true, criticalCount, warningCount, headline };
+}
+
+function summarizeNetwork(networkEvidence) {
+  if (!networkEvidence || networkEvidence.checked !== true) {
+    return { checked: false, criticalCount: 0, warningCount: 0, headline: "No bounded network summary is available." };
+  }
+  const criticalCount = Number(networkEvidence.criticalCount || networkEvidence.failureCount || 0);
+  const warningCount = Number(networkEvidence.warningCount || 0);
+  const headline = criticalCount > 0
+    ? `${criticalCount} critical network issue(s) detected.`
+    : warningCount > 0
+      ? `${warningCount} network warning(s) detected.`
+      : "No critical network issues detected.";
+  return { checked: true, criticalCount, warningCount, headline };
+}
+
+function summarizeDom(domEvidence) {
+  if (!domEvidence || domEvidence.checked !== true) {
+    return { checked: false, selector: null, found: false, headline: "No bounded DOM evidence is available." };
+  }
+  const selector = sanitizeText(domEvidence.selector || domEvidence.signal || "", 80);
+  const found = domEvidence.found === true || domEvidence.present === true;
+  const headline = found
+    ? selector ? `DOM signal found for ${selector}.` : "DOM signal found."
+    : selector ? `DOM signal missing for ${selector}.` : "DOM signal is missing.";
+  return { checked: true, selector, found, headline };
+}
+
+function buildScreenshotRef(cwd, screenshot) {
+  if (!screenshot || !screenshot.path) return null;
+  const relPath = toRelativePath(cwd, screenshot.path);
+  return {
+    pathRef: redactScreenshotPath(relPath),
+    localOnly: true,
+    capturedAt: sanitizeText(screenshot.capturedAt || null, 60),
+    redacted: true,
+  };
+}
+
+function buildCheck(checkType, state, confidence, evidenceRefs, reasonCodes) {
+  return {
+    id: hashId("browser-check", { checkType, state, evidenceRefs, reasonCodes }),
+    checkType,
+    state,
+    confidence,
+    evidenceRefs: unique(evidenceRefs),
+    reasonCodes: unique(reasonCodes),
+    redacted: true,
+  };
+}
+
+function stateFromBoundary(decision) {
+  if (decision === "block") return "blocked";
+  if (decision === "approval_required") return "approval_required";
+  return null;
+}
+
+function evaluateReachabilityCheck(classification, evidence, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("reachability", governed, "none", evidenceRefs, reasonCodes);
+  if (!classification.targetType || classification.targetType === "unknown") {
+    return buildCheck("reachability", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "TARGET_NOT_RESOLVED"]);
+  }
+  if (classification.targetType === "local_file") {
+    const exists = classification.localPath && classification.localPath !== "<outside-repo>";
+    return buildCheck("reachability", exists ? "pass" : "fail", exists ? "high" : "medium", evidenceRefs, [
+      ...reasonCodes,
+      exists ? "LOCAL_FILE_PRESENT" : "LOCAL_FILE_MISSING",
+    ]);
+  }
+  if (!evidence || evidence.checked !== true) {
+    return buildCheck("reachability", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "REACHABILITY_NOT_CAPTURED"]);
+  }
+  if (evidence.reachable === true) {
+    return buildCheck("reachability", "pass", "high", evidenceRefs, [...reasonCodes, "TARGET_REACHABLE"]);
+  }
+  return buildCheck("reachability", "fail", "medium", evidenceRefs, [...reasonCodes, "TARGET_UNREACHABLE"]);
+}
+
+function evaluateDomCheck(domSummary, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("dom", governed, "none", evidenceRefs, reasonCodes);
+  if (!domSummary.checked) {
+    return buildCheck("dom", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "DOM_EVIDENCE_MISSING"]);
+  }
+  if (domSummary.found) {
+    return buildCheck("dom", "pass", "medium", evidenceRefs, [...reasonCodes, "DOM_SIGNAL_FOUND"]);
+  }
+  return buildCheck("dom", "warn", "low", evidenceRefs, [...reasonCodes, "DOM_SIGNAL_MISSING"]);
+}
+
+function evaluateConsoleCheck(consoleSummary, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("console", governed, "none", evidenceRefs, reasonCodes);
+  if (!consoleSummary.checked) {
+    return buildCheck("console", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "CONSOLE_EVIDENCE_MISSING"]);
+  }
+  if (consoleSummary.criticalCount > 0) {
+    return buildCheck("console", "fail", "high", evidenceRefs, [...reasonCodes, "CONSOLE_CRITICAL_ERRORS"]);
+  }
+  if (consoleSummary.warningCount > 0) {
+    return buildCheck("console", "warn", "medium", evidenceRefs, [...reasonCodes, "CONSOLE_WARNINGS_PRESENT"]);
+  }
+  return buildCheck("console", "pass", "high", evidenceRefs, [...reasonCodes, "CONSOLE_CLEAN"]);
+}
+
+function evaluateNetworkCheck(networkSummary, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("network", governed, "none", evidenceRefs, reasonCodes);
+  if (!networkSummary.checked) {
+    return buildCheck("network", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "NETWORK_EVIDENCE_MISSING"]);
+  }
+  if (networkSummary.criticalCount > 0) {
+    return buildCheck("network", "fail", "high", evidenceRefs, [...reasonCodes, "NETWORK_CRITICAL_FAILURES"]);
+  }
+  if (networkSummary.warningCount > 0) {
+    return buildCheck("network", "warn", "medium", evidenceRefs, [...reasonCodes, "NETWORK_WARNINGS_PRESENT"]);
+  }
+  return buildCheck("network", "pass", "high", evidenceRefs, [...reasonCodes, "NETWORK_CLEAN"]);
+}
+
+function evaluateScreenshotCheck(screenshotRef, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("screenshot", governed, "none", evidenceRefs, reasonCodes);
+  if (!screenshotRef) {
+    return buildCheck("screenshot", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "SCREENSHOT_REFERENCE_MISSING"]);
+  }
+  return buildCheck("screenshot", "pass", "low", evidenceRefs, [...reasonCodes, "LOCAL_SCREENSHOT_REFERENCE_REDACTED"]);
+}
+
+function evaluateVisualHintCheck(visualHint, boundaryDecision, evidenceRefs, reasonCodes) {
+  const governed = stateFromBoundary(boundaryDecision);
+  if (governed) return buildCheck("visual_hint", governed, "none", evidenceRefs, reasonCodes);
+  if (!visualHint || visualHint.checked !== true) {
+    return buildCheck("visual_hint", "not_enough_evidence", "none", evidenceRefs, [...reasonCodes, "VISUAL_HINT_MISSING"]);
+  }
+  if (visualHint.obviousFailure === true) {
+    return buildCheck("visual_hint", "warn", "low", evidenceRefs, [...reasonCodes, "VISUAL_HINT_FAILURE"]);
+  }
+  if (visualHint.pageRendered === true) {
+    return buildCheck("visual_hint", "pass", "low", evidenceRefs, [...reasonCodes, "VISUAL_HINT_RENDERED"]);
+  }
+  return buildCheck("visual_hint", "warn", "low", evidenceRefs, [...reasonCodes, "VISUAL_HINT_NEEDS_REVIEW"]);
+}
+
+function buildProofReceipt(cwd, classification, checks, screenshotRef, consoleSummary, networkSummary, domSummary) {
+  const receipt = {
+    receiptId: hashId("browser-proof-receipt", {
+      targetType: classification.targetType,
+      checks: checks.map((check) => [check.checkType, check.state, check.reasonCodes]),
+    }),
+    generatedAt: nowIso(),
+    targetType: classification.targetType,
+    checksIncluded: checks.map((check) => check.checkType),
+    screenshotRef,
+    consoleSummary: {
+      checked: consoleSummary.checked,
+      criticalCount: consoleSummary.criticalCount,
+      warningCount: consoleSummary.warningCount,
+      headline: consoleSummary.headline,
+    },
+    networkSummary: {
+      checked: networkSummary.checked,
+      criticalCount: networkSummary.criticalCount,
+      warningCount: networkSummary.warningCount,
+      headline: networkSummary.headline,
+    },
+    domSummary: {
+      checked: domSummary.checked,
+      selector: domSummary.selector,
+      found: domSummary.found,
+      headline: domSummary.headline,
+    },
+    redacted: true,
+  };
+  safeWriteJson(cwd, RECEIPT_REL, receipt);
+  return receipt;
+}
+
+function summarizeChecks(cwd, checks, targetType, targetDecision) {
+  const counts = {
+    allowedChecks: 0,
+    approvalRequired: 0,
+    blocked: 0,
+    proofsCreated: 0,
+    consoleIssues: 0,
+    networkIssues: 0,
+    domIssues: 0,
+    screenshotsCaptured: 0,
+  };
+
+  checks.forEach((check) => {
+    if (["pass", "warn", "fail", "not_enough_evidence"].includes(check.state)) counts.allowedChecks += 1;
+    if (check.state === "approval_required") counts.approvalRequired += 1;
+    if (check.state === "blocked") counts.blocked += 1;
+    if (check.checkType === "console" && ["warn", "fail"].includes(check.state)) counts.consoleIssues += 1;
+    if (check.checkType === "network" && ["warn", "fail"].includes(check.state)) counts.networkIssues += 1;
+    if (check.checkType === "dom" && ["warn", "fail", "not_enough_evidence"].includes(check.state)) counts.domIssues += 1;
+    if (check.checkType === "screenshot" && check.state === "pass") counts.screenshotsCaptured += 1;
+  });
+
+  counts.proofsCreated = fs.existsSync(path.join(cwd, RECEIPT_REL)) ? 1 : 0;
+  const passChecks = checks.filter((check) => check.state === "pass").length;
+  const hasIssues = checks.some((check) => ["warn", "fail", "approval_required", "blocked", "not_enough_evidence"].includes(check.state));
+  let safeNextAction = "Run `avorelo browser-proof --text` after collecting bounded local browser evidence.";
+  if (targetDecision === "block") {
+    safeNextAction = "Keep browser work local-only. Production browsing stays blocked in v1.";
+  } else if (targetDecision === "approval_required") {
+    safeNextAction = "Keep browser work local-first or request explicit approval before external browsing.";
+  } else if (checks.some((check) => check.checkType === "console" && check.state === "fail")) {
+    safeNextAction = "Fix the client-side console error and rerun `avorelo browser-proof --text`.";
+  } else if (checks.some((check) => check.checkType === "network" && check.state === "fail")) {
+    safeNextAction = "Fix the failing local network dependency and rerun `avorelo browser-proof --text`.";
+  } else if (checks.some((check) => check.checkType === "dom" && ["warn", "not_enough_evidence"].includes(check.state))) {
+    safeNextAction = "Capture bounded DOM evidence and rerun `avorelo browser-proof --text`.";
+  } else if (!hasIssues && passChecks >= 4) {
+    safeNextAction = "Keep the proof receipt linked with the UI change and continue the bounded local workflow.";
+  }
+
+  return {
+    browserChecksReviewed: checks.length,
+    localTargetsReviewed: ["localhost", "local_file"].includes(targetType) ? 1 : 0,
+    ...counts,
+    safeNextAction,
+  };
+}
+
+function computeWorkflowStatus(classification, checks, targetDecision) {
+  if (targetDecision === "block") return "fail";
+  if (checks.some((check) => check.state === "fail" || check.state === "blocked")) return "fail";
+  if (classification.targetType === "unknown") return "warn";
+  const required = ["reachability", "dom", "console", "network"];
+  const requiredChecks = required.map((type) => checks.find((check) => check.checkType === type)).filter(Boolean);
+  const allRequiredPass = requiredChecks.length === required.length
+    && requiredChecks.every((check) => check.state === "pass");
+  if (allRequiredPass && targetDecision === "allow") return "pass";
+  return "warn";
+}
+
+function buildIntegrations(cwd, reports, browserCapability) {
+  const refs = (relPath) => fs.existsSync(path.join(cwd, relPath)) ? [relPath] : [];
+  return {
+    boundaryRefs: refs(BOUNDARY_REPORT_REL),
+    skillsRefs: reports.skillsReport ? [SKILLS_REPORT_REL] : [],
+    productionConfidenceRefs: reports.productionReport ? [PRODUCTION_CONFIDENCE_REPORT_REL] : [],
+    workspaceHygieneRefs: unique([
+      ...refs(WORKSPACE_REPORT_REL),
+      browserCapability?.evidenceArtifact || null,
+    ]),
+    outcomeEvidenceRefs: unique([
+      ...refs(RECEIPT_REL),
+      ...refs(PROOF_OUTCOME_REL),
+    ]),
+    learningRefs: reports.learningReport ? [LEARNING_REPORT_REL] : [],
+  };
+}
+
+function buildBrowserProofWorkflow(cwd = process.cwd(), options = {}) {
+  const reports = loadIntegrationReports(cwd);
+  const browserCapability = buildBrowserCapabilityRisk(cwd);
+  const evidence = normalizeEvidence(cwd, options);
+  const classification = classifyBrowserTarget(cwd, evidence.target);
+  const skillsGate = detectSkillsBrowserGate(reports.skillsReport);
+  const boundaryCandidates = buildBoundaryCandidates(classification, evidence, skillsGate);
+  const boundaryReview = buildGovernedActionExposureReport(cwd, {
+    actions: boundaryCandidates,
+    exposures: [],
+    tools: [],
+    integrationOverrides: {
+      workspaceReport: reports.workspaceReport,
+      learningReport: reports.learningReport,
+      productionReport: reports.productionReport,
+      skillsReport: reports.skillsReport,
+    },
+  });
+  const decisionsById = new Map(boundaryReview.decisions.map((decision) => [decision.id, decision]));
+  const screenshotRef = buildScreenshotRef(cwd, evidence.screenshot);
+  const consoleSummary = summarizeConsole(evidence.console);
+  const networkSummary = summarizeNetwork(evidence.network);
+  const domSummary = summarizeDom(evidence.dom);
+
+  const evidenceRefs = unique([
+    evidence.evidenceFileUsed,
+    evidence.visualQaUsed,
+    screenshotRef ? RECEIPT_REL : null,
+  ]);
+  const browserRiskCodes = browserCapability && ["high", "critical"].includes(browserCapability.overallTier)
+    ? ["BROWSER_CAPABILITY_REVIEW_RECOMMENDED"]
+    : [];
+  const skillCodes = skillsGate.reasonCodes;
+  const baseReasonCodes = unique([
+    ...classification.reasonCodes,
+    ...browserRiskCodes,
+    ...skillCodes,
+  ]);
+
+  const checks = [
+    evaluateReachabilityCheck(classification, evidence.reachability, decisionsById.get("browser-reachability")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+    evaluateDomCheck(domSummary, decisionsById.get("browser-dom")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+    evaluateConsoleCheck(consoleSummary, decisionsById.get("browser-console")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+    evaluateNetworkCheck(networkSummary, decisionsById.get("browser-network")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+    evaluateScreenshotCheck(screenshotRef, decisionsById.get("browser-screenshot")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+    evaluateVisualHintCheck(evidence.visualHint, decisionsById.get("browser-visual-hint")?.decision || classification.boundaryDecision, evidenceRefs, baseReasonCodes),
+  ];
+
+  const targetDecision = summarizeTargetDecision(classification, boundaryReview.decisions);
+  const proof = buildProofReceipt(cwd, classification, checks, screenshotRef, consoleSummary, networkSummary, domSummary);
+  const summary = summarizeChecks(cwd, checks, classification.targetType, targetDecision);
+
+  const report = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status: computeWorkflowStatus(classification, checks, targetDecision),
+    redacted: true,
+    summary,
+    target: {
+      targetType: classification.targetType,
+      urlRedacted: classification.urlRedacted,
+      sourceTrust: classification.sourceTrust,
+      boundaryDecision: targetDecision,
+      reasonCodes: unique([
+        ...baseReasonCodes,
+        ...boundaryReview.decisions.flatMap((decision) => decision.reasonCodes || []),
+      ]),
+    },
+    checks,
+    proof: {
+      ...proof,
+      screenshotRef,
+    },
+    policy: {
+      localOnly: true,
+      externalBrowsingDefault: false,
+      productionBrowsingDefault: false,
+      formSubmissionDefault: false,
+      credentialUseDefault: false,
+      browserAutomationUnbounded: false,
+      providerApis: false,
+      upload: false,
+    },
+    integrations: buildIntegrations(cwd, reports, browserCapability),
+    claimSafety: {
+      fullQACertified: false,
+      productionVerified: false,
+      securityGuaranteed: false,
+      externalUserJourneyCompleted: false,
+      visualRegressionCertified: false,
+    },
+    dogfood: {
+      ranOnAvorelo: safeReadJson(cwd, "package.json", {}).name === "avorelo",
+      commands: DOGFOOD_COMMANDS.slice(),
+      summary: "Avorelo can convert bounded local browser evidence into a governed proof receipt without browsing external or production targets.",
+    },
+  };
+
+  return report;
+}
+
+function writeBrowserProofWorkflowReport(cwd, report) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, REPORT_JSON_REL, report);
+  return { jsonPath: REPORT_JSON_REL, receiptPath: RECEIPT_REL };
+}
+
+function generateBrowserProofWorkflow(cwd = process.cwd(), options = {}) {
+  const report = buildBrowserProofWorkflow(cwd, options);
+  const written = writeBrowserProofWorkflowReport(cwd, report);
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "browser_proof_workflow_run",
+      category: "browser_proof",
+      status: report.status,
+      targetType: report.target.targetType,
+      boundaryDecision: report.target.boundaryDecision,
+      proofsCreated: report.summary.proofsCreated,
+      redacted: true,
+    });
+  } catch {}
+  return {
+    report,
+    written: true,
+    jsonPath: written.jsonPath,
+    receiptPath: written.receiptPath,
+  };
+}
+
+function readLatestBrowserProofWorkflowReport(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function summarizeFound(checks) {
+  const found = [];
+  if (checks.some((check) => check.checkType === "reachability" && check.state === "pass")) found.push("page reachable");
+  if (checks.some((check) => check.checkType === "dom" && check.state === "pass")) found.push("DOM signal found");
+  if (checks.some((check) => check.checkType === "console" && check.state === "pass")) found.push("console summary clean");
+  if (checks.some((check) => check.checkType === "network" && check.state === "pass")) found.push("network summary clean");
+  if (checks.some((check) => check.checkType === "screenshot" && check.state === "pass")) found.push("local screenshot reference recorded");
+  return found.length > 0 ? found.join(", ") : "no bounded local browser proof yet";
+}
+
+function summarizeNeedsAttention(checks, report) {
+  const consoleCheck = checks.find((item) => item.checkType === "console");
+  if (consoleCheck && ["warn", "fail"].includes(consoleCheck.state)) return "console issue detected";
+
+  const networkCheck = checks.find((item) => item.checkType === "network");
+  if (networkCheck && ["warn", "fail"].includes(networkCheck.state)) return "network issue detected";
+
+  const domCheck = checks.find((item) => item.checkType === "dom");
+  if (domCheck && ["warn", "fail", "not_enough_evidence"].includes(domCheck.state)) {
+    return "DOM evidence missing or incomplete";
+  }
+
+  const reachabilityCheck = checks.find((item) => item.checkType === "reachability");
+  if (reachabilityCheck && ["warn", "fail", "not_enough_evidence"].includes(reachabilityCheck.state)) {
+    return "page reachability still unproven";
+  }
+
+  const visualHintCheck = checks.find((item) => item.checkType === "visual_hint");
+  if (visualHintCheck && ["warn", "fail", "not_enough_evidence", "approval_required", "blocked"].includes(visualHintCheck.state)) {
+    return "visual hint still needs review";
+  }
+
+  const blockedCheck = checks.find((item) => ["approval_required", "blocked"].includes(item.state));
+  if (blockedCheck) {
+    return blockedCheck.state === "blocked"
+      ? "governed browser action remains blocked"
+      : "explicit approval is still required";
+  }
+
+  return report.summary.safeNextAction;
+}
+
+function formatBrowserProofWorkflowText(report) {
+  return [
+    "Avorelo Browser Proof",
+    `Status: ${String(report.status || "warn").toUpperCase()}`,
+    `Target: ${report.target.targetType}`,
+    `Found: ${summarizeFound(report.checks)}`,
+    `Needs attention: ${summarizeNeedsAttention(report.checks, report)}`,
+    `Proof: ${report.summary.proofsCreated > 0 ? "local receipt created" : "no receipt created"}`,
+    `Safe next action: ${report.summary.safeNextAction}`,
+  ].join("\n");
+}
+
+function buildBrowserProofWorkflowSurface(cwd = process.cwd(), options = {}) {
+  const report = readLatestBrowserProofWorkflowReport(cwd)
+    || (options.buildIfMissing === true ? buildBrowserProofWorkflow(cwd, options) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      showInStatus: true,
+      showInDashboard: true,
+      targetType: "unknown",
+      proofsCreated: 0,
+      browserChecksReviewed: 0,
+      approvalRequired: 0,
+      blocked: 0,
+      nextAction: "Run `avorelo browser-proof --text` to generate the first governed browser proof receipt.",
+      latestReportPath: null,
+      statusLine: "Browser proof: NOT RUN · run `avorelo browser-proof --text`",
+    };
+  }
+
+  const found = summarizeFound(report.checks);
+  const needsAttention = summarizeNeedsAttention(report.checks, report);
+  const headline = report.status === "pass"
+    ? `Browser proof: PASS · ${report.target.targetType} ${found} · proof receipt linked`
+    : `Browser proof: ${String(report.status || "warn").toUpperCase()} · ${report.target.targetType} ${found} · next: ${needsAttention}`;
+
+  return {
+    status: report.status,
+    showInStatus: true,
+    showInDashboard: true,
+    targetType: report.target.targetType,
+    proofsCreated: report.summary.proofsCreated,
+    browserChecksReviewed: report.summary.browserChecksReviewed,
+    approvalRequired: report.summary.approvalRequired,
+    blocked: report.summary.blocked,
+    nextAction: report.summary.safeNextAction,
+    latestReportPath: REPORT_JSON_REL,
+    statusLine: headline,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  REPORT_JSON_REL,
+  RECEIPT_REL,
+  DOGFOOD_COMMANDS,
+  classifyBrowserTarget,
+  buildBrowserProofWorkflow,
+  writeBrowserProofWorkflowReport,
+  generateBrowserProofWorkflow,
+  readLatestBrowserProofWorkflowReport,
+  buildBrowserProofWorkflowSurface,
+  formatBrowserProofWorkflowText,
+};