avorelo 0.1.0

package/scripts/lib/install-intake-risk.js

@@ -0,0 +1,1037 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const { buildSkillRegistry } = require("./avorelo-skill-registry");
+
+const INSTALL_INTAKE_CONTRACT = "avorelo.installIntakeRisk.v1";
+const INSTALL_INTAKE_SCHEMA_VERSION = 1;
+const LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH = ".claude/cco/security/install-intake/latest-receipt.json";
+const INSTALL_INTAKE_HISTORY_DIR_REL_PATH = ".claude/cco/security/install-intake/history";
+const INSTALL_INTAKE_EVENT_LOG_REL_PATH = ".claude/cco/events/install-intake-risk.jsonl";
+
+const VALID_ITEM_TYPES = new Set([
+  "mcp_server",
+  "mcp_tool",
+  "package_dependency",
+  "dev_dependency",
+  "npm_script",
+  "vscode_extension",
+  "cursor_rule_or_extension",
+  "claude_or_agents_guidance",
+  "gemini_guidance",
+  "copilot_guidance",
+  "connector",
+  "skill_pack",
+  "browser_integration",
+  "unknown",
+]);
+
+const REVIEW_STATUSES = new Set(["reviewed", "known", "unknown", "deferred", "blocked"]);
+const TRUST_LEVELS = new Set(["high", "medium", "low", "unknown"]);
+const RISK_LEVELS = Object.freeze(["low", "medium", "high", "critical"]);
+const RISK_ORDER = Object.freeze({ low: 1, medium: 2, high: 3, critical: 4 });
+const CAPABILITY_FLAGS = new Set(["read", "write", "execute", "network", "browser", "secrets", "deploy", "unknown"]);
+
+const SKIP_DIRS = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".claude",
+]);
+
+const GUIDANCE_FILE_CANDIDATES = Object.freeze([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  path.posix.join(".github", "copilot-instructions.md"),
+]);
+
+const ADAPTER_POLICY_LEAK_MARKERS = Object.freeze([
+  "sourceTrustLevel",
+  "reviewStatus",
+  "The Five-Axis Review",
+  "Write a failing test before writing the code",
+  "source-backed skill/reference inventory",
+]);
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function maxRisk(left, right) {
+  return (RISK_ORDER[left] || 0) >= (RISK_ORDER[right] || 0) ? left : right;
+}
+
+function normalizePathValue(value) {
+  return String(value || "").replace(/\\/g, "/").trim();
+}
+
+function relativeRepoPath(cwd, absolutePath) {
+  return normalizePathValue(path.relative(cwd, absolutePath));
+}
+
+function sanitizeText(value) {
+  return String(value || "")
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-openai-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-github-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]");
+}
+
+function createItemId(parts) {
+  return `intake-${sha256(parts.filter(Boolean).join("|")).slice(0, 12)}`;
+}
+
+function createReceiptPath(cwd, relPath, payload, options = {}) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, relPath, payload);
+  if (options.plan === "pro") {
+    safeWriteJson(cwd, `${INSTALL_INTAKE_HISTORY_DIR_REL_PATH}/${payload.receiptId || sha256(JSON.stringify(payload)).slice(0, 12)}.json`, payload);
+  }
+  const eventPath = path.join(cwd, INSTALL_INTAKE_EVENT_LOG_REL_PATH);
+  fs.mkdirSync(path.dirname(eventPath), { recursive: true });
+  fs.appendFileSync(eventPath, `${JSON.stringify(payload)}\n`, "utf8");
+  return relPath;
+}
+
+function isValidEnum(value, set, fallback) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return set.has(normalized) ? normalized : fallback;
+}
+
+function walkRepo(cwd, visitor, options = {}) {
+  const maxDepth = Number.isFinite(Number(options.maxDepth)) ? Number(options.maxDepth) : 6;
+  function visit(absPath, depth) {
+    if (depth > maxDepth) return;
+    const rel = relativeRepoPath(cwd, absPath);
+    const stat = fs.statSync(absPath);
+    if (stat.isDirectory()) {
+      const base = path.basename(absPath);
+      if (SKIP_DIRS.has(base)) return;
+      for (const entry of fs.readdirSync(absPath, { withFileTypes: true })) {
+        visit(path.join(absPath, entry.name), depth + 1);
+      }
+      return;
+    }
+    visitor(absPath, rel);
+  }
+  visit(cwd, 0);
+}
+
+function findRepoFiles(cwd, predicate, options = {}) {
+  const files = [];
+  walkRepo(cwd, (absPath, relPath) => {
+    if (predicate(absPath, relPath)) files.push({ absPath, relPath });
+  }, options);
+  return files;
+}
+
+function capabilitySet(flags = []) {
+  const deduped = unique(flags.filter((flag) => CAPABILITY_FLAGS.has(flag)));
+  return deduped.length ? deduped : ["unknown"];
+}
+
+function packageReviewStatus(version) {
+  const spec = String(version || "").trim();
+  if (!spec) return "unknown";
+  if (/^(https?:|git\+|git@|github:)/i.test(spec)) return "deferred";
+  if (/^(file:|link:)/i.test(spec)) return "unknown";
+  return "known";
+}
+
+function packageTrustLevel(reviewStatus) {
+  if (reviewStatus === "known") return "medium";
+  if (reviewStatus === "reviewed") return "high";
+  if (reviewStatus === "blocked") return "low";
+  return "unknown";
+}
+
+function guidanceSignals(text) {
+  const signals = [];
+  const value = String(text || "");
+  if (/\b(ignore|bypass|disable|remove)\b[^\n]{0,120}\b(policy|guard|audit|proof|tests?|verification)\b/i.test(value)) {
+    signals.push({ code: "GUIDANCE_POLICY_BYPASS", risk: "high", message: "Guidance includes policy-bypass language." });
+  }
+  if (/\b(auto-?run|run immediately|execute automatically)\b/i.test(value)) {
+    signals.push({ code: "GUIDANCE_AUTO_EXECUTION", risk: "high", message: "Guidance encourages automatic execution." });
+  }
+  if (/\b(secret|token|credential|authorization|cookie|session)\b[^\n]{0,80}\b(access|reuse|read|print|upload)\b/i.test(value)) {
+    signals.push({ code: "GUIDANCE_SECRET_ACCESS", risk: "high", message: "Guidance implies broad secret or session access." });
+  }
+  if (ADAPTER_POLICY_LEAK_MARKERS.some((marker) => value.includes(marker)) && value.length > 1200) {
+    signals.push({ code: "ADAPTER_POLICY_LEAKAGE", risk: "medium", message: "Adapter or guidance file looks too heavy and leaks policy detail." });
+  }
+  return signals;
+}
+
+function browserSignals(text) {
+  const signals = [];
+  const value = String(text || "");
+  if (/https?:\/\/(?!localhost|127\.0\.0\.1|::1)[^\s)'"`]+/i.test(value)) {
+    signals.push({ code: "EXTERNAL_BROWSER_DOMAIN", risk: "medium", message: "External browser domain reference detected." });
+  }
+  if (/\b(cookie|session|localStorage|auth header|authorization)\b/i.test(value)) {
+    signals.push({ code: "BROWSER_SESSION_RISK", risk: "high", message: "Browser guidance references session, cookies, or auth-bearing state." });
+  }
+  if (/\b(browser|playwright|devtools|chrome|edge)\b/i.test(value) && !/localhost|127\.0\.0\.1|local preview/i.test(value)) {
+    signals.push({ code: "NO_LOCAL_PREVIEW_BOUNDARY", risk: "medium", message: "Browser automation is referenced without a local preview boundary." });
+  }
+  return signals;
+}
+
+function packageScriptSignals(name, command) {
+  const signals = [];
+  const text = String(command || "");
+  const lowerName = String(name || "").toLowerCase();
+  if (["preinstall", "postinstall", "prepare"].includes(lowerName)) {
+    signals.push({ code: "INSTALL_SCRIPT_PRESENT", risk: "high", message: `${lowerName} lifecycle script detected.` });
+  }
+  if (/\b(curl|wget|Invoke-WebRequest|Invoke-RestMethod)\b/i.test(text)) {
+    signals.push({ code: "NETWORK_SCRIPT_PRESENT", risk: "high", message: "Lifecycle or package script makes a network request." });
+  }
+  if (/\b(token|secret|credential|authorization|process\.env|echo\s+\$[A-Z_]+)\b/i.test(text)) {
+    signals.push({ code: "SECRET_EXFIL_SCRIPT", risk: "high", message: "Lifecycle or package script references possible secret or env exfiltration." });
+  }
+  if (/\brm\s+-rf\b|\bdel\s+\/s\s+\/q\b|\brmdir\b/i.test(text)) {
+    signals.push({ code: "DESTRUCTIVE_SCRIPT_PRESENT", risk: "critical", message: "Lifecycle or package script includes destructive deletion." });
+  }
+  if (/\b(deploy|publish|release|npm publish|gh release)\b/i.test(text) || /\b(predeploy|deploy|publish)\b/i.test(lowerName)) {
+    signals.push({ code: "DEPLOY_SCRIPT_PRESENT", risk: "high", message: "Lifecycle or package script deploys or publishes." });
+  }
+  return signals;
+}
+
+function packageDependencySignals(name, version) {
+  const signals = [];
+  const spec = String(version || "").trim();
+  if (/^(https?:|git\+|git@|github:)/i.test(spec)) {
+    signals.push({ code: "PACKAGE_NON_REGISTRY_SOURCE", risk: "high", message: `${name} installs from git or HTTP instead of a normal registry spec.` });
+  }
+  if (/^(file:|link:)/i.test(spec)) {
+    signals.push({ code: "PACKAGE_LOCAL_FILE_SOURCE", risk: "medium", message: `${name} installs from a local file or link path.` });
+  }
+  if (/workspace:/i.test(spec)) {
+    signals.push({ code: "PACKAGE_WORKSPACE_SOURCE", risk: "low", message: `${name} uses a local workspace source.` });
+  }
+  return signals;
+}
+
+function detectToolCapabilities(serverOrTool = {}) {
+  const capabilities = [];
+  const text = JSON.stringify(serverOrTool || {});
+  if (serverOrTool.writeCapable === true || /\b(write|patch|delete|mutate|edit|create)\b/i.test(text)) capabilities.push("write");
+  if (serverOrTool.networkCapable === true || /\b(http|https|fetch|network|url)\b/i.test(text)) capabilities.push("network");
+  if (serverOrTool.commandCapable === true || /\b(command|shell|exec|spawn|terminal)\b/i.test(text)) capabilities.push("execute");
+  if (serverOrTool.browserCapable === true || /\b(browser|playwright|chrome|devtools)\b/i.test(text)) capabilities.push("browser");
+  if (serverOrTool.secretCapable === true || /\b(secret|token|credential|env)\b/i.test(text)) capabilities.push("secrets");
+  if (serverOrTool.deployCapable === true || /\b(deploy|publish|release)\b/i.test(text)) capabilities.push("deploy");
+  if (!capabilities.length) capabilities.push("read");
+  return capabilitySet(capabilities);
+}
+
+function mcpSignals(serverOrTool, reviewStatus) {
+  const signals = [];
+  const caps = detectToolCapabilities(serverOrTool);
+  if (reviewStatus === "unknown" || reviewStatus === "deferred") {
+    signals.push({ code: "UNKNOWN_MCP_SOURCE", risk: "high", message: "MCP server or tool is present without reviewed source metadata." });
+  }
+  if (caps.includes("write")) signals.push({ code: "WRITE_CAPABLE_MCP", risk: "high", message: "MCP item appears write-capable." });
+  if (caps.includes("network")) signals.push({ code: "NETWORK_CAPABLE_MCP", risk: "high", message: "MCP item appears network-capable." });
+  if (caps.includes("execute")) signals.push({ code: "COMMAND_CAPABLE_MCP", risk: "high", message: "MCP item appears shell or command-capable." });
+  if (caps.includes("secrets")) signals.push({ code: "SECRET_CAPABLE_MCP", risk: "high", message: "MCP item appears secret-sensitive." });
+  return { caps, signals };
+}
+
+function signalsToRisk(signals = [], fallback = "low") {
+  return signals.reduce((level, signal) => maxRisk(level, signal.risk || "low"), fallback);
+}
+
+function signalsToReasonCodes(signals = []) {
+  return unique(signals.map((signal) => signal.code));
+}
+
+function defaultSafeNextAction(item) {
+  if (item.reviewStatus === "blocked") return "Keep this item blocked until the source or config is intentionally replaced.";
+  if (item.reviewStatus === "deferred" || item.reviewStatus === "unknown") return "Review source, ownership, and scope before relying on this item at runtime.";
+  if (item.riskLevel === "critical" || item.riskLevel === "high") return "Use read-only, no-secrets, or no-network alternatives first and review this item before normal use.";
+  return "Keep this item in the smallest useful reviewed scope and preserve evidence.";
+}
+
+function createItem(input) {
+  const type = isValidEnum(input.type, VALID_ITEM_TYPES, "unknown");
+  const reviewStatus = isValidEnum(input.reviewStatus, REVIEW_STATUSES, "unknown");
+  const trustLevel = isValidEnum(input.trustLevel, TRUST_LEVELS, "unknown");
+  const riskLevel = isValidEnum(input.riskLevel, new Set(RISK_LEVELS), "low");
+  const capabilities = capabilitySet(input.capabilities);
+  const item = {
+    id: input.id || createItemId([type, input.name, input.configPath, input.detectedFrom]),
+    type,
+    name: sanitizeText(input.name || type),
+    source: sanitizeText(input.source || "local"),
+    configPath: normalizePathValue(input.configPath || ""),
+    detectedFrom: sanitizeText(input.detectedFrom || "local_scan"),
+    ownerOrPublisher: sanitizeText(input.ownerOrPublisher || ""),
+    version: sanitizeText(input.version || ""),
+    reviewStatus,
+    trustLevel,
+    riskLevel,
+    capabilities,
+    riskSignals: (input.riskSignals || []).map((signal) => ({
+      code: signal.code,
+      risk: signal.risk,
+      message: sanitizeText(signal.message),
+    })),
+    reasonCodes: unique(input.reasonCodes || signalsToReasonCodes(input.riskSignals || [])),
+    safeNextAction: sanitizeText(input.safeNextAction || defaultSafeNextAction({
+      reviewStatus,
+      riskLevel,
+    })),
+    feedsGovernance: input.feedsGovernance !== false,
+    feedsSafePath: input.feedsSafePath !== false,
+    redacted: true,
+  };
+  return item;
+}
+
+function detectPackageItems(cwd) {
+  const files = findRepoFiles(cwd, (_abs, rel) => path.basename(rel) === "package.json", { maxDepth: 6 });
+  const items = [];
+  const scannedSources = [];
+
+  files.forEach(({ absPath, relPath }) => {
+    let pkg = null;
+    try {
+      pkg = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    } catch {
+      return;
+    }
+    scannedSources.push(relPath);
+    [
+      { key: "dependencies", type: "package_dependency" },
+      { key: "devDependencies", type: "dev_dependency" },
+    ].forEach(({ key, type }) => {
+      const deps = pkg[key] || {};
+      Object.entries(deps).forEach(([name, version]) => {
+        const reviewStatus = packageReviewStatus(version);
+        const riskSignals = packageDependencySignals(name, version);
+        const riskLevel = signalsToRisk(riskSignals, reviewStatus === "known" ? "low" : reviewStatus === "deferred" ? "high" : "medium");
+        const capabilities = [];
+        if (riskSignals.some((signal) => signal.code === "PACKAGE_NON_REGISTRY_SOURCE")) capabilities.push("execute", "network");
+        if (riskSignals.some((signal) => signal.code === "PACKAGE_LOCAL_FILE_SOURCE")) capabilities.push("read", "execute");
+        items.push(createItem({
+          type,
+          name,
+          source: "package_manifest",
+          configPath: relPath,
+          detectedFrom: `${relPath}:${key}`,
+          ownerOrPublisher: name.startsWith("@") ? name.slice(1).split("/")[0] : "",
+          version,
+          reviewStatus,
+          trustLevel: packageTrustLevel(reviewStatus),
+          riskLevel,
+          capabilities,
+          riskSignals,
+          safeNextAction: reviewStatus === "deferred"
+            ? "Review non-registry or git-sourced dependencies before install and prefer a pinned reviewed version."
+            : undefined,
+          feedsGovernance: true,
+          feedsSafePath: true,
+        }));
+      });
+    });
+    const scripts = pkg.scripts || {};
+    Object.entries(scripts).forEach(([name, command]) => {
+      const riskSignals = packageScriptSignals(name, command);
+      const capabilities = capabilitySet([
+        "execute",
+        ...(/curl|wget|Invoke-WebRequest|Invoke-RestMethod/i.test(String(command || "")) ? ["network"] : []),
+        ...(/token|secret|credential|process\.env/i.test(String(command || "")) ? ["secrets"] : []),
+        ...(/deploy|publish|release|npm publish/i.test(String(command || "")) ? ["deploy"] : []),
+      ]);
+      items.push(createItem({
+        type: "npm_script",
+        name,
+        source: "package_manifest",
+        configPath: relPath,
+        detectedFrom: `${relPath}:scripts`,
+        version: "",
+        reviewStatus: "known",
+        trustLevel: "medium",
+        riskLevel: signalsToRisk(riskSignals, "low"),
+        capabilities,
+        riskSignals,
+        safeNextAction: riskSignals.length
+          ? "Review the script before install or runtime use, then prefer dry-run, test-only, or no-network alternatives first."
+          : undefined,
+        feedsGovernance: true,
+        feedsSafePath: true,
+      }));
+    });
+  });
+  return { items, scannedSources };
+}
+
+function parseMcpServers(absPath) {
+  const parsed = safeReadJson(path.dirname(absPath), path.basename(absPath), null);
+  if (!parsed || typeof parsed !== "object") return [];
+  if (parsed.mcpServers && typeof parsed.mcpServers === "object") {
+    return Object.entries(parsed.mcpServers).map(([name, value]) => ({ name, value }));
+  }
+  if (parsed.servers && typeof parsed.servers === "object" && /mcp/i.test(path.basename(absPath))) {
+    return Object.entries(parsed.servers).map(([name, value]) => ({ name, value }));
+  }
+  return [];
+}
+
+function detectMcpItems(cwd) {
+  const files = findRepoFiles(
+    cwd,
+    (_abs, rel) => /mcp/i.test(path.basename(rel)) && /\.(json|ya?ml)$/i.test(rel),
+    { maxDepth: 6 }
+  );
+  const items = [];
+  const scannedSources = [];
+  files.forEach(({ absPath, relPath }) => {
+    scannedSources.push(relPath);
+    const servers = parseMcpServers(absPath);
+    servers.forEach(({ name, value }) => {
+      const reviewStatus = isValidEnum(value.reviewStatus || value.trustStatus || (value.reviewed === true ? "reviewed" : "unknown"), REVIEW_STATUSES, "unknown");
+      const trustLevel = value.reviewed === true ? "high" : reviewStatus === "known" ? "medium" : reviewStatus === "blocked" ? "low" : "unknown";
+      const { caps, signals } = mcpSignals(value, reviewStatus);
+      items.push(createItem({
+        type: "mcp_server",
+        name,
+        source: sanitizeText(value.source || value.command || value.url || "mcp_config"),
+        configPath: relPath,
+        detectedFrom: `${relPath}:mcpServers`,
+        ownerOrPublisher: value.owner || value.publisher || "",
+        version: value.version || "",
+        reviewStatus,
+        trustLevel,
+        riskLevel: signalsToRisk(signals, reviewStatus === "reviewed" ? "medium" : "high"),
+        capabilities: caps,
+        riskSignals: signals,
+        safeNextAction: "Review the MCP server source and owner first, then prefer one reviewed read-only tool scope before wider use.",
+        feedsGovernance: true,
+        feedsSafePath: true,
+      }));
+
+      const tools = Array.isArray(value.tools)
+        ? value.tools.map((tool) => [tool.name || tool.id || "unnamed-tool", tool])
+        : value.tools && typeof value.tools === "object"
+          ? Object.entries(value.tools)
+          : [];
+      tools.forEach(([toolName, toolValue]) => {
+        const toolReviewStatus = isValidEnum(toolValue.reviewStatus || toolValue.trustStatus || reviewStatus, REVIEW_STATUSES, reviewStatus);
+        const { caps: toolCaps, signals: toolSignals } = mcpSignals(toolValue, toolReviewStatus);
+        items.push(createItem({
+          type: "mcp_tool",
+          name: `${name}:${toolName}`,
+          source: sanitizeText(value.source || name),
+          configPath: relPath,
+          detectedFrom: `${relPath}:mcpServers.${name}.tools`,
+          ownerOrPublisher: value.owner || value.publisher || "",
+          version: value.version || "",
+          reviewStatus: toolReviewStatus,
+          trustLevel: toolReviewStatus === "reviewed" ? "high" : toolReviewStatus === "known" ? "medium" : "unknown",
+          riskLevel: signalsToRisk(toolSignals, toolReviewStatus === "reviewed" ? "medium" : "high"),
+          capabilities: toolCaps,
+          riskSignals: toolSignals,
+          safeNextAction: "Review the MCP tool source and scope before runtime use, then prefer the narrowest reviewed tool boundary.",
+          feedsGovernance: true,
+          feedsSafePath: true,
+        }));
+      });
+    });
+  });
+  return { items, scannedSources };
+}
+
+function detectExtensionItems(cwd) {
+  const items = [];
+  const scannedSources = [];
+  const vscodePath = path.join(cwd, ".vscode", "extensions.json");
+  if (fs.existsSync(vscodePath)) {
+    scannedSources.push(".vscode/extensions.json");
+    const payload = safeReadJson(path.join(cwd, ".vscode"), "extensions.json", {});
+    const recommendations = unique([
+      ...((payload.recommendations || []).filter(Boolean)),
+      ...((payload.unwantedRecommendations || []).filter(Boolean)),
+    ]);
+    recommendations.forEach((name) => {
+      const parts = String(name || "").split(".");
+      const hasPublisher = parts.length >= 2;
+      const signals = [];
+      if (!hasPublisher) signals.push({ code: "UNKNOWN_EXTENSION_SOURCE", risk: "high", message: "Extension recommendation is missing a publisher." });
+      if (/\b(browser|playwright|devtools|chrome)\b/i.test(name)) signals.push({ code: "EXTENSION_BROWSER_ACCESS", risk: "medium", message: "Extension likely touches browser or devtools surfaces." });
+      items.push(createItem({
+        type: "vscode_extension",
+        name,
+        source: "vscode_extensions",
+        configPath: ".vscode/extensions.json",
+        detectedFrom: ".vscode/extensions.json",
+        ownerOrPublisher: hasPublisher ? parts[0] : "",
+        reviewStatus: hasPublisher ? "known" : "unknown",
+        trustLevel: hasPublisher ? "medium" : "unknown",
+        riskLevel: signalsToRisk(signals, hasPublisher ? "low" : "medium"),
+        capabilities: /\b(browser|playwright|devtools|chrome)\b/i.test(name) ? ["browser", "network"] : ["unknown"],
+        riskSignals: signals,
+        safeNextAction: "Review the publisher and required workspace access before enabling the extension.",
+      }));
+    });
+  }
+  return { items, scannedSources };
+}
+
+function detectGuidanceItems(cwd) {
+  const items = [];
+  const scannedSources = [];
+  const addGuidanceFile = (relPath, type, source) => {
+    const absPath = path.join(cwd, relPath);
+    if (!fs.existsSync(absPath) || fs.statSync(absPath).isDirectory()) return;
+    const text = fs.readFileSync(absPath, "utf8");
+    const signals = guidanceSignals(text);
+    scannedSources.push(relPath);
+    items.push(createItem({
+      type,
+      name: relPath,
+      source,
+      configPath: relPath,
+      detectedFrom: relPath,
+      reviewStatus: relPath.startsWith(".avorelo/generated/") ? "reviewed" : "known",
+      trustLevel: relPath.startsWith(".avorelo/generated/") ? "high" : "medium",
+      riskLevel: signalsToRisk(signals, "low"),
+      capabilities: capabilitySet([
+        "read",
+        ...(/auto-?run|execute/i.test(text) ? ["execute"] : []),
+        ...(/cookie|session|browser|playwright|devtools/i.test(text) ? ["browser"] : []),
+        ...(/secret|token|credential|authorization/i.test(text) ? ["secrets"] : []),
+        ...(/network|http|https|curl|wget/i.test(text) ? ["network"] : []),
+      ]),
+      riskSignals: signals,
+      safeNextAction: signals.length
+        ? "Keep generated or local guidance thin, remove bypass language, and route core policy through Avorelo rather than adapter files."
+        : undefined,
+      feedsGovernance: false,
+      feedsSafePath: true,
+    }));
+    const browserRiskSignals = browserSignals(text);
+    if (browserRiskSignals.length) {
+      items.push(createItem({
+        type: "browser_integration",
+        name: `${relPath}:browser`,
+        source,
+        configPath: relPath,
+        detectedFrom: relPath,
+        reviewStatus: relPath.startsWith(".avorelo/generated/") ? "reviewed" : "known",
+        trustLevel: relPath.startsWith(".avorelo/generated/") ? "high" : "medium",
+        riskLevel: signalsToRisk(browserRiskSignals, "medium"),
+        capabilities: capabilitySet(["browser", "network"]),
+        riskSignals: browserRiskSignals,
+        safeNextAction: "Prefer localhost preview or reviewed domain boundaries before browser automation uses this guidance.",
+        feedsGovernance: false,
+        feedsSafePath: true,
+      }));
+    }
+  };
+
+  GUIDANCE_FILE_CANDIDATES.forEach((relPath) => {
+    if (relPath.endsWith("GEMINI.md")) addGuidanceFile(relPath, "gemini_guidance", "guidance");
+    else if (relPath.includes("copilot")) addGuidanceFile(relPath, "copilot_guidance", "guidance");
+    else addGuidanceFile(relPath, "claude_or_agents_guidance", "guidance");
+  });
+
+  const cursorRuleFiles = findRepoFiles(cwd, (_abs, rel) => rel.startsWith(".cursor/"), { maxDepth: 5 });
+  cursorRuleFiles.forEach(({ relPath }) => addGuidanceFile(relPath, "cursor_rule_or_extension", "cursor"));
+
+  const generatedGuidance = findRepoFiles(cwd, (_abs, rel) => rel.startsWith(".avorelo/generated/") && /\.(md|mdc|txt)$/i.test(rel), { maxDepth: 6 });
+  generatedGuidance.forEach(({ relPath }) => {
+    const type = /GEMINI/i.test(relPath)
+      ? "gemini_guidance"
+      : /copilot/i.test(relPath)
+        ? "copilot_guidance"
+        : /cursor/i.test(relPath)
+          ? "cursor_rule_or_extension"
+          : "claude_or_agents_guidance";
+    addGuidanceFile(relPath, type, "generated_guidance");
+  });
+
+  const copilotInstructions = findRepoFiles(cwd, (_abs, rel) => rel.startsWith(".github/instructions/") && /\.instructions\.md$/i.test(rel), { maxDepth: 5 });
+  copilotInstructions.forEach(({ relPath }) => addGuidanceFile(relPath, "copilot_guidance", "guidance"));
+
+  return { items, scannedSources };
+}
+
+function detectSkillSourceItems(cwd) {
+  const items = [];
+  const scannedSources = ["skills/avorelo", "vendor/skillpacks", "docs/references/references.json", "scripts/lib/source-catalog.js"];
+  const registry = buildSkillRegistry(cwd);
+  const bySource = new Map();
+  registry.skills.forEach((skill) => {
+    const key = skill.sourceId || skill.packId;
+    if (!bySource.has(key)) {
+      bySource.set(key, {
+        sourceId: key,
+        name: skill.sourceName || key,
+        reviewStatus: skill.sourceReviewStatus,
+        trustLevel: skill.sourceTrustLevel,
+        warnings: [],
+        scripts: [],
+        sourcePath: skill.packId === "avorelo" ? "skills/avorelo" : `vendor/skillpacks/${skill.packId}`,
+      });
+    }
+    const aggregate = bySource.get(key);
+    aggregate.reviewStatus = aggregate.reviewStatus === "blocked" || skill.sourceReviewStatus === "blocked"
+      ? "blocked"
+      : aggregate.reviewStatus === "reviewed" || skill.sourceReviewStatus === "reviewed" || skill.sourceReviewStatus === "trusted"
+        ? "reviewed"
+        : !skill.routeEligible
+          ? "deferred"
+          : aggregate.reviewStatus;
+    aggregate.warnings.push(...(skill.warnings || []));
+    aggregate.scripts.push(...(skill.scripts || []));
+  });
+
+  bySource.forEach((aggregate) => {
+    const riskSignals = [];
+    if (aggregate.reviewStatus === "deferred") {
+      riskSignals.push({ code: "DEFERRED_SKILL_SOURCE", risk: "high", message: "Skill source is deferred and must not be trusted like a reviewed source." });
+    }
+    if (aggregate.reviewStatus === "blocked") {
+      riskSignals.push({ code: "BLOCKED_SKILL_SOURCE", risk: "critical", message: "Skill source is blocked." });
+    }
+    if (aggregate.scripts.length) {
+      riskSignals.push({ code: "SKILL_SCRIPT_METADATA_ONLY", risk: "medium", message: "Skill source references scripts that must remain metadata-only." });
+    }
+    aggregate.warnings.forEach((warning) => {
+      if (warning.code === "unknown_or_unconfirmed_license") {
+        riskSignals.push({ code: "UNKNOWN_SKILL_LICENSE", risk: "high", message: "Skill source license is not confirmed for reuse." });
+      }
+      if (warning.code === "hidden_unicode") {
+        riskSignals.push({ code: "SKILL_HIDDEN_UNICODE", risk: "high", message: "Skill source includes hidden Unicode markers." });
+      }
+      if (warning.code === "policy_bypass_phrase") {
+        riskSignals.push({ code: "SKILL_POLICY_BYPASS", risk: "high", message: "Skill source includes instruction-bypass language." });
+      }
+      if (warning.code === "context_heavy_skill") {
+        riskSignals.push({ code: "SKILL_CONTEXT_HEAVY", risk: "medium", message: "Skill source is context-heavy and should be lazy-loaded." });
+      }
+      if (warning.code === "adapter_leakage_risk") {
+        riskSignals.push({ code: "SKILL_ADAPTER_LEAKAGE", risk: "medium", message: "Skill source is too heavy for thin adapter copying." });
+      }
+    });
+    items.push(createItem({
+      type: "skill_pack",
+      name: aggregate.name,
+      source: aggregate.sourceId,
+      configPath: aggregate.sourcePath,
+      detectedFrom: "skill_registry",
+      reviewStatus: aggregate.reviewStatus === "trusted" ? "reviewed" : aggregate.reviewStatus,
+      trustLevel: aggregate.trustLevel || "unknown",
+      riskLevel: signalsToRisk(riskSignals, aggregate.reviewStatus === "reviewed" ? "low" : aggregate.reviewStatus === "deferred" ? "high" : "medium"),
+      capabilities: capabilitySet(aggregate.scripts.length ? ["read"] : ["read"]),
+      riskSignals,
+      safeNextAction: aggregate.reviewStatus === "reviewed"
+        ? "Use only the reviewed source-backed subset and keep any script references as data-only metadata."
+        : "Do not trust deferred or unknown skill sources at runtime until their source, license, and warnings are reviewed.",
+      feedsGovernance: true,
+      feedsSafePath: true,
+    }));
+  });
+
+  return { items, scannedSources };
+}
+
+function buildReceipt(cwd, items, scannedSources, options = {}) {
+  const sortedItems = items.slice().sort((left, right) => {
+    const risk = (RISK_ORDER[right.riskLevel] || 0) - (RISK_ORDER[left.riskLevel] || 0);
+    if (risk !== 0) return risk;
+    return left.name.localeCompare(right.name);
+  });
+  const summary = {
+    totalItems: sortedItems.length,
+    reviewedItems: sortedItems.filter((item) => item.reviewStatus === "reviewed").length,
+    unknownItems: sortedItems.filter((item) => item.reviewStatus === "unknown").length,
+    deferredItems: sortedItems.filter((item) => item.reviewStatus === "deferred").length,
+    blockedItems: sortedItems.filter((item) => item.reviewStatus === "blocked").length,
+    highRiskItems: sortedItems.filter((item) => item.riskLevel === "high").length,
+    criticalRiskItems: sortedItems.filter((item) => item.riskLevel === "critical").length,
+    itemsFeedingGovernance: sortedItems.filter((item) => item.feedsGovernance).length,
+    itemsFeedingSafePath: sortedItems.filter((item) => item.feedsSafePath).length,
+  };
+  const reasonCounts = new Map();
+  sortedItems.forEach((item) => {
+    item.reasonCodes.forEach((code) => reasonCounts.set(code, (reasonCounts.get(code) || 0) + 1));
+  });
+  const topReasonCodes = Array.from(reasonCounts.entries())
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, 8)
+    .map(([code]) => code);
+  const nextAction = summary.blockedItems > 0
+    ? "Keep blocked intake items out of runtime use and review the highest-risk unknown or deferred sources first."
+    : summary.unknownItems > 0 || summary.deferredItems > 0
+      ? "Review unknown or deferred intake sources before relying on them in governance, Safe Path, or runtime tool use."
+      : summary.highRiskItems > 0
+        ? "Reduce scope around the highest-risk reviewed items and prefer read-only, no-network, or no-secrets alternatives first."
+        : "Keep reviewed intake items scoped narrowly and preserve local evidence.";
+  return {
+    schemaVersion: INSTALL_INTAKE_SCHEMA_VERSION,
+    contract: INSTALL_INTAKE_CONTRACT,
+    receiptId: `intake-${sha256(JSON.stringify({
+      scannedSources,
+      totalItems: summary.totalItems,
+      highRiskItems: summary.highRiskItems,
+      createdAt: nowIso(),
+    })).slice(0, 12)}`,
+    receiptType: "workspace_intake_scan",
+    createdAt: nowIso(),
+    scannedSources: unique(scannedSources),
+    items: sortedItems,
+    summary,
+    topReasonCodes,
+    nextAction,
+    redacted: true,
+    generatedBy: options.generatedBy || "install_intake_scan",
+  };
+}
+
+function appendIntakeEvents(cwd, receipt) {
+  appendProductLearningEvent(cwd, {
+    eventName: "intake_scan_completed",
+    category: "install_intake_risk",
+    status: "pass",
+    payload: {
+      totalItems: receipt.summary.totalItems,
+      unknownItems: receipt.summary.unknownItems,
+      highRiskItems: receipt.summary.highRiskItems,
+    },
+  });
+  if (receipt.summary.unknownItems > 0) {
+    appendProductLearningEvent(cwd, {
+      eventName: "intake_unknown_item_detected",
+      category: "install_intake_risk",
+      status: "warn",
+      payload: { unknownItems: receipt.summary.unknownItems },
+    });
+  }
+  if (receipt.summary.highRiskItems > 0 || receipt.summary.criticalRiskItems > 0) {
+    appendProductLearningEvent(cwd, {
+      eventName: "intake_high_risk_item_detected",
+      category: "install_intake_risk",
+      status: "warn",
+      payload: {
+        highRiskItems: receipt.summary.highRiskItems,
+        criticalRiskItems: receipt.summary.criticalRiskItems,
+      },
+    });
+  }
+  if (receipt.summary.blockedItems > 0) {
+    appendProductLearningEvent(cwd, {
+      eventName: "intake_blocked_item_detected",
+      category: "install_intake_risk",
+      status: "block",
+      payload: { blockedItems: receipt.summary.blockedItems },
+    });
+  }
+  appendProductLearningEvent(cwd, {
+    eventName: "intake_safe_next_action_recommended",
+    category: "install_intake_risk",
+    status: "pass",
+    payload: {
+      nextAction: receipt.nextAction,
+      topReasonCodes: receipt.topReasonCodes.slice(0, 5),
+    },
+  });
+  appendProductLearningEvent(cwd, {
+    eventName: "intake_receipt_written",
+    category: "install_intake_risk",
+    status: "pass",
+    payload: {
+      receiptPath: LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+      totalItems: receipt.summary.totalItems,
+    },
+  });
+  appendProductLearningEvent(cwd, {
+    eventName: "intake_feeds_governance",
+    category: "install_intake_risk",
+    status: "pass",
+    payload: { items: receipt.summary.itemsFeedingGovernance },
+  });
+  appendProductLearningEvent(cwd, {
+    eventName: "intake_feeds_safe_path",
+    category: "install_intake_risk",
+    status: "pass",
+    payload: { items: receipt.summary.itemsFeedingSafePath },
+  });
+}
+
+function scanInstallIntakeRisk(cwd, options = {}) {
+  const packageData = detectPackageItems(cwd);
+  const mcpData = detectMcpItems(cwd);
+  const extensionData = detectExtensionItems(cwd);
+  const guidanceData = detectGuidanceItems(cwd);
+  const skillData = detectSkillSourceItems(cwd);
+
+  const items = [
+    ...packageData.items,
+    ...mcpData.items,
+    ...extensionData.items,
+    ...guidanceData.items,
+    ...skillData.items,
+  ];
+  const receipt = buildReceipt(cwd, items, [
+    ...packageData.scannedSources,
+    ...mcpData.scannedSources,
+    ...extensionData.scannedSources,
+    ...guidanceData.scannedSources,
+    ...skillData.scannedSources,
+  ], {
+    generatedBy: options.generatedBy || "install_intake_scan",
+  });
+
+  let receiptPath = null;
+  if (options.writeReceipt !== false) {
+    receiptPath = createReceiptPath(cwd, LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH, receipt, { plan: options.plan || "free" });
+    appendIntakeEvents(cwd, receipt);
+  }
+
+  return { receipt, receiptPath };
+}
+
+function readLatestInstallIntakeReceipt(cwd) {
+  return safeReadJson(cwd, LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH, null);
+}
+
+function buildInstallIntakeRiskSurface(cwd) {
+  const latestReceipt = readLatestInstallIntakeReceipt(cwd);
+  const source = latestReceipt || scanInstallIntakeRisk(cwd, { writeReceipt: false }).receipt;
+  const status = source.summary.totalItems > 0 ? "foundation" : "partial";
+  return {
+    status,
+    showInStatus: true,
+    showInDashboard: true,
+    latestReceiptPath: latestReceipt ? LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH : null,
+    totalItems: source.summary.totalItems,
+    unknownItems: source.summary.unknownItems,
+    deferredItems: source.summary.deferredItems,
+    blockedItems: source.summary.blockedItems,
+    highRiskItems: source.summary.highRiskItems,
+    criticalRiskItems: source.summary.criticalRiskItems,
+    topReasonCodes: source.topReasonCodes.slice(0, 5),
+    nextAction: source.nextAction,
+    latestReceipt,
+    topRiskyItems: source.items
+      .filter((item) => ["high", "critical"].includes(item.riskLevel) || ["unknown", "deferred", "blocked"].includes(item.reviewStatus))
+      .slice(0, 5)
+      .map((item) => ({
+        id: item.id,
+        type: item.type,
+        name: item.name,
+        reviewStatus: item.reviewStatus,
+        riskLevel: item.riskLevel,
+        reasonCodes: item.reasonCodes.slice(0, 4),
+        safeNextAction: item.safeNextAction,
+      })),
+    statusLine: `Install Intake: ${status.toUpperCase()} · items=${source.summary.totalItems} · unknown=${source.summary.unknownItems} · deferred=${source.summary.deferredItems} · high=${source.summary.highRiskItems} · critical=${source.summary.criticalRiskItems}`,
+  };
+}
+
+function matchItemByName(items, name) {
+  const target = String(name || "").trim().toLowerCase();
+  return items.find((item) => {
+    const itemName = String(item.name || "").trim().toLowerCase();
+    if (itemName === target) return true;
+    if (itemName.endsWith(`:${target}`)) return true;
+    return false;
+  }) || null;
+}
+
+function extractPackageInstallTarget(command) {
+  const text = String(command || "").trim();
+  const match = text.match(/\b(?:npm\s+install|pnpm\s+add|yarn\s+add)\s+([@A-Za-z0-9._/-]+)/i);
+  return match ? match[1] : null;
+}
+
+function buildSubjectFromItem(item) {
+  if (!item) return null;
+  const typeMap = {
+    mcp_server: "mcp_server",
+    mcp_tool: "tool",
+    package_dependency: "package",
+    dev_dependency: "package",
+    npm_script: "package",
+    vscode_extension: "extension",
+    cursor_rule_or_extension: "extension",
+    connector: "connector",
+    skill_pack: "skill",
+    browser_integration: "browser_integration",
+  };
+  const trustMap = {
+    reviewed: "reviewed",
+    known: "known",
+    blocked: "blocked",
+    unknown: "unknown",
+    deferred: "unknown",
+  };
+  return {
+    type: typeMap[item.type] || "unknown",
+    name: item.name,
+    source: item.source,
+    configPath: item.configPath || null,
+    owner: item.ownerOrPublisher || "workspace operator",
+    sponsor: "Avorelo install intake",
+    trustStatus: trustMap[item.reviewStatus] || "unknown",
+  };
+}
+
+function buildToolMetadataFromItem(item) {
+  if (!item) return {};
+  const caps = new Set(item.capabilities || []);
+  return {
+    trusted: item.reviewStatus === "reviewed" || item.reviewStatus === "known",
+    reviewed: item.reviewStatus === "reviewed",
+    unknown: item.reviewStatus === "unknown" || item.reviewStatus === "deferred",
+    blocked: item.reviewStatus === "blocked",
+    writeCapable: caps.has("write"),
+    networkCapable: caps.has("network"),
+    secretSensitive: caps.has("secrets"),
+  };
+}
+
+function buildActionIntakeContext(cwd, input = {}, options = {}) {
+  const result = scanInstallIntakeRisk(cwd, {
+    writeReceipt: options.writeReceipt !== false,
+    plan: options.plan || "free",
+    generatedBy: "guard_intake_scan",
+  });
+  const items = result.receipt.items || [];
+  const actionType = String(input.actionType || "").trim().toLowerCase();
+  const matches = [];
+
+  if (actionType === "tool_call") {
+    const item = matchItemByName(items.filter((entry) => entry.type === "mcp_tool"), input.toolName)
+      || matchItemByName(items.filter((entry) => entry.type === "mcp_server"), input.toolName);
+    if (item) {
+      matches.push(item);
+    } else if (input.toolName) {
+      matches.push(createItem({
+        type: "mcp_tool",
+        name: input.toolName,
+        source: "runtime_target",
+        configPath: "",
+        detectedFrom: "tool_call",
+        reviewStatus: "unknown",
+        trustLevel: "unknown",
+        riskLevel: "high",
+        capabilities: ["execute"],
+        riskSignals: [
+          { code: "UNKNOWN_MCP_SOURCE", risk: "high", message: "Tool target is not present in reviewed local intake." },
+        ],
+        safeNextAction: "Review the tool or MCP source first, then prefer one reviewed read-only tool scope before wider runtime access.",
+        feedsGovernance: true,
+        feedsSafePath: true,
+      }));
+    }
+  }
+  if (actionType === "mcp_tool_call") {
+    const specific = input.mcpServer && input.toolName ? `${input.mcpServer}:${input.toolName}` : input.toolName;
+    const item = matchItemByName(items.filter((entry) => entry.type === "mcp_tool"), specific)
+      || matchItemByName(items.filter((entry) => entry.type === "mcp_server"), input.mcpServer || input.toolName);
+    if (item) {
+      matches.push(item);
+    } else if (specific || input.mcpServer) {
+      matches.push(createItem({
+        type: input.toolName ? "mcp_tool" : "mcp_server",
+        name: specific || input.mcpServer,
+        source: "runtime_target",
+        configPath: "",
+        detectedFrom: "mcp_tool_call",
+        reviewStatus: "unknown",
+        trustLevel: "unknown",
+        riskLevel: "high",
+        capabilities: ["execute"],
+        riskSignals: [
+          { code: "UNKNOWN_MCP_SOURCE", risk: "high", message: "MCP target is not present in reviewed local intake." },
+        ],
+        safeNextAction: "Review the MCP server or tool source first, then keep runtime scope to one reviewed target with no-secrets or no-network alternatives where possible.",
+        feedsGovernance: true,
+        feedsSafePath: true,
+      }));
+    }
+  }
+  if (actionType === "command_run") {
+    const packageName = extractPackageInstallTarget(input.command || input.target);
+    if (packageName) {
+      const item = matchItemByName(items.filter((entry) => entry.type === "package_dependency" || entry.type === "dev_dependency"), packageName);
+      if (item) {
+        matches.push(item);
+      } else {
+        matches.push(createItem({
+          type: "package_dependency",
+          name: packageName,
+          source: "install_command",
+          configPath: "",
+          detectedFrom: "command_run",
+          reviewStatus: "unknown",
+          trustLevel: "unknown",
+          riskLevel: "high",
+          capabilities: ["execute", "network"],
+          riskSignals: [
+            { code: "UNKNOWN_PACKAGE_INSTALL", risk: "high", message: "Package install target is not yet present in local reviewed intake." },
+          ],
+          safeNextAction: "Review the package source first, pin the intended version, inspect install scripts, and keep the install outside secret-bearing contexts.",
+          feedsGovernance: true,
+          feedsSafePath: true,
+        }));
+      }
+    }
+    const scriptNameMatch = String(input.command || "").match(/\bnpm\s+run\s+([A-Za-z0-9:_-]+)/i);
+    if (scriptNameMatch) {
+      const scriptItem = matchItemByName(items.filter((entry) => entry.type === "npm_script"), scriptNameMatch[1]);
+      if (scriptItem) matches.push(scriptItem);
+    }
+  }
+
+  const matchedItems = unique(matches.map((item) => item.id)).map((id) => matches.find((item) => item.id === id)).filter(Boolean);
+  const riskLevel = matchedItems.reduce((level, item) => maxRisk(level, item.riskLevel || "low"), "low");
+  const reasonCodes = unique(matchedItems.flatMap((item) => item.reasonCodes || []));
+  const safeNextAction = matchedItems[0]?.safeNextAction || result.receipt.nextAction;
+  const subject = matchedItems[0] ? buildSubjectFromItem(matchedItems[0]) : null;
+  const toolMetadata = matchedItems[0] ? buildToolMetadataFromItem(matchedItems[0]) : {};
+
+  return {
+    receipt: result.receipt,
+    receiptPath: result.receiptPath || LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+    matchedItems,
+    riskLevel,
+    reasonCodes,
+    safeNextAction,
+    subject,
+    toolMetadata,
+  };
+}
+
+module.exports = {
+  INSTALL_INTAKE_CONTRACT,
+  INSTALL_INTAKE_SCHEMA_VERSION,
+  LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH,
+  INSTALL_INTAKE_HISTORY_DIR_REL_PATH,
+  INSTALL_INTAKE_EVENT_LOG_REL_PATH,
+  scanInstallIntakeRisk,
+  readLatestInstallIntakeReceipt,
+  buildInstallIntakeRiskSurface,
+  buildActionIntakeContext,
+};