avorelo 0.1.0 → 0.2.0

package/scripts/lib/external-user-simulation.js

@@ -1,166 +0,0 @@
-"use strict";
-
-// ── External User Simulation ──────────────────────────────────────────────────
-// Contract: avorelo.externalUserSimulation.v1
-// Simulates an external user's first experience across 10 key scenarios.
-// Does NOT modify user config, apply hooks, patch MCP, or run destructive commands.
-
-const fs = require("fs");
-const path = require("path");
-const { nowIso } = require("./fsx");
-const { appendProductLearningEvent } = require("./product-learning-events");
-
-const CONTRACT = "avorelo.externalUserSimulation.v1";
-const SCHEMA_VERSION = 1;
-const SIM_DIR_REL = ".claude/cco/orchestration/full-readiness";
-const ARTIFACT_REL = SIM_DIR_REL + "/latest-external-user-simulation.json";
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch { return null; }
-}
-
-function buildExternalUserScenarios(cwd, options) {
-  options = options || {};
-  return [
-    { id: "scenario_1_see_install_prompt", title: "Fresh user sees install-ai prompt", description: "A new user runs `avorelo install-ai --prompt` and sees the one-prompt AI install experience.", expectedBehavior: "Compact prompt text appears. Approval boundaries are visible. No auto-apply.", safetyConstraints: ["no_config_modification", "no_auto_apply"] },
-    { id: "scenario_2_run_ai_install", title: "User runs AI install prompt in simulated order", description: "User follows the AI install prompt steps: install-ai, prelaunch-readiness, first-value-check.", expectedBehavior: "Each step returns a compact JSON result. Journey steps complete in order.", safetyConstraints: ["no_destructive_commands", "no_prod_deploy"] },
-    { id: "scenario_3_hooks_not_applied", title: "User has hooks not applied", description: "User runs `avorelo hooks doctor` and sees hooks are not yet applied.", expectedBehavior: "Doctor shows hooks_not_applied warning. safeNextAction points to `hooks apply --yes`.", safetyConstraints: ["no_auto_hook_apply", "requires_explicit_approval"] },
-    { id: "scenario_4_mcp_governance_warning", title: "User sees MCP governance warning", description: "User runs `avorelo mcp doctor` and sees MCP servers inventoried with risk scores.", expectedBehavior: "Inventory shows servers and risk levels. Policy is preview-only — no auto-patch.", safetyConstraints: ["no_mcp_config_patch", "preview_only"] },
-    { id: "scenario_5_token_cost_not_available", title: "User sees token/cost not_available", description: "User runs `avorelo token-cost` before completing any tasks.", expectedBehavior: "Status is not_available. Caveats explain estimates vs exact. No exact savings claimed.", safetyConstraints: ["no_exact_savings_claim", "caveats_required"] },
-    { id: "scenario_6_support_bundle", title: "User needs support bundle", description: "User runs `avorelo support-bundle --json` to get a redacted support bundle.", expectedBehavior: "Bundle is redacted. No raw prompts, code, secrets, or PII. Safe to share.", safetyConstraints: ["redacted", "no_raw_prompts", "no_raw_code", "no_secrets"] },
-    { id: "scenario_7_missing_proof_outcome", title: "User hits missing proof/outcome", description: "User runs `avorelo proof` before completing any task — no proof available.", expectedBehavior: "Compact message: no proof available. safeNextAction: run a task first.", safetyConstraints: ["no_false_proof_claim", "safeNextAction_required"] },
-    { id: "scenario_8_known_limitations", title: "User reads known limitations", description: "User runs `avorelo known-limitations --json` and reads the limitations register.", expectedBehavior: "Limitations are honest, categorized, and include mitigations. No hidden limitations.", safetyConstraints: ["honest_limitations", "no_hidden_limitations"] },
-    { id: "scenario_9_see_next_action", title: "User sees next action", description: "User runs `avorelo full-readiness --json` and sees a clear safeNextAction.", expectedBehavior: "safeNextAction is specific and actionable. No vague or generic next step.", safetyConstraints: ["specific_next_action", "actionable"] },
-    { id: "scenario_10_blocked_action_safe_next", title: "User gets blocked action with safeNextAction", description: "User attempts an action that is blocked. safeNextAction guides recovery.", expectedBehavior: "Blocked action shows safeNextAction. User is not left without guidance.", safetyConstraints: ["every_blocker_has_safeNextAction", "no_silent_failure"] },
-  ];
-}
-
-function evaluateExternalUserScenario(cwd, scenario, options) {
-  options = options || {};
-  function read(rel) { return safeReadJson(path.join(cwd, rel)); }
-  var status = "pass";
-  var finding = null;
-  var evidence = null;
-
-  switch (scenario.id) {
-    case "scenario_1_see_install_prompt": {
-      var ip = read(".claude/cco/orchestration/ai-install/latest-prompt.json");
-      if (!ip) { status = "warn"; finding = "AI install prompt not generated. Run: node bin/avorelo install-ai --json"; }
-      else if (!ip.requiresApprovalFor || ip.requiresApprovalFor.length === 0) { status = "warn"; finding = "Approval boundaries not explicitly listed in install prompt."; }
-      else { finding = "Install prompt present with approval boundaries."; evidence = { artifactPath: ".claude/cco/orchestration/ai-install/latest-prompt.json" }; }
-      break;
-    }
-    case "scenario_2_run_ai_install": {
-      var ip2 = read(".claude/cco/orchestration/ai-install/latest-prompt.json");
-      var pr = read(".claude/cco/orchestration/prelaunch-readiness/latest-activation-readiness.json");
-      var steps = [ip2, pr].filter(Boolean).length;
-      if (steps < 2) { status = "warn"; finding = "Only " + steps + "/2 journey steps have receipts."; }
-      else finding = "Core install journey steps have receipts.";
-      break;
-    }
-    case "scenario_3_hooks_not_applied": {
-      var hd = read(".claude/cco/orchestration/hook-doctor/latest-doctor.json");
-      if (!hd) { status = "warn"; finding = "Hooks doctor not run. Run: node bin/avorelo hooks doctor --json"; }
-      else {
-        var hasApprovalCheck = (hd.checks || []).some(function(c) { return c.id === "no_global_config_modified"; });
-        if (!hasApprovalCheck) { status = "warn"; finding = "Hooks doctor missing explicit approval boundary check."; }
-        else finding = "Hooks doctor present. Approval required before hooks apply.";
-      }
-      break;
-    }
-    case "scenario_4_mcp_governance_warning": {
-      var mp = read(".claude/cco/orchestration/mcp-tool-governance/latest-policy.json");
-      if (!mp) { status = "warn"; finding = "MCP governance not run. Run: node bin/avorelo mcp doctor --json"; }
-      else if (!mp.note || (Array.isArray(mp.note) ? !mp.note.join(" ").includes("preview") : !mp.note.includes("preview"))) { status = "warn"; finding = "MCP policy does not explicitly state preview-only mode."; }
-      else finding = "MCP governance present and preview-only note confirmed.";
-      break;
-    }
-    case "scenario_5_token_cost_not_available": {
-      var tc = read(".claude/cco/orchestration/prelaunch-intelligence/latest-token-cost-intelligence.json");
-      if (!tc) { status = "warn"; finding = "Token/cost intelligence not run. Run: node bin/avorelo token-cost --json"; }
-      else if (tc.noExactSavingsClaim !== true) { status = "blocked"; finding = "Token cost intelligence does not have noExactSavingsClaim=true."; }
-      else finding = "Token cost status: " + (tc.status || tc.evidenceLevel) + ". Caveats present.";
-      break;
-    }
-    case "scenario_6_support_bundle": {
-      var sb = read(".claude/cco/support/latest-support-bundle.json");
-      if (!sb) { status = "warn"; finding = "Support bundle not generated. Run: node bin/avorelo support-bundle --json"; }
-      else if (sb.redacted !== true) { status = "blocked"; finding = "Support bundle is not marked redacted — safety violation."; }
-      else finding = "Support bundle present and redacted.";
-      break;
-    }
-    case "scenario_7_missing_proof_outcome": {
-      var vs = read(".claude/cco/orchestration/seamless-outcome/latest-value-summary.json");
-      finding = vs ? "Proof/value summary present from prior task." : "No proof available (expected). CLI shows clear message: run a task first.";
-      break;
-    }
-    case "scenario_8_known_limitations": {
-      var kl = read(".claude/cco/orchestration/full-readiness/latest-known-limitations.json");
-      if (!kl) { status = "warn"; finding = "Known limitations register not yet built. Run: node bin/avorelo known-limitations --json"; }
-      else if (!kl.limitations || kl.limitations.length === 0) { status = "warn"; finding = "Known limitations register is empty — limitations must be documented."; }
-      else {
-        var allMit = kl.limitations.every(function(l) { return l.mitigation && l.mitigation.length > 0; });
-        if (!allMit) { status = "warn"; finding = "Some limitations are missing mitigation documentation."; }
-        else finding = "Known limitations: " + kl.limitations.length + " documented with mitigations.";
-      }
-      break;
-    }
-    case "scenario_9_see_next_action": {
-      var gate = read(".claude/cco/orchestration/full-readiness/latest-gate.json");
-      if (!gate) { status = "warn"; finding = "Full readiness gate not yet run. Run: node bin/avorelo full-readiness --json"; }
-      else if (!gate.safeNextAction || gate.safeNextAction.length < 10) { status = "warn"; finding = "safeNextAction is missing or too vague."; }
-      else finding = "safeNextAction present: \"" + gate.safeNextAction.slice(0, 60) + "...\"";
-      break;
-    }
-    case "scenario_10_blocked_action_safe_next": {
-      var gate2 = read(".claude/cco/orchestration/full-readiness/latest-gate.json");
-      if (!gate2) { status = "warn"; finding = "Full readiness gate not run — cannot verify blocked action handling."; }
-      else {
-        var allHaveSN = (gate2.blockers || []).every(function(b) { return b.safeNextAction && b.safeNextAction.length > 0; });
-        if (!allHaveSN && (gate2.blockers || []).length > 0) { status = "blocked"; finding = "Some blockers are missing safeNextAction."; }
-        else finding = gate2.blockers && gate2.blockers.length > 0 ? "All " + gate2.blockers.length + " blockers have safeNextAction." : "No blockers — safeNextAction pattern not needed.";
-      }
-      break;
-    }
-    default: status = "warn"; finding = "Unknown scenario: " + scenario.id;
-  }
-
-  return Object.assign({}, scenario, { result: status, finding: finding, evidence: evidence || null, safetyConstraintsVerified: scenario.safetyConstraints, configModified: false, hooksApplied: false, mcpPatched: false, destructiveCommandRun: false });
-}
-
-function runExternalUserSimulation(cwd, options) {
-  options = options || {};
-  var scenarios = buildExternalUserScenarios(cwd, options);
-  var evaluated = scenarios.map(function(s) { return evaluateExternalUserScenario(cwd, s, options); });
-  var passed = evaluated.filter(function(s) { return s.result === "pass"; }).length;
-  var warned = evaluated.filter(function(s) { return s.result === "warn"; }).length;
-  var blocked = evaluated.filter(function(s) { return s.result === "blocked"; }).length;
-  var overallStatus = blocked > 0 ? "blocked" : warned > 0 ? "warn" : "pass";
-  var simulation = { contract: CONTRACT, schemaVersion: SCHEMA_VERSION, createdAt: nowIso(), status: overallStatus, totalScenarios: scenarios.length, passed: passed, warned: warned, blocked: blocked, scenarios: evaluated, safetyGuarantees: { configModified: false, hooksApplied: false, mcpPatched: false, destructiveCommandRun: false, publicLaunchClaimed: false }, redacted: true };
-  try { appendProductLearningEvent(cwd, { eventName: "external_user_simulation_run", category: "full_readiness", status: overallStatus, passed: passed, warned: warned, blocked: blocked }); } catch (e) {}
-  return simulation;
-}
-
-function writeExternalUserSimulation(cwd, simulation) {
-  var dir = path.join(cwd, SIM_DIR_REL);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(simulation, null, 2));
-  return simulation;
-}
-
-function formatExternalUserSimulationText(simulation, options) {
-  options = options || {};
-  var lines = [];
-  lines.push("External user simulation: " + simulation.status + " (" + simulation.passed + "/" + simulation.totalScenarios + " pass)");
-  if (simulation.blocked > 0 || simulation.warned > 0) {
-    lines.push(""); lines.push("Issues:");
-    simulation.scenarios.filter(function(s) { return s.result !== "pass"; }).forEach(function(s) { lines.push("  [" + s.result + "] " + s.title); lines.push("    " + s.finding); });
-  }
-  lines.push(""); lines.push("Safety: no config modified, no hooks applied, no MCP patched.");
-  return lines.join("\n");
-}
-
-module.exports = { CONTRACT, SCHEMA_VERSION, ARTIFACT_REL, runExternalUserSimulation, buildExternalUserScenarios, evaluateExternalUserScenario, writeExternalUserSimulation, formatExternalUserSimulationText };

