avorelo 0.1.0

package/scripts/lib/context-optimizer.js

@@ -0,0 +1,715 @@
+"use strict";
+
+// ── Prompt / Context / Token Optimization Foundation ─────────────────────────
+//
+// Builds stage-specific context packs for Avorelo's seamless orchestration.
+// Each pack is compact, deterministic, local-only, and safety-bounded.
+//
+// Contract: avorelo.contextOptimization.v1
+//
+// Non-goals: generic prompt optimizer, RAG, vector search, guaranteed savings,
+//            full cost analytics, external API calls, LLM calls.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+
+function safeWriteJson(absPath, obj) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(obj, null, 2), "utf8");
+}
+
+function safeReadJson(absPath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return fallback !== undefined ? fallback : null;
+  }
+}
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const SCHEMA_VERSION = 1;
+const CONTRACT = "avorelo.contextOptimization.v1";
+
+const CONTEXT_OPT_DIR_REL = ".claude/cco/orchestration/context-optimizer";
+const LATEST_PACK_REL = ".claude/cco/orchestration/context-optimizer/latest-pack.json";
+const LATEST_RECEIPT_REL = ".claude/cco/orchestration/context-optimizer/latest-receipt.json";
+
+// ── Token estimation ──────────────────────────────────────────────────────────
+
+const GPT_TOKENIZER_VENDOR_PATH = path.resolve(
+  __dirname, "../vendor/node_modules/gpt-tokenizer/cjs/main.js"
+);
+
+let _tokenizer = null;
+function tryLoadTokenizer() {
+  if (_tokenizer !== null) return _tokenizer;
+  try {
+    if (fs.existsSync(GPT_TOKENIZER_VENDOR_PATH)) {
+      const mod = require(GPT_TOKENIZER_VENDOR_PATH);
+      _tokenizer = mod;
+      return _tokenizer;
+    }
+  } catch {}
+  _tokenizer = false;
+  return false;
+}
+
+function estimateTokens(text) {
+  if (!text) return { estimatedTokens: 0, estimatedChars: 0, estimateMethod: "heuristic" };
+  const s = String(text);
+  const chars = s.length;
+  const tok = tryLoadTokenizer();
+  if (tok) {
+    try {
+      const encode = tok.encode || (tok.default && tok.default.encode);
+      if (typeof encode === "function") {
+        const tokens = encode(s).length;
+        return { estimatedTokens: tokens, estimatedChars: chars, estimateMethod: "local_tokenizer" };
+      }
+    } catch {}
+  }
+  return {
+    estimatedTokens: Math.ceil(chars / 4),
+    estimatedChars: chars,
+    estimateMethod: "heuristic",
+  };
+}
+
+function tokenWarning(estimatedTokens, maxTokens) {
+  if (!maxTokens) return "unknown";
+  const ratio = estimatedTokens / maxTokens;
+  if (ratio <= 0.7) return "within_budget";
+  if (ratio <= 1.0) return "near_budget";
+  return "over_budget";
+}
+
+// ── Stage budget map ──────────────────────────────────────────────────────────
+// Conservative token caps. Local models get the small cap regardless of stage.
+
+const STAGE_BUDGETS = {
+  inspect:        { budgetClass: "small",  maxInputTokens: 4000 },
+  summarize:      { budgetClass: "small",  maxInputTokens: 4000 },
+  plan:           { budgetClass: "medium", maxInputTokens: 8000 },
+  implement:      { budgetClass: "large",  maxInputTokens: 16000 },
+  verify:         { budgetClass: "small",  maxInputTokens: 4000 },
+  security_review:{ budgetClass: "medium", maxInputTokens: 8000 },
+  review:         { budgetClass: "medium", maxInputTokens: 8000 },
+  handoff:        { budgetClass: "small",  maxInputTokens: 4000 },
+  final_review:   { budgetClass: "medium", maxInputTokens: 8000 },
+};
+
+const LOCAL_WORKER_IDS = new Set(["lm_studio", "ollama"]);
+
+function getStageBudget(stageId, workerToolId) {
+  const base = STAGE_BUDGETS[stageId] || { budgetClass: "medium", maxInputTokens: 8000 };
+  const isLocal = LOCAL_WORKER_IDS.has(workerToolId);
+  if (isLocal) {
+    return { budgetClass: "small", maxInputTokens: 4000, localWorkerCapped: true };
+  }
+  return { ...base, localWorkerCapped: false };
+}
+
+// ── Safety boundary helpers ───────────────────────────────────────────────────
+
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*\S+)/i;
+
+function containsSecret(text) {
+  return SECRET_PATTERN.test(String(text || ""));
+}
+
+function redactIfSecret(text) {
+  if (!text) return text;
+  return containsSecret(text) ? "[REDACTED]" : String(text);
+}
+
+const EXCLUDED_PATH_PATTERNS = [
+  /node_modules/,
+  /\.git[\/\\]/,
+  /\.env(\.|$)/,
+  /dist[\/\\]/,
+  /build[\/\\]/,
+  /coverage[\/\\]/,
+  /\.next[\/\\]/,
+  /\.claude[\/\\]cco[\/\\]events/,
+];
+
+function shouldExcludePath(filePath) {
+  const normalized = String(filePath || "").replace(/\\/g, "/");
+  return EXCLUDED_PATH_PATTERNS.some((pat) => pat.test(normalized));
+}
+
+// ── Context item classification ───────────────────────────────────────────────
+
+function buildSafetyBoundaries(stage) {
+  const isSecurityStage = stage === "security_review";
+  return {
+    noSecrets: true,
+    noRawPrompt: true,
+    noRawThirdPartySkillBodies: true,
+    localOnly: false,
+    approvalRequired: isSecurityStage,
+  };
+}
+
+// ── Context selection logic ───────────────────────────────────────────────────
+
+function selectContextItems(options, budget) {
+  const {
+    changedFiles = [],
+    relevantFiles = [],
+    skillSummaries = [],
+    safePathConstraints = [],
+    intakeWarnings = [],
+    governanceSummary = null,
+    testCommands = [],
+    proofSummary = null,
+    taskSummary = "",
+  } = options;
+
+  const included = [];
+  const excluded = [];
+  let usedTokens = 0;
+  const maxTokens = budget.maxInputTokens;
+
+  // 1. Task summary (always included, compact)
+  if (taskSummary) {
+    const est = estimateTokens(taskSummary.slice(0, 400));
+    included.push({ type: "task_summary", ref: "task", tokenEstimate: est.estimatedTokens });
+    usedTokens += est.estimatedTokens;
+  }
+
+  // 2. Changed files (compact list, not full contents)
+  const safeChangedFiles = changedFiles
+    .map((f) => (typeof f === "string" ? f : f.path || f.file || String(f)))
+    .filter((f) => !shouldExcludePath(f) && !containsSecret(f));
+
+  if (safeChangedFiles.length) {
+    const snippet = safeChangedFiles.slice(0, 20).join("\n");
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "changed_files", count: safeChangedFiles.length, tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "changed_files", itemRef: `${safeChangedFiles.length} files` });
+    }
+  }
+
+  // 3. Relevant file paths (not full contents — summaries/paths only)
+  const safeRelevantFiles = relevantFiles
+    .map((f) => (typeof f === "string" ? f : f.path || String(f)))
+    .filter((f) => !shouldExcludePath(f) && !containsSecret(f));
+
+  if (safeRelevantFiles.length) {
+    const snippet = safeRelevantFiles.slice(0, 15).join("\n");
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "relevant_files", count: safeRelevantFiles.length, tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "relevant_files", itemRef: `${safeRelevantFiles.length} files` });
+    }
+  }
+
+  // 4. Skill summaries (lazy — only selected summaries, no bodies)
+  const safeSkillSummaries = skillSummaries
+    .filter((s) => !containsSecret(String(s.summary || s.id || "")))
+    .slice(0, 5);
+
+  if (safeSkillSummaries.length) {
+    const snippet = safeSkillSummaries.map((s) => `${s.id || "skill"}: ${(s.summary || "").slice(0, 80)}`).join("\n");
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "skill_summaries", count: safeSkillSummaries.length, tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "skill_summaries", itemRef: `${safeSkillSummaries.length} skills` });
+    }
+  }
+
+  // 5. Safe path / intake / governance constraints (always included if present)
+  if (safePathConstraints.length || intakeWarnings.length || governanceSummary) {
+    const snippets = [
+      ...safePathConstraints.slice(0, 3).map((c) => redactIfSecret(c)),
+      ...intakeWarnings.slice(0, 3).map((w) => redactIfSecret(w)),
+      governanceSummary ? redactIfSecret(String(governanceSummary).slice(0, 200)) : null,
+    ].filter(Boolean);
+    const snippet = snippets.join("\n");
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "constraints", count: snippets.length, tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "constraints", itemRef: "safe_path/intake/governance" });
+    }
+  }
+
+  // 6. Test commands (small, always useful for verify/implement stages)
+  if (testCommands.length) {
+    const snippet = testCommands.slice(0, 5).join("\n");
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "test_commands", count: testCommands.length, tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "test_commands", itemRef: `${testCommands.length} commands` });
+    }
+  }
+
+  // 7. Proof summary reference (path + compact summary, not full payload)
+  if (proofSummary) {
+    const snippet = String(proofSummary).slice(0, 300);
+    const est = estimateTokens(snippet);
+    if (usedTokens + est.estimatedTokens <= maxTokens) {
+      included.push({ type: "proof_summary", tokenEstimate: est.estimatedTokens });
+      usedTokens += est.estimatedTokens;
+    } else {
+      excluded.push({ reason: "over_budget", itemType: "proof_summary", itemRef: "proof" });
+    }
+  }
+
+  const compactionUsed = usedTokens < (estimateTokens([
+    taskSummary,
+    ...safeChangedFiles,
+    ...safeRelevantFiles,
+    ...safeSkillSummaries.map((s) => s.summary || ""),
+    ...safePathConstraints,
+  ].join("\n")).estimatedTokens);
+
+  return {
+    included,
+    excluded,
+    estimatedTokens: usedTokens,
+    compactionUsed,
+  };
+}
+
+// ── Context pack builder ──────────────────────────────────────────────────────
+
+function createContextPackId() {
+  return `ctx-${Date.now()}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+/**
+ * Builds a stage-specific context pack for the given task/stage.
+ *
+ * options:
+ *   taskSummary, stageId, stageRole, selectedWorker (toolId), selectedModel,
+ *   contextNeed ("small"|"medium"|"large"), reasoningNeed ("low"|"medium"|"high"),
+ *   routeId, changedFiles, relevantFiles, skillSummaries,
+ *   safePathConstraints, intakeWarnings, governanceSummary,
+ *   testCommands, proofSummary, nextAction
+ */
+function buildContextPack(cwd, options = {}) {
+  const {
+    taskSummary = "Unknown task",
+    stageId = "implement",
+    stageRole = "implementation",
+    selectedWorker = null,
+    selectedModel = null,
+    contextNeed = "medium",
+    reasoningNeed = "medium",
+    routeId = null,
+    nextAction = null,
+  } = options;
+
+  const contextPackId = createContextPackId();
+  const budget = getStageBudget(stageId, selectedWorker);
+
+  // Override budget class if contextNeed signals it
+  const effectiveBudget = { ...budget };
+  if (contextNeed === "small" && budget.budgetClass !== "small") {
+    effectiveBudget.budgetClass = "small";
+    effectiveBudget.maxInputTokens = Math.min(budget.maxInputTokens, 4000);
+  }
+  if (contextNeed === "large" && budget.budgetClass === "small" && !budget.localWorkerCapped) {
+    effectiveBudget.budgetClass = "medium";
+    effectiveBudget.maxInputTokens = 8000;
+  }
+
+  const selection = selectContextItems(options, effectiveBudget);
+  const tokenWarningLevel = tokenWarning(selection.estimatedTokens, effectiveBudget.maxInputTokens);
+  const safetyBoundaries = buildSafetyBoundaries(stageId);
+
+  const reductionSummary = {
+    compactionUsed: selection.compactionUsed,
+    includedCount: selection.included.length,
+    excludedCount: selection.excluded.length,
+    estimatedTokens: selection.estimatedTokens,
+    maxTokens: effectiveBudget.maxInputTokens,
+    budgetWarning: tokenWarningLevel,
+  };
+
+  const pack = {
+    schemaVersion: SCHEMA_VERSION,
+    contract: CONTRACT,
+    contextPackId,
+    generatedAt: nowIso(),
+    taskSummary: redactIfSecret(String(taskSummary).slice(0, 300)),
+    routeId: routeId || null,
+    stageId,
+    stageRole,
+    selectedWorker: selectedWorker || null,
+    selectedModel: selectedModel || null,
+    contextNeed,
+    reasoningNeed,
+    targetBudget: {
+      estimatedInputTokens: selection.estimatedTokens,
+      maxInputTokens: effectiveBudget.maxInputTokens,
+      budgetClass: effectiveBudget.budgetClass,
+    },
+    includedContext: selection.included,
+    excludedContext: selection.excluded,
+    safetyBoundaries,
+    tokenEstimate: {
+      estimatedTokens: selection.estimatedTokens,
+      maxInputTokens: effectiveBudget.maxInputTokens,
+      warning: tokenWarningLevel,
+    },
+    reductionSummary,
+    evidenceRequirements: [
+      "No secrets in context pack",
+      "No full unselected skill bodies",
+      "No .env or raw credential files",
+    ],
+    nextAction: nextAction ? redactIfSecret(String(nextAction).slice(0, 200)) : null,
+    redacted: true,
+    localWorkerCapped: effectiveBudget.localWorkerCapped,
+  };
+
+  return pack;
+}
+
+// ── Persistence ───────────────────────────────────────────────────────────────
+
+function ensureContextOptimizerDirs(cwd) {
+  ensureCcoDirs(cwd);
+  const dir = path.join(cwd, CONTEXT_OPT_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writeContextPack(cwd, pack, options = {}) {
+  ensureContextOptimizerDirs(cwd);
+  const latestPath = path.join(cwd, LATEST_PACK_REL);
+  safeWriteJson(latestPath, pack);
+
+  // Also write timestamped copy for history
+  if (!options.noHistory) {
+    const histDir = path.join(cwd, CONTEXT_OPT_DIR_REL, "history");
+    fs.mkdirSync(histDir, { recursive: true });
+    const histPath = path.join(histDir, `${pack.contextPackId}.json`);
+    safeWriteJson(histPath, pack);
+  }
+
+  return {
+    contextPackId: pack.contextPackId,
+    latestPackPath: LATEST_PACK_REL,
+  };
+}
+
+function readLatestContextPack(cwd) {
+  return safeReadJson(path.join(cwd, LATEST_PACK_REL), null);
+}
+
+// ── Receipt ───────────────────────────────────────────────────────────────────
+
+function buildContextOptimizationReceipt(cwd, pack) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    contract: "avorelo.contextOptimizationReceipt.v1",
+    generatedAt: nowIso(),
+    latestContextPackPath: LATEST_PACK_REL,
+    latestContextPackId: pack.contextPackId,
+    stageId: pack.stageId,
+    budgetClass: pack.targetBudget.budgetClass,
+    estimatedTokens: pack.tokenEstimate.estimatedTokens,
+    maxInputTokens: pack.tokenEstimate.maxInputTokens,
+    budgetWarning: pack.tokenEstimate.warning,
+    includedCount: pack.includedContext.length,
+    excludedCount: pack.excludedContext.length,
+    compactionUsed: pack.reductionSummary.compactionUsed,
+    localWorkerCapped: pack.localWorkerCapped,
+    safetyBoundaries: pack.safetyBoundaries,
+    noSecretsConfirmed: pack.safetyBoundaries.noSecrets,
+    nextAction: pack.nextAction,
+    redacted: true,
+  };
+}
+
+function writeContextOptimizationReceipt(cwd, receipt) {
+  ensureContextOptimizerDirs(cwd);
+  const latestPath = path.join(cwd, LATEST_RECEIPT_REL);
+  safeWriteJson(latestPath, receipt);
+  return { latestReceiptPath: LATEST_RECEIPT_REL };
+}
+
+function readLatestContextOptimizationReceipt(cwd) {
+  return safeReadJson(path.join(cwd, LATEST_RECEIPT_REL), null);
+}
+
+// ── Product learning events ───────────────────────────────────────────────────
+
+function emitContextPackEvent(cwd, pack) {
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "context_pack_generated",
+      category: "context_optimization",
+      surface: "local",
+      status: "observed",
+      payload: {
+        stageId: pack.stageId,
+        budgetClass: pack.targetBudget.budgetClass,
+        estimatedTokens: pack.tokenEstimate.estimatedTokens,
+        maxInputTokens: pack.tokenEstimate.maxInputTokens,
+        budgetWarning: pack.tokenEstimate.warning,
+        includedCount: pack.includedContext.length,
+        excludedCount: pack.excludedContext.length,
+        compactionUsed: pack.reductionSummary.compactionUsed,
+        localWorkerCapped: pack.localWorkerCapped,
+        contextNeed: pack.contextNeed,
+        reasoningNeed: pack.reasoningNeed,
+      },
+    });
+    if (pack.tokenEstimate.warning === "over_budget") {
+      appendProductLearningEvent(cwd, {
+        eventName: "context_over_budget",
+        category: "context_optimization",
+        surface: "local",
+        status: "observed",
+        payload: {
+          stageId: pack.stageId,
+          estimatedTokens: pack.tokenEstimate.estimatedTokens,
+          maxInputTokens: pack.tokenEstimate.maxInputTokens,
+          budgetClass: pack.targetBudget.budgetClass,
+        },
+      });
+    } else if (pack.tokenEstimate.warning === "near_budget") {
+      appendProductLearningEvent(cwd, {
+        eventName: "context_budget_warning",
+        category: "context_optimization",
+        surface: "local",
+        status: "observed",
+        payload: {
+          stageId: pack.stageId,
+          estimatedTokens: pack.tokenEstimate.estimatedTokens,
+          maxInputTokens: pack.tokenEstimate.maxInputTokens,
+        },
+      });
+    }
+    if (pack.reductionSummary.compactionUsed) {
+      appendProductLearningEvent(cwd, {
+        eventName: "context_compaction_used",
+        category: "context_optimization",
+        surface: "local",
+        status: "observed",
+        payload: {
+          stageId: pack.stageId,
+          excludedCount: pack.reductionSummary.excludedCount,
+        },
+      });
+    }
+    if (pack.localWorkerCapped) {
+      appendProductLearningEvent(cwd, {
+        eventName: "local_worker_context_boundary_used",
+        category: "context_optimization",
+        surface: "local",
+        status: "observed",
+        payload: {
+          stageId: pack.stageId,
+          worker: pack.selectedWorker,
+          budgetClass: pack.targetBudget.budgetClass,
+        },
+      });
+    }
+    if (pack.safetyBoundaries.noSecrets) {
+      appendProductLearningEvent(cwd, {
+        eventName: "no_secrets_context_boundary_applied",
+        category: "context_optimization",
+        surface: "local",
+        status: "observed",
+        payload: {
+          stageId: pack.stageId,
+        },
+      });
+    }
+    if (pack.excludedContext.length > 0) {
+      pack.excludedContext.slice(0, 3).forEach((item) => {
+        appendProductLearningEvent(cwd, {
+          eventName: "context_item_excluded",
+          category: "context_optimization",
+          surface: "local",
+          status: "observed",
+          payload: {
+            reason: item.reason,
+            itemType: item.itemType,
+          },
+        });
+      });
+    }
+  } catch {
+    // product learning is best-effort
+  }
+}
+
+// ── Build + write shortcut ────────────────────────────────────────────────────
+
+function buildAndWriteContextPack(cwd, options = {}) {
+  const pack = buildContextPack(cwd, options);
+  const writeResult = writeContextPack(cwd, pack);
+  const receipt = buildContextOptimizationReceipt(cwd, pack);
+  writeContextOptimizationReceipt(cwd, receipt);
+  emitContextPackEvent(cwd, pack);
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "context_optimization_receipt_written",
+      category: "context_optimization",
+      surface: "local",
+      status: "observed",
+      payload: {
+        stageId: pack.stageId,
+        budgetClass: pack.targetBudget.budgetClass,
+        estimatedTokens: pack.tokenEstimate.estimatedTokens,
+      },
+    });
+    appendProductLearningEvent(cwd, {
+      eventName: "context_budget_estimated",
+      category: "context_optimization",
+      surface: "local",
+      status: "observed",
+      payload: {
+        stageId: pack.stageId,
+        budgetClass: pack.targetBudget.budgetClass,
+        estimatedTokens: pack.tokenEstimate.estimatedTokens,
+        maxInputTokens: pack.tokenEstimate.maxInputTokens,
+        estimateMethod: "heuristic",
+      },
+    });
+  } catch {}
+
+  return {
+    pack,
+    receipt,
+    contextPackId: pack.contextPackId,
+    latestPackPath: writeResult.latestPackPath,
+    latestReceiptPath: LATEST_RECEIPT_REL,
+  };
+}
+
+// ── Dashboard surface ─────────────────────────────────────────────────────────
+
+function buildContextOptimizerSurface(cwd) {
+  const receipt = readLatestContextOptimizationReceipt(cwd);
+  const pack = readLatestContextPack(cwd);
+
+  if (!receipt || !pack) {
+    return {
+      status: "not_run",
+      latestReceiptPath: null,
+      latestContextPackPath: null,
+      stageBudgets: null,
+      lastEstimateMethod: null,
+      lastEstimatedTokens: null,
+      budgetWarning: null,
+      includedItems: null,
+      excludedItems: null,
+      compactionUsed: null,
+      nextAction: "Run `avorelo context --task \"<task>\" --json` to generate a stage context pack.",
+    };
+  }
+
+  const status = receipt.budgetWarning === "over_budget" ? "over_budget"
+    : receipt.budgetWarning === "near_budget" ? "near_budget"
+    : "ok";
+
+  return {
+    status,
+    latestReceiptPath: LATEST_RECEIPT_REL,
+    latestContextPackPath: LATEST_PACK_REL,
+    stageId: receipt.stageId,
+    budgetClass: receipt.budgetClass,
+    lastEstimateMethod: "heuristic",
+    lastEstimatedTokens: receipt.estimatedTokens,
+    maxInputTokens: receipt.maxInputTokens,
+    budgetWarning: receipt.budgetWarning,
+    includedItems: receipt.includedCount,
+    excludedItems: receipt.excludedCount,
+    compactionUsed: receipt.compactionUsed,
+    localWorkerCapped: receipt.localWorkerCapped,
+    noSecretsConfirmed: receipt.noSecretsConfirmed,
+    nextAction: receipt.nextAction || "Context pack is ready for handoff.",
+  };
+}
+
+// ── Handoff integration helper ────────────────────────────────────────────────
+
+function buildHandoffContextPackSummary(cwd) {
+  const pack = readLatestContextPack(cwd);
+  if (!pack) return null;
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "handoff_context_pack_attached",
+      category: "handoff",
+      surface: "local",
+      status: "observed",
+      payload: {
+        stageId: pack.stageId,
+        budgetClass: pack.targetBudget.budgetClass,
+        estimatedTokens: pack.tokenEstimate.estimatedTokens,
+      },
+    });
+  } catch {}
+
+  return {
+    contextPackPath: LATEST_PACK_REL,
+    contextPackId: pack.contextPackId,
+    stageId: pack.stageId,
+    budgetClass: pack.targetBudget.budgetClass,
+    tokenEstimate: pack.tokenEstimate.estimatedTokens,
+    includedCount: pack.includedContext.length,
+    excludedCount: pack.excludedContext.length,
+    budgetWarning: pack.tokenEstimate.warning,
+    nextAction: pack.nextAction,
+  };
+}
+
+// ── Skill lazy-loading signal ─────────────────────────────────────────────────
+
+function emitSkillLazyLoadEvent(cwd, skillId, loadedTokens) {
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "skill_context_lazy_loaded",
+      category: "context_optimization",
+      surface: "local",
+      status: "observed",
+      payload: {
+        skillId: String(skillId || "unknown").slice(0, 60),
+        loadedTokens,
+      },
+    });
+  } catch {}
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_PACK_REL,
+  LATEST_RECEIPT_REL,
+  STAGE_BUDGETS,
+  estimateTokens,
+  tokenWarning,
+  getStageBudget,
+  buildContextPack,
+  writeContextPack,
+  readLatestContextPack,
+  buildContextOptimizationReceipt,
+  writeContextOptimizationReceipt,
+  readLatestContextOptimizationReceipt,
+  buildAndWriteContextPack,
+  buildContextOptimizerSurface,
+  buildHandoffContextPackSummary,
+  emitSkillLazyLoadEvent,
+};