avorelo 0.1.0 → 0.3.0

package/scripts/lib/run-improvements.js

@@ -1,789 +0,0 @@
-"use strict";
-
-// Run Improvements: local-first next-run preparation based on evidence from the previous run.
-// Generates a canonical artifact with improvement categories and next-run defaults.
-// No cloud calls, no LLM, no daemon, no hidden destructive actions.
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-
-const RUN_IMPROVEMENTS_REL = ".claude/cco/state/run-improvements.json";
-const SCHEMA_VERSION = "avorelo.runImprovements.v1";
-const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-const IMPROVEMENT_CATEGORIES = [
-  "stale_context",
-  "missing_validation",
-  "rework_loop",
-  "instruction_noise",
-  "risky_action",
-  "unclear_continuation",
-  "oversized_scope",
-  "missing_proof",
-  "cost_or_token_waste",
-  "repo_state_risk",
-];
-
-const STATUSES = [
-  "not_available",
-  "insufficient_evidence",
-  "prepared",
-  "consumed",
-  "applied",
-  "expired",
-  "stale",
-  "skipped",
-  "error",
-];
-
-const MODES = ["observe", "prepare", "enforce"];
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function expiresAtFromNow(fromIso) {
-  const base = fromIso ? new Date(fromIso) : new Date();
-  return new Date(base.getTime() + TTL_MS).toISOString();
-}
-
-function isExpired(artifact) {
-  if (!artifact || !artifact.expiresAt) return true;
-  return Date.now() > new Date(artifact.expiresAt).getTime();
-}
-
-// Stable fingerprint from the key signals that determine improvements.
-// Same evidence → same fingerprint → idempotent artifact.
-function buildSourceFingerprint(signals) {
-  const stable = JSON.stringify({
-    budgetStatus: signals?.contextBudget?.status || "unknown",
-    budgetPercent: Math.round((signals?.contextBudget?.usedPercent || 0) / 10) * 10,
-    reentryIntervention: signals?.reentryState?.lastInterventionType || "none",
-    unresolvedRisk: Boolean(signals?.reentryState?.unresolvedRisk),
-    weeklyEventCount: signals?.outcomeEvents?.weeklyEventCount || 0,
-    loopDetected: Boolean(signals?.outcomeEvents?.loopDetected),
-    riskySkillCount: signals?.outcomeEvents?.riskySkillCount || 0,
-    validationState: signals?.validationState || "missing",
-    carryForwardAvailable: Boolean(signals?.carryForward?.available),
-    hasProofReceipt: Boolean(signals?.latestProofReceipt?.available),
-    proofStatus: signals?.latestProofReceipt?.completionStatus || "unknown",
-  });
-  return crypto.createHash("sha256").update(stable).digest("hex").slice(0, 16);
-}
-
-// Load the latest proof receipt to detect validation/completion signals.
-function loadLatestProofReceipt(cwd) {
-  try {
-    const receiptsDir = path.join(cwd, ".claude", "cco", "receipts");
-    if (!fs.existsSync(receiptsDir)) return null;
-    const files = fs.readdirSync(receiptsDir).filter((f) => f.endsWith(".json"));
-    if (!files.length) return null;
-    const latest = files
-      .map((name) => ({ name, mtimeMs: fs.statSync(path.join(receiptsDir, name)).mtimeMs }))
-      .sort((a, b) => b.mtimeMs - a.mtimeMs)[0];
-    const raw = JSON.parse(fs.readFileSync(path.join(receiptsDir, latest.name), "utf8"));
-    return {
-      available: true,
-      completionStatus: raw.result?.status || "unknown",
-      material: raw.material || false,
-      improvements: raw.improvements || [],
-      antiGamingValid: raw.anti_gaming?.valid !== false,
-    };
-  } catch {
-    return null;
-  }
-}
-
-// Safe read-only repo state check. Fails open to "unknown".
-// No write, no stage, no commit, no network, no config mutation.
-function collectRepoState(cwd) {
-  try {
-    const { spawnSync } = require("child_process");
-    const result = spawnSync("git", ["status", "--porcelain"], {
-      cwd,
-      encoding: "utf8",
-      timeout: 3000,
-    });
-    if (result.status !== 0 || result.error) return "unknown";
-    const output = (result.stdout || "").trim();
-    return output.length > 0 ? "dirty" : "clean";
-  } catch {
-    return "unknown";
-  }
-}
-
-function collectSignals(cwd) {
-  const signals = {
-    contextBudget: null,
-    reentryState: null,
-    carryForward: null,
-    outcomeEvents: null,
-    workflowDiscipline: null,
-    latestProofReceipt: null,
-    validationState: "missing",
-    riskLevel: "low",
-    repoState: "unknown",
-  };
-
-  // Context budget
-  try {
-    const { loadBudgetState } = require("./context-budget-guard");
-    const budgetState = loadBudgetState(cwd);
-    if (budgetState) {
-      signals.contextBudget = {
-        status: budgetState.status || "ok",
-        usedPercent: budgetState.usedPercent || 0,
-        usedChars: budgetState.usedChars || 0,
-      };
-    }
-  } catch {}
-
-  // Reentry state
-  try {
-    const { loadReentryState } = require("./reentry-state");
-    const rs = loadReentryState(cwd);
-    if (rs) {
-      signals.reentryState = {
-        lastInterventionType: rs.lastInterventionType || "none",
-        unresolvedRisk: Boolean(rs.unresolvedRisk),
-        nextAction: rs.nextAction || null,
-      };
-      if (rs.unresolvedRisk) {
-        signals.riskLevel = "high";
-      }
-    }
-  } catch {}
-
-  // Carry-forward
-  try {
-    const { loadCarryForward } = require("./carry-forward-surfacing");
-    const cf = loadCarryForward(cwd);
-    signals.carryForward = {
-      available: cf !== null,
-      sessionId: cf?.sessionId || null,
-      toolHistoryDepth: cf?.toolHistory?.toolNames?.length || 0,
-    };
-  } catch {}
-
-  // Latest proof receipt
-  signals.latestProofReceipt = loadLatestProofReceipt(cwd);
-  if (signals.latestProofReceipt?.completionStatus === "completed") {
-    signals.validationState = "passed";
-  } else if (signals.latestProofReceipt?.available) {
-    signals.validationState = "partial";
-  }
-
-  // Outcome events (last 7 days)
-  try {
-    const { readOutcomeEvents, aggregateOutcomeEvents } = require("./unified-events");
-    const rawEvents = readOutcomeEvents(cwd);
-    // Exclude run_improvements audit events from signal calculation to preserve idempotency
-    const events = rawEvents.filter((e) => e.category !== "run_improvements");
-    if (events.length > 0) {
-      const agg = aggregateOutcomeEvents(events, { days: 7 });
-      const weekly = agg.weeklyRepoSummary || {};
-      const byCategory = weekly.byCategory || {};
-      signals.outcomeEvents = {
-        weeklyEventCount: weekly.events || 0,
-        loopDetected: (byCategory.loop_detected || 0) > 0,
-        loopCount: byCategory.loop_detected || 0,
-        riskySkillCount: byCategory.risky_skill_flagged || 0,
-        outputTrimmedCount: byCategory.output_trimmed || 0,
-        tokenUsageTotal: weekly.tokenUsageTotal || 0,
-        measuredCostTotal: weekly.measuredCostTotal || 0,
-        topReasonCodes: agg.sessionSummary?.topReasonCodes || [],
-      };
-    }
-  } catch {}
-
-  // Safe read-only repo state
-  signals.repoState = collectRepoState(cwd);
-
-  // Workflow discipline — inferred from available signals
-  try {
-    const { buildWorkflowDisciplineStatus } = require("./workflow-discipline");
-    const budgetStatus = signals.contextBudget?.status || "ok";
-    const contextPressure =
-      budgetStatus === "critical" ? "critical" : budgetStatus === "warn" ? "warn" : "ok";
-    const reentryAvailable = signals.carryForward?.available ? "available" : "missing";
-    const loopDetected = signals.outcomeEvents?.loopDetected || false;
-
-    const wdInput = {
-      taskType: "unknown",
-      riskLevel: signals.riskLevel,
-      repoState: signals.repoState === "dirty" ? "modified" : signals.repoState === "clean" ? "clean" : "unknown",
-      contextPressure,
-      reentryState: reentryAvailable,
-      validationState: signals.validationState,
-      agentSecurityState: signals.reentryState?.unresolvedRisk ? "warn" : "off",
-      ambiguous: false,
-      repetitiveAgent: loopDetected,
-    };
-    signals.workflowDiscipline = buildWorkflowDisciplineStatus(wdInput, {});
-  } catch {}
-
-  // Learning summary (compact influence on next-run defaults)
-  try {
-    const { loadLearningSummary } = require("./learning-memory");
-    signals.learningSummary = loadLearningSummary(cwd);
-  } catch {
-    signals.learningSummary = null;
-  }
-
-  return signals;
-}
-
-function generateImprovements(signals) {
-  const improvements = [];
-  let idx = 0;
-
-  const budgetStatus = signals.contextBudget?.status;
-
-  // stale_context: context window was under pressure
-  if (budgetStatus === "critical" || budgetStatus === "warn") {
-    improvements.push({
-      id: `imp_${++idx}_stale_context`,
-      category: "stale_context",
-      severity: budgetStatus === "critical" ? "critical" : "warn",
-      title: "Context window was under pressure",
-      evidence: `Context usage at ${signals.contextBudget.usedPercent}%`,
-      recommendedDefault: "prefer carry-forward summary over full stale context",
-      reasonCodes: [`CTX_PRESSURE_${budgetStatus.toUpperCase()}`],
-      confidence: budgetStatus === "critical" ? 0.92 : 0.75,
-      source: "contextBudget",
-    });
-  }
-
-  // rework_loop: repeated tool loops detected
-  if (signals.outcomeEvents?.loopDetected) {
-    improvements.push({
-      id: `imp_${++idx}_rework_loop`,
-      category: "rework_loop",
-      severity: "warn",
-      title: "Repeated tool loops detected",
-      evidence: `${signals.outcomeEvents.loopCount} loop event(s) in last 7 days`,
-      recommendedDefault: "ask for a plan or options before re-executing the same approach",
-      reasonCodes: ["LOOP_REPEATED_TOOL"],
-      confidence: 0.81,
-      source: "outcomeEvents",
-    });
-  }
-
-  // risky_action: unresolved risk from reentry
-  if (signals.reentryState?.unresolvedRisk) {
-    const interventionCode = String(signals.reentryState.lastInterventionType || "unknown")
-      .toUpperCase()
-      .replace(/-/g, "_");
-    improvements.push({
-      id: `imp_${++idx}_risky_action`,
-      category: "risky_action",
-      severity: "critical",
-      title: "Unresolved risk from previous run",
-      evidence: `Last intervention: ${signals.reentryState.lastInterventionType}`,
-      recommendedDefault: "ask for confirmation before risky or destructive actions",
-      reasonCodes: ["UNRESOLVED_RISK", `INTERVENTION_${interventionCode}`],
-      confidence: 0.90,
-      source: "reentryState",
-    });
-  }
-
-  // risky_action from security events (only if not already from reentry)
-  if (
-    (signals.outcomeEvents?.riskySkillCount || 0) > 0 &&
-    !improvements.find((i) => i.category === "risky_action")
-  ) {
-    improvements.push({
-      id: `imp_${++idx}_risky_action_events`,
-      category: "risky_action",
-      severity: "warn",
-      title: "Risky tool actions detected in session events",
-      evidence: `${signals.outcomeEvents.riskySkillCount} risky skill event(s) in last 7 days`,
-      recommendedDefault: "ask for confirmation before risky or destructive actions",
-      reasonCodes: ["RISKY_SKILL_FLAGGED"],
-      confidence: 0.83,
-      source: "outcomeEvents",
-    });
-  }
-
-  // missing_validation: no completed proof receipt
-  if (signals.validationState === "missing" || signals.validationState === "partial") {
-    const isPartial = signals.validationState === "partial";
-    improvements.push({
-      id: `imp_${++idx}_missing_validation`,
-      category: "missing_validation",
-      severity: isPartial ? "info" : "warn",
-      title: isPartial ? "Validation proof incomplete from previous run" : "No validation proof from previous run",
-      evidence: isPartial
-        ? "Proof receipt exists but completion status is not 'completed'"
-        : "No proof receipt found for last run",
-      recommendedDefault: "require validation proof before claiming done",
-      reasonCodes: [isPartial ? "VALIDATION_PARTIAL" : "VALIDATION_MISSING"],
-      confidence: isPartial ? 0.68 : 0.72,
-      source: "latestProofReceipt",
-    });
-  }
-
-  // missing_proof: no receipt at all and there was activity
-  if (
-    !signals.latestProofReceipt?.available &&
-    (signals.outcomeEvents?.weeklyEventCount || 0) > 0
-  ) {
-    if (!improvements.find((i) => i.category === "missing_proof")) {
-      improvements.push({
-        id: `imp_${++idx}_missing_proof`,
-        category: "missing_proof",
-        severity: "info",
-        title: "No proof receipt found for recent sessions",
-        evidence: `${signals.outcomeEvents.weeklyEventCount} events logged but no receipt written`,
-        recommendedDefault: "require proof/receipt output at end of run",
-        reasonCodes: ["NO_PROOF_RECEIPT", "EVENTS_WITHOUT_RECEIPT"],
-        confidence: 0.65,
-        source: "outcomeEvents",
-      });
-    }
-  }
-
-  // cost_or_token_waste: high token usage with loop signals
-  if (
-    (signals.outcomeEvents?.tokenUsageTotal || 0) > 50000 &&
-    signals.outcomeEvents?.loopDetected
-  ) {
-    improvements.push({
-      id: `imp_${++idx}_cost_or_token_waste`,
-      category: "cost_or_token_waste",
-      severity: "info",
-      title: "High token usage with loop signals",
-      evidence: `${signals.outcomeEvents.tokenUsageTotal} tokens used with loop detection active`,
-      recommendedDefault: "run targeted tests before full suite to reduce redundant token spend",
-      reasonCodes: ["HIGH_TOKEN_USAGE", "LOOP_REPEATED_TOOL"],
-      confidence: 0.65,
-      source: "outcomeEvents",
-    });
-  }
-
-  // repo_state_risk: unresolved risk with unknown repo state
-  if (signals.reentryState?.unresolvedRisk && signals.repoState === "unknown") {
-    improvements.push({
-      id: `imp_${++idx}_repo_state_risk`,
-      category: "repo_state_risk",
-      severity: "warn",
-      title: "Repo state unknown with unresolved risk",
-      evidence: "Unresolved risk detected and repo state not verified",
-      recommendedDefault: "preserve rollback or undo note before continuing",
-      reasonCodes: ["UNRESOLVED_RISK", "REPO_STATE_UNKNOWN"],
-      confidence: 0.70,
-      source: "reentryState",
-    });
-  }
-
-  // unclear_continuation: no carry-forward + past intervention
-  if (
-    !signals.carryForward?.available &&
-    signals.reentryState?.lastInterventionType &&
-    signals.reentryState.lastInterventionType !== "none"
-  ) {
-    improvements.push({
-      id: `imp_${++idx}_unclear_continuation`,
-      category: "unclear_continuation",
-      severity: "info",
-      title: "No carry-forward context for continuation",
-      evidence: "Previous run ended without carry-forward state capture",
-      recommendedDefault: "prefer carry-forward summary for context continuity",
-      reasonCodes: ["NO_CARRY_FORWARD", "REENTRY_MISSING"],
-      confidence: 0.63,
-      source: "carryForward",
-    });
-  }
-
-  // instruction_noise: signal-backed from context pressure + carry-forward depth
-  // Only generated when concrete signals support it; otherwise remains insufficient_evidence.
-  const carryForwardDepth = signals.carryForward?.toolHistoryDepth || 0;
-  const ctxCritical = budgetStatus === "critical";
-  const ctxWarn = budgetStatus === "warn";
-  const heavyCarryForward = carryForwardDepth >= 3;
-  const wdRecommendations = signals.workflowDiscipline?.recommendations || [];
-  const wdHandoff = wdRecommendations.some((r) => r.id === "WF_HANDOFF_COMPRESS");
-  if (ctxCritical && (heavyCarryForward || wdHandoff)) {
-    improvements.push({
-      id: `imp_${++idx}_instruction_noise`,
-      category: "instruction_noise",
-      severity: "warn",
-      title: "Context pressure with heavy carry-forward suggests instruction noise",
-      evidence:
-        `Context at ${signals.contextBudget.usedPercent}% (critical)` +
-        (heavyCarryForward ? `, carry-forward depth ${carryForwardDepth}` : "") +
-        (wdHandoff ? ", workflow recommends compress/handoff" : ""),
-      recommendedDefault: "reduce stale context and clarify scope before next run",
-      reasonCodes: [
-        "CTX_PRESSURE_CRITICAL",
-        heavyCarryForward ? "HEAVY_CARRY_FORWARD" : null,
-        wdHandoff ? "WF_HANDOFF_COMPRESS" : null,
-      ].filter(Boolean),
-      confidence: 0.70,
-      source: "contextBudget",
-    });
-  } else if (ctxWarn && heavyCarryForward) {
-    improvements.push({
-      id: `imp_${++idx}_instruction_noise`,
-      category: "instruction_noise",
-      severity: "info",
-      title: "Context pressure with deep carry-forward may introduce noise",
-      evidence: `Context at ${signals.contextBudget.usedPercent}% (warn), carry-forward depth ${carryForwardDepth}`,
-      recommendedDefault: "prefer fresh compact context over full carry-forward when context is under pressure",
-      reasonCodes: ["CTX_PRESSURE_WARN", "HEAVY_CARRY_FORWARD"],
-      confidence: 0.60,
-      source: "contextBudget",
-    });
-  }
-  // If no signal: instruction_noise remains undefined (insufficient_evidence) — do not generate it.
-
-  // oversized_scope: signal-backed from output trimming, token waste without loop, or WF_PLAN_FIRST
-  const outputTrimmedCount = signals.outcomeEvents?.outputTrimmedCount || 0;
-  const wdPlanFirst = wdRecommendations.some((r) => r.id === "WF_PLAN_FIRST");
-  const highTokenNoLoop =
-    (signals.outcomeEvents?.tokenUsageTotal || 0) > 100000 &&
-    !signals.outcomeEvents?.loopDetected;
-  if (outputTrimmedCount > 0 || wdPlanFirst || highTokenNoLoop) {
-    const evidenceParts = [];
-    if (outputTrimmedCount > 0) evidenceParts.push(`${outputTrimmedCount} output(s) trimmed`);
-    if (wdPlanFirst) evidenceParts.push("workflow recommends plan-first");
-    if (highTokenNoLoop)
-      evidenceParts.push(`${signals.outcomeEvents.tokenUsageTotal} tokens without loop`);
-    improvements.push({
-      id: `imp_${++idx}_oversized_scope`,
-      category: "oversized_scope",
-      severity: "warn",
-      title: "Scope may have been too broad for clean single-run completion",
-      evidence: evidenceParts.join("; "),
-      recommendedDefault: "define a clear scope boundary and acceptance criteria before next run",
-      reasonCodes: [
-        outputTrimmedCount > 0 ? "OUTPUT_TRIMMED" : null,
-        wdPlanFirst ? "WF_PLAN_FIRST" : null,
-        highTokenNoLoop ? "HIGH_TOKEN_NO_LOOP" : null,
-      ].filter(Boolean),
-      confidence: wdPlanFirst ? 0.72 : 0.65,
-      source: "outcomeEvents",
-    });
-  }
-  // If no signal: oversized_scope remains undefined (insufficient_evidence) — do not generate it.
-
-  // Deduplicate by category (keep highest confidence)
-  const byCat = new Map();
-  for (const imp of improvements) {
-    const existing = byCat.get(imp.category);
-    if (!existing || imp.confidence > existing.confidence) {
-      byCat.set(imp.category, imp);
-    }
-  }
-
-  const deduped = [...byCat.values()];
-
-  // Sort: confidence desc, then severity rank
-  const severityRank = { critical: 3, warn: 2, info: 1 };
-  deduped.sort((a, b) => {
-    const confDiff = b.confidence - a.confidence;
-    if (Math.abs(confDiff) > 0.05) return confDiff;
-    return (severityRank[b.severity] || 0) - (severityRank[a.severity] || 0);
-  });
-
-  return deduped.slice(0, 5);
-}
-
-function generateNextRunDefaults(improvements, learningSummary) {
-  const defaults = [];
-  const seen = new Set();
-
-  for (const imp of improvements) {
-    const text = imp.recommendedDefault;
-    if (!text || seen.has(text)) continue;
-    seen.add(text);
-    defaults.push({
-      id: `def_${imp.category}`,
-      text,
-      reasonCodes: imp.reasonCodes,
-      source: imp.category,
-    });
-  }
-
-  // Learning influence: append bounded, reason-coded defaults from learning summary.
-  // Learning may recommend but never silently overrides user instructions.
-  // Only include influence that is not already covered by evidence-based defaults.
-  if (learningSummary && Array.isArray(learningSummary.nextRunInfluence)) {
-    for (const influence of learningSummary.nextRunInfluence) {
-      if (!influence.text || seen.has(influence.text)) continue;
-      seen.add(influence.text);
-      defaults.push({
-        id: `def_learning_${influence.type}`,
-        text: influence.text,
-        reasonCodes: influence.reasonCodes || [],
-        source: "learning",
-      });
-    }
-  }
-
-  return defaults;
-}
-
-function buildPublicSummary(status, topImprovements, nextRunDefaults) {
-  if (status === "not_available") {
-    return "Run Improvements: not available. No prior run evidence found.";
-  }
-  if (status === "insufficient_evidence") {
-    return "Run Improvements: insufficient evidence. No improvements generated.";
-  }
-  if (status === "expired") {
-    return "Run Improvements: expired. Run again to refresh.";
-  }
-  if (status === "error") {
-    return "Run Improvements: error generating improvements.";
-  }
-  if (status === "skipped") {
-    return "Run Improvements: skipped.";
-  }
-
-  const topDefault = nextRunDefaults[0];
-  const improvementNote = topDefault
-    ? `Next run: ${topDefault.text}.`
-    : "No improvements needed.";
-
-  const topCategories = [...new Set(topImprovements.map((i) => i.category))].slice(0, 2);
-  const whyNote =
-    topCategories.length > 0
-      ? `Why: ${topCategories.map((c) => c.replace(/_/g, " ")).join(" and ")}.`
-      : "";
-
-  return [`Run Improvements: ${status}.`, improvementNote, whyNote].filter(Boolean).join(" ");
-}
-
-function buildRunImprovements(cwd, options = {}) {
-  const mode = MODES.includes(options.mode) ? options.mode : "prepare";
-  const generatedAt = nowIso();
-
-  let signals;
-  try {
-    signals = collectSignals(cwd);
-  } catch (err) {
-    return {
-      schemaVersion: SCHEMA_VERSION,
-      generatedAt,
-      expiresAt: expiresAtFromNow(generatedAt),
-      sourceRunFingerprint: "error",
-      status: "error",
-      mode,
-      applied: false,
-      appliedAt: null,
-      sourceSignals: {},
-      topImprovements: [],
-      nextRunDefaults: [],
-      publicSummary: "Run Improvements: error collecting signals.",
-      reasonCodes: ["SIGNAL_COLLECTION_ERROR"],
-      limitations: [String(err.message)],
-    };
-  }
-
-  const fingerprint = buildSourceFingerprint(signals);
-
-  const hasAnySignal =
-    signals.contextBudget !== null ||
-    signals.reentryState !== null ||
-    signals.outcomeEvents !== null ||
-    signals.latestProofReceipt !== null;
-
-  if (!hasAnySignal) {
-    return {
-      schemaVersion: SCHEMA_VERSION,
-      generatedAt,
-      expiresAt: expiresAtFromNow(generatedAt),
-      sourceRunFingerprint: fingerprint,
-      status: "not_available",
-      mode,
-      applied: false,
-      appliedAt: null,
-      sourceSignals: signals,
-      topImprovements: [],
-      nextRunDefaults: [],
-      publicSummary: "Run Improvements: not available. No prior run evidence found.",
-      reasonCodes: ["NO_EVIDENCE"],
-      limitations: ["No prior run artifacts found. Run an Avorelo session first."],
-    };
-  }
-
-  const topImprovements = generateImprovements(signals);
-
-  if (topImprovements.length === 0) {
-    return {
-      schemaVersion: SCHEMA_VERSION,
-      generatedAt,
-      expiresAt: expiresAtFromNow(generatedAt),
-      sourceRunFingerprint: fingerprint,
-      status: "insufficient_evidence",
-      mode,
-      applied: false,
-      appliedAt: null,
-      sourceSignals: signals,
-      topImprovements: [],
-      nextRunDefaults: [],
-      publicSummary: "Run Improvements: insufficient evidence. No improvements generated.",
-      reasonCodes: ["INSUFFICIENT_EVIDENCE"],
-      limitations: ["Signal sources present but no actionable improvements derived."],
-    };
-  }
-
-  const nextRunDefaults = generateNextRunDefaults(topImprovements, signals.learningSummary);
-  const reasonCodes = [...new Set(topImprovements.flatMap((i) => i.reasonCodes))];
-  const publicSummary = buildPublicSummary("prepared", topImprovements, nextRunDefaults);
-
-  return {
-    schemaVersion: SCHEMA_VERSION,
-    generatedAt,
-    expiresAt: expiresAtFromNow(generatedAt),
-    sourceRunFingerprint: fingerprint,
-    status: "prepared",
-    mode,
-    applied: false,
-    appliedAt: null,
-    sourceSignals: signals,
-    topImprovements,
-    nextRunDefaults,
-    publicSummary,
-    reasonCodes,
-    limitations: [
-      "Defaults are prepared and visible in status/dashboard output.",
-      "Applied state requires explicit consume/apply via a supported surface.",
-      "No cloud calls, no LLM, no daemon — purely evidence-based.",
-      "instruction_noise and oversized_scope require specific signal combinations.",
-    ],
-  };
-}
-
-// Write artifact. Idempotent: same fingerprint + not expired → skip rewrite.
-function generateRunImprovementsArtifact(cwd, options = {}) {
-  const artifact = buildRunImprovements(cwd, options);
-
-  const existing = loadRunImprovements(cwd);
-  if (
-    existing &&
-    !isExpired(existing) &&
-    existing.sourceRunFingerprint === artifact.sourceRunFingerprint &&
-    existing.status === artifact.status
-  ) {
-    return { artifact: existing, written: false, reason: "same_fingerprint_not_expired" };
-  }
-
-  const absPath = path.join(cwd, RUN_IMPROVEMENTS_REL);
-  fs.mkdirSync(path.dirname(absPath), { recursive: true });
-  fs.writeFileSync(absPath, JSON.stringify(artifact, null, 2), "utf8");
-
-  try {
-    _emitAuditEvent(cwd, artifact);
-  } catch {}
-
-  return { artifact, written: true, reason: "generated" };
-}
-
-function loadRunImprovements(cwd) {
-  try {
-    const absPath = path.join(cwd, RUN_IMPROVEMENTS_REL);
-    const raw = JSON.parse(fs.readFileSync(absPath, "utf8"));
-    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
-    if (isExpired(raw)) {
-      raw.status = "expired";
-    }
-    return raw;
-  } catch {
-    return null;
-  }
-}
-
-function formatRunImprovementsText(cwd) {
-  const artifact = loadRunImprovements(cwd);
-  if (!artifact || artifact.status === "not_available" || artifact.status === "expired") {
-    return null;
-  }
-  const lines = [artifact.publicSummary];
-  if (
-    (artifact.status === "prepared" || artifact.status === "applied") &&
-    artifact.nextRunDefaults.length > 0
-  ) {
-    const top = artifact.nextRunDefaults[0];
-    lines.push(`  Next: ${top.text}`);
-  }
-  return lines.join("\n");
-}
-
-function formatRunImprovementsStatusLine(cwd) {
-  const artifact = loadRunImprovements(cwd);
-  if (!artifact || artifact.status === "not_available") return null;
-  if (artifact.status === "expired") {
-    return "Run Improvements: expired";
-  }
-  if (artifact.status === "insufficient_evidence") {
-    return "Run Improvements: no actionable improvements from last run";
-  }
-  if (artifact.status === "prepared" || artifact.status === "applied") {
-    const topCats = [...new Set(artifact.topImprovements.map((i) => i.category))].slice(0, 2);
-    const catText = topCats.map((c) => c.replace(/_/g, " ")).join(", ");
-    return `Run Improvements: ${artifact.status} · ${artifact.topImprovements.length} improvement(s) · focus: ${catText || "general"}`;
-  }
-  return null;
-}
-
-function buildRunImprovementsSurface(cwd) {
-  const artifact = loadRunImprovements(cwd);
-  if (!artifact) {
-    return { showInStatus: false, statusLine: null, artifact: null };
-  }
-  const statusLine = formatRunImprovementsStatusLine(cwd);
-  return {
-    showInStatus: statusLine !== null,
-    statusLine,
-    artifact,
-  };
-}
-
-function _emitAuditEvent(cwd, artifact) {
-  const eventsPath = path.join(cwd, ".claude/cco/events/outcome-events.jsonl");
-  fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
-  const event = JSON.stringify({
-    event_id: `run_imp_${artifact.sourceRunFingerprint}`,
-    session_id: "avorelo-run-improvements",
-    timestamp: artifact.generatedAt,
-    category: "run_improvements",
-    event_name: "RunImprovementsGenerated",
-    reason_code: "RUN_IMPROVEMENTS_PREPARED",
-    confidence_score: 1.0,
-    platform: "avorelo",
-    metadata: {
-      schemaVersion: artifact.schemaVersion,
-      status: artifact.status,
-      improvementCount: artifact.topImprovements.length,
-      topCategories: [...new Set(artifact.topImprovements.map((i) => i.category))].slice(0, 3),
-      sourceRunFingerprint: artifact.sourceRunFingerprint,
-      redacted: true,
-    },
-  });
-  fs.appendFileSync(eventsPath, event + "\n", "utf8");
-}
-
-module.exports = {
-  SCHEMA_VERSION,
-  IMPROVEMENT_CATEGORIES,
-  STATUSES,
-  MODES,
-  TTL_MS,
-  RUN_IMPROVEMENTS_REL,
-  buildSourceFingerprint,
-  collectRepoState,
-  collectSignals,
-  generateImprovements,
-  generateNextRunDefaults,
-  buildPublicSummary,
-  buildRunImprovements,
-  generateRunImprovementsArtifact,
-  loadRunImprovements,
-  formatRunImprovementsText,
-  formatRunImprovementsStatusLine,
-  buildRunImprovementsSurface,
-  isExpired,
-};