package/scripts/lib/failure-recovery-readiness.js

@@ -1,81 +0,0 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-
-const { nowIso } = require("./fsx");
-
-const CONTRACT = "avorelo.failureRecoveryReadiness.v1";
-const SCHEMA_VERSION = 1;
-const RECEIPT_REL = ".claude/cco/orchestration/failure-recovery/latest-recovery.json";
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function buildFailureRecoveryReadiness(cwd) {
-  const receipt = safeReadJson(path.join(cwd, RECEIPT_REL));
-  const launchHardening = safeReadJson(path.join(cwd, ".claude/cco/orchestration/launch-hardening/latest-gate.json"));
-  const supportBundle = safeReadJson(path.join(cwd, ".claude/cco/support/latest-support-bundle.json"));
-  const knownLimitations = safeReadJson(path.join(cwd, ".claude/cco/orchestration/full-readiness/latest-known-limitations.json"));
-
-  let moduleAvailable = false;
-  try {
-    const mod = require("./failure-recovery");
-    moduleAvailable = typeof mod.buildRecoveryPlan === "function" || typeof mod.buildFailureRecoveryReceipt === "function";
-  } catch {
-    moduleAvailable = false;
-  }
-
-  const missingEvidence = [];
-  const safeNextActions = [];
-
-  if (!moduleAvailable) {
-    missingEvidence.push("Failure recovery module is not loadable.");
-    safeNextActions.push("Inspect: scripts/lib/failure-recovery.js");
-  }
-  if (!launchHardening) {
-    missingEvidence.push("Launch hardening gate artifact is missing.");
-    safeNextActions.push("Run: node bin/avorelo launch-hardening --json");
-  }
-  if (!supportBundle || supportBundle.redacted !== true) {
-    missingEvidence.push("Redacted support bundle is missing.");
-    safeNextActions.push("Run: node bin/avorelo support-bundle --json");
-  }
-  if (!knownLimitations) {
-    missingEvidence.push("Known limitations register is missing.");
-    safeNextActions.push("Run: node bin/avorelo full-readiness --json");
-  }
-
-  const status = missingEvidence.length === 0 ? "pass" : "warn";
-  const safeNextAction = safeNextActions[0] || "Run: node bin/avorelo full-readiness --json";
-
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    createdAt: nowIso(),
-    status,
-    receiptAvailable: receipt !== null,
-    moduleAvailable,
-    launchHardeningAvailable: launchHardening !== null,
-    supportBundleAvailable: supportBundle?.redacted === true,
-    knownLimitationsAvailable: knownLimitations !== null,
-    artifactPath: RECEIPT_REL,
-    missingEvidence,
-    safeNextActions: safeNextActions.length ? safeNextActions : [safeNextAction],
-    safeNextAction,
-    redacted: true,
-  };
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  RECEIPT_REL,
-  buildFailureRecoveryReadiness,
-};

