avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/capability-kernel.js

@@ -0,0 +1,202 @@
+"use strict";
+
+/**
+ * Capability Kernel v1 — avorelo.capabilityKernelReport.v1
+ *
+ * Audit-first, contract-first operating layer over Avorelo capabilities.
+ * Discovers capabilities from the static registry, validates contracts,
+ * produces a deterministic report, and surfaces one compact outcome.
+ *
+ * This does NOT rewrite capability internals or create a new dashboard.
+ * It is an audit/normalization/reporting layer.
+ */
+
+const path = require("path");
+const { getCapabilityRegistry } = require("./capability-kernel-registry");
+const { validateAllContracts, COMPLIANCE_READY, COMPLIANCE_PARTIAL } = require("./capability-contract-validator");
+const { checkClaimSafety, SCHEMA_VERSION } = require("./capability-manifest");
+
+const KERNEL_REPORT_SCHEMA = "avorelo.capabilityKernelReport.v1";
+
+/**
+ * Build the full Capability Kernel v1 report.
+ * @param {string} cwd - Repository root
+ * @param {object} [options] - Options
+ * @param {object[]} [options.capabilities] - Override capability list (for testing)
+ * @returns {object} Kernel report
+ */
+function buildCapabilityKernelReport(cwd, options = {}) {
+  const capabilities = options.capabilities || getCapabilityRegistry();
+  const { results, summary } = validateAllContracts(capabilities, cwd);
+
+  // Classify gaps
+  const gaps = [];
+  for (const r of results) {
+    if (r.compliance !== COMPLIANCE_READY) {
+      const gapReasons = [];
+      if (r.errors.length > 0) gapReasons.push(...r.errors.map((e) => `error: ${e}`));
+      if (!r.hasTests) gapReasons.push("missing tests");
+      if (!r.hasDocs) gapReasons.push("missing docs");
+      if (!r.hasPolicyGate) gapReasons.push("missing policy gate");
+      if (!r.hasRollback) gapReasons.push("missing rollback behavior");
+      if (!r.hasDogfood) gapReasons.push("missing dogfood artifact");
+      if (r.claimSafetyIssues.length > 0) gapReasons.push("claim-safety issues detected");
+      if (r.warnings.length > 2) gapReasons.push(`${r.warnings.length} warnings`);
+
+      gaps.push({
+        capabilityId: r.id,
+        capabilityName: r.name,
+        compliance: r.compliance,
+        reasons: gapReasons,
+        safeNextAction: buildSafeNextAction(r),
+      });
+    }
+  }
+
+  // Overall status
+  let status = "pass";
+  if (summary.needsAttention > 0 || summary.unsafeClaims > 0) {
+    status = "needs_attention";
+  } else if (summary.partiallyCompliant > 0) {
+    status = "warn";
+  }
+
+  // Duplicate surface check
+  const surfaceCounts = {};
+  for (const cap of capabilities) {
+    if (cap.surfaces) {
+      for (const [key, val] of Object.entries(cap.surfaces)) {
+        if (val) {
+          surfaceCounts[key] = (surfaceCounts[key] || 0) + 1;
+        }
+      }
+    }
+  }
+  // Flag if any single surface has >15 capabilities (noise risk)
+  const noisySurfaces = Object.entries(surfaceCounts).filter(([, count]) => count > 15);
+  summary.duplicateSurfaces = noisySurfaces.length;
+
+  const safeNextAction = buildOverallSafeNextAction(gaps, summary);
+
+  return {
+    schemaVersion: KERNEL_REPORT_SCHEMA,
+    status,
+    summary,
+    capabilities: results.map((r) => ({
+      id: r.id,
+      name: r.name,
+      compliance: r.compliance,
+      hasTests: r.hasTests,
+      hasDocs: r.hasDocs,
+      hasPolicyGate: r.hasPolicyGate,
+      hasRollback: r.hasRollback,
+      hasBudgets: r.hasBudgets,
+      hasDogfood: r.hasDogfood,
+      errorCount: r.errors.length,
+      warningCount: r.warnings.length,
+      claimSafetyIssueCount: r.claimSafetyIssues.length,
+    })),
+    gaps,
+    noisySurfaces: noisySurfaces.map(([surface, count]) => ({ surface, count })),
+    safeNextAction,
+  };
+}
+
+/**
+ * Build a safe next action for a single capability gap.
+ */
+function buildSafeNextAction(result) {
+  if (result.errors.length > 0) {
+    return `Fix contract errors for ${result.name}: ${result.errors[0]}`;
+  }
+  if (!result.hasTests) {
+    return `Add test coverage for ${result.name}`;
+  }
+  if (!result.hasDocs) {
+    return `Add documentation for ${result.name}`;
+  }
+  if (result.claimSafetyIssues.length > 0) {
+    return `Review claim-safety issues in ${result.name}`;
+  }
+  if (!result.hasDogfood) {
+    return `Add dogfood artifact for ${result.name}`;
+  }
+  return `Review ${result.warnings.length} warnings for ${result.name}`;
+}
+
+/**
+ * Build the overall safe next action for the kernel report.
+ */
+function buildOverallSafeNextAction(gaps, summary) {
+  if (summary.unsafeClaims > 0) {
+    return "Review and fix unsafe public claims before release.";
+  }
+  if (summary.needsAttention > 0) {
+    const first = gaps.find((g) => g.compliance === "needs_attention");
+    return first
+      ? `Fix: ${first.safeNextAction}`
+      : "Fix capabilities that need attention.";
+  }
+  if (summary.partiallyCompliant > 0) {
+    const first = gaps.find((g) => g.compliance === "partial");
+    return first
+      ? `Next: ${first.safeNextAction}`
+      : "Improve partial capabilities toward full compliance.";
+  }
+  return "All capabilities checked and compliant. Continue normal operation.";
+}
+
+/**
+ * Format kernel report as compact text for CLI/status.
+ */
+function formatKernelReportText(report) {
+  const s = report.summary;
+  let text = `Capabilities: ${s.capabilitiesFound} checked; ${s.fullyCompliant} ready; ${s.partiallyCompliant} partial; ${s.needsAttention} need attention.`;
+
+  if (report.safeNextAction) {
+    text += ` ${report.safeNextAction}`;
+  }
+
+  return text;
+}
+
+/**
+ * Format kernel report as a Product Home bucket mapping.
+ */
+function formatKernelProductHomeBuckets(report) {
+  const buckets = {
+    found: [],
+    fixed: [],
+    saved_or_proved: [],
+    needs_attention: [],
+  };
+
+  for (const cap of report.capabilities) {
+    if (cap.compliance === COMPLIANCE_READY) {
+      buckets.saved_or_proved.push({
+        title: cap.name,
+        oneLine: `${cap.name}: checked, proof-backed`,
+      });
+    } else {
+      buckets.needs_attention.push({
+        title: cap.name,
+        oneLine: `${cap.name}: ${cap.compliance} (${cap.errorCount} errors, ${cap.warningCount} warnings)`,
+      });
+    }
+  }
+
+  // The discovery itself is a "found" item
+  buckets.found.push({
+    title: "Capability Kernel v1",
+    oneLine: `${report.summary.capabilitiesFound} capabilities discovered and mapped`,
+  });
+
+  return buckets;
+}
+
+module.exports = {
+  KERNEL_REPORT_SCHEMA,
+  buildCapabilityKernelReport,
+  formatKernelReportText,
+  formatKernelProductHomeBuckets,
+};

