avorelo 0.1.0 → 0.3.0

package/scripts/lib/context-optimizer.js

@@ -1,715 +0,0 @@
-"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,
-};