avorelo 0.1.0

package/scripts/lib/proof-events.js

@@ -0,0 +1,342 @@
+"use strict";
+
+/**
+ * Proof Event Taxonomy Mapping
+ *
+ * Maps existing Wuz reason codes and metric events to the 7 proof event families
+ * and 4 proof dimensions. This is a mapping layer, not a replacement for existing events.
+ */
+
+const PROOF_DIMENSIONS = ["outcome", "efficiency", "trust", "control"];
+
+const PROOF_EVENT_FAMILIES = [
+  "context_optimization",
+  "tool_model_efficiency",
+  "safety_control",
+  "recovery",
+  "trust",
+  "outcome",
+  "ux_exposure",
+];
+
+/**
+ * Maps reason codes to proof event family and dimension.
+ * Each entry: { family, dimension, proofWorthy, calmCopy }
+ *
+ * proofWorthy: true if this event should surface as a micro-proof moment.
+ * calmCopy: the user-facing one-liner if surfaced as micro-proof.
+ */
+const REASON_CODE_PROOF_MAP = {
+  // Context optimization -> efficiency
+  CTX_LARGE_OUTPUT: {
+    family: "context_optimization",
+    dimension: "efficiency",
+    proofWorthy: true,
+    calmCopy: "Wuz stored a large output out-of-band to reduce context pressure.",
+  },
+  CTX_SCAN_SKIPPED_UNCHANGED: {
+    family: "context_optimization",
+    dimension: "efficiency",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  CTX_SNAPSHOT: {
+    family: "context_optimization",
+    dimension: "efficiency",
+    proofWorthy: true,
+    calmCopy: "Wuz preserved a context snapshot before compaction.",
+  },
+  CTX_COST_PRESSURE_SUBAGENT: {
+    family: "context_optimization",
+    dimension: "efficiency",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+
+  // Tool/model efficiency -> efficiency
+  LOOP_REPEATED_TOOL: {
+    family: "tool_model_efficiency",
+    dimension: "efficiency",
+    proofWorthy: true,
+    calmCopy: "Wuz interrupted a repeated tool loop to prevent wasted cycles.",
+  },
+  FAIL_RETRY_GUARD: {
+    family: "recovery",
+    dimension: "trust",
+    proofWorthy: true,
+    calmCopy: "Wuz prevented a blind retry after a tool failure.",
+  },
+
+  // Safety/control -> control
+  SEC_CURL_PIPE_SH: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked a remote script piped into shell.",
+  },
+  SEC_REMOTE_FETCH: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz flagged a remote fetch pattern for review.",
+  },
+  SEC_REMOTE_INCLUDE: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz flagged a remote include pattern for review.",
+  },
+  SEC_UNPINNED_GIT_DEP: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_OVERBROAD_PERMISSION: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_SKILL_SOURCE_UNKNOWN: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz flagged an unknown skill source for review.",
+  },
+  SEC_SKILL_SOURCE_UNAPPROVED: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked an unapproved skill source.",
+  },
+  SEC_SKILL_INTAKE_BLOCK: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked a skill that did not pass intake policy.",
+  },
+  SEC_SKILL_INTAKE_WARN: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_SKILL_INTAKE_ALLOW: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_PRERUN_SCAN_STALE: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_HTTP_ENDPOINT_BLOCKED: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked a request to an unsafe HTTP endpoint.",
+  },
+  SEC_HTTP_PRIVATE_NETWORK_BLOCKED: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked a request to a private network address.",
+  },
+  SEC_OUTPUT_SENSITIVE_DATA: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz detected a sensitive data pattern in tool output.",
+  },
+  TEAM_BLOCK_PATTERN: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz blocked a command matching team policy.",
+  },
+
+  // Permission -> control
+  PERM_FATIGUE_CONSOLIDATED: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz consolidated repeated safe permission requests.",
+  },
+  PERM_REQ_DENY: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: true,
+    calmCopy: "Wuz denied a permission request based on policy.",
+  },
+  PERM_REQ_ASK: {
+    family: "safety_control",
+    dimension: "control",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+
+  // Trust -> trust
+  SEC_REMEDIATION_JOB_CREATED: {
+    family: "trust",
+    dimension: "trust",
+    proofWorthy: true,
+    calmCopy: "Wuz generated a remediation job for a security finding.",
+  },
+  SEC_SUPPRESSION_AUDIT: {
+    family: "trust",
+    dimension: "trust",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  SEC_TRUST_UNKNOWN_HIGH: {
+    family: "trust",
+    dimension: "trust",
+    proofWorthy: true,
+    calmCopy: "Wuz flagged high-risk changes in trusted-surface files.",
+  },
+  SEC_TRUST_AUDIT: {
+    family: "trust",
+    dimension: "trust",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+
+  // Recovery -> trust
+  STOP_SNAPSHOT: {
+    family: "recovery",
+    dimension: "trust",
+    proofWorthy: true,
+    calmCopy: "Wuz preserved progress for safe re-entry.",
+  },
+
+  // Outcome -> outcome
+  TASK_COMPLETED: {
+    family: "outcome",
+    dimension: "outcome",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  REPORT_WRITTEN: {
+    family: "outcome",
+    dimension: "outcome",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+
+  // UX exposure (proof-system-specific events)
+  PROOF_MICRO_RENDERED: {
+    family: "ux_exposure",
+    dimension: "outcome",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  PROOF_RECEIPT_GENERATED: {
+    family: "ux_exposure",
+    dimension: "outcome",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+  PROOF_DRILLDOWN_OPENED: {
+    family: "ux_exposure",
+    dimension: "outcome",
+    proofWorthy: false,
+    calmCopy: null,
+  },
+};
+
+/**
+ * Classify a reason code into its proof dimension.
+ * Returns null if the code is unknown.
+ */
+function classifyReasonCode(code) {
+  const entry = REASON_CODE_PROOF_MAP[code];
+  if (!entry) return null;
+  return {
+    code,
+    family: entry.family,
+    dimension: entry.dimension,
+    proofWorthy: entry.proofWorthy,
+    calmCopy: entry.calmCopy,
+  };
+}
+
+/**
+ * Classify all reason codes from a metric entry.
+ * Returns array of classified codes (unknown codes are excluded).
+ */
+function classifyMetricReasonCodes(metric) {
+  const codes = metric?.reasonCodes || [];
+  return codes.map(classifyReasonCode).filter(Boolean);
+}
+
+/**
+ * Extract proof-worthy events from a list of metrics.
+ * Returns only events that should surface to the user.
+ */
+function extractProofWorthyEvents(metrics) {
+  const results = [];
+  for (const metric of metrics || []) {
+    const classified = classifyMetricReasonCodes(metric);
+    for (const c of classified) {
+      if (c.proofWorthy) {
+        results.push({
+          ...c,
+          ts: metric.ts,
+          sessionId: metric.sessionId,
+          event: metric.event,
+          tool: metric.tool,
+          action: metric.action,
+        });
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Count metrics by proof dimension.
+ */
+function countByDimension(metrics) {
+  const counts = { outcome: 0, efficiency: 0, trust: 0, control: 0 };
+  for (const metric of metrics || []) {
+    const classified = classifyMetricReasonCodes(metric);
+    for (const c of classified) {
+      if (counts[c.dimension] !== undefined) {
+        counts[c.dimension]++;
+      }
+    }
+  }
+  return counts;
+}
+
+/**
+ * Count metrics by event family.
+ */
+function countByFamily(metrics) {
+  const counts = {};
+  for (const family of PROOF_EVENT_FAMILIES) counts[family] = 0;
+  for (const metric of metrics || []) {
+    const classified = classifyMetricReasonCodes(metric);
+    for (const c of classified) {
+      if (counts[c.family] !== undefined) {
+        counts[c.family]++;
+      }
+    }
+  }
+  return counts;
+}
+
+module.exports = {
+  PROOF_DIMENSIONS,
+  PROOF_EVENT_FAMILIES,
+  REASON_CODE_PROOF_MAP,
+  classifyReasonCode,
+  classifyMetricReasonCodes,
+  extractProofWorthyEvents,
+  countByDimension,
+  countByFamily,
+};

package/scripts/lib/proof-history.js

@@ -0,0 +1,243 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { getHistoryRetention, canExportReports } = require("./entitlements");
+const { redactPayload } = require("./product-learning-events");
+
+const PROOF_RECEIPTS_REL = ".claude/cco/receipts";
+const PROOF_EXPORTS_REL = ".claude/cco/exports";
+const DEFAULT_HISTORY_LIMIT = 10;
+
+function tsOrFallback(value, fallback = 0) {
+  const parsed = Date.parse(value || "");
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function redactFreeformText(value) {
+  const text = String(value || "");
+  const sanitized = redactPayload({ text }).text;
+  return sanitized
+    .replace(/[A-Za-z]:\\[^\s,;]+/g, "[redacted-path]")
+    .replace(/(^|[\s(])\/[A-Za-z0-9._\-\/]+/g, (match, prefix) => `${prefix}[redacted-path]`)
+    .replace(/(^|[\s(])\.claude\/[A-Za-z0-9._\-\/]+/g, (match, prefix) => `${prefix}[redacted-path]`)
+    .replace(/(^|[\s(])artifacts\/[A-Za-z0-9._\-\/]+/g, (match, prefix) => `${prefix}[redacted-path]`)
+    .replace(/(^|[\s(])\.env(?:\.[A-Za-z0-9._-]+)?/g, (match, prefix) => `${prefix}[redacted-path]`);
+}
+
+function safeSummary(value) {
+  const text = redactFreeformText(value);
+  if (!text) return null;
+  return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+
+function projectReceiptHistoryEntry(filename, receipt, stat) {
+  const result = receipt?.result || {};
+  const trustControl = receipt?.trust_control || {};
+  return {
+    receiptId: safeSummary(receipt?.session_id || filename.replace(/\.json$/i, "")),
+    endedAt: receipt?.ended_at || receipt?.started_at || new Date(stat.mtimeMs).toISOString(),
+    status: safeSummary(result.status || "unknown"),
+    summary: safeSummary(result.summary || "Proof receipt recorded."),
+    nextAction: safeSummary(
+      result.next_bounded_action
+        || trustControl.next_bounded_action
+        || null,
+    ),
+    claimBoundary: safeSummary(result.claim_boundary || trustControl.claim_boundary || null),
+    material: receipt?.material === true,
+    source: "proof_receipt",
+    redacted: true,
+  };
+}
+
+function listReceiptFiles(cwd) {
+  const dir = path.join(cwd, PROOF_RECEIPTS_REL);
+  try {
+    return fs.readdirSync(dir)
+      .filter((file) => file.endsWith(".json"))
+      .map((file) => {
+        const abs = path.join(dir, file);
+        return {
+          file,
+          abs,
+          stat: fs.statSync(abs),
+        };
+      });
+  } catch {
+    return [];
+  }
+}
+
+function readProofHistory(cwd, options = {}) {
+  const retention = getHistoryRetention(options.plan);
+  const maxReports = Math.max(1, Number(retention.maxReports || 1));
+  const limit = Math.max(
+    1,
+    Math.min(
+      Number(options.limit || DEFAULT_HISTORY_LIMIT),
+      maxReports,
+    ),
+  );
+  const receipts = listReceiptFiles(cwd)
+    .sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs);
+
+  const entries = [];
+  let corruptCount = 0;
+
+  for (const receiptFile of receipts) {
+    if (entries.length >= maxReports) break;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(receiptFile.abs, "utf8"));
+      entries.push(projectReceiptHistoryEntry(receiptFile.file, parsed, receiptFile.stat));
+    } catch {
+      corruptCount += 1;
+    }
+  }
+
+  entries.sort((left, right) => tsOrFallback(right.endedAt) - tsOrFallback(left.endedAt));
+
+  return {
+    redacted: true,
+    sourcePath: PROOF_RECEIPTS_REL,
+    retention,
+    totalReceiptsScanned: receipts.length,
+    corruptReceipts: corruptCount,
+    partial: corruptCount > 0,
+    available: entries.length > 0,
+    entries: entries.slice(0, limit),
+    totalRetainedEntries: entries.length,
+  };
+}
+
+function formatProofHistoryText(history, options = {}) {
+  if (!history?.available) {
+    return "Proof history is not available yet.";
+  }
+
+  const limit = Math.max(1, Number(options.limit || history.entries.length || 1));
+  const lines = [
+    "Avorelo Proof History",
+    `Entries shown: ${Math.min(history.entries.length, limit)} of ${history.totalRetainedEntries}`,
+  ];
+
+  for (const entry of history.entries.slice(0, limit)) {
+    lines.push(
+      `- ${entry.receiptId} | ${entry.status} | ${entry.endedAt}`,
+    );
+    lines.push(`  Summary: ${entry.summary}`);
+    if (entry.nextAction) {
+      lines.push(`  Next: ${entry.nextAction}`);
+    }
+  }
+
+  if (history.partial) {
+    lines.push("Caveat: Some local proof receipts were unreadable and were skipped.");
+  }
+
+  lines.push("Caveat: History is redacted and limited to safe local receipt summaries.");
+  return lines.join("\n");
+}
+
+function formatProofExportText(result) {
+  const lines = [
+    "Avorelo Proof Export",
+    `JSON: ${result.jsonRel}`,
+    `Markdown: ${result.mdRel}`,
+    `Entries exported: ${result.count}`,
+  ];
+  if (result.partial) {
+    lines.push("Caveat: Some local proof receipts were unreadable and were skipped.");
+  }
+  lines.push("Caveat: Export is redacted and excludes raw prompts, code, secrets, and sensitive paths.");
+  return lines.join("\n");
+}
+
+function buildProofHistoryMarkdown(history) {
+  const lines = [
+    "# Avorelo Proof History Export",
+    "",
+    `Generated: ${nowIso()}`,
+    `Entries: ${history.entries.length}`,
+    "",
+  ];
+
+  for (const entry of history.entries) {
+    lines.push(`## ${entry.receiptId}`);
+    lines.push(`- Status: ${entry.status}`);
+    lines.push(`- Ended: ${entry.endedAt}`);
+    lines.push(`- Summary: ${entry.summary}`);
+    if (entry.nextAction) {
+      lines.push(`- Next: ${entry.nextAction}`);
+    }
+    if (entry.claimBoundary) {
+      lines.push(`- Claim boundary: ${entry.claimBoundary}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("Caveat: Export is redacted and excludes raw prompts, code, secrets, and sensitive paths.");
+  return lines.join("\n");
+}
+
+function exportProofHistoryBundle(cwd, options = {}) {
+  const plan = options.plan || "free";
+  if (!canExportReports(plan)) {
+    return {
+      ok: false,
+      reason: "plan_lacks_export",
+    };
+  }
+
+  const history = readProofHistory(cwd, {
+    plan,
+    limit: options.limit || getHistoryRetention(plan).maxReports || DEFAULT_HISTORY_LIMIT,
+  });
+  const stamp = nowIso().replace(/[:.]/g, "-");
+  const jsonRel = path.posix.join(PROOF_EXPORTS_REL, `proof-history-${stamp}.json`);
+  const mdRel = path.posix.join(PROOF_EXPORTS_REL, `proof-history-${stamp}.md`);
+  const jsonAbs = path.join(cwd, jsonRel);
+  const mdAbs = path.join(cwd, mdRel);
+
+  ensureCcoDirs(cwd);
+  fs.mkdirSync(path.dirname(jsonAbs), { recursive: true });
+
+  fs.writeFileSync(jsonAbs, JSON.stringify({
+    version: 1,
+    generatedAt: nowIso(),
+    plan,
+    redacted: true,
+    sourcePath: PROOF_RECEIPTS_REL,
+    count: history.entries.length,
+    retention: history.retention,
+    partial: history.partial,
+    caveats: [
+      "Redacted local proof history export.",
+      "No raw prompts, raw code, secrets, or sensitive paths are included.",
+    ],
+    entries: history.entries,
+  }, null, 2), "utf8");
+
+  fs.writeFileSync(mdAbs, buildProofHistoryMarkdown(history), "utf8");
+
+  return {
+    ok: true,
+    count: history.entries.length,
+    partial: history.partial,
+    jsonRel,
+    mdRel,
+    history,
+  };
+}
+
+module.exports = {
+  DEFAULT_HISTORY_LIMIT,
+  PROOF_EXPORTS_REL,
+  PROOF_RECEIPTS_REL,
+  exportProofHistoryBundle,
+  formatProofExportText,
+  formatProofHistoryText,
+  readProofHistory,
+};