avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/proof-savings-report.js

@@ -0,0 +1,1549 @@
+"use strict";
+
+// Proof & Savings Report — local evidence-backed report explaining what improved,
+// what was validated, what was saved or avoided, what risks remain, and the next best action.
+//
+// No cloud calls, no LLM, no daemon, no marketing copy.
+// Evidence-backed. Conservative estimates. Honest limitations.
+//
+// Report artifacts:
+//   .claude/cco/reports/proof-savings-report.json  — avorelo.proofSavingsReport.v1
+//   .claude/cco/reports/proof-savings-report.md    — Markdown report
+//
+// Evidence quality values:
+//   sufficient    — multiple validated signals from real artifacts
+//   candidate     — some signals, partial coverage
+//   insufficient  — few or weak signals
+//   stale         — artifacts exist but TTL exceeded or fingerprint mismatch
+//   fixture_only  — only test fixture artifacts found
+//   error         — unexpected error during collection
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const REPORT_JSON_REL = ".claude/cco/reports/proof-savings-report.json";
+const REPORT_MD_REL = ".claude/cco/reports/proof-savings-report.md";
+const SCHEMA_VERSION = "avorelo.proofSavingsReport.v1";
+
+const EVIDENCE_QUALITY_VALUES = [
+  "sufficient",
+  "candidate",
+  "insufficient",
+  "stale",
+  "fixture_only",
+  "error",
+];
+
+const PROOF_TYPES = ["real", "dogfood", "fixture", "insufficient"];
+
+const SAVINGS_CATEGORIES = [
+  "avoided_repeated_setup",
+  "avoided_validation_rework",
+  "avoided_context_waste",
+  "avoided_risky_action",
+  "avoided_public_claim_rework",
+  "token_or_cost_waste_avoided",
+  "manual_investigation_avoided",
+];
+
+const RISK_CATEGORIES = [
+  "missing_proof",
+  "stale_context",
+  "fake_applied_claim",
+  "unsupported_host_assumption",
+  "unsafe_public_claim",
+  "prompt_or_instruction_risk",
+  "token_cost_gap",
+  "repo_state_risk",
+  "unresolved_validation_gap",
+  "production_orchestration_missing",
+];
+
+// Conservative time heuristics (min, max) in minutes per confidence tier.
+// These are heuristics, not measured values. Always mark as estimate.
+const MINUTE_HEURISTICS = {
+  avoided_repeated_setup: { low: [3, 5], medium: [6, 12], high: [12, 20] },
+  avoided_validation_rework: { low: [5, 10], medium: [10, 20], high: [20, 40] },
+  avoided_context_waste: { low: [2, 5], medium: [5, 12], high: [12, 25] },
+  avoided_risky_action: { low: [2, 5], medium: [5, 15], high: [15, 30] },
+  avoided_public_claim_rework: { low: [3, 8], medium: [8, 18], high: [18, 35] },
+  token_or_cost_waste_avoided: { low: [2, 5], medium: [5, 12], high: [12, 25] },
+  manual_investigation_avoided: { low: [5, 10], medium: [10, 25], high: [25, 45] },
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function buildFingerprint(data) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(data))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// ── Evidence collection ───────────────────────────────────────────────────────
+
+function collectEvidence(cwd) {
+  const ev = {
+    runImprovements: null,
+    lifecycleReceipt: null,
+    nextRunContext: null,
+    learningSummary: null,
+    decisionRegister: null,
+    riskRegister: null,
+    adapterReadiness: null,
+    outcomeEvents: null,
+    tokenEvidence: null,
+    costEvidence: null,
+    tokenCostEvidence: null,
+    fullReadinessGate: null,
+    proofReceipts: null,
+  };
+
+  // Run improvements artifact
+  try {
+    const { loadRunImprovements } = require("./run-improvements");
+    ev.runImprovements = loadRunImprovements(cwd);
+  } catch {}
+
+  // Lifecycle receipt
+  try {
+    const { loadLifecycleReceipt } = require("./run-improvements-lifecycle");
+    ev.lifecycleReceipt = loadLifecycleReceipt(cwd);
+  } catch {}
+
+  // Next-run context
+  try {
+    const { loadNextRunContext } = require("./next-run-context");
+    ev.nextRunContext = loadNextRunContext(cwd);
+  } catch {}
+
+  // Learning artifacts
+  try {
+    const { loadLearningSummary, loadDecisionRegister, loadRiskRegister } = require("./learning-memory");
+    ev.learningSummary = loadLearningSummary(cwd);
+    ev.decisionRegister = loadDecisionRegister(cwd);
+    ev.riskRegister = loadRiskRegister(cwd);
+  } catch {}
+
+  // Adapter readiness
+  try {
+    const { buildAdapterReadinessSurface } = require("./adapter-readiness");
+    ev.adapterReadiness = buildAdapterReadinessSurface(cwd);
+  } catch {}
+
+  // Outcome events (last 7 days, exclude run_improvements audit category)
+  try {
+    const { readOutcomeEvents, aggregateOutcomeEvents } = require("./unified-events");
+    const raw = readOutcomeEvents(cwd);
+    const events = raw.filter((e) => e.category !== "run_improvements");
+    if (events.length > 0) {
+      ev.outcomeEvents = aggregateOutcomeEvents(events, { days: 7 });
+    }
+  } catch {}
+
+  // Proof receipts — latest from .claude/cco/receipts/
+  try {
+    const receiptsDir = path.join(cwd, ".claude", "cco", "receipts");
+    if (fs.existsSync(receiptsDir)) {
+      const files = fs.readdirSync(receiptsDir).filter((f) => f.endsWith(".json"));
+      if (files.length > 0) {
+        const sorted = files
+          .map((n) => ({ n, mt: fs.statSync(path.join(receiptsDir, n)).mtimeMs }))
+          .sort((a, b) => b.mt - a.mt);
+        const latest = JSON.parse(
+          fs.readFileSync(path.join(receiptsDir, sorted[0].n), "utf8")
+        );
+        ev.proofReceipts = {
+          count: files.length,
+          latest: {
+            completionStatus: latest.result?.status || "unknown",
+            material: latest.material || false,
+            antiGamingValid: latest.anti_gaming?.valid !== false,
+          },
+        };
+      }
+    }
+  } catch {}
+
+  // Token evidence — absent unless artifact exists
+  try {
+    const te = require("./token-evidence");
+    if (typeof te.loadTokenEvidence === "function") {
+      ev.tokenEvidence = te.loadTokenEvidence(cwd);
+    }
+  } catch {}
+
+  // Cost evidence — absent unless artifact exists
+  try {
+    const ce = require("./cost-evidence");
+    if (typeof ce.loadCostEvidence === "function") {
+      ev.costEvidence = ce.loadCostEvidence(cwd);
+    }
+  } catch {}
+
+  // Unified token/cost evidence — absent unless artifact exists
+  try {
+    const tce = require("./token-cost-evidence");
+    if (typeof tce.loadTokenCostEvidence === "function") {
+      const raw = tce.loadTokenCostEvidence({ cwd });
+      if (raw) {
+        const validation = tce.validateTokenCostEvidence(raw);
+        // Only use evidence that is valid and not a test fixture
+        if (validation.valid && !validation.isFixture) {
+          ev.tokenCostEvidence = raw;
+        }
+      }
+    }
+  } catch {}
+
+  // Full-readiness gate — optional
+  try {
+    const frg = require("./full-readiness-gate");
+    if (typeof frg.loadFullReadinessGate === "function") {
+      ev.fullReadinessGate = frg.loadFullReadinessGate(cwd);
+    } else if (typeof frg.buildFullReadinessGate === "function") {
+      ev.fullReadinessGate = frg.buildFullReadinessGate(cwd);
+    }
+  } catch {}
+
+  return ev;
+}
+
+// ── Evidence quality classification ──────────────────────────────────────────
+
+function classifyEvidenceQuality(ev) {
+  const populated = Object.values(ev).filter((v) => v !== null).length;
+  if (populated === 0) return "error";
+
+  const ri = ev.runImprovements;
+  const riExpired =
+    ri &&
+    (ri.status === "expired" || ri.status === "stale" || ri.status === "not_available");
+  const nrc = ev.nextRunContext;
+  const nrcExpired =
+    nrc && (nrc.status === "expired" || nrc.status === "stale" || nrc.status === "not_available");
+
+  // Stale: main artifact is expired and no other live signals
+  if (
+    ri &&
+    riExpired &&
+    (!nrc || nrcExpired) &&
+    !ev.lifecycleReceipt &&
+    !ev.learningSummary
+  ) {
+    return "stale";
+  }
+
+  // Count live, real signal sources
+  let signalCount = 0;
+  if (ri && !riExpired) signalCount++;
+  if (ev.lifecycleReceipt) signalCount++;
+  if (nrc && !nrcExpired) signalCount++;
+  if (ev.learningSummary) signalCount++;
+  if (ev.proofReceipts) signalCount++;
+  if (ev.adapterReadiness && ev.adapterReadiness.readiness?.verdict !== "adapter_not_ready") signalCount++;
+  if (ev.fullReadinessGate && ev.fullReadinessGate.status === "ok") signalCount++;
+
+  if (signalCount >= 3) return "sufficient";
+  if (signalCount >= 1) return "candidate";
+  return "insufficient";
+}
+
+// ── Proof section ─────────────────────────────────────────────────────────────
+
+function buildProofSection(ev) {
+  const validatedSignals = [];
+  const limitations = [];
+
+  // Run improvements artifact
+  const ri = ev.runImprovements;
+  if (ri) {
+    if (ri.status === "expired" || ri.status === "stale") {
+      limitations.push(
+        "Run improvements artifact is expired or stale — proof signal degraded."
+      );
+    } else if (
+      ri.status === "not_available" ||
+      ri.status === "insufficient_evidence"
+    ) {
+      limitations.push(
+        "Run improvements: insufficient evidence — no validated improvement signals."
+      );
+    } else {
+      validatedSignals.push({
+        signal: "run_improvements_prepared",
+        description: `Run improvements ${ri.status}: ${
+          (ri.topImprovements || []).length
+        } improvement(s), ${(ri.nextRunDefaults || []).length} next-run default(s).`,
+        proofType: "real",
+        source: "run_improvements_artifact",
+        reasonCodes: ri.reasonCodes || [],
+      });
+    }
+  } else {
+    limitations.push("No run improvements artifact found.");
+  }
+
+  // Lifecycle receipt
+  const lc = ev.lifecycleReceipt;
+  if (lc) {
+    validatedSignals.push({
+      signal: "lifecycle_receipt_exists",
+      description: `Lifecycle receipt: ${lc.lifecycleState} (surface: ${
+        lc.surface || "unknown"
+      }).`,
+      proofType: "real",
+      source: "lifecycle_receipt",
+      reasonCodes: lc.reasonCodes || [],
+    });
+    if (lc.lifecycleState === "applied") {
+      validatedSignals.push({
+        signal: "run_improvements_applied",
+        description: `Run improvements applied via ${lc.surface || "unknown"} at ${
+          lc.appliedAt || "unknown"
+        }.`,
+        proofType: "real",
+        source: "lifecycle_receipt",
+        reasonCodes: ["LIFECYCLE_HONEST_CLAIM"],
+      });
+    }
+  } else {
+    limitations.push(
+      "No lifecycle receipt found — applied state cannot be confirmed."
+    );
+  }
+
+  // Next-run context
+  const nrc = ev.nextRunContext;
+  if (nrc) {
+    if (nrc.status === "expired") {
+      limitations.push("Next-run context artifact is expired.");
+    } else if (
+      nrc.status !== "not_available" &&
+      nrc.status !== "insufficient_evidence"
+    ) {
+      validatedSignals.push({
+        signal: "next_run_context_exists",
+        description: `Next-run context: ${nrc.status}, ${
+          (nrc.appliedDefaults || []).length
+        } default(s), ${nrc.activeDecisionCount || 0} decision(s).`,
+        proofType: "real",
+        source: "next_run_context",
+        reasonCodes: nrc.reasonCodes || [],
+      });
+    }
+  } else {
+    limitations.push("No next-run context artifact found.");
+  }
+
+  // Learning summary
+  if (ev.learningSummary) {
+    const ls = ev.learningSummary;
+    validatedSignals.push({
+      signal: "learning_summary_exists",
+      description: `Learning summary: ${ls.activeDecisionCount} decision(s), ${ls.activeRiskCount} risk(s), ${ls.capabilityCount} capability(ies).`,
+      proofType: "real",
+      source: "learning_summary",
+      reasonCodes: [],
+    });
+  } else {
+    limitations.push("No learning summary found.");
+  }
+
+  // Proof receipts
+  if (ev.proofReceipts) {
+    const pr = ev.proofReceipts;
+    const completed = pr.latest.completionStatus === "completed";
+    validatedSignals.push({
+      signal: "proof_receipt_exists",
+      description: `Proof receipt found (${pr.count} total). Latest: status=${pr.latest.completionStatus}, material=${pr.latest.material}.`,
+      proofType: completed ? "real" : "dogfood",
+      source: "proof_receipts",
+      reasonCodes: completed ? [] : ["INCOMPLETE_PROOF_RECEIPT"],
+    });
+    if (!completed) {
+      limitations.push("Latest proof receipt is not 'completed' — proof is partial.");
+    }
+  } else {
+    limitations.push("No proof receipts found in .claude/cco/receipts/.");
+  }
+
+  // Adapter readiness — only a validated signal when adapter is actually ready
+  if (
+    ev.adapterReadiness &&
+    ev.adapterReadiness.readiness?.verdict !== "adapter_not_ready"
+  ) {
+    validatedSignals.push({
+      signal: "adapter_readiness_available",
+      description: `Adapter readiness: ${
+        ev.adapterReadiness.readiness?.status || "checked"
+      }.`,
+      proofType: "real",
+      source: "adapter_readiness",
+      reasonCodes: [],
+    });
+  }
+
+  // Full readiness gate
+  if (ev.fullReadinessGate) {
+    const fg = ev.fullReadinessGate;
+    validatedSignals.push({
+      signal: "full_readiness_gate_run",
+      description: `Full readiness gate: ${fg.status || "available"}.`,
+      proofType: "real",
+      source: "full_readiness_gate",
+      reasonCodes: [],
+    });
+  }
+
+  // Token/cost evidence — only counts as validated signal when it is real, non-fixture
+  if (ev.tokenCostEvidence) {
+    try {
+      const { summarizeTokenCostEvidence } = require("./token-cost-evidence");
+      const tceSum = summarizeTokenCostEvidence(ev.tokenCostEvidence);
+      if (tceSum.available && !tceSum.isFixture) {
+        const tokenStr = tceSum.totalTokens !== null
+          ? `${(tceSum.totalTokens / 1000).toFixed(1)}k tokens`
+          : "tokens: unknown";
+        const costStr = tceSum.totalCost !== null
+          ? `, ~$${tceSum.totalCost.toFixed(4)}`
+          : ", cost: not estimated";
+        validatedSignals.push({
+          signal: "token_cost_evidence_valid",
+          description: `Token/cost evidence: ${tokenStr}${costStr}, ${tceSum.confidence} confidence.`,
+          proofType: tceSum.isDogfood ? "dogfood" : "real",
+          source: "token_cost_evidence",
+          reasonCodes: (tceSum.reasonCodes || []).slice(0, 3),
+        });
+      }
+    } catch {}
+  }
+
+  const proofType =
+    validatedSignals.length >= 3
+      ? "real"
+      : validatedSignals.length >= 1
+      ? "dogfood"
+      : "insufficient";
+
+  const proofCoverage =
+    validatedSignals.length === 0
+      ? "none"
+      : validatedSignals.length <= 2
+      ? "partial"
+      : "sufficient";
+
+  return {
+    validatedSignals,
+    validatedSignalCount: validatedSignals.length,
+    proofType,
+    proofCoverage,
+    limitations,
+  };
+}
+
+// ── Savings section ───────────────────────────────────────────────────────────
+
+function makeSavingsEstimate(
+  category,
+  confidence,
+  basis,
+  evidenceRefs,
+  limitations = [],
+  reasonCodes = []
+) {
+  const heuristic = MINUTE_HEURISTICS[category];
+  const range = heuristic
+    ? heuristic[confidence] || heuristic.low
+    : null;
+  return {
+    category,
+    estimateType: "conservative_heuristic",
+    estimatedMinutesRange: range ? { min: range[0], max: range[1] } : null,
+    tokenSavings: null, // Only set when token evidence exists
+    costSavings: null, // Only set when cost evidence exists
+    confidence,
+    basis,
+    evidenceRefs,
+    limitations: [
+      "This is a conservative heuristic estimate, not a measured value.",
+      ...limitations,
+    ],
+    reasonCodes,
+  };
+}
+
+function buildSavingsSection(ev) {
+  const estimates = [];
+
+  // avoided_repeated_setup: run improvements prepared with improvements
+  const ri = ev.runImprovements;
+  if (
+    ri &&
+    ri.status !== "not_available" &&
+    ri.status !== "expired" &&
+    ri.status !== "stale" &&
+    ri.status !== "insufficient_evidence" &&
+    Array.isArray(ri.topImprovements) &&
+    ri.topImprovements.length > 0
+  ) {
+    const improvCount = ri.topImprovements.length;
+    const confidence =
+      improvCount >= 3 ? "medium" : improvCount >= 1 ? "low" : "insufficient";
+    if (confidence !== "insufficient") {
+      estimates.push(
+        makeSavingsEstimate(
+          "avoided_repeated_setup",
+          confidence,
+          `${improvCount} run improvement(s) prepared — next-run defaults reduce redundant context setup.`,
+          ["run_improvements_artifact"],
+          [
+            "Estimate assumes defaults would have been discovered manually in a follow-up session.",
+          ],
+          (ri.reasonCodes || []).slice(0, 3)
+        )
+      );
+    }
+  }
+
+  // avoided_validation_rework: lifecycle applied + proof receipt
+  const lc = ev.lifecycleReceipt;
+  if (lc && lc.lifecycleState === "applied" && ev.proofReceipts) {
+    estimates.push(
+      makeSavingsEstimate(
+        "avoided_validation_rework",
+        "medium",
+        "Lifecycle applied + proof receipt exists — validation state was captured, avoiding re-validation in next session.",
+        ["lifecycle_receipt", "proof_receipts"],
+        [
+          "Assumes validation would be repeated without this artifact.",
+          "Estimate is conservative.",
+        ],
+        ["LIFECYCLE_HONEST_CLAIM"]
+      )
+    );
+  } else if (lc && lc.lifecycleState === "applied") {
+    estimates.push(
+      makeSavingsEstimate(
+        "avoided_validation_rework",
+        "low",
+        "Lifecycle applied — defaults injected into next run via next-run context.",
+        ["lifecycle_receipt"],
+        ["No proof receipt to corroborate. Lower confidence."],
+        ["LIFECYCLE_HONEST_CLAIM"]
+      )
+    );
+  }
+
+  // avoided_context_waste: next-run context with defaults
+  const nrc = ev.nextRunContext;
+  if (
+    nrc &&
+    nrc.status !== "not_available" &&
+    nrc.status !== "expired" &&
+    nrc.status !== "insufficient_evidence" &&
+    (nrc.appliedDefaults || []).length > 0
+  ) {
+    estimates.push(
+      makeSavingsEstimate(
+        "avoided_context_waste",
+        "medium",
+        `Next-run context with ${nrc.appliedDefaults.length} default(s) and ${
+          nrc.activeDecisionCount || 0
+        } decision(s) prepared — reduces context re-discovery in next session.`,
+        ["next_run_context"],
+        [
+          "Assumes context would be rediscovered manually without this artifact.",
+        ],
+        (nrc.reasonCodes || []).slice(0, 3)
+      )
+    );
+  }
+
+  // avoided_risky_action: learning risks + lifecycle receipt
+  if (ev.learningSummary && ev.learningSummary.activeRiskCount > 0 && lc) {
+    const riskCount = ev.learningSummary.activeRiskCount;
+    estimates.push(
+      makeSavingsEstimate(
+        "avoided_risky_action",
+        riskCount >= 2 ? "medium" : "low",
+        `${riskCount} active risk(s) tracked in learning memory — risk awareness carried forward reduces risky action probability.`,
+        ["learning_summary", "lifecycle_receipt"],
+        [
+          "Risk reduction is probabilistic, not guaranteed.",
+          "Minutes are not directly measurable.",
+        ],
+        ["LIFECYCLE_HONEST_CLAIM"]
+      )
+    );
+  }
+
+  // manual_investigation_avoided: learning decisions active
+  if (ev.learningSummary && ev.learningSummary.activeDecisionCount > 0) {
+    const decCount = ev.learningSummary.activeDecisionCount;
+    estimates.push(
+      makeSavingsEstimate(
+        "manual_investigation_avoided",
+        decCount >= 3 ? "medium" : "low",
+        `${decCount} active decision(s) in learning register — decisions carried forward avoid re-investigation.`,
+        ["learning_summary"],
+        [
+          "Assumes decisions would need to be re-derived without learning memory.",
+        ],
+        []
+      )
+    );
+  }
+
+  // ── Token/cost evidence integration ──────────────────────────────────────
+  // Use unified token-cost-evidence artifact if available.
+  // Fall back to legacy tokenEvidence/costEvidence artifacts if present.
+
+  let tceSummary = null;
+  try {
+    const { summarizeTokenCostEvidence } = require("./token-cost-evidence");
+    if (ev.tokenCostEvidence) {
+      tceSummary = summarizeTokenCostEvidence(ev.tokenCostEvidence);
+    }
+  } catch {}
+
+  // token_or_cost_waste_avoided: only when valid token evidence present
+  const hasRealTokenCost = tceSummary && tceSummary.available && !tceSummary.isFixture;
+  const legacyTokenEvidence = ev.tokenEvidence && ev.tokenEvidence.measurements &&
+    (ev.tokenEvidence.measurements.totalProviderTokens ||
+     ev.tokenEvidence.measurements.candidateTokenReduction);
+
+  if (hasRealTokenCost && tceSummary.totalTokens) {
+    const tokenK = Math.round(tceSummary.totalTokens / 1000);
+    const isDogfood = tceSummary.isDogfood;
+    estimates.push(
+      makeSavingsEstimate(
+        "token_or_cost_waste_avoided",
+        isDogfood ? "low" : "low",
+        isDogfood
+          ? `Token usage tracked via dogfood evidence: ~${tokenK}k tokens. Candidate only — not high-confidence real evidence.`
+          : `Token usage tracked: ~${tokenK}k tokens from safe local evidence.`,
+        ["token_cost_evidence"],
+        [
+          "Token savings require a measured baseline for accurate estimation.",
+          isDogfood ? "Dogfood evidence: candidate signal, not high-confidence real evidence." : null,
+          tceSummary.totalCost === null ? "Cost estimate not available — no explicit cost data in evidence." : null,
+        ].filter(Boolean),
+        tceSummary.reasonCodes || []
+      )
+    );
+  } else if (legacyTokenEvidence) {
+    // Legacy fallback
+    estimates.push(
+      makeSavingsEstimate(
+        "token_or_cost_waste_avoided",
+        "low",
+        "Token evidence present — token usage is being tracked.",
+        ["token_evidence"],
+        ["Token savings require baseline measurement for accurate estimation."],
+        []
+      )
+    );
+  }
+
+  const totalMinSaved = estimates.reduce(
+    (sum, e) => sum + (e.estimatedMinutesRange?.min || 0),
+    0
+  );
+  const totalMaxSaved = estimates.reduce(
+    (sum, e) => sum + (e.estimatedMinutesRange?.max || 0),
+    0
+  );
+
+  const overallConfidence =
+    estimates.length >= 3
+      ? "medium"
+      : estimates.length >= 1
+      ? "low"
+      : "insufficient";
+
+  // Determine token/cost evidence summary for report fields
+  const hasTokenEvidence = (tceSummary && tceSummary.totalTokens !== null && !tceSummary.isFixture) ||
+    legacyTokenEvidence;
+  const hasCostEvidence = (tceSummary && tceSummary.totalCost !== null && !tceSummary.isFixture) ||
+    (ev.costEvidence && ev.costEvidence.preferredMeasuredCost && ev.costEvidence.preferredMeasuredCost > 0);
+
+  const tokenCostLimitations = [
+    ...(!hasTokenEvidence ? ["No token evidence found — token savings not estimated."] : []),
+    ...(!hasCostEvidence ? ["No cost evidence found — cost savings not estimated."] : []),
+    ...(tceSummary?.limitations || []).slice(0, 2),
+  ];
+
+  const limitations = [
+    "All estimates are conservative heuristics, not measured values.",
+    "Prefer 'estimated X–Y minutes avoided' over 'saved X minutes'.",
+    ...tokenCostLimitations.slice(0, 2),
+  ];
+
+  // Build token savings block — only when token evidence is real
+  const tokenSavingsBlock = (() => {
+    if (tceSummary && tceSummary.totalTokens !== null && !tceSummary.isFixture) {
+      return {
+        available: true,
+        totalTokens: tceSummary.totalTokens,
+        confidence: tceSummary.confidence,
+        isDogfood: tceSummary.isDogfood,
+        evidence: "token_cost_evidence artifact",
+        limitations: tceSummary.limitations.slice(0, 2),
+        note: tceSummary.isDogfood
+          ? "Dogfood evidence: candidate signal only."
+          : "Token evidence from safe local sources.",
+      };
+    }
+    if (legacyTokenEvidence) {
+      return {
+        available: true,
+        evidence: "token_evidence artifact",
+        note: "Token evidence present. See token-evidence module for details.",
+      };
+    }
+    return null;
+  })();
+
+  // Build cost savings block — only when explicit cost evidence exists
+  const costSavingsBlock = (() => {
+    if (tceSummary && tceSummary.totalCost !== null && !tceSummary.isFixture) {
+      return {
+        available: true,
+        totalCost: tceSummary.totalCost,
+        currency: tceSummary.currency || "USD",
+        confidence: tceSummary.confidence,
+        isDogfood: tceSummary.isDogfood,
+        evidence: "token_cost_evidence artifact",
+        note: "Cost from safe local evidence. Not suitable for billing reconciliation.",
+      };
+    }
+    if (ev.costEvidence && ev.costEvidence.preferredMeasuredCost && ev.costEvidence.preferredMeasuredCost > 0) {
+      return {
+        available: true,
+        evidence: "cost_evidence artifact",
+        note: "Cost evidence present. See cost-evidence module for details.",
+      };
+    }
+    return null;
+  })();
+
+  return {
+    estimates,
+    tokenCostEvidence: tceSummary
+      ? {
+          sourceType: tceSummary.sourceType,
+          available: tceSummary.available,
+          totalTokens: tceSummary.totalTokens,
+          totalCost: tceSummary.totalCost,
+          currency: tceSummary.currency,
+          confidence: tceSummary.confidence,
+          isFixture: tceSummary.isFixture,
+          isDogfood: tceSummary.isDogfood,
+          recordCount: tceSummary.recordCount,
+          limitations: tceSummary.limitations,
+        }
+      : null,
+    estimatedTokenSavings: tokenSavingsBlock ? tokenSavingsBlock.totalTokens ?? null : null,
+    estimatedCostSavings: costSavingsBlock ? costSavingsBlock.totalCost ?? null : null,
+    tokenCostConfidence: tceSummary?.confidence ?? "unavailable",
+    tokenCostLimitations,
+    tokenSavings: tokenSavingsBlock,
+    costSavings: costSavingsBlock,
+    conservativeTotalMinutesRange:
+      estimates.length > 0 ? { min: totalMinSaved, max: totalMaxSaved } : null,
+    overallConfidence,
+    limitations,
+  };
+}
+
+// ── Risk section ──────────────────────────────────────────────────────────────
+
+function buildRiskSection(ev) {
+  const openRisks = [];
+  const reducedRisks = [];
+  const blockedClaims = [];
+
+  // Missing proof
+  if (!ev.proofReceipts) {
+    openRisks.push({
+      category: "missing_proof",
+      title: "No proof receipts found",
+      severity: "medium",
+      nextMitigation:
+        "Run an Avorelo session with proof capture enabled.",
+      evidenceRefs: [],
+      reasonCodes: ["NO_PROOF_RECEIPT"],
+    });
+  }
+
+  // Fake applied claim: run improvements says applied but no receipt
+  const ri = ev.runImprovements;
+  const lc = ev.lifecycleReceipt;
+  if (ri && ri.status === "applied" && !lc) {
+    blockedClaims.push({
+      category: "fake_applied_claim",
+      title:
+        "Run improvements shows 'applied' but no lifecycle receipt exists",
+      severity: "high",
+      nextMitigation:
+        "Re-apply via `avorelo run-improvements --apply` to generate a legitimate receipt.",
+      evidenceRefs: ["run_improvements_artifact"],
+      reasonCodes: ["LIFECYCLE_HONEST_CLAIM"],
+    });
+  } else if (lc && lc.lifecycleState === "applied") {
+    reducedRisks.push({
+      category: "fake_applied_claim",
+      title: "Applied claim is backed by lifecycle receipt",
+      severity: "none",
+      evidenceRefs: ["lifecycle_receipt"],
+      reasonCodes: ["LIFECYCLE_HONEST_CLAIM"],
+    });
+  }
+
+  // Stale context
+  if (ri && (ri.status === "expired" || ri.status === "stale")) {
+    openRisks.push({
+      category: "stale_context",
+      title: "Run improvements artifact is expired or stale",
+      severity: "medium",
+      nextMitigation:
+        "Regenerate via `avorelo run-improvements --generate`.",
+      evidenceRefs: ["run_improvements_artifact"],
+      reasonCodes: ["STALE_ARTIFACT_RISK"],
+    });
+  }
+
+  // Production orchestration missing — always note; local-only limitation
+  openRisks.push({
+    category: "production_orchestration_missing",
+    title: "No production orchestration receipt in this workspace",
+    severity: "low",
+    nextMitigation:
+      "Expected in local development. Production receipts are generated during real sessions.",
+    evidenceRefs: [],
+    reasonCodes: ["LOCAL_WORKSPACE_ONLY"],
+    note: "This is a local-workspace limitation, not a product failure.",
+  });
+
+  // Unsupported host assumption — adapter readiness always runs but may return not_ready
+  if (!ev.adapterReadiness || ev.adapterReadiness.readiness?.verdict === "adapter_not_ready") {
+    openRisks.push({
+      category: "unsupported_host_assumption",
+      title: "Adapter readiness not checked — host capabilities unknown",
+      severity: "low",
+      nextMitigation:
+        "Run `avorelo adapter-readiness` to verify host support.",
+      evidenceRefs: [],
+      reasonCodes: ["HOST_SUPPORT_HOST_SPECIFIC"],
+    });
+  } else {
+    reducedRisks.push({
+      category: "unsupported_host_assumption",
+      title: "Adapter readiness checked — host capabilities known",
+      severity: "none",
+      evidenceRefs: ["adapter_readiness"],
+      reasonCodes: ["HOST_SUPPORT_HOST_SPECIFIC"],
+    });
+  }
+
+  // Token/cost gap — check unified evidence first, then legacy
+  const hasTCE = ev.tokenCostEvidence !== null;
+  const hasLegacyToken = ev.tokenEvidence !== null;
+  const hasLegacyCost = ev.costEvidence !== null;
+  const hasSufficientTokenCost = hasTCE || (hasLegacyToken && hasLegacyCost);
+
+  if (!hasSufficientTokenCost) {
+    if (hasTCE) {
+      // Has unified evidence but no cost — lower severity
+      openRisks.push({
+        category: "token_cost_gap",
+        title: "Token evidence available but cost evidence absent — cost savings not estimated",
+        severity: "low",
+        nextMitigation:
+          "Import redacted cost evidence via `avorelo token-evidence --import <path>` to enable cost estimates.",
+        evidenceRefs: ["token_cost_evidence"],
+        reasonCodes: ["NO_COST_EVIDENCE"],
+      });
+    } else {
+      openRisks.push({
+        category: "token_cost_gap",
+        title: "Token or cost evidence absent — savings cannot include cost estimates",
+        severity: "low",
+        nextMitigation:
+          "Capture token usage via `avorelo token-evidence --generate` to enable cost estimates.",
+        evidenceRefs: [],
+        reasonCodes: ["NO_TOKEN_COST_EVIDENCE"],
+      });
+    }
+  } else if (hasTCE) {
+    reducedRisks.push({
+      category: "token_cost_gap",
+      title: "Token/cost evidence present — token savings estimates available",
+      severity: "none",
+      evidenceRefs: ["token_cost_evidence"],
+      reasonCodes: ["TOKEN_COST_EVIDENCE_PRESENT"],
+    });
+  }
+
+  // Active risks from learning risk register (bounded to top 3)
+  if (ev.riskRegister && Array.isArray(ev.riskRegister.risks)) {
+    const active = ev.riskRegister.risks.filter((r) => r.status === "active");
+    for (const r of active.slice(0, 3)) {
+      openRisks.push({
+        category: r.category || "unresolved_validation_gap",
+        title: r.title,
+        severity: r.severity || "medium",
+        nextMitigation: r.mitigation || "See risk register for details.",
+        evidenceRefs: r.evidenceRefs || ["risk_register"],
+        reasonCodes: r.reasonCodes || [],
+      });
+    }
+  }
+
+  // Production confidence risks — consume from artifact if current and not fixture
+  try {
+    const { extractProductionConfidenceRisks } = require("./production-confidence");
+    const pcRisks = extractProductionConfidenceRisks(cwd);
+    if (pcRisks && pcRisks.blockerCount > 0) {
+      for (const b of (pcRisks.blockers || []).slice(0, 2)) {
+        openRisks.push({
+          category: "production_orchestration_missing",
+          title: `Production confidence blocker: ${b.title}`,
+          severity: b.severity === "critical" ? "high" : b.severity || "medium",
+          nextMitigation: b.recommendation || "Resolve production confidence blocker before shipping.",
+          evidenceRefs: ["production_confidence_report"],
+          reasonCodes: (b.reasonCodes || ["PRODUCTION_CONFIDENCE_BLOCKER"]).slice(0, 3),
+          note: "From production confidence scan — local read-only.",
+        });
+      }
+    }
+  } catch {}
+
+  return {
+    openRisks,
+    reducedRisks,
+    blockedClaims,
+    openRiskCount: openRisks.length,
+    reducedRiskCount: reducedRisks.length,
+    blockedClaimCount: blockedClaims.length,
+    limitations: [
+      "Risk register is evidence-backed but bounded — not exhaustive.",
+      "Production orchestration limitation is local-workspace-only.",
+    ],
+  };
+}
+
+// ── Run Improvements outcome section ─────────────────────────────────────────
+
+function buildRunImprovementsSection(ev) {
+  if (!ev.runImprovements) {
+    return {
+      status: "not_available",
+      prepared: false,
+      consumed: false,
+      applied: false,
+      injected: false,
+      expired: false,
+      categories: [],
+      defaultsCount: 0,
+      lifecycleReceipt: null,
+      nextRunContextArtifact: null,
+      limitations: ["No run improvements artifact found."],
+    };
+  }
+
+  const ri = ev.runImprovements;
+  const lc = ev.lifecycleReceipt;
+  const nrc = ev.nextRunContext;
+
+  // Only trust lifecycle receipt for applied/consumed state
+  const isApplied = lc !== null && lc.lifecycleState === "applied";
+  const isConsumed =
+    lc !== null &&
+    (lc.lifecycleState === "consumed" || lc.lifecycleState === "applied");
+  const isInjected =
+    nrc !== null &&
+    (nrc.status === "applied" || nrc.status === "injected");
+
+  return {
+    status: ri.status,
+    prepared:
+      ri.status === "prepared" ||
+      ri.status === "applied" ||
+      ri.status === "consumed",
+    consumed: isConsumed,
+    applied: isApplied,
+    injected: isInjected,
+    expired: ri.status === "expired" || ri.status === "stale",
+    categories: [
+      ...new Set((ri.topImprovements || []).map((i) => i.category)),
+    ],
+    defaultsCount: (ri.nextRunDefaults || []).length,
+    lifecycleReceipt: lc
+      ? {
+          lifecycleState: lc.lifecycleState,
+          surface: lc.surface,
+          consumedAt: lc.consumedAt,
+          appliedAt: lc.appliedAt,
+        }
+      : null,
+    nextRunContextArtifact: nrc
+      ? {
+          status: nrc.status,
+          appliedDefaultsCount: (nrc.appliedDefaults || []).length,
+          activeDecisionCount: nrc.activeDecisionCount || 0,
+        }
+      : null,
+    limitations: [
+      ...(!isApplied && ri.status !== "not_available"
+        ? [
+            "applied=true requires a lifecycle receipt via `avorelo run-improvements --apply`.",
+          ]
+        : []),
+      ...(!isInjected
+        ? [
+            "injected requires session-start hook to consume next-run context artifact.",
+          ]
+        : []),
+    ],
+  };
+}
+
+// ── Learning section ──────────────────────────────────────────────────────────
+
+function buildLearningSection(ev) {
+  if (!ev.learningSummary) {
+    return {
+      available: false,
+      activeDecisionCount: 0,
+      activeRiskCount: 0,
+      capabilityCount: 0,
+      staleItemCount: 0,
+      topLearningSignals: [],
+      nextRunInfluence: [],
+      limitations: [
+        "No learning summary found. Run `avorelo learning --generate` to build.",
+      ],
+    };
+  }
+
+  const ls = ev.learningSummary;
+
+  // Bounded top signals — no raw register dump
+  const rawSignals = ls.topLearningSignals || ls.topSignals || [];
+  const topSignals = rawSignals.slice(0, 3).map((s) => ({
+    type: s.type,
+    summary: (s.summary || "").slice(0, 120),
+    confidence: s.confidence,
+    reasonCodes: (s.reasonCodes || []).slice(0, 3),
+  }));
+
+  // Bounded next-run influence
+  const nextRunInfluence = (ls.nextRunInfluence || []).slice(0, 3).map((inf) => ({
+    type: inf.type,
+    text: inf.text,
+    reasonCodes: (inf.reasonCodes || []).slice(0, 3),
+  }));
+
+  return {
+    available: true,
+    activeDecisionCount: ls.activeDecisionCount || 0,
+    activeRiskCount: ls.activeRiskCount || 0,
+    capabilityCount: ls.capabilityCount || 0,
+    staleItemCount: ls.staleItemCount || 0,
+    topLearningSignals: topSignals,
+    nextRunInfluence,
+    limitations: (ls.limitations || []).slice(0, 2),
+  };
+}
+
+// ── Next best action ──────────────────────────────────────────────────────────
+
+function buildNextBestAction(ev, proof, savings, risk, runImprovementsSection) {
+  // Priority 1: blocked claim — fix this first
+  if (risk.blockedClaims.length > 0) {
+    const blocked = risk.blockedClaims[0];
+    return {
+      title: "Fix blocked claim before sharing report",
+      reason: blocked.title,
+      source: "risk_section",
+      priority: "critical",
+      evidenceRefs: blocked.evidenceRefs,
+    };
+  }
+
+  // Priority 2: no run improvements artifact
+  if (!ev.runImprovements || ev.runImprovements.status === "not_available") {
+    return {
+      title: "Generate run improvements to enable proof and savings",
+      reason:
+        "No run improvements artifact found. Run `avorelo run-improvements --generate`.",
+      source: "evidence_collection",
+      priority: "high",
+      evidenceRefs: [],
+    };
+  }
+
+  // Priority 3: prepared but not applied
+  if (runImprovementsSection.prepared && !runImprovementsSection.applied) {
+    return {
+      title: "Apply run improvements to next-run context",
+      reason:
+        "Run improvements prepared but not yet applied. Run `avorelo run-improvements --apply`.",
+      source: "run_improvements_lifecycle",
+      priority: "high",
+      evidenceRefs: ["run_improvements_artifact"],
+    };
+  }
+
+  // Priority 4: no learning summary
+  if (!ev.learningSummary) {
+    return {
+      title: "Generate learning memory to improve next-run influence",
+      reason:
+        "No learning summary found. Run `avorelo learning --generate` to build decisions and risks.",
+      source: "learning_section",
+      priority: "medium",
+      evidenceRefs: [],
+    };
+  }
+
+  // Priority 5: applied but no proof receipts
+  if (runImprovementsSection.applied && !ev.proofReceipts) {
+    return {
+      title: "Run a session with proof capture to build validation evidence",
+      reason:
+        "Run improvements applied but no proof receipts found — savings estimates remain low confidence.",
+      source: "proof_section",
+      priority: "medium",
+      evidenceRefs: ["run_improvements_artifact", "lifecycle_receipt"],
+    };
+  }
+
+  // Default: good state — keep evidence fresh
+  return {
+    title: "Rerun proof validation to keep evidence fresh",
+    reason:
+      "Evidence is available. Keep artifacts fresh by regenerating after each session.",
+    source: "report_summary",
+    priority: "low",
+    evidenceRefs: Object.keys(ev).filter((k) => ev[k] !== null),
+  };
+}
+
+// ── Source fingerprint ────────────────────────────────────────────────────────
+
+function buildSourceFingerprint(ev) {
+  return buildFingerprint({
+    riStatus: ev.runImprovements?.status || "none",
+    riFingerprint: ev.runImprovements?.sourceRunFingerprint || "none",
+    lcState: ev.lifecycleReceipt?.lifecycleState || "none",
+    nrcStatus: ev.nextRunContext?.status || "none",
+    lsFingerprint: ev.learningSummary?.sourceFingerprint || "none",
+    proofReceiptCount: ev.proofReceipts?.count || 0,
+  });
+}
+
+// ── Main report builder ───────────────────────────────────────────────────────
+
+function buildProofSavingsReport(cwd) {
+  const generatedAt = nowIso();
+  const ev = collectEvidence(cwd);
+  const evidenceQuality = classifyEvidenceQuality(ev);
+  const fingerprint = buildSourceFingerprint(ev);
+
+  const proof = buildProofSection(ev);
+  const savings = buildSavingsSection(ev);
+  const risk = buildRiskSection(ev);
+  const runImprovementsSection = buildRunImprovementsSection(ev);
+  const learningSection = buildLearningSection(ev);
+  const nextBestAction = buildNextBestAction(
+    ev,
+    proof,
+    savings,
+    risk,
+    runImprovementsSection
+  );
+
+  const reasonCodes = [
+    ...new Set([
+      ...proof.validatedSignals.flatMap((s) => s.reasonCodes),
+      ...savings.estimates.flatMap((e) => e.reasonCodes),
+      ...risk.openRisks.flatMap((r) => r.reasonCodes),
+    ]),
+  ].slice(0, 10);
+
+  const allLimitations = [
+    ...proof.limitations.slice(0, 3),
+    ...savings.limitations.slice(0, 2),
+    ...risk.limitations.slice(0, 2),
+    "This report is local-only. No cloud sync, no external services.",
+    "Token and cost savings are omitted unless token/cost evidence artifacts exist.",
+  ];
+
+  const nrc = ev.nextRunContext;
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt,
+    sourceFingerprint: fingerprint,
+    reportScope: "local_workspace",
+    evidenceQuality,
+    proof,
+    savings,
+    risk,
+    runImprovements: runImprovementsSection,
+    learning: learningSection,
+    nextRunContext: nrc
+      ? {
+          status: nrc.status,
+          appliedDefaultsCount: (nrc.appliedDefaults || []).length,
+          activeDecisionCount: nrc.activeDecisionCount || 0,
+          activeRiskCount: nrc.activeRiskCount || 0,
+        }
+      : null,
+    nextBestAction,
+    redactionStatus: "redacted",
+    reasonCodes,
+    limitations: [...new Set(allLimitations)].slice(0, 10),
+  };
+}
+
+// ── Write artifacts ───────────────────────────────────────────────────────────
+
+function generateProofSavingsReport(cwd) {
+  const report = buildProofSavingsReport(cwd);
+
+  const jsonPath = path.join(cwd, REPORT_JSON_REL);
+  fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+  fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2), "utf8");
+
+  const md = formatReportMarkdown(report);
+  const mdPath = path.join(cwd, REPORT_MD_REL);
+  fs.writeFileSync(mdPath, md, "utf8");
+
+  try {
+    _emitAuditEvent(cwd, report);
+  } catch {}
+
+  return {
+    report,
+    written: true,
+    jsonPath: REPORT_JSON_REL,
+    mdPath: REPORT_MD_REL,
+  };
+}
+
+function loadProofSavingsReport(cwd) {
+  try {
+    const absPath = path.join(cwd, REPORT_JSON_REL);
+    const raw = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+// ── Markdown report ───────────────────────────────────────────────────────────
+
+function formatReportMarkdown(report) {
+  const r = report;
+  const lines = [];
+
+  lines.push(`# Avorelo Proof & Savings Report`);
+  lines.push(``);
+  lines.push(`Generated: ${r.generatedAt}`);
+  lines.push(`Evidence quality: **${r.evidenceQuality}**`);
+  lines.push(`Validated signals: ${r.proof.validatedSignalCount}`);
+  lines.push(``);
+
+  // Summary
+  lines.push(`## Summary`);
+  lines.push(``);
+  const sv = r.savings;
+  const totalMin = sv.conservativeTotalMinutesRange;
+  if (totalMin) {
+    lines.push(
+      `Estimated savings: **${totalMin.min}–${totalMin.max} minutes avoided**, ${sv.overallConfidence} confidence.`
+    );
+  } else {
+    lines.push(`Estimated savings: insufficient evidence to estimate.`);
+  }
+  lines.push(`Open risks: ${r.risk.openRiskCount}.`);
+  lines.push(`Next action: ${r.nextBestAction.title}.`);
+  lines.push(``);
+
+  // What improved
+  lines.push(`## What Improved`);
+  lines.push(``);
+  const ri = r.runImprovements;
+  if (ri.prepared) {
+    lines.push(
+      `- Run improvements prepared: ${ri.defaultsCount} next-run default(s) across ${ri.categories.length} category(ies).`
+    );
+    if (ri.applied)
+      lines.push(
+        `- Applied via lifecycle receipt (surface: ${ri.lifecycleReceipt?.surface || "unknown"}).`
+      );
+    if (ri.injected)
+      lines.push(
+        `- Injected into next-run context: ${ri.nextRunContextArtifact?.appliedDefaultsCount || 0} default(s).`
+      );
+  } else {
+    lines.push(`- No run improvements prepared.`);
+  }
+  if (r.learning.available) {
+    lines.push(
+      `- Learning memory: ${r.learning.activeDecisionCount} active decision(s), ${r.learning.activeRiskCount} active risk(s).`
+    );
+  }
+  lines.push(``);
+
+  // What was proven
+  lines.push(`## What Was Proven`);
+  lines.push(``);
+  if (r.proof.validatedSignals.length > 0) {
+    for (const s of r.proof.validatedSignals) {
+      lines.push(`- **${s.signal}** [${s.proofType}]: ${s.description}`);
+    }
+  } else {
+    lines.push(
+      `No validated signals. Run an Avorelo session to generate evidence.`
+    );
+  }
+  lines.push(``);
+  if (r.proof.limitations.length > 0) {
+    lines.push(`**Proof limitations:**`);
+    for (const l of r.proof.limitations) lines.push(`- ${l}`);
+    lines.push(``);
+  }
+
+  // Estimated savings
+  lines.push(`## Estimated Savings`);
+  lines.push(``);
+  if (sv.estimates.length > 0) {
+    for (const e of sv.estimates) {
+      const range = e.estimatedMinutesRange
+        ? `${e.estimatedMinutesRange.min}–${e.estimatedMinutesRange.max} min`
+        : "n/a";
+      lines.push(`- **${e.category}**: estimated ${range}, ${e.confidence} confidence.`);
+      lines.push(`  Basis: ${e.basis}`);
+      if (e.limitations.length > 1)
+        lines.push(`  Limitation: ${e.limitations[1]}`);
+    }
+  } else {
+    lines.push(`No savings estimates. Insufficient evidence.`);
+  }
+  lines.push(``);
+  for (const l of sv.limitations.slice(0, 3)) lines.push(`> ${l}`);
+  lines.push(``);
+
+  // Risks and limitations
+  lines.push(`## Risks and Limitations`);
+  lines.push(``);
+  if (r.risk.openRisks.length > 0) {
+    lines.push(`**Open risks:**`);
+    for (const rk of r.risk.openRisks) {
+      lines.push(`- [${rk.severity}] **${rk.category}**: ${rk.title}`);
+      lines.push(`  Mitigation: ${rk.nextMitigation}`);
+    }
+    lines.push(``);
+  }
+  if (r.risk.reducedRisks.length > 0) {
+    lines.push(`**Risks reduced:**`);
+    for (const rk of r.risk.reducedRisks) {
+      lines.push(`- ~~${rk.category}~~: ${rk.title}`);
+    }
+    lines.push(``);
+  }
+  if (r.risk.blockedClaims.length > 0) {
+    lines.push(`**Blocked claims:**`);
+    for (const bc of r.risk.blockedClaims) {
+      lines.push(`- [${bc.severity}] ${bc.title}`);
+      lines.push(`  Fix: ${bc.nextMitigation}`);
+    }
+    lines.push(``);
+  }
+
+  // Run Improvements outcome
+  lines.push(`## Run Improvements Outcome`);
+  lines.push(``);
+  lines.push(`Status: \`${ri.status}\``);
+  lines.push(`- Prepared: ${ri.prepared}`);
+  lines.push(`- Consumed: ${ri.consumed}`);
+  lines.push(
+    `- Applied: ${ri.applied}${
+      ri.applied ? ` (receipt confirmed)` : ` (requires lifecycle receipt)`
+    }`
+  );
+  lines.push(`- Injected: ${ri.injected}`);
+  if (ri.categories.length > 0)
+    lines.push(`- Categories: ${ri.categories.join(", ")}`);
+  lines.push(``);
+  for (const l of ri.limitations) lines.push(`> ${l}`);
+  lines.push(``);
+
+  // Learning influence
+  lines.push(`## Learning Influence`);
+  lines.push(``);
+  if (r.learning.available) {
+    lines.push(`- Active decisions: ${r.learning.activeDecisionCount}`);
+    lines.push(`- Active risks: ${r.learning.activeRiskCount}`);
+    lines.push(`- Capabilities: ${r.learning.capabilityCount}`);
+    lines.push(`- Stale items: ${r.learning.staleItemCount}`);
+    if (r.learning.topLearningSignals.length > 0) {
+      lines.push(``);
+      lines.push(`**Top learning signals:**`);
+      for (const s of r.learning.topLearningSignals) {
+        lines.push(`- [${s.type}, conf=${s.confidence}] ${s.summary}`);
+      }
+    }
+    if (r.learning.nextRunInfluence.length > 0) {
+      lines.push(``);
+      lines.push(`**Next-run influence:**`);
+      for (const inf of r.learning.nextRunInfluence) {
+        lines.push(`- ${inf.text}`);
+      }
+    }
+  } else {
+    lines.push(
+      `Learning memory not available. ${r.learning.limitations[0] || ""}`
+    );
+  }
+  lines.push(``);
+
+  // Next action
+  lines.push(`## Next Action`);
+  lines.push(``);
+  lines.push(`**${r.nextBestAction.title}**`);
+  lines.push(``);
+  lines.push(r.nextBestAction.reason);
+  lines.push(`Priority: ${r.nextBestAction.priority}`);
+  lines.push(``);
+
+  // Evidence quality
+  lines.push(`## Evidence Quality`);
+  lines.push(``);
+  lines.push(`Quality: **${r.evidenceQuality}**`);
+  lines.push(`Proof type: ${r.proof.proofType}`);
+  lines.push(`Coverage: ${r.proof.proofCoverage}`);
+  lines.push(``);
+  if (r.limitations.length > 0) {
+    lines.push(`**Report limitations:**`);
+    for (const l of r.limitations) lines.push(`- ${l}`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+// ── Compact status/dashboard surface ─────────────────────────────────────────
+
+function buildProofSavingsSurface(cwd) {
+  const ev = collectEvidence(cwd);
+  const evidenceQuality = classifyEvidenceQuality(ev);
+  const proof = buildProofSection(ev);
+  const savings = buildSavingsSection(ev);
+  const risk = buildRiskSection(ev);
+  const riSection = buildRunImprovementsSection(ev);
+
+  const totalMin = savings.conservativeTotalMinutesRange;
+  const rangeText = totalMin
+    ? `${totalMin.min}–${totalMin.max} min estimated`
+    : "no estimate";
+
+  const statusLine = `Proof & Savings: ${proof.validatedSignalCount} validated signal(s), ${rangeText}, ${savings.overallConfidence} confidence, ${risk.openRiskCount} limitation(s).`;
+
+  const shouldShow =
+    proof.validatedSignalCount > 0 || ev.runImprovements !== null;
+
+  // Compact token/cost evidence line
+  let tokenCostLine = null;
+  try {
+    const { formatTokenCostEvidenceStatusLine } = require("./token-cost-evidence");
+    tokenCostLine = formatTokenCostEvidenceStatusLine(ev.tokenCostEvidence);
+  } catch {}
+
+  return {
+    showInStatus: shouldShow,
+    statusLine,
+    evidenceQuality,
+    estimatedSavings: totalMin,
+    openRisks: risk.openRiskCount,
+    nextBestAction: buildNextBestAction(ev, proof, savings, risk, riSection).title,
+    validatedSignalCount: proof.validatedSignalCount,
+    savingsConfidence: savings.overallConfidence,
+    tokenCostEvidence: {
+      available: !!ev.tokenCostEvidence,
+      statusLine: tokenCostLine,
+      totalTokens: savings.tokenCostEvidence?.totalTokens ?? null,
+      totalCost: savings.tokenCostEvidence?.totalCost ?? null,
+      confidence: savings.tokenCostConfidence,
+      limitations: savings.tokenCostLimitations,
+    },
+  };
+}
+
+function formatProofSavingsStatusLine(cwd) {
+  const surface = buildProofSavingsSurface(cwd);
+  if (!surface.showInStatus) return null;
+  return surface.statusLine;
+}
+
+// ── Audit event ───────────────────────────────────────────────────────────────
+
+function _emitAuditEvent(cwd, report) {
+  const eventsPath = path.join(cwd, ".claude/cco/events/outcome-events.jsonl");
+  fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+  const event = JSON.stringify({
+    event_id: `psr_generated_${report.sourceFingerprint}`,
+    session_id: "avorelo-proof-savings-report",
+    timestamp: report.generatedAt,
+    category: "proof_savings_report",
+    event_name: "proof_savings_report_generated",
+    reason_code: "PROOF_SAVINGS_REPORT_GENERATED",
+    confidence_score: 1.0,
+    platform: "avorelo",
+    metadata: {
+      schemaVersion: report.schemaVersion,
+      evidenceQuality: report.evidenceQuality,
+      validatedSignalCount: report.proof.validatedSignalCount,
+      savingsConfidence: report.savings.overallConfidence,
+      openRiskCount: report.risk.openRiskCount,
+      reportPaths: [REPORT_JSON_REL, REPORT_MD_REL],
+      redactionStatus: report.redactionStatus,
+      reasonCodes: report.reasonCodes.slice(0, 5),
+    },
+  });
+  fs.appendFileSync(eventsPath, event + "\n", "utf8");
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  REPORT_JSON_REL,
+  REPORT_MD_REL,
+  EVIDENCE_QUALITY_VALUES,
+  PROOF_TYPES,
+  SAVINGS_CATEGORIES,
+  RISK_CATEGORIES,
+  MINUTE_HEURISTICS,
+  collectEvidence,
+  classifyEvidenceQuality,
+  buildProofSection,
+  buildSavingsSection,
+  buildRiskSection,
+  buildRunImprovementsSection,
+  buildLearningSection,
+  buildNextBestAction,
+  buildProofSavingsReport,
+  generateProofSavingsReport,
+  loadProofSavingsReport,
+  formatReportMarkdown,
+  buildProofSavingsSurface,
+  formatProofSavingsStatusLine,
+};