avorelo 0.1.0 → 0.2.0

package/scripts/lib/capability-recommender.js

@@ -1,512 +0,0 @@
-"use strict";
-
-/**
- * Avorelo Capability Recommender
- *
- * Deterministic, local-first recommendation logic.
- * Takes workflow signals (from workflow-signals.js) and local file probes,
- * returns the recommended capability pack and next action.
- *
- * No AI/LLM calls. No external requests. All logic is deterministic and testable.
- *
- * Output:
- *   { recommendedPack, reason, status, entitlement, riskLevel, nextAction,
- *     evidencePath, additionalPacks }
- */
-
-const fs = require("fs");
-const path = require("path");
-const { CAPABILITY_PACKS, getPack } = require("./capability-packs");
-
-// ─── Local file probes ────────────────────────────────────────────────────────
-
-/**
- * Probe local files to detect frontend project signals.
- * Returns { isFrontend, hasPlaywright, hasReact, hasVue, hasNext }
- */
-function probeFrontendSignals(cwd) {
-  const base = cwd || process.cwd();
-  let isFrontend = false;
-  let hasPlaywright = false;
-  let hasReact = false;
-  let hasVue = false;
-  let hasNext = false;
-
-  // Check playwright config files
-  const playwrightFiles = [
-    "playwright.config.ts",
-    "playwright.config.js",
-    "e2e-tests/playwright.config.ts",
-    "e2e-tests/playwright.landing-qa.config.ts",
-  ];
-  for (const rel of playwrightFiles) {
-    if (fs.existsSync(path.join(base, rel))) {
-      hasPlaywright = true;
-      isFrontend = true;
-      break;
-    }
-  }
-
-  // Check package.json for frontend frameworks
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(base, "package.json"), "utf8"));
-    const allDeps = {
-      ...(pkg.dependencies || {}),
-      ...(pkg.devDependencies || {}),
-    };
-    if (allDeps["react"] || allDeps["react-dom"]) { hasReact = true; isFrontend = true; }
-    if (allDeps["vue"]) { hasVue = true; isFrontend = true; }
-    if (allDeps["next"]) { hasNext = true; isFrontend = true; }
-    if (allDeps["vite"] || allDeps["@vitejs/plugin-react"]) { isFrontend = true; }
-    if (allDeps["svelte"] || allDeps["@sveltejs/kit"]) { isFrontend = true; }
-  } catch {
-    // No package.json or parse error — not a frontend signal
-  }
-
-  // Check apps/public-web (Avorelo's own pattern)
-  if (fs.existsSync(path.join(base, "apps/public-web"))) {
-    isFrontend = true;
-  }
-
-  return { isFrontend, hasPlaywright, hasReact, hasVue, hasNext };
-}
-
-/**
- * Probe activation state — is Avorelo activated in this repo?
- */
-function probeActivationState(cwd) {
-  const base = cwd || process.cwd();
-  const activationPaths = [
-    ".claude/cco/state/activation.json",
-    ".claude/cco/config.json",
-    ".claude/cco/state",
-  ];
-  for (const rel of activationPaths) {
-    if (fs.existsSync(path.join(base, rel))) {
-      return { activated: true };
-    }
-  }
-  return { activated: false };
-}
-
-/**
- * Probe for reentry memory / carry-forward state.
- */
-function probeReentryState(cwd) {
-  const base = cwd || process.cwd();
-  const reentryPaths = [
-    ".claude/cco/state/reentry-memory.jsonl",
-    ".claude/cco/state/reentry-carry-forward.json",
-    ".claude/cco/state/reentry-state.json",
-  ];
-  for (const rel of reentryPaths) {
-    try {
-      const stat = fs.statSync(path.join(base, rel));
-      if (stat.size > 0) return { hasReentry: true, path: rel };
-    } catch {
-      // file missing
-    }
-  }
-  return { hasReentry: false, path: null };
-}
-
-function probeWorkspaceSignals(cwd) {
-  const base = cwd || process.cwd();
-  let docsCount = 0;
-  let testsCount = 0;
-  let hasSourceCatalog = false;
-  let hasLocalSkills = false;
-  let hasPackageManifest = false;
-  try {
-    docsCount = fs.existsSync(path.join(base, "docs")) ? fs.readdirSync(path.join(base, "docs")).length : 0;
-    testsCount = fs.existsSync(path.join(base, "tests")) ? fs.readdirSync(path.join(base, "tests")).length : 0;
-    hasSourceCatalog = fs.existsSync(path.join(base, "scripts", "lib", "source-catalog.js"));
-    hasLocalSkills =
-      fs.existsSync(path.join(base, "skills", "avorelo")) ||
-      fs.existsSync(path.join(base, "vendor", "skillpacks"));
-    hasPackageManifest = fs.existsSync(path.join(base, "package.json"));
-  } catch {}
-  return {
-    largeRepo: docsCount + testsCount >= 20,
-    hasSourceCatalog,
-    hasLocalSkills,
-    hasPackageManifest,
-  };
-}
-
-function probeSafePathState(cwd) {
-  const base = cwd || process.cwd();
-  const relPath = ".claude/cco/security/safe-path/latest-receipt.json";
-  const absPath = path.join(base, relPath);
-  if (!fs.existsSync(absPath)) {
-    return { hasSafePath: false, latestReceiptPath: null };
-  }
-  return { hasSafePath: true, latestReceiptPath: relPath };
-}
-
-function probeInstallIntakeState(cwd) {
-  const base = cwd || process.cwd();
-  const relPath = ".claude/cco/security/install-intake/latest-receipt.json";
-  const absPath = path.join(base, relPath);
-  if (!fs.existsSync(absPath)) {
-    return { hasInstallIntake: false, latestReceiptPath: null };
-  }
-  return { hasInstallIntake: true, latestReceiptPath: relPath };
-}
-
-/**
- * Probe for latest evidence / proof receipts.
- */
-function probeEvidencePath(cwd) {
-  const base = cwd || process.cwd();
-  const receiptsDir = path.join(base, ".claude/cco/receipts");
-  try {
-    const files = fs.readdirSync(receiptsDir).filter((f) => f.endsWith(".json"));
-    if (files.length > 0) {
-      const sorted = files
-        .map((f) => ({ f, mtime: fs.statSync(path.join(receiptsDir, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime);
-      return path.posix.join(".claude/cco/receipts", sorted[0].f);
-    }
-  } catch {
-    // no receipts dir
-  }
-  return null;
-}
-
-// ─── Signal → Pack mapping ─────────────────────────────────────────────────────
-
-/**
- * Priority-ordered recommendation rules.
- * Each rule is { test(signals, probes) → boolean, packId, reason, nextAction }.
- * First matching rule wins for recommendedPack.
- * All matching rules contribute to additionalPacks.
- */
-const RECOMMENDATION_RULES = [
-  {
-    packId: "install_intake_risk",
-    reason: "Local intake visibility is relevant because this workspace has package, source, or skill surfaces that should be reviewed before runtime trust.",
-    nextAction: "Run `avorelo intake --json` to scan local intake items, review unknown or deferred sources, and capture a compact intake receipt.",
-    test: (_signals, probes) =>
-      probes.installIntake?.hasInstallIntake === true ||
-      probes.workspace?.hasPackageManifest === true,
-  },
-  {
-    packId: "safe_path_engine",
-    reason: "Guard and governance signals suggest reduced-scope Safe Path recommendations are relevant here.",
-    nextAction: "Run `avorelo guard --action <type> --target <target> --json` to see a bounded Safe Path with approval boundaries and safer alternatives.",
-    test: (signals, probes) =>
-      probes.safePath.hasSafePath === true ||
-      signals.agentSecurityState === "approve" ||
-      signals.agentSecurityState === "enforce" ||
-      Number(signals.riskyIntercepts || 0) > 0,
-  },
-  {
-    packId: "agent_security",
-    reason: "High-risk signals or risky agent intercepts detected in this repo.",
-    nextAction: "Run `avorelo status` to review security findings, then run `avorelo audit` to resolve the top active finding.",
-    test: (signals) =>
-      signals.riskLevel === "high" ||
-      Number(signals.riskyIntercepts || 0) > 0 ||
-      Number(signals.trustAlerts || 0) > 0 ||
-      signals.agentSecurityState === "enforce" ||
-      signals.agentSecurityState === "approve",
-  },
-  {
-    packId: "release_readiness",
-    reason: "Staged changes and validation evidence suggest release readiness is relevant.",
-    nextAction: "Run `avorelo status` to review proof summary, then address remaining gaps before shipping.",
-    test: (signals) =>
-      signals.hasStagedChanges === true &&
-      (signals.validationState === "passed" || signals.validationState === "partial"),
-  },
-  {
-    packId: "source_backed_skills",
-    reason: "Reviewed skill sources and deterministic skill routing are available in this workspace.",
-    nextAction: "Run `avorelo skills route --task \"<task>\"` to select a reviewed skill path before broad work.",
-    test: (_signals, probes) =>
-      probes.workspace.hasSourceCatalog === true && probes.workspace.hasLocalSkills === true,
-  },
-  {
-    packId: "workspace_navigation",
-    reason: "Repo navigation and context reduction look relevant for this workspace.",
-    nextAction: "Run `avorelo workspace-map --json` to generate compact navigation context before broad scans.",
-    test: (signals, probes) =>
-      signals.contextPressure === "warn" ||
-      signals.contextPressure === "critical" ||
-      probes.reentry.hasReentry === true ||
-      probes.workspace.largeRepo === true,
-  },
-  {
-    packId: "workflow_efficiency",
-    reason: "Context pressure or reentry state signals that workflow efficiency is relevant.",
-    nextAction: "Run `avorelo status` to see context budget, carry-forward state, and next actions.",
-    test: (signals, probes) =>
-      signals.contextPressure === "critical" ||
-      signals.contextPressure === "warn" ||
-      probes.reentry.hasReentry === true ||
-      signals.reentryState === "available",
-  },
-  {
-    packId: "frontend_readiness",
-    reason: "Frontend project detected — Visual QA and browser readiness checks are available.",
-    nextAction: "Run `avorelo visual-qa --dry-run` to check Visual QA availability, or `avorelo capabilities --pack frontend_readiness` for details.",
-    test: (_signals, probes) =>
-      probes.frontend.isFrontend === true,
-  },
-  {
-    packId: "agent_readiness",
-    reason: "No activation state found — start with Agent Readiness to get set up safely.",
-    nextAction: "Run `avorelo activate` to set up Avorelo in this repo, then `avorelo doctor` to check readiness.",
-    test: (_signals, probes) =>
-      probes.activation.activated === false,
-  },
-];
-
-/** Fallback when no rule matches */
-const FALLBACK = {
-  packId: "agent_readiness",
-  reason: "No specific signals detected — Agent Readiness is the recommended starting point.",
-  nextAction: "Run `avorelo status` to see current state, or `avorelo doctor` to check setup.",
-};
-
-// ─── Main recommender ──────────────────────────────────────────────────────────
-
-/**
- * Recommend capability packs based on deterministic signals.
- *
- * @param {object} options
- *   @param {string}  options.cwd           - working directory
- *   @param {object}  options.signals        - pre-built workflow signals (from workflow-signals.js)
- *   @param {object}  options.probes         - pre-built local probes (optional, for testing)
- *   @param {string}  options.plan           - 'free' | 'pro'
- * @returns {object} recommendation
- */
-function recommendCapabilities(options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const signals = options.signals || {};
-  const plan = String(options.plan || "free").toLowerCase();
-
-  // Build or use probes
-  const probes = options.probes || {
-    frontend: probeFrontendSignals(cwd),
-    activation: probeActivationState(cwd),
-    reentry: probeReentryState(cwd),
-    workspace: probeWorkspaceSignals(cwd),
-    safePath: probeSafePathState(cwd),
-    installIntake: probeInstallIntakeState(cwd),
-  };
-
-  // Evaluate all rules — first match = recommended, all matches = additional
-  let recommendedRule = null;
-  const additionalPackIds = [];
-
-  for (const rule of RECOMMENDATION_RULES) {
-    let matched = false;
-    try {
-      matched = rule.test(signals, probes);
-    } catch {
-      matched = false;
-    }
-    if (matched) {
-      if (!recommendedRule) {
-        recommendedRule = rule;
-      } else if (rule.packId !== recommendedRule.packId) {
-        additionalPackIds.push(rule.packId);
-      }
-    }
-  }
-
-  // Use fallback if nothing matched
-  const winner = recommendedRule || FALLBACK;
-  const recommendedPack = getPack(winner.packId);
-
-  const additionalPacks = [...new Set(additionalPackIds)]
-    .filter((id) => id !== winner.packId)
-    .map((id) => getPack(id))
-    .filter(Boolean)
-    .slice(0, 3);
-
-  // Determine entitlement
-  const packEntitlement = recommendedPack?.defaultEntitlement || "free";
-  const isGated = packEntitlement === "pro" && plan === "free";
-
-  // Determine status
-  let status = "available";
-  if (isGated) status = "gated";
-  else if (!probes.activation.activated && winner.packId !== "agent_readiness") status = "suggested";
-
-  // Evidence path
-  const evidencePath = probeEvidencePath(cwd);
-
-  return {
-    recommendedPack: recommendedPack
-      ? {
-          id: recommendedPack.id,
-          name: recommendedPack.name,
-          description: recommendedPack.description,
-          userFacingCopy: recommendedPack.userFacingCopy,
-          statusCopy: recommendedPack.statusCopy,
-          dashboardCopy: recommendedPack.dashboardCopy,
-        }
-      : null,
-    reason: winner.reason,
-    status,
-    entitlement: packEntitlement,
-    riskLevel: signals.riskLevel || "low",
-    nextAction: winner.nextAction,
-    evidencePath,
-    additionalPacks: additionalPacks.map((p) => ({
-      id: p.id,
-      name: p.name,
-      userFacingCopy: p.userFacingCopy,
-    })),
-    signals: {
-      riskLevel: signals.riskLevel || "low",
-      contextPressure: signals.contextPressure || "unknown",
-      reentryState: signals.reentryState || (probes.reentry.hasReentry ? "available" : "missing"),
-      hasStagedChanges: signals.hasStagedChanges || false,
-      validationState: signals.validationState || "missing",
-      frontendDetected: probes.frontend.isFrontend || false,
-      activated: probes.activation.activated,
-      largeRepo: probes.workspace.largeRepo || false,
-    },
-  };
-}
-
-/**
- * Build a compact capability layer surface for dashboard/status.
- * Safe to call from dashboard.js — fails open with null on any error.
- */
-function buildCapabilityLayerSurface(cwd, config, prebuiltSignals) {
-  try {
-    const plan = config?.tier || "free";
-    let signals = prebuiltSignals || {};
-    const probes = {
-      frontend: probeFrontendSignals(cwd),
-      activation: probeActivationState(cwd),
-      reentry: probeReentryState(cwd),
-      workspace: probeWorkspaceSignals(cwd),
-      safePath: probeSafePathState(cwd),
-      installIntake: probeInstallIntakeState(cwd),
-    };
-
-    // If no pre-built signals, try to collect them
-    if (!prebuiltSignals) {
-      try {
-        const { collectWorkflowSignals } = require("./workflow-signals");
-        signals = collectWorkflowSignals({ cwd });
-      } catch {
-        signals = {};
-      }
-    }
-
-    // Merge in agent security surface data if available
-    try {
-      const { buildAgentSecuritySurface } = require("./agent-security");
-      const secSurface = buildAgentSecuritySurface(cwd, config);
-      if (secSurface) {
-        signals = {
-          ...signals,
-          riskyIntercepts: Number(secSurface.summary?.highRisk || 0) + Number(secSurface.summary?.mediumRisk || 0),
-          trustAlerts: Number(secSurface.summary?.unknownRisk || 0),
-          agentSecurityState: secSurface.mode || signals.agentSecurityState,
-        };
-      }
-    } catch {
-      // agent security surface unavailable — continue
-    }
-
-    const recommendation = recommendCapabilities({ cwd, signals, probes, plan });
-
-    // Determine active packs (packs with evidence of activity)
-    const activePacks = [];
-    if (signals.agentSecurityState && signals.agentSecurityState !== "off") {
-      activePacks.push({ id: "agent_security", name: "Agent Security" });
-    }
-    if (probes.safePath.hasSafePath || signals.agentSecurityState === "approve" || signals.agentSecurityState === "enforce") {
-      activePacks.push({ id: "safe_path_engine", name: "Safe Path Engine" });
-    }
-    if (probes.installIntake?.hasInstallIntake || probes.workspace?.hasPackageManifest) {
-      activePacks.push({ id: "install_intake_risk", name: "Install / Intake Risk" });
-    }
-    if (signals.contextPressure !== "unknown" && signals.contextPressure !== undefined) {
-      activePacks.push({ id: "workflow_efficiency", name: "Workflow Efficiency" });
-    }
-    if (recommendation.additionalPacks.some((pack) => pack.id === "workspace_navigation") || recommendation.recommendedPack?.id === "workspace_navigation") {
-      activePacks.push({ id: "workspace_navigation", name: "Workspace Navigation" });
-    }
-    if (probes.workspace.hasSourceCatalog && probes.workspace.hasLocalSkills) {
-      activePacks.push({ id: "source_backed_skills", name: "Source-Backed Skills" });
-    }
-    if (recommendation.signals.activated) {
-      activePacks.push({ id: "agent_readiness", name: "Agent Readiness" });
-    }
-
-    return {
-      capabilityLayerVersion: 1,
-      recommendedPack: recommendation.recommendedPack,
-      reason: recommendation.reason,
-      status: recommendation.status,
-      entitlement: recommendation.entitlement,
-      riskLevel: recommendation.riskLevel,
-      nextAction: recommendation.nextAction,
-      evidencePath: recommendation.evidencePath,
-      additionalPacks: recommendation.additionalPacks,
-      activePacks: activePacks.slice(0, 5),
-      trustRiskState: {
-        riskLevel: recommendation.riskLevel,
-        agentSecurityState: signals.agentSecurityState || "off",
-      },
-      entitlementSummary: {
-        plan,
-        note: plan === "free"
-          ? "Free plan includes basic capability packs. Upgrade to Pro for deeper checks and richer evidence."
-          : "Pro plan includes all capability packs with deeper checks and richer evidence.",
-      },
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Format a compact capability summary for CLI status output.
- * Returns a string, or empty string on error.
- */
-function formatCapabilitySummary(capabilityLayer) {
-  if (!capabilityLayer) return "";
-  try {
-    const lines = ["── Capability Layer ──────────────────────────────────"];
-    if (capabilityLayer.recommendedPack) {
-      lines.push(`  Recommended:  ${capabilityLayer.recommendedPack.name} (${capabilityLayer.entitlement})`);
-      lines.push(`  Why:          ${capabilityLayer.reason}`);
-    }
-    if (capabilityLayer.activePacks && capabilityLayer.activePacks.length > 0) {
-      lines.push(`  Active packs: ${capabilityLayer.activePacks.map((p) => p.name).join(", ")}`);
-    }
-    if (capabilityLayer.nextAction) {
-      lines.push(`  Next:         ${capabilityLayer.nextAction}`);
-    }
-    if (capabilityLayer.evidencePath) {
-      lines.push(`  Evidence:     ${capabilityLayer.evidencePath}`);
-    }
-    lines.push("");
-    return lines.join("\n");
-  } catch {
-    return "";
-  }
-}
-
-module.exports = {
-  recommendCapabilities,
-  buildCapabilityLayerSurface,
-  formatCapabilitySummary,
-  probeFrontendSignals,
-  probeActivationState,
-  probeReentryState,
-  probeWorkspaceSignals,
-  probeSafePathState,
-  probeInstallIntakeState,
-  probeEvidencePath,
-};