avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/capability-intake-quarantine.js

@@ -0,0 +1,789 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.capabilityIntakeQuarantine.v1";
+const REPORT_DIR_REL = ".claude/cco/security/capability-intake";
+const LATEST_REPORT_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const SOURCE_REPORT_REL = ".claude/cco/skills/latest-report.json";
+const BOUNDARY_REPORT_REL = ".claude/cco/security/governed-action-exposure/latest-report.json";
+const AGENT_READINESS_REPORT_REL = ".claude/cco/orchestration/agent-readiness/latest-readiness.json";
+const PRODUCT_HOME_REPORT_REL = ".claude/cco/orchestration/product-home/latest-receipt.json";
+const RADAR_REPORT_REL = ".claude/cco/orchestration/workflow-radar/latest-report.json";
+
+const VALID_TYPES = new Set(["skill", "mcp", "tool", "adapter", "prompt_pack", "unknown"]);
+const VALID_PROVENANCE = new Set(["local", "repo", "package", "external_reference", "unknown"]);
+const VALID_PERMISSIONS = new Set([
+  "read_only",
+  "writes_files",
+  "executes_commands",
+  "network_access",
+  "browser_access",
+  "secrets_or_env",
+  "credentials",
+  "package_install",
+  "production_or_deploy",
+  "unknown",
+]);
+const VALID_INSTRUCTION_RISKS = new Set([
+  "safe_pointer",
+  "broad_agent_instruction",
+  "hidden_automation",
+  "prompt_injection_like",
+  "chain_of_thought_request",
+  "secret_exfiltration_risk",
+  "unsafe_external_action",
+  "unknown",
+]);
+const VALID_DECISIONS = new Set(["allow_local_reference", "allow_prepare_only", "quarantine", "manual_review", "block"]);
+
+const SKIP_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  ".next",
+  ".turbo",
+  ".cache",
+  "dist",
+  "build",
+  "coverage",
+  ".claude",
+]);
+
+const ADAPTER_CANDIDATES = new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".github/copilot-instructions.md",
+  ".codex/config.toml",
+  ".cursor/rules/wuz-project.mdc",
+]);
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function hashId(prefix, value) {
+  return `${prefix}-${sha256(value).slice(0, 12)}`;
+}
+
+function compactText(value, maxChars = 220) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text) return null;
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+function sanitizeText(value, maxChars = 220) {
+  return compactText(
+    String(value || "")
+      .replace(/sk-[A-Za-z0-9_-]{16,}/g, "[redacted-openai-key]")
+      .replace(/gh[pousr]_[A-Za-z0-9]{12,}/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]")
+      .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]"),
+    maxChars
+  );
+}
+
+function normalizePathValue(value) {
+  return String(value || "").replace(/\\/g, "/").replace(/^\.\/+/, "").trim();
+}
+
+function toRedactedRef(cwd, value) {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  if (/^https?:\/\//i.test(raw)) {
+    try {
+      return new URL(raw).hostname.toLowerCase();
+    } catch {
+      return "[redacted-url]";
+    }
+  }
+  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  const relative = normalizePathValue(path.relative(cwd, absolute));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return null;
+  return relative;
+}
+
+function normalizeEnum(value, allowed, fallback) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return allowed.has(normalized) ? normalized : fallback;
+}
+
+function safeReadText(absPath) {
+  try {
+    return fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, "");
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJsonAbs(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function walkRepo(cwd, visitor, options = {}) {
+  const maxDepth = Number.isFinite(Number(options.maxDepth)) ? Number(options.maxDepth) : 7;
+  function visit(absPath, depth) {
+    if (depth > maxDepth) return;
+    let stat;
+    try {
+      stat = fs.statSync(absPath);
+    } catch {
+      return;
+    }
+    if (stat.isDirectory()) {
+      const base = path.basename(absPath);
+      if (SKIP_DIRS.has(base)) return;
+      let entries = [];
+      try {
+        entries = fs.readdirSync(absPath, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        visit(path.join(absPath, entry.name), depth + 1);
+      }
+      return;
+    }
+    const relPath = normalizePathValue(path.relative(cwd, absPath));
+    visitor(absPath, relPath);
+  }
+  visit(cwd, 0);
+}
+
+function buildSourceMetadataMap(cwd) {
+  const metadata = new Map();
+  walkRepo(cwd, (absPath, relPath) => {
+    if (!/\/SOURCE\.json$/i.test(`/${relPath}`)) return;
+    const payload = safeReadJsonAbs(absPath);
+    if (!payload) return;
+    metadata.set(path.posix.dirname(relPath), payload);
+  });
+  return metadata;
+}
+
+function hasFrontMatter(text) {
+  const value = String(text || "");
+  return /^---\s*\r?\n[\s\S]+?\r?\n---(?:\r?\n|$)/.test(value);
+}
+
+function hasExternalUrl(text) {
+  return /https?:\/\/(?!localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|::1)[^\s)'"]+/i.test(String(text || ""));
+}
+
+function detectCandidateType(relPath, manifest) {
+  const normalized = normalizePathValue(relPath);
+  if (manifest && manifest.type) {
+    return normalizeEnum(manifest.type, VALID_TYPES, "unknown");
+  }
+  if (normalized.endsWith("SKILL.md")) return "skill";
+  if (/\.capability\.json$/i.test(normalized)) return "unknown";
+  if (/(^|\/)(mcp|mcp-config|mcp-servers?)(\/|[-_.])/.test(normalized) || /(^|[-_.])mcp\.(json|ya?ml|md)$/i.test(normalized)) {
+    return "mcp";
+  }
+  if (/(^|\/)(prompt-packs?|prompts?)(\/|$)/i.test(normalized)) return "prompt_pack";
+  if (/(^|\/)(tools?|capabilities|fixtures\/capabilities|tests\/fixtures\/capabilities)(\/|$)/i.test(normalized)) return "tool";
+  return "unknown";
+}
+
+function detectCandidateName(relPath, manifest, type) {
+  if (manifest && typeof manifest.name === "string" && manifest.name.trim()) {
+    return sanitizeText(manifest.name.trim(), 120);
+  }
+  const normalized = normalizePathValue(relPath);
+  if (type === "skill") {
+    const segments = normalized.split("/");
+    return sanitizeText(segments[segments.length - 2] || "skill", 120);
+  }
+  return sanitizeText(path.basename(normalized), 120);
+}
+
+function sourceMetadataForCandidate(metadataMap, relPath) {
+  const normalized = normalizePathValue(relPath);
+  const vendorMatch = normalized.match(/^(vendor\/skillpacks\/[^/]+)/);
+  if (vendorMatch) {
+    return metadataMap.get(vendorMatch[1]) || null;
+  }
+  const skillMatch = normalized.match(/^(skills\/[^/]+)/);
+  if (skillMatch) {
+    return metadataMap.get(skillMatch[1]) || null;
+  }
+  return null;
+}
+
+function detectProvenance(relPath, manifest, sourceMetadata, text) {
+  if (manifest && manifest.provenance) {
+    return normalizeEnum(manifest.provenance, VALID_PROVENANCE, "unknown");
+  }
+  if (manifest && manifest.packageRef) return "package";
+  const normalized = normalizePathValue(relPath);
+  if (normalized.startsWith("skills/")) return "local";
+  if (normalized.startsWith("vendor/")) return "repo";
+  if (normalized.startsWith("prompts/") || normalized.startsWith("prompt-packs/")) return "local";
+  if (normalized.startsWith("mcp/") || normalized.startsWith("tools/") || normalized.startsWith("capabilities/")) return "repo";
+  if (normalized.startsWith("fixtures/capabilities/") || normalized.startsWith("tests/fixtures/capabilities/")) return "unknown";
+  if (sourceMetadata && sourceMetadata.packageName) return "package";
+  if (sourceMetadata && sourceMetadata.sourceUrl && !normalized.startsWith("vendor/")) return "external_reference";
+  if (hasExternalUrl(text)) return "external_reference";
+  return "unknown";
+}
+
+function detectPermissions(text, manifest) {
+  const permissions = [];
+  const reasonCodes = [];
+  const value = String(text || "");
+  const manifestPermissions = Array.isArray(manifest?.permissions) ? manifest.permissions : [];
+  for (const entry of manifestPermissions) {
+    const normalized = normalizeEnum(entry, VALID_PERMISSIONS, null);
+    if (normalized) permissions.push(normalized);
+  }
+  const patterns = [
+    { permission: "writes_files", pattern: /\b(write|writes|modify|modifies|edit|edits|create|creates|delete|deletes|patch|overwrite|rename|move)\b[^\n]{0,80}\b(file|files|config|configs|hook|hooks)\b/i, reasonCode: "write_permission_requested" },
+    { permission: "executes_commands", pattern: /\b(command|commands|shell|terminal|powershell|bash|spawn|exec|git |npm run|node )/i, reasonCode: "command_execution_requested" },
+    { permission: "network_access", pattern: /\b(fetch|http|https|api|curl|wget|invoke-webrequest|invoke-restmethod|network)\b/i, reasonCode: "network_access_requested" },
+    { permission: "browser_access", pattern: /\b(browser|playwright|chrome|edge|devtools|open page|visit url)\b/i, reasonCode: "browser_access_requested" },
+    { permission: "secrets_or_env", pattern: /\b(secret|secrets|token|tokens|api[_ -]?key|password|passwords|authorization|\.env|process\.env|env vars?)\b/i, reasonCode: "secrets_or_env_risk" },
+    { permission: "credentials", pattern: /\b(credentials?|cookie|cookies|session|oauth|login|auth token)\b/i, reasonCode: "credential_risk" },
+    { permission: "package_install", pattern: /\b(npm install|pnpm add|pnpm install|yarn add|pip install|brew install|apt-get install)\b/i, reasonCode: "package_install_requested" },
+    { permission: "production_or_deploy", pattern: /\b(deploy|deployment|production|prod\b|publish|release|ship to prod|npm publish|gh release)\b/i, reasonCode: "production_or_deploy_risk" },
+  ];
+
+  for (const rule of patterns) {
+    if (rule.pattern.test(value)) {
+      permissions.push(rule.permission);
+      reasonCodes.push(rule.reasonCode);
+    }
+  }
+
+  if (permissions.length === 0) {
+    permissions.push("read_only");
+    reasonCodes.push("read_only_candidate");
+  }
+
+  return {
+    permissions: unique(permissions).map((permission) => normalizeEnum(permission, VALID_PERMISSIONS, "unknown")),
+    reasonCodes: unique(reasonCodes),
+  };
+}
+
+function detectInstructionRisks(text, manifest) {
+  const risks = [];
+  const reasonCodes = [];
+  const value = String(text || "");
+  const manifestRisks = Array.isArray(manifest?.instructionRisks) ? manifest.instructionRisks : [];
+  for (const entry of manifestRisks) {
+    const normalized = normalizeEnum(entry, VALID_INSTRUCTION_RISKS, null);
+    if (normalized) risks.push(normalized);
+  }
+
+  const patterns = [
+    { risk: "broad_agent_instruction", pattern: /\b(do anything|take over|full autonomy|entire repo|across the whole workspace|all files)\b/i, reasonCode: "broad_agent_instruction" },
+    { risk: "hidden_automation", pattern: /\b(automatically|auto-run|autorun|without asking|silently|hidden background|background runtime)\b/i, reasonCode: "hidden_automation_risk" },
+    { risk: "prompt_injection_like", pattern: /\b(ignore previous|ignore above|bypass policy|override policy|disable guard|skip verification|do not mention)\b/i, reasonCode: "prompt_injection_like_instruction" },
+    { risk: "chain_of_thought_request", pattern: /\b(chain of thought|show your reasoning|reveal hidden reasoning|think step by step verbosely)\b/i, reasonCode: "chain_of_thought_request_detected" },
+    { risk: "secret_exfiltration_risk", pattern: /\b(upload|print|send|exfiltrate|paste)\b[^\n]{0,120}\b(secret|token|credential|password|cookie|session|env)\b/i, reasonCode: "secret_exfiltration_risk" },
+    { risk: "unsafe_external_action", pattern: /\b(download from|open external|visit external|deploy now|publish now|call external api|push directly to production)\b/i, reasonCode: "unsafe_external_action" },
+  ];
+
+  for (const rule of patterns) {
+    if (rule.pattern.test(value)) {
+      risks.push(rule.risk);
+      reasonCodes.push(rule.reasonCode);
+    }
+  }
+
+  if (risks.length === 0) {
+    risks.push("safe_pointer");
+  }
+
+  return {
+    instructionRisks: unique(risks).map((risk) => normalizeEnum(risk, VALID_INSTRUCTION_RISKS, "unknown")),
+    reasonCodes: unique(reasonCodes),
+  };
+}
+
+function inferSideEffectLevel(permissions) {
+  const set = new Set(permissions || []);
+  if (set.has("production_or_deploy")) return "network";
+  if (set.has("network_access") || set.has("browser_access")) return "network";
+  if (set.has("executes_commands")) return "execute";
+  if (set.has("writes_files") || set.has("package_install")) return "write";
+  if (set.has("read_only")) return "read";
+  return "unknown";
+}
+
+function inferRiskTier(permissions, instructionRisks, provenance, missingManifest) {
+  const permissionSet = new Set(permissions || []);
+  const instructionSet = new Set(instructionRisks || []);
+  if (
+    permissionSet.has("secrets_or_env")
+    || permissionSet.has("credentials")
+    || permissionSet.has("production_or_deploy")
+    || instructionSet.has("prompt_injection_like")
+    || instructionSet.has("hidden_automation")
+    || instructionSet.has("secret_exfiltration_risk")
+    || instructionSet.has("unsafe_external_action")
+  ) {
+    return "blocked";
+  }
+  if (
+    permissionSet.has("writes_files")
+    || permissionSet.has("executes_commands")
+    || permissionSet.has("network_access")
+    || permissionSet.has("browser_access")
+    || permissionSet.has("package_install")
+    || instructionSet.has("chain_of_thought_request")
+  ) {
+    return "high";
+  }
+  if (missingManifest || provenance === "external_reference" || provenance === "unknown") return "medium";
+  if (permissionSet.has("read_only") && instructionSet.has("safe_pointer")) return "low";
+  return "unknown";
+}
+
+function classifyDecision(input) {
+  const permissionSet = new Set(input.permissions || []);
+  const instructionSet = new Set(input.instructionRisks || []);
+  const reasonCodes = ["candidate_detected"];
+
+  if (input.provenance === "local") reasonCodes.push("local_source_detected");
+  if (input.provenance === "repo") reasonCodes.push("repo_source_detected");
+  if (input.provenance === "external_reference") reasonCodes.push("external_reference_detected");
+  if (input.provenance === "unknown") reasonCodes.push("unknown_provenance");
+  if (input.missingManifest) reasonCodes.push("missing_manifest");
+  if (input.missingPermissions) reasonCodes.push("missing_permissions");
+  if (input.sideEffectUnknown) reasonCodes.push("side_effect_unknown");
+
+  if (
+    permissionSet.has("secrets_or_env")
+    || permissionSet.has("credentials")
+    || permissionSet.has("production_or_deploy")
+    || instructionSet.has("prompt_injection_like")
+    || instructionSet.has("hidden_automation")
+    || instructionSet.has("secret_exfiltration_risk")
+    || instructionSet.has("unsafe_external_action")
+    || instructionSet.has("chain_of_thought_request")
+  ) {
+    return {
+      state: "block",
+      reasonCodes: unique([...reasonCodes, "blocked_unsafe_capability"]),
+      safeNextAction: "Keep this capability blocked and review the unsafe instruction or secret-sensitive behavior before any use.",
+    };
+  }
+
+  if (
+    permissionSet.has("writes_files")
+    || permissionSet.has("executes_commands")
+    || permissionSet.has("network_access")
+    || permissionSet.has("browser_access")
+    || permissionSet.has("package_install")
+    || input.adapterOrConfigSensitive
+  ) {
+    return {
+      state: "manual_review",
+      reasonCodes: unique([...reasonCodes, "manual_review_required"]),
+      safeNextAction: "Review the requested side effects and keep this capability in manual-review mode before trusting it.",
+    };
+  }
+
+  if (
+    input.provenance === "external_reference"
+    || input.provenance === "unknown"
+    || input.missingManifest
+    || input.sideEffectUnknown
+  ) {
+    return {
+      state: "quarantine",
+      reasonCodes: unique([...reasonCodes, "quarantined_for_review"]),
+      safeNextAction: "Keep this capability quarantined until provenance and permission evidence are complete.",
+    };
+  }
+
+  if (
+    permissionSet.has("read_only")
+    && instructionSet.size === 1
+    && instructionSet.has("safe_pointer")
+    && (input.provenance === "local" || input.provenance === "repo")
+  ) {
+    return {
+      state: "allow_local_reference",
+      reasonCodes: unique([...reasonCodes, "allowed_local_reference"]),
+      safeNextAction: "Keep this capability available as a local reference only and do not treat it as trusted runtime execution.",
+    };
+  }
+
+  return {
+    state: "allow_prepare_only",
+    reasonCodes: unique([...reasonCodes, "allowed_prepare_only"]),
+    safeNextAction: "Prepare documentation or evidence for this capability, but do not promote it automatically.",
+  };
+}
+
+function candidateShouldBeScanned(relPath) {
+  const normalized = normalizePathValue(relPath);
+  if (normalized.endsWith("SKILL.md")) return true;
+  if (/\.capability\.json$/i.test(normalized)) return true;
+  if (/(^|\/)(mcp|mcp-config|mcp-servers?|prompts?|prompt-packs?|tools?|capabilities|fixtures\/capabilities|tests\/fixtures\/capabilities)(\/|$)/i.test(normalized)) {
+    return /\.(md|json|ya?ml|toml)$/i.test(normalized);
+  }
+  return false;
+}
+
+function readManifestForCandidate(absPath, relPath, type) {
+  const normalized = normalizePathValue(relPath);
+  if (/\.json$/i.test(normalized)) {
+    return safeReadJsonAbs(absPath);
+  }
+  if (type === "skill" || type === "prompt_pack") {
+    const text = safeReadText(absPath) || "";
+    const match = text.match(/^---\s*\r?\n([\s\S]+?)\r?\n---(?:\r?\n|$)/);
+    if (!match) return null;
+    const lines = match[1].split(/\r?\n/);
+    const manifest = {};
+    for (const line of lines) {
+      const split = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.+)$/);
+      if (!split) continue;
+      manifest[split[1]] = split[2].replace(/^['"]|['"]$/g, "").trim();
+    }
+    return manifest;
+  }
+  return null;
+}
+
+function buildCandidate(cwd, absPath, relPath, sourceMetadataMap) {
+  const detectedType = detectCandidateType(relPath, null);
+  const text = safeReadText(absPath) || "";
+  const manifest = readManifestForCandidate(absPath, relPath, detectedType);
+  const type = detectCandidateType(relPath, manifest);
+  const sourceMetadata = sourceMetadataForCandidate(sourceMetadataMap, relPath);
+  const provenance = detectProvenance(relPath, manifest, sourceMetadata, text);
+  const permissionInfo = detectPermissions(text, manifest);
+  const instructionInfo = detectInstructionRisks(text, manifest);
+  const missingManifest = Boolean(
+    (type === "skill" || type === "prompt_pack")
+      && !hasFrontMatter(text)
+      && !(manifest && typeof manifest === "object")
+  );
+  const missingPermissions = !Array.isArray(manifest?.permissions)
+    && permissionInfo.permissions.length === 1
+    && permissionInfo.permissions[0] === "read_only"
+    && (type === "mcp" || type === "tool" || type === "adapter");
+  const sideEffectUnknown = permissionInfo.permissions.includes("unknown");
+  const adapterOrConfigSensitive = type === "adapter"
+    || /\b(hook|config|settings\.json|\.codex|adapter)\b/i.test(text)
+    || /\.codex\/config\.toml$/i.test(normalizePathValue(relPath));
+  const decision = classifyDecision({
+    provenance,
+    permissions: permissionInfo.permissions,
+    instructionRisks: instructionInfo.instructionRisks,
+    missingManifest,
+    missingPermissions,
+    sideEffectUnknown,
+    adapterOrConfigSensitive,
+  });
+  const riskTier = inferRiskTier(permissionInfo.permissions, instructionInfo.instructionRisks, provenance, missingManifest);
+  const name = detectCandidateName(relPath, manifest, type);
+  const sourceUrl = sanitizeText(manifest?.urlRef || manifest?.sourceUrl || sourceMetadata?.sourceUrl || null, 160);
+  const packageRef = sanitizeText(manifest?.packageRef || sourceMetadata?.packageName || null, 120);
+  const evidenceRefs = unique([
+    toRedactedRef(cwd, relPath),
+    sourceUrl ? toRedactedRef(cwd, sourceUrl) : null,
+  ]).slice(0, 4);
+
+  return {
+    id: hashId("cap", `${relPath}|${type}|${name}`),
+    name,
+    type,
+    source: {
+      provenance,
+      pathRef: toRedactedRef(cwd, relPath),
+      packageRef,
+      urlRef: sourceUrl ? toRedactedRef(cwd, sourceUrl) : null,
+      redacted: true,
+    },
+    risk: {
+      tier: riskTier,
+      permissions: permissionInfo.permissions,
+      instructionRisks: instructionInfo.instructionRisks,
+      sideEffectLevel: inferSideEffectLevel(permissionInfo.permissions),
+      secretsRisk: permissionInfo.permissions.includes("secrets_or_env") || permissionInfo.permissions.includes("credentials"),
+      networkRisk: permissionInfo.permissions.includes("network_access") || permissionInfo.permissions.includes("browser_access"),
+      productionRisk: permissionInfo.permissions.includes("production_or_deploy"),
+    },
+    decision: {
+      state: normalizeEnum(decision.state, VALID_DECISIONS, "quarantine"),
+      reasonCodes: unique([
+        ...decision.reasonCodes,
+        ...permissionInfo.reasonCodes,
+        ...instructionInfo.reasonCodes,
+      ]),
+      safeNextAction: decision.safeNextAction,
+    },
+    evidenceRefs,
+  };
+}
+
+function collectCandidates(cwd) {
+  const candidates = [];
+  const sourceMetadataMap = buildSourceMetadataMap(cwd);
+  walkRepo(cwd, (absPath, relPath) => {
+    if (!candidateShouldBeScanned(relPath)) return;
+    const candidate = buildCandidate(cwd, absPath, relPath, sourceMetadataMap);
+    candidates.push(candidate);
+  });
+  return candidates.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function summarizeCandidates(candidates) {
+  const counts = {
+    allow_local_reference: 0,
+    allow_prepare_only: 0,
+    quarantine: 0,
+    manual_review: 0,
+    block: 0,
+  };
+  for (const candidate of candidates) {
+    counts[candidate.decision.state] += 1;
+  }
+  return counts;
+}
+
+function buildRollup(candidates) {
+  return {
+    safeLocalReferences: candidates.filter((candidate) => candidate.decision.state === "allow_local_reference").map((candidate) => candidate.id),
+    quarantineQueue: candidates.filter((candidate) => candidate.decision.state === "quarantine").map((candidate) => candidate.id),
+    manualReviewQueue: candidates.filter((candidate) => candidate.decision.state === "manual_review").map((candidate) => candidate.id),
+    blockedItems: candidates.filter((candidate) => candidate.decision.state === "block").map((candidate) => candidate.id),
+    notEnoughEvidence: candidates
+      .filter((candidate) =>
+        candidate.decision.reasonCodes.includes("missing_manifest")
+        || candidate.decision.reasonCodes.includes("unknown_provenance")
+        || candidate.decision.reasonCodes.includes("side_effect_unknown")
+      )
+      .map((candidate) => candidate.id),
+  };
+}
+
+function buildIntegrationRefs(candidates) {
+  const hasCandidates = candidates.length > 0;
+  const hasSkillCandidates = candidates.some((candidate) => candidate.type === "skill" && candidate.decision.state === "allow_local_reference");
+  const hasBoundaryRisk = candidates.some((candidate) =>
+    candidate.risk.permissions.some((permission) =>
+      ["writes_files", "executes_commands", "network_access", "browser_access", "package_install", "production_or_deploy"].includes(permission)
+    )
+  );
+  const hasAgentReadinessRisk = candidates.some((candidate) =>
+    candidate.type === "adapter"
+    || candidate.decision.reasonCodes.some((code) => ["write_permission_requested", "browser_access_requested"].includes(code))
+  );
+
+  return {
+    skills: hasSkillCandidates ? [LATEST_REPORT_REL, SOURCE_REPORT_REL] : [],
+    boundary: hasBoundaryRisk ? [LATEST_REPORT_REL, BOUNDARY_REPORT_REL] : [],
+    agentReadiness: hasAgentReadinessRisk ? [LATEST_REPORT_REL, AGENT_READINESS_REPORT_REL] : [],
+    productHome: hasCandidates ? [LATEST_REPORT_REL, PRODUCT_HOME_REPORT_REL] : [],
+    radar: hasCandidates ? [LATEST_REPORT_REL, RADAR_REPORT_REL] : [],
+    status: hasCandidates ? [LATEST_REPORT_REL, "scripts/cco-status.js"] : [],
+    dashboard: hasCandidates ? [LATEST_REPORT_REL, "scripts/cco-dashboard.js"] : [],
+  };
+}
+
+function buildSafeNextAction(summary) {
+  if (summary.block > 0) {
+    return "Keep blocked capability candidates out of use and review the unsafe instruction or secret-sensitive behavior first.";
+  }
+  if (summary.manual_review > 0) {
+    return "Review the requested writes, command, browser, network, or package side effects before trusting these capabilities.";
+  }
+  if (summary.quarantine > 0) {
+    return "Add provenance and permission evidence before promoting quarantined capability candidates.";
+  }
+  if (summary.allow_prepare_only > 0) {
+    return "Prepare documentation and evidence for these candidates, but keep them out of trusted runtime use.";
+  }
+  if (summary.allow_local_reference > 0) {
+    return "Keep allowed capability candidates as local references only and avoid auto-install or auto-execution claims.";
+  }
+  return "Add a local capability manifest, skill, or MCP fixture and rerun `avorelo capability-intake --json`.";
+}
+
+function determineStatus(candidates, summary) {
+  if (candidates.length === 0) return "no_data";
+  if (summary.block > 0 && summary.manual_review === 0 && summary.quarantine === 0 && summary.allow_prepare_only === 0 && summary.allow_local_reference === 0) {
+    return "blocked";
+  }
+  if (summary.block > 0 || summary.manual_review > 0 || summary.quarantine > 0 || summary.allow_prepare_only > 0) {
+    return "needs_attention";
+  }
+  return "ready";
+}
+
+function buildPrivacySection() {
+  return {
+    localOnly: true,
+    remoteFetch: false,
+    remoteTelemetry: false,
+    rawPromptStored: false,
+    rawCodeStored: false,
+    secretsStored: false,
+    envStored: false,
+    fullLogsStored: false,
+    privatePathsStored: false,
+    redacted: true,
+  };
+}
+
+function buildClaimSafetySection() {
+  return {
+    marketplaceClaim: false,
+    autoInstallClaim: false,
+    autoExecutionClaim: false,
+    trustedByDefault: false,
+    guaranteedSafe: false,
+    universalMcpSupport: false,
+  };
+}
+
+function buildCapabilityIntakeQuarantineReport(cwd = process.cwd(), options = {}) {
+  const candidates = collectCandidates(cwd);
+  const summaryByDecision = summarizeCandidates(candidates);
+  const safeNextAction = buildSafeNextAction(summaryByDecision);
+  const status = determineStatus(candidates, summaryByDecision);
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      candidatesInspected: candidates.length,
+      allowed: summaryByDecision.allow_local_reference,
+      quarantined: summaryByDecision.quarantine,
+      manualReview: summaryByDecision.manual_review,
+      blocked: summaryByDecision.block,
+      safeNextAction,
+    },
+    candidates,
+    rollup: buildRollup(candidates),
+    integrationRefs: buildIntegrationRefs(candidates),
+    privacy: buildPrivacySection(),
+    claimSafety: buildClaimSafetySection(),
+  };
+
+  if (candidates.length === 0) {
+    report.rollup.notEnoughEvidence = ["no_candidates_found"];
+  }
+
+  return report;
+}
+
+function writeCapabilityIntakeQuarantineReport(cwd, report) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, LATEST_REPORT_REL, report);
+  return LATEST_REPORT_REL;
+}
+
+function generateCapabilityIntakeQuarantine(cwd = process.cwd(), options = {}) {
+  const report = buildCapabilityIntakeQuarantineReport(cwd, options);
+  const writtenPath = options.write === false ? null : writeCapabilityIntakeQuarantineReport(cwd, report);
+  return {
+    report,
+    writtenPath,
+  };
+}
+
+function readLatestCapabilityIntakeQuarantineReport(cwd = process.cwd()) {
+  return safeReadJson(cwd, LATEST_REPORT_REL, null);
+}
+
+function buildCapabilityIntakeQuarantineSurface(cwd = process.cwd(), options = {}) {
+  const report = options.report
+    || readLatestCapabilityIntakeQuarantineReport(cwd)
+    || (options.buildIfMissing ? buildCapabilityIntakeQuarantineReport(cwd, { write: false }) : null);
+
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return {
+      status: "not_run",
+      totalCandidates: 0,
+      allowed: 0,
+      quarantined: 0,
+      manualReview: 0,
+      blocked: 0,
+      nextAction: "Run `node bin/avorelo capability-intake --json` to inspect local capability candidates.",
+      latestReportPath: null,
+      showInStatus: false,
+      showInDashboard: false,
+      statusLine: "Capability intake: NOT RUN",
+    };
+  }
+
+  return {
+    status: report.status,
+    totalCandidates: Number(report.summary?.candidatesInspected || 0),
+    allowed: Number(report.summary?.allowed || 0),
+    quarantined: Number(report.summary?.quarantined || 0),
+    manualReview: Number(report.summary?.manualReview || 0),
+    blocked: Number(report.summary?.blocked || 0),
+    nextAction: report.summary?.safeNextAction || "Review capability candidates before trusting them.",
+    latestReportPath: LATEST_REPORT_REL,
+    showInStatus: true,
+    showInDashboard: true,
+    statusLine: `Capability intake: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()} · inspected=${Number(report.summary?.candidatesInspected || 0)} · allowed=${Number(report.summary?.allowed || 0)} · quarantine=${Number(report.summary?.quarantined || 0)} · manual=${Number(report.summary?.manualReview || 0)} · blocked=${Number(report.summary?.blocked || 0)}`,
+  };
+}
+
+function formatCapabilityIntakeQuarantineText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Capability Intake",
+      "Status: NO DATA",
+      "Candidates: 0",
+      "Next: Add a local capability manifest, skill, or MCP fixture and rerun `avorelo capability-intake --json`.",
+    ].join("\n");
+  }
+
+  const lines = [
+    "Avorelo Capability Intake",
+    `Status: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()}`,
+    `Candidates: ${Number(report.summary?.candidatesInspected || 0)} inspected`,
+    `Allowed: ${Number(report.summary?.allowed || 0)} · Quarantine: ${Number(report.summary?.quarantined || 0)} · Manual review: ${Number(report.summary?.manualReview || 0)} · Blocked: ${Number(report.summary?.blocked || 0)}`,
+  ];
+
+  const topCandidate = (report.candidates || []).find((candidate) => candidate.decision?.state !== "allow_local_reference")
+    || (report.candidates || [])[0];
+  if (topCandidate) {
+    lines.push(
+      `Top candidate: ${topCandidate.name} (${topCandidate.type}) · ${topCandidate.decision.state} · ${topCandidate.risk.tier}`
+    );
+    lines.push(`Reason codes: ${(topCandidate.decision.reasonCodes || []).slice(0, 5).join(", ") || "none"}`);
+  }
+
+  lines.push(`Next: ${report.summary?.safeNextAction || "Review the latest capability intake report."}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  LATEST_REPORT_REL,
+  buildCapabilityIntakeQuarantineReport,
+  buildCapabilityIntakeQuarantineSurface,
+  formatCapabilityIntakeQuarantineText,
+  generateCapabilityIntakeQuarantine,
+  readLatestCapabilityIntakeQuarantineReport,
+  writeCapabilityIntakeQuarantineReport,
+};