avorelo 0.3.8 → 0.4.0-rc.2

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

@@ -0,0 +1,359 @@
+"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;
+}
+
+// ── Tool/MCP tax — no-connect governor ────────────────────────────────────────
+//
+// Before loading an external tool/MCP, decide deterministically whether local
+// evidence already suffices. Avoids the "tool tax" (loading connectors just in
+// case). Advisory only (claimType heuristic) — records the decision, never hard
+// blocks. Local read tools are always allowed.
+
+const LOCAL_EVIDENCE_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "NotebookRead"]);
+const EXTERNAL_TOOL_RE = /^(mcp__|WebFetch|WebSearch|browser|Computer|Fetch)/i;
+// Task kinds where local repo evidence is typically sufficient (no external connect).
+const LOCAL_SUFFICIENT_KINDS = new Set(["docs", "explore", "refactor", "test", "bugfix"]);
+
+function hasLocalRepoEvidence(cwd) {
+  try {
+    const mapPath = path.join(cwd, ".claude/cco/orchestration/repo-map/latest-map.json");
+    if (fs.existsSync(mapPath)) return true;
+  } catch {}
+  try {
+    // Any source files present is weak local evidence.
+    return fs.existsSync(path.join(cwd, "package.json")) || fs.existsSync(path.join(cwd, "scripts"));
+  } catch {}
+  return false;
+}
+
+function buildToolTaxDecision(cwd, input = {}, options = {}) {
+  const { toolName = "", taskText = "" } = input;
+  const taskKind = classifyTask(taskText);
+  const localEvidence =
+    typeof input.localEvidenceSufficient === "boolean"
+      ? input.localEvidenceSufficient
+      : hasLocalRepoEvidence(cwd);
+
+  // Local read tools never incur tool tax.
+  if (LOCAL_EVIDENCE_TOOLS.has(toolName)) {
+    return { contract: CONTRACT, toolName, taskKind, decision: "local_tool", reasonCode: "local_tool_no_tax", connect: true, claimType: "heuristic", nextAction: null, redacted: true };
+  }
+
+  const isExternal = EXTERNAL_TOOL_RE.test(toolName);
+  if (!isExternal) {
+    // Unknown/internal tool — allow, no tax claim.
+    return { contract: CONTRACT, toolName, taskKind, decision: "tool_load_required", reasonCode: "non_external_tool", connect: true, claimType: "heuristic", nextAction: null, redacted: true };
+  }
+
+  // External/MCP tool: avoid the connect when local evidence already covers the task.
+  if (localEvidence && LOCAL_SUFFICIENT_KINDS.has(taskKind)) {
+    return {
+      contract: CONTRACT,
+      toolName,
+      taskKind,
+      decision: "no_connect",
+      reasonCode: "tool_load_avoided",
+      connect: false,
+      claimType: "heuristic",
+      nextAction: `Local repo evidence is sufficient for a ${taskKind} task; skip loading ${toolName}.`,
+      redacted: true,
+    };
+  }
+
+  return {
+    contract: CONTRACT,
+    toolName,
+    taskKind,
+    decision: "tool_load_required",
+    reasonCode: localEvidence ? "task_needs_external_evidence" : "no_local_evidence",
+    connect: true,
+    claimType: "heuristic",
+    nextAction: `External evidence needed for ${taskKind || "this"} task; ${toolName} load is justified.`,
+    redacted: true,
+  };
+}
+
+// ── 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,
+  buildToolTaxDecision,
+  buildContextAcquisitionPlan,
+  writeContextAcquisitionPlan,
+  buildContextPlanSurface,
+  formatContextPlanText,
+};

package/scripts/lib/context-authority-rules.js

