avorelo 0.1.0

package/scripts/lib/score.js

@@ -0,0 +1,262 @@
+"use strict";
+
+/**
+ * lib/score.js — Shared verification-gap score logic.
+ *
+ * Used by:
+ *   scripts/cco-score.js  (CLI)
+ *   scripts/cco-sessionend.js  (SessionEnd hook)
+ *
+ * Exposes pure functions only. No process.exit, no console output.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const METRICS_REL = ".claude/cco/metrics/metrics.jsonl";
+const RELEVANT_EVENTS = new Set(["file.change", "validation.start", "validation.result"]);
+
+// ── Metrics reader ───────────────────────────────────────────────────────────
+
+/**
+ * Read metrics.jsonl safely.
+ * @param {string} metricsPath Absolute path to metrics.jsonl
+ * @returns {{ events: object[], warnings: string[], missing: boolean }}
+ */
+function readMetrics(metricsPath) {
+  if (!fs.existsSync(metricsPath)) {
+    return { events: [], warnings: [], missing: true };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(metricsPath, "utf8");
+  } catch {
+    return { events: [], warnings: ["Could not read metrics.jsonl."], missing: false };
+  }
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  const events = [];
+  const warnings = [];
+  let corruptSeen = false;
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line);
+      if (obj && typeof obj === "object") events.push(obj);
+    } catch {
+      corruptSeen = true;
+    }
+  }
+  if (corruptSeen) {
+    warnings.push("Some lines in metrics.jsonl could not be parsed and were skipped.");
+  }
+  return { events, warnings, missing: false };
+}
+
+// ── Run ID selection ─────────────────────────────────────────────────────────
+
+/**
+ * Select the target runId.
+ * Preferred order: explicit arg > latest file.change event's runId > null.
+ *
+ * @param {object[]} events Already-filtered RELEVANT_EVENTS subset
+ * @param {string|null} explicitRunId
+ * @returns {string|null}
+ */
+function selectTargetRunId(events, explicitRunId) {
+  if (explicitRunId) return explicitRunId;
+  const fileChanges = events.filter((e) => e.event === "file.change");
+  if (fileChanges.length === 0) return null;
+  fileChanges.sort((a, b) => {
+    const ta = a.ts ? new Date(a.ts).getTime() : 0;
+    const tb = b.ts ? new Date(b.ts).getTime() : 0;
+    return tb - ta; // descending — latest first
+  });
+  const latest = fileChanges[0];
+  const id = latest.meta?.runId ?? latest.sessionId ?? null;
+  return id != null ? String(id) : null;
+}
+
+// ── Core analysis ────────────────────────────────────────────────────────────
+
+/**
+ * Analyze a single run. Always filters events to targetRunId.
+ *
+ * @param {string} targetRunId
+ * @param {object[]} events Already-filtered RELEVANT_EVENTS subset
+ * @returns {object|null} Score result, or null if targetRunId is falsy
+ */
+function analyzeRun(targetRunId, events) {
+  if (!targetRunId) return null;
+
+  // Strict filter — never mix runs
+  const filtered = events.filter(
+    (e) => String(e.meta?.runId ?? e.sessionId ?? "") === targetRunId
+  );
+
+  const fileChanges = filtered.filter((e) => e.event === "file.change");
+  const validationStarts = filtered.filter((e) => e.event === "validation.start");
+  const validationResults = filtered.filter((e) => e.event === "validation.result");
+
+  const sessionIds = [...new Set(filtered.map((e) => e.sessionId).filter(Boolean))];
+  const fileChangePaths = [
+    ...new Set(fileChanges.map((f) => String(f.meta?.filePath ?? f.meta?.path ?? "unknown"))),
+  ];
+
+  const hadFileChange = fileChanges.length > 0;
+  const hadValidationStart = validationStarts.length > 0;
+  const hadValidationResult = validationResults.length > 0;
+  const verificationGap = hadFileChange && !hadValidationResult;
+
+  let status, reason, nextAction;
+
+  if (!hadFileChange) {
+    status = "NO DATA";
+    reason = "No file changes recorded for this run.";
+    nextAction = "Make a code change and re-run wuz score.";
+  } else if (hadValidationResult) {
+    status = "PASS";
+    const outcome =
+      validationResults[0]?.meta?.verdict ??
+      validationResults[0]?.meta?.policyOutcome ??
+      "unknown";
+    reason = `Validation completed with outcome: ${outcome}.`;
+    nextAction = "No action needed — verification is closed.";
+  } else if (hadValidationStart) {
+    status = "INSUFFICIENT";
+    reason = "Validation started but no result recorded yet.";
+    nextAction = "Wait for validation to complete, then re-run wuz score.";
+  } else {
+    status = "GAP";
+    reason = "File changes were made but no validation was started or completed.";
+    nextAction =
+      "Run validation (e.g. npm test or your check command) before completing this task.";
+  }
+
+  return {
+    status,
+    runId: targetRunId,
+    sessionIds,
+    hadFileChange,
+    hadValidationStart,
+    hadValidationResult,
+    verificationGap,
+    fileChangeCount: fileChanges.length,
+    fileChangePaths,
+    validationStartCount: validationStarts.length,
+    validationResultCount: validationResults.length,
+    reason,
+    nextAction,
+  };
+}
+
+// ── No-data result ───────────────────────────────────────────────────────────
+
+/**
+ * Standardized NO DATA result shape.
+ * @param {string} reason
+ * @returns {object}
+ */
+function noDataResult(reason) {
+  return {
+    status: "NO DATA",
+    runId: null,
+    sessionIds: [],
+    hadFileChange: false,
+    hadValidationStart: false,
+    hadValidationResult: false,
+    verificationGap: false,
+    fileChangeCount: 0,
+    fileChangePaths: [],
+    validationStartCount: 0,
+    validationResultCount: 0,
+    reason,
+    nextAction: "Make a code change and run validation, then re-run wuz score.",
+  };
+}
+
+// ── Text formatter ───────────────────────────────────────────────────────────
+
+/**
+ * Compact human-readable score line.
+ * @param {object} result
+ * @returns {string}
+ */
+function formatScoreText(result) {
+  const lines = [`Wuz score: ${result.status}`];
+  if (result.runId) lines.push(`Run:       ${result.runId}`);
+  lines.push(`Reason:    ${result.reason}`);
+  lines.push(`Next:      ${result.nextAction}`);
+  return lines.join("\n");
+}
+
+// ── Compact single-line for hook output ──────────────────────────────────────
+
+/**
+ * One-liner for session-end hook stderr — avoids multi-line clutter.
+ * Returns null for NO DATA (stay quiet).
+ * @param {object} result
+ * @returns {string|null}
+ */
+function formatScoreOneLiner(result) {
+  switch (result.status) {
+    case "GAP":
+      return `Wuz score: GAP — file changes detected, no validation.result completed. Next: ${result.nextAction}`;
+    case "PASS":
+      return `Wuz score: PASS — validation evidence exists for this run.`;
+    case "INSUFFICIENT":
+      return `Wuz score: INSUFFICIENT — validation started but did not complete. Next: ${result.nextAction}`;
+    case "NO DATA":
+      return null; // stay quiet
+    default:
+      return null;
+  }
+}
+
+// ── Orchestration ────────────────────────────────────────────────────────────
+
+/**
+ * Full score pipeline: read metrics, select run, analyze.
+ *
+ * @param {string} metricsPath Absolute path to metrics.jsonl
+ * @param {string|null} explicitRunId
+ * @returns {{ result: object, warnings: string[] }}
+ */
+function runScore(metricsPath, explicitRunId) {
+  const { events, warnings, missing } = readMetrics(metricsPath);
+
+  if (missing) {
+    return {
+      result: noDataResult(
+        `Metrics file not found at ${path.basename(metricsPath)}. Has the CCO harness run yet?`
+      ),
+      warnings,
+    };
+  }
+
+  const relevantEvents = events.filter((e) => RELEVANT_EVENTS.has(e.event));
+  const targetRunId = selectTargetRunId(relevantEvents, explicitRunId);
+
+  if (!targetRunId) {
+    return {
+      result: noDataResult("No file.change events found in metrics. No run to score."),
+      warnings,
+    };
+  }
+
+  const result =
+    analyzeRun(targetRunId, relevantEvents) ||
+    noDataResult(`Could not analyze run: ${targetRunId}`);
+
+  return { result, warnings };
+}
+
+module.exports = {
+  METRICS_REL,
+  RELEVANT_EVENTS,
+  readMetrics,
+  selectTargetRunId,
+  analyzeRun,
+  noDataResult,
+  formatScoreText,
+  formatScoreOneLiner,
+  runScore,
+};

