avorelo 0.1.0

package/scripts/lib/context-acquisition-plan.js

@@ -0,0 +1,287 @@
+"use strict";
+
+// ── Context Acquisition Plan ──────────────────────────────────────────────────
+//
+// Determines what context to acquire for a task — without loading it all.
+// Selects the minimal sufficient context strategy, budget, and fallback.
+//
+// Contract: avorelo.contextAcquisitionPlan.v1
+//
+// Strategy order:
+//   1. project profile / activation facts
+//   2. repo map / symbol map
+//   3. selected package scope
+//   4. git diff summary (if relevant)
+//   5. file slices
+//   6. full file (only if necessary and within budget)
+//   7. fallback + warn if confidence low
+//
+// Non-goals: loading full repo, selecting secrets/sensitive files,
+//            automatic full-file fallback without reason.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.contextAcquisitionPlan.v1";
+const SCHEMA_VERSION = 1;
+
+const PLAN_DIR_REL = ".claude/cco/orchestration/context-acquisition";
+const LATEST_PLAN_REL = `${PLAN_DIR_REL}/latest-plan.json`;
+
+const DEFAULT_CONTEXT_BUDGET_TOKENS = 8000;
+const MAX_CONTEXT_BUDGET_TOKENS = 16384;
+
+// ── Task classification ───────────────────────────────────────────────────────
+
+const TASK_PATTERNS = {
+  docs: /\b(docs?|documentation|readme|changelog|guide|tutorial|write up|update docs?)\b/i,
+  test: /\b(test|spec|jest|vitest|mocha|pytest|unit test|integration test)\b/i,
+  // security checked before bugfix so "fix auth vulnerability" classifies as security
+  security: /\b(auth(?:entication|orization)?|security|secret|password|rbac|csrf|xss|sql injection|vulnerability|privilege|injection)\b/i,
+  bugfix: /\b(fix|bug|broken|regression|error|crash|fail|patch)\b/i,
+  refactor: /\b(refactor|cleanup|clean up|restructure|rename|reorganize|simplify)\b/i,
+  feature: /\b(add|implement|build|create|new feature|support)\b/i,
+  explore: /\b(understand|explore|survey|overview|what does|explain|analyze)\b/i,
+};
+
+function classifyTask(taskText) {
+  if (!taskText) return "unknown";
+  for (const [kind, re] of Object.entries(TASK_PATTERNS)) {
+    if (re.test(taskText)) return kind;
+  }
+  return "unknown";
+}
+
+// ── Strategy selection ────────────────────────────────────────────────────────
+
+function selectContextStrategy(cwd, taskText, repoMap, executionPacket, options = {}) {
+  const taskKind = classifyTask(taskText);
+  const budget = options.contextBudget || DEFAULT_CONTEXT_BUDGET_TOKENS;
+
+  const strategy = {
+    taskKind,
+    useProjectProfile: true,
+    useRepoMap: true,
+    usePackageScope: false,
+    useGitDiff: false,
+    useFileSlices: false,
+    useFullFiles: false,
+    requiresApproval: false,
+    conservative: false,
+    confidence: "medium",
+    qualityRisks: [],
+    nextAction: null,
+  };
+
+  // Docs task: profile + repo map only, no source
+  if (taskKind === "docs") {
+    strategy.useFileSlices = false;
+    strategy.useFullFiles = false;
+    strategy.confidence = "high";
+    strategy.nextAction = "Load project profile and repo map; read only doc files.";
+    return strategy;
+  }
+
+  // Security task: caution + approval
+  if (taskKind === "security") {
+    strategy.requiresApproval = true;
+    strategy.useFileSlices = true;
+    strategy.qualityRisks.push("security_sensitive: do not compress security-critical config");
+    strategy.confidence = "low";
+    strategy.nextAction = "Review selected files carefully. Approval required before proceeding.";
+    return strategy;
+  }
+
+  // Explore task: repo map first, no full dump
+  if (taskKind === "explore") {
+    strategy.useRepoMap = true;
+    strategy.useFileSlices = false;
+    strategy.useFullFiles = false;
+    strategy.confidence = "medium";
+    strategy.nextAction = "Use repo map for overview. Load slices only if specific question requires it.";
+    return strategy;
+  }
+
+  // Bug fix: repo map + slices + git diff
+  if (taskKind === "bugfix") {
+    strategy.useGitDiff = true;
+    strategy.useFileSlices = true;
+    strategy.confidence = "medium";
+    strategy.nextAction = "Load git diff first. Select likely relevant file slices.";
+    return strategy;
+  }
+
+  // Test / refactor / feature: slices with optional full file fallback
+  if (["test", "refactor", "feature"].includes(taskKind)) {
+    strategy.useFileSlices = true;
+    strategy.useFullFiles = false; // only if slice insufficient
+    strategy.confidence = "medium";
+    strategy.nextAction = "Select relevant file slices via repo map symbols.";
+    return strategy;
+  }
+
+  // Unknown: conservative
+  strategy.conservative = true;
+  strategy.useFileSlices = false;
+  strategy.confidence = "low";
+  strategy.qualityRisks.push("task_unclear: conservative context to avoid quality regression");
+  strategy.nextAction = "Task unclear. Use repo map only. Escalate if more context needed.";
+  return strategy;
+}
+
+// ── Plan builder ──────────────────────────────────────────────────────────────
+
+function buildContextAcquisitionPlan(cwd, taskText, options = {}) {
+  const budget = options.contextBudget || DEFAULT_CONTEXT_BUDGET_TOKENS;
+
+  // Try to read repo map
+  let repoMap = null;
+  try {
+    const mapPath = path.join(cwd, ".claude/cco/orchestration/repo-map/latest-map.json");
+    if (fs.existsSync(mapPath)) {
+      repoMap = JSON.parse(fs.readFileSync(mapPath, "utf8"));
+    }
+  } catch {}
+
+  // Try to read execution packet
+  let executionPacket = null;
+  try {
+    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
+    if (fs.existsSync(packetPath)) {
+      executionPacket = JSON.parse(fs.readFileSync(packetPath, "utf8"));
+    }
+  } catch {}
+
+  const strategy = selectContextStrategy(cwd, taskText, repoMap, executionPacket, options);
+  const taskKind = strategy.taskKind;
+
+  // Select relevant files via repo map
+  let selectedFiles = [];
+  let selectedSymbols = [];
+  let fullFileFallbacks = [];
+
+  if (repoMap && strategy.useFileSlices) {
+    try {
+      const { selectLikelyRelevantFiles } = require("./repo-map");
+      const relevant = selectLikelyRelevantFiles(cwd, taskText, repoMap, options);
+      selectedFiles = relevant.slice(0, 10).map((f) => ({ path: f.path, reason: "relevance_score", estimatedTokens: f.estimatedTokens }));
+      selectedSymbols = relevant.flatMap((f) => (f.symbols || []).slice(0, 3)).slice(0, 20);
+    } catch {}
+  }
+
+  // Slices are symbolic; actual slicing happens in execution
+  const slices = strategy.useFileSlices ? selectedFiles.map((f) => ({ path: f.path, type: "slice" })) : [];
+
+  // Full file fallbacks: only listed if necessary
+  if (strategy.useFullFiles) {
+    for (const f of selectedFiles.slice(0, 3)) {
+      if (f.estimatedTokens && f.estimatedTokens < 2000) {
+        fullFileFallbacks.push({ path: f.path, reason: "small_file_full_read_safe" });
+      }
+    }
+  }
+
+  const contextBudget = {
+    targetTokens: budget,
+    maxTokens: MAX_CONTEXT_BUDGET_TOKENS,
+    estimatedSelected: selectedFiles.reduce((s, f) => s + (f.estimatedTokens || 0), 0),
+    withinBudget: selectedFiles.reduce((s, f) => s + (f.estimatedTokens || 0), 0) < budget,
+  };
+
+  const excluded = [];
+  if (taskKind === "docs") excluded.push({ reason: "docs_task_no_source_context_needed" });
+  if (strategy.conservative) excluded.push({ reason: "unknown_task_conservative" });
+  if (repoMap && repoMap.sensitiveExcluded > 0) excluded.push({ reason: "sensitive_files_excluded", count: repoMap.sensitiveExcluded });
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    taskSummary: taskText ? taskText.slice(0, 200) : null,
+    taskKind,
+    strategy: {
+      useProjectProfile: strategy.useProjectProfile,
+      useRepoMap: strategy.useRepoMap,
+      useGitDiff: strategy.useGitDiff,
+      useFileSlices: strategy.useFileSlices,
+      useFullFiles: strategy.useFullFiles,
+      requiresApproval: strategy.requiresApproval,
+      conservative: strategy.conservative,
+    },
+    selectedFiles,
+    selectedSymbols,
+    slices,
+    excluded,
+    fullFileFallbacks,
+    contextBudget,
+    confidence: strategy.confidence,
+    qualityRisks: strategy.qualityRisks,
+    nextAction: strategy.nextAction,
+    redacted: true,
+  };
+}
+
+function writeContextAcquisitionPlan(cwd, plan) {
+  const dir = path.join(cwd, PLAN_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const abs = path.join(cwd, LATEST_PLAN_REL);
+  fs.writeFileSync(abs, JSON.stringify(plan, null, 2), "utf8");
+  try {
+    appendProductLearningEvent(cwd, "context_acquisition_plan_generated", {
+      taskKind: plan.taskKind,
+      confidence: plan.confidence,
+      selectedFiles: plan.selectedFiles.length,
+      withinBudget: plan.contextBudget.withinBudget,
+      requiresApproval: plan.strategy.requiresApproval,
+    });
+  } catch {}
+  return abs;
+}
+
+function buildContextPlanSurface(cwd, options = {}) {
+  const abs = path.join(cwd, LATEST_PLAN_REL);
+  if (!fs.existsSync(abs)) {
+    return { status: "not_available", artifactPath: LATEST_PLAN_REL };
+  }
+  try {
+    const plan = JSON.parse(fs.readFileSync(abs, "utf8"));
+    return {
+      status: "available",
+      taskKind: plan.taskKind,
+      confidence: plan.confidence,
+      selectedFiles: plan.selectedFiles.length,
+      withinBudget: plan.contextBudget.withinBudget,
+      artifactPath: LATEST_PLAN_REL,
+    };
+  } catch {
+    return { status: "error", artifactPath: LATEST_PLAN_REL };
+  }
+}
+
+function formatContextPlanText(plan, options = {}) {
+  const lines = [`Context Acquisition Plan [${plan.taskKind}]`];
+  lines.push(`  Confidence: ${plan.confidence} | Approval required: ${plan.strategy.requiresApproval}`);
+  lines.push(`  Strategy: profile=${plan.strategy.useProjectProfile} repoMap=${plan.strategy.useRepoMap} gitDiff=${plan.strategy.useGitDiff} slices=${plan.strategy.useFileSlices} fullFile=${plan.strategy.useFullFiles}`);
+  if (plan.selectedFiles.length) {
+    lines.push(`  Selected files (${plan.selectedFiles.length}): ${plan.selectedFiles.slice(0, 5).map((f) => f.path).join(", ")}`);
+  }
+  lines.push(`  Budget: ~${plan.contextBudget.estimatedSelected}/${plan.contextBudget.targetTokens} tokens (${plan.contextBudget.withinBudget ? "within" : "over"} budget)`);
+  if (plan.qualityRisks.length) lines.push(`  Quality risks: ${plan.qualityRisks.join("; ")}`);
+  if (plan.nextAction) lines.push(`  Next: ${plan.nextAction}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  PLAN_DIR_REL,
+  LATEST_PLAN_REL,
+  classifyTask,
+  selectContextStrategy,
+  buildContextAcquisitionPlan,
+  writeContextAcquisitionPlan,
+  buildContextPlanSurface,
+  formatContextPlanText,
+};

package/scripts/lib/context-budget-guard.js

@@ -0,0 +1,170 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const BUDGET_REL = ".claude/cco/state/context-budget.json";
+
+const DEFAULT_BUDGETS = {
+  "cost-saver": {
+    maxContextChars: 40000,
+    warnAtPercent: 70,
+    blockAtPercent: 90,
+    maxToolOutputBytes: 12000,
+    maxSingleFileBytes: 20000,
+  },
+  balanced: {
+    maxContextChars: 80000,
+    warnAtPercent: 70,
+    blockAtPercent: 90,
+    maxToolOutputBytes: 24000,
+    maxSingleFileBytes: 40000,
+  },
+  quality: {
+    maxContextChars: 160000,
+    warnAtPercent: 75,
+    blockAtPercent: 92,
+    maxToolOutputBytes: 48000,
+    maxSingleFileBytes: 80000,
+  },
+};
+
+const DEFAULT_PROFILE = "balanced";
+
+function getBudgetForProfile(profile) {
+  return DEFAULT_BUDGETS[profile] || DEFAULT_BUDGETS[DEFAULT_PROFILE];
+}
+
+function normalizeBudgetConfig(raw) {
+  if (!raw || raw.enabled === false) {
+    return { enabled: false };
+  }
+  const rawProfile = String(raw.profile || DEFAULT_PROFILE);
+  const profile = DEFAULT_BUDGETS[rawProfile] ? rawProfile : DEFAULT_PROFILE;
+  const base = DEFAULT_BUDGETS[profile];
+  return {
+    enabled: raw.enabled !== false,
+    profile,
+    maxContextChars: Number.isFinite(Number(raw.maxContextChars)) ? Math.max(8000, Number(raw.maxContextChars)) : base.maxContextChars,
+    warnAtPercent: Number.isFinite(Number(raw.warnAtPercent)) ? Math.min(99, Math.max(10, Number(raw.warnAtPercent))) : base.warnAtPercent,
+    blockAtPercent: Number.isFinite(Number(raw.blockAtPercent)) ? Math.min(100, Math.max(50, Number(raw.blockAtPercent))) : base.blockAtPercent,
+    maxToolOutputBytes: Number.isFinite(Number(raw.maxToolOutputBytes)) ? Number(raw.maxToolOutputBytes) : base.maxToolOutputBytes,
+    maxSingleFileBytes: Number.isFinite(Number(raw.maxSingleFileBytes)) ? Number(raw.maxSingleFileBytes) : base.maxSingleFileBytes,
+  };
+}
+
+function estimateChars(text) {
+  return typeof text === "string" ? text.length : String(text || "").length;
+}
+
+function computeBudgetState(usedChars, budget) {
+  const { maxContextChars, warnAtPercent, blockAtPercent } = budget;
+  const usedPercent = maxContextChars > 0 ? (usedChars / maxContextChars) * 100 : 0;
+  const isOverWarn = usedPercent >= warnAtPercent;
+  const isOverBlock = usedPercent >= blockAtPercent;
+  const remainingChars = Math.max(0, maxContextChars - usedChars);
+
+  let status = "ok";
+  if (isOverBlock) status = "critical";
+  else if (isOverWarn) status = "warn";
+
+  return {
+    usedChars,
+    maxContextChars,
+    usedPercent: Math.round(usedPercent * 10) / 10,
+    remainingChars,
+    status,
+    warnAtPercent,
+    blockAtPercent,
+  };
+}
+
+function checkToolOutputSize(outputText, budget) {
+  const bytes = Buffer.byteLength(String(outputText || ""), "utf8");
+  const isOversized = bytes > budget.maxToolOutputBytes;
+  return {
+    bytes,
+    maxBytes: budget.maxToolOutputBytes,
+    isOversized,
+    truncateHint: isOversized ? `Output exceeds ${budget.maxToolOutputBytes} bytes. Store out-of-band and reference by path.` : null,
+  };
+}
+
+function checkSingleFileSize(fileSizeBytes, budget) {
+  const isOversized = fileSizeBytes > budget.maxSingleFileBytes;
+  return {
+    bytes: fileSizeBytes,
+    maxBytes: budget.maxSingleFileBytes,
+    isOversized,
+    truncateHint: isOversized ? `File exceeds ${budget.maxSingleFileBytes} bytes. Read in chunks or summarize.` : null,
+  };
+}
+
+function loadBudgetState(cwd) {
+  try {
+    const p = path.join(cwd, BUDGET_REL);
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveBudgetState(cwd, state) {
+  const p = path.join(cwd, BUDGET_REL);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
+}
+
+function buildBudgetStatus(cwd, rawBudgetConfig) {
+  const budget = normalizeBudgetConfig(rawBudgetConfig);
+  if (!budget.enabled) {
+    return { enabled: false, status: "off" };
+  }
+
+  const stored = loadBudgetState(cwd);
+  const usedChars = stored?.usedChars || 0;
+  const budgetState = computeBudgetState(usedChars, budget);
+
+  const warnings = [];
+  if (budgetState.status === "critical") {
+    warnings.push(`Context at ${budgetState.usedPercent}% of limit — consider /cco-optimize or summarize large outputs.`);
+  } else if (budgetState.status === "warn") {
+    warnings.push(`Context at ${budgetState.usedPercent}% of limit — approaching budget.`);
+  }
+
+  return {
+    enabled: true,
+    status: budgetState.status,
+    usedChars: budgetState.usedChars,
+    maxContextChars: budgetState.maxContextChars,
+    usedPercent: budgetState.usedPercent,
+    remainingChars: budgetState.remainingChars,
+    warnAtPercent: budgetState.warnAtPercent,
+    blockAtPercent: budgetState.blockAtPercent,
+    warnings,
+    budgetPath: BUDGET_REL,
+  };
+}
+
+function formatBudgetStatusText(budgetStatus) {
+  if (!budgetStatus || !budgetStatus.enabled || budgetStatus.status === "off") return null;
+  const { status, usedPercent, remainingChars, warnings } = budgetStatus;
+  if (status === "ok" && warnings.length === 0) return null;
+  const lines = [`Context budget: ${usedPercent}% used, ${remainingChars} chars remaining`];
+  warnings.forEach((w) => lines.push(`  ⚠ ${w}`));
+  return lines.join("\n");
+}
+
+module.exports = {
+  DEFAULT_BUDGETS,
+  getBudgetForProfile,
+  normalizeBudgetConfig,
+  estimateChars,
+  computeBudgetState,
+  checkToolOutputSize,
+  checkSingleFileSize,
+  loadBudgetState,
+  saveBudgetState,
+  buildBudgetStatus,
+  formatBudgetStatusText,
+};