avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/agent-activation-readiness.js

@@ -0,0 +1,878 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const {
+  ensureCcoDirs,
+  nowIso,
+  safeReadJson,
+  safeWriteJson,
+} = require("./fsx");
+
+const CONTRACT = "avorelo.agentActivationReadiness.v1";
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const REPORT_DIR_REL = ".claude/cco/orchestration/agent-readiness";
+const LATEST_REPORT_REL = `${REPORT_DIR_REL}/latest-readiness.json`;
+
+const PRODUCT_HOME_REPORT_REL = ".claude/cco/orchestration/product-home/latest-receipt.json";
+const SUPPORT_BUNDLE_REL = ".claude/cco/support/latest-support-bundle.json";
+const PUBLIC_DISTRIBUTION_TRUTH_REL = ".claude/cco/orchestration/public-distribution/latest-truth.json";
+const INSTALL_CLAIMS_REL = ".claude/cco/orchestration/public-distribution/latest-install-claim-check.json";
+const CAPABILITY_INTAKE_REPORT_REL = ".claude/cco/security/capability-intake/latest-report.json";
+
+const REQUIRED_HOOK_EVENTS = Object.freeze(["PreToolUse", "PostToolUse", "Stop"]);
+const SECRET_LIKE_RE = /authorization:\s*bearer|api[_-]?key|password\s*=|secret\s*=|_authToken|AVORELO_NPM_OTP/i;
+
+function fileExists(cwd, relPath) {
+  return Boolean(relPath) && fs.existsSync(path.join(cwd, relPath));
+}
+
+function packageFileExists(relPath) {
+  return Boolean(relPath) && fs.existsSync(path.join(PACKAGE_ROOT, relPath));
+}
+
+function safeReadText(cwd, relPath) {
+  try {
+    return fs.readFileSync(path.join(cwd, relPath), "utf8").replace(/^\uFEFF/, "");
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeText(value, max = 220) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.replace(/\s+/g, " ").trim();
+  if (!trimmed) return null;
+  return trimmed.length > max ? `${trimmed.slice(0, max - 3)}...` : trimmed;
+}
+
+function toTitleCaseStatus(value) {
+  return String(value || "no_data")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+function uniq(items) {
+  return Array.from(new Set((items || []).filter(Boolean)));
+}
+
+function pushReason(reasonCodes, code, condition = true) {
+  if (condition) reasonCodes.push(code);
+}
+
+function hasGeneratedMarker(text) {
+  return /Generated by Wuz/i.test(text || "");
+}
+
+function looksThinAdapter(text) {
+  if (typeof text !== "string") return true;
+  const lines = text.split(/\r?\n/).length;
+  return text.length <= 6000 && lines <= 140;
+}
+
+function hasPointerLanguage(text) {
+  return /(Avorelo|Wuz|node bin\/avorelo|npx avorelo@latest|local launch layer|project instruction)/i.test(text || "");
+}
+
+function buildRefList(cwd, refs) {
+  return uniq((refs || []).filter((ref) => fileExists(cwd, ref) || packageFileExists(ref) || /^[A-Za-z0-9._/-]+$/.test(ref)));
+}
+
+function summarizeAgentReadiness(readiness) {
+  if (!readiness || typeof readiness !== "object") return null;
+  return {
+    status: readiness.status,
+    readyItems: readiness.summary?.readyItems || 0,
+    missingItems: readiness.summary?.missingItems || 0,
+    needsApproval: readiness.summary?.needsApproval || 0,
+    blockedItems: readiness.summary?.blockedItems || 0,
+    firstValueVerified: readiness.summary?.firstValueVerified === true,
+    safeNextAction: readiness.summary?.safeNextAction || "Continue with bounded AI-agent work.",
+    reasonCodes: uniq(readiness.activationPlan?.reasonCodes || []),
+    evidenceRef: LATEST_REPORT_REL,
+    redacted: true,
+  };
+}
+
+function listSensitiveWorkspaceFiles(cwd) {
+  const matches = [];
+  const candidates = [
+    { rel: ".env", code: "env_file_blocked" },
+    { rel: ".env.local", code: "env_file_blocked" },
+    { rel: ".env.production", code: "env_file_blocked" },
+    { rel: ".npmrc", code: "secret_like_content_blocked" },
+    { rel: "auth.json", code: "auth_file_blocked" },
+    { rel: "auth.config.json", code: "auth_file_blocked" },
+    { rel: "secrets.json", code: "secret_like_content_blocked" },
+  ];
+
+  for (const candidate of candidates) {
+    if (fileExists(cwd, candidate.rel)) {
+      matches.push({
+        relPath: candidate.rel,
+        code: candidate.code,
+        summary: `${candidate.rel} stays out of activation scope.`,
+      });
+    }
+  }
+
+  return matches;
+}
+
+function inspectHookState(cwd, reasonCodes) {
+  const { buildHookConfigPreview } = require("./hook-config-preview");
+  const { AVORELO_LIFECYCLE_COMMANDS } = require("./hook-apply");
+
+  const preview = buildHookConfigPreview(cwd);
+  const configTargets = uniq([
+    ".claude/settings.json",
+    ...((preview.configPaths || []).filter(Boolean)),
+  ]);
+
+  const installedEvents = new Set();
+  const hookChanges = [];
+  const plannedChanges = [];
+  const approvalRequiredChanges = [];
+  const blockedChanges = [];
+
+  let invalidConfigDetected = false;
+  let configPresent = false;
+  let userHookConfigPresent = false;
+
+  for (const configRelPath of configTargets) {
+    const configAbsPath = path.join(cwd, configRelPath);
+    if (!fs.existsSync(configAbsPath)) {
+      continue;
+    }
+
+    configPresent = true;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(fs.readFileSync(configAbsPath, "utf8").replace(/^\uFEFF/, ""));
+    } catch {
+      invalidConfigDetected = true;
+      hookChanges.push({
+        target: configRelPath,
+        status: "needs_review",
+        change: "Existing hook config is not valid JSON.",
+        approvalRequired: true,
+      });
+      approvalRequiredChanges.push(`Review invalid hook config in ${configRelPath} before changing lifecycle hooks.`);
+      pushReason(reasonCodes, "tool_config_requires_approval");
+      continue;
+    }
+
+    const hooks = Array.isArray(parsed?.hooks) ? parsed.hooks : [];
+    const userHooks = hooks.filter((entry) =>
+      !String(entry?.command || "").includes("node bin/avorelo lifecycle-hook")
+    );
+    if (userHooks.length > 0) {
+      userHookConfigPresent = true;
+    }
+
+    for (const expected of AVORELO_LIFECYCLE_COMMANDS) {
+      const found = hooks.some((entry) =>
+        entry
+        && entry.event === expected.event
+        && String(entry.command || "").includes(expected.command)
+      );
+      if (found) {
+        installedEvents.add(expected.event);
+      }
+    }
+  }
+
+  const missingEvents = REQUIRED_HOOK_EVENTS.filter((event) => !installedEvents.has(event));
+  const preToolReady = installedEvents.has("PreToolUse");
+  const postToolReady = installedEvents.has("PostToolUse");
+  const stopHookReady = installedEvents.has("Stop");
+
+  for (const event of missingEvents) {
+    hookChanges.push({
+      target: ".claude/settings.json",
+      status: "missing",
+      change: `Would add the ${event} lifecycle hook through the previewed local config path.`,
+      approvalRequired: true,
+    });
+    plannedChanges.push(`Preview the missing ${event} lifecycle hook in .claude/settings.json.`);
+  }
+
+  if (missingEvents.length > 0) {
+    approvalRequiredChanges.push(
+      userHookConfigPresent
+        ? "Merge the previewed lifecycle hooks into the existing local hook config while preserving user-authored entries."
+        : "Approve the preview before adding lifecycle hooks to the local hook config."
+    );
+    pushReason(reasonCodes, "hook_approval_required");
+    pushReason(reasonCodes, "silent_hook_install_blocked");
+  } else if (!invalidConfigDetected) {
+    pushReason(reasonCodes, "hook_ready");
+  }
+
+  pushReason(reasonCodes, "hook_preview_available");
+  pushReason(reasonCodes, "pre_tool_hook_missing", !preToolReady);
+  pushReason(reasonCodes, "post_tool_hook_missing", !postToolReady);
+  pushReason(reasonCodes, "stop_hook_missing", !stopHookReady);
+
+  return {
+    checked: true,
+    preToolReady,
+    postToolReady,
+    stopHookReady,
+    hookPreviewAvailable: true,
+    silentInstall: false,
+    approvalRequired: missingEvents.length > 0 || invalidConfigDetected,
+    hookChanges,
+    plannedChanges,
+    approvalRequiredChanges,
+    blockedChanges,
+    configPresent,
+  };
+}
+
+function inspectAdapterFile(cwd, relPath, requiredMarkers, options = {}) {
+  const text = safeReadText(cwd, relPath);
+  const exists = text !== null;
+  const notApplicableWhenMissing = options.notApplicableWhenMissing === true;
+
+  if (!exists) {
+    return {
+      status: notApplicableWhenMissing ? "not_applicable" : "missing",
+      thin: true,
+      reasonCode: notApplicableWhenMissing ? null : "adapter_missing",
+    };
+  }
+
+  if (SECRET_LIKE_RE.test(text)) {
+    return {
+      status: "user_content_preserved",
+      thin: true,
+      reasonCode: "secret_like_content_blocked",
+    };
+  }
+
+  const generated = hasGeneratedMarker(text);
+  const thin = looksThinAdapter(text);
+  const markersPresent = requiredMarkers.every((marker) => marker.test(text));
+  const pointerReady = hasPointerLanguage(text);
+
+  if (!generated) {
+    return {
+      status: "user_content_preserved",
+      thin,
+      reasonCode: "adapter_user_content_preserved",
+    };
+  }
+
+  if (!thin || !markersPresent || !pointerReady) {
+    return {
+      status: "stale",
+      thin,
+      reasonCode: "adapter_stale",
+    };
+  }
+
+  return {
+    status: "ready",
+    thin: true,
+    reasonCode: "adapter_ready",
+  };
+}
+
+function inspectCursorAdapter(cwd) {
+  const expectedRelPath = ".cursor/rules/wuz-project.mdc";
+  const expectedAbsPath = path.join(cwd, expectedRelPath);
+  const cursorDir = path.join(cwd, ".cursor");
+  if (!fs.existsSync(cursorDir)) {
+    return { status: "not_applicable", thin: true, reasonCode: null };
+  }
+  if (!fs.existsSync(expectedAbsPath)) {
+    const otherFiles = fs.existsSync(path.join(cursorDir, "rules"))
+      ? fs.readdirSync(path.join(cursorDir, "rules")).length
+      : 0;
+    return {
+      status: otherFiles > 0 ? "user_content_preserved" : "missing",
+      thin: true,
+      reasonCode: otherFiles > 0 ? "adapter_user_content_preserved" : "adapter_missing",
+    };
+  }
+  return inspectAdapterFile(cwd, expectedRelPath, [/Cursor/i, /(Avorelo|Wuz)/i], {});
+}
+
+function inspectCodexAdapter(cwd) {
+  const configRelPath = ".codex/config.toml";
+  if (!fileExists(cwd, ".codex")) {
+    return { status: "not_applicable", thin: true, reasonCode: null };
+  }
+  return inspectAdapterFile(cwd, configRelPath, [/\[wuz\]/i, /tool\s*=\s*"codex"/i], {});
+}
+
+function inspectGeminiAdapter(cwd) {
+  const geminiDir = path.join(cwd, ".gemini");
+  if (!fs.existsSync(geminiDir)) {
+    return { status: "not_applicable", thin: true, reasonCode: null };
+  }
+  const candidateFiles = [
+    ".gemini/config.json",
+    ".gemini/settings.json",
+    ".gemini/GEMINI.md",
+  ];
+  const relPath = candidateFiles.find((candidate) => fileExists(cwd, candidate));
+  if (!relPath) {
+    return { status: "missing", thin: true, reasonCode: "adapter_missing" };
+  }
+  return inspectAdapterFile(cwd, relPath, [/(Gemini|Avorelo|Wuz)/i], {});
+}
+
+function inspectAdapters(cwd, reasonCodes) {
+  const claudeMd = inspectAdapterFile(cwd, "CLAUDE.md", [/Wuz/i, /Claude/i], {});
+  const agentsMd = inspectAdapterFile(cwd, "AGENTS.md", [/Wuz/i, /Codex/i], {});
+  const llmsTxt = inspectAdapterFile(cwd, "llms.txt", [/(Avorelo|Wuz)/i], { notApplicableWhenMissing: true });
+  const cursor = inspectCursorAdapter(cwd);
+  const codex = inspectCodexAdapter(cwd);
+  const gemini = inspectGeminiAdapter(cwd);
+
+  const statuses = [claudeMd, agentsMd, llmsTxt, cursor, codex, gemini];
+  const thinAdaptersOnly = statuses.every((adapter) => adapter.thin !== false);
+
+  for (const adapter of statuses) {
+    pushReason(reasonCodes, adapter.reasonCode, Boolean(adapter.reasonCode));
+  }
+  pushReason(reasonCodes, "thin_adapter_required", !thinAdaptersOnly);
+
+  return {
+    checked: true,
+    claudeMd: claudeMd.status,
+    agentsMd: agentsMd.status,
+    llmsTxt: llmsTxt.status,
+    cursor: cursor.status,
+    codex: codex.status,
+    gemini: gemini.status,
+    thinAdaptersOnly,
+  };
+}
+
+function classifySurfaceAvailability(cwd, refs) {
+  return refs.every((ref) => fileExists(cwd, ref) || packageFileExists(ref)) ? "pass" : "missing";
+}
+
+function buildFirstValue(cwd, workspace, reasonCodes) {
+  const valueSignalsExists = packageFileExists("scripts/lib/cost-to-outcome-signals.js")
+    || packageFileExists("tests/cost-to-outcome-signals.test.js");
+
+  const firstValue = {
+    home: classifySurfaceAvailability(cwd, ["scripts/lib/product-home-receipt.js"]),
+    status: classifySurfaceAvailability(cwd, ["scripts/cco-status.js", "scripts/lib/dashboard.js"]),
+    repair: classifySurfaceAvailability(cwd, ["scripts/lib/safe-repair.js"]),
+    nextRun: classifySurfaceAvailability(cwd, ["scripts/lib/next-run-continuity.js"]),
+    scopeRepair: classifySurfaceAvailability(cwd, ["scripts/lib/scope-repair-before-approval.js"]),
+    valueSignals: valueSignalsExists ? "pass" : "not_applicable",
+    support: classifySurfaceAvailability(cwd, ["scripts/lib/support-bundle.js"]),
+  };
+
+  const requiredStatuses = [firstValue.home, firstValue.status, firstValue.repair, firstValue.nextRun, firstValue.scopeRepair, firstValue.support];
+  const firstValueVerified = workspace.publicPackageVerified === true
+    && requiredStatuses.every((status) => status === "pass")
+    && (firstValue.valueSignals === "pass" || firstValue.valueSignals === "not_applicable");
+
+  pushReason(reasonCodes, "home_verified", firstValue.home === "pass");
+  pushReason(reasonCodes, "status_verified", firstValue.status === "pass");
+  pushReason(reasonCodes, "repair_verified", firstValue.repair === "pass");
+  pushReason(reasonCodes, "next_run_verified", firstValue.nextRun === "pass");
+  pushReason(reasonCodes, "scope_repair_verified", firstValue.scopeRepair === "pass");
+  pushReason(reasonCodes, "value_signals_verified", firstValue.valueSignals === "pass");
+  pushReason(reasonCodes, "value_signals_not_applicable", firstValue.valueSignals === "not_applicable");
+  pushReason(reasonCodes, "support_verified", firstValue.support === "pass");
+  pushReason(reasonCodes, "support_fallback_available", firstValue.support !== "missing");
+  pushReason(reasonCodes, "first_value_verified", firstValueVerified);
+
+  return {
+    firstValue,
+    firstValueVerified,
+  };
+}
+
+function summarizeReadyItems(workspace, hooks, adapters, firstValueVerified) {
+  let count = 0;
+  if (workspace.repoDetected) count += 1;
+  if (workspace.packageDetected) count += 1;
+  if (workspace.publicPackageVerified) count += 1;
+  if (hooks.preToolReady && hooks.postToolReady && hooks.stopHookReady) count += 1;
+  if (adapters.claudeMd === "ready") count += 1;
+  if (adapters.agentsMd === "ready") count += 1;
+  if (adapters.codex === "ready") count += 1;
+  if (adapters.cursor === "ready") count += 1;
+  if (firstValueVerified) count += 1;
+  return count;
+}
+
+function summarizeMissingItems(hooks, adapters, firstValue) {
+  const adapterStates = [adapters.claudeMd, adapters.agentsMd, adapters.llmsTxt, adapters.cursor, adapters.codex, adapters.gemini];
+  let count = adapterStates.filter((status) => status === "missing" || status === "stale").length;
+  count += REQUIRED_HOOK_EVENTS.filter((event) =>
+    (event === "PreToolUse" && !hooks.preToolReady)
+    || (event === "PostToolUse" && !hooks.postToolReady)
+    || (event === "Stop" && !hooks.stopHookReady)
+  ).length;
+  count += Object.values(firstValue).filter((status) => status === "missing").length;
+  return count;
+}
+
+function determineSafeNextAction(status, hooks, adapters, firstValueVerified, blockedChanges) {
+  if (blockedChanges.length > 0 || status === "blocked") {
+    return "Review the blocked file or config manually before changing lifecycle hooks.";
+  }
+  if (hooks.approvalRequired) {
+    return "Run `node bin/avorelo hooks preview --json` and approve the hook preview before changing lifecycle hooks, or continue in prepare-only mode.";
+  }
+  if (
+    ["missing", "stale", "user_content_preserved"].includes(adapters.claudeMd)
+    || ["missing", "stale", "user_content_preserved"].includes(adapters.agentsMd)
+    || ["missing", "stale", "user_content_preserved"].includes(adapters.codex)
+  ) {
+    return "Keep adapter files thin and local. Preserve user-authored content and add only compact Avorelo pointers.";
+  }
+  if (!firstValueVerified) {
+    return "Run `node bin/avorelo home --text` and `node bin/avorelo next-run --text` to verify the first local value path.";
+  }
+  return "Continue with bounded AI-agent work.";
+}
+
+function buildWorkspaceSection(cwd, reasonCodes) {
+  const pkg = safeReadJson(cwd, "package.json", null);
+  const truthArtifact = safeReadJson(cwd, PUBLIC_DISTRIBUTION_TRUTH_REL, null);
+  const installClaimsArtifact = safeReadJson(cwd, INSTALL_CLAIMS_REL, null);
+
+  const repoDetected = fileExists(cwd, ".git") || fileExists(cwd, "AGENTS.md") || fileExists(cwd, "CLAUDE.md") || fileExists(cwd, ".codex/config.toml");
+  const packageDetected = Boolean(pkg);
+  const distributionState = truthArtifact?.distributionState
+    || pkg?.avoreloDistributionState
+    || (pkg?.private === false ? "ready_to_publish" : "unknown");
+  const publicPackageVerified = distributionState === "published_verified";
+  const npmVersion = typeof pkg?.version === "string" ? pkg.version : "unknown";
+
+  pushReason(reasonCodes, "repo_detected", repoDetected);
+  pushReason(reasonCodes, "package_detected", packageDetected);
+  pushReason(reasonCodes, "public_distribution_verified", publicPackageVerified);
+  pushReason(reasonCodes, "npm_version_verified", npmVersion !== "unknown");
+
+  return {
+    workspace: {
+      repoDetected,
+      packageDetected,
+      publicPackageVerified,
+      distributionState,
+      npmVersion,
+    },
+    packageTruthBlocked: Boolean(
+      packageDetected
+      && (pkg?.name === "avorelo" || pkg?.avoreloDistributionState || truthArtifact)
+      && (!publicPackageVerified || Number(installClaimsArtifact?.blockedCount || 0) > 0)
+    ),
+  };
+}
+
+function buildIntegrationRefs(cwd, valueSignalsIncluded) {
+  return {
+    home: buildRefList(cwd, ["scripts/lib/product-home-receipt.js", PRODUCT_HOME_REPORT_REL]),
+    status: buildRefList(cwd, ["scripts/cco-status.js", "scripts/lib/dashboard.js"]),
+    dashboard: buildRefList(cwd, ["scripts/cco-dashboard.js", "scripts/lib/dashboard.js"]),
+    repair: buildRefList(cwd, ["scripts/lib/safe-repair.js"]),
+    nextRun: buildRefList(cwd, ["scripts/lib/next-run-continuity.js"]),
+    scopeRepair: buildRefList(cwd, ["scripts/lib/scope-repair-before-approval.js"]),
+    valueSignals: valueSignalsIncluded ? buildRefList(cwd, ["scripts/lib/cost-to-outcome-signals.js"]) : [],
+    support: buildRefList(cwd, ["scripts/lib/support-bundle.js", SUPPORT_BUNDLE_REL]),
+    capabilityIntake: buildRefList(cwd, ["scripts/lib/capability-intake-quarantine.js", CAPABILITY_INTAKE_REPORT_REL]),
+    packagePublicGates: buildRefList(cwd, [
+      "scripts/lib/public-distribution-truth.js",
+      "scripts/lib/public-install-claim-checker.js",
+      PUBLIC_DISTRIBUTION_TRUTH_REL,
+      INSTALL_CLAIMS_REL,
+    ]),
+  };
+}
+
+function inspectCapabilityIntake(cwd, reasonCodes) {
+  const report = safeReadJson(cwd, CAPABILITY_INTAKE_REPORT_REL, null);
+  if (!report || report.schemaVersion !== "avorelo.capabilityIntakeQuarantine.v1") {
+    return {
+      present: false,
+      approvalRequiredChanges: [],
+      blockedChanges: [],
+    };
+  }
+
+  const relevant = (report.candidates || []).filter((candidate) =>
+    candidate.type === "adapter"
+    || (candidate.risk?.permissions || []).some((permission) =>
+      ["writes_files", "browser_access", "network_access", "executes_commands", "package_install"].includes(permission)
+    )
+  );
+  const blocked = relevant.filter((candidate) => candidate.decision?.state === "block");
+  const review = relevant.filter((candidate) =>
+    ["manual_review", "quarantine"].includes(candidate.decision?.state)
+  );
+
+  if (blocked.length > 0) pushReason(reasonCodes, "capability_intake_blocked");
+  if (review.length > 0) pushReason(reasonCodes, "capability_intake_review_required");
+
+  return {
+    present: true,
+    approvalRequiredChanges: review.length > 0
+      ? ["Capability intake found adapter, browser, network, command, or package candidates that need review before trust."]
+      : [],
+    blockedChanges: blocked.length > 0
+      ? ["Capability intake blocked an adapter or side-effecting capability candidate that must stay out of readiness scope."]
+      : [],
+  };
+}
+
+function buildClaimSafetySection() {
+  return {
+    silentHookInstall: false,
+    universalAgentSupport: false,
+    guaranteedEnforcement: false,
+    launchReadyClaim: false,
+    cloudSync: false,
+    remoteTelemetry: false,
+    fullAdapterFramework: false,
+  };
+}
+
+function buildPrivacySection() {
+  return {
+    localOnly: true,
+    rawPromptStored: false,
+    rawCodeStored: false,
+    secretsStored: false,
+    envStored: false,
+    fullLogsStored: false,
+    privatePathsStored: false,
+    redacted: true,
+  };
+}
+
+function buildAgentActivationReadiness(cwd = process.cwd(), options = {}) {
+  const reasonCodes = [];
+  const { workspace, packageTruthBlocked } = buildWorkspaceSection(cwd, reasonCodes);
+  const activationContextDetected = [
+    ".avorelo/activation/activation-state.json",
+    ".claude/cco/state/activation.json",
+    ".claude/settings.json",
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".codex/config.toml",
+    ".cursor",
+    ".gemini",
+    "llms.txt",
+  ].some((relPath) => fileExists(cwd, relPath));
+
+  if (!workspace.repoDetected && !workspace.packageDetected) {
+    const noData = {
+      schemaVersion: CONTRACT,
+      generatedAt: nowIso(),
+      status: "no_data",
+      redacted: true,
+      summary: {
+        readyItems: 0,
+        missingItems: 0,
+        needsApproval: 0,
+        blockedItems: 0,
+        firstValueVerified: false,
+        safeNextAction: "Run from a project repo or use `node bin/avorelo status --text` first.",
+      },
+      workspace,
+      activationPlan: {
+        mode: "check_only",
+        plannedChanges: [],
+        approvalRequiredChanges: [],
+        blockedChanges: [],
+        reasonCodes: uniq(reasonCodes),
+      },
+      hooks: {
+        checked: false,
+        preToolReady: false,
+        postToolReady: false,
+        stopHookReady: false,
+        hookPreviewAvailable: false,
+        silentInstall: false,
+        approvalRequired: false,
+        hookChanges: [],
+      },
+      adapters: {
+        checked: false,
+        claudeMd: "not_applicable",
+        agentsMd: "not_applicable",
+        llmsTxt: "not_applicable",
+        cursor: "not_applicable",
+        codex: "not_applicable",
+        gemini: "not_applicable",
+        thinAdaptersOnly: true,
+      },
+      firstValue: {
+        home: "missing",
+        status: "missing",
+        repair: "missing",
+        nextRun: "missing",
+        scopeRepair: "missing",
+        valueSignals: "not_applicable",
+        support: "missing",
+      },
+      integrationRefs: buildIntegrationRefs(cwd, false),
+      privacy: buildPrivacySection(),
+      claimSafety: buildClaimSafetySection(),
+    };
+    return noData;
+  }
+
+  if (!activationContextDetected) {
+    return {
+      schemaVersion: CONTRACT,
+      generatedAt: nowIso(),
+      status: "no_data",
+      redacted: true,
+      summary: {
+        readyItems: workspace.publicPackageVerified ? 1 : 0,
+        missingItems: 0,
+        needsApproval: 0,
+        blockedItems: packageTruthBlocked ? 1 : 0,
+        firstValueVerified: false,
+        safeNextAction: "Run from a project repo with local activation context, or use `node bin/avorelo status --text` first.",
+      },
+      workspace,
+      activationPlan: {
+        mode: "check_only",
+        plannedChanges: [],
+        approvalRequiredChanges: [],
+        blockedChanges: packageTruthBlocked
+          ? ["Public package or install-claim truth must stay published_verified before claiming activation readiness."]
+          : [],
+        reasonCodes: uniq(reasonCodes),
+      },
+      hooks: {
+        checked: false,
+        preToolReady: false,
+        postToolReady: false,
+        stopHookReady: false,
+        hookPreviewAvailable: false,
+        silentInstall: false,
+        approvalRequired: false,
+        hookChanges: [],
+      },
+      adapters: {
+        checked: false,
+        claudeMd: "not_applicable",
+        agentsMd: "not_applicable",
+        llmsTxt: "not_applicable",
+        cursor: "not_applicable",
+        codex: "not_applicable",
+        gemini: "not_applicable",
+        thinAdaptersOnly: true,
+      },
+      firstValue: {
+        home: "missing",
+        status: "missing",
+        repair: "missing",
+        nextRun: "missing",
+        scopeRepair: "missing",
+        valueSignals: "not_applicable",
+        support: "missing",
+      },
+      integrationRefs: buildIntegrationRefs(cwd, false),
+      privacy: buildPrivacySection(),
+      claimSafety: buildClaimSafetySection(),
+    };
+  }
+
+  pushReason(reasonCodes, "activation_plan_created");
+
+  const hooks = inspectHookState(cwd, reasonCodes);
+  const adapters = inspectAdapters(cwd, reasonCodes);
+  const { firstValue, firstValueVerified } = buildFirstValue(cwd, workspace, reasonCodes);
+  const blockedSensitiveFiles = listSensitiveWorkspaceFiles(cwd);
+  const capabilityIntake = inspectCapabilityIntake(cwd, reasonCodes);
+
+  const plannedChanges = [...hooks.plannedChanges];
+  const approvalRequiredChanges = [...hooks.approvalRequiredChanges, ...capabilityIntake.approvalRequiredChanges];
+  const blockedChanges = [...hooks.blockedChanges, ...capabilityIntake.blockedChanges];
+
+  for (const file of blockedSensitiveFiles) {
+    blockedChanges.push(file.summary);
+    pushReason(reasonCodes, file.code);
+  }
+
+  if (adapters.claudeMd === "missing") {
+    plannedChanges.push("Prepare a thin CLAUDE.md adapter pointer.");
+  } else if (adapters.claudeMd === "stale") {
+    plannedChanges.push("Refresh the thin CLAUDE.md adapter pointer.");
+  } else if (adapters.claudeMd === "user_content_preserved") {
+    approvalRequiredChanges.push("Preserve the existing CLAUDE.md content and add any Avorelo pointer only with review.");
+  }
+
+  if (adapters.agentsMd === "missing") {
+    plannedChanges.push("Prepare a thin AGENTS.md adapter pointer.");
+  } else if (adapters.agentsMd === "stale") {
+    plannedChanges.push("Refresh the thin AGENTS.md adapter pointer.");
+  } else if (adapters.agentsMd === "user_content_preserved") {
+    approvalRequiredChanges.push("Preserve the existing AGENTS.md content and add any Avorelo pointer only with review.");
+  }
+
+  if (adapters.codex === "missing" || adapters.codex === "stale") {
+    plannedChanges.push("Prepare or refresh the thin Codex config pointer.");
+  } else if (adapters.codex === "user_content_preserved") {
+    approvalRequiredChanges.push("Preserve the existing Codex config and review any pointer changes before applying them.");
+  }
+
+  let status = "ready";
+  if (packageTruthBlocked || blockedChanges.length > 0) {
+    status = "blocked";
+  } else if (
+    hooks.approvalRequired
+    || approvalRequiredChanges.length > 0
+    || plannedChanges.length > 0
+    || !firstValueVerified
+    || [adapters.claudeMd, adapters.agentsMd, adapters.codex, adapters.cursor].some((state) =>
+      state === "missing" || state === "stale" || state === "user_content_preserved"
+    )
+  ) {
+    status = "needs_attention";
+  }
+
+  const activationMode = blockedChanges.length > 0 || packageTruthBlocked
+    ? "blocked"
+    : approvalRequiredChanges.length > 0
+      ? "approval_required"
+      : plannedChanges.length > 0
+        ? "prepare_only"
+        : "check_only";
+
+  pushReason(reasonCodes, "prepare_only_mode", activationMode === "prepare_only");
+  pushReason(reasonCodes, "safe_next_action_available");
+
+  const safeNextAction = determineSafeNextAction(status, hooks, adapters, firstValueVerified, blockedChanges);
+  const integrationRefs = buildIntegrationRefs(cwd, firstValue.valueSignals === "pass");
+
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status,
+    redacted: true,
+    summary: {
+      readyItems: summarizeReadyItems(workspace, hooks, adapters, firstValueVerified),
+      missingItems: summarizeMissingItems(hooks, adapters, firstValue),
+      needsApproval: approvalRequiredChanges.length,
+      blockedItems: blockedChanges.length + (packageTruthBlocked ? 1 : 0),
+      firstValueVerified,
+      safeNextAction,
+    },
+    workspace,
+    activationPlan: {
+      mode: activationMode,
+      plannedChanges: uniq(plannedChanges),
+      approvalRequiredChanges: uniq(approvalRequiredChanges),
+      blockedChanges: uniq([
+        ...blockedChanges,
+        ...(packageTruthBlocked ? ["Public package or install-claim truth must stay published_verified before claiming activation readiness."] : []),
+      ]),
+      reasonCodes: uniq(reasonCodes),
+    },
+    hooks: {
+      checked: hooks.checked,
+      preToolReady: hooks.preToolReady,
+      postToolReady: hooks.postToolReady,
+      stopHookReady: hooks.stopHookReady,
+      hookPreviewAvailable: hooks.hookPreviewAvailable,
+      silentInstall: hooks.silentInstall,
+      approvalRequired: hooks.approvalRequired,
+      hookChanges: hooks.hookChanges,
+    },
+    adapters,
+    firstValue,
+    integrationRefs,
+    privacy: buildPrivacySection(),
+    claimSafety: buildClaimSafetySection(),
+  };
+}
+
+function writeAgentActivationReadiness(cwd, readiness) {
+  ensureCcoDirs(cwd);
+  safeWriteJson(cwd, LATEST_REPORT_REL, readiness);
+  return LATEST_REPORT_REL;
+}
+
+function generateAgentActivationReadiness(cwd = process.cwd(), options = {}) {
+  const readiness = buildAgentActivationReadiness(cwd, options);
+  const shouldWrite = options.write !== false;
+  const writtenPath = shouldWrite ? writeAgentActivationReadiness(cwd, readiness) : null;
+  return {
+    readiness,
+    writtenPath,
+  };
+}
+
+function formatAgentActivationReadinessText(readiness) {
+  const readyParts = [];
+  if (readiness.workspace.packageDetected) readyParts.push("local package");
+  if (readiness.firstValue.status === "pass") readyParts.push("status");
+  if (readiness.firstValue.home === "pass") readyParts.push("home");
+  if (readiness.firstValue.repair === "pass") readyParts.push("repair");
+  if (readiness.firstValue.nextRun === "pass") readyParts.push("next-run");
+  if (readiness.hooks.preToolReady && readiness.hooks.postToolReady && readiness.hooks.stopHookReady) readyParts.push("hooks");
+
+  const foundParts = [];
+  if (!readiness.hooks.preToolReady) foundParts.push("missing pre-tool hook");
+  if (!readiness.hooks.postToolReady) foundParts.push("missing post-tool hook");
+  if (!readiness.hooks.stopHookReady) foundParts.push("missing stop hook");
+  if (readiness.adapters.claudeMd === "stale") foundParts.push("stale CLAUDE.md adapter");
+  if (readiness.adapters.agentsMd === "stale") foundParts.push("stale AGENTS.md adapter");
+  if (readiness.adapters.codex === "stale") foundParts.push("stale Codex adapter");
+  if (foundParts.length === 0 && readiness.status === "no_data") {
+    foundParts.push("no repo or activation context available");
+  }
+
+  const reviewParts = [];
+  if (readiness.hooks.approvalRequired) reviewParts.push("hook installation requires approval");
+  if (readiness.activationPlan.reasonCodes.includes("capability_intake_review_required")) reviewParts.push("capability intake requires review");
+  if (readiness.adapters.claudeMd === "user_content_preserved") reviewParts.push("existing CLAUDE.md content was preserved");
+  if (readiness.adapters.agentsMd === "user_content_preserved") reviewParts.push("existing AGENTS.md content was preserved");
+  if (readiness.adapters.codex === "user_content_preserved") reviewParts.push("existing Codex config was preserved");
+  if (readiness.activationPlan.blockedChanges.length > 0) reviewParts.push("sensitive files stayed blocked");
+
+  const firstValueSummary = readiness.summary.firstValueVerified
+    ? "verified through local value surfaces"
+    : readiness.firstValue.home === "pass"
+      ? "Product Home receipt available"
+      : "still incomplete";
+
+  return [
+    "Avorelo Agent Readiness",
+    `Status: ${toTitleCaseStatus(readiness.status)}`,
+    `Ready: ${readyParts.length > 0 ? readyParts.join(", ") : "none"}`,
+    `Found: ${foundParts.length > 0 ? foundParts.join(", ") : "none"}`,
+    `For review: ${reviewParts.length > 0 ? reviewParts.join(", ") : "none"}`,
+    `First value: ${firstValueSummary}`,
+    `Next: ${readiness.summary.safeNextAction}`,
+  ].join("\n");
+}
+
+function formatAgentActivationStatusLine(readiness) {
+  if (!readiness) return "Agent readiness: unavailable";
+  const parts = [`Agent readiness: ${toTitleCaseStatus(readiness.status)}`];
+  if (readiness.hooks.approvalRequired) parts.push("hook approval required");
+  if (readiness.summary.firstValueVerified) parts.push("first value verified");
+  if (readiness.activationPlan.reasonCodes.includes("capability_intake_review_required")) parts.push("capability intake review required");
+  parts.push(`next: ${sanitizeText(readiness.summary.safeNextAction, 120)}`);
+  return parts.join(" · ");
+}
+
+module.exports = {
+  CONTRACT,
+  LATEST_REPORT_REL,
+  buildAgentActivationReadiness,
+  generateAgentActivationReadiness,
+  writeAgentActivationReadiness,
+  summarizeAgentReadiness,
+  formatAgentActivationReadinessText,
+  formatAgentActivationStatusLine,
+};