avorelo 0.1.0

package/scripts/lib/anti-gaming.js

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

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