avorelo 0.1.0

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

@@ -0,0 +1,1499 @@
+"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,
+};