avorelo 0.1.0 → 0.2.0

package/scripts/lib/lifecycle-hooks.js

@@ -1,802 +0,0 @@
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-
-const CONTRACT = "avorelo.lifecycleHookHandler.v1";
-const SCHEMA_VERSION = 1;
-
-const HOOKS_DIR_REL = ".claude/cco/orchestration/lifecycle-hooks";
-
-const DESTRUCTIVE_KEYWORDS = Object.freeze([
-  "deploy",
-  "publish",
-  "delete database",
-  "drop table",
-  "rm -rf",
-  "git clean",
-  "force push",
-  "reset --hard",
-  "secret",
-  "password",
-  "api key",
-  "prod",
-  "production",
-  "staging push",
-]);
-
-function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true });
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function makeHandlerId() {
-  return `lh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-function safeWriteJson(filePath, data) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
-}
-
-function safeReadJson(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function containsDestructiveIntent(text) {
-  if (!text) return false;
-  const lower = text.toLowerCase();
-  return DESTRUCTIVE_KEYWORDS.some((kw) => lower.includes(kw));
-}
-
-function writeReceipt(cwd, event, result) {
-  const eventSlug = event.toLowerCase().replace(/[^a-z0-9]/g, "-");
-  const relPath = `${HOOKS_DIR_REL}/latest-${eventSlug}.json`;
-  const absPath = path.join(cwd, relPath);
-  safeWriteJson(absPath, result);
-  return relPath;
-}
-
-function writeLedgerEntry(cwd, event, result) {
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, {
-      eventName: "lifecycle_hook_handler_invoked",
-      payload: {
-        event,
-        handlerId: result.handlerId,
-        status: result.status,
-        blocking: result.blocking,
-        reasonCodes: result.reasonCodes || [],
-      },
-    });
-  } catch {
-    // product-learning not available — non-fatal
-  }
-}
-
-// ── SessionStart ─────────────────────────────────────────────────────────────
-
-function handleSessionStart(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "SessionStart",
-    blocking: false,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    summary: null,
-    redacted: true,
-  };
-
-  // Load project profile (cheap, local)
-  try {
-    const profilePath = path.join(cwd, ".claude/cco/orchestration/project-profile/latest-profile.json");
-    const profile = safeReadJson(profilePath);
-    if (profile) {
-      result.actions.push({ action: "project_profile_loaded", status: "ok" });
-      result.projectProfile = {
-        framework: profile.framework || null,
-        packageManager: profile.packageManager || null,
-        allowedActions: profile.allowedActions ? profile.allowedActions.slice(0, 5) : [],
-        redacted: true,
-      };
-    } else {
-      result.actions.push({ action: "project_profile_loaded", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "project_profile_loaded", status: "error" });
-  }
-
-  // Workspace hygiene summary (status only, no heavy scan)
-  try {
-    const hygienePath = path.join(cwd, ".claude/cco/orchestration/ai-workspace-hygiene/latest-report.json");
-    const hygiene = safeReadJson(hygienePath);
-    if (hygiene) {
-      result.actions.push({ action: "workspace_hygiene_checked", status: "ok" });
-      result.workspaceStatus = {
-        status: hygiene.status || "unknown",
-        redacted: true,
-      };
-    } else {
-      result.actions.push({ action: "workspace_hygiene_checked", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "workspace_hygiene_checked", status: "skipped" });
-  }
-
-  // Auto-inject next-run context if available and not expired
-  try {
-    const { loadNextRunContext, buildCompactContextText, updateNextRunContextStatus, emitNextRunContextEvent } = require("./next-run-context");
-    const nrc = loadNextRunContext(cwd);
-    if (nrc && nrc.status !== "not_available" && nrc.status !== "expired" && nrc.status !== "insufficient_evidence" && nrc.status !== "error") {
-      const compactText = buildCompactContextText(nrc);
-      result.actions.push({ action: "next_run_context_loaded", status: "ok" });
-      result.nextRunContext = {
-        status: nrc.status,
-        defaultsCount: (nrc.appliedDefaults || []).length,
-        decisionsCount: nrc.activeDecisionCount || 0,
-        risksCount: nrc.activeRiskCount || 0,
-        sourceRunFingerprint: nrc.sourceRunFingerprint,
-        compactText: compactText || null,
-        artifactPath: ".claude/cco/state/next-run-context.json",
-        redacted: true,
-      };
-      // Mark as injected if it was applied (session-start is the real injection point)
-      if (nrc.status === "applied") {
-        const now = nowIso();
-        updateNextRunContextStatus(cwd, "injected", { injectedAt: now });
-        emitNextRunContextEvent(cwd, { ...nrc, status: "injected", injectedSurface: "session_start" }, "next_run_context.injected");
-        result.nextRunContext.status = "injected";
-      }
-    } else {
-      result.actions.push({ action: "next_run_context_loaded", status: nrc ? nrc.status : "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "next_run_context_loaded", status: "skipped" });
-  }
-
-  result.summary = "Session state prepared. Project profile, workspace status, and next-run context loaded.";
-  result.safeNextAction = "Continue session. Avorelo has prepared project/workspace state.";
-  result.reasonCodes = ["SESSION_STATE_PREPARED", "NON_BLOCKING"];
-
-  const receiptPath = writeReceipt(cwd, "SessionStart", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "SessionStart", result);
-
-  return result;
-}
-
-// ── UserPromptSubmit ──────────────────────────────────────────────────────────
-
-function handleUserPromptSubmit(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-  const taskText = input.prompt || input.taskText || input.task || "";
-
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "UserPromptSubmit",
-    blocking: false,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    decision: "allow",
-    summary: null,
-    redacted: true,
-  };
-
-  // Check for prohibited intent
-  if (containsDestructiveIntent(taskText)) {
-    result.blocking = true;
-    result.decision = "block";
-    result.status = "blocked";
-    result.summary = "Prompt contains prohibited intent (destructive/deploy/secrets/prod). Blocked before routing.";
-    result.safeNextAction = "Rephrase the task to avoid destructive, deployment, or secrets-related actions.";
-    result.reasonCodes = ["BLOCKING_PROHIBITED_INTENT", "DESTRUCTIVE_KEYWORDS_DETECTED"];
-    result.actions.push({ action: "prompt_classified", status: "blocked", reason: "prohibited_intent" });
-    const receiptPath = writeReceipt(cwd, "UserPromptSubmit", result);
-    result.receiptPath = receiptPath;
-    writeLedgerEntry(cwd, "UserPromptSubmit", result);
-    try {
-      const { appendProductLearningEvent } = require("./product-learning-events");
-      appendProductLearningEvent(cwd, {
-        eventName: "lifecycle_pre_tool_use_blocked",
-        payload: { event: "UserPromptSubmit", reason: "prohibited_intent", redacted: true },
-      });
-    } catch {}
-    return result;
-  }
-
-  result.actions.push({ action: "prompt_classified", status: "ok", reason: "safe" });
-
-  // Build safe-run plan (prepare-only, no execution)
-  if (taskText) {
-    try {
-      const { buildSafeRunPlan } = require("./safe-run-controller");
-      const plan = buildSafeRunPlan(cwd, taskText, { prepareOnly: true });
-      result.actions.push({ action: "safe_run_plan_built", status: "ok" });
-      result.safeRunPlan = {
-        runId: plan.runId || null,
-        taskType: plan.taskType || null,
-        riskLevel: plan.riskLevel || null,
-        steps: plan.steps ? plan.steps.length : 0,
-        redacted: true,
-      };
-    } catch {
-      result.actions.push({ action: "safe_run_plan_built", status: "skipped" });
-    }
-
-    // Smart-route
-    try {
-      const { classifyTaskForRouting, decideExecutionPath } = require("./smart-work-routing");
-      const classification = classifyTaskForRouting(taskText);
-      result.actions.push({ action: "smart_route_classified", status: "ok" });
-      result.routeClassification = {
-        taskType: classification.taskType || null,
-        riskLevel: classification.riskLevel || null,
-        redacted: true,
-      };
-    } catch {
-      result.actions.push({ action: "smart_route_classified", status: "skipped" });
-    }
-
-    // Compile execution packet (prepare only)
-    try {
-      const { compileExecutionPacket } = require("./execution-packet");
-      if (typeof compileExecutionPacket === "function") {
-        const packet = compileExecutionPacket(cwd, { task: taskText, prepareOnly: true });
-        result.actions.push({ action: "execution_packet_compiled", status: "ok" });
-        result.executionPacket = {
-          packetId: packet.packetId || null,
-          mode: packet.mode || null,
-          riskLevel: packet.riskLevel || null,
-          redacted: true,
-        };
-      }
-    } catch {
-      result.actions.push({ action: "execution_packet_compiled", status: "skipped" });
-    }
-  }
-
-  result.summary = "Task classified and safe run plan prepared. No code modified.";
-  result.safeNextAction = "Continue with the prepared execution plan.";
-  result.reasonCodes = ["NON_BLOCKING", "TASK_CLASSIFIED", "SAFE_RUN_PLAN_PREPARED"];
-
-  const receiptPath = writeReceipt(cwd, "UserPromptSubmit", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "UserPromptSubmit", result);
-
-  return result;
-}
-
-// ── PreToolUse ────────────────────────────────────────────────────────────────
-
-const BLOCKED_TOOL_PATTERNS = Object.freeze([
-  /deploy/i,
-  /publish/i,
-  /drop[_\s]table/i,
-  /delete[_\s]database/i,
-  /rm\s+-rf/i,
-  /git\s+clean/i,
-  /force[_\s]push/i,
-  /reset\s+--hard/i,
-]);
-
-const BLOCKED_INPUT_PATTERNS = Object.freeze([
-  { key: "command", patterns: [/deploy/i, /publish/i, /rm\s+-rf/i, /git\s+clean/i, /reset\s+--hard/i, /force.*push/i] },
-  { key: "file_path", patterns: [/\.env$/, /\.pem$/, /\.key$/, /secrets?\./i] },
-  { key: "path", patterns: [/\.env$/, /\.pem$/, /\.key$/, /secrets?\./i] },
-]);
-
-function evaluateToolSafety(toolName, toolInput) {
-  const toolStr = String(toolName || "").toLowerCase();
-
-  // Check tool name for blocked patterns
-  for (const pat of BLOCKED_TOOL_PATTERNS) {
-    if (pat.test(toolStr)) {
-      return {
-        decision: "block",
-        reason: `Tool name matches blocked pattern: ${pat}`,
-        reasonCode: "TOOL_NAME_BLOCKED",
-      };
-    }
-  }
-
-  // Check input fields
-  const inputObj = typeof toolInput === "object" && toolInput !== null ? toolInput : {};
-  for (const { key, patterns } of BLOCKED_INPUT_PATTERNS) {
-    const val = String(inputObj[key] || "");
-    if (!val) continue;
-    for (const pat of patterns) {
-      if (pat.test(val)) {
-        return {
-          decision: "block",
-          reason: `Input field '${key}' matches blocked pattern`,
-          reasonCode: "INPUT_FIELD_BLOCKED",
-        };
-      }
-    }
-  }
-
-  // Check for secrets in input values
-  const inputStr = JSON.stringify(inputObj).toLowerCase();
-  if (/password|api_key|apikey|secret|token/.test(inputStr)) {
-    return {
-      decision: "warn",
-      reason: "Input may reference sensitive fields (secrets/tokens). Review before proceeding.",
-      reasonCode: "SENSITIVE_INPUT_DETECTED",
-    };
-  }
-
-  return { decision: "allow", reason: "Tool and input appear safe.", reasonCode: "SAFE_TOOL_INPUT" };
-}
-
-function handlePreToolUse(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-  const toolName = input.tool_name || input.toolName || input.tool || "";
-  const toolInput = input.tool_input || input.toolInput || input.input || {};
-
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "PreToolUse",
-    blocking: true,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    decision: "allow",
-    toolName,
-    summary: null,
-    redacted: true,
-  };
-
-  const safety = evaluateToolSafety(toolName, toolInput);
-  result.actions.push({ action: "tool_safety_evaluated", status: safety.decision, reason: safety.reason });
-  result.decision = safety.decision;
-  result.reasonCode = safety.reasonCode;
-
-  // MCP governance: apply least-privilege policy if tool signal present
-  if (result.decision !== "block") {
-    try {
-      const { decideMcpPreToolUse, writeMcpPreToolUseDecision } = require("./mcp-enforcement");
-      const mcpDecision = decideMcpPreToolUse(cwd, input, options);
-      writeMcpPreToolUseDecision(cwd, mcpDecision);
-      result.actions.push({ action: "mcp_governance_evaluated", status: mcpDecision.decision });
-      if (mcpDecision.decision === "block" || mcpDecision.decision === "approval_required") {
-        if (result.decision !== "block") {
-          result.decision = mcpDecision.decision === "block" ? "block" : "warn";
-          result.reasonCode = "MCP_GOVERNANCE_DECISION";
-          result.mcpGovernance = {
-            decision: mcpDecision.decision,
-            reasonCodes: (mcpDecision.reasonCodes || []).slice(0, 5),
-            safeNextAction: mcpDecision.safeNextAction,
-          };
-        }
-      }
-    } catch {
-      result.actions.push({ action: "mcp_governance_evaluated", status: "skipped" });
-    }
-  }
-
-  if (result.decision === "block") {
-    result.status = "blocked";
-    result.summary = `Tool use blocked: ${safety.reason}`;
-    result.safeNextAction = result.mcpGovernance?.safeNextAction || "Use a safe, whitelisted tool. Avoid destructive/deploy/secrets/prod actions.";
-    result.reasonCodes = ["BLOCKING_HOOK", "DESTRUCTIVE_OR_SENSITIVE_BLOCKED", safety.reasonCode];
-
-    try {
-      const { appendProductLearningEvent } = require("./product-learning-events");
-      appendProductLearningEvent(cwd, {
-        eventName: "lifecycle_pre_tool_use_blocked",
-        payload: { event: "PreToolUse", toolName, reasonCode: safety.reasonCode, redacted: true },
-      });
-    } catch {}
-  } else if (safety.decision === "warn") {
-    result.status = "warn";
-    result.summary = `Tool use allowed with warning: ${safety.reason}`;
-    result.safeNextAction = "Proceed with caution. Verify input does not contain secrets or sensitive data.";
-    result.reasonCodes = ["BLOCKING_HOOK", "ALLOWED_WITH_WARNING", safety.reasonCode];
-  } else {
-    result.status = "ok";
-    result.summary = "Tool use allowed.";
-    result.safeNextAction = null;
-    result.reasonCodes = ["BLOCKING_HOOK", "ALLOWED", safety.reasonCode];
-  }
-
-  // Enforce packet boundaries if packet exists
-  try {
-    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
-    const packet = safeReadJson(packetPath);
-    if (packet && packet.blockedScope && Array.isArray(packet.blockedScope)) {
-      const toolLower = toolName.toLowerCase();
-      const blocked = packet.blockedScope.some((s) => toolLower.includes(String(s).toLowerCase()));
-      if (blocked && result.decision !== "block") {
-        result.decision = "block";
-        result.status = "blocked";
-        result.summary = `Tool '${toolName}' is in the blocked scope of the current execution packet.`;
-        result.safeNextAction = "Review the execution packet blocked scope. This action is not allowed for the current task.";
-        result.reasonCodes = ["BLOCKING_HOOK", "PACKET_BOUNDARY_ENFORCED"];
-        result.actions.push({ action: "packet_boundary_checked", status: "blocked", reason: "in_blocked_scope" });
-      } else {
-        result.actions.push({ action: "packet_boundary_checked", status: "ok" });
-      }
-    } else {
-      result.actions.push({ action: "packet_boundary_checked", status: "no_packet" });
-    }
-  } catch {
-    result.actions.push({ action: "packet_boundary_checked", status: "skipped" });
-  }
-
-  const receiptPath = writeReceipt(cwd, "PreToolUse", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "PreToolUse", result);
-
-  return result;
-}
-
-// ── PostToolUse ───────────────────────────────────────────────────────────────
-
-function handlePostToolUse(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-  const toolName = input.tool_name || input.toolName || input.tool || "";
-
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "PostToolUse",
-    blocking: false,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    summary: null,
-    redacted: true,
-  };
-
-  // Record tool result summary (no raw output)
-  result.actions.push({
-    action: "tool_result_recorded",
-    status: "ok",
-    toolName,
-    note: "Raw tool output not stored. Status and metadata only.",
-  });
-
-  // Write product-learning event
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, {
-      eventName: "lifecycle_hook_handler_invoked",
-      payload: {
-        event: "PostToolUse",
-        handlerId,
-        toolName,
-        status: "ok",
-        redacted: true,
-      },
-    });
-    result.actions.push({ action: "product_learning_event_written", status: "ok" });
-  } catch {
-    result.actions.push({ action: "product_learning_event_written", status: "skipped" });
-  }
-
-  result.summary = `Tool '${toolName}' post-use recorded. Ledger and product-learning updated.`;
-  result.safeNextAction = null;
-  result.reasonCodes = ["NON_BLOCKING", "LEDGER_UPDATED", "PRODUCT_LEARNING_RECORDED"];
-
-  const receiptPath = writeReceipt(cwd, "PostToolUse", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "PostToolUse", result);
-
-  return result;
-}
-
-// ── Stop ─────────────────────────────────────────────────────────────────────
-
-function handleStop(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "Stop",
-    blocking: true,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    decision: "allow",
-    proofRequired: false,
-    proofFound: false,
-    summary: null,
-    redacted: true,
-  };
-
-  // Check execution packet for proof requirements
-  let proofRequired = false;
-  try {
-    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
-    const packet = safeReadJson(packetPath);
-    if (packet) {
-      proofRequired = !!(packet.proofRequired || (packet.requirements && packet.requirements.proofRequired));
-      result.actions.push({ action: "execution_packet_checked", status: "ok", proofRequired });
-    } else {
-      result.actions.push({ action: "execution_packet_checked", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "execution_packet_checked", status: "skipped" });
-  }
-
-  // Check safe-run result for proof
-  let proofFound = false;
-  try {
-    const runPath = path.join(cwd, ".claude/cco/orchestration/safe-run/latest-run.json");
-    const run = safeReadJson(runPath);
-    if (run) {
-      proofFound = !!(run.proofSummary || run.status === "completed" || run.proofGenerated);
-      result.actions.push({ action: "safe_run_checked", status: "ok", proofFound });
-    } else {
-      result.actions.push({ action: "safe_run_checked", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "safe_run_checked", status: "skipped" });
-  }
-
-  result.proofRequired = proofRequired;
-  result.proofFound = proofFound;
-
-  if (proofRequired && !proofFound) {
-    result.decision = "block";
-    result.status = "blocked";
-    result.summary = "Proof required by execution packet but not found. Cannot stop until proof is generated.";
-    result.safeNextAction = "Run `avorelo run <task>` to generate proof, then stop.";
-    result.reasonCodes = ["BLOCKING_HOOK", "PROOF_REQUIRED", "PROOF_MISSING"];
-
-    try {
-      const { appendProductLearningEvent } = require("./product-learning-events");
-      appendProductLearningEvent(cwd, {
-        eventName: "lifecycle_stop_proof_required",
-        payload: { event: "Stop", proofRequired, proofFound, redacted: true },
-      });
-    } catch {}
-  } else {
-    result.decision = "allow";
-    result.status = "ok";
-    if (proofRequired && proofFound) {
-      result.summary = "Proof found. Stop allowed.";
-    } else {
-      result.summary = "Proof not required for this task. Stop allowed.";
-    }
-    result.safeNextAction = null;
-    result.reasonCodes = ["BLOCKING_HOOK", "STOP_ALLOWED"];
-  }
-
-  const receiptPath = writeReceipt(cwd, "Stop", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "Stop", result);
-
-  return result;
-}
-
-// ── SessionEnd ────────────────────────────────────────────────────────────────
-
-function handleSessionEnd(cwd, input = {}, options = {}) {
-  const handlerId = makeHandlerId();
-
-  const result = {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    handlerId,
-    event: "SessionEnd",
-    blocking: false,
-    status: "ok",
-    createdAt: nowIso(),
-    actions: [],
-    summary: null,
-    redacted: true,
-  };
-
-  // Run outcome summary
-  try {
-    const outcomePath = path.join(cwd, ".claude/cco/orchestration/seamless-outcome/latest-outcome.json");
-    const outcome = safeReadJson(outcomePath);
-    if (outcome) {
-      result.actions.push({ action: "outcome_summary_read", status: "ok" });
-      result.outcomeSummary = {
-        status: outcome.status || "unknown",
-        redacted: true,
-      };
-    } else {
-      result.actions.push({ action: "outcome_summary_read", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "outcome_summary_read", status: "skipped" });
-  }
-
-  // Update ledger (via product-learning event)
-  try {
-    const { appendProductLearningEvent } = require("./product-learning-events");
-    appendProductLearningEvent(cwd, {
-      eventName: "lifecycle_session_end_summary_written",
-      payload: {
-        event: "SessionEnd",
-        handlerId,
-        status: "ok",
-        redacted: true,
-      },
-    });
-    result.actions.push({ action: "ledger_updated", status: "ok" });
-  } catch {
-    result.actions.push({ action: "ledger_updated", status: "skipped" });
-  }
-
-  // Read company-loop status
-  try {
-    const loopPath = path.join(cwd, ".claude/cco/orchestration/company-loop/latest-report.json");
-    const loop = safeReadJson(loopPath);
-    if (loop) {
-      result.actions.push({ action: "company_loop_read", status: "ok" });
-      result.companyLoopStatus = {
-        status: loop.status || "unknown",
-        nextPrRecommendation: (loop.surface && loop.surface.recommendedNextPr) || null,
-        redacted: true,
-      };
-    } else {
-      result.actions.push({ action: "company_loop_read", status: "not_found" });
-    }
-  } catch {
-    result.actions.push({ action: "company_loop_read", status: "skipped" });
-  }
-
-  // Prepare handoff summary
-  try {
-    const handoffPath = path.join(cwd, ".claude/cco/orchestration/worker-handoff/latest-handoff.json");
-    const handoff = safeReadJson(handoffPath);
-    if (handoff) {
-      result.actions.push({ action: "handoff_summary_prepared", status: "ok" });
-      result.handoffStatus = { available: true, redacted: true };
-    } else {
-      result.actions.push({ action: "handoff_summary_prepared", status: "not_found" });
-      result.handoffStatus = { available: false, redacted: true };
-    }
-  } catch {
-    result.actions.push({ action: "handoff_summary_prepared", status: "skipped" });
-    result.handoffStatus = { available: false, redacted: true };
-  }
-
-  result.summary = "Session end: outcome, ledger, company-loop, and handoff updated.";
-  result.safeNextAction = null;
-  result.reasonCodes = ["NON_BLOCKING", "OUTCOME_WRITTEN", "LEDGER_UPDATED", "HANDOFF_PREPARED"];
-
-  const receiptPath = writeReceipt(cwd, "SessionEnd", result);
-  result.receiptPath = receiptPath;
-  writeLedgerEntry(cwd, "SessionEnd", result);
-
-  return result;
-}
-
-// ── Dispatcher ────────────────────────────────────────────────────────────────
-
-// ── Recursion guard ───────────────────────────────────────────────────────────
-// Prevents Avorelo lifecycle hooks from re-entering when a hook-triggered
-// command itself calls another Avorelo command (e.g. lifecycle-hook → run →
-// lifecycle-hook). The environment variable is set by the shell hook wrapper
-// and checked here before any handler runs.
-
-const RECURSION_GUARD_ENV = "AVORELO_HOOK_ACTIVE";
-
-function isRecursionGuardActive() {
-  return process.env[RECURSION_GUARD_ENV] === "1";
-}
-
-function buildRecursionSkippedResult(event) {
-  return {
-    contract: CONTRACT,
-    schemaVersion: SCHEMA_VERSION,
-    event,
-    status: "ok",
-    recursionSkipped: true,
-    blocking: false,
-    decision: "allow",
-    summary: "Recursion guard active. Lifecycle re-entry skipped.",
-    reasonCodes: ["RECURSION_GUARD_ACTIVE", "AVORELO_HOOK_ACTIVE_SET"],
-    redacted: true,
-  };
-}
-
-function handleLifecycleHook(cwd, event, input = {}, options = {}) {
-  // Recursion guard: if a hook-triggered command calls us again, skip silently
-  if (isRecursionGuardActive()) {
-    return buildRecursionSkippedResult(event);
-  }
-
-  switch (event) {
-    case "SessionStart":
-    case "session-start":
-      return handleSessionStart(cwd, input, options);
-    case "UserPromptSubmit":
-    case "user-prompt-submit":
-      return handleUserPromptSubmit(cwd, input, options);
-    case "PreToolUse":
-    case "pre-tool-use":
-      return handlePreToolUse(cwd, input, options);
-    case "PostToolUse":
-    case "post-tool-use":
-      return handlePostToolUse(cwd, input, options);
-    case "Stop":
-    case "stop":
-      return handleStop(cwd, input, options);
-    case "SessionEnd":
-    case "session-end":
-      return handleSessionEnd(cwd, input, options);
-    default:
-      return {
-        contract: CONTRACT,
-        schemaVersion: SCHEMA_VERSION,
-        event,
-        status: "error",
-        error: `Unknown lifecycle event: ${event}`,
-        reasonCodes: ["UNKNOWN_EVENT"],
-        redacted: true,
-      };
-  }
-}
-
-function formatLifecycleHookText(result, options = {}) {
-  const debug = options.debug || false;
-  const lines = [];
-
-  const statusLabel = result.status === "ok" ? "ok" : result.status === "blocked" ? "BLOCKED" : result.status;
-  lines.push(`Lifecycle hook [${result.event}]: ${statusLabel}`);
-
-  if (result.decision && result.decision !== "allow") {
-    lines.push(`Decision: ${result.decision}`);
-  }
-  if (result.summary) {
-    lines.push(`Summary: ${result.summary}`);
-  }
-  if (result.safeNextAction) {
-    lines.push(`Next: ${result.safeNextAction}`);
-  }
-
-  if (debug && result.actions && result.actions.length > 0) {
-    lines.push("", "Actions:");
-    for (const a of result.actions) {
-      lines.push(`  - ${a.action}: ${a.status}${a.reason ? ` (${a.reason})` : ""}`);
-    }
-    if (result.reasonCodes) {
-      lines.push("", `Reason codes: ${result.reasonCodes.join(", ")}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-module.exports = {
-  CONTRACT,
-  SCHEMA_VERSION,
-  HOOKS_DIR_REL,
-  RECURSION_GUARD_ENV,
-  handleLifecycleHook,
-  handleSessionStart,
-  handleUserPromptSubmit,
-  handlePreToolUse,
-  handlePostToolUse,
-  handleStop,
-  handleSessionEnd,
-  formatLifecycleHookText,
-  isRecursionGuardActive,
-  buildRecursionSkippedResult,
-};