avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/external-readiness/safe-fix-executor.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { checkFixEligibility } = require('./skills/safe-fix-policy');
+
+function generateLlmsTxt(productFacts) {
+  if (!productFacts) return null;
+  const lines = [
+    `# ${productFacts.product_name || 'Product'}`,
+    '',
+    `> ${productFacts.short_description || ''}`,
+    '',
+    `## What it is`,
+    productFacts.what_it_is || '',
+    '',
+    `## What it is not`,
+    ...(productFacts.what_it_is_not || []).map(s => `- ${s}`),
+    '',
+    `## Category`,
+    productFacts.category || '',
+    '',
+    `## Core value`,
+    productFacts.core_value || '',
+    '',
+    `## Plans`,
+    productFacts.free_plan ? `- Free: ${productFacts.free_plan.includes || ''}` : '',
+    productFacts.pro_plan ? `- Pro: ${productFacts.pro_plan.includes || ''}` : '',
+    productFacts.teams_plan ? `- Teams: ${productFacts.teams_plan.includes || ''}` : '',
+    '',
+    `## Integrations`,
+    (productFacts.integrations || []).join(', '),
+    '',
+    `## Security`,
+    productFacts.security_positioning || '',
+  ].filter(l => l !== undefined);
+  return lines.join('\n') + '\n';
+}
+
+function generateHeadersFile() {
+  return [
+    '/*',
+    '  X-Content-Type-Options: nosniff',
+    '  X-Frame-Options: DENY',
+    '  Referrer-Policy: strict-origin-when-cross-origin',
+    '',
+  ].join('\n');
+}
+
+function executeSafeFixes(findings, context) {
+  const applied = [];
+  const skipped = [];
+
+  for (const f of findings) {
+    if (!f.autoFixEligible) continue;
+
+    // llms.txt generation
+    if (f.id === 'io-no-llms-txt' && context.publicWebSrc && context.productFacts) {
+      const policy = checkFixEligibility('llms-txt');
+      if (!policy.allowed) { skipped.push({ ...f, reason: policy.reason }); continue; }
+
+      const content = generateLlmsTxt(context.productFacts);
+      if (content) {
+        const target = path.join(context.publicWebSrc, 'llms.txt');
+        const before = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+        fs.writeFileSync(target, content, 'utf8');
+        applied.push({
+          findingId: f.id,
+          type: 'llms-txt',
+          file: target,
+          before: before ? 'existing file updated' : 'file did not exist',
+          after: `Generated ${content.length} bytes from product facts`,
+          reversible: true,
+        });
+      }
+    }
+
+    // Static headers file
+    if (f.id === 'io-no-static-headers-config' && context.publicWebSrc) {
+      const policy = checkFixEligibility('x-content-type-options');
+      if (!policy.allowed) { skipped.push({ ...f, reason: policy.reason }); continue; }
+
+      const target = path.join(context.publicWebSrc, '_headers');
+      if (!fs.existsSync(target)) {
+        const content = generateHeadersFile();
+        fs.writeFileSync(target, content, 'utf8');
+        applied.push({
+          findingId: f.id,
+          type: 'x-content-type-options',
+          file: target,
+          before: 'file did not exist',
+          after: 'Created _headers with X-Content-Type-Options, X-Frame-Options, Referrer-Policy',
+          reversible: true,
+        });
+      }
+    }
+  }
+
+  return { applied, skipped };
+}
+
+function revertFixes(appliedFixes) {
+  const reverted = [];
+  for (const fix of appliedFixes) {
+    if (fix.reversible && fix.before === 'file did not exist') {
+      try {
+        fs.unlinkSync(fix.file);
+        reverted.push({ file: fix.file, type: fix.type, result: 'deleted' });
+      } catch (e) {
+        reverted.push({ file: fix.file, type: fix.type, result: `revert failed: ${e.message}` });
+      }
+    }
+  }
+  return reverted;
+}
+
+module.exports = { executeSafeFixes, revertFixes, generateLlmsTxt, generateHeadersFile };

package/scripts/lib/external-readiness/skills/category-boundary-guard.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { BANNED_PHRASES } = require('./pmm-positioning-guard');
+
+function runCategoryGuard(texts) {
+  const allText = (Array.isArray(texts) ? texts : [texts]).join('\n');
+  const findings = [];
+
+  for (const phrase of BANNED_PHRASES) {
+    const re = new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+    let match;
+    while ((match = re.exec(allText)) !== null) {
+      const ctx = allText.slice(Math.max(0, match.index - 80), match.index + match[0].length + 40);
+      if (/not an?\s/i.test(ctx) || /\*\*not\*\*/i.test(ctx) || /is not/i.test(ctx) || /avoid/i.test(ctx) || /anti-trigger/i.test(ctx) || /what.it.is.not/i.test(ctx) || /asks about/i.test(ctx) || /not a/i.test(ctx)) continue;
+      findings.push({
+        id: `cat-boundary-${phrase.replace(/\s+/g, '-')}`,
+        category: 'pmm',
+        source: 'skill',
+        severity: 'blocking',
+        confidence: 'measured',
+        title: `Category drift: "${match[0]}"`,
+        detail: ctx.trim(),
+      });
+    }
+  }
+
+  return { pass: findings.length === 0, findings };
+}
+
+module.exports = { runCategoryGuard };

