pan-wizard 2.8.1

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -0,0 +1,150 @@
+/**
+ * Context Budget — Estimate context utilization and quality for current phase
+ *
+ * Reads state.md, phase plans, and config to produce a context health report.
+ * Makes PAN's context rot prevention visible and measurable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, loadConfig, findPhaseInternal, toPosix } = require('./core.cjs');
+const { planningPath, phasesPath, fileAccessible } = require('./utils.cjs');
+const { STATE_FILE, ROADMAP_FILE, PROJECT_FILE, isPlanFile, isSummaryFile, CHARS_PER_TOKEN, CONTEXT_WINDOW, WARNING_THRESHOLD, CRITICAL_THRESHOLD } = require('./constants.cjs');
+
+/**
+ * Estimate token count from text content.
+ * @param {string} text - Text content
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Compute context budget for the current project state.
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - If true, output human-readable string
+ */
+function cmdContextBudget(cwd, raw) {
+  const planDir = planningPath(cwd);
+  if (!fileAccessible(planDir)) {
+    return output({ error: '.planning/ directory not found', hint: 'Run /pan:new-project to initialize' }, raw,
+      'Error: .planning/ directory not found\nHint: Run /pan:new-project to initialize');
+  }
+
+  const config = loadConfig(cwd);
+
+  // Read core files and estimate tokens
+  const stateContent = safeReadFile(path.join(planDir, STATE_FILE));
+  const roadmapContent = safeReadFile(path.join(planDir, ROADMAP_FILE));
+  const projectContent = safeReadFile(path.join(planDir, PROJECT_FILE));
+
+  const stateTokens = estimateTokens(stateContent);
+  const roadmapTokens = estimateTokens(roadmapContent);
+  const projectTokens = estimateTokens(projectContent);
+
+  // Find current phase and estimate plan tokens
+  let currentPhase = null;
+  let planTokens = 0;
+  let planCount = 0;
+  let incompletePlanCount = 0;
+  let phaseDir = null;
+
+  if (stateContent) {
+    const phaseMatch = stateContent.match(/\*\*Current Phase:\*\*\s*(\S+)/);
+    if (phaseMatch) {
+      currentPhase = phaseMatch[1];
+      const phaseInfo = findPhaseInternal(cwd, currentPhase);
+      if (phaseInfo && phaseInfo.found) {
+        phaseDir = phaseInfo.directory;
+        planCount = phaseInfo.plans.length;
+        incompletePlanCount = phaseInfo.incomplete_plans.length;
+
+        // Estimate plan tokens
+        const fullPhasePath = path.join(cwd, phaseInfo.directory);
+        for (const planFile of phaseInfo.plans) {
+          const planContent = safeReadFile(path.join(fullPhasePath, planFile));
+          planTokens += estimateTokens(planContent);
+        }
+      }
+    }
+  }
+
+  // Calculate totals
+  const contextTokens = stateTokens + roadmapTokens + projectTokens;
+  const totalTokens = contextTokens + planTokens;
+  const utilization = totalTokens / CONTEXT_WINDOW;
+
+  // Determine status
+  let status = 'healthy';
+  if (!currentPhase) {
+    status = 'idle';
+  } else if (utilization >= CRITICAL_THRESHOLD) {
+    status = 'critical';
+  } else if (utilization >= WARNING_THRESHOLD) {
+    status = 'warning';
+  }
+
+  // Generate recommendation
+  let recommendation;
+  if (status === 'idle') {
+    recommendation = 'No active phase. Run /pan:plan-phase to start.';
+  } else if (status === 'critical') {
+    recommendation = 'Context budget near limit. Consider splitting this phase into smaller phases.';
+  } else if (status === 'warning') {
+    recommendation = 'Context usage is elevated. Monitor quality during execution.';
+  } else {
+    const remainingTokens = CONTEXT_WINDOW - totalTokens;
+    const avgPlanTokens = planCount > 0 ? Math.ceil(planTokens / planCount) : 5000;
+    const additionalPlans = avgPlanTokens > 0 ? Math.floor(remainingTokens / avgPlanTokens) : 0;
+    recommendation = `Within budget. ~${additionalPlans} more plans could fit before degradation.`;
+  }
+
+  const result = {
+    status,
+    currentPhase: currentPhase || null,
+    phaseDirectory: phaseDir ? toPosix(phaseDir) : null,
+    plans: planCount,
+    incompletePlans: incompletePlanCount,
+    modelProfile: config.model_profile,
+    tokens: {
+      project: projectTokens,
+      roadmap: roadmapTokens,
+      state: stateTokens,
+      plans: planTokens,
+      total: totalTokens,
+    },
+    contextWindow: CONTEXT_WINDOW,
+    budgetUtilization: Math.round(utilization * 1000) / 1000,
+    recommendation,
+  };
+
+  if (raw) {
+    const lines = [
+      `Context Budget: ${status.toUpperCase()}`,
+      ``,
+      `Current Phase: ${currentPhase || 'none'}`,
+      `Model Profile: ${config.model_profile}`,
+      `Plans: ${planCount} total, ${incompletePlanCount} incomplete`,
+      ``,
+      `Token Estimates:`,
+      `  project.md:  ${projectTokens.toLocaleString()}`,
+      `  roadmap.md:  ${roadmapTokens.toLocaleString()}`,
+      `  state.md:    ${stateTokens.toLocaleString()}`,
+      `  Phase Plans: ${planTokens.toLocaleString()}`,
+      `  Total:       ${totalTokens.toLocaleString()} / ${CONTEXT_WINDOW.toLocaleString()}`,
+      ``,
+      `Utilization: ${(utilization * 100).toFixed(1)}%`,
+      `${recommendation}`,
+    ];
+    return output(result, true, lines.join('\n'));
+  }
+
+  return output(result, false);
+}
+
+module.exports = {
+  cmdContextBudget,
+  estimateTokens,
+};