avorelo 0.1.0 → 0.3.0

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

@@ -1,1499 +0,0 @@
-"use strict";
-
-// ── AI Workspace Hygiene + Capability Registry v1 ────────────────────────────
-//
-// Contract: avorelo.aiWorkspaceHygiene.v1
-//
-// Scans repo-local AI workspace files, normalizes them into a capability
-// registry layer, derives hygiene findings, and writes a compact receipt.
-//
-// Rules:
-// - Deterministic, local-first, no network, no LLM, no package-registry calls
-// - No execution of scripts/MCP tools
-// - No scanning outside repo root
-// - Redact secrets and sensitive values
-// - Default output compact; debug exposes asset detail
-// - Do not auto-patch user files; recommend cleanup only
-// - OpenHands is a reference architecture, not an installed adapter
-
-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");
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-const HYGIENE_CONTRACT = "avorelo.aiWorkspaceHygiene.v1";
-const HYGIENE_SCHEMA_VERSION = 1;
-const LATEST_REPORT_REL = ".claude/cco/orchestration/ai-workspace-hygiene/latest-report.json";
-const LATEST_DEBUG_REPORT_REL = ".claude/cco/orchestration/ai-workspace-hygiene/latest-report-debug.json";
-const HYGIENE_HISTORY_DIR_REL = ".claude/cco/orchestration/ai-workspace-hygiene/history";
-const HYGIENE_EVENT_LOG_REL = ".claude/cco/events/ai-workspace-hygiene.jsonl";
-
-const SKIP_DIRS = new Set([
-  ".git", "node_modules", "dist", "build", "coverage",
-  ".next", ".turbo", ".cache", ".wasp", ".avorelo",
-]);
-
-const VALID_ASSET_TYPES = new Set([
-  "agent_instruction", "claude_instruction", "codex_instruction",
-  "gemini_instruction", "cursor_rule", "copilot_instruction",
-  "skill", "skill_pack", "mcp_config", "mcp_server", "mcp_tool",
-  "hook_config", "lifecycle_hook", "plugin_package",
-  "package_script", "context_pack", "proof_gate", "adapter_config",
-  "unknown_ai_asset",
-]);
-
-const VALID_STATUSES = new Set(["ready", "needs_review", "deferred", "blocked", "unknown"]);
-const VALID_TRUST_LEVELS = new Set(["high", "medium", "low", "unknown"]);
-const VALID_REVIEW_STATUSES = new Set(["reviewed", "known", "unknown", "deferred", "blocked"]);
-const VALID_RISK_LEVELS = new Set(["low", "medium", "high", "critical", "unknown"]);
-const VALID_CONTEXT_COSTS = new Set(["none", "low", "medium", "high", "unknown"]);
-
-const VALID_SCOPES = new Set([
-  "repo", "file", "directory", "network", "browser",
-  "secrets", "command", "deploy", "unknown",
-]);
-
-const VALID_CAPABILITIES = new Set([
-  "read", "write", "execute", "network", "browser",
-  "secrets", "deploy", "proof", "context", "routing", "unknown",
-]);
-
-const VALID_LIFECYCLE_STAGES = new Set([
-  "session_start", "prompt_submit", "pre_tool_use", "post_tool_use",
-  "stop", "session_end", "manual", "unknown",
-]);
-
-const VALID_STAGE_HINTS = new Set([
-  "inspect", "plan", "implement", "verify",
-  "review", "handoff", "summarize", "debug",
-]);
-
-const VALID_WORKER_HINTS = new Set([
-  "local_or_cheap", "strong_model", "local_test_runner",
-  "human_approval", "reviewed_tool", "none",
-]);
-
-// Finding codes
-const FINDING_CODES = Object.freeze({
-  DUPLICATE_INSTRUCTION_SURFACE: "DUPLICATE_INSTRUCTION_SURFACE",
-  CONFLICTING_INSTRUCTION_SURFACES: "CONFLICTING_INSTRUCTION_SURFACES",
-  HIGH_CONTEXT_COST_ASSET: "HIGH_CONTEXT_COST_ASSET",
-  MISSING_SKILL_TRIGGERS: "MISSING_SKILL_TRIGGERS",
-  MISSING_STAGE_HINTS: "MISSING_STAGE_HINTS",
-  UNKNOWN_SOURCE: "UNKNOWN_SOURCE",
-  UNKNOWN_MCP_SERVER: "UNKNOWN_MCP_SERVER",
-  BROAD_MCP_TOOL_CAPABILITY: "BROAD_MCP_TOOL_CAPABILITY",
-  RISKY_PACKAGE_SCRIPT: "RISKY_PACKAGE_SCRIPT",
-  SECRET_LIKE_REFERENCE: "SECRET_LIKE_REFERENCE",
-  EXTERNAL_DOMAIN_REFERENCE: "EXTERNAL_DOMAIN_REFERENCE",
-  MISSING_PROOF_GATE: "MISSING_PROOF_GATE",
-  STALE_OR_UNREFERENCED_SKILL: "STALE_OR_UNREFERENCED_SKILL",
-  FULL_SKILL_BODY_RISK: "FULL_SKILL_BODY_RISK",
-  ADAPTER_CORE_LOGIC_LEAKAGE: "ADAPTER_CORE_LOGIC_LEAKAGE",
-  UNKNOWN_HOOK_STAGE: "UNKNOWN_HOOK_STAGE",
-});
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-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 normalizeSlash(value) {
-  return String(value || "").replace(/\\/g, "/");
-}
-
-function safeReadFile(absPath, maxBytes = 32768) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    const stat = fs.statSync(absPath);
-    if (stat.size > maxBytes) return null;
-    return fs.readFileSync(absPath, "utf8");
-  } catch {
-    return null;
-  }
-}
-
-function safeReadDir(absPath) {
-  try {
-    return fs.readdirSync(absPath, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-}
-
-function safeStatSize(absPath) {
-  try {
-    return fs.statSync(absPath).size;
-  } catch {
-    return 0;
-  }
-}
-
-function redactSecrets(text) {
-  return String(text || "")
-    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted]")
-    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted]")
-    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted]")
-    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]");
-}
-
-function hasSecretLike(text) {
-  return /\b(api[_ -]?key|token|password|secret|authorization|credential)\s*[:=]\s*[^\s'"]+/i.test(String(text || ""));
-}
-
-function hasExternalDomain(text) {
-  return /https?:\/\/(?!localhost|127\.0\.0\.1|::1)[^\s)'"`,]+/i.test(String(text || ""));
-}
-
-function hasPolicyBypass(text) {
-  const val = String(text || "");
-  return /\b(ignore|bypass|disable|remove)\b[^\n]{0,120}\b(policy|guard|audit|proof|tests?|verification)\b/i.test(val);
-}
-
-function hasAdapterCoreLogicLeak(text) {
-  const markers = [
-    "sourceTrustLevel", "reviewStatus", "The Five-Axis Review",
-    "Write a failing test before writing the code",
-    "source-backed skill/reference inventory",
-  ];
-  const val = String(text || "");
-  return val.length > 1200 && markers.some((marker) => val.includes(marker));
-}
-
-function contextCostFromSize(bytes) {
-  if (bytes <= 512) return "none";
-  if (bytes <= 4096) return "low";
-  if (bytes <= 16384) return "medium";
-  return "high";
-}
-
-function maxRiskLevel(a, b) {
-  const order = { low: 1, medium: 2, high: 3, critical: 4, unknown: 0 };
-  return (order[a] || 0) >= (order[b] || 0) ? a : b;
-}
-
-function assetId(type, relPath, name) {
-  return `ws-asset-${sha256Short([type, relPath, name].join("|"))}`;
-}
-
-// ── Asset Builder ─────────────────────────────────────────────────────────────
-
-function buildAsset(input) {
-  const type = VALID_ASSET_TYPES.has(input.type) ? input.type : "unknown_ai_asset";
-  const status = VALID_STATUSES.has(input.status) ? input.status : "unknown";
-  const trustLevel = VALID_TRUST_LEVELS.has(input.trustLevel) ? input.trustLevel : "unknown";
-  const reviewStatus = VALID_REVIEW_STATUSES.has(input.reviewStatus) ? input.reviewStatus : "unknown";
-  const riskLevel = VALID_RISK_LEVELS.has(input.riskLevel) ? input.riskLevel : "unknown";
-  const contextCost = VALID_CONTEXT_COSTS.has(input.contextCost) ? input.contextCost : "unknown";
-
-  return {
-    id: input.id || assetId(type, input.path || "", input.name || ""),
-    type,
-    name: redactSecrets(String(input.name || type)),
-    path: normalizeSlash(input.path || ""),
-    source: String(input.source || "local"),
-    host: String(input.host || "local"),
-    status,
-    trustLevel,
-    reviewStatus,
-    riskLevel,
-    contextCost,
-    scope: unique((input.scope || ["unknown"]).filter((s) => VALID_SCOPES.has(s))),
-    capabilities: unique((input.capabilities || ["unknown"]).filter((c) => VALID_CAPABILITIES.has(c))),
-    lifecycleStage: VALID_LIFECYCLE_STAGES.has(input.lifecycleStage) ? input.lifecycleStage : "unknown",
-    stageHints: unique((input.stageHints || []).filter((h) => VALID_STAGE_HINTS.has(h))),
-    workerHints: unique((input.workerHints || ["none"]).filter((h) => VALID_WORKER_HINTS.has(h))),
-    proofValue: String(input.proofValue || "unknown"),
-    safetyControls: unique(input.safetyControls || []),
-    reasonCodes: unique(input.reasonCodes || []),
-    warnings: (input.warnings || []).map((w) => ({ code: w.code, message: redactSecrets(w.message || "") })),
-    recommendedAction: redactSecrets(String(input.recommendedAction || "")),
-    customerVisible: input.customerVisible !== false,
-    debugVisible: input.debugVisible !== false,
-    orchestrationReady: Boolean(input.orchestrationReady),
-    redacted: true,
-  };
-}
-
-// ── Scanner: Root AI instructions ─────────────────────────────────────────────
-
-function scanRootInstructions(cwd) {
-  const candidates = [
-    { file: "AGENTS.md", type: "agent_instruction", host: "claude-code" },
-    { file: "CLAUDE.md", type: "claude_instruction", host: "claude-code" },
-    { file: "GEMINI.md", type: "gemini_instruction", host: "gemini-cli" },
-  ];
-  return candidates
-    .filter(({ file }) => fs.existsSync(path.join(cwd, file)))
-    .map(({ file, type, host }) => {
-      const absPath = path.join(cwd, file);
-      const size = safeStatSize(absPath);
-      const content = safeReadFile(absPath);
-      const warnings = [];
-      if (content && hasPolicyBypass(content)) warnings.push({ code: "GUIDANCE_POLICY_BYPASS", message: "Guidance includes policy-bypass language." });
-      if (content && hasSecretLike(content)) warnings.push({ code: "SECRET_LIKE_REFERENCE", message: "Guidance may reference secrets or credentials." });
-      if (content && hasExternalDomain(content)) warnings.push({ code: "EXTERNAL_BROWSER_DOMAIN", message: "Guidance references external domain." });
-      if (content && hasAdapterCoreLogicLeak(content)) warnings.push({ code: "ADAPTER_CORE_LOGIC_LEAKAGE", message: "Instruction file looks too heavy and may leak internal policy." });
-      return buildAsset({
-        type,
-        name: file,
-        path: file,
-        source: "local_repo",
-        host,
-        status: warnings.length ? "needs_review" : "ready",
-        trustLevel: "medium",
-        reviewStatus: "known",
-        riskLevel: warnings.some((w) => ["GUIDANCE_POLICY_BYPASS", "SECRET_LIKE_REFERENCE"].includes(w.code)) ? "high" : "low",
-        contextCost: contextCostFromSize(size),
-        scope: ["repo"],
-        capabilities: ["read", "context"],
-        lifecycleStage: "session_start",
-        stageHints: ["inspect", "plan"],
-        workerHints: ["local_or_cheap"],
-        proofValue: "low",
-        safetyControls: ["instruction_risk_review"],
-        reasonCodes: unique(warnings.map((w) => w.code)),
-        warnings,
-        recommendedAction: warnings.length
-          ? "Review this instruction file for policy-bypass language, secret references, or external domain links."
-          : "Keep instruction bounded and review before sharing.",
-        customerVisible: false,
-        debugVisible: true,
-        orchestrationReady: true,
-      });
-    });
-}
-
-// ── Scanner: Editor/Agent instructions ───────────────────────────────────────
-
-function scanEditorInstructions(cwd) {
-  const assets = [];
-
-  // Cursor rules
-  const cursorRulesDir = path.join(cwd, ".cursor", "rules");
-  if (fs.existsSync(cursorRulesDir)) {
-    for (const entry of safeReadDir(cursorRulesDir)) {
-      if (!entry.isFile()) continue;
-      const filePath = normalizeSlash(path.relative(cwd, path.join(cursorRulesDir, entry.name)));
-      const absPath = path.join(cwd, filePath);
-      const size = safeStatSize(absPath);
-      const content = safeReadFile(absPath);
-      const warnings = [];
-      if (content && hasSecretLike(content)) warnings.push({ code: "SECRET_LIKE_REFERENCE", message: "Cursor rule references secret-like value." });
-      if (content && hasAdapterCoreLogicLeak(content)) warnings.push({ code: "ADAPTER_CORE_LOGIC_LEAKAGE", message: "Cursor rule is too heavy and may leak internal policy." });
-      assets.push(buildAsset({
-        type: "cursor_rule",
-        name: entry.name,
-        path: filePath,
-        source: "local_repo",
-        host: "cursor",
-        status: warnings.length ? "needs_review" : "ready",
-        trustLevel: "medium",
-        reviewStatus: "known",
-        riskLevel: warnings.length ? "medium" : "low",
-        contextCost: contextCostFromSize(size),
-        scope: ["repo"],
-        capabilities: ["read", "context"],
-        lifecycleStage: "session_start",
-        stageHints: ["inspect", "plan"],
-        workerHints: ["local_or_cheap"],
-        proofValue: "low",
-        warnings,
-        reasonCodes: unique(warnings.map((w) => w.code)),
-        recommendedAction: warnings.length ? "Review cursor rule for leaked policy." : "Keep cursor rule compact.",
-        customerVisible: false,
-        debugVisible: true,
-        orchestrationReady: true,
-      }));
-    }
-  }
-
-  // Copilot instructions
-  const copilotCandidates = [
-    ".github/copilot-instructions.md",
-  ];
-  // .github/instructions/*.instructions.md
-  const ghInstructionsDir = path.join(cwd, ".github", "instructions");
-  if (fs.existsSync(ghInstructionsDir)) {
-    for (const entry of safeReadDir(ghInstructionsDir)) {
-      if (entry.isFile() && entry.name.endsWith(".instructions.md")) {
-        copilotCandidates.push(normalizeSlash(path.relative(cwd, path.join(ghInstructionsDir, entry.name))));
-      }
-    }
-  }
-
-  for (const relFile of copilotCandidates) {
-    if (!fs.existsSync(path.join(cwd, relFile))) continue;
-    const absPath = path.join(cwd, relFile);
-    const size = safeStatSize(absPath);
-    const content = safeReadFile(absPath);
-    const warnings = [];
-    if (content && hasSecretLike(content)) warnings.push({ code: "SECRET_LIKE_REFERENCE", message: "Copilot instruction references secret-like value." });
-    if (content && hasAdapterCoreLogicLeak(content)) warnings.push({ code: "ADAPTER_CORE_LOGIC_LEAKAGE", message: "Copilot instruction is too heavy." });
-    assets.push(buildAsset({
-      type: "copilot_instruction",
-      name: path.basename(relFile),
-      path: relFile,
-      source: "local_repo",
-      host: "github-copilot",
-      status: warnings.length ? "needs_review" : "ready",
-      trustLevel: "medium",
-      reviewStatus: "known",
-      riskLevel: warnings.length ? "medium" : "low",
-      contextCost: contextCostFromSize(size),
-      scope: ["repo"],
-      capabilities: ["read", "context"],
-      lifecycleStage: "session_start",
-      stageHints: ["inspect"],
-      workerHints: ["local_or_cheap"],
-      proofValue: "low",
-      warnings,
-      reasonCodes: unique(warnings.map((w) => w.code)),
-      recommendedAction: "Keep copilot instruction bounded and reviewed.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: false,
-    }));
-  }
-
-  return assets;
-}
-
-// ── Scanner: .claude / .openhands config dirs ─────────────────────────────────
-
-function scanAgentConfigDirs(cwd) {
-  const assets = [];
-  const dirs = [
-    { dir: ".claude", host: "claude-code", type: "claude_instruction" },
-    { dir: ".openhands", host: "openhands", type: "agent_instruction" },
-  ];
-
-  for (const { dir, host, type } of dirs) {
-    const absDir = path.join(cwd, dir);
-    if (!fs.existsSync(absDir)) continue;
-
-    // Only scan metadata/config-like files; skip generated receipts/large artifacts
-    const CONFIG_EXTENSIONS = new Set([".json", ".yaml", ".yml", ".toml", ".md"]);
-    const MAX_CONFIG_BYTES = 16384;
-
-    function walkDir(absPath, relBase) {
-      const entries = safeReadDir(absPath);
-      for (const entry of entries) {
-        const entryAbs = path.join(absPath, entry.name);
-        const entryRel = normalizeSlash(path.join(relBase, entry.name));
-        if (entry.isDirectory()) {
-          // Skip large generated subdirs
-          if (["cco", "receipts", "history", "events", "runs", "reports", "state", "orchestration"].includes(entry.name)) continue;
-          walkDir(entryAbs, entryRel);
-          continue;
-        }
-        const ext = path.extname(entry.name).toLowerCase();
-        if (!CONFIG_EXTENSIONS.has(ext)) continue;
-        const size = safeStatSize(entryAbs);
-        if (size > MAX_CONFIG_BYTES) continue;
-        const content = safeReadFile(entryAbs, MAX_CONFIG_BYTES);
-        const warnings = [];
-        if (content && hasSecretLike(content)) warnings.push({ code: "SECRET_LIKE_REFERENCE", message: `${dir} config references secret-like value.` });
-        assets.push(buildAsset({
-          type,
-          name: entry.name,
-          path: entryRel,
-          source: "local_repo",
-          host,
-          status: "ready",
-          trustLevel: host === "claude-code" ? "high" : "medium",
-          reviewStatus: "known",
-          riskLevel: warnings.length ? "medium" : "low",
-          contextCost: contextCostFromSize(size),
-          scope: ["repo"],
-          capabilities: ["read", "context"],
-          lifecycleStage: "session_start",
-          stageHints: ["inspect"],
-          workerHints: ["local_or_cheap"],
-          proofValue: "medium",
-          warnings,
-          reasonCodes: unique(warnings.map((w) => w.code)),
-          recommendedAction: warnings.length ? "Review config file for leaked secrets." : "Keep config bounded.",
-          customerVisible: false,
-          debugVisible: true,
-          orchestrationReady: host === "claude-code",
-        }));
-      }
-    }
-
-    walkDir(absDir, dir);
-  }
-
-  return assets;
-}
-
-// ── Scanner: Skills ───────────────────────────────────────────────────────────
-
-function scanSkills(cwd) {
-  const assets = [];
-  const skillsDirs = [
-    { dir: "skills", host: "avorelo", reviewStatus: "reviewed", trustLevel: "high" },
-    { dir: "vendor/skillpacks", host: "vendor", reviewStatus: "known", trustLevel: "medium" },
-  ];
-
-  for (const { dir, host, reviewStatus, trustLevel } of skillsDirs) {
-    const absDir = path.join(cwd, dir);
-    if (!fs.existsSync(absDir)) continue;
-
-    function walkForSkills(absPath, relBase) {
-      const entries = safeReadDir(absPath);
-      let foundPackMeta = false;
-
-      for (const entry of entries) {
-        const entryAbs = path.join(absPath, entry.name);
-        const entryRel = normalizeSlash(path.join(relBase, entry.name));
-
-        if (entry.isDirectory()) {
-          if (SKIP_DIRS.has(entry.name)) continue;
-          walkForSkills(entryAbs, entryRel);
-          continue;
-        }
-
-        // Detect skill pack metadata
-        if (entry.name === "SOURCE.json" || entry.name === "MANIFEST.json") {
-          foundPackMeta = true;
-          const size = safeStatSize(entryAbs);
-          assets.push(buildAsset({
-            type: "skill_pack",
-            name: path.basename(relBase),
-            path: entryRel,
-            source: host === "vendor" ? "vendor_skill_pack" : "local_skill_pack",
-            host,
-            status: "ready",
-            trustLevel,
-            reviewStatus,
-            riskLevel: "low",
-            contextCost: contextCostFromSize(size),
-            scope: ["repo"],
-            capabilities: ["read", "context", "routing"],
-            lifecycleStage: "prompt_submit",
-            stageHints: ["inspect", "plan", "implement"],
-            workerHints: ["local_or_cheap"],
-            proofValue: "medium",
-            warnings: [],
-            reasonCodes: [],
-            recommendedAction: "Verify skill pack source and trust level before use.",
-            customerVisible: false,
-            debugVisible: true,
-            orchestrationReady: true,
-          }));
-          continue;
-        }
-
-        // Detect individual skill files
-        if (!/\.(md|yaml|yml|json)$/i.test(entry.name)) continue;
-        const size = safeStatSize(entryAbs);
-        const content = safeReadFile(entryAbs, 4096);
-        const warnings = [];
-        const hasTrigger = content && /trigger|when|task_type|activation/i.test(content);
-        const hasStageHint = content && /stage|phase|step|workflow/i.test(content);
-
-        if (!hasTrigger) warnings.push({ code: FINDING_CODES.MISSING_SKILL_TRIGGERS, message: "Skill file has no clear trigger or activation condition." });
-        if (!hasStageHint) warnings.push({ code: FINDING_CODES.MISSING_STAGE_HINTS, message: "Skill file has no stage or workflow hints." });
-        if (size > 8192) warnings.push({ code: FINDING_CODES.FULL_SKILL_BODY_RISK, message: "Skill file is large; loading full body risks high context cost." });
-        if (content && hasAdapterCoreLogicLeak(content)) warnings.push({ code: FINDING_CODES.ADAPTER_CORE_LOGIC_LEAKAGE, message: "Skill file may contain adapter or core logic that should not be exposed." });
-
-        assets.push(buildAsset({
-          type: "skill",
-          name: entry.name,
-          path: entryRel,
-          source: host === "vendor" ? "vendor_skill_pack" : "local_skill_pack",
-          host,
-          status: warnings.some((w) => ["FULL_SKILL_BODY_RISK", "ADAPTER_CORE_LOGIC_LEAKAGE"].includes(w.code)) ? "needs_review" : "ready",
-          trustLevel,
-          reviewStatus,
-          riskLevel: size > 16384 ? "medium" : "low",
-          contextCost: contextCostFromSize(size),
-          scope: ["repo"],
-          capabilities: ["read", "context"],
-          lifecycleStage: "prompt_submit",
-          stageHints: hasTrigger ? ["plan", "implement"] : [],
-          workerHints: hasTrigger ? ["local_or_cheap"] : ["none"],
-          proofValue: "low",
-          warnings,
-          reasonCodes: unique(warnings.map((w) => w.code)),
-          recommendedAction: warnings.length
-            ? "Add activation triggers, stage hints, and keep skill compact."
-            : "Keep skill focused and lazy-loaded.",
-          customerVisible: false,
-          debugVisible: true,
-          orchestrationReady: Boolean(hasTrigger && hasStageHint),
-        }));
-      }
-    }
-
-    walkForSkills(absDir, dir);
-  }
-
-  return assets;
-}
-
-// ── Scanner: MCP configs ──────────────────────────────────────────────────────
-
-function parseMcpJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function mcpServersFromParsed(parsed) {
-  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") {
-    return Object.entries(parsed.servers).map(([name, value]) => ({ name, value }));
-  }
-  return [];
-}
-
-function detectMcpCapabilities(serverConfig) {
-  const text = JSON.stringify(serverConfig || {});
-  const caps = [];
-  if (/write|patch|delete|mutate|edit|create/i.test(text)) caps.push("write");
-  if (/http|https|fetch|network|url/i.test(text)) caps.push("network");
-  if (/command|shell|exec|spawn|terminal/i.test(text)) caps.push("execute");
-  if (/browser|playwright|chrome|devtools/i.test(text)) caps.push("browser");
-  if (/secret|token|credential|env/i.test(text)) caps.push("secrets");
-  if (/deploy|publish|release/i.test(text)) caps.push("deploy");
-  if (!caps.length) caps.push("read");
-  return caps;
-}
-
-function scanMcpConfigs(cwd) {
-  const assets = [];
-  const MCP_CONFIG_CANDIDATES = [
-    ".mcp.json",
-    "mcp.json",
-    ".claude/mcp.json",
-    "mcp-config.json",
-    "mcp-shadow.json",
-  ];
-
-  for (const relPath of MCP_CONFIG_CANDIDATES) {
-    const absPath = path.join(cwd, relPath);
-    if (!fs.existsSync(absPath)) continue;
-
-    const parsed = parseMcpJson(absPath);
-    const size = safeStatSize(absPath);
-
-    // Emit a mcp_config asset for the config file itself
-    assets.push(buildAsset({
-      type: "mcp_config",
-      name: path.basename(relPath),
-      path: relPath,
-      source: "local_repo",
-      host: "local",
-      status: "ready",
-      trustLevel: "medium",
-      reviewStatus: "known",
-      riskLevel: "medium",
-      contextCost: contextCostFromSize(size),
-      scope: ["repo"],
-      capabilities: ["read"],
-      lifecycleStage: "session_start",
-      stageHints: ["inspect"],
-      workerHints: ["local_or_cheap"],
-      proofValue: "medium",
-      warnings: [],
-      reasonCodes: [],
-      recommendedAction: "Review MCP config servers and their tool capabilities.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: false,
-    }));
-
-    // Emit mcp_server assets per server
-    for (const { name, value } of mcpServersFromParsed(parsed)) {
-      const caps = detectMcpCapabilities(value);
-      const hasBroadCap = caps.some((c) => ["write", "network", "execute", "secrets", "deploy"].includes(c));
-      const warnings = [];
-      warnings.push({ code: FINDING_CODES.UNKNOWN_MCP_SERVER, message: `MCP server '${name}' is present without reviewed source metadata.` });
-      if (hasBroadCap) warnings.push({ code: FINDING_CODES.BROAD_MCP_TOOL_CAPABILITY, message: `MCP server '${name}' has broad capabilities: ${caps.join(", ")}.` });
-
-      assets.push(buildAsset({
-        type: "mcp_server",
-        name,
-        path: relPath,
-        source: "mcp_config",
-        host: "local",
-        status: "needs_review",
-        trustLevel: "unknown",
-        reviewStatus: "unknown",
-        riskLevel: hasBroadCap ? "high" : "medium",
-        contextCost: "none",
-        scope: unique(caps.map((c) => c === "execute" ? "command" : c === "browser" ? "browser" : c === "deploy" ? "deploy" : c === "network" ? "network" : c === "secrets" ? "secrets" : "repo")),
-        capabilities: caps,
-        lifecycleStage: "manual",
-        stageHints: ["inspect"],
-        workerHints: ["human_approval"],
-        proofValue: "low",
-        warnings,
-        reasonCodes: unique(warnings.map((w) => w.code)),
-        recommendedAction: "Review MCP server source, ownership, and capabilities before trusting at runtime.",
-        customerVisible: false,
-        debugVisible: true,
-        orchestrationReady: false,
-      }));
-    }
-  }
-
-  return assets;
-}
-
-// ── Scanner: Hook configs ─────────────────────────────────────────────────────
-
-function scanHookConfigs(cwd) {
-  const assets = [];
-  const HOOK_CONFIG_CANDIDATES = [
-    ".claude/settings.json",
-    ".openhands/hooks.json",
-    ".openhands/config.yaml",
-    ".openhands/config.json",
-    "hooks/config.json",
-  ];
-
-  const HOOK_LIFECYCLE_PATTERNS = {
-    PreToolUse: "pre_tool_use",
-    PostToolUse: "post_tool_use",
-    Stop: "stop",
-    Notification: "session_end",
-    UserPromptSubmit: "prompt_submit",
-    SubagentStop: "stop",
-  };
-
-  for (const relPath of HOOK_CONFIG_CANDIDATES) {
-    const absPath = path.join(cwd, relPath);
-    if (!fs.existsSync(absPath)) continue;
-    const size = safeStatSize(absPath);
-    if (size > 32768) continue;
-
-    let parsed = null;
-    try {
-      const content = fs.readFileSync(absPath, "utf8");
-      parsed = JSON.parse(content);
-    } catch {
-      // yaml or unreadable
-    }
-
-    // Detect lifecycle stages from hook config
-    let detectedStages = [];
-    if (parsed && typeof parsed === "object") {
-      const hooksObj = parsed.hooks || parsed;
-      for (const [key, stage] of Object.entries(HOOK_LIFECYCLE_PATTERNS)) {
-        if (hooksObj[key] !== undefined) {
-          detectedStages.push(stage);
-        }
-      }
-    }
-
-    const warnings = [];
-    if (detectedStages.length === 0) {
-      warnings.push({ code: FINDING_CODES.UNKNOWN_HOOK_STAGE, message: `Hook config at '${relPath}' has no recognized lifecycle stage.` });
-      detectedStages = ["unknown"];
-    }
-
-    assets.push(buildAsset({
-      type: "hook_config",
-      name: path.basename(relPath),
-      path: relPath,
-      source: "local_repo",
-      host: relPath.includes(".openhands") ? "openhands" : "claude-code",
-      status: "ready",
-      trustLevel: "high",
-      reviewStatus: "reviewed",
-      riskLevel: "low",
-      contextCost: contextCostFromSize(size),
-      scope: ["repo"],
-      capabilities: ["execute", "context"],
-      lifecycleStage: detectedStages[0] || "unknown",
-      stageHints: ["inspect"],
-      workerHints: ["local_or_cheap"],
-      proofValue: "medium",
-      warnings,
-      reasonCodes: unique(warnings.map((w) => w.code)),
-      recommendedAction: "Verify hook configs install and run correctly.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: true,
-    }));
-  }
-
-  return assets;
-}
-
-// ── Scanner: Package scripts ──────────────────────────────────────────────────
-
-function scanPackageScripts(cwd) {
-  const assets = [];
-  const pkgPath = path.join(cwd, "package.json");
-  if (!fs.existsSync(pkgPath)) return assets;
-
-  let pkg = null;
-  try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-  } catch {
-    return assets;
-  }
-
-  const scripts = pkg.scripts || {};
-  const RISKY_PATTERNS = [
-    { re: /\b(preinstall|postinstall|prepare)\b/i, code: "INSTALL_SCRIPT_PRESENT", risk: "high" },
-    { re: /\b(curl|wget|Invoke-WebRequest|Invoke-RestMethod)\b/i, code: "NETWORK_SCRIPT_PRESENT", risk: "high" },
-    { re: /\b(token|secret|credential|process\.env|echo\s+\$[A-Z_]+)\b/i, code: "SECRET_EXFIL_SCRIPT", risk: "high" },
-    { re: /\brm\s+-rf\b|\bdel\s+\/s\s+\/q\b|\brmdir\b/i, code: "DESTRUCTIVE_SCRIPT_PRESENT", risk: "critical" },
-    { re: /\b(deploy|publish|release|npm publish|gh release)\b/i, code: "DEPLOY_SCRIPT_PRESENT", risk: "high" },
-  ];
-
-  for (const [name, command] of Object.entries(scripts)) {
-    const commandStr = String(command || "");
-    const matchedPatterns = RISKY_PATTERNS.filter(({ re, code }) => {
-      if (code === "INSTALL_SCRIPT_PRESENT") return ["preinstall", "postinstall", "prepare"].includes(name.toLowerCase());
-      return re.test(commandStr);
-    });
-
-    if (matchedPatterns.length === 0) continue;
-
-    const maxRisk = matchedPatterns.reduce((r, p) => maxRiskLevel(r, p.risk), "low");
-    const warnings = matchedPatterns.map(({ code, risk }) => ({
-      code: FINDING_CODES.RISKY_PACKAGE_SCRIPT,
-      message: `Script '${name}' has ${risk}-risk pattern: ${code}.`,
-    }));
-
-    assets.push(buildAsset({
-      type: "package_script",
-      name,
-      path: "package.json",
-      source: "package_manifest",
-      host: "local",
-      status: "needs_review",
-      trustLevel: "medium",
-      reviewStatus: "known",
-      riskLevel: maxRisk,
-      contextCost: "none",
-      scope: ["command", ...(commandStr.match(/deploy|publish|release/i) ? ["deploy"] : []), ...(commandStr.match(/curl|wget/i) ? ["network"] : [])],
-      capabilities: ["execute", ...(commandStr.match(/deploy|publish/i) ? ["deploy"] : []), ...(commandStr.match(/curl|wget/i) ? ["network"] : [])],
-      lifecycleStage: "manual",
-      stageHints: [],
-      workerHints: ["human_approval"],
-      proofValue: "low",
-      warnings,
-      reasonCodes: unique(matchedPatterns.map((p) => p.code)),
-      recommendedAction: "Review this script before running; prefer dry-run or no-network alternatives first.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: false,
-    }));
-  }
-
-  return assets;
-}
-
-// ── Scanner: Avorelo context/proof metadata ───────────────────────────────────
-
-function scanAvoreloPacks(cwd) {
-  const assets = [];
-
-  // Context pack metadata
-  const ctxPackPath = ".claude/cco/orchestration/context-optimizer/latest-pack.json";
-  const ctxPackAbs = path.join(cwd, ctxPackPath);
-  if (fs.existsSync(ctxPackAbs)) {
-    const pack = parseMcpJson(ctxPackAbs);
-    const tokenEstimate = pack?.tokenEstimate || 0;
-    const contextCost = tokenEstimate > 8192 ? "high" : tokenEstimate > 2048 ? "medium" : tokenEstimate > 256 ? "low" : "none";
-    const warnings = [];
-    if (tokenEstimate > 8192) warnings.push({ code: "HIGH_CONTEXT_COST_ASSET", message: `Context pack is large (${tokenEstimate} tokens estimated).` });
-    assets.push(buildAsset({
-      type: "context_pack",
-      name: "latest-pack.json",
-      path: ctxPackPath,
-      source: "avorelo_generated",
-      host: "avorelo",
-      status: "ready",
-      trustLevel: "high",
-      reviewStatus: "reviewed",
-      riskLevel: "low",
-      contextCost,
-      scope: ["repo"],
-      capabilities: ["context"],
-      lifecycleStage: "prompt_submit",
-      stageHints: ["plan", "implement"],
-      workerHints: ["local_or_cheap"],
-      proofValue: "medium",
-      warnings,
-      reasonCodes: unique(warnings.map((w) => w.code)),
-      recommendedAction: tokenEstimate > 8192 ? "Reduce context pack size for local worker compatibility." : "Context pack is compact.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: true,
-    }));
-  }
-
-  // Proof gate metadata
-  const proofPath = ".claude/cco/orchestration/current-proof.json";
-  const proofAbs = path.join(cwd, proofPath);
-  if (fs.existsSync(proofAbs)) {
-    assets.push(buildAsset({
-      type: "proof_gate",
-      name: "current-proof.json",
-      path: proofPath,
-      source: "avorelo_generated",
-      host: "avorelo",
-      status: "ready",
-      trustLevel: "high",
-      reviewStatus: "reviewed",
-      riskLevel: "low",
-      contextCost: "low",
-      scope: ["repo"],
-      capabilities: ["proof", "context"],
-      lifecycleStage: "stop",
-      stageHints: ["verify", "summarize"],
-      workerHints: ["local_or_cheap"],
-      proofValue: "high",
-      warnings: [],
-      reasonCodes: [],
-      recommendedAction: "Proof gate is active and ready.",
-      customerVisible: false,
-      debugVisible: true,
-      orchestrationReady: true,
-    }));
-  }
-
-  return assets;
-}
-
-// ── Main Scanner ──────────────────────────────────────────────────────────────
-
-function scanAiWorkspaceAssets(cwd) {
-  const assets = [
-    ...scanRootInstructions(cwd),
-    ...scanEditorInstructions(cwd),
-    ...scanAgentConfigDirs(cwd),
-    ...scanSkills(cwd),
-    ...scanMcpConfigs(cwd),
-    ...scanHookConfigs(cwd),
-    ...scanPackageScripts(cwd),
-    ...scanAvoreloPacks(cwd),
-  ];
-  return assets;
-}
-
-// ── Hygiene Findings ──────────────────────────────────────────────────────────
-
-function buildHygieneFindings(assets) {
-  const findings = [];
-
-  // Duplicate instruction surfaces
-  const instructionTypes = ["agent_instruction", "claude_instruction", "codex_instruction", "gemini_instruction"];
-  const byType = new Map();
-  for (const asset of assets) {
-    if (instructionTypes.includes(asset.type)) {
-      if (!byType.has(asset.type)) byType.set(asset.type, []);
-      byType.get(asset.type).push(asset.name);
-    }
-  }
-  for (const [type, names] of byType.entries()) {
-    if (names.length > 1) {
-      findings.push({
-        code: FINDING_CODES.DUPLICATE_INSTRUCTION_SURFACE,
-        severity: "warn",
-        message: `Multiple ${type} files detected: ${names.join(", ")}. Only one will typically be read.`,
-        assetNames: names,
-      });
-    }
-  }
-
-  // Check for conflicting agent instructions (AGENTS.md + CLAUDE.md both present)
-  const hasAgents = assets.some((a) => a.type === "agent_instruction" && a.name === "AGENTS.md");
-  const hasClaude = assets.some((a) => a.type === "claude_instruction" && a.name === "CLAUDE.md");
-  if (hasAgents && hasClaude) {
-    findings.push({
-      code: FINDING_CODES.CONFLICTING_INSTRUCTION_SURFACES,
-      severity: "info",
-      message: "Both AGENTS.md and CLAUDE.md are present. These are read by different agents; verify intent is consistent.",
-      assetNames: ["AGENTS.md", "CLAUDE.md"],
-    });
-  }
-
-  // High context cost assets
-  for (const asset of assets) {
-    if (asset.contextCost === "high") {
-      findings.push({
-        code: FINDING_CODES.HIGH_CONTEXT_COST_ASSET,
-        severity: "warn",
-        message: `Asset '${asset.name}' (${asset.type}) has high context cost. Loading it always-on wastes tokens.`,
-        assetNames: [asset.name],
-      });
-    }
-  }
-
-  // Skills missing triggers
-  const skillsNoTrigger = assets.filter((a) => a.type === "skill" && a.reasonCodes.includes(FINDING_CODES.MISSING_SKILL_TRIGGERS));
-  if (skillsNoTrigger.length > 0) {
-    findings.push({
-      code: FINDING_CODES.MISSING_SKILL_TRIGGERS,
-      severity: "info",
-      message: `${skillsNoTrigger.length} skill file(s) have no activation triggers. These may be loaded always-on.`,
-      assetNames: skillsNoTrigger.map((a) => a.name),
-    });
-  }
-
-  // Unknown MCP servers
-  const unknownMcp = assets.filter((a) => a.type === "mcp_server" && a.reviewStatus === "unknown");
-  if (unknownMcp.length > 0) {
-    findings.push({
-      code: FINDING_CODES.UNKNOWN_MCP_SERVER,
-      severity: "warn",
-      message: `${unknownMcp.length} MCP server(s) with unknown source: ${unknownMcp.map((a) => a.name).join(", ")}.`,
-      assetNames: unknownMcp.map((a) => a.name),
-    });
-  }
-
-  // Broad MCP tool capabilities
-  const broadMcp = assets.filter((a) => a.type === "mcp_server" && a.reasonCodes.includes(FINDING_CODES.BROAD_MCP_TOOL_CAPABILITY));
-  if (broadMcp.length > 0) {
-    findings.push({
-      code: FINDING_CODES.BROAD_MCP_TOOL_CAPABILITY,
-      severity: "warn",
-      message: `${broadMcp.length} MCP server(s) have broad capabilities (write/network/execute/secrets/deploy).`,
-      assetNames: broadMcp.map((a) => a.name),
-    });
-  }
-
-  // Risky package scripts
-  const riskyScripts = assets.filter((a) => a.type === "package_script");
-  if (riskyScripts.length > 0) {
-    findings.push({
-      code: FINDING_CODES.RISKY_PACKAGE_SCRIPT,
-      severity: "warn",
-      message: `${riskyScripts.length} package script(s) have deploy/network/destructive risk: ${riskyScripts.map((a) => a.name).join(", ")}.`,
-      assetNames: riskyScripts.map((a) => a.name),
-    });
-  }
-
-  // Secret-like references
-  const secretRefs = assets.filter((a) => a.reasonCodes.includes(FINDING_CODES.SECRET_LIKE_REFERENCE));
-  if (secretRefs.length > 0) {
-    findings.push({
-      code: FINDING_CODES.SECRET_LIKE_REFERENCE,
-      severity: "high",
-      message: `${secretRefs.length} asset(s) may reference secrets or credentials. Redacted in output.`,
-      assetNames: secretRefs.map((a) => a.name),
-    });
-  }
-
-  // Adapter/core logic leakage
-  const leakAssets = assets.filter((a) => a.reasonCodes.includes(FINDING_CODES.ADAPTER_CORE_LOGIC_LEAKAGE));
-  if (leakAssets.length > 0) {
-    findings.push({
-      code: FINDING_CODES.ADAPTER_CORE_LOGIC_LEAKAGE,
-      severity: "warn",
-      message: `${leakAssets.length} asset(s) appear to contain adapter or internal policy content that should not be exposed directly.`,
-      assetNames: leakAssets.map((a) => a.name),
-    });
-  }
-
-  // Missing proof gate
-  const hasProofGate = assets.some((a) => a.type === "proof_gate");
-  if (!hasProofGate) {
-    findings.push({
-      code: FINDING_CODES.MISSING_PROOF_GATE,
-      severity: "info",
-      message: "No orchestration proof gate found. Run a task to establish proof coverage.",
-      assetNames: [],
-    });
-  }
-
-  return findings;
-}
-
-// ── Capability Registry Metadata ──────────────────────────────────────────────
-
-const CAPABILITY_REGISTRY_METADATA = Object.freeze([
-  {
-    id: "ai_workspace_hygiene_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "AI Workspace Hygiene",
-    description: "Detect and normalize AI workspace assets for hygiene and capability metadata.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "context"],
-    proofValue: "medium",
-    safetyControls: ["local_scan_only", "no_execution", "no_network"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "ai_workspace_asset_inventory_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "AI Workspace Asset Inventory",
-    description: "Build a normalized inventory of AI workspace assets from local repo files.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "context"],
-    proofValue: "medium",
-    safetyControls: ["local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "capability_registry_metadata_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Capability Registry Metadata",
-    description: "Enrich capability IDs with trust, scope, context-cost, stage, and worker metadata for future orchestration.",
-    lifecycleStages: ["session_start", "prompt_submit"],
-    stageHints: ["inspect", "plan"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "routing"],
-    proofValue: "medium",
-    safetyControls: ["local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "workspace_skill_hygiene_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Workspace Skill Hygiene",
-    description: "Detect skill files missing triggers, stage hints, or at risk of full-body context loading.",
-    lifecycleStages: ["prompt_submit"],
-    stageHints: ["inspect"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "context"],
-    proofValue: "low",
-    safetyControls: ["local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "instruction_surface_hygiene_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Instruction Surface Hygiene",
-    description: "Detect duplicate, conflicting, or overly-heavy agent instruction files.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "context"],
-    proofValue: "low",
-    safetyControls: ["local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "mcp_workspace_visibility_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "MCP Workspace Visibility",
-    description: "Detect and classify MCP config files and servers without executing them.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["human_approval"],
-    riskLevel: "medium",
-    contextCost: "none",
-    trustLevel: "medium",
-    scopes: ["repo"],
-    capabilities: ["read"],
-    proofValue: "medium",
-    safetyControls: ["no_execution", "no_network", "local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: false,
-    adapterReady: false,
-  },
-  {
-    id: "hook_surface_visibility_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Hook Surface Visibility",
-    description: "Detect lifecycle hook configs and classify their stage without installing or running hooks.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "none",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read"],
-    proofValue: "low",
-    safetyControls: ["no_execution", "local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-  {
-    id: "package_script_hygiene_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Package Script Hygiene",
-    description: "Flag risky deploy/network/destructive package scripts without running them.",
-    lifecycleStages: ["session_start"],
-    stageHints: ["inspect"],
-    workerHints: ["human_approval"],
-    riskLevel: "medium",
-    contextCost: "none",
-    trustLevel: "medium",
-    scopes: ["repo", "command"],
-    capabilities: ["read"],
-    proofValue: "low",
-    safetyControls: ["no_execution", "local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: false,
-    adapterReady: false,
-  },
-  {
-    id: "orchestration_ready_capability_metadata_basic",
-    family: "ai_workspace_hygiene",
-    displayName: "Orchestration-Ready Capability Metadata",
-    description: "Attach workerHints, stageHints, contextCost, riskLevel, and trustLevel to capability registry entries for future orchestration.",
-    lifecycleStages: ["session_start", "prompt_submit"],
-    stageHints: ["inspect", "plan"],
-    workerHints: ["local_or_cheap"],
-    riskLevel: "low",
-    contextCost: "low",
-    trustLevel: "high",
-    scopes: ["repo"],
-    capabilities: ["read", "routing"],
-    proofValue: "high",
-    safetyControls: ["local_scan_only"],
-    autoUsable: true,
-    requiresApproval: false,
-    customerVisible: false,
-    debugVisible: true,
-    orchestrationReady: true,
-    adapterReady: false,
-  },
-]);
-
-// ── Report Builder ────────────────────────────────────────────────────────────
-
-function scoreFromAssets(assets, findings) {
-  let score = 100;
-  for (const f of findings) {
-    if (f.severity === "high") score -= 15;
-    else if (f.severity === "warn") score -= 8;
-    else if (f.severity === "info") score -= 3;
-  }
-  const unknownAssets = assets.filter((a) => a.reviewStatus === "unknown").length;
-  score -= Math.min(unknownAssets * 3, 20);
-  return Math.max(0, Math.min(100, score));
-}
-
-function statusFromScore(score) {
-  if (score >= 80) return "pass";
-  if (score >= 50) return "warn";
-  return "fail";
-}
-
-function nextActionFromFindings(findings) {
-  const high = findings.find((f) => f.severity === "high");
-  if (high) return `Address: ${high.message}`;
-  const warn = findings.find((f) => f.severity === "warn");
-  if (warn) return `Review: ${warn.message}`;
-  return "AI workspace hygiene is clean. Proceed with confidence.";
-}
-
-function buildHygieneReport(cwd, options = {}) {
-  ensureCcoDirs(cwd);
-  const assets = scanAiWorkspaceAssets(cwd);
-  const findings = buildHygieneFindings(assets);
-  const score = scoreFromAssets(assets, findings);
-  const status = statusFromScore(score);
-  const isDebug = Boolean(options.debug);
-
-  const readyAssets = assets.filter((a) => a.status === "ready");
-  const needsReviewAssets = assets.filter((a) => a.status === "needs_review");
-  const blockedAssets = assets.filter((a) => a.status === "blocked");
-  const unknownAssets = assets.filter((a) => a.reviewStatus === "unknown");
-  const highRiskAssets = assets.filter((a) => ["high", "critical"].includes(a.riskLevel));
-  const highContextCostAssets = assets.filter((a) => a.contextCost === "high");
-  const unknownMcpServers = assets.filter((a) => a.type === "mcp_server" && a.reviewStatus === "unknown");
-  const riskyPackageScripts = assets.filter((a) => a.type === "package_script");
-
-  const duplicateInstructionFindings = findings.filter((f) => f.code === FINDING_CODES.DUPLICATE_INSTRUCTION_SURFACE);
-  const missingProofGates = findings.filter((f) => f.code === FINDING_CODES.MISSING_PROOF_GATE);
-
-  const cleanAndReady = readyAssets.slice(0, 5).map((a) => a.name);
-  const needsReviewList = needsReviewAssets.slice(0, 5).map((a) => `${a.name} (${a.type})`);
-  const protectedList = unknownMcpServers.slice(0, 3).map((a) => `${a.name} (unknown MCP — not auto-trusted)`);
-
-  const savedOrAvoided = [];
-  if (highContextCostAssets.length > 0) {
-    savedOrAvoided.push(`${highContextCostAssets.length} high-context-cost asset(s) kept out of automatic loading — context waste may be avoided.`);
-  }
-  if (unknownMcpServers.length > 0) {
-    savedOrAvoided.push(`${unknownMcpServers.length} unknown MCP server(s) isolated from auto-trust — execution risk reduced.`);
-  }
-
-  const topReasonCodes = unique(
-    findings.flatMap((f) => [f.code])
-  ).slice(0, 5);
-
-  const report = {
-    contract: HYGIENE_CONTRACT,
-    schemaVersion: HYGIENE_SCHEMA_VERSION,
-    createdAt: nowIso(),
-    status,
-    score,
-    summary: {
-      totalAssets: assets.length,
-      readyAssets: readyAssets.length,
-      needsReviewAssets: needsReviewAssets.length,
-      blockedAssets: blockedAssets.length,
-      unknownAssets: unknownAssets.length,
-      highRiskAssets: highRiskAssets.length,
-      highContextCostAssets: highContextCostAssets.length,
-      duplicateInstructionGroups: duplicateInstructionFindings.length,
-      unknownMcpServers: unknownMcpServers.length,
-      riskyPackageScripts: riskyPackageScripts.length,
-      missingProofGates: missingProofGates.length,
-    },
-    cleanAndReady,
-    needsReview: needsReviewList,
-    protected: protectedList,
-    savedOrAvoided,
-    nextAction: nextActionFromFindings(findings),
-    topReasonCodes,
-    debugReportPath: LATEST_DEBUG_REPORT_REL,
-    redacted: true,
-  };
-
-  // Write compact report
-  safeWriteJson(cwd, LATEST_REPORT_REL, report);
-
-  // Write debug report with full asset list
-  const debugReport = {
-    ...report,
-    assets: isDebug ? assets : assets.map((a) => ({
-      id: a.id, type: a.type, name: a.name, path: a.path,
-      status: a.status, riskLevel: a.riskLevel, contextCost: a.contextCost,
-      reviewStatus: a.reviewStatus, reasonCodes: a.reasonCodes,
-    })),
-    findings,
-    capabilityRegistryMetadata: CAPABILITY_REGISTRY_METADATA,
-  };
-  safeWriteJson(cwd, LATEST_DEBUG_REPORT_REL, debugReport);
-
-  // Product-learning events
-  try {
-    appendProductLearningEvent(cwd, {
-      eventName: "ai_workspace_hygiene_scanned",
-      category: "workspace_hygiene",
-      surface: "local",
-      status: "observed",
-      payload: {
-        totalAssets: assets.length,
-        readyAssets: readyAssets.length,
-        needsReviewAssets: needsReviewAssets.length,
-        unknownAssets: unknownAssets.length,
-        highRiskAssets: highRiskAssets.length,
-        unknownMcpServers: unknownMcpServers.length,
-        riskyPackageScripts: riskyPackageScripts.length,
-        findingsCount: findings.length,
-        score,
-        status,
-        topReasonCodes,
-      },
-    });
-    appendProductLearningEvent(cwd, {
-      eventName: "ai_workspace_capability_registry_built",
-      category: "workspace_hygiene",
-      surface: "local",
-      status: "observed",
-      payload: {
-        capabilityCount: CAPABILITY_REGISTRY_METADATA.length,
-        orchestrationReadyCount: CAPABILITY_REGISTRY_METADATA.filter((c) => c.orchestrationReady).length,
-      },
-    });
-  } catch {
-    // Non-fatal
-  }
-
-  return { report, assets, findings };
-}
-
-// ── Compact Surface ───────────────────────────────────────────────────────────
-
-function buildAiWorkspaceHygieneSurface(cwd) {
-  const reportPath = path.join(cwd, LATEST_REPORT_REL);
-  if (!fs.existsSync(reportPath)) {
-    return {
-      status: "not_run",
-      score: null,
-      totalAssets: null,
-      needsReview: null,
-      highRisk: null,
-      highContextCost: null,
-      nextAction: "Run `avorelo workspace-hygiene` to scan the AI workspace.",
-      latestReportPath: null,
-    };
-  }
-
-  let report = null;
-  try {
-    report = JSON.parse(fs.readFileSync(reportPath, "utf8"));
-  } catch {
-    return {
-      status: "error",
-      score: null,
-      totalAssets: null,
-      needsReview: null,
-      highRisk: null,
-      highContextCost: null,
-      nextAction: "Report file is unreadable. Re-run `avorelo workspace-hygiene`.",
-      latestReportPath: LATEST_REPORT_REL,
-    };
-  }
-
-  return {
-    status: report.status || "unknown",
-    score: report.score ?? null,
-    totalAssets: report.summary?.totalAssets ?? null,
-    needsReview: report.summary?.needsReviewAssets ?? null,
-    highRisk: report.summary?.highRiskAssets ?? null,
-    highContextCost: report.summary?.highContextCostAssets ?? null,
-    nextAction: report.nextAction || null,
-    latestReportPath: LATEST_REPORT_REL,
-  };
-}
-
-// ── CLI Renderers ─────────────────────────────────────────────────────────────
-
-function renderHygieneText(report, options = {}) {
-  if (!report) return "AI Workspace Hygiene: not run. Use `avorelo workspace-hygiene` to scan.\n";
-
-  const statusEmoji = report.status === "pass" ? "✓" : report.status === "warn" ? "⚠" : "✗";
-  const lines = [
-    `AI Workspace Hygiene: ${statusEmoji} ${String(report.status).toUpperCase()} (score: ${report.score}/100)`,
-    "",
-    `Assets: ${report.summary.totalAssets} total · ${report.summary.readyAssets} ready · ${report.summary.needsReviewAssets} needs review · ${report.summary.highRiskAssets} high-risk`,
-  ];
-
-  if (report.cleanAndReady.length > 0) {
-    lines.push(`Clean/ready: ${report.cleanAndReady.join(", ")}`);
-  }
-  if (report.needsReview.length > 0) {
-    lines.push(`Needs review: ${report.needsReview.join(", ")}`);
-  }
-  if (report.protected.length > 0) {
-    lines.push(`Protected (not auto-trusted): ${report.protected.join(", ")}`);
-  }
-  if (report.savedOrAvoided.length > 0) {
-    for (const s of report.savedOrAvoided) lines.push(`Saved/avoided: ${s}`);
-  }
-  lines.push("", `Next action: ${report.nextAction}`);
-  if (!options.debug) {
-    lines.push(`Full detail: avorelo workspace-hygiene --debug`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}
-
-function renderHygieneDebugText(report, assets, findings) {
-  if (!report || !assets) return "No workspace hygiene debug data available.\n";
-  const lines = [
-    `AI Workspace Hygiene — Debug Report`,
-    `Status: ${report.status} · Score: ${report.score}/100`,
-    `Assets: ${assets.length} total`,
-    "",
-    "── Asset List ──────────────────────────────────────────",
-  ];
-  for (const asset of assets) {
-    lines.push(`  [${asset.type}] ${asset.name} (${asset.path})`);
-    lines.push(`    status=${asset.status} risk=${asset.riskLevel} context=${asset.contextCost} trust=${asset.trustLevel}`);
-    if (asset.reasonCodes.length > 0) lines.push(`    reasons: ${asset.reasonCodes.join(", ")}`);
-    if (asset.recommendedAction) lines.push(`    action: ${asset.recommendedAction}`);
-  }
-  lines.push("", "── Findings ────────────────────────────────────────────");
-  if (findings.length === 0) {
-    lines.push("  No findings.");
-  } else {
-    for (const f of findings) {
-      lines.push(`  [${f.severity.toUpperCase()}] ${f.code}: ${f.message}`);
-    }
-  }
-  lines.push("", "── Capability Registry Metadata ────────────────────────");
-  for (const cap of CAPABILITY_REGISTRY_METADATA) {
-    lines.push(`  ${cap.id} (${cap.family}) — orchestration-ready: ${cap.orchestrationReady}`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}
-
-// ── Exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  HYGIENE_CONTRACT,
-  HYGIENE_SCHEMA_VERSION,
-  LATEST_REPORT_REL,
-  LATEST_DEBUG_REPORT_REL,
-  FINDING_CODES,
-  CAPABILITY_REGISTRY_METADATA,
-  scanAiWorkspaceAssets,
-  buildHygieneFindings,
-  buildHygieneReport,
-  buildAiWorkspaceHygieneSurface,
-  renderHygieneText,
-  renderHygieneDebugText,
-};