package/scripts/lib/external-readiness/skills/pmm-positioning-guard.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const BANNED_PHRASES = [
+  'seo optimizer', 'aeo platform', 'geo dashboard',
+  'ai search ranking tool', 'marketing analytics suite',
+  'unlock full report', 'rank higher', 'boost ai visibility',
+  'boost your ai visibility', 'fix your ai seo',
+  'website grader',
+];
+
+const REQUIRED_CONCEPTS = [
+  'ai work control',
+  'outside-in',
+  'inside',
+  'safe fix',
+  'proof',
+  'no signup',
+];
+
+function runPmmGuard(texts) {
+  const findings = [];
+  const allText = (Array.isArray(texts) ? texts : [texts]).join('\n').toLowerCase();
+
+  for (const phrase of BANNED_PHRASES) {
+    const idx = allText.indexOf(phrase);
+    if (idx !== -1) {
+      const context = allText.slice(Math.max(0, idx - 80), idx + phrase.length + 40);
+      // Allow in "what Avorelo is not" / anti-trigger / negative positioning context
+      if (/not an?\s/i.test(context) || /\*\*not\*\*/i.test(context) || /is not/i.test(context) || /anti-trigger/i.test(context) || /what.it.is.not/i.test(context) || /avoid/i.test(context)) continue;
+      findings.push({
+        id: `pmm-banned-${phrase.replace(/\s+/g, '-')}`,
+        category: 'pmm',
+        source: 'skill',
+        severity: 'blocking',
+        confidence: 'measured',
+        title: `Banned phrase: "${phrase}"`,
+        detail: `Found in: "...${context.trim()}..."`,
+        evidence: context.trim(),
+        autoFixEligible: false,
+        requiresApproval: true,
+        suggestedFix: 'Remove or rephrase to avoid category drift.',
+      });
+    }
+  }
+
+  const missingConcepts = REQUIRED_CONCEPTS.filter(c => !allText.includes(c));
+  if (missingConcepts.length > 2) {
+    findings.push({
+      id: 'pmm-missing-concepts',
+      category: 'pmm',
+      source: 'skill',
+      severity: 'advisory',
+      confidence: 'estimated',
+      title: 'Missing core positioning concepts',
+      detail: `Missing: ${missingConcepts.join(', ')}`,
+      evidence: missingConcepts.join(', '),
+      autoFixEligible: false,
+      requiresApproval: false,
+    });
+  }
+
+  return {
+    pass: findings.filter(f => f.severity === 'blocking').length === 0,
+    riskLevel: findings.length === 0 ? 'low' : findings.some(f => f.severity === 'blocking') ? 'high' : 'medium',
+    findings,
+  };
+}
+
+module.exports = { runPmmGuard, BANNED_PHRASES, REQUIRED_CONCEPTS };

package/scripts/lib/external-readiness/skills/safe-fix-policy.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const ALLOWED_AUTO = [
+  'title', 'meta-description', 'og-metadata', 'twitter-metadata', 'canonical',
+  'json-ld', 'llms-txt', 'sitemap-basic', 'robots-basic', 'aria-label', 'internal-docs-link',
+  'x-content-type-options',
+];
+
+const REQUIRES_APPROVAL = [
+  'pricing-claims', 'legal-privacy-terms', 'security-compliance-claims',
+  'auth-payment-flows', 'oauth-api-mcp-exposure', 'competitor-comparison',
+  'aggressive-csp-session-cookie', 'destructive-file-change',
+];
+
+function checkFixEligibility(fixType) {
+  if (ALLOWED_AUTO.includes(fixType)) return { allowed: true, requiresApproval: false };
+  if (REQUIRES_APPROVAL.includes(fixType)) return { allowed: false, requiresApproval: true, reason: `"${fixType}" requires human approval.` };
+  return { allowed: false, requiresApproval: true, reason: `Unknown fix type "${fixType}" requires approval.` };
+}
+
+function runSafeFixPolicy(plannedFixes) {
+  const approved = [];
+  const needsAttention = [];
+  for (const fix of plannedFixes) {
+    const result = checkFixEligibility(fix.type);
+    if (result.allowed) {
+      approved.push({ ...fix, policyResult: 'approved' });
+    } else {
+      needsAttention.push({ ...fix, policyResult: 'requires_approval', reason: result.reason });
+    }
+  }
+  return { approved, needsAttention };
+}
+
+module.exports = { checkFixEligibility, runSafeFixPolicy, ALLOWED_AUTO, REQUIRES_APPROVAL };

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 open` 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,
+};