avorelo 0.1.0 → 0.2.0

package/scripts/lib/anti-gaming.js

@@ -1,169 +0,0 @@
-"use strict";
-
-/**
- * Anti-Gaming Rules for the Effectiveness Proof System.
- *
- * The system must not appear effective by becoming worse.
- * These validation functions check proof records and scorecard data
- * for patterns that suggest gaming or misleading metrics.
- *
- * Each returns { valid: boolean, warning?: string }.
- */
-
-/**
- * Rule 1: Efficiency must never outrank truth or outcome quality.
- * Flag if context reduction is high but completion quality is low.
- */
-function validateEfficiencyWithQuality(proof) {
-  const largeOutputsManaged = Number(proof?.efficiency?.large_output_bytes_managed || 0);
-  const completionQuality = String(proof?.outcome?.completion_quality_state || "unknown");
-  const usefulResult = String(proof?.outcome?.useful_result_state || "unknown");
-
-  if (largeOutputsManaged > 100000 && (completionQuality === "low" || usefulResult === "not_useful")) {
-    return {
-      valid: false,
-      warning: "Many large outputs were managed out-of-band but completion quality is low. Aggressive output handling may have harmed results.",
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Rule 2: Tool skipping is not good if it harms the result.
- * Flag if many tools were skipped but dead-end rate is high.
- */
-function validateToolSkipSafety(proof) {
-  const toolsSkipped = Number(proof?.efficiency?.tools_skipped || 0);
-  const deadEndCount = Number(proof?.efficiency?.dead_end_count || 0);
-
-  if (toolsSkipped > 3 && deadEndCount > 0) {
-    return {
-      valid: false,
-      warning: "Tools were skipped but run ended in a dead end. Skipping may have been premature.",
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Rule 3: Approval avoidance is not good if escalation should have happened.
- * Flag if approvals were avoided but risky actions were also high.
- */
-function validateApprovalAvoidance(proof) {
-  const avoided = Number(proof?.control?.approval_requests_avoided || 0);
-  const riskyAttempts = Number(proof?.control?.risky_action_attempts || 0);
-  const riskyBlocked = Number(proof?.control?.risky_actions_blocked || 0);
-
-  if (avoided > 2 && riskyAttempts > 3 && riskyBlocked < riskyAttempts / 2) {
-    return {
-      valid: false,
-      warning: "Many approvals avoided while risky actions were frequent. Some escalations may have been skipped incorrectly.",
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Rule 4: Honest fallback is not good if overused to avoid work.
- * Flag if honest fallback rate exceeds 30%.
- */
-function validateHonestFallback(proofMetrics) {
-  const rate = Number(proofMetrics?.honest_fallback_rate?.value || 0);
-
-  if (rate > 30) {
-    return {
-      valid: false,
-      warning: `Honest fallback rate is ${rate}%. Above 30% suggests the system may be stopping too early rather than completing work.`,
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Rule 5: Scorecards must always pair efficiency with trust and outcome.
- * Flag if a scorecard shows efficiency without corresponding trust/outcome data.
- */
-function validateScorecardBalance(scorecard) {
-  const hasEfficiency = scorecard?.efficiency && Object.values(scorecard.efficiency).some((v) => v?.value > 0);
-  const hasOutcome = scorecard?.outcomes && Object.values(scorecard.outcomes).some((v) => v?.value > 0);
-  const hasTrust = scorecard?.trust && Object.values(scorecard.trust).some((v) => v?.value > 0);
-
-  if (hasEfficiency && !hasOutcome && !hasTrust) {
-    return {
-      valid: false,
-      warning: "Scorecard shows efficiency data without outcome or trust context. This is misleading.",
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Rule 6: No metric should create pressure to hide uncertainty.
- * Flag if evidence coverage is claimed as 100% with very few sessions.
- */
-function validateEvidencePlausibility(proofMetrics) {
-  const coverage = Number(proofMetrics?.evidence_coverage?.value || 0);
-  const sessions = Number(proofMetrics?.evidence_coverage?.denominator || 0);
-
-  if (coverage === 100 && sessions < 3) {
-    return {
-      valid: false,
-      warning: "100% evidence coverage with fewer than 3 sessions is not statistically meaningful.",
-    };
-  }
-  return { valid: true };
-}
-
-/**
- * Run all anti-gaming validations on a proof record.
- * Returns { valid: boolean, warnings: string[] }.
- */
-function validateProofRecord(proof) {
-  const checks = [
-    validateEfficiencyWithQuality(proof),
-    validateToolSkipSafety(proof),
-    validateApprovalAvoidance(proof),
-  ];
-
-  const warnings = checks.filter((c) => !c.valid).map((c) => c.warning);
-  return { valid: warnings.length === 0, warnings };
-}
-
-/**
- * Run all anti-gaming validations on computed proof metrics.
- * Returns { valid: boolean, warnings: string[] }.
- */
-function validateProofMetrics(proofMetrics) {
-  const checks = [
-    validateHonestFallback(proofMetrics),
-    validateEvidencePlausibility(proofMetrics),
-  ];
-
-  const warnings = checks.filter((c) => !c.valid).map((c) => c.warning);
-  return { valid: warnings.length === 0, warnings };
-}
-
-/**
- * Run all anti-gaming validations on a scorecard.
- * Returns { valid: boolean, warnings: string[] }.
- */
-function validateScorecard(scorecard) {
-  const checks = [
-    validateScorecardBalance(scorecard),
-  ];
-
-  const warnings = checks.filter((c) => !c.valid).map((c) => c.warning);
-  return { valid: warnings.length === 0, warnings };
-}
-
-module.exports = {
-  validateEfficiencyWithQuality,
-  validateToolSkipSafety,
-  validateApprovalAvoidance,
-  validateHonestFallback,
-  validateScorecardBalance,
-  validateEvidencePlausibility,
-  validateProofRecord,
-  validateProofMetrics,
-  validateScorecard,
-};

package/scripts/lib/artifact-health.js

@@ -1,431 +0,0 @@
-"use strict";
-
-// ── Artifact Health ───────────────────────────────────────────────────────────
-//
-// Contracts: avorelo.artifactHealth.v1, avorelo.artifactCleanup.v1
-//
-// Scans .claude/cco artifacts for validity, staleness, and size issues.
-// Plans and applies safe cleanup. Never deletes latest-*.json or outside cco.
-
-const fs = require("fs");
-const path = require("path");
-const { nowIso } = require("./fsx");
-
-const HEALTH_CONTRACT = "avorelo.artifactHealth.v1";
-const CLEANUP_CONTRACT = "avorelo.artifactCleanup.v1";
-const SCHEMA_VERSION = 1;
-
-const CCO_DIR_REL = ".claude/cco";
-const HEALTH_DIR_REL = ".claude/cco/orchestration/artifact-health";
-const LATEST_HEALTH_REL = `${HEALTH_DIR_REL}/latest-health.json`;
-const LATEST_CLEANUP_REL = `${HEALTH_DIR_REL}/latest-cleanup.json`;
-
-const MAX_FILE_BYTES = 512 * 1024; // 512KB
-const STALE_DAYS = 30;
-const MAX_JSONL_LINES = 5000;
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function bestEffortWrite(absPath, obj) {
-  try {
-    fs.mkdirSync(path.dirname(absPath), { recursive: true });
-    fs.writeFileSync(absPath, JSON.stringify(obj, null, 2), "utf8");
-  } catch {}
-}
-
-function isLatestFile(filename) {
-  return /^latest-/.test(filename) || filename === "latest-support-bundle.json" || filename === "latest-ledger.json";
-}
-
-function walkJsonFiles(dirAbs, results, ccoRootAbs) {
-  try {
-    if (!fs.existsSync(dirAbs)) return;
-    const entries = fs.readdirSync(dirAbs, { withFileTypes: true });
-    for (const entry of entries) {
-      const absPath = path.join(dirAbs, entry.name);
-      if (entry.isDirectory()) {
-        walkJsonFiles(absPath, results, ccoRootAbs);
-      } else if (entry.isFile()) {
-        const relToCco = path.relative(ccoRootAbs, absPath).replace(/\\/g, "/");
-        results.push({ absPath, relToCco, filename: entry.name });
-      }
-    }
-  } catch {}
-}
-
-function checkJsonFile(absPath) {
-  const issues = [];
-  try {
-    const stat = fs.statSync(absPath);
-    const raw = fs.readFileSync(absPath, "utf8").replace(/^/, "");
-
-    // Parse check
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      issues.push({ issueType: "invalid_json", severity: "error", message: "File is not valid JSON." });
-      return { parsed: null, issues };
-    }
-
-    // Contract field
-    if (!parsed.contract) {
-      issues.push({ issueType: "missing_contract", severity: "warn", message: "File missing 'contract' field." });
-    }
-
-    // SchemaVersion field
-    if (parsed.schemaVersion == null) {
-      issues.push({ issueType: "missing_schema_version", severity: "warn", message: "File missing 'schemaVersion' field." });
-    }
-
-    // Oversized
-    if (stat.size > MAX_FILE_BYTES) {
-      issues.push({ issueType: "oversized", severity: "warn", message: `File is ${stat.size} bytes (limit: ${MAX_FILE_BYTES}).` });
-    }
-
-    // Stale
-    const ageMs = Date.now() - stat.mtimeMs;
-    const ageDays = ageMs / (1000 * 60 * 60 * 24);
-    if (ageDays > STALE_DAYS) {
-      issues.push({ issueType: "stale", severity: "info", message: `File is ${Math.round(ageDays)} days old (threshold: ${STALE_DAYS}).` });
-    }
-
-    return { parsed, issues, stat };
-  } catch (e) {
-    issues.push({ issueType: "invalid_json", severity: "error", message: `Could not read file: ${e.message}` });
-    return { parsed: null, issues };
-  }
-}
-
-function checkJsonlFile(absPath, relToCco) {
-  const issues = [];
-  try {
-    const raw = fs.readFileSync(absPath, "utf8");
-    const lines = raw.split(/\r?\n/).filter((l) => l.trim());
-    let badLines = 0;
-    for (const line of lines) {
-      try { JSON.parse(line); } catch { badLines++; }
-    }
-    if (badLines > 0) {
-      issues.push({ issueType: "corrupt_jsonl", severity: "warn", message: `${badLines} unparseable line(s) in JSONL file.` });
-    }
-    if (lines.length > MAX_JSONL_LINES) {
-      issues.push({ issueType: "jsonl_too_large", severity: "warn", message: `JSONL has ${lines.length} lines (limit: ${MAX_JSONL_LINES}).` });
-    }
-  } catch (e) {
-    issues.push({ issueType: "corrupt_jsonl", severity: "error", message: `Could not read JSONL: ${e.message}` });
-  }
-  return issues;
-}
-
-// ── classifyArtifactIssue ─────────────────────────────────────────────────────
-
-function classifyArtifactIssue(issue, options = {}) {
-  return {
-    ...issue,
-    severity: issue.severity || "warn",
-    suggestedAction: suggestAction(issue.issueType),
-  };
-}
-
-function suggestAction(issueType) {
-  switch (issueType) {
-    case "invalid_json": return "Delete and regenerate this artifact.";
-    case "missing_contract": return "Update the module that writes this artifact to include a contract field.";
-    case "missing_schema_version": return "Update the module that writes this artifact to include a schemaVersion field.";
-    case "oversized": return "Review the artifact for unnecessary data and trim it.";
-    case "stale": return "Re-run the command that generates this artifact to refresh it.";
-    case "corrupt_jsonl": return "Truncate or delete the corrupt JSONL file and re-run the generating command.";
-    case "jsonl_too_large": return "Run `avorelo artifacts cleanup` to truncate or archive old JSONL lines.";
-    case "redaction_failure": return "Fix the generating module to ensure redacted:true is set.";
-    default: return "Review and regenerate this artifact.";
-  }
-}
-
-// ── scanArtifactHealth ────────────────────────────────────────────────────────
-
-function scanArtifactHealth(cwd, options = {}) {
-  const ccoRootAbs = path.join(cwd, CCO_DIR_REL);
-  const allFiles = [];
-  walkJsonFiles(ccoRootAbs, allFiles, ccoRootAbs);
-
-  const allIssues = [];
-  let healthyCount = 0;
-  let warnCount = 0;
-  let errorCount = 0;
-
-  for (const { absPath, relToCco, filename } of allFiles) {
-    const isJsonl = filename.endsWith(".jsonl");
-    if (isJsonl) {
-      const jsonlIssues = checkJsonlFile(absPath, relToCco);
-      for (const issue of jsonlIssues) {
-        const classified = classifyArtifactIssue({ ...issue, artifactPath: relToCco });
-        allIssues.push(classified);
-        if (issue.severity === "error") errorCount++;
-        else if (issue.severity === "warn") warnCount++;
-      }
-      if (jsonlIssues.length === 0) healthyCount++;
-    } else if (filename.endsWith(".json")) {
-      const { issues } = checkJsonFile(absPath);
-      const fileIssues = issues.map((issue) => classifyArtifactIssue({ ...issue, artifactPath: relToCco }));
-      if (fileIssues.length === 0) {
-        healthyCount++;
-      } else {
-        for (const issue of fileIssues) {
-          allIssues.push(issue);
-          if (issue.severity === "error") errorCount++;
-          else if (issue.severity === "warn") warnCount++;
-          else if (issue.severity === "info") {
-            // info issues don't degrade healthyCount
-          }
-        }
-        // If only info/stale, still count as healthy for summary
-        const hasRealIssue = fileIssues.some((i) => i.severity === "error" || i.severity === "warn");
-        if (!hasRealIssue) healthyCount++;
-      }
-    }
-  }
-
-  const artifactsScanned = allFiles.length;
-
-  let status;
-  if (errorCount > 0) status = "unhealthy";
-  else if (warnCount > 0) status = "warn";
-  else status = "healthy";
-
-  const nextAction = allIssues.length === 0
-    ? "All artifacts are healthy."
-    : `${allIssues.length} issue(s) found. Run \`avorelo artifacts cleanup --dry-run\` to review cleanup options.`;
-
-  return {
-    contract: HEALTH_CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    status,
-    scanRoot: CCO_DIR_REL,
-    artifactsScanned,
-    issues: allIssues,
-    summary: { healthy: healthyCount, warn: warnCount, error: errorCount },
-    nextAction,
-    createdAt: nowIso(),
-    redacted: true,
-  };
-}
-
-// ── buildArtifactCleanupPlan ──────────────────────────────────────────────────
-
-function buildArtifactCleanupPlan(cwd, health, options = {}) {
-  const dryRun = options.yes !== true;
-  const ccoRootAbs = path.join(cwd, CCO_DIR_REL);
-  const actions = [];
-
-  // Only plan cleanup for issues in .claude/cco
-  for (const issue of (health.issues || [])) {
-    const absPath = path.join(ccoRootAbs, issue.artifactPath);
-
-    // Safety: never plan to delete outside .claude/cco
-    const relResolved = path.relative(ccoRootAbs, absPath);
-    if (relResolved.startsWith("..")) continue;
-
-    // Never plan to delete latest-* files
-    const filename = path.basename(absPath);
-    if (isLatestFile(filename)) continue;
-
-    if (issue.issueType === "stale") {
-      actions.push({
-        artifactPath: issue.artifactPath,
-        absPath,
-        action: "delete_stale",
-        reason: issue.message,
-        severity: issue.severity,
-        protected: false,
-      });
-    } else if (issue.issueType === "jsonl_too_large") {
-      actions.push({
-        artifactPath: issue.artifactPath,
-        absPath,
-        action: "truncate_jsonl",
-        reason: issue.message,
-        severity: issue.severity,
-        protected: false,
-      });
-    }
-    // invalid_json, corrupt, oversized, etc. — do not auto-delete; surface for review
-  }
-
-  return {
-    contract: CLEANUP_CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    dryRun,
-    actions,
-    summary: {
-      toDelete: actions.filter((a) => a.action === "delete_stale").length,
-      toTruncate: actions.filter((a) => a.action === "truncate_jsonl").length,
-    },
-    note: dryRun
-      ? "Dry-run mode. No files will be modified. Pass --yes to apply."
-      : "Real cleanup mode. Files will be modified.",
-    createdAt: nowIso(),
-    redacted: true,
-  };
-}
-
-// ── applyArtifactCleanup ──────────────────────────────────────────────────────
-
-function applyArtifactCleanup(cwd, plan, options = {}) {
-  // Default: dry-run only. Requires options.yes === true for real execution.
-  const realRun = options.yes === true && options.dryRun !== true;
-  const ccoRootAbs = path.join(cwd, CCO_DIR_REL);
-  const applied = [];
-  const skipped = [];
-  const errors = [];
-
-  for (const action of (plan.actions || [])) {
-    const absPath = action.absPath || path.join(ccoRootAbs, action.artifactPath);
-
-    // Safety: never delete outside .claude/cco
-    const relResolved = path.relative(ccoRootAbs, absPath);
-    if (relResolved.startsWith("..")) {
-      skipped.push({ artifactPath: action.artifactPath, reason: "outside .claude/cco — skipped for safety" });
-      continue;
-    }
-
-    // Never delete latest-* files
-    const filename = path.basename(absPath);
-    if (isLatestFile(filename)) {
-      skipped.push({ artifactPath: action.artifactPath, reason: "protected latest-* file" });
-      continue;
-    }
-
-    if (!realRun) {
-      skipped.push({ artifactPath: action.artifactPath, reason: "dry-run mode" });
-      continue;
-    }
-
-    try {
-      if (action.action === "delete_stale") {
-        fs.unlinkSync(absPath);
-        applied.push({ artifactPath: action.artifactPath, action: "deleted" });
-      } else if (action.action === "truncate_jsonl") {
-        // Keep last 1000 lines
-        const raw = fs.readFileSync(absPath, "utf8");
-        const lines = raw.split(/\r?\n/).filter((l) => l.trim());
-        const kept = lines.slice(-1000);
-        fs.writeFileSync(absPath, kept.join("\n") + "\n", "utf8");
-        applied.push({ artifactPath: action.artifactPath, action: "truncated", keptLines: kept.length });
-      }
-    } catch (e) {
-      errors.push({ artifactPath: action.artifactPath, error: e.message });
-    }
-  }
-
-  return {
-    contract: CLEANUP_CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    dryRun: !realRun,
-    applied,
-    skipped,
-    errors,
-    createdAt: nowIso(),
-    redacted: true,
-  };
-}
-
-// ── writeArtifactHealthReceipt ────────────────────────────────────────────────
-
-function writeArtifactHealthReceipt(cwd, receipt) {
-  bestEffortWrite(path.join(cwd, LATEST_HEALTH_REL), receipt);
-}
-
-// ── writeArtifactCleanupReceipt ───────────────────────────────────────────────
-
-function writeArtifactCleanupReceipt(cwd, receipt) {
-  bestEffortWrite(path.join(cwd, LATEST_CLEANUP_REL), receipt);
-}
-
-// ── formatArtifactHealthText ──────────────────────────────────────────────────
-
-function formatArtifactHealthText(health, options = {}) {
-  if (!health) return "No artifact health data available.";
-  const lines = [];
-  lines.push(`Artifact Health: ${health.status?.toUpperCase() || "UNKNOWN"}`);
-  lines.push(`Scanned ${health.artifactsScanned ?? 0} artifact(s) in ${health.scanRoot || ".claude/cco"}`);
-  lines.push(`Healthy: ${health.summary?.healthy ?? 0}  Warn: ${health.summary?.warn ?? 0}  Error: ${health.summary?.error ?? 0}`);
-
-  const errors = (health.issues || []).filter((i) => i.severity === "error");
-  const warns = (health.issues || []).filter((i) => i.severity === "warn");
-  const infos = (health.issues || []).filter((i) => i.severity === "info");
-
-  if (errors.length > 0) {
-    lines.push("");
-    lines.push("Errors:");
-    errors.forEach((i) => lines.push(`  !! [${i.issueType}] ${i.artifactPath}: ${i.message}`));
-  }
-  if (warns.length > 0) {
-    lines.push("");
-    lines.push("Warnings:");
-    warns.forEach((i) => lines.push(`  -- [${i.issueType}] ${i.artifactPath}: ${i.message}`));
-  }
-  if (options.debug && infos.length > 0) {
-    lines.push("");
-    lines.push("Info:");
-    infos.forEach((i) => lines.push(`     [${i.issueType}] ${i.artifactPath}: ${i.message}`));
-  }
-
-  lines.push("");
-  lines.push(`Next step: ${health.nextAction || "All clear."}`);
-  return lines.join("\n");
-}
-
-// ── formatArtifactCleanupText ─────────────────────────────────────────────────
-
-function formatArtifactCleanupText(cleanup, options = {}) {
-  if (!cleanup) return "No artifact cleanup data available.";
-  const lines = [];
-  const label = cleanup.dryRun ? "Artifact Cleanup (DRY-RUN)" : "Artifact Cleanup";
-  lines.push(label);
-  lines.push(`To delete: ${cleanup.summary?.toDelete ?? 0}  To truncate: ${cleanup.summary?.toTruncate ?? 0}`);
-
-  if (cleanup.actions && cleanup.actions.length > 0) {
-    lines.push("");
-    lines.push("Planned actions:");
-    cleanup.actions.forEach((a) => lines.push(`  ${a.action}: ${a.artifactPath} (${a.reason})`));
-  }
-
-  if (cleanup.applied && cleanup.applied.length > 0) {
-    lines.push("");
-    lines.push("Applied:");
-    cleanup.applied.forEach((a) => lines.push(`  OK ${a.action}: ${a.artifactPath}`));
-  }
-
-  if (cleanup.skipped && cleanup.skipped.length > 0 && options.debug) {
-    lines.push("");
-    lines.push("Skipped:");
-    cleanup.skipped.forEach((a) => lines.push(`     skipped: ${a.artifactPath} (${a.reason})`));
-  }
-
-  if (cleanup.errors && cleanup.errors.length > 0) {
-    lines.push("");
-    lines.push("Errors:");
-    cleanup.errors.forEach((a) => lines.push(`  !! ${a.artifactPath}: ${a.error}`));
-  }
-
-  lines.push("");
-  lines.push(cleanup.note || (cleanup.dryRun ? "Dry-run mode. Pass --yes to apply." : "Cleanup complete."));
-  return lines.join("\n");
-}
-
-module.exports = {
-  HEALTH_CONTRACT,
-  CLEANUP_CONTRACT,
-  SCHEMA_VERSION,
-  LATEST_HEALTH_REL,
-  LATEST_CLEANUP_REL,
-  scanArtifactHealth,
-  classifyArtifactIssue,
-  buildArtifactCleanupPlan,
-  applyArtifactCleanup,
-  writeArtifactHealthReceipt,
-  writeArtifactCleanupReceipt,
-  formatArtifactHealthText,
-  formatArtifactCleanupText,
-};