avorelo 0.1.0

package/scripts/lib/proof-receipt.js

@@ -0,0 +1,335 @@
+"use strict";
+
+/**
+ * Completion Receipt (Surface 2).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { validateProofRecord } = require("./anti-gaming");
+const { formatNextBoundedAction } = require("./proof-canonical");
+
+function isMaterialRun(proofRecord) {
+  if (!proofRecord) return false;
+  const toolCalls = proofRecord.efficiency?.tools_considered || 0;
+  return toolCalls > 0 || proofRecord.completion_status !== "unknown";
+}
+
+function buildCompletionReceipt(proofRecord) {
+  if (!isMaterialRun(proofRecord)) {
+    return {
+      version: 1,
+      material: false,
+      session_id: proofRecord?.session_id || "unknown",
+      result: { summary: "No material run detected.", status: "empty" },
+      improvements: [],
+      trust_control: buildTrustControlSummary(proofRecord),
+      metrics: {},
+      anti_gaming: { valid: true, warnings: [] },
+    };
+  }
+
+  const result = buildResultSection(proofRecord);
+  const improvements = buildImprovements(proofRecord);
+  const trustControl = buildTrustControlSummary(proofRecord);
+  const metrics = buildReceiptMetrics(proofRecord);
+  const antiGaming = validateProofRecord(proofRecord);
+
+  return {
+    version: 1,
+    material: true,
+    session_id: proofRecord.session_id,
+    started_at: proofRecord.started_at,
+    ended_at: proofRecord.ended_at,
+    result,
+    improvements,
+    trust_control: trustControl,
+    metrics,
+    anti_gaming: antiGaming,
+  };
+}
+
+function buildResultSection(proof) {
+  const status = proof.completion_status;
+  const outcomeType = proof.final_outcome_type;
+  const nextBoundedAction = formatNextBoundedAction(proof.outcome?.next_bounded_action);
+  const taskContract = proof.task_contract || {};
+  const repoTruth = proof.repo_truth || {};
+
+  const summaryMap = {
+    completed: "Task completed.",
+    safe_stop: "Safe stop reached with bounded next action.",
+    partial: "Partially completed with recovery path available.",
+    ended_without_completion: "Session ended without explicit completion.",
+    unknown: "Session outcome not determined.",
+  };
+
+  return {
+    summary: summaryMap[status] || summaryMap.unknown,
+    status,
+    outcome_type: outcomeType,
+    task_type: proof.task_type || "general",
+    next_bounded_action: nextBoundedAction,
+    output_artifact_reference: proof.outcome?.output_artifact_reference || null,
+    claim_boundary: proof.outcome?.claim_boundary || null,
+    where_am_i_now: repoTruth.where_am_i_now || null,
+    readiness_status: repoTruth.readiness_status || null,
+    task_objective: taskContract.objective || null,
+    allowed_paths: taskContract.allowed_paths || [],
+  };
+}
+
+function buildImprovements(proof) {
+  const items = [];
+
+  const eff = proof.efficiency || {};
+  const ctrl = proof.control || {};
+  const trust = proof.trust || {};
+  const outcome = proof.outcome || {};
+
+  if (eff.large_output_bytes_managed > 0) {
+    items.push({
+      dimension: "efficiency",
+      text: `Stored ${eff.large_output_events || 1} large output${(eff.large_output_events || 1) > 1 ? "s" : ""} out-of-band to reduce context pressure.`,
+      evidence: `${eff.large_output_bytes_managed} bytes managed`,
+    });
+  }
+
+  if (eff.retries_count > 0) {
+    items.push({
+      dimension: "efficiency",
+      text: `Interrupted ${eff.retries_count} repeated loop${eff.retries_count > 1 ? "s" : ""} to prevent wasted cycles.`,
+      evidence: `${eff.retries_count} retries caught`,
+    });
+  }
+
+  if (eff.tools_skipped > 0) {
+    items.push({
+      dimension: "efficiency",
+      text: `Skipped ${eff.tools_skipped} unnecessary tool re-scan${eff.tools_skipped > 1 ? "s" : ""}.`,
+      evidence: `${eff.tools_skipped} scans avoided`,
+    });
+  }
+
+  if (ctrl.risky_actions_blocked > 0 || ctrl.risky_actions_downgraded > 0) {
+    const total = ctrl.risky_actions_blocked + ctrl.risky_actions_downgraded;
+    items.push({
+      dimension: "control",
+      text: `Blocked or flagged ${total} risky action${total > 1 ? "s" : ""}.`,
+      evidence: `${ctrl.risky_actions_blocked} blocked, ${ctrl.risky_actions_downgraded} flagged`,
+    });
+  }
+
+  if (trust.has_related_evidence) {
+    items.push({
+      dimension: "trust",
+      text: "Attached related evidence or runtime artifacts for this session.",
+      evidence: trust.evidence_bundle_reference || (outcome.evidence_refs || [])[0] || ".claude/cco/security/",
+    });
+  }
+
+  if (trust.progress_preserved) {
+    items.push({
+      dimension: "trust",
+      text: "Preserved progress for safe re-entry.",
+      evidence: outcome.progress_ref || "stop snapshot saved",
+    });
+  }
+
+  if (trust.uncertainty_annotations_count > 0) {
+    items.push({
+      dimension: "trust",
+      text: `Marked ${trust.uncertainty_annotations_count} unverified claim${trust.uncertainty_annotations_count > 1 ? "s" : ""} clearly.`,
+      evidence: `${trust.uncertainty_annotations_count} uncertainty annotations`,
+    });
+  }
+
+  return diversifyAndCap(items, 5);
+}
+
+function buildTrustControlSummary(proof) {
+  const trust = proof?.trust || {};
+  const ctrl = proof?.control || {};
+  const outcome = proof?.outcome || {};
+  const taskContract = proof?.task_contract || {};
+  const repoTruth = proof?.repo_truth || {};
+
+  return {
+    evidence_attached: Boolean(trust.has_related_evidence),
+    evidence_refs: outcome.evidence_refs || [],
+    unverified_claims_present: (trust.unverified_claim_count || 0) > 0,
+    unverified_claim_count: trust.unverified_claim_count || 0,
+    risky_actions_handled:
+      (ctrl.risky_actions_blocked || 0) + (ctrl.risky_actions_downgraded || 0) > 0,
+    risky_actions_blocked: ctrl.risky_actions_blocked || 0,
+    risky_actions_downgraded: ctrl.risky_actions_downgraded || 0,
+    rollback_available: Boolean(trust.rollback_available),
+    policy_violations_status: ctrl.trusted_scope_preserved || "unknown",
+    safe_stop_occurred: (ctrl.safe_stop_count || 0) > 0,
+    next_bounded_action: formatNextBoundedAction(outcome.next_bounded_action),
+    claim_boundary: outcome.claim_boundary || null,
+    where_am_i_now: repoTruth.where_am_i_now || null,
+    readiness_status: repoTruth.readiness_status || null,
+    task_objective: taskContract.objective || null,
+    allowed_paths: taskContract.allowed_paths || [],
+    expected_evidence_refs: taskContract.evidence_refs || [],
+    review_reasons: taskContract.review_reasons || [],
+    output_artifact_reference: outcome.output_artifact_reference || null,
+  };
+}
+
+function buildReceiptMetrics(proof) {
+  const eff = proof.efficiency || {};
+  const ctrl = proof.control || {};
+  const trust = proof.trust || {};
+
+  const metrics = {};
+
+  if (eff.time_saved_estimate && eff.time_saved_estimate.minutes > 0) {
+    metrics.estimated_time_saved = `~${eff.time_saved_estimate.minutes} min (${eff.time_saved_estimate.confidence} confidence)`;
+  }
+  if (eff.retries_count > 0) {
+    metrics.retries_caught = eff.retries_count;
+  }
+  if (eff.large_output_bytes_managed > 0) {
+    metrics.large_outputs_managed = `${eff.large_output_events || 1} outputs (${eff.large_output_bytes_managed} bytes)`;
+  }
+  if (eff.tools_skipped > 0) {
+    metrics.tool_overhead_reduced = eff.tools_skipped;
+  }
+  if (trust.has_related_evidence) {
+    metrics.evidence_present = "yes";
+  }
+  if (ctrl.risky_actions_blocked > 0) {
+    metrics.risky_actions_blocked = ctrl.risky_actions_blocked;
+  }
+
+  return metrics;
+}
+
+function renderReceiptMarkdown(receipt) {
+  if (!receipt.material) {
+    return "## Wuz Receipt\n\nNo material run detected.\n";
+  }
+
+  const lines = [
+    "## Wuz Effectiveness Receipt",
+    "",
+    `Session: ${receipt.session_id}`,
+    receipt.started_at ? `Started: ${receipt.started_at}` : "",
+    receipt.ended_at ? `Ended: ${receipt.ended_at}` : "",
+    "",
+    "### Result",
+    `${receipt.result.summary}`,
+    receipt.result.task_objective ? `Objective: ${receipt.result.task_objective}` : "",
+    receipt.result.allowed_paths?.length > 0 ? `Allowed scope: ${receipt.result.allowed_paths.join(", ")}` : "",
+    receipt.result.next_bounded_action ? `Next action: ${receipt.result.next_bounded_action}` : "",
+    receipt.result.output_artifact_reference
+      ? `Artifact: ${receipt.result.output_artifact_reference}`
+      : "",
+    receipt.result.claim_boundary ? `Claim boundary: ${receipt.result.claim_boundary}` : "",
+    receipt.result.where_am_i_now ? `Current state: ${receipt.result.where_am_i_now}` : "",
+    receipt.result.readiness_status ? `Readiness: ${receipt.result.readiness_status}` : "",
+    "",
+  ];
+
+  if (receipt.improvements.length > 0) {
+    lines.push("### What Wuz improved");
+    for (const imp of receipt.improvements) {
+      lines.push(`- ${imp.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("### Trust & control");
+  const tc = receipt.trust_control;
+  lines.push(`- Evidence attached: ${tc.evidence_attached ? "yes" : "no"}`);
+  if (tc.unverified_claims_present) {
+    lines.push(`- Unverified claims: ${tc.unverified_claim_count}`);
+  }
+  if (tc.risky_actions_handled) {
+    lines.push(
+      `- Risky actions blocked: ${tc.risky_actions_blocked}, flagged: ${tc.risky_actions_downgraded}`
+    );
+  }
+  lines.push(`- Rollback available: ${tc.rollback_available ? "yes" : "no"}`);
+  lines.push(`- Policy violations: ${tc.policy_violations_status}`);
+  if (tc.safe_stop_occurred) {
+    lines.push("- Safe stop occurred: yes");
+  }
+  if (tc.where_am_i_now) {
+    lines.push(`- Current state: ${tc.where_am_i_now}`);
+  }
+  if (tc.readiness_status) {
+    lines.push(`- Readiness: ${tc.readiness_status}`);
+  }
+  if (tc.next_bounded_action) {
+    lines.push(`- Bounded next action: ${tc.next_bounded_action}`);
+  }
+  if (tc.expected_evidence_refs.length > 0) {
+    lines.push(`- Expected evidence: ${tc.expected_evidence_refs.join(", ")}`);
+  }
+  if (tc.review_reasons.length > 0) {
+    lines.push(`- Review triggers: ${tc.review_reasons.join(", ")}`);
+  }
+  lines.push("");
+
+  if (Object.keys(receipt.metrics).length > 0) {
+    lines.push("### Metrics");
+    for (const [key, value] of Object.entries(receipt.metrics)) {
+      lines.push(`- ${key.replace(/_/g, " ")}: ${value}`);
+    }
+    lines.push("");
+  }
+
+  if (receipt.anti_gaming && !receipt.anti_gaming.valid) {
+    lines.push("### Warnings");
+    for (const warning of receipt.anti_gaming.warnings) {
+      lines.push(`- ${warning}`);
+    }
+    lines.push("");
+  }
+
+  return lines.filter((line) => line !== undefined).join("\n");
+}
+
+function saveReceipt(cwd, receipt) {
+  const sessionId = receipt.session_id || "unknown";
+  const jsonPath = path.join(cwd, ".claude", "cco", "receipts", `${sessionId}.json`);
+  const mdPath = path.join(cwd, ".claude", "cco", "receipts", `${sessionId}.md`);
+
+  fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+  fs.writeFileSync(jsonPath, JSON.stringify(receipt, null, 2), "utf8");
+  fs.writeFileSync(mdPath, renderReceiptMarkdown(receipt), "utf8");
+
+  return { jsonPath, mdPath };
+}
+
+function diversifyAndCap(items, maxCount) {
+  const result = [];
+  const seenDimensions = new Set();
+
+  for (const item of items) {
+    if (result.length >= maxCount) break;
+    if (!seenDimensions.has(item.dimension)) {
+      result.push(item);
+      seenDimensions.add(item.dimension);
+    }
+  }
+
+  for (const item of items) {
+    if (result.length >= maxCount) break;
+    if (!result.includes(item)) {
+      result.push(item);
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  isMaterialRun,
+  buildCompletionReceipt,
+  renderReceiptMarkdown,
+  saveReceipt,
+};