@@ -0,0 +1,138 @@
+"use strict";
+
+const AUTHORITY_ORDER = { high: 3, medium: 2, low: 1 };
+
+const RULES = [
+  {
+    id: "release-beats-planning",
+    description: "Release docs beat planning docs",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.type === "release_doc") return { ...r, authorityBoost: 2 };
+        if (r.type === "planning_doc") return { ...r, authorityPenalty: 1 };
+        return r;
+      });
+    },
+  },
+  {
+    id: "dogfood-beats-claim",
+    description: "Dogfood artifact / proof receipt beats claim in prose",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.type === "proof_artifact" || r.type === "dogfood_artifact") {
+          return { ...r, authorityBoost: (r.authorityBoost || 0) + 1 };
+        }
+        return r;
+      });
+    },
+  },
+  {
+    id: "source-beats-screenshot",
+    description: "Current source code beats old screenshots",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.type === "screenshot_ref" && r.freshness !== "fresh") {
+          return { ...r, authorityPenalty: (r.authorityPenalty || 0) + 2 };
+        }
+        if (r.type === "source_code" || r.type === "public_web_source") {
+          return { ...r, authorityBoost: (r.authorityBoost || 0) + 1 };
+        }
+        return r;
+      });
+    },
+  },
+  {
+    id: "kernel-beats-scattered",
+    description: "Capability Kernel registry beats scattered assumptions",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.type === "capability_manifest") {
+          return { ...r, authorityBoost: (r.authorityBoost || 0) + 1 };
+        }
+        return r;
+      });
+    },
+  },
+  {
+    id: "memory-cannot-override",
+    description: "Reentry Memory cannot override source of truth",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.type === "reentry_memory") {
+          return { ...r, authorityPenalty: (r.authorityPenalty || 0) + 1, cannotOverride: true };
+        }
+        return r;
+      });
+    },
+  },
+  {
+    id: "public-needs-public-safe",
+    description: "Public copy needs public-safe sources",
+    apply(refs, context) {
+      if (!context || !context.requiresPublicSafe) return refs;
+      return refs.map((r) => {
+        if (r.internalOnly && !r.publicSafe) {
+          return { ...r, excludedByPublicSafety: true };
+        }
+        return r;
+      });
+    },
+  },
+  {
+    id: "evidence-refs-must-be-real",
+    description: "Evidence refs must point to real files",
+    apply(refs, context) {
+      const fs = require("fs");
+      const path = require("path");
+      const repoRoot = (context && context.repoRoot) || process.cwd();
+      return refs.map((r) => {
+        if (!r.evidenceRefs || !r.evidenceRefs.length) return r;
+        const verified = [];
+        for (const ev of r.evidenceRefs) {
+          const abs = path.join(repoRoot, ev);
+          try { fs.accessSync(abs); verified.push(ev); } catch { /* skip fake */ }
+        }
+        return { ...r, evidenceRefs: verified };
+      });
+    },
+  },
+  {
+    id: "freshness-matters",
+    description: "Stale sources get penalties",
+    apply(refs) {
+      return refs.map((r) => {
+        if (r.freshness === "stale") return { ...r, authorityPenalty: (r.authorityPenalty || 0) + 3 };
+        if (r.freshness === "possibly_stale") return { ...r, authorityPenalty: (r.authorityPenalty || 0) + 1 };
+        return r;
+      });
+    },
+  },
+];
+
+function computeAuthorityScore(ref) {
+  const base = AUTHORITY_ORDER[ref.authority] || 1;
+  const boost = ref.authorityBoost || 0;
+  const penalty = ref.authorityPenalty || 0;
+  const proofBonus = (ref.evidenceRefs && ref.evidenceRefs.length > 0) ? 1 : 0;
+  return base + boost - penalty + proofBonus;
+}
+
+function applyAllRules(refs, context) {
+  let result = refs;
+  for (const rule of RULES) {
+    result = rule.apply(result, context);
+  }
+  return result;
+}
+
+function rankByAuthority(refs) {
+  return refs.slice().sort((a, b) => computeAuthorityScore(b) - computeAuthorityScore(a));
+}
+
+module.exports = {
+  AUTHORITY_ORDER,
+  RULES,
+  computeAuthorityScore,
+  applyAllRules,
+  rankByAuthority,
+};

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,
+};