avorelo 0.1.0

package/scripts/lib/run-improvements-lifecycle.js

@@ -0,0 +1,330 @@
+"use strict";
+
+// Run Improvements Lifecycle — manages the consumption and application receipt
+// for next-run defaults prepared by run-improvements.js.
+// Receipt schema: avorelo.runImprovementsReceipt.v1
+//
+// Lifecycle states:
+//   prepared          Improvements generated, ready
+//   consumed          A supported surface explicitly read the prepared defaults
+//   applied           Defaults made available to a next run; receipt exists
+//   expired           TTL exceeded on source artifact
+//   stale             Source fingerprint no longer matches current artifact
+//   insufficient_evidence  Not enough evidence to generate reliable defaults
+//   skipped           Explicitly skipped
+//   error             Unexpected error
+
+const fs = require("fs");
+const path = require("path");
+
+const RECEIPT_REL = ".claude/cco/state/run-improvements-receipt.json";
+const SCHEMA_VERSION = "avorelo.runImprovementsReceipt.v1";
+
+const LIFECYCLE_STATES = [
+  "prepared",
+  "consumed",
+  "applied",
+  "expired",
+  "stale",
+  "insufficient_evidence",
+  "skipped",
+  "error",
+];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function loadLifecycleReceipt(cwd) {
+  try {
+    const absPath = path.join(cwd, RECEIPT_REL);
+    const raw = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+function writeLifecycleReceipt(cwd, receipt) {
+  const absPath = path.join(cwd, RECEIPT_REL);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(receipt, null, 2), "utf8");
+  return receipt;
+}
+
+function buildLifecycleReceipt(artifact, options = {}) {
+  const now = nowIso();
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: now,
+    sourceRunFingerprint: artifact.sourceRunFingerprint,
+    runImprovementsArtifactId: artifact.sourceRunFingerprint,
+    lifecycleState: options.lifecycleState || "prepared",
+    surface: options.surface || null,
+    consumedAt: options.consumedAt || null,
+    appliedAt: options.appliedAt || null,
+    reasonCodes: options.reasonCodes || artifact.reasonCodes || [],
+    redactionStatus: "redacted",
+    limitations: options.limitations || artifact.limitations || [],
+  };
+}
+
+// Check if existing receipt is stale (source fingerprint no longer matches current artifact).
+function checkLifecycleStale(cwd) {
+  const receipt = loadLifecycleReceipt(cwd);
+  if (!receipt) return { stale: false, reason: "no_receipt" };
+
+  try {
+    const { loadRunImprovements } = require("./run-improvements");
+    const artifact = loadRunImprovements(cwd);
+    if (!artifact) return { stale: false, reason: "no_artifact" };
+    if (receipt.sourceRunFingerprint !== artifact.sourceRunFingerprint) {
+      return { stale: true, reason: "fingerprint_mismatch" };
+    }
+    return { stale: false, reason: "ok" };
+  } catch {
+    return { stale: false, reason: "check_error" };
+  }
+}
+
+// Mark as consumed — a supported surface explicitly read the prepared defaults.
+// Idempotent: same fingerprint already consumed or applied → return existing receipt.
+function consumeRunImprovements(cwd, surface) {
+  try {
+    const { loadRunImprovements } = require("./run-improvements");
+    const artifact = loadRunImprovements(cwd);
+    if (!artifact || artifact.status === "not_available" || artifact.status === "expired") {
+      return null;
+    }
+
+    const existing = loadLifecycleReceipt(cwd);
+    if (
+      existing &&
+      existing.sourceRunFingerprint === artifact.sourceRunFingerprint &&
+      (existing.lifecycleState === "consumed" || existing.lifecycleState === "applied")
+    ) {
+      return existing;
+    }
+
+    const now = nowIso();
+    const receipt = buildLifecycleReceipt(artifact, {
+      lifecycleState: "consumed",
+      surface: surface || "cli",
+      consumedAt: now,
+      appliedAt: null,
+    });
+
+    writeLifecycleReceipt(cwd, receipt);
+    _emitLifecycleAuditEvent(cwd, artifact, receipt, "run_improvements.consumed");
+    return receipt;
+  } catch {
+    return null;
+  }
+}
+
+// Mark as applied — defaults were made available to a next AI coding run
+// through a supported surface and an application receipt exists.
+// This is the only honest way to set applied=true on the main artifact.
+function applyRunImprovements(cwd, surface) {
+  try {
+    const { loadRunImprovements, RUN_IMPROVEMENTS_REL, SCHEMA_VERSION: RI_SCHEMA } = require("./run-improvements");
+    const artifact = loadRunImprovements(cwd);
+    if (!artifact || artifact.status === "not_available" || artifact.status === "expired") {
+      return { success: false, reason: "no_valid_artifact" };
+    }
+
+    const existing = loadLifecycleReceipt(cwd);
+    if (
+      existing &&
+      existing.sourceRunFingerprint === artifact.sourceRunFingerprint &&
+      existing.lifecycleState === "applied"
+    ) {
+      return { success: true, receipt: existing, reason: "already_applied" };
+    }
+
+    const now = nowIso();
+    const receipt = buildLifecycleReceipt(artifact, {
+      lifecycleState: "applied",
+      surface: surface || "cli",
+      consumedAt: existing?.consumedAt || now,
+      appliedAt: now,
+    });
+
+    writeLifecycleReceipt(cwd, receipt);
+    _emitLifecycleAuditEvent(cwd, artifact, receipt, "run_improvements.applied");
+
+    // Update the main artifact to reflect applied state (only when fingerprint matches)
+    try {
+      const absPath = path.join(cwd, RUN_IMPROVEMENTS_REL);
+      if (fs.existsSync(absPath)) {
+        const stored = JSON.parse(fs.readFileSync(absPath, "utf8"));
+        if (
+          stored.schemaVersion === RI_SCHEMA &&
+          stored.sourceRunFingerprint === artifact.sourceRunFingerprint
+        ) {
+          stored.status = "applied";
+          stored.applied = true;
+          stored.appliedAt = now;
+          fs.writeFileSync(absPath, JSON.stringify(stored, null, 2), "utf8");
+        }
+      }
+    } catch {}
+
+    return { success: true, receipt, reason: "applied" };
+  } catch (err) {
+    return { success: false, reason: "error", error: String(err.message) };
+  }
+}
+
+function _emitLifecycleAuditEvent(cwd, artifact, receipt, eventName) {
+  try {
+    const eventsPath = path.join(cwd, ".claude/cco/events/outcome-events.jsonl");
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    const safeEventName = eventName.replace(/\./g, "_");
+    const event = JSON.stringify({
+      event_id: `run_lc_${safeEventName}_${artifact.sourceRunFingerprint}`,
+      session_id: "avorelo-run-improvements",
+      timestamp: nowIso(),
+      category: "run_improvements",
+      event_name: safeEventName,
+      reason_code: "RUN_IMPROVEMENTS_LIFECYCLE",
+      confidence_score: 1.0,
+      platform: "avorelo",
+      metadata: {
+        schemaVersion: SCHEMA_VERSION,
+        lifecycleState: receipt.lifecycleState,
+        surface: receipt.surface,
+        sourceRunFingerprint: artifact.sourceRunFingerprint,
+        improvementCount: (artifact.topImprovements || []).length,
+        topCategories: [
+          ...new Set((artifact.topImprovements || []).map((i) => i.category)),
+        ].slice(0, 3),
+        redacted: true,
+      },
+    });
+    fs.appendFileSync(eventsPath, event + "\n", "utf8");
+  } catch {}
+}
+
+// Inject next-run context: generates the bounded next-run-context artifact,
+// marks consumed (defaults read) and applied (artifact written + receipt exists).
+// This is the real application path — `applied` requires this function to succeed.
+// Surface: "next_run_context" — never "cli" or generic display.
+function injectNextRunContext(cwd, options = {}) {
+  try {
+    const { loadRunImprovements, RUN_IMPROVEMENTS_REL, SCHEMA_VERSION: RI_SCHEMA } = require("./run-improvements");
+    const artifact = loadRunImprovements(cwd);
+    if (!artifact || artifact.status === "not_available" || artifact.status === "expired") {
+      return { success: false, reason: "no_valid_artifact", nextRunContextArtifact: null, receipt: null };
+    }
+
+    // Idempotency: same fingerprint already applied through next_run_context → return existing
+    const existing = loadLifecycleReceipt(cwd);
+    if (
+      existing &&
+      existing.sourceRunFingerprint === artifact.sourceRunFingerprint &&
+      existing.lifecycleState === "applied" &&
+      existing.surface === "next_run_context"
+    ) {
+      const { loadNextRunContext } = require("./next-run-context");
+      return {
+        success: true,
+        receipt: existing,
+        nextRunContextArtifact: loadNextRunContext(cwd),
+        reason: "already_applied",
+      };
+    }
+
+    // Step 1: generate the next-run context artifact (this "consumes" the defaults)
+    const { generateNextRunContextArtifact, emitNextRunContextEvent } = require("./next-run-context");
+    const { artifact: nrcArtifact, written } = generateNextRunContextArtifact(cwd, { force: options.force || false });
+
+    if (!nrcArtifact || nrcArtifact.status === "not_available" || nrcArtifact.status === "error") {
+      return {
+        success: false,
+        reason: "next_run_context_generation_failed",
+        nextRunContextArtifact: nrcArtifact,
+        receipt: null,
+      };
+    }
+
+    const now = nowIso();
+
+    // Step 2: consumed receipt — defaults were read and embedded into context artifact
+    const consumedReceipt = buildLifecycleReceipt(artifact, {
+      lifecycleState: "consumed",
+      surface: "next_run_context",
+      consumedAt: now,
+      appliedAt: null,
+    });
+    writeLifecycleReceipt(cwd, consumedReceipt);
+    _emitLifecycleAuditEvent(cwd, artifact, consumedReceipt, "run_improvements.consumed");
+
+    // Step 3: applied receipt — next-run-context artifact written and points to defaults
+    const appliedReceipt = buildLifecycleReceipt(artifact, {
+      lifecycleState: "applied",
+      surface: "next_run_context",
+      consumedAt: now,
+      appliedAt: now,
+      limitations: [
+        "Applied via next-run-context artifact injection.",
+        "Injected status requires session-start hook to read the artifact.",
+        ...(nrcArtifact.limitations || []).slice(0, 2),
+      ],
+    });
+    writeLifecycleReceipt(cwd, appliedReceipt);
+    _emitLifecycleAuditEvent(cwd, artifact, appliedReceipt, "run_improvements.applied");
+
+    // Step 4: update main run-improvements artifact to reflect applied state
+    try {
+      const absPath = path.join(cwd, RUN_IMPROVEMENTS_REL);
+      if (fs.existsSync(absPath)) {
+        const stored = JSON.parse(fs.readFileSync(absPath, "utf8"));
+        if (
+          stored.schemaVersion === RI_SCHEMA &&
+          stored.sourceRunFingerprint === artifact.sourceRunFingerprint
+        ) {
+          stored.status = "applied";
+          stored.applied = true;
+          stored.appliedAt = now;
+          fs.writeFileSync(absPath, JSON.stringify(stored, null, 2), "utf8");
+        }
+      }
+    } catch {}
+
+    // Step 5: mark next-run-context artifact as applied (now has lifecycle backing)
+    try {
+      const { updateNextRunContextStatus } = require("./next-run-context");
+      updateNextRunContextStatus(cwd, "applied");
+      emitNextRunContextEvent(cwd, { ...nrcArtifact, status: "applied" }, "next_run_context.applied");
+    } catch {}
+
+    return {
+      success: true,
+      receipt: appliedReceipt,
+      nextRunContextArtifact: { ...nrcArtifact, status: "applied" },
+      reason: written ? "injected" : "idempotent_existing",
+      defaultsCount: (nrcArtifact.appliedDefaults || []).length,
+      decisionsCount: nrcArtifact.activeDecisionCount || 0,
+      risksCount: nrcArtifact.activeRiskCount || 0,
+      surface: "next_run_context",
+      artifactPath: ".claude/cco/state/next-run-context.json",
+    };
+  } catch (err) {
+    return { success: false, reason: "error", error: String(err.message), nextRunContextArtifact: null, receipt: null };
+  }
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  LIFECYCLE_STATES,
+  RECEIPT_REL,
+  loadLifecycleReceipt,
+  writeLifecycleReceipt,
+  buildLifecycleReceipt,
+  consumeRunImprovements,
+  applyRunImprovements,
+  injectNextRunContext,
+  checkLifecycleStale,
+};