avorelo 0.1.0

package/scripts/lib/alpha-activation.js

@@ -0,0 +1,520 @@
+"use strict";
+
+// ── Alpha Activation ─────────────────────────────────────────────────────────
+//
+// Contract: avorelo.alphaActivation.v1
+//
+// Builds the first-run activation surface for a new user.
+// Reads existing surfaces (hooks, run, proof, ledger, feedback, support) and
+// aggregates them into a compact first-value view.
+//
+// Rules:
+// - No network calls, no cloud telemetry, no secrets
+// - No automatic hook apply (explicit user approval required)
+// - No deploy/destructive execution
+// - Default output is compact; debug exposes internals
+
+const fs = require("fs");
+const path = require("path");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.alphaActivation.v1";
+const SCHEMA_VERSION = 1;
+
+const RECEIPT_REL = ".claude/cco/orchestration/activation/latest-activation.json";
+const RECEIPT_DIR_REL = ".claude/cco/orchestration/activation";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// The avorelo installation root (where scripts/lib lives)
+const AVORELO_ROOT = path.resolve(__dirname, "../../");
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJsonRel(cwd, rel) {
+  return safeReadJson(path.join(cwd, rel));
+}
+
+// Check if an avorelo module exists (installed in AVORELO_ROOT, not target project)
+function avorModuleExists(rel) {
+  return fs.existsSync(path.join(AVORELO_ROOT, rel));
+}
+
+// ── Check: project profile ────────────────────────────────────────────────────
+
+function checkProjectProfile(cwd) {
+  const profile = safeReadJsonRel(cwd, ".claude/cco/orchestration/project-profile/latest-profile.json");
+  if (!profile) {
+    return { id: "project_profile", status: "warn", message: "No project profile found. Run `avorelo project-profile --json` to create one." };
+  }
+  return { id: "project_profile", status: "pass", message: `Project profile detected (${profile.projectType || "unknown"} / ${profile.riskLevel || "unknown"} risk).` };
+}
+
+// ── Check: safe run ───────────────────────────────────────────────────────────
+
+function checkSafeRun(cwd) {
+  const hasBin = avorModuleExists("bin/avorelo") || avorModuleExists("bin/avorelo.js");
+  if (!hasBin) {
+    return { id: "safe_run", status: "fail", message: "Avorelo binary not found. Run `npm install` or check bin/avorelo." };
+  }
+  const hasModule = avorModuleExists("scripts/lib/safe-run-controller.js");
+  if (!hasModule) {
+    return { id: "safe_run", status: "fail", message: "safe-run-controller.js not found." };
+  }
+  return { id: "safe_run", status: "pass", message: "Safe run available." };
+}
+
+// ── Check: smart route ────────────────────────────────────────────────────────
+
+function checkSmartRoute(cwd) {
+  if (!avorModuleExists("scripts/lib/smart-work-routing.js")) {
+    return { id: "smart_route", status: "fail", message: "smart-work-routing.js not found." };
+  }
+  return { id: "smart_route", status: "pass", message: "Smart route available." };
+}
+
+// ── Check: hooks ─────────────────────────────────────────────────────────────
+
+function checkHooks(cwd) {
+  const baselinePath = path.join(cwd, ".claude/cco/orchestration/hook-baseline/latest-baseline.json");
+  const applyPath = path.join(cwd, ".claude/cco/orchestration/hook-apply/latest-apply.json");
+  const doctorPath = path.join(cwd, ".claude/cco/orchestration/hook-apply/latest-doctor.json");
+
+  const baseline = safeReadJson(baselinePath);
+  const apply = safeReadJson(applyPath);
+  const doctor = safeReadJson(doctorPath);
+
+  const hookModExists = avorModuleExists("scripts/lib/hook-apply.js");
+
+  if (!hookModExists) {
+    return {
+      id: "hook_status",
+      status: "fail",
+      message: "hook-apply.js not found.",
+      applied: false,
+      doctorPass: false,
+      nextAction: "Check hook-apply.js exists."
+    };
+  }
+
+  const applied = apply && apply.hooksApplied === true;
+  const doctorPass = doctor && (doctor.summary && doctor.summary.fail === 0);
+
+  if (!baseline) {
+    return {
+      id: "hook_status",
+      status: "warn",
+      message: "Hook baseline not generated. Run `avorelo hooks --json` to generate baseline.",
+      applied: false,
+      doctorPass: false,
+      nextAction: "Run: avorelo hooks --json"
+    };
+  }
+
+  if (!applied) {
+    return {
+      id: "hook_status",
+      status: "warn",
+      message: "Hooks not yet applied. Run `avorelo hooks apply --dry-run` to preview, then `--yes` to apply with approval.",
+      applied: false,
+      doctorPass: doctorPass || false,
+      nextAction: "Run: avorelo hooks apply --dry-run"
+    };
+  }
+
+  return {
+    id: "hook_status",
+    status: "pass",
+    message: `Hooks applied. Doctor: ${doctorPass ? "pass" : "warn"}.`,
+    applied: true,
+    doctorPass: doctorPass || false,
+    nextAction: null
+  };
+}
+
+// ── Check: proof ─────────────────────────────────────────────────────────────
+
+function checkProof(cwd) {
+  const hasProofMod = avorModuleExists("scripts/lib/seamless-reality-gate.js");
+
+  const existingPaths = [
+    ".claude/cco/orchestration/seamless-outcome/latest-reality-gate.json",
+    ".claude/cco/orchestration/seamless-outcome/latest-value-summary.json",
+  ];
+  const anyExists = existingPaths.some((rel) => fs.existsSync(path.join(cwd, rel)));
+
+  if (!hasProofMod) {
+    return { id: "proof_status", status: "fail", message: "seamless-reality-gate.js not found." };
+  }
+  if (!anyExists) {
+    return { id: "proof_status", status: "warn", message: "No proof artifacts yet. Run `avorelo proof` to generate.", nextAction: "Run: avorelo proof" };
+  }
+  return { id: "proof_status", status: "pass", message: "Proof artifacts available." };
+}
+
+// ── Check: feedback ───────────────────────────────────────────────────────────
+
+function checkFeedback(cwd) {
+  const feedbackDir = path.join(cwd, ".claude/cco/feedback");
+  const hasModule = avorModuleExists("scripts/lib/alpha-feedback.js");
+  const hasDir = fs.existsSync(feedbackDir);
+
+  if (!hasModule) {
+    return { id: "feedback_status", status: "warn", message: "Feedback capture not available.", nextAction: "Add alpha-feedback.js" };
+  }
+
+  let count = 0;
+  if (hasDir) {
+    try {
+      count = fs.readdirSync(feedbackDir).filter((f) => f.endsWith(".json")).length;
+    } catch {}
+  }
+  return {
+    id: "feedback_status",
+    status: "pass",
+    message: `Feedback capture available. ${count} feedback item(s).`,
+    feedbackCount: count,
+    nextAction: count === 0 ? "Run: avorelo feedback add --source dogfood --summary \"...\"" : null
+  };
+}
+
+// ── Check: token efficiency ───────────────────────────────────────────────────
+
+function checkTokenEfficiency(cwd) {
+  const evidencePath = path.join(cwd, ".claude/cco/orchestration/token-efficiency/latest-evidence.json");
+  const qualityGatePath = path.join(cwd, ".claude/cco/orchestration/token-efficiency/latest-quality-gate.json");
+  const hasEvidence = fs.existsSync(evidencePath);
+  const hasGate = fs.existsSync(qualityGatePath);
+  const hasModule = avorModuleExists("scripts/lib/token-efficiency-evidence.js");
+
+  if (!hasModule) {
+    return { id: "token_efficiency_status", status: "warn", message: "Token efficiency hardening not available.", nextAction: "Token efficiency is part of PR #143." };
+  }
+  if (!hasEvidence && !hasGate) {
+    return {
+      id: "token_efficiency_status",
+      status: "warn",
+      message: "Token efficiency evidence not yet generated. Run a task to generate.",
+      nextAction: "Run: avorelo run \"<task>\" --prepare-only --json"
+    };
+  }
+  let verdict = null;
+  if (hasGate) {
+    try {
+      const gate = JSON.parse(fs.readFileSync(qualityGatePath, "utf8"));
+      verdict = gate.verdict;
+      if (gate.status === "fail") {
+        return { id: "token_efficiency_status", status: "warn", message: `Token context quality gate: ${gate.verdict}. Review: ${gate.nextAction}`, verdict };
+      }
+    } catch {}
+  }
+  return {
+    id: "token_efficiency_status",
+    status: "pass",
+    message: `Token efficiency hardening active.${verdict ? ` Quality gate: ${verdict}.` : ""}`,
+    verdict: verdict || null,
+    nextAction: null
+  };
+}
+
+// ── Check: support bundle ─────────────────────────────────────────────────────
+
+function checkSupportBundle(cwd) {
+  const bundlePath = path.join(cwd, ".claude/cco/support/latest-support-bundle.json");
+  const hasModule = avorModuleExists("scripts/lib/support-bundle.js");
+  const hasBundle = fs.existsSync(bundlePath);
+
+  if (!hasModule) {
+    return { id: "support_status", status: "warn", message: "Support bundle not available.", nextAction: "Add support-bundle.js" };
+  }
+  return {
+    id: "support_status",
+    status: hasBundle ? "pass" : "warn",
+    message: hasBundle ? "Support bundle available (redacted)." : "Support bundle module available. Run `avorelo support-bundle` to generate.",
+    nextAction: hasBundle ? null : "Run: avorelo support-bundle --json"
+  };
+}
+
+// ── First-value path selection ─────────────────────────────────────────────────
+
+function buildFirstValuePath(cwd, checks) {
+  const hookCheck = checks.find((c) => c.id === "hook_status") || {};
+  const profileCheck = checks.find((c) => c.id === "project_profile") || {};
+  const proofCheck = checks.find((c) => c.id === "proof_status") || {};
+  const safeRunCheck = checks.find((c) => c.id === "safe_run") || {};
+
+  // Priority: hooks not applied → guide hook apply (low risk, high value)
+  if (hookCheck.status === "warn" && !hookCheck.applied) {
+    return {
+      type: "hook_readiness",
+      label: "Preview and apply lifecycle hooks",
+      command: "avorelo hooks apply --dry-run",
+      why: "Hook lifecycle automation reduces manual oversight. Dry-run first, apply with --yes after review.",
+      riskLevel: "low",
+      manualStepsAvoided: 1,
+      proofPrepared: false,
+      proofRun: false,
+      riskBlocked: false,
+      caveats: ["Requires explicit --yes to apply. No auto-apply."]
+    };
+  }
+
+  // Profile missing → safe project inspection
+  if (profileCheck.status !== "pass") {
+    return {
+      type: "project_inspection",
+      label: "Generate project profile",
+      command: "avorelo project-profile --json",
+      why: "Understanding project type, risk level, and safe boundaries before first run.",
+      riskLevel: "low",
+      manualStepsAvoided: 1,
+      proofPrepared: false,
+      proofRun: false,
+      riskBlocked: false,
+      caveats: []
+    };
+  }
+
+  // Proof missing → run proof
+  if (proofCheck.status === "warn") {
+    return {
+      type: "proof_generation",
+      label: "Generate safety and outcome proof",
+      command: "avorelo proof",
+      why: "Proof shows current safety posture and outcome state. Low risk, high clarity.",
+      riskLevel: "low",
+      manualStepsAvoided: 1,
+      proofPrepared: true,
+      proofRun: false,
+      riskBlocked: false,
+      caveats: []
+    };
+  }
+
+  // Safe run prepare-only
+  if (safeRunCheck.status === "pass") {
+    return {
+      type: "safe_run_prepare",
+      label: "Prepare a safe run for a task",
+      command: "avorelo run \"<your task description>\" --prepare-only",
+      why: "Builds smart route, execution packet, and worker handoff without executing. Shows what Avorelo would do.",
+      riskLevel: "low",
+      manualStepsAvoided: 2,
+      proofPrepared: true,
+      proofRun: false,
+      riskBlocked: false,
+      caveats: ["Use --prepare-only to inspect before running"]
+    };
+  }
+
+  // Fallback: status check
+  return {
+    type: "status_check",
+    label: "Check current Avorelo status",
+    command: "avorelo status --json",
+    why: "Understand current project state before taking any action.",
+    riskLevel: "low",
+    manualStepsAvoided: 0,
+    proofPrepared: false,
+    proofRun: false,
+    riskBlocked: false,
+    caveats: []
+  };
+}
+
+// ── Activation stage ──────────────────────────────────────────────────────────
+
+function computeActivationStage(checks, firstValuePath) {
+  const allPass = checks.every((c) => c.status === "pass");
+  const anyFail = checks.some((c) => c.status === "fail");
+  const hasFeedback = checks.find((c) => c.id === "feedback_status" && c.feedbackCount > 0);
+
+  if (anyFail) return "not_started";
+  if (!allPass) return "checked";
+  if (hasFeedback) return "feedback_ready";
+  if (firstValuePath.type !== "status_check") return "first_value_ready";
+  return "checked";
+}
+
+// ── Status rollup ─────────────────────────────────────────────────────────────
+
+function computeStatus(checks) {
+  if (checks.some((c) => c.status === "fail")) return "blocked";
+  if (checks.some((c) => c.status === "warn")) return "partial";
+  return "ready";
+}
+
+// ── Next action ───────────────────────────────────────────────────────────────
+
+function computeNextAction(status, checks, firstValuePath, hookCheck) {
+  if (status === "blocked") {
+    const failCheck = checks.find((c) => c.status === "fail");
+    return `Fix: ${failCheck ? failCheck.message : "see checks above"}`;
+  }
+  if (firstValuePath) {
+    return `Run: ${firstValuePath.command}`;
+  }
+  return "Run: avorelo status --json";
+}
+
+// ── Build activation plan ─────────────────────────────────────────────────────
+
+function buildActivationPlan(cwd, options = {}) {
+  const checks = [
+    checkProjectProfile(cwd),
+    checkSafeRun(cwd),
+    checkSmartRoute(cwd),
+    checkHooks(cwd),
+    checkProof(cwd),
+    checkFeedback(cwd),
+    checkSupportBundle(cwd),
+    checkTokenEfficiency(cwd),
+  ];
+
+  const hookCheck = checks.find((c) => c.id === "hook_status") || {};
+  const status = computeStatus(checks);
+  const firstValuePath = buildFirstValuePath(cwd, checks);
+  const activationStage = computeActivationStage(checks, firstValuePath);
+  const nextAction = computeNextAction(status, checks, firstValuePath, hookCheck);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    status,
+    activationStage,
+    checks,
+    firstValuePath,
+    hookStatus: {
+      applied: hookCheck.applied || false,
+      doctorPass: hookCheck.doctorPass || false,
+      nextAction: hookCheck.nextAction || null
+    },
+    proofStatus: {
+      available: checks.find((c) => c.id === "proof_status")?.status === "pass",
+    },
+    feedbackStatus: {
+      available: checks.find((c) => c.id === "feedback_status")?.status === "pass",
+      count: checks.find((c) => c.id === "feedback_status")?.feedbackCount || 0,
+    },
+    supportStatus: {
+      available: checks.find((c) => c.id === "support_status")?.status === "pass",
+    },
+    tokenEfficiencyStatus: {
+      available: checks.find((c) => c.id === "token_efficiency_status")?.status === "pass",
+      verdict: checks.find((c) => c.id === "token_efficiency_status")?.verdict || null,
+    },
+    nextAction,
+    redacted: true,
+  };
+}
+
+// ── Run activation check ──────────────────────────────────────────────────────
+
+function runActivationCheck(cwd, options = {}) {
+  const plan = buildActivationPlan(cwd, options);
+  return plan;
+}
+
+// ── Write activation receipt ──────────────────────────────────────────────────
+
+function writeActivationReceipt(cwd, receipt) {
+  try {
+    ensureCcoDirs(cwd);
+    const dirAbs = path.join(cwd, RECEIPT_DIR_REL);
+    if (!fs.existsSync(dirAbs)) fs.mkdirSync(dirAbs, { recursive: true });
+    const receiptAbs = path.join(cwd, RECEIPT_REL);
+    fs.writeFileSync(receiptAbs, JSON.stringify(receipt, null, 2), "utf8");
+    return receiptAbs;
+  } catch {
+    return null;
+  }
+}
+
+// ── Build activation surface ──────────────────────────────────────────────────
+
+function buildActivationSurface(cwd, options = {}) {
+  const receipt = runActivationCheck(cwd, options);
+  const written = writeActivationReceipt(cwd, receipt);
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "alpha_activation_checked",
+      status: receipt.status,
+      activationStage: receipt.activationStage,
+    });
+  } catch {}
+
+  return { ...receipt, artifactPath: written ? RECEIPT_REL : null };
+}
+
+// ── Format compact text ───────────────────────────────────────────────────────
+
+function formatActivationText(receipt, options = {}) {
+  const lines = [];
+  const status = receipt.status || "unknown";
+  const statusLabel = status === "ready" ? "ready" : status === "partial" ? "partial" : "blocked";
+
+  lines.push(`Avorelo activation: ${statusLabel}`);
+  lines.push("");
+
+  // Checks summary
+  const pass = receipt.checks ? receipt.checks.filter((c) => c.status === "pass").length : 0;
+  const warn = receipt.checks ? receipt.checks.filter((c) => c.status === "warn").length : 0;
+  const fail = receipt.checks ? receipt.checks.filter((c) => c.status === "fail").length : 0;
+  lines.push(`Checks: ${pass} pass  ${warn} warn  ${fail} fail`);
+
+  // Readiness
+  lines.push("");
+  lines.push("Ready:");
+  if (receipt.checks) {
+    receipt.checks.filter((c) => c.status === "pass").forEach((c) => {
+      lines.push(`  + ${c.message}`);
+    });
+    receipt.checks.filter((c) => c.status !== "pass").forEach((c) => {
+      const icon = c.status === "fail" ? "✗" : "~";
+      lines.push(`  ${icon} ${c.message}`);
+    });
+  }
+
+  // First value
+  if (receipt.firstValuePath) {
+    const fv = receipt.firstValuePath;
+    lines.push("");
+    lines.push("First value:");
+    lines.push(`  Run: ${fv.command}`);
+    if (fv.why) lines.push(`  Why: ${fv.why}`);
+  }
+
+  // Protected
+  lines.push("");
+  lines.push("Protected:");
+  lines.push("  Deploy/destructive/secrets blocked by PreToolUse guard.");
+  if (!receipt.hookStatus?.applied) {
+    lines.push("  Hooks not yet applied — no lifecycle automation until you approve.");
+  }
+
+  // Next
+  lines.push("");
+  lines.push(`Next: ${receipt.nextAction || "Run: avorelo status --json"}`);
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  RECEIPT_REL,
+  buildActivationPlan,
+  runActivationCheck,
+  writeActivationReceipt,
+  buildActivationSurface,
+  formatActivationText,
+};