package/scripts/lib/failure-recovery.js

@@ -1,419 +0,0 @@
-"use strict";
-
-// ── Failure Recovery ──────────────────────────────────────────────────────────
-//
-// Contract: avorelo.failureRecovery.v1
-//
-// Classifies every failure mode with a safe next action, severity, and
-// recoverability flag. No raw logs, prompts, code, or secrets in receipts.
-
-const fs = require("fs");
-const path = require("path");
-const { ensureCcoDirs, nowIso } = require("./fsx");
-
-const CONTRACT = "avorelo.failureRecovery.v1";
-const SCHEMA_VERSION = 1;
-
-const RECOVERY_DIR_REL = ".claude/cco/orchestration/failure-recovery";
-const LATEST_RECOVERY_REL = `${RECOVERY_DIR_REL}/latest-recovery.json`;
-
-// ── Failure type constants ────────────────────────────────────────────────────
-
-const FAILURE_TYPES = Object.freeze({
-  CONFIG_INVALID: "CONFIG_INVALID",
-  CONFIG_BACKUP_MISSING: "CONFIG_BACKUP_MISSING",
-  HOOKS_NOT_APPLIED: "HOOKS_NOT_APPLIED",
-  HOOK_DOCTOR_FAILED: "HOOK_DOCTOR_FAILED",
-  RECURSION_GUARD_ACTIVE: "RECURSION_GUARD_ACTIVE",
-  PROJECT_PROFILE_UNKNOWN: "PROJECT_PROFILE_UNKNOWN",
-  SAFE_RUN_BLOCKED: "SAFE_RUN_BLOCKED",
-  PROOF_UNAVAILABLE: "PROOF_UNAVAILABLE",
-  PROOF_FAILED: "PROOF_FAILED",
-  TOKEN_GATE_FAILED: "TOKEN_GATE_FAILED",
-  SUPPORT_BUNDLE_REDACTION_FAILED: "SUPPORT_BUNDLE_REDACTION_FAILED",
-  STALE_ARTIFACTS: "STALE_ARTIFACTS",
-  CORRUPT_ARTIFACT: "CORRUPT_ARTIFACT",
-  PERMISSION_DENIED: "PERMISSION_DENIED",
-  MISSING_TOOL: "MISSING_TOOL",
-  PATH_NOT_FOUND: "PATH_NOT_FOUND",
-  WINDOWS_PATH_ISSUE: "WINDOWS_PATH_ISSUE",
-  MONOREPO_SCOPE_UNKNOWN: "MONOREPO_SCOPE_UNKNOWN",
-  FLAKY_TEST_SUSPECTED: "FLAKY_TEST_SUSPECTED",
-  DEPENDENCY_RESOLUTION_FAILED: "DEPENDENCY_RESOLUTION_FAILED",
-  NETWORK_DISABLED_EXPECTED: "NETWORK_DISABLED_EXPECTED",
-  ARTIFACT_WRITE_FAILED: "ARTIFACT_WRITE_FAILED",
-  JSON_OUTPUT_INVALID: "JSON_OUTPUT_INVALID",
-});
-
-// ── Failure classification table ──────────────────────────────────────────────
-
-const FAILURE_CLASSIFICATION = Object.freeze({
-  CONFIG_INVALID: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "The Avorelo config is invalid or cannot be parsed.",
-    safeNextAction: "Run `avorelo doctor` to identify and fix config issues.",
-    debugHint: "Check .claude/cco/state/ for config artifacts.",
-  },
-  CONFIG_BACKUP_MISSING: {
-    status: "needs_review",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "No config backup found before hook apply.",
-    safeNextAction: "Run `avorelo hooks apply --dry-run` to preview hook changes. Review backup artifacts before applying.",
-    debugHint: "Check .claude/cco/orchestration/hook-apply/ for backup artifacts.",
-  },
-  HOOKS_NOT_APPLIED: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "Avorelo hooks are not applied to this project.",
-    safeNextAction: "Run `avorelo hooks apply --dry-run` to preview, then `avorelo hooks apply --yes` to apply.",
-    debugHint: "Check .claude/cco/orchestration/hook-apply/latest-apply.json.",
-  },
-  HOOK_DOCTOR_FAILED: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "Hook validation failed. Avorelo hooks may not be functioning correctly.",
-    safeNextAction: "Run `avorelo hooks doctor` for details, then `avorelo hooks rollback` to restore previous config.",
-    debugHint: "Check .claude/cco/orchestration/hook-apply/latest-doctor.json.",
-  },
-  RECURSION_GUARD_ACTIVE: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "Avorelo recursion guard prevented a nested invocation.",
-    safeNextAction: "Wait for the current Avorelo run to complete, then retry.",
-    debugHint: "Recursion guard is expected in nested Claude Code sessions.",
-  },
-  PROJECT_PROFILE_UNKNOWN: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "Avorelo could not detect the project profile.",
-    safeNextAction: "Run `avorelo project-profile` to detect or configure the project profile.",
-    debugHint: "Check .claude/cco/orchestration/project-profile/latest-profile.json.",
-  },
-  SAFE_RUN_BLOCKED: {
-    status: "blocked",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "A safe run step was blocked due to scope or risk level.",
-    safeNextAction: "Review the blocking reason in `avorelo run --json` output. Narrow scope or get approval.",
-    debugHint: "Check .claude/cco/orchestration/safe-run/latest-run.json.",
-  },
-  PROOF_UNAVAILABLE: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "No proof artifact is available for this operation.",
-    safeNextAction: "Run `avorelo outcome` to generate a proof artifact.",
-    debugHint: "Check .claude/cco/orchestration/seamless-outcome/.",
-  },
-  PROOF_FAILED: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "Proof validation failed. Outcome integrity cannot be confirmed.",
-    safeNextAction: "Run `avorelo outcome --json` to see the proof failure details. Review and rerun the failing step.",
-    debugHint: "Check .claude/cco/orchestration/seamless-outcome/latest-reality-gate.json.",
-  },
-  TOKEN_GATE_FAILED: {
-    status: "needs_review",
-    severity: "error",
-    recoverable: false,
-    userMessage: "Token context quality gate failed.",
-    safeNextAction: "Run `avorelo token-efficiency --json` to see the quality gate details and reduce context.",
-    debugHint: "Check .claude/cco/orchestration/token-efficiency/latest-quality-gate.json.",
-  },
-  SUPPORT_BUNDLE_REDACTION_FAILED: {
-    status: "blocked",
-    severity: "critical",
-    recoverable: false,
-    userMessage: "Support bundle redaction failed. Bundle may contain sensitive data.",
-    safeNextAction: "Do not share the support bundle. Contact support@avorelo.com for a safe bundle procedure.",
-    debugHint: "Check support-bundle.js redaction logic.",
-  },
-  STALE_ARTIFACTS: {
-    status: "recoverable",
-    severity: "info",
-    recoverable: true,
-    userMessage: "Some Avorelo artifacts are stale and may not reflect current state.",
-    safeNextAction: "Run `avorelo artifacts health` to review stale artifacts, then `avorelo artifacts cleanup --dry-run` to plan cleanup.",
-    debugHint: "Check .claude/cco/orchestration/artifact-health/latest-health.json.",
-  },
-  CORRUPT_ARTIFACT: {
-    status: "needs_review",
-    severity: "error",
-    recoverable: false,
-    userMessage: "A corrupt artifact was detected. The artifact cannot be parsed.",
-    safeNextAction: "Run `avorelo artifacts health` to identify corrupt artifacts. Delete and regenerate corrupt artifacts.",
-    debugHint: "Check .claude/cco/orchestration/artifact-health/latest-health.json for corrupt file paths.",
-  },
-  PERMISSION_DENIED: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "Permission denied when accessing a required file or directory.",
-    safeNextAction: "Check file permissions for .claude/cco/ and ensure the current user can read/write this directory.",
-    debugHint: "Check OS-level permissions for .claude/cco/.",
-  },
-  MISSING_TOOL: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "A required tool is missing from PATH.",
-    safeNextAction: "Install the required tool and ensure it is available in PATH. Run `avorelo doctor` to re-check.",
-    debugHint: "Run `avorelo doctor` to see which tools are required.",
-  },
-  PATH_NOT_FOUND: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "A required path does not exist.",
-    safeNextAction: "Verify the path exists and the workspace is correctly configured. Run `avorelo doctor` to check.",
-    debugHint: "Check that cwd is set to the correct project root.",
-  },
-  WINDOWS_PATH_ISSUE: {
-    status: "needs_review",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "A Windows path issue was detected (spaces, backslashes, or drive letter handling).",
-    safeNextAction: "Ensure all paths use path.join() and avoid string concatenation. Move the project to a path without spaces if needed.",
-    debugHint: "Check for hardcoded path separators or unquoted paths with spaces.",
-  },
-  MONOREPO_SCOPE_UNKNOWN: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "Avorelo could not determine the monorepo scope.",
-    safeNextAction: "Run `avorelo project-profile` to detect the monorepo structure and configure scope.",
-    debugHint: "Check .claude/cco/orchestration/project-profile/latest-profile.json.",
-  },
-  FLAKY_TEST_SUSPECTED: {
-    status: "recoverable",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "A flaky test failure was suspected. The test may pass on retry.",
-    safeNextAction: "Retry the failing test in isolation. If it fails consistently, investigate the test for environmental dependencies.",
-    debugHint: "Check test output for timing-related or environment-specific failures.",
-  },
-  DEPENDENCY_RESOLUTION_FAILED: {
-    status: "blocked",
-    severity: "error",
-    recoverable: false,
-    userMessage: "Dependency resolution failed. Package install may be needed.",
-    safeNextAction: "Run `npm install` (or the project package manager) to restore dependencies.",
-    debugHint: "Check package.json and lockfile for inconsistencies.",
-  },
-  NETWORK_DISABLED_EXPECTED: {
-    status: "recoverable",
-    severity: "info",
-    recoverable: true,
-    userMessage: "Network is disabled. Avorelo is running in local-only mode.",
-    safeNextAction: "No action needed — Avorelo operates fully locally. Network access is not required.",
-    debugHint: "All Avorelo operations are local-first. No network access is expected.",
-  },
-  ARTIFACT_WRITE_FAILED: {
-    status: "needs_review",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "An Avorelo artifact could not be written.",
-    safeNextAction: "Check disk space and .claude/cco/ write permissions. Run `avorelo doctor` to check local state writability.",
-    debugHint: "Check for disk full or permission errors on .claude/cco/.",
-  },
-  JSON_OUTPUT_INVALID: {
-    status: "needs_review",
-    severity: "error",
-    recoverable: false,
-    userMessage: "A command produced invalid JSON output.",
-    safeNextAction: "Run the command again with --json flag. Check for mixed stdout/stderr contaminating JSON output.",
-    debugHint: "Ensure all log output goes to stderr, not stdout.",
-  },
-});
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function safeReadJson(absPath) {
-  try {
-    if (!fs.existsSync(absPath)) return null;
-    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
-  } catch {
-    return null;
-  }
-}
-
-function bestEffortWrite(absPath, obj) {
-  try {
-    fs.mkdirSync(path.dirname(absPath), { recursive: true });
-    fs.writeFileSync(absPath, JSON.stringify(obj, null, 2), "utf8");
-  } catch {}
-}
-
-// ── classifyFailure ───────────────────────────────────────────────────────────
-
-function classifyFailure(errorOrSignal, options = {}) {
-  const failureType = options.failureType || detectFailureType(errorOrSignal);
-  const classification = FAILURE_CLASSIFICATION[failureType] || {
-    status: "unknown",
-    severity: "warn",
-    recoverable: true,
-    userMessage: "An unknown error occurred.",
-    safeNextAction: "Run `avorelo doctor` for diagnostics.",
-    debugHint: null,
-  };
-
-  const exitCode = options.exitCode != null ? options.exitCode : (errorOrSignal?.exitCode ?? 1);
-
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    status: classification.status,
-    failureType,
-    severity: classification.severity,
-    recoverable: classification.recoverable,
-    userMessage: classification.userMessage,
-    safeNextAction: classification.safeNextAction,
-    debugHint: options.includeDebugHint !== false ? classification.debugHint : undefined,
-    artifactRefs: options.artifactRefs || [],
-    exitCode,
-    redacted: true,
-  };
-}
-
-function detectFailureType(errorOrSignal) {
-  if (!errorOrSignal) return "JSON_OUTPUT_INVALID";
-  const msg = String(errorOrSignal.message || errorOrSignal.code || errorOrSignal || "").toLowerCase();
-  if (/recursion.guard|recursion_guard/i.test(msg)) return FAILURE_TYPES.RECURSION_GUARD_ACTIVE;
-  if (/EACCES|permission.denied/i.test(msg)) return FAILURE_TYPES.PERMISSION_DENIED;
-  if (/ENOENT|path.not.found|no such file/i.test(msg)) return FAILURE_TYPES.PATH_NOT_FOUND;
-  if (/windows|backslash|drive.letter/i.test(msg)) return FAILURE_TYPES.WINDOWS_PATH_ISSUE;
-  if (/flaky|flaky.test/i.test(msg)) return FAILURE_TYPES.FLAKY_TEST_SUSPECTED;
-  if (/network|ECONNREFUSED|ENETUNREACH/i.test(msg)) return FAILURE_TYPES.NETWORK_DISABLED_EXPECTED;
-  if (/config.invalid|parse.error|SyntaxError/i.test(msg)) return FAILURE_TYPES.CONFIG_INVALID;
-  if (/hook.doctor/i.test(msg)) return FAILURE_TYPES.HOOK_DOCTOR_FAILED;
-  if (/proof.failed/i.test(msg)) return FAILURE_TYPES.PROOF_FAILED;
-  if (/token.gate/i.test(msg)) return FAILURE_TYPES.TOKEN_GATE_FAILED;
-  if (/redaction.failed/i.test(msg)) return FAILURE_TYPES.SUPPORT_BUNDLE_REDACTION_FAILED;
-  if (/corrupt/i.test(msg)) return FAILURE_TYPES.CORRUPT_ARTIFACT;
-  if (/stale/i.test(msg)) return FAILURE_TYPES.STALE_ARTIFACTS;
-  if (/missing.tool|command.not.found/i.test(msg)) return FAILURE_TYPES.MISSING_TOOL;
-  if (/dependency|npm.install/i.test(msg)) return FAILURE_TYPES.DEPENDENCY_RESOLUTION_FAILED;
-  if (/artifact.write/i.test(msg)) return FAILURE_TYPES.ARTIFACT_WRITE_FAILED;
-  return "JSON_OUTPUT_INVALID";
-}
-
-// ── buildRecoveryPlan ─────────────────────────────────────────────────────────
-
-function buildRecoveryPlan(cwd, failure, options = {}) {
-  const action = buildRecoveryAction(cwd, failure.failureType || "JSON_OUTPUT_INVALID", options);
-  const receipt = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    status: failure.status || "unknown",
-    failureType: failure.failureType,
-    severity: failure.severity || "warn",
-    recoverable: failure.recoverable !== undefined ? failure.recoverable : true,
-    userMessage: failure.userMessage || "An error occurred.",
-    safeNextAction: failure.safeNextAction || action.command || "Run `avorelo doctor`.",
-    debugHint: failure.debugHint || null,
-    artifactRefs: failure.artifactRefs || [],
-    exitCode: failure.exitCode != null ? failure.exitCode : 1,
-    recoveryAction: action,
-    createdAt: nowIso(),
-    redacted: true,
-  };
-  return receipt;
-}
-
-// ── buildRecoveryAction ───────────────────────────────────────────────────────
-
-function buildRecoveryAction(cwd, failureType, options = {}) {
-  const classification = FAILURE_CLASSIFICATION[failureType];
-  if (!classification) {
-    return {
-      failureType,
-      command: "avorelo doctor",
-      rationale: "Run diagnostics to identify and recover from this failure.",
-      automated: false,
-    };
-  }
-
-  return {
-    failureType,
-    command: classification.safeNextAction,
-    rationale: classification.userMessage,
-    automated: false,
-    severity: classification.severity,
-    recoverable: classification.recoverable,
-  };
-}
-
-// ── writeFailureRecoveryReceipt ───────────────────────────────────────────────
-
-function writeFailureRecoveryReceipt(cwd, receipt) {
-  const absPath = path.join(cwd, LATEST_RECOVERY_REL);
-  bestEffortWrite(absPath, receipt);
-}
-
-// ── buildFailureRecoverySurface ───────────────────────────────────────────────
-
-function buildFailureRecoverySurface(cwd, options = {}) {
-  const absPath = path.join(cwd, LATEST_RECOVERY_REL);
-  const latest = safeReadJson(absPath);
-
-  if (!latest) {
-    return {
-      contract: CONTRACT,
-      status: "no_failure_recorded",
-      failureType: null,
-      severity: null,
-      recoverable: null,
-      safeNextAction: "No failure recovery receipt found. Run any avorelo command to generate state.",
-      latestRecoveryPath: null,
-    };
-  }
-
-  return {
-    contract: CONTRACT,
-    status: latest.status,
-    failureType: latest.failureType,
-    severity: latest.severity,
-    recoverable: latest.recoverable,
-    safeNextAction: latest.safeNextAction,
-    latestRecoveryPath: LATEST_RECOVERY_REL,
-  };
-}
-
-// ── formatFailureRecoveryText ─────────────────────────────────────────────────
-
-function formatFailureRecoveryText(receipt, options = {}) {
-  if (!receipt) return "No failure recovery data available.";
-  const lines = [];
-  lines.push(`Failure Recovery: ${receipt.failureType || "unknown"}`);
-  lines.push(`Status: ${receipt.status || "unknown"} | Severity: ${receipt.severity || "unknown"} | Recoverable: ${receipt.recoverable ? "yes" : "no"}`);
-  lines.push("");
-  lines.push(receipt.userMessage || "No details available.");
-  lines.push("");
-  lines.push(`Next step: ${receipt.safeNextAction || "Run avorelo doctor."}`);
-  if (options.debug && receipt.debugHint) {
-    lines.push(`Debug: ${receipt.debugHint}`);
-  }
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  FAILURE_TYPES,
-  FAILURE_CLASSIFICATION,
-  LATEST_RECOVERY_REL,
-  classifyFailure,
-  buildRecoveryPlan,
-  buildRecoveryAction,
-  writeFailureRecoveryReceipt,
-  buildFailureRecoverySurface,
-  formatFailureRecoveryText,
-};