avorelo 0.1.0

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

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

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

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