avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/capability-hygiene.js

@@ -0,0 +1,504 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.capabilityHygiene.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/capability-hygiene";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const MAX_FILES = 1500;
+const MAX_FINDINGS = 25;
+const MAX_EVIDENCE_REFS_PER_FINDING = 3;
+
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "coverage", ".next", ".nuxt", ".turbo", ".wasp", "temp",
+]);
+
+const EXTERNAL_WRITE_CATEGORIES = new Set([
+  "browser", "network", "deploy", "billing", "write", "external",
+]);
+
+const RISKY_CATEGORIES = new Set([
+  "browser", "network", "deploy", "billing", "write", "external", "admin", "delete",
+]);
+
+const CONTEXT_HEAVY_CATEGORIES = new Set([
+  "full_codebase", "repo_map", "large_context", "workspace_scan",
+]);
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/(?:sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16})/g, "[redacted-token]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .trim();
+  if (!text) return null;
+  return text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text;
+}
+
+function sanitizeRef(ref) {
+  const text = toPosix(String(ref || "").trim());
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function makeEvidenceRef(relPath, label) {
+  const base = sanitizeRef(relPath);
+  if (!base) return null;
+  const note = label ? ` (${sanitizeText(label, 80)})` : "";
+  return `${base}${note}`;
+}
+
+function severityRank(severity) {
+  if (severity === "block") return 3;
+  if (severity === "warn") return 2;
+  if (severity === "info") return 1;
+  return 0;
+}
+
+// ── Load capability kernel and related evidence ─────────────────────────────
+
+function loadCapabilityRegistry(cwd) {
+  try {
+    // Only load kernel if cwd contains the capability registry
+    const regPath = path.join(cwd, "scripts", "lib", "capability-registry.js");
+    if (!fs.existsSync(regPath)) return [];
+    const reg = require("./capability-registry");
+    if (typeof reg.listCapabilities === "function") return reg.listCapabilities();
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+function loadCapabilityManifests(cwd) {
+  const manifests = [];
+  const manifestDir = path.join(cwd, ".claude", "cco", "state");
+  try {
+    if (!fs.existsSync(manifestDir)) return manifests;
+    for (const entry of fs.readdirSync(manifestDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(manifestDir, entry.name), "utf8").replace(/^/, ""));
+        if (data && typeof data === "object") {
+          manifests.push({ file: toPosix(`.claude/cco/state/${entry.name}`), data });
+        }
+      } catch {}
+    }
+  } catch {}
+  return manifests;
+}
+
+function loadGovernedExposure(cwd) {
+  return safeReadJson(cwd, ".claude/cco/orchestration/governed-action-exposure/latest-report.json", null);
+}
+
+function loadSkillsOperatingLayer(cwd) {
+  return safeReadJson(cwd, ".claude/cco/orchestration/skills-operating-layer/latest-report.json", null);
+}
+
+function loadCapabilityIntake(cwd) {
+  return safeReadJson(cwd, ".claude/cco/orchestration/capability-intake/latest-report.json", null);
+}
+
+// ── Core analysis ───────────────────────────────────────────────────────────
+
+function buildCapabilityHygieneReport(cwd = process.cwd(), options = {}) {
+  const limitsApplied = [];
+  const findings = [];
+  const seenCodes = new Set();
+
+  function addFinding(severity, reasonCode, title, safeNextAction, evidenceRefs) {
+    if (findings.length >= MAX_FINDINGS) {
+      if (!limitsApplied.includes("MAX_FINDINGS_REACHED")) limitsApplied.push("MAX_FINDINGS_REACHED");
+      return;
+    }
+    if (seenCodes.has(reasonCode)) return;
+    seenCodes.add(reasonCode);
+    findings.push({
+      severity,
+      reasonCode,
+      title: sanitizeText(title, 220),
+      safeNextAction: sanitizeText(safeNextAction, 220),
+      evidenceRefs: (evidenceRefs || []).slice(0, MAX_EVIDENCE_REFS_PER_FINDING).filter(Boolean),
+    });
+  }
+
+  // Load evidence sources
+  const registry = loadCapabilityRegistry(cwd);
+  const manifests = loadCapabilityManifests(cwd);
+  const governedExposure = loadGovernedExposure(cwd);
+  const skillsLayer = loadSkillsOperatingLayer(cwd);
+  const capabilityIntake = loadCapabilityIntake(cwd);
+
+  const capabilitiesInspected = registry.length;
+
+  // No data path
+  if (capabilitiesInspected === 0 && manifests.length === 0) {
+    const emptyReport = buildEmptyReport(limitsApplied);
+    if (options.write !== false) {
+      safeWriteJson(cwd, REPORT_JSON_REL, emptyReport);
+    }
+    return emptyReport;
+  }
+
+  addFinding("info", "CAP_HYGIENE_KERNEL_FOUND", `Capability Kernel loaded with ${capabilitiesInspected} capabilities`, "Kernel is available for hygiene checks.", [makeEvidenceRef("scripts/lib/capability-registry.js", "kernel source")]);
+
+  // ── Check 1: too many capabilities ──
+  const MAX_REASONABLE = 40;
+  if (capabilitiesInspected > MAX_REASONABLE) {
+    addFinding("warn", "CAP_HYGIENE_TOO_MANY_CAPABILITIES", `${capabilitiesInspected} capabilities registered, which exceeds the ${MAX_REASONABLE}-capability hygiene threshold`, "Review whether all capabilities are needed for the current task scope.", [makeEvidenceRef("scripts/lib/capability-registry.js", `${capabilitiesInspected} capabilities`)]);
+  } else {
+    addFinding("info", "CAP_HYGIENE_CAPABILITY_COUNT_OK", `Capability count (${capabilitiesInspected}) within hygiene threshold`, "No action needed.", []);
+  }
+
+  // ── Check 2: duplicate capability families ──
+  const familySeen = new Map();
+  for (const cap of registry) {
+    const family = cap.familyId || cap.family || "unknown";
+    if (!familySeen.has(family)) {
+      familySeen.set(family, []);
+    }
+    familySeen.get(family).push(cap.id || cap.name || "unnamed");
+  }
+  for (const [family, ids] of familySeen) {
+    if (ids.length > 3) {
+      addFinding("warn", "CAP_HYGIENE_DUPLICATE_CAPABILITY", `Family '${family}' has ${ids.length} capabilities — possible duplication`, "Review whether multiple capabilities in this family serve distinct purposes.", [makeEvidenceRef("scripts/lib/capability-registry.js", `family: ${family}`)]);
+    }
+  }
+
+  // ── Check 3: stale capabilities ──
+  for (const cap of registry) {
+    const status = cap.productStatus || cap.status;
+    if (status === "gap" || status === "docs_only") {
+      addFinding("warn", "CAP_HYGIENE_STALE_CAPABILITY", `Capability '${cap.id || cap.name}' has status '${status}' — may be stale or unimplemented`, "Verify whether this capability is still needed or should be removed.", [makeEvidenceRef("scripts/lib/capability-registry.js", `${cap.id}: ${status}`)]);
+    }
+  }
+
+  // ── Check 4: missing dogfood evidence ──
+  const dogfoodDir = path.join(cwd, "docs", "dogfood");
+  const hasDogfoodDir = fs.existsSync(dogfoodDir);
+  if (!hasDogfoodDir) {
+    addFinding("warn", "CAP_HYGIENE_MISSING_DOGFOOD", "No docs/dogfood directory found — capabilities lack dogfood evidence", "Create dogfood docs for active capabilities.", []);
+  }
+
+  // ── Check 5: missing proof/evidence refs ──
+  const evidenceDir = path.join(cwd, ".claude", "cco", "evidence");
+  const hasEvidence = fs.existsSync(evidenceDir);
+  if (!hasEvidence) {
+    addFinding("warn", "CAP_HYGIENE_MISSING_PROOF", "No .claude/cco/evidence directory found — capabilities may lack proof references", "Run proof-generating commands to build evidence.", []);
+  }
+
+  // ── Check 6: external/write/browser/network/deploy/billing exposure ──
+  if (governedExposure && typeof governedExposure === "object") {
+    const exposedActions = governedExposure.exposedActions || governedExposure.actions || [];
+    for (const action of (Array.isArray(exposedActions) ? exposedActions : [])) {
+      const cat = String(action.category || action.type || "").toLowerCase();
+      if (EXTERNAL_WRITE_CATEGORIES.has(cat)) {
+        const gateFound = action.policyGate || action.approvalRequired || action.blocked;
+        if (!gateFound) {
+          addFinding("block", "CAP_HYGIENE_EXTERNAL_WRITE_EXPOSED", `External/write capability '${action.name || cat}' is exposed without a policy gate`, "Add a policy gate or approval requirement for this capability.", [makeEvidenceRef(".claude/cco/orchestration/governed-action-exposure/latest-report.json", cat)]);
+        } else {
+          addFinding("info", "CAP_HYGIENE_POLICY_GATE_FOUND", `Policy gate found for external capability '${action.name || cat}'`, "No action needed.", [makeEvidenceRef(".claude/cco/orchestration/governed-action-exposure/latest-report.json", cat)]);
+        }
+      }
+      if (cat === "browser") {
+        addFinding("warn", "CAP_HYGIENE_BROWSER_CAPABILITY_EXPOSED", `Browser capability '${action.name || "browser"}' is exposed`, "Verify browser capability is needed for current task.", [makeEvidenceRef(".claude/cco/orchestration/governed-action-exposure/latest-report.json", "browser")]);
+      }
+      if (cat === "deploy") {
+        addFinding("warn", "CAP_HYGIENE_DEPLOY_CAPABILITY_EXPOSED", `Deploy capability '${action.name || "deploy"}' is exposed`, "Verify deploy capability is needed for current task.", [makeEvidenceRef(".claude/cco/orchestration/governed-action-exposure/latest-report.json", "deploy")]);
+      }
+      if (cat === "billing") {
+        addFinding("warn", "CAP_HYGIENE_BILLING_CAPABILITY_EXPOSED", `Billing capability '${action.name || "billing"}' is exposed`, "Verify billing capability is needed for current task.", [makeEvidenceRef(".claude/cco/orchestration/governed-action-exposure/latest-report.json", "billing")]);
+      }
+    }
+  }
+
+  // ── Check 7: broad permissions for small tasks ──
+  if (governedExposure && typeof governedExposure === "object") {
+    const taskScope = governedExposure.taskScope || governedExposure.scope;
+    const scopeSize = String(taskScope || "").toLowerCase();
+    const exposedCount = Array.isArray(governedExposure.exposedActions) ? governedExposure.exposedActions.length : 0;
+    if ((scopeSize === "small" || scopeSize === "bounded") && exposedCount > 10) {
+      addFinding("warn", "CAP_HYGIENE_PERMISSION_TOO_BROAD", `${exposedCount} actions exposed for a '${scopeSize}' task — permissions may be too broad`, "Consider suppressing capabilities not needed for this task scope.", []);
+    }
+  }
+
+  // ── Check 8: context-heavy capability for small task ──
+  for (const cap of registry) {
+    const cat = String(cap.category || cap.familyId || "").toLowerCase();
+    if (CONTEXT_HEAVY_CATEGORIES.has(cat)) {
+      addFinding("warn", "CAP_HYGIENE_CONTEXT_HEAVY_FOR_TASK", `Context-heavy capability '${cap.id || cap.name}' is available — verify it's needed`, "Suppress if current task does not require full codebase context.", [makeEvidenceRef("scripts/lib/capability-registry.js", cap.id || cap.name)]);
+    }
+  }
+
+  // ── Check 9: policy gate missing for risky capabilities ──
+  for (const cap of registry) {
+    const surfaces = Array.isArray(cap.surfaces) ? cap.surfaces : [];
+    const hasApproval = surfaces.some(s => s === "approval" || s === "block");
+    const cat = String(cap.category || cap.familyId || "").toLowerCase();
+    if (RISKY_CATEGORIES.has(cat) && !hasApproval) {
+      addFinding("warn", "CAP_HYGIENE_POLICY_GATE_MISSING", `Risky capability '${cap.id || cap.name}' in category '${cat}' has no approval/block surface`, "Add an approval gate for this capability.", [makeEvidenceRef("scripts/lib/capability-registry.js", cap.id || cap.name)]);
+    }
+  }
+
+  // ── Build suppression recommendations ──
+  const kept = [];
+  const suppressed = [];
+  const approvalRequired = [];
+
+  for (const f of findings) {
+    if (f.reasonCode === "CAP_HYGIENE_EXTERNAL_WRITE_EXPOSED" && f.severity === "block") {
+      approvalRequired.push(f.title);
+    } else if (f.reasonCode.includes("SUPPRESSION") || f.reasonCode.includes("CONTEXT_HEAVY") || f.reasonCode.includes("BROWSER") || f.reasonCode.includes("DEPLOY") || f.reasonCode.includes("BILLING")) {
+      suppressed.push(f.title);
+    }
+  }
+
+  const keptCount = capabilitiesInspected - suppressed.length;
+  if (keptCount > 0) {
+    kept.push(`${keptCount} capabilities kept after hygiene review`);
+  }
+
+  // ── Determine overall status ──
+  const hasBlock = findings.some(f => f.severity === "block");
+  const hasWarn = findings.some(f => f.severity === "warn");
+  const status = hasBlock ? "blocked" : hasWarn ? "warn" : "pass";
+
+  const warnCount = findings.filter(f => f.severity === "warn").length;
+  const blockCount = findings.filter(f => f.severity === "block").length;
+  const infoCount = findings.filter(f => f.severity === "info").length;
+
+  const safeNextAction = hasBlock
+    ? "Resolve blocked capabilities before proceeding. Add policy gates for exposed external/write access."
+    : hasWarn
+      ? "Review warned capabilities and consider suppressing unused or overly broad ones."
+      : "Capability exposure is bounded and evidence-backed. Safe to proceed.";
+
+  const report = {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      title: "Capability Hygiene & Over-Skilling Control",
+      text: `${capabilitiesInspected} capabilities inspected. ${keptCount} kept, ${suppressed.length} suppressed, ${approvalRequired.length} need approval.`,
+      findingCounts: {
+        info: infoCount,
+        warn: warnCount,
+        block: blockCount,
+      },
+      safeNextAction,
+    },
+    surfaceEvidence: {
+      filesInspected: manifests.length,
+      artifactsInspected: manifests.length + (governedExposure ? 1 : 0) + (skillsLayer ? 1 : 0) + (capabilityIntake ? 1 : 0),
+      capabilitiesInspected,
+      limitsApplied,
+    },
+    findings: findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity)),
+    capabilityAnalysis: {
+      kept,
+      suppressed,
+      approvalRequired,
+    },
+    productHome: {
+      cardSource: "capability-hygiene",
+      status,
+      found: findings.filter(f => f.severity === "warn" || f.severity === "block").map(f => sanitizeText(f.title, 120)).slice(0, 5),
+      fixedOrPrepared: suppressed.length > 0 ? [`Prepared a smaller capability set (${suppressed.length} suppressed)`] : [],
+      savedOrProved: suppressed.length > 0 ? [`Suppressed ${suppressed.length} irrelevant capability candidate(s)`] : [],
+      forReview: approvalRequired.map(t => sanitizeText(t, 120)).slice(0, 3),
+      safeNextAction,
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "heuristic",
+      publicClaimAllowed: false,
+      evidenceRefs: [makeEvidenceRef(REPORT_JSON_REL, "capability hygiene report")].filter(Boolean),
+      caveat: "Hygiene checks are heuristic-based static analysis. No exact token or cost savings measured.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      registryCalls: false,
+      rawDump: false,
+      autoFix: false,
+    },
+  };
+
+  if (options.write !== false) {
+    safeWriteJson(cwd, REPORT_JSON_REL, report);
+  }
+
+  return report;
+}
+
+function buildEmptyReport(limitsApplied = []) {
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      title: "Capability Hygiene & Over-Skilling Control",
+      text: "No capability or kernel evidence found.",
+      findingCounts: { info: 0, warn: 0, block: 0 },
+      safeNextAction: "No capability evidence available. Run capability registration or kernel commands first.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      capabilitiesInspected: 0,
+      limitsApplied,
+    },
+    findings: [],
+    capabilityAnalysis: { kept: [], suppressed: [], approvalRequired: [] },
+    productHome: {
+      cardSource: "capability-hygiene",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "No capability evidence available.",
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "unavailable",
+      publicClaimAllowed: false,
+      evidenceRefs: [],
+      caveat: "No data to measure against.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      registryCalls: false,
+      rawDump: false,
+      autoFix: false,
+    },
+  };
+}
+
+// ── Generate / Load / Format / Surface ──────────────────────────────────────
+
+function generateCapabilityHygiene(cwd = process.cwd(), options = {}) {
+  const report = buildCapabilityHygieneReport(cwd, options);
+  return { report, reportPath: path.join(cwd, REPORT_JSON_REL) };
+}
+
+function loadCapabilityHygiene(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+function formatCapabilityHygieneText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Capability Hygiene & Over-Skilling Control",
+      "Status: NO DATA",
+      "No capability or kernel evidence found yet.",
+      "Safe next action: Run capability registration or kernel commands first.",
+    ].join("\n");
+  }
+
+  const lines = [
+    "Avorelo Capability Hygiene & Over-Skilling Control",
+    `Status: ${String(report.status || "no_data").toUpperCase()} · redacted=${report.redacted === true ? "yes" : "no"}`,
+    `Capabilities: ${report.surfaceEvidence?.capabilitiesInspected || 0} inspected · info=${report.summary?.findingCounts?.info || 0} · warn=${report.summary?.findingCounts?.warn || 0} · block=${report.summary?.findingCounts?.block || 0}`,
+    "Notes: local static analysis only · no model calls · no network calls",
+  ];
+
+  if (Array.isArray(report.findings) && report.findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const finding of report.findings.slice(0, 5)) {
+      lines.push(`- [${finding.severity}] ${finding.title}${finding.evidenceRefs?.length ? ` · ${finding.evidenceRefs[0]}` : ""}`);
+    }
+    if (report.findings.length > 5) {
+      lines.push(`  ... and ${report.findings.length - 5} more`);
+    }
+  }
+
+  const analysis = report.capabilityAnalysis;
+  if (analysis) {
+    lines.push("");
+    if (analysis.kept.length) lines.push(`Kept: ${analysis.kept.join(", ")}`);
+    if (analysis.suppressed.length) lines.push(`Suppressed: ${analysis.suppressed.length} candidate(s)`);
+    if (analysis.approvalRequired.length) lines.push(`Approval required: ${analysis.approvalRequired.length} capability(s)`);
+  }
+
+  lines.push("");
+  lines.push(`Safe next action: ${report.summary?.safeNextAction || "Review capability exposure before proceeding."}`);
+  return lines.join("\n");
+}
+
+function formatCapabilityHygieneStatusLine(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Capability hygiene: NOT RUN · run `avorelo capability-hygiene --text`";
+  }
+  return `Capability hygiene: ${String(report.status || "no_data").toUpperCase()}`
+    + ` · capabilities=${report.surfaceEvidence?.capabilitiesInspected || 0}`
+    + ` · warn=${report.summary?.findingCounts?.warn || 0}`
+    + ` · block=${report.summary?.findingCounts?.block || 0}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review capability hygiene."}`;
+}
+
+function buildCapabilityHygieneSurface(cwd = process.cwd(), options = {}) {
+  const report = loadCapabilityHygiene(cwd) || (options.buildIfMissing ? buildCapabilityHygieneReport(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      capabilitiesInspected: 0,
+      warnCount: 0,
+      blockCount: 0,
+      nextBestAction: "Run `avorelo capability-hygiene --text` to check capability exposure.",
+      statusLine: "Capability hygiene: NOT RUN · run `avorelo capability-hygiene --text`",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: ["Local heuristic analysis only. No model or network calls."],
+    };
+  }
+
+  return {
+    status: report.status,
+    capabilitiesInspected: report.surfaceEvidence?.capabilitiesInspected || 0,
+    warnCount: report.summary?.findingCounts?.warn || 0,
+    blockCount: report.summary?.findingCounts?.block || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatCapabilityHygieneStatusLine(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: ["Local heuristic analysis only. No model or network calls."],
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildCapabilityHygieneReport,
+  generateCapabilityHygiene,
+  loadCapabilityHygiene,
+  formatCapabilityHygieneText,
+  formatCapabilityHygieneStatusLine,
+  buildCapabilityHygieneSurface,
+};