avorelo 0.1.0 → 0.3.0

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

@@ -1,330 +0,0 @@
-"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,
-};