avorelo 0.1.0

package/scripts/lib/micro-proof.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * Inline Micro-Proof System (Surface 1).
+ *
+ * Shows small, calm, contextual proof moments inside the workflow
+ * only when a material value event actually happened.
+ *
+ * Rules:
+ * - Must not be modal
+ * - Must not spam the user
+ * - Must deduplicate repeated proof types per session
+ * - Must show at most top 1-2 meaningful proofs at a moment
+ * - Must map directly to real telemetry/proof data
+ * - Must use calm factual copy
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { REASON_CODE_PROOF_MAP } = require("./proof-events");
+
+const MAX_PROOFS_PER_HOOK = 2;
+const MAX_PROOFS_PER_TYPE_PER_SESSION = 3;
+
+/**
+ * Load the micro-proof dedup state for a session.
+ */
+function loadMicroProofState(cwd, sessionId) {
+  const p = path.join(cwd, ".claude", "cco", "state", `micro-proof-${sessionId}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return { shown: {} };
+  }
+}
+
+/**
+ * Save the micro-proof dedup state for a session.
+ */
+function saveMicroProofState(cwd, sessionId, state) {
+  const p = path.join(cwd, ".claude", "cco", "state", `micro-proof-${sessionId}.json`);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
+}
+
+/**
+ * Select proof-worthy micro-proofs from a set of reason codes.
+ *
+ * Returns up to MAX_PROOFS_PER_HOOK calm one-liners, deduplicated
+ * against what was already shown in this session.
+ *
+ * @param {string[]} reasonCodes - reason codes from the current hook metric
+ * @param {string} cwd - workspace root
+ * @param {string} sessionId - session identifier
+ * @param {object} options - { proofEnabled?: boolean }
+ * @returns {{ proofs: string[], updated: boolean }}
+ */
+function selectMicroProofs(reasonCodes, cwd, sessionId, options = {}) {
+  if (options.proofEnabled === false) {
+    return { proofs: [], updated: false };
+  }
+
+  const state = loadMicroProofState(cwd, sessionId);
+  const candidates = [];
+
+  for (const code of reasonCodes || []) {
+    const mapping = REASON_CODE_PROOF_MAP[code];
+    if (!mapping || !mapping.proofWorthy || !mapping.calmCopy) continue;
+
+    // Dedup: skip if this proof type has been shown too many times
+    const shown = state.shown[code] || 0;
+    if (shown >= MAX_PROOFS_PER_TYPE_PER_SESSION) continue;
+
+    candidates.push({
+      code,
+      copy: mapping.calmCopy,
+      dimension: mapping.dimension,
+      family: mapping.family,
+    });
+  }
+
+  if (candidates.length === 0) {
+    return { proofs: [], updated: false };
+  }
+
+  // Prioritize by dimension diversity: show one from each dimension if possible
+  const selected = [];
+  const seenDimensions = new Set();
+
+  for (const c of candidates) {
+    if (selected.length >= MAX_PROOFS_PER_HOOK) break;
+    if (!seenDimensions.has(c.dimension)) {
+      selected.push(c);
+      seenDimensions.add(c.dimension);
+    }
+  }
+
+  // Fill remaining slots if we haven't hit the cap
+  for (const c of candidates) {
+    if (selected.length >= MAX_PROOFS_PER_HOOK) break;
+    if (!selected.includes(c)) {
+      selected.push(c);
+    }
+  }
+
+  // Update dedup state
+  for (const s of selected) {
+    state.shown[s.code] = (state.shown[s.code] || 0) + 1;
+  }
+  saveMicroProofState(cwd, sessionId, state);
+
+  return {
+    proofs: selected.map((s) => s.copy),
+    updated: true,
+  };
+}
+
+/**
+ * Format micro-proofs as additional context for hook output.
+ * Returns a single string to be injected via outAdditional, or null if no proofs.
+ */
+function formatMicroProofContext(proofs) {
+  if (!proofs || proofs.length === 0) return null;
+  return proofs.join(" ");
+}
+
+module.exports = {
+  selectMicroProofs,
+  formatMicroProofContext,
+  loadMicroProofState,
+  MAX_PROOFS_PER_HOOK,
+  MAX_PROOFS_PER_TYPE_PER_SESSION,
+};

package/scripts/lib/next-run-context.js

@@ -0,0 +1,436 @@
+"use strict";
+
+// Next-Run Context — auto-injection of evidence-backed learning into the next AI coding run.
+// Builds a compact, bounded artifact from prepared run improvements and learning summary.
+// No cloud calls, no LLM, no daemon. Deterministic, local-first, honest.
+//
+// Artifact path: .claude/cco/state/next-run-context.json
+// Schema:        avorelo.nextRunContext.v1
+//
+// Lifecycle:
+//   not_available      — run improvements not prepared
+//   prepared           — artifact built, waiting for session to consume
+//   injected           — session-start hook read and embedded it
+//   applied            — artifact written and pointed to by lifecycle receipt
+//   expired            — TTL exceeded
+//   stale              — source fingerprint no longer matches run improvements
+//   insufficient_evidence — no actionable defaults to inject
+//   skipped            — injection explicitly skipped
+//   error              — unexpected error
+
+const fs = require("fs");
+const path = require("path");
+
+const NEXT_RUN_CONTEXT_REL = ".claude/cco/state/next-run-context.json";
+const SCHEMA_VERSION = "avorelo.nextRunContext.v1";
+
+// 4-hour TTL: this is a "current-handoff" artifact, shorter than run-improvements (24h)
+const TTL_MS = 4 * 60 * 60 * 1000;
+
+const NEXT_RUN_STATUSES = [
+  "not_available",
+  "prepared",
+  "injected",
+  "applied",
+  "expired",
+  "stale",
+  "insufficient_evidence",
+  "skipped",
+  "error",
+];
+
+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();
+}
+
+function isStale(artifact, runImprovementsArtifact) {
+  if (!artifact || !runImprovementsArtifact) return false;
+  return artifact.sourceRunFingerprint !== runImprovementsArtifact.sourceRunFingerprint;
+}
+
+// ── Bounded payload selection ─────────────────────────────────────────────────
+
+// Top 1–3 defaults from run improvements (evidence-backed only)
+function selectBoundedDefaults(runImprovements) {
+  if (!runImprovements || !Array.isArray(runImprovements.nextRunDefaults)) return [];
+  return runImprovements.nextRunDefaults.slice(0, 3);
+}
+
+// Top 1–3 active decisions from learning summary
+function selectActiveDecisions(learningSummary) {
+  if (!learningSummary || !Array.isArray(learningSummary.topSignals)) return [];
+  return learningSummary.topSignals
+    .filter((s) => s.type === "decision")
+    .slice(0, 3)
+    .map((s) => ({
+      summary: s.summary,
+      confidence: s.confidence,
+      reasonCodes: s.reasonCodes || [],
+    }));
+}
+
+// Top 1–3 active risks from learning summary
+function selectActiveRisks(learningSummary) {
+  if (!learningSummary || !Array.isArray(learningSummary.topRisks)) return [];
+  return learningSummary.topRisks
+    .filter((r) => r.status === "active")
+    .slice(0, 3)
+    .map((r) => ({
+      title: r.title,
+      severity: r.severity,
+      mitigation: r.mitigation,
+      reasonCodes: r.reasonCodes || [],
+    }));
+}
+
+// Evidence-backed capability recommendation
+function selectCapabilityRecommendation(learningSummary) {
+  if (!learningSummary || !learningSummary.capabilityRecommendation) return null;
+  const rec = learningSummary.capabilityRecommendation;
+  if (!rec.id) return null;
+  return {
+    id: rec.id,
+    whenToUse: rec.whenToUse || null,
+    whenNotToUse: rec.whenNotToUse || null,
+    evidenceBacked: Boolean(rec.evidenceRefs && rec.evidenceRefs.length > 0),
+  };
+}
+
+// Build the human-readable context blocks for session injection
+function buildContextBlocks(appliedDefaults, activeDecisions, activeRisks, capabilityRec) {
+  const blocks = [];
+
+  if (appliedDefaults.length > 0) {
+    const lines = appliedDefaults.map((d) => `- ${d.text}`).join("\n");
+    blocks.push({
+      type: "next_run_defaults",
+      heading: "Next-run defaults (evidence-backed):",
+      text: lines,
+    });
+  }
+
+  if (activeDecisions.length > 0) {
+    const lines = activeDecisions.map((d) => `- ${d.summary}`).join("\n");
+    blocks.push({
+      type: "active_decisions",
+      heading: "Active decisions for this run:",
+      text: lines,
+    });
+  }
+
+  if (activeRisks.length > 0) {
+    const lines = activeRisks.map((r) => `- [${r.severity}] ${r.title}: ${r.mitigation}`).join("\n");
+    blocks.push({
+      type: "active_risks",
+      heading: "Active risks to carry forward:",
+      text: lines,
+    });
+  }
+
+  if (capabilityRec && capabilityRec.evidenceBacked) {
+    blocks.push({
+      type: "capability_recommendation",
+      heading: "Capability recommendation:",
+      text: `Use: ${capabilityRec.id}. ${capabilityRec.whenToUse || ""}`,
+    });
+  }
+
+  return blocks;
+}
+
+// Produce a compact human-readable text block suitable for session injection
+function buildCompactContextText(artifact) {
+  if (!artifact || !Array.isArray(artifact.contextBlocks) || artifact.contextBlocks.length === 0) {
+    return null;
+  }
+
+  const lines = ["Next-run context from Avorelo:"];
+  for (const block of artifact.contextBlocks) {
+    for (const line of block.text.split("\n")) {
+      lines.push(`  ${line}`);
+    }
+  }
+  if (artifact.limitations && artifact.limitations.length > 0) {
+    lines.push(`  Limitations: ${artifact.limitations[0]}`);
+  }
+  return lines.join("\n");
+}
+
+// ── Core builder ──────────────────────────────────────────────────────────────
+
+function buildNextRunContext(cwd) {
+  const generatedAt = nowIso();
+
+  // Load run improvements
+  let runImprovements = null;
+  try {
+    const { loadRunImprovements } = require("./run-improvements");
+    runImprovements = loadRunImprovements(cwd);
+  } catch {}
+
+  if (!runImprovements || runImprovements.status === "not_available" || runImprovements.status === "expired") {
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      generatedAt,
+      expiresAt: expiresAtFromNow(generatedAt),
+      sourceRunFingerprint: runImprovements?.sourceRunFingerprint || "none",
+      sourceArtifacts: {
+        runImprovementsRef: null,
+        learningSummaryRef: null,
+      },
+      appliedDefaults: [],
+      contextBlocks: [],
+      reasonCodes: ["NO_RUN_IMPROVEMENTS"],
+      redactionStatus: "redacted",
+      limitations: ["No prepared run improvements found. Run `avorelo run-improvements --generate` first."],
+      status: "not_available",
+    };
+  }
+
+  // Load learning summary (optional)
+  let learningSummary = null;
+  try {
+    const { loadLearningSummary } = require("./learning-memory");
+    learningSummary = loadLearningSummary(cwd);
+  } catch {}
+
+  const fingerprint = runImprovements.sourceRunFingerprint;
+  const appliedDefaults = selectBoundedDefaults(runImprovements);
+  const activeDecisions = selectActiveDecisions(learningSummary);
+  const activeRisks = selectActiveRisks(learningSummary);
+  const capabilityRec = selectCapabilityRecommendation(learningSummary);
+
+  if (appliedDefaults.length === 0 && activeDecisions.length === 0) {
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      generatedAt,
+      expiresAt: expiresAtFromNow(generatedAt),
+      sourceRunFingerprint: fingerprint,
+      sourceArtifacts: {
+        runImprovementsRef: ".claude/cco/state/run-improvements.json",
+        learningSummaryRef: learningSummary ? ".claude/cco/state/learning-summary.json" : null,
+      },
+      appliedDefaults: [],
+      contextBlocks: [],
+      reasonCodes: ["INSUFFICIENT_DEFAULTS"],
+      redactionStatus: "redacted",
+      limitations: [
+        "No actionable defaults or decisions found to inject.",
+        "Run `avorelo learning --generate` to refresh learning artifacts.",
+      ],
+      status: "insufficient_evidence",
+    };
+  }
+
+  const contextBlocks = buildContextBlocks(appliedDefaults, activeDecisions, activeRisks, capabilityRec);
+  const reasonCodes = [
+    ...new Set([
+      ...(runImprovements.reasonCodes || []),
+      ...(learningSummary ? ["LEARNING_SUMMARY_INCLUDED"] : []),
+    ]),
+  ];
+
+  const limitations = [
+    "Defaults are bounded to top 3 from evidence — full register is not included.",
+    "Decisions are active-only — stale/superseded items are excluded.",
+    "Run improvements lifecycle: applied only when this artifact is written and receipt exists.",
+    ...(runImprovements.limitations || []).slice(0, 2),
+  ];
+
+  // Never include raw transcripts, secrets, env dumps, or absolute local paths
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt,
+    expiresAt: expiresAtFromNow(generatedAt),
+    sourceRunFingerprint: fingerprint,
+    sourceArtifacts: {
+      runImprovementsRef: ".claude/cco/state/run-improvements.json",
+      learningSummaryRef: learningSummary ? ".claude/cco/state/learning-summary.json" : null,
+    },
+    appliedDefaults,
+    activeDecisionCount: activeDecisions.length,
+    activeRiskCount: activeRisks.length,
+    capabilityRecommendation: capabilityRec,
+    contextBlocks,
+    reasonCodes,
+    redactionStatus: "redacted",
+    limitations,
+    status: "prepared",
+  };
+}
+
+// ── Write / load ──────────────────────────────────────────────────────────────
+
+function generateNextRunContextArtifact(cwd, options = {}) {
+  const artifact = buildNextRunContext(cwd);
+
+  // Idempotency: same fingerprint + prepared/applied + not expired → skip rewrite
+  const existing = loadNextRunContext(cwd);
+  if (
+    existing &&
+    !isExpired(existing) &&
+    existing.sourceRunFingerprint === artifact.sourceRunFingerprint &&
+    (existing.status === "prepared" || existing.status === "applied" || existing.status === "injected") &&
+    !options.force
+  ) {
+    return { artifact: existing, written: false, reason: "same_fingerprint_not_expired" };
+  }
+
+  const absPath = path.join(cwd, NEXT_RUN_CONTEXT_REL);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(artifact, null, 2), "utf8");
+
+  _emitAuditEvent(cwd, artifact, "next_run_context.prepared");
+
+  return { artifact, written: true, reason: "generated" };
+}
+
+function loadNextRunContext(cwd) {
+  try {
+    const absPath = path.join(cwd, NEXT_RUN_CONTEXT_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;
+  }
+}
+
+// Update the artifact's status in-place (used by session-start injection)
+function updateNextRunContextStatus(cwd, newStatus, options = {}) {
+  try {
+    const absPath = path.join(cwd, NEXT_RUN_CONTEXT_REL);
+    if (!fs.existsSync(absPath)) return false;
+    const stored = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    if (stored.schemaVersion !== SCHEMA_VERSION) return false;
+    stored.status = newStatus;
+    if (options.injectedAt) stored.injectedAt = options.injectedAt;
+    fs.writeFileSync(absPath, JSON.stringify(stored, null, 2), "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Audit events ──────────────────────────────────────────────────────────────
+
+function _emitAuditEvent(cwd, artifact, 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: `nrc_${safeEventName}_${artifact.sourceRunFingerprint}`,
+      session_id: "avorelo-next-run-context",
+      timestamp: nowIso(),
+      category: "next_run_context",
+      event_name: safeEventName,
+      reason_code: "NEXT_RUN_CONTEXT_LIFECYCLE",
+      confidence_score: 1.0,
+      platform: "avorelo",
+      metadata: {
+        schemaVersion: artifact.schemaVersion,
+        status: artifact.status,
+        defaultsCount: (artifact.appliedDefaults || []).length,
+        decisionsCount: artifact.activeDecisionCount || 0,
+        risksCount: artifact.activeRiskCount || 0,
+        capabilityCount: artifact.capabilityRecommendation ? 1 : 0,
+        sourceRunFingerprint: artifact.sourceRunFingerprint,
+        surface: artifact.injectedSurface || null,
+        redactionStatus: artifact.redactionStatus || "redacted",
+        reasonCodes: (artifact.reasonCodes || []).slice(0, 5),
+      },
+    });
+    fs.appendFileSync(eventsPath, event + "\n", "utf8");
+  } catch {}
+}
+
+function emitNextRunContextEvent(cwd, artifact, eventName) {
+  _emitAuditEvent(cwd, artifact, eventName);
+}
+
+// ── Status/dashboard surface ──────────────────────────────────────────────────
+
+function buildNextRunContextSurface(cwd) {
+  const artifact = loadNextRunContext(cwd);
+  if (!artifact || artifact.status === "not_available") {
+    return {
+      showInStatus: false,
+      statusLine: null,
+      artifact: null,
+    };
+  }
+
+  const statusText = {
+    prepared: "prepared",
+    injected: "injected",
+    applied: "applied",
+    expired: "expired",
+    stale: "stale",
+    insufficient_evidence: "no actionable context",
+    skipped: "skipped",
+    error: "error",
+  }[artifact.status] || artifact.status;
+
+  const defaultsCount = (artifact.appliedDefaults || []).length;
+  const expiresIn = artifact.expiresAt
+    ? Math.max(0, Math.round((new Date(artifact.expiresAt).getTime() - Date.now()) / 60000))
+    : null;
+
+  const expiryNote = expiresIn !== null && artifact.status !== "expired"
+    ? ` · expires in ${expiresIn}m`
+    : "";
+
+  const statusLine =
+    artifact.status === "expired"
+      ? "Next-run context: expired — run `avorelo run-improvements --apply` to refresh"
+      : artifact.status === "insufficient_evidence"
+        ? "Next-run context: no actionable context"
+        : `Next-run context: ${statusText} · ${defaultsCount} default(s)${expiryNote}`;
+
+  return {
+    showInStatus: true,
+    statusLine,
+    artifact,
+  };
+}
+
+function formatNextRunContextText(cwd) {
+  const artifact = loadNextRunContext(cwd);
+  if (!artifact) return null;
+  if (artifact.status === "not_available" || artifact.status === "expired") return null;
+  return buildCompactContextText(artifact);
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  NEXT_RUN_CONTEXT_REL,
+  NEXT_RUN_STATUSES,
+  TTL_MS,
+  buildNextRunContext,
+  generateNextRunContextArtifact,
+  loadNextRunContext,
+  updateNextRunContextStatus,
+  buildNextRunContextSurface,
+  buildCompactContextText,
+  formatNextRunContextText,
+  emitNextRunContextEvent,
+  isExpired,
+  isStale,
+  selectBoundedDefaults,
+  selectActiveDecisions,
+  selectActiveRisks,
+};