avorelo 0.1.0 → 0.2.0

package/scripts/lib/score.js

@@ -1,262 +0,0 @@
-"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

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