avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/governed-workspace-hygiene.js

@@ -0,0 +1,946 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const { listCapabilities } = require("./capability-registry");
+const { buildSkillRegistry, GENERATED_SKILL_REGISTRY_REL_PATH } = require("./avorelo-skill-registry");
+const { buildSkillHygiene } = require("./skill-hygiene");
+const { buildMcpToolInventory, INVENTORY_REL } = require("./mcp-tool-inventory");
+const { buildMcpToolRiskReport, RISK_REL } = require("./mcp-tool-risk");
+const { getSource } = require("./source-catalog");
+const { LATEST_RECEIPT_REL_PATH: GOVERNANCE_RECEIPT_REL_PATH } = require("./agent-access-governance");
+const { LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH } = require("./install-intake-risk");
+const { LATEST_REPORT_REL: LEGACY_AI_WORKSPACE_HYGIENE_REL } = require("./ai-workspace-hygiene");
+
+const CONTRACT = "avorelo.governedWorkspaceHygiene.v1";
+const SCHEMA_VERSION = 1;
+const REPORT_DIR_REL = ".claude/cco/orchestration/governed-workspace-hygiene";
+const LATEST_REPORT_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const RELEVANT_FAMILIES = new Set([
+  "ai_workspace_hygiene",
+  "agent_access_governance",
+  "install_intake_risk",
+  "safe_path_engine",
+  "skills_skill_packs",
+  "source_intake",
+  "mcp_tool_governance",
+  "proof_evidence",
+]);
+
+const FIRST_PARTY_MODULES = Object.freeze([
+  "scripts/lib/agent-access-governance.js",
+  "scripts/lib/ai-workspace-hygiene.js",
+  "scripts/lib/governed-workspace-hygiene.js",
+  "scripts/lib/install-intake-risk.js",
+  "scripts/lib/mcp-tool-inventory.js",
+  "scripts/lib/mcp-tool-risk.js",
+  "scripts/lib/outcome-evidence-stack.js",
+  "scripts/lib/source-catalog.js",
+  "scripts/lib/work-control-receipts.js",
+]);
+
+const CONFIG_SOURCE_CANDIDATES = Object.freeze([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".codex/mcp.json",
+  ".cursor/mcp.json",
+  ".mcp.json",
+  "mcp.json",
+  ".openhands/config.json",
+  "package.json",
+  "config/http-hook-policy.json",
+  "config/intel-policy.json",
+  "config/intel-sources.json",
+  "config/pricing-experiment.json",
+  "config/security-intake-policy.json",
+  "config/tier-feature-map.json",
+]);
+
+const DANGEROUS_REASON_CODES = new Set([
+  "BLOCKED_SOURCE",
+  "POLICY_BYPASS",
+  "UNSAFE_AUTO_EXECUTION",
+  "SECRET_ACCESS",
+  "SECRET_CAPABLE_MCP",
+  "DESTRUCTIVE_ACTION",
+]);
+
+const DIMENSION_ORDER = Object.freeze({
+  read: 1,
+  path: 2,
+  write: 3,
+  execution: 3,
+  network: 3,
+  browser: 3,
+  production: 4,
+  secret: 5,
+});
+
+const RISK_MODEL = Object.freeze({
+  dimensions: [
+    "read",
+    "write",
+    "network",
+    "secret",
+    "path",
+    "execution",
+    "browser",
+    "production",
+  ],
+  levels: ["low", "medium", "high", "critical"],
+});
+
+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 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",
+  "node bin/avorelo report --summary",
+]);
+
+function sha256Short(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex").slice(0, 12);
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function fileExists(absPath) {
+  try {
+    return fs.existsSync(absPath);
+  } catch {
+    return false;
+  }
+}
+
+function listDirectories(absPath) {
+  try {
+    return fs.readdirSync(absPath, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  } catch {
+    return [];
+  }
+}
+
+function readJsonFile(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeText(value, max = 160) {
+  if (value === null || value === undefined) return null;
+  const trimmed = String(value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "").trim();
+  if (!trimmed) return null;
+  return trimmed
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/ig, "<redacted-email>")
+    .replace(/\b[A-Za-z]:\\[^\s"']+/g, "<redacted-path>")
+    .replace(/(?:^|[\s(])\/(?:Users|home|root|tmp|var|etc|opt|usr)\/[^\s"')]+/g, " <redacted-path>")
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-token]")
+    .replace(/gh[ps]_[A-Za-z0-9]{10,}/g, "[redacted-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-token]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .slice(0, max);
+}
+
+function sanitizeRelPath(value) {
+  const text = sanitizeText(value, 200);
+  if (!text) return null;
+  return text.replace(/\\/g, "/");
+}
+
+function ownerSponsor(owner, sponsor) {
+  const normalizedOwner = sanitizeText(owner, 80) || "unknown";
+  const normalizedSponsor = sanitizeText(sponsor, 80) || "unknown";
+  return {
+    status: normalizedOwner === "unknown" || normalizedSponsor === "unknown" ? "unknown" : "known",
+    owner: normalizedOwner,
+    sponsor: normalizedSponsor,
+  };
+}
+
+function createInventoryItem(input) {
+  return {
+    id: input.id || `gwh-${input.type || "item"}-${sha256Short([input.type, input.name, input.source].join("|"))}`,
+    type: input.type,
+    name: sanitizeText(input.name, 120) || input.type,
+    source: sanitizeRelPath(input.source) || "local",
+    provenance: sanitizeText(input.provenance, 160) || "local_workspace",
+    trustLevel: input.trustLevel,
+    ownerSponsor: input.ownerSponsor,
+    riskDimensions: unique(input.riskDimensions || ["read"]),
+    riskLevel: input.riskLevel,
+    recommendedDecision: input.recommendedDecision,
+    reasonCodes: unique(input.reasonCodes || []),
+    proofRef: sanitizeRelPath(input.proofRef) || null,
+    safeNextAction: sanitizeText(input.safeNextAction, 220) || defaultSafeNextAction(input.recommendedDecision, input.name),
+    redacted: true,
+  };
+}
+
+function hasHighImpactDimensions(dimensions) {
+  const set = new Set(dimensions || []);
+  return ["write", "network", "secret", "path", "execution", "browser", "production"].some((dimension) => set.has(dimension));
+}
+
+function highestRiskDimension(dimensions) {
+  return unique(dimensions || ["read"])
+    .slice()
+    .sort((left, right) => (DIMENSION_ORDER[right] || 0) - (DIMENSION_ORDER[left] || 0))[0] || "read";
+}
+
+function riskLevelFromDimensions(dimensions) {
+  const topDimension = highestRiskDimension(dimensions);
+  if (topDimension === "secret") return "critical";
+  if (["production", "write", "execution", "browser", "network"].includes(topDimension)) return "high";
+  if (topDimension === "path") return "medium";
+  return "low";
+}
+
+function detectRiskDimensionsFromText(text) {
+  const value = String(text || "");
+  const dimensions = [];
+  if (/\b(write|patch|delete|remove|edit|create|mutate)\b/i.test(value)) dimensions.push("write");
+  if (/\b(exec|execute|shell|powershell|cmd|spawn|subprocess|command)\b/i.test(value)) dimensions.push("execution");
+  if (/\b(fetch|network|http|https|remote|url|webhook)\b/i.test(value)) dimensions.push("network");
+  if (/\b(secret|token|credential|authorization|password|env)\b/i.test(value)) dimensions.push("secret");
+  if (/\b(browser|playwright|chrome|selenium|devtools)\b/i.test(value)) dimensions.push("browser");
+  if (/\b(deploy|publish|release|production|prod)\b/i.test(value)) dimensions.push("production");
+  if (/\b(path|file|folder|directory|repo|filesystem)\b/i.test(value)) dimensions.push("path");
+  if (dimensions.length === 0) dimensions.push("read");
+  return unique(dimensions);
+}
+
+function mapSkillTrustLevel(skill) {
+  if (skill.packId === "avorelo") return "trusted";
+  if (skill.sourceReviewStatus === "trusted" || skill.sourceReviewStatus === "reviewed") return "trusted";
+  if (skill.sourceReviewStatus === "blocked") return "untrusted";
+  if (skill.sourceReviewStatus === "known") return "known";
+  return "unknown";
+}
+
+function defaultSafeNextAction(decision, name) {
+  const target = sanitizeText(name, 80) || "this item";
+  if (decision === "block") return `Keep ${target} blocked by default until its source and scope are reviewed.`;
+  if (decision === "approval_required") return `Review ${target} before granting broader local workspace access.`;
+  if (decision === "auto_limit") return `Keep ${target} limited to redacted local metadata only.`;
+  if (decision === "warn") return `Review ${target} metadata before treating it as fully trusted.`;
+  return `Keep ${target} local-first and redacted.`;
+}
+
+function reasonCodesFromWarningCodes(warnings) {
+  const codes = new Set();
+  for (const warning of warnings || []) {
+    const code = String(warning?.code || "").toLowerCase();
+    if (!code) continue;
+    if (code.includes("policy_bypass")) codes.add("POLICY_BYPASS");
+    if (code.includes("auto_execution")) codes.add("UNSAFE_AUTO_EXECUTION");
+    if (code.includes("hidden_unicode")) codes.add("HIDDEN_UNICODE");
+    if (code.includes("external_script")) codes.add("EXTERNAL_SCRIPT_METADATA_ONLY");
+    if (code.includes("secret")) codes.add("SECRET_ACCESS");
+    if (code.includes("browser")) codes.add("BROWSER_REFERENCE");
+    if (code.includes("mcp")) codes.add("MCP_REFERENCE");
+    if (code.includes("network")) codes.add("NETWORK_REFERENCE");
+  }
+  return Array.from(codes);
+}
+
+function decideGovernance(input) {
+  const reasonCodes = new Set(input.reasonCodes || []);
+  const ownerUnknown = input.ownerSponsor?.status === "unknown";
+  const highImpact = hasHighImpactDimensions(input.riskDimensions);
+  const externalCapability = reasonCodes.has("EXTERNAL_CAPABILITY");
+  const dangerous = Array.from(reasonCodes).some((code) => DANGEROUS_REASON_CODES.has(code));
+
+  let recommendedDecision = "allow";
+
+  if (input.type === "capability" && input.trustLevel === "trusted") {
+    recommendedDecision = (input.provenance || "").includes("metadata_only") ? "auto_limit" : "allow";
+  } else if (input.type === "skill" && input.trustLevel === "trusted" && !dangerous) {
+    recommendedDecision = reasonCodes.has("HIGH_CONTEXT_WEIGHT") ? "warn" : "allow";
+  } else if (input.trustLevel === "untrusted" && (highImpact || dangerous || input.riskLevel === "critical")) {
+    recommendedDecision = "block";
+  } else if (dangerous || (new Set(input.riskDimensions || []).has("secret"))) {
+    recommendedDecision = "block";
+  } else if (highImpact || ownerUnknown || externalCapability) {
+    recommendedDecision = "approval_required";
+  } else if (input.trustLevel === "unknown" || input.riskLevel === "medium" || reasonCodes.has("MISSING_PROVENANCE") || reasonCodes.has("INCOMPLETE_METADATA")) {
+    recommendedDecision = "warn";
+  }
+
+  if (ownerUnknown) reasonCodes.add("OWNER_SPONSOR_UNKNOWN");
+  if (input.trustLevel === "unknown") reasonCodes.add("UNKNOWN_PROVENANCE");
+  if (input.trustLevel === "untrusted") reasonCodes.add("UNTRUSTED_SOURCE");
+
+  return {
+    ...input,
+    recommendedDecision,
+    reasonCodes: Array.from(reasonCodes),
+    safeNextAction: input.safeNextAction || defaultSafeNextAction(recommendedDecision, input.name),
+  };
+}
+
+function capabilityDimensions(entry) {
+  const familyMap = {
+    ai_workspace_hygiene: ["read"],
+    agent_access_governance: ["read"],
+    install_intake_risk: ["read"],
+    safe_path_engine: ["read"],
+    skills_skill_packs: ["read"],
+    source_intake: ["read"],
+    mcp_tool_governance: ["read"],
+    proof_evidence: ["read"],
+  };
+  return familyMap[entry.familyId] || detectRiskDimensionsFromText([entry.shortDescription, entry.familyName, entry.name].join(" "));
+}
+
+function buildCapabilityInventory() {
+  return listCapabilities()
+    .filter((entry) => RELEVANT_FAMILIES.has(entry.familyId))
+    .map((entry) => {
+      const dimensions = capabilityDimensions(entry);
+      const decided = decideGovernance({
+        type: "capability",
+        name: entry.name,
+        source: entry.sourceOfTruth,
+        provenance: entry.familyId === "mcp_tool_governance" || entry.familyId === "install_intake_risk"
+          ? "first_party_capability_metadata_only"
+          : "first_party_capability_registry",
+        trustLevel: "trusted",
+        ownerSponsor: ownerSponsor("Avorelo", "Avorelo local policy"),
+        riskDimensions: dimensions,
+        riskLevel: riskLevelFromDimensions(dimensions),
+        reasonCodes: [entry.familyId.toUpperCase(), "FIRST_PARTY_LOCAL_POLICY"],
+        proofRef: entry.sourceOfTruth,
+        safeNextAction: entry.familyId === "mcp_tool_governance" || entry.familyId === "install_intake_risk"
+          ? `Use ${entry.name} in metadata-only mode until a reviewed local target requires more scope.`
+          : `Keep ${entry.name} limited to reviewed local workspace context.`,
+      });
+      return createInventoryItem({
+        id: `capability-${entry.id}`,
+        ...decided,
+      });
+    });
+}
+
+function buildSkillInventory(cwd) {
+  const registry = buildSkillRegistry(cwd);
+  const hygiene = buildSkillHygiene(registry);
+  const items = registry.skills.map((skill) => {
+    const source = getSource(skill.sourceId || skill.packId);
+    const warningCodes = reasonCodesFromWarningCodes(skill.warnings || []);
+    const provenance = skill.packId === "avorelo"
+      ? "first_party_skill_registry"
+      : source
+        ? "vendor_skillpack_with_reviewed_metadata"
+        : "vendor_skillpack_unknown_provenance";
+    const riskDimensions = unique([
+      "read",
+      warningCodes.includes("NETWORK_REFERENCE") ? "network" : null,
+      warningCodes.includes("BROWSER_REFERENCE") ? "browser" : null,
+      warningCodes.includes("SECRET_ACCESS") ? "secret" : null,
+      warningCodes.includes("MCP_REFERENCE") || warningCodes.includes("EXTERNAL_SCRIPT_METADATA_ONLY") ? "execution" : null,
+    ]);
+    const reasonCodes = unique([
+      ...warningCodes,
+      skill.routeEligible ? "ROUTE_ELIGIBLE" : "ROUTE_DEFERRED",
+      !source && skill.packId !== "avorelo" ? "MISSING_PROVENANCE" : null,
+      skill.sourceReviewStatus === "blocked" ? "BLOCKED_SOURCE" : null,
+      skill.sourceReviewStatus === "deferred" ? "DEFERRED_SOURCE" : null,
+      skill.contextWeight?.label === "high" ? "HIGH_CONTEXT_WEIGHT" : null,
+    ]);
+
+    const decided = decideGovernance({
+      type: "skill",
+      name: skill.name,
+      source: skill.path || GENERATED_SKILL_REGISTRY_REL_PATH,
+      provenance,
+      trustLevel: mapSkillTrustLevel(skill),
+      ownerSponsor: ownerSponsor(
+        source?.owner || (skill.packId === "avorelo" ? "Avorelo" : "unknown"),
+        skill.packId === "avorelo" ? "Avorelo local policy" : source?.name || "unknown"
+      ),
+      riskDimensions,
+      riskLevel: riskLevelFromDimensions(riskDimensions),
+      reasonCodes,
+      proofRef: GENERATED_SKILL_REGISTRY_REL_PATH,
+      safeNextAction: skill.routeEligible
+        ? `Keep ${skill.name} scoped to reviewed local tasks and redacted outputs.`
+        : `Review ${skill.name} source metadata before routing work through it.`,
+    });
+
+    return createInventoryItem({
+      id: `skill-${skill.id}`,
+      ...decided,
+    });
+  });
+
+  return {
+    registry,
+    hygiene,
+    items,
+  };
+}
+
+function buildMcpInventories(cwd) {
+  const inventory = buildMcpToolInventory(cwd);
+  const risk = buildMcpToolRiskReport(cwd, inventory);
+  const serverRiskById = new Map((risk.servers || []).map((entry) => [entry.serverId, entry]));
+
+  const mcpServers = (inventory.servers || []).map((server) => {
+    const serverRisk = serverRiskById.get(server.serverId) || {};
+    const trustLevel = server.trustedSource === "trusted" ? "trusted" : server.trustedSource === "known" ? "known" : "unknown";
+    const reasonCodes = unique([
+      ...(serverRisk.reasonCodes || []),
+      !server.owner || server.owner === "unknown" ? "MISSING_PROVENANCE" : null,
+      server.transport === "http" || server.transport === "sse" ? "EXTERNAL_CAPABILITY" : null,
+    ]);
+    const riskDimensions = unique([
+      "read",
+      ...detectRiskDimensionsFromText([
+        server.transport,
+        server.argsSummary,
+        server.envRefSummary,
+        server.urlRef,
+      ].join(" ")),
+    ]);
+
+    const decided = decideGovernance({
+      type: "mcp_server",
+      name: server.name,
+      source: server.sourceConfigRef || INVENTORY_REL,
+      provenance: "local_mcp_config_reference_only",
+      trustLevel,
+      ownerSponsor: ownerSponsor(server.owner, "workspace operator"),
+      riskDimensions,
+      riskLevel: serverRisk.riskLevel || riskLevelFromDimensions(riskDimensions),
+      reasonCodes,
+      proofRef: INVENTORY_REL,
+    });
+
+    return createInventoryItem({
+      id: `mcp-server-${server.serverId}`,
+      ...decided,
+    });
+  });
+
+  const tools = (risk.tools || []).map((tool) => {
+    const toolText = [tool.name, (tool.reasonCodes || []).join(" ")].join(" ");
+    const riskDimensions = unique([
+      ...detectRiskDimensionsFromText(toolText),
+      tool.reasonCodes?.includes("BROAD_FILESYSTEM_ACCESS") ? "path" : null,
+      tool.reasonCodes?.includes("NETWORK_ACCESS") ? "network" : null,
+      tool.reasonCodes?.includes("AUTH_REQUIRED") || tool.reasonCodes?.includes("TOKEN_OR_ENV_REFERENCE_PRESENT") ? "secret" : null,
+      tool.reasonCodes?.includes("SHELL_COMMAND_CAPABILITY") ? "execution" : null,
+      tool.reasonCodes?.includes("DEPLOY_OR_PROD_ACTION") ? "production" : null,
+    ]);
+    const reasonCodes = unique([
+      ...(tool.reasonCodes || []),
+      tool.riskLevel === "critical" || tool.riskLevel === "high" ? "EXTERNAL_CAPABILITY" : null,
+    ]);
+
+    const decided = decideGovernance({
+      type: "tool",
+      name: tool.name,
+      source: tool.serverId || RISK_REL,
+      provenance: "mcp_tool_metadata_only",
+      trustLevel: "unknown",
+      ownerSponsor: ownerSponsor("unknown", "workspace operator"),
+      riskDimensions,
+      riskLevel: tool.riskLevel || riskLevelFromDimensions(riskDimensions),
+      reasonCodes,
+      proofRef: RISK_REL,
+    });
+
+    return createInventoryItem({
+      id: `tool-${tool.toolId}`,
+      ...decided,
+    });
+  });
+
+  return { inventory, risk, mcpServers, tools };
+}
+
+function buildFirstPartySourceItems() {
+  return FIRST_PARTY_MODULES.map((relPath) => createInventoryItem({
+    id: `source-first-party-${sha256Short(relPath)}`,
+    ...decideGovernance({
+      type: "source",
+      name: path.basename(relPath),
+      source: relPath,
+      provenance: "first_party_module",
+      trustLevel: "trusted",
+      ownerSponsor: ownerSponsor("Avorelo", "Avorelo local policy"),
+      riskDimensions: ["read"],
+      riskLevel: "low",
+      reasonCodes: ["FIRST_PARTY_LOCAL_POLICY"],
+      proofRef: relPath,
+      safeNextAction: `Keep ${path.basename(relPath)} local and reviewed inside the repo.`,
+    }),
+  }));
+}
+
+function sourceMetadataStatus(sourceJson) {
+  if (!sourceJson) return "unknown";
+  if (sourceJson.id && sourceJson.name && sourceJson.license && sourceJson.upstreamCommit) return "known";
+  return "unknown";
+}
+
+function buildVendorSourceItems(cwd, skillRegistry) {
+  const root = path.join(cwd, "vendor", "skillpacks");
+  const locallyReferenced = new Set(
+    (skillRegistry.skills || [])
+      .map((skill) => skill.packId)
+      .filter((packId) => packId && packId !== "avorelo")
+  );
+  return listDirectories(root)
+    .filter((entry) => locallyReferenced.size === 0 || locallyReferenced.has(entry.name))
+    .map((entry) => {
+      const relRoot = sanitizeRelPath(path.join("vendor", "skillpacks", entry.name));
+      const sourceJsonPath = path.join(root, entry.name, "SOURCE.json");
+      const sourceJson = readJsonFile(sourceJsonPath);
+      const sourceCatalogEntry = getSource(entry.name);
+      const hasLicense = fileExists(path.join(root, entry.name, "LICENSE")) || fileExists(path.join(root, entry.name, "LICENSE.md"));
+      const hasScriptsDir = fileExists(path.join(root, entry.name, "scripts"));
+      const trustLevel = sourceCatalogEntry && sourceCatalogEntry.sourceReviewStatus === "reviewed"
+        ? "trusted"
+        : sourceMetadataStatus(sourceJson) === "known" && hasLicense
+          ? "known"
+          : hasScriptsDir && !sourceJson
+            ? "untrusted"
+            : "unknown";
+      const riskDimensions = unique([
+        "read",
+        hasScriptsDir ? "execution" : null,
+      ]);
+      const reasonCodes = unique([
+        sourceCatalogEntry ? "SOURCE_CATALOG_MATCH" : null,
+        sourceJson ? "SOURCE_METADATA_PRESENT" : "MISSING_PROVENANCE",
+        hasLicense ? "LICENSE_PRESENT" : "LICENSE_MISSING",
+        hasScriptsDir ? "EXTERNAL_CAPABILITY" : null,
+        hasScriptsDir && !(sourceJson && /data_only|no_auto_execution/i.test(String(sourceJson.runtimePolicy || sourceJson.notes || "")))
+          ? "UNSAFE_AUTO_EXECUTION"
+          : null,
+      ]);
+
+      const decided = decideGovernance({
+        type: "source",
+        name: sourceCatalogEntry?.name || sourceJson?.name || entry.name,
+        source: relRoot,
+        provenance: sourceCatalogEntry
+          ? "vendor_skillpack_with_catalog_metadata"
+          : sourceJson
+            ? "vendor_skillpack_with_local_metadata"
+            : "vendor_skillpack_unknown_provenance",
+        trustLevel,
+        ownerSponsor: ownerSponsor(sourceCatalogEntry?.owner || sourceJson?.owner, sourceCatalogEntry?.name || sourceJson?.name),
+        riskDimensions,
+        riskLevel: riskLevelFromDimensions(riskDimensions),
+        reasonCodes,
+        proofRef: sanitizeRelPath(path.join(relRoot, "SOURCE.json")) || relRoot,
+        safeNextAction: trustLevel === "trusted"
+          ? `Keep ${entry.name} data-only and reviewed before deeper adaptation.`
+          : `Add or review SOURCE.json and license metadata for ${entry.name} before trusting it.`,
+      });
+
+      return createInventoryItem({
+        id: `source-vendor-${entry.name}`,
+        ...decided,
+      });
+    });
+}
+
+function buildConfigSourceItems(cwd, mcpInventories) {
+  const riskyConfigs = new Set((mcpInventories.mcpServers || []).map((item) => item.source));
+  return CONFIG_SOURCE_CANDIDATES
+    .filter((relPath) => fileExists(path.join(cwd, relPath)))
+    .map((relPath) => {
+      const normalizedPath = sanitizeRelPath(relPath);
+      const isMcpConfig = /\.mcp\.json$|mcp\.json$|\.codex\/mcp\.json$|\.cursor\/mcp\.json$/i.test(normalizedPath);
+      const riskDimensions = isMcpConfig ? ["read", "path"] : ["read"];
+      const reasonCodes = unique([
+        "LOCAL_CONFIG_SOURCE",
+        isMcpConfig ? "EXTERNAL_CAPABILITY" : null,
+        riskyConfigs.has(normalizedPath) ? "MISSING_PROVENANCE" : null,
+      ]);
+      const trustLevel = isMcpConfig ? "unknown" : "known";
+
+      const decided = decideGovernance({
+        type: "source",
+        name: path.basename(normalizedPath),
+        source: normalizedPath,
+        provenance: isMcpConfig ? "local_mcp_config_reference_only" : "local_repo_config",
+        trustLevel,
+        ownerSponsor: ownerSponsor(isMcpConfig ? "unknown" : "Avorelo", isMcpConfig ? "workspace operator" : "Avorelo local policy"),
+        riskDimensions,
+        riskLevel: riskLevelFromDimensions(riskDimensions),
+        reasonCodes,
+        proofRef: normalizedPath,
+        safeNextAction: isMcpConfig
+          ? `Review ${normalizedPath} before trusting any MCP server it references.`
+          : `Keep ${normalizedPath} local and redacted.`,
+      });
+
+      return createInventoryItem({
+        id: `source-config-${sha256Short(normalizedPath)}`,
+        ...decided,
+      });
+    });
+}
+
+function buildSourceInventory(cwd, skillRegistry, mcpInventories) {
+  return [
+    ...buildFirstPartySourceItems(),
+    ...buildVendorSourceItems(cwd, skillRegistry),
+    ...buildConfigSourceItems(cwd, mcpInventories),
+  ];
+}
+
+function createReceipt(item) {
+  return {
+    receiptId: `gwh-receipt-${sha256Short([item.id, item.recommendedDecision, item.source].join("|"))}`,
+    createdAt: nowIso(),
+    decision: item.recommendedDecision,
+    reasonCodes: item.reasonCodes.slice(0, 8),
+    itemId: item.id,
+    itemType: item.type,
+    source: item.source,
+    safeNextAction: item.safeNextAction,
+    redacted: true,
+  };
+}
+
+function summarizeDecision(item) {
+  return {
+    itemId: item.id,
+    itemType: item.type,
+    name: item.name,
+    trustLevel: item.trustLevel,
+    ownerSponsor: item.ownerSponsor,
+    riskDimensions: item.riskDimensions,
+    decision: item.recommendedDecision,
+    reasonCodes: item.reasonCodes.slice(0, 8),
+    safeNextAction: item.safeNextAction,
+    redacted: true,
+  };
+}
+
+function buildGovernanceSection(allItems, receiptRefs) {
+  const decisions = allItems.map(summarizeDecision);
+  const exposureReductions = allItems
+    .filter((item) => item.recommendedDecision === "auto_limit" || item.recommendedDecision === "warn")
+    .slice(0, 12)
+    .map((item) => ({
+      itemId: item.id,
+      reduction: item.recommendedDecision === "auto_limit"
+        ? "metadata_only"
+        : "review_before_auto_use",
+      summary: item.recommendedDecision === "auto_limit"
+        ? `Keep ${item.name} limited to redacted local metadata.`
+        : `Keep ${item.name} visible but not silently trusted.`,
+      redacted: true,
+    }));
+  const approvalBoundaries = allItems
+    .filter((item) => item.recommendedDecision === "approval_required" || item.recommendedDecision === "block")
+    .map((item) => ({
+      itemId: item.id,
+      decision: item.recommendedDecision,
+      summary: item.recommendedDecision === "block"
+        ? `Blocked by default: ${item.name}.`
+        : `Approval required before ${item.name} can expand beyond local redacted review.`,
+      reasonCodes: item.reasonCodes.slice(0, 8),
+      redacted: true,
+    }));
+  const receipts = allItems
+    .filter((item) => item.recommendedDecision !== "allow")
+    .map(createReceipt);
+
+  receiptRefs
+    .filter(Boolean)
+    .forEach((ref) => {
+      receipts.push({
+        receiptId: `gwh-existing-${sha256Short(ref)}`,
+        createdAt: nowIso(),
+        decision: "observed",
+        reasonCodes: ["EXISTING_SAFE_LOCAL_RECEIPT"],
+        itemId: `receipt-${sha256Short(ref)}`,
+        itemType: "source",
+        source: sanitizeRelPath(ref),
+        safeNextAction: "Keep existing local receipts redacted and local-first.",
+        redacted: true,
+      });
+    });
+
+  return {
+    decisions,
+    exposureReductions,
+    approvalBoundaries,
+    receipts,
+  };
+}
+
+function safeNextActionFromSummary(status, summary) {
+  if (status === "fail") {
+    return "Review blocked local sources first and keep workspace exposure reduced to reviewed metadata only.";
+  }
+  if (summary.approvalRequired > 0) {
+    return "Review approval-required capabilities before expanding local workspace access.";
+  }
+  if (summary.unknownSources > 0) {
+    return "Add provenance and owner metadata for unknown local sources before trusting them.";
+  }
+  return "Keep workspace exposure limited to reviewed low-risk local sources and metadata-only scans.";
+}
+
+function collectReceiptRefs(cwd) {
+  const refs = [
+    GOVERNANCE_RECEIPT_REL_PATH,
+    LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+    LEGACY_AI_WORKSPACE_HYGIENE_REL,
+    INVENTORY_REL,
+    RISK_REL,
+    LATEST_REPORT_REL,
+    GENERATED_SKILL_REGISTRY_REL_PATH,
+  ];
+  return refs.filter((relPath) => fileExists(path.join(cwd, relPath)));
+}
+
+function readPackageJson(cwd) {
+  return safeReadJson(cwd, "package.json", {}) || {};
+}
+
+function buildOutcomeReadiness(summary, governance) {
+  const found = [];
+  const needsAttention = [];
+  const savedOrProved = [];
+
+  if (summary.unknownSources > 0) found.push(`${summary.unknownSources} unknown local source(s) need provenance review.`);
+  if (summary.blockedSources > 0) found.push(`${summary.blockedSources} source(s) stay blocked by default.`);
+  if (summary.approvalRequired > 0) found.push(`${summary.approvalRequired} approval boundary suggestion(s) were generated.`);
+
+  if (governance.receipts.length > 0) {
+    savedOrProved.push(`${governance.receipts.length} safe local receipt(s) were prepared.`);
+  }
+  if (summary.approvalRequired > 0) {
+    needsAttention.push(`Review ${summary.approvalRequired} approval-required item(s) before broader tool or source access.`);
+  }
+  if (summary.blockedSources > 0) {
+    needsAttention.push(`Keep ${summary.blockedSources} blocked source(s) out of the active AI workspace until provenance is resolved.`);
+  }
+
+  return {
+    found,
+    fixed: [],
+    savedOrProved,
+    needsAttention,
+  };
+}
+
+function buildDogfoodSection(cwd) {
+  const pkg = readPackageJson(cwd);
+  const ranOnAvorelo = pkg.name === "avorelo";
+  return {
+    ranOnAvorelo,
+    commands: ranOnAvorelo ? DOGFOOD_COMMANDS.slice() : [],
+    summary: ranOnAvorelo
+      ? "Avorelo can inventory and govern its own local AI workspace without uploading data or executing discovered tools."
+      : "Workspace hygiene stays local-first and redacted.",
+  };
+}
+
+function writeGovernedWorkspaceHygieneReport(cwd, report) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, LATEST_REPORT_REL, report);
+  return LATEST_REPORT_REL;
+}
+
+function buildGovernedWorkspaceHygieneReport(cwd, options = {}) {
+  const capabilityItems = buildCapabilityInventory();
+  const skillInventory = buildSkillInventory(cwd);
+  const mcpInventories = buildMcpInventories(cwd);
+  const sourceItems = buildSourceInventory(cwd, skillInventory.registry, mcpInventories);
+  const allItems = [
+    ...capabilityItems,
+    ...skillInventory.items,
+    ...mcpInventories.tools,
+    ...mcpInventories.mcpServers,
+    ...sourceItems,
+  ];
+  const receiptRefs = collectReceiptRefs(cwd);
+  const governance = buildGovernanceSection(allItems, receiptRefs);
+  const unknownSources = sourceItems.filter((item) => item.trustLevel === "unknown").length;
+  const trustedSources = sourceItems.filter((item) => item.trustLevel === "trusted").length;
+  const deferredSources = sourceItems.filter((item) => item.trustLevel === "unknown" && item.recommendedDecision !== "block").length;
+  const blockedSources = sourceItems.filter((item) => item.recommendedDecision === "block").length;
+  const approvalRequired = governance.decisions.filter((item) => item.decision === "approval_required").length;
+  const blockedCount = governance.decisions.filter((item) => item.decision === "block").length;
+  const status = blockedCount > 0 ? "fail" : (approvalRequired > 0 || unknownSources > 0 ? "warn" : "pass");
+
+  const report = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      capabilitiesReviewed: capabilityItems.length,
+      toolsReviewed: mcpInventories.tools.length,
+      skillsReviewed: skillInventory.items.length,
+      mcpServersReviewed: mcpInventories.mcpServers.length,
+      unknownSources,
+      trustedSources,
+      deferredSources,
+      blockedSources,
+      approvalRequired,
+      blockedCount,
+      receiptCount: governance.receipts.length,
+      safeNextAction: safeNextActionFromSummary(status, {
+        unknownSources,
+        approvalRequired,
+        blockedSources,
+      }),
+    },
+    inventory: {
+      capabilities: capabilityItems,
+      skills: skillInventory.items,
+      tools: mcpInventories.tools,
+      mcpServers: mcpInventories.mcpServers,
+      sources: sourceItems,
+    },
+    governance,
+    riskModel: RISK_MODEL,
+    outcomeReadiness: buildOutcomeReadiness({
+      unknownSources,
+      blockedSources,
+      approvalRequired,
+    }, governance),
+    dogfood: buildDogfoodSection(cwd),
+  };
+
+  if (options.writeReport !== false) {
+    writeGovernedWorkspaceHygieneReport(cwd, report);
+  }
+
+  return {
+    report,
+    detail: {
+      skillRegistry: skillInventory.registry,
+      skillHygiene: skillInventory.hygiene,
+      mcpInventory: mcpInventories.inventory,
+      mcpRisk: mcpInventories.risk,
+      receiptRefs,
+    },
+  };
+}
+
+function readLatestGovernedWorkspaceHygieneReport(cwd) {
+  return safeReadJson(cwd, LATEST_REPORT_REL, null);
+}
+
+function buildGovernedWorkspaceHygieneSurface(cwd, options = {}) {
+  const report = readLatestGovernedWorkspaceHygieneReport(cwd)
+    || (options.buildIfMissing ? buildGovernedWorkspaceHygieneReport(cwd, { writeReport: false }).report : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      showInStatus: true,
+      showInDashboard: true,
+      reviewedCount: 0,
+      unknownSources: 0,
+      approvalRequired: 0,
+      blockedSources: 0,
+      receiptCount: 0,
+      nextAction: "Run `avorelo workspace-hygiene --json` to build the first governed workspace report.",
+      latestReportPath: null,
+      statusLine: "Workspace hygiene: NOT RUN · run `avorelo workspace-hygiene --json`",
+    };
+  }
+
+  const statusLine = report.status === "pass"
+    ? `Workspace hygiene: PASS · reviewed local capabilities low-risk · receipts=${report.summary.receiptCount || 0}`
+    : report.status === "fail"
+      ? `Workspace hygiene: FAIL · ${report.summary.blockedSources || 0} blocked source(s) · ${report.summary.approvalRequired || 0} approval boundary suggested`
+      : `Workspace hygiene: WARN · ${report.summary.unknownSources || 0} unknown source(s) · ${report.summary.approvalRequired || 0} approval boundary suggested`;
+
+  return {
+    status: report.status,
+    showInStatus: true,
+    showInDashboard: true,
+    reviewedCount: (report.summary.capabilitiesReviewed || 0) + (report.summary.skillsReviewed || 0) + (report.summary.toolsReviewed || 0),
+    unknownSources: report.summary.unknownSources || 0,
+    approvalRequired: report.summary.approvalRequired || 0,
+    blockedSources: report.summary.blockedSources || 0,
+    receiptCount: report.summary.receiptCount || 0,
+    nextAction: report.summary.safeNextAction,
+    latestReportPath: LATEST_REPORT_REL,
+    statusLine,
+  };
+}
+
+function formatGovernedWorkspaceHygieneText(report, options = {}) {
+  const lines = [
+    "Avorelo Workspace Hygiene",
+    `Status: ${String(report.status || "warn").toUpperCase()}`,
+    `Reviewed: ${report.summary.capabilitiesReviewed} capabilities, ${report.summary.toolsReviewed} tools, ${report.summary.skillsReviewed} skills, ${report.summary.mcpServersReviewed} MCP servers`,
+    `Found: ${report.summary.unknownSources} unknown sources, ${report.summary.approvalRequired} approval boundary suggestions, ${report.summary.blockedSources} blocked sources`,
+    `Needs attention: ${(report.outcomeReadiness.needsAttention || [report.summary.safeNextAction]).slice(0, 2).join(" ") || "None."}`,
+    `Safe next action: ${report.summary.safeNextAction}`,
+  ];
+
+  if (options.debug) {
+    lines.push("");
+    lines.push("Inventory detail:");
+    lines.push(`- Capabilities: ${report.inventory.capabilities.length}`);
+    lines.push(`- Skills: ${report.inventory.skills.length}`);
+    lines.push(`- Tools: ${report.inventory.tools.length}`);
+    lines.push(`- MCP servers: ${report.inventory.mcpServers.length}`);
+    lines.push(`- Sources: ${report.inventory.sources.length}`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+function buildOutcomeEvidenceWorkspaceSignal(cwd) {
+  const report = readLatestGovernedWorkspaceHygieneReport(cwd);
+  if (!report) return null;
+  return {
+    status: report.status,
+    unknownSources: report.summary.unknownSources || 0,
+    blockedSources: report.summary.blockedSources || 0,
+    approvalRequired: report.summary.approvalRequired || 0,
+    receiptCount: report.summary.receiptCount || 0,
+    safeNextAction: report.summary.safeNextAction || null,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_REPORT_REL,
+  RISK_MODEL,
+  DOGFOOD_COMMANDS,
+  buildGovernedWorkspaceHygieneReport,
+  buildGovernedWorkspaceHygieneSurface,
+  readLatestGovernedWorkspaceHygieneReport,
+  writeGovernedWorkspaceHygieneReport,
+  formatGovernedWorkspaceHygieneText,
+  buildOutcomeEvidenceWorkspaceSignal,
+};