package/scripts/lib/capability-manifest.js

@@ -0,0 +1,255 @@
+"use strict";
+
+/**
+ * Capability Manifest Schema — avorelo.capabilityManifest.v1
+ *
+ * Defines the operating contract for every Avorelo capability.
+ * Each capability is represented by a manifest that describes its
+ * triggers, risk tier, policy gate, evidence requirements, output
+ * contract, surfaces, budgets, tests, docs, and rollback behavior.
+ *
+ * This is an audit/contract layer — it does not rewrite capability internals.
+ */
+
+const SCHEMA_VERSION = "avorelo.capabilityManifest.v1";
+
+const VALID_STATUSES = new Set(["active", "partial", "deprecated", "internal_only"]);
+const VALID_RISK_TIERS = new Set(["low", "medium", "high"]);
+const VALID_SIDE_EFFECT_LEVELS = new Set(["read_only", "local_write", "external_write", "destructive"]);
+const VALID_DECISIONS = new Set(["allow", "warn", "require_approval", "block", "defer", "no_op"]);
+const VALID_REF_TYPES = new Set(["report", "receipt", "test", "diff", "proof", "audit"]);
+const VALID_OUTCOME_TYPES = new Set(["found", "fixed", "saved_or_proved", "needs_attention"]);
+const VALID_FAIL_BEHAVIORS = new Set(["fail_open_advisory", "fail_closed_policy"]);
+
+const UNSAFE_CLAIM_TERMS = [
+  "guaranteed",
+  "fully secure",
+  "fully secured",
+  "autonomous",
+  "company brain",
+  "remembers everything",
+  "full memory",
+  "guaranteed recall",
+  "saves dollars",
+  "saves credits",
+  "saves money",
+  "auto-inject",
+  "auto-injected",
+  "perfect proof",
+  "complete proof",
+  "production certified",
+];
+
+const UNSAFE_CLAIM_PATTERNS = UNSAFE_CLAIM_TERMS.map(
+  (term) => new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i")
+);
+
+/**
+ * Validate a capability manifest against the v1 schema.
+ * Returns { valid, errors, warnings }.
+ */
+function validateManifest(manifest) {
+  const errors = [];
+  const warnings = [];
+
+  if (!manifest || typeof manifest !== "object") {
+    return { valid: false, errors: ["manifest must be a non-null object"], warnings };
+  }
+
+  // Required fields
+  if (manifest.schemaVersion !== SCHEMA_VERSION) {
+    errors.push(`schemaVersion must be "${SCHEMA_VERSION}", got "${manifest.schemaVersion}"`);
+  }
+  if (!manifest.id || typeof manifest.id !== "string") {
+    errors.push("id is required and must be a non-empty string");
+  }
+  if (!manifest.name || typeof manifest.name !== "string") {
+    errors.push("name is required and must be a non-empty string");
+  }
+  if (!manifest.category || typeof manifest.category !== "string") {
+    errors.push("category is required and must be a non-empty string");
+  }
+
+  // Status
+  if (manifest.status && !VALID_STATUSES.has(manifest.status)) {
+    errors.push(`status must be one of: ${[...VALID_STATUSES].join(", ")}`);
+  }
+
+  // Risk tier
+  if (manifest.riskTier && !VALID_RISK_TIERS.has(manifest.riskTier)) {
+    errors.push(`riskTier must be one of: ${[...VALID_RISK_TIERS].join(", ")}`);
+  }
+
+  // Side-effect level
+  if (manifest.sideEffectLevel && !VALID_SIDE_EFFECT_LEVELS.has(manifest.sideEffectLevel)) {
+    errors.push(`sideEffectLevel must be one of: ${[...VALID_SIDE_EFFECT_LEVELS].join(", ")}`);
+  }
+
+  // Policy gate validation for side-effect capabilities
+  if (manifest.sideEffectLevel && manifest.sideEffectLevel !== "read_only") {
+    if (!manifest.policy || typeof manifest.policy !== "object") {
+      errors.push("side-effect capabilities (non-read_only) must define a policy gate");
+    } else {
+      if (manifest.policy.defaultDecision && !VALID_DECISIONS.has(manifest.policy.defaultDecision)) {
+        errors.push(`policy.defaultDecision must be one of: ${[...VALID_DECISIONS].join(", ")}`);
+      }
+      // Destructive or external_write must not default to allow
+      if (
+        (manifest.sideEffectLevel === "destructive" || manifest.sideEffectLevel === "external_write") &&
+        manifest.policy.defaultDecision === "allow"
+      ) {
+        errors.push("destructive or external_write capabilities must not default to allow");
+      }
+    }
+  }
+
+  // Evidence requirements for active capabilities
+  if (manifest.status === "active") {
+    if (!manifest.evidenceRequirements || typeof manifest.evidenceRequirements !== "object") {
+      warnings.push("active capabilities should define evidenceRequirements");
+    } else {
+      if (manifest.evidenceRequirements.allowedRefTypes) {
+        for (const rt of manifest.evidenceRequirements.allowedRefTypes) {
+          if (!VALID_REF_TYPES.has(rt)) {
+            warnings.push(`unknown evidenceRequirements.allowedRefTypes: "${rt}"`);
+          }
+        }
+      }
+    }
+  }
+
+  // Output contract
+  if (manifest.outputContract && typeof manifest.outputContract === "object") {
+    if (manifest.outputContract.outcomeTypes) {
+      for (const ot of manifest.outputContract.outcomeTypes) {
+        if (!VALID_OUTCOME_TYPES.has(ot)) {
+          warnings.push(`unknown outputContract.outcomeTypes: "${ot}"`);
+        }
+      }
+    }
+  }
+
+  // Budgets for context-heavy capabilities
+  if (manifest.budgets && typeof manifest.budgets === "object") {
+    if (manifest.budgets.maxFilesScanned != null && typeof manifest.budgets.maxFilesScanned !== "number") {
+      warnings.push("budgets.maxFilesScanned should be a number");
+    }
+    if (manifest.budgets.maxFileBytes != null && typeof manifest.budgets.maxFileBytes !== "number") {
+      warnings.push("budgets.maxFileBytes should be a number");
+    }
+  }
+
+  // Rollback / fail behavior
+  if (manifest.rollback && typeof manifest.rollback === "object") {
+    if (manifest.rollback.failBehavior && !VALID_FAIL_BEHAVIORS.has(manifest.rollback.failBehavior)) {
+      errors.push(`rollback.failBehavior must be one of: ${[...VALID_FAIL_BEHAVIORS].join(", ")}`);
+    }
+  } else if (manifest.status === "active") {
+    warnings.push("active capabilities should define rollback behavior");
+  }
+
+  // Tests and docs
+  if (!manifest.tests || !Array.isArray(manifest.tests) || manifest.tests.length === 0) {
+    warnings.push("capability should reference at least one test file");
+  }
+  if (!manifest.docs || !Array.isArray(manifest.docs) || manifest.docs.length === 0) {
+    warnings.push("capability should reference at least one doc file");
+  }
+
+  // Surfaces
+  if (manifest.surfaces && typeof manifest.surfaces === "object") {
+    // No additional validation needed — booleans
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Check a text string for unsafe public claim terms.
+ * Returns array of { term, matched } for each violation found.
+ */
+function checkClaimSafety(text) {
+  if (!text || typeof text !== "string") return [];
+  const violations = [];
+  for (let i = 0; i < UNSAFE_CLAIM_TERMS.length; i++) {
+    if (UNSAFE_CLAIM_PATTERNS[i].test(text)) {
+      violations.push({ term: UNSAFE_CLAIM_TERMS[i], matched: true });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Build a minimal manifest from known capability metadata.
+ */
+function buildManifest(fields) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: fields.id || "",
+    name: fields.name || "",
+    category: fields.category || "",
+    owner: fields.owner || "avorelo-core",
+    status: fields.status || "active",
+    riskTier: fields.riskTier || "low",
+    sideEffectLevel: fields.sideEffectLevel || "read_only",
+    triggers: fields.triggers || [],
+    antiTriggers: fields.antiTriggers || [],
+    inputSignals: fields.inputSignals || [],
+    allowedActions: fields.allowedActions || [],
+    forbiddenActions: fields.forbiddenActions || [],
+    policy: fields.policy || {
+      defaultDecision: "allow",
+      requiresApprovalWhen: [],
+      blocksWhen: [],
+    },
+    evidenceRequirements: fields.evidenceRequirements || {
+      minimumRefs: 0,
+      allowedRefTypes: ["report", "receipt", "test"],
+      rawDataAllowed: false,
+    },
+    outputContract: fields.outputContract || {
+      outcomeTypes: ["found", "needs_attention"],
+      reasonCodesRequired: true,
+      claimSafetyRequired: true,
+    },
+    budgets: fields.budgets || {
+      maxFilesScanned: 2200,
+      maxFileBytes: 262144,
+      maxContextRefs: 10,
+      maxRuntimeMs: 2000,
+    },
+    surfaces: fields.surfaces || {
+      productHome: true,
+      status: true,
+      dashboard: true,
+      nextRun: true,
+      teams: false,
+    },
+    tests: fields.tests || [],
+    docs: fields.docs || [],
+    dogfood: fields.dogfood || {
+      required: true,
+      artifactPath: "",
+    },
+    rollback: fields.rollback || {
+      disableFlag: "",
+      failBehavior: "fail_open_advisory",
+    },
+  };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  VALID_STATUSES,
+  VALID_RISK_TIERS,
+  VALID_SIDE_EFFECT_LEVELS,
+  VALID_DECISIONS,
+  VALID_REF_TYPES,
+  VALID_OUTCOME_TYPES,
+  VALID_FAIL_BEHAVIORS,
+  UNSAFE_CLAIM_TERMS,
+  UNSAFE_CLAIM_PATTERNS,
+  validateManifest,
+  checkClaimSafety,
+  buildManifest,
+};

package/scripts/lib/capability-outcome-normalizer.js

@@ -0,0 +1,104 @@
+"use strict";
+
+/**
+ * Capability Outcome Normalizer — avorelo.outcomeSurface.v1
+ *
+ * Maps capability outputs to the standard Found / Fixed / Saved-or-Proved / Needs Attention
+ * buckets. Enforces evidence/proof ref requirements. Downgrades unsupported claims.
+ */
+
+const { checkClaimSafety } = require("./capability-manifest");
+
+const VALID_BUCKETS = new Set(["found", "fixed", "saved_or_proved", "needs_attention"]);
+const VALID_SEVERITIES = new Set(["low", "medium", "high"]);
+
+/**
+ * Normalize a capability output into an outcome surface entry.
+ * @param {object} params
+ * @param {string} params.capabilityId
+ * @param {string} params.title
+ * @param {string} params.bucket - One of: found, fixed, saved_or_proved, needs_attention
+ * @param {string} params.oneLine - Compact summary
+ * @param {string[]} [params.proofRefs] - Evidence references
+ * @param {string} [params.nextAction] - Safe next action
+ * @param {string} [params.severity] - low, medium, high
+ * @param {object} [params.surfaces] - Which surfaces to show in
+ * @returns {{ normalized, warnings }}
+ */
+function normalizeOutcome(params) {
+  const warnings = [];
+
+  let bucket = params.bucket;
+  if (!VALID_BUCKETS.has(bucket)) {
+    warnings.push(`unknown bucket "${bucket}", defaulting to "needs_attention"`);
+    bucket = "needs_attention";
+  }
+
+  let severity = params.severity || "low";
+  if (!VALID_SEVERITIES.has(severity)) {
+    warnings.push(`unknown severity "${severity}", defaulting to "low"`);
+    severity = "low";
+  }
+
+  const proofRefs = params.proofRefs || [];
+
+  // Downgrade saved_or_proved if no proof refs
+  if (bucket === "saved_or_proved" && proofRefs.length === 0) {
+    warnings.push("saved_or_proved claim downgraded to found: no proof refs provided");
+    bucket = "found";
+  }
+
+  // Claim safety on the oneLine text
+  const oneLine = params.oneLine || "";
+  const claimViolations = checkClaimSafety(oneLine);
+  if (claimViolations.length > 0) {
+    warnings.push(`unsafe claim terms detected in oneLine: ${claimViolations.map((v) => v.term).join(", ")}`);
+    bucket = "needs_attention";
+  }
+
+  const normalized = {
+    schemaVersion: "avorelo.outcomeSurface.v1",
+    capabilityId: params.capabilityId || "",
+    title: params.title || "",
+    bucket,
+    severity,
+    oneLine: oneLine,
+    proofRefs,
+    nextAction: params.nextAction || "",
+    showInProductHome: params.surfaces?.productHome !== false,
+    showInStatus: params.surfaces?.status !== false,
+    showInDashboard: params.surfaces?.dashboard !== false,
+  };
+
+  return { normalized, warnings };
+}
+
+/**
+ * Normalize multiple outcomes and return a compact summary.
+ */
+function normalizeOutcomes(outcomes) {
+  const allWarnings = [];
+  const normalized = [];
+
+  for (const o of outcomes) {
+    const result = normalizeOutcome(o);
+    normalized.push(result.normalized);
+    allWarnings.push(...result.warnings);
+  }
+
+  const bucketCounts = {
+    found: normalized.filter((n) => n.bucket === "found").length,
+    fixed: normalized.filter((n) => n.bucket === "fixed").length,
+    saved_or_proved: normalized.filter((n) => n.bucket === "saved_or_proved").length,
+    needs_attention: normalized.filter((n) => n.bucket === "needs_attention").length,
+  };
+
+  return { normalized, bucketCounts, warnings: allWarnings };
+}
+
+module.exports = {
+  VALID_BUCKETS,
+  VALID_SEVERITIES,
+  normalizeOutcome,
+  normalizeOutcomes,
+};