package/scripts/lib/seamless-enforcement.js

@@ -0,0 +1,329 @@
+"use strict";
+
+// ── Seamless Automation Enforcement ──────────────────────────────────────────
+//
+// Wires shouldInterruptForDecision() and shouldApplySilently() into actual
+// CLI command output and post-run value summary writes. This is not a new
+// orchestrator — it's an enforcement layer over existing foundations.
+//
+// Principles:
+// - Automatic mode: work silently when safe; show compact outcome at end
+// - Assisted/manual_debug: expose decision detail when appropriate
+// - Every block must include taskStillExecutable + safeNextAction
+// - Every run writes a value summary (best-effort, never blocks the command)
+// - No LLM calls, no network calls, fully deterministic
+
+const {
+  getSeamlessMode,
+  shouldInterruptForDecision,
+  shouldApplySilently,
+  buildOutcomePreservationCheck,
+  buildValueSummaryFromReceipts,
+  emitSeamlessEvent,
+} = require("./seamless-outcome");
+const { buildTaskContinuation } = require("./task-continuation");
+
+const CONTRACT = "avorelo.seamlessEnforcement.v1";
+const SCHEMA_VERSION = 1;
+
+// ── Decision visibility ───────────────────────────────────────────────────────
+
+// Returns whether full decision detail should be shown vs. compact outcome line.
+// Used by guard and route text output to enforce seamless mode behavior.
+function getDecisionVisibility(input = {}) {
+  const mode = getSeamlessMode({});
+  const interruptResult = shouldInterruptForDecision({
+    actionType: input.actionType,
+    riskLevel: input.riskLevel,
+    isDestructive: input.isDestructive,
+    isIrreversible: input.isIrreversible,
+    hasSecretsRisk: input.hasSecretsRisk,
+    requiresExplicitApproval: input.requiresExplicitApproval,
+  });
+
+  // Always show full detail when user action is required
+  if (interruptResult.interrupt) {
+    return {
+      showDetail: true,
+      interruptRequired: true,
+      interruptReason: interruptResult.reason,
+      mode,
+    };
+  }
+
+  // manual_debug always shows detail
+  if (mode === "manual_debug") {
+    return {
+      showDetail: true,
+      interruptRequired: false,
+      interruptReason: "manual_debug_exposes_all_decisions",
+      mode,
+    };
+  }
+
+  const silentResult = shouldApplySilently({
+    actionType: input.actionType,
+    riskLevel: input.riskLevel,
+    isDestructive: input.isDestructive,
+    isIrreversible: input.isIrreversible,
+    hasSecretsRisk: input.hasSecretsRisk,
+  });
+
+  if (silentResult.silent) {
+    return {
+      showDetail: false,
+      interruptRequired: false,
+      interruptReason: null,
+      mode,
+      compactSuffix: "Applied silently in automatic mode. Run with --debug for details.",
+    };
+  }
+
+  // Assisted or high-risk: show detail without requiring interrupt
+  return {
+    showDetail: true,
+    interruptRequired: false,
+    interruptReason: silentResult.reason,
+    mode,
+  };
+}
+
+// ── Compact outcome lines ─────────────────────────────────────────────────────
+
+// Returns a compact, customer-outcome-oriented summary line for automatic mode.
+function formatCompactRouteLine(route) {
+  const worker = route.chosenTool || "none";
+  const profile = route.chosenModelProfile || "unknown";
+  const risk = route.task?.risk || "unknown";
+  const premium = route.premiumUseInvolved ? "premium" : "local/free";
+  const state = route.state || "partial";
+  return [
+    `Routed: ${worker} / ${profile} (${premium} · risk: ${risk} · state: ${state}).`,
+    `Receipt written. Run \`avorelo proof --debug\` for routing details.`,
+  ].join(" ");
+}
+
+function formatCompactContextLine(pack) {
+  const tokens = pack.tokenEstimate?.estimatedTokens ?? 0;
+  const stage = pack.stageId || "implement";
+  const warning = pack.tokenEstimate?.warning || "within_budget";
+  const compacted = pack.reductionSummary?.compactionUsed ? " (compacted)" : "";
+  return `Context: ~${tokens} tokens / ${stage} stage / ${warning}${compacted}. Receipt written.`;
+}
+
+function formatCompactGuardLine(decision, riskLevel) {
+  if (decision === "allow") {
+    return `Guard: allow. Safe routine — applied silently. Risk: ${riskLevel || "low"}.`;
+  }
+  if (decision === "approval_required") {
+    return `Guard: approval required. Task can proceed with narrower scope — see saferAlternative.`;
+  }
+  return `Guard: ${decision}. Risk: ${riskLevel || "unknown"}. See saferAlternative for next step.`;
+}
+
+// ── Outcome-preserving guard block check ──────────────────────────────────────
+
+// Every guard decision must include taskStillExecutable and safeNextAction.
+// This enforces the "reduced access must still allow the task to finish,
+// or provide fallback/escalation" principle.
+// Handles block, approval_required, and warn decisions.
+function buildGuardBlockOutcome(decision, guardInput = {}) {
+  if (!["block", "approval_required", "warn"].includes(decision)) return null;
+
+  const riskLevel = guardInput.riskLevel || "unknown";
+  const isHighRisk = ["high", "critical"].includes(String(riskLevel).toLowerCase());
+
+  const continuation = buildTaskContinuation({
+    actionType: guardInput.actionType,
+    target: guardInput.target || guardInput.command || guardInput.url || guardInput.toolName || "",
+    task: guardInput.userIntent || guardInput.taskType || "",
+    riskLevel,
+    decision,
+    reasonCodes: guardInput.reasonCodes || [],
+  });
+
+  const taskStillExecutable = continuation.taskStillExecutable;
+  const fallbackAvailable = continuation.fallbackAvailable;
+  const escalationRecommended = continuation.escalationRecommended;
+  const derivedSafeNextAction = continuation.safeNextAction;
+
+  return buildOutcomePreservationCheck({
+    originalAction: guardInput.actionType,
+    reductionApplied: decision === "approval_required" || decision === "warn",
+    riskLevel,
+    actionType: guardInput.actionType,
+    target: guardInput.target,
+    taskDescription: guardInput.userIntent || guardInput.taskType || "",
+    taskStillExecutable,
+    qualityRiskIntroduced: continuation.qualityRiskIntroduced,
+    fallbackAvailable,
+    escalationRecommended,
+    safeNextAction: derivedSafeNextAction,
+    interruptRequired: decision === "block",
+    reasonCodes: guardInput.reasonCodes || [],
+    continuationType: continuation.continuationType,
+    suggestedScope: continuation.suggestedScope,
+    suggestedCommand: continuation.suggestedCommand,
+    verificationNextStep: continuation.verificationNextStep,
+  });
+}
+
+// ── Auto-write value summary ──────────────────────────────────────────────────
+
+// Called after any automated run to write a value summary and emit events.
+// Best-effort: never throws, never blocks the calling command.
+function writeSeamlessRunReceipt(cwd, opts = {}) {
+  try {
+    const mode = getSeamlessMode({});
+    const { summary, path: summaryPath } = buildValueSummaryFromReceipts(cwd, {
+      mode,
+      manualDecisionsAvoided: opts.manualDecisionsAvoided || 0,
+      safePathReductionsApplied: opts.safePathReductionsApplied || 0,
+      unsafeActionsBlocked: opts.unsafeActionsBlocked || 0,
+      secretsExposurePrevented: opts.secretsExposurePrevented || 0,
+      qualityPreserved: opts.qualityPreserved !== false,
+      qualityRiskIntroduced: Boolean(opts.qualityRiskIntroduced),
+      escalationRecommended: Boolean(opts.escalationRecommended),
+      strongWorkerReservedForCriticalStage: Boolean(opts.strongWorkerReservedForCriticalStage),
+    });
+
+    emitSeamlessEvent(cwd, "automatic_optimization_applied", {
+      triggerCommand: opts.command || "unknown",
+      mode,
+      manualDecisionsAvoided: opts.manualDecisionsAvoided || 0,
+      unsafeActionsBlocked: opts.unsafeActionsBlocked || 0,
+    });
+
+    if (opts.manualDecisionsAvoided > 0) {
+      emitSeamlessEvent(cwd, "manual_decision_avoided", {
+        triggerCommand: opts.command || "unknown",
+        count: opts.manualDecisionsAvoided,
+      });
+    }
+
+    if (opts.userInterruptAvoided) {
+      emitSeamlessEvent(cwd, "user_interrupt_avoided", {
+        triggerCommand: opts.command || "unknown",
+      });
+    }
+
+    if (opts.interruptionRequired) {
+      emitSeamlessEvent(cwd, "interruption_required", {
+        triggerCommand: opts.command || "unknown",
+        reason: opts.interruptReason || "unknown",
+      });
+    }
+
+    return { summary, summaryPath, mode };
+  } catch {
+    return null;
+  }
+}
+
+// ── Enforcement contract surface ──────────────────────────────────────────────
+
+function buildEnforcementSurface(cwd) {
+  const mode = getSeamlessMode({});
+  try {
+    const { readLatestValueSummary } = require("./seamless-outcome");
+    const summary = readLatestValueSummary(cwd);
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      mode,
+      enforced: true,
+      manualDecisionsAvoided: summary?.saved?.manualDecisionsAvoided || 0,
+      unsafeActionsBlocked: summary?.protected?.unsafeActionsBlocked || 0,
+      qualityPreserved: summary?.quality?.qualityPreserved !== false,
+      escalationRecommended: Boolean(summary?.quality?.escalationRecommended),
+    };
+  } catch {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      mode,
+      enforced: true,
+      manualDecisionsAvoided: 0,
+      unsafeActionsBlocked: 0,
+      qualityPreserved: true,
+      escalationRecommended: false,
+    };
+  }
+}
+
+// ── Task continuation event emission ─────────────────────────────────────────
+//
+// Emits product-learning events for task continuation. Called after the guard
+// payload is built — best-effort, never throws.
+
+function emitTaskContinuationEvents(cwd, opts = {}) {
+  try {
+    const { appendProductLearningEvent } = require("./product-learning-events");
+    const continuationType = opts.continuationType || "unknown";
+    const safeNextAction = opts.safeNextAction || "";
+
+    // Detect generic fallback text
+    const isGeneric =
+      safeNextAction.startsWith("Reduce scope around the highest-risk") ||
+      safeNextAction.startsWith("Keep the action narrowed to the smallest") ||
+      safeNextAction === "" ||
+      safeNextAction == null;
+
+    appendProductLearningEvent(cwd, {
+      eventName: "task_continuation_generated",
+      category: "task_continuation",
+      surface: "local",
+      status: "observed",
+      payload: {
+        continuationType,
+        decision: opts.decision || "unknown",
+        riskLevel: opts.riskLevel || "unknown",
+        actionType: opts.actionType || "unknown",
+        taskStillExecutable: opts.taskStillExecutable,
+        fallbackAvailable: Boolean(opts.fallbackAvailable),
+        escalationRecommended: Boolean(opts.escalationRecommended),
+      },
+    });
+
+    if (isGeneric) {
+      appendProductLearningEvent(cwd, {
+        eventName: "generic_safe_next_action_detected",
+        category: "task_continuation",
+        surface: "local",
+        status: "observed",
+        payload: {
+          continuationType,
+          decision: opts.decision || "unknown",
+          actionType: opts.actionType || "unknown",
+          riskLevel: opts.riskLevel || "unknown",
+        },
+      });
+    } else {
+      appendProductLearningEvent(cwd, {
+        eventName: "task_specific_safe_next_action_generated",
+        category: "task_continuation",
+        surface: "local",
+        status: "observed",
+        payload: {
+          continuationType,
+          decision: opts.decision || "unknown",
+          actionType: opts.actionType || "unknown",
+          riskLevel: opts.riskLevel || "unknown",
+        },
+      });
+    }
+  } catch {}
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  getDecisionVisibility,
+  buildGuardBlockOutcome,
+  writeSeamlessRunReceipt,
+  emitTaskContinuationEvents,
+  formatCompactRouteLine,
+  formatCompactContextLine,
+  formatCompactGuardLine,
+  buildEnforcementSurface,
+};