gsd-pi 2.18.0 → 2.20.0

package/dist/resources/extensions/gsd/complexity-classifier.ts

@@ -0,0 +1,322 @@
+// GSD Extension — Complexity Classifier
+// Classifies unit complexity for dynamic model routing.
+// Pure heuristics + adaptive learning — no LLM calls. Sub-millisecond classification.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { getAdaptiveTierAdjustment } from "./routing-history.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type ComplexityTier = "light" | "standard" | "heavy";
+
+export interface ClassificationResult {
+  tier: ComplexityTier;
+  reason: string;
+  downgraded: boolean;   // true if budget pressure lowered the tier
+}
+
+export interface TaskMetadata {
+  fileCount?: number;
+  dependencyCount?: number;
+  isNewFile?: boolean;
+  tags?: string[];
+  estimatedLines?: number;
+  codeBlockCount?: number;      // number of fenced code blocks in plan
+  complexityKeywords?: string[]; // detected complexity signals
+}
+
+// ─── Unit Type → Default Tier Mapping ────────────────────────────────────────
+
+const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
+  // Tier 1 — Light: structured summaries, completion, UAT
+  "complete-slice": "light",
+  "run-uat": "light",
+
+  // Tier 2 — Standard: research, routine planning
+  "research-milestone": "standard",
+  "research-slice": "standard",
+  "plan-milestone": "standard",
+  "plan-slice": "standard",
+
+  // Tier 3 — Heavy: execution, replanning (requires deep reasoning)
+  "execute-task": "standard",   // default standard, upgraded by metadata
+  "replan-slice": "heavy",
+  "reassess-roadmap": "heavy",
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Classify unit complexity to determine which model tier to use.
+ *
+ * @param unitType    The type of unit being dispatched
+ * @param unitId      The unit ID (e.g. "M001/S01/T01")
+ * @param basePath    Project base path (for reading task plans)
+ * @param budgetPct   Current budget usage as fraction (0.0-1.0+), or undefined if no budget
+ * @param metadata    Optional pre-parsed task metadata
+ */
+export function classifyUnitComplexity(
+  unitType: string,
+  unitId: string,
+  basePath: string,
+  budgetPct?: number,
+  metadata?: TaskMetadata,
+): ClassificationResult {
+  // Hook units default to light
+  if (unitType.startsWith("hook/")) {
+    const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false };
+    return applyBudgetPressure(result, budgetPct);
+  }
+
+  // Start with the default tier for this unit type
+  let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
+  let reason = `unit type: ${unitType}`;
+
+  // For execute-task, analyze task metadata for complexity signals
+  if (unitType === "execute-task") {
+    const taskAnalysis = analyzeTaskComplexity(unitId, basePath, metadata);
+    tier = taskAnalysis.tier;
+    reason = taskAnalysis.reason;
+  }
+
+  // For plan-slice, check if the slice has many tasks (complex planning)
+  if (unitType === "plan-slice" || unitType === "plan-milestone") {
+    const planAnalysis = analyzePlanComplexity(unitId, basePath);
+    if (planAnalysis) {
+      tier = planAnalysis.tier;
+      reason = planAnalysis.reason;
+    }
+  }
+
+  // Adaptive learning: check if history suggests bumping the tier
+  const tags = metadata?.tags ?? extractTaskMetadata(unitId, basePath).tags;
+  const adaptiveAdjustment = getAdaptiveTierAdjustment(unitType, tier, tags);
+  if (adaptiveAdjustment && tierOrdinal(adaptiveAdjustment) > tierOrdinal(tier)) {
+    reason = `${reason} (adaptive: high failure rate at ${tier})`;
+    tier = adaptiveAdjustment;
+  }
+
+  const result: ClassificationResult = { tier, reason, downgraded: false };
+  return applyBudgetPressure(result, budgetPct);
+}
+
+/**
+ * Get a short label for the tier (for dashboard display).
+ */
+export function tierLabel(tier: ComplexityTier): string {
+  switch (tier) {
+    case "light": return "L";
+    case "standard": return "S";
+    case "heavy": return "H";
+  }
+}
+
+/**
+ * Get the tier ordering value (for comparison).
+ */
+export function tierOrdinal(tier: ComplexityTier): number {
+  switch (tier) {
+    case "light": return 0;
+    case "standard": return 1;
+    case "heavy": return 2;
+  }
+}
+
+// ─── Task Complexity Analysis ────────────────────────────────────────────────
+
+interface TaskAnalysis {
+  tier: ComplexityTier;
+  reason: string;
+}
+
+function analyzeTaskComplexity(
+  unitId: string,
+  basePath: string,
+  metadata?: TaskMetadata,
+): TaskAnalysis {
+  // Try to read task plan for complexity signals
+  const meta = metadata ?? extractTaskMetadata(unitId, basePath);
+
+  // Heavy signals
+  if (meta.dependencyCount && meta.dependencyCount >= 3) {
+    return { tier: "heavy", reason: `${meta.dependencyCount} dependencies` };
+  }
+  if (meta.fileCount && meta.fileCount >= 6) {
+    return { tier: "heavy", reason: `${meta.fileCount} files to modify` };
+  }
+  if (meta.estimatedLines && meta.estimatedLines >= 500) {
+    return { tier: "heavy", reason: `~${meta.estimatedLines} lines estimated` };
+  }
+
+  // Heavy signals from complexity keywords (Phase 4)
+  if (meta.complexityKeywords && meta.complexityKeywords.length >= 2) {
+    return { tier: "heavy", reason: `complex: ${meta.complexityKeywords.join(", ")}` };
+  }
+  if (meta.codeBlockCount && meta.codeBlockCount >= 5) {
+    return { tier: "heavy", reason: `${meta.codeBlockCount} code blocks in plan` };
+  }
+
+  // Standard signals from single complexity keyword
+  if (meta.complexityKeywords && meta.complexityKeywords.length === 1) {
+    return { tier: "standard", reason: `${meta.complexityKeywords[0]} task` };
+  }
+
+  // Light signals (simple tasks)
+  if (meta.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) {
+    return { tier: "light", reason: `simple task: ${meta.tags.join(", ")}` };
+  }
+  if (meta.fileCount !== undefined && meta.fileCount <= 1 && !meta.isNewFile) {
+    return { tier: "light", reason: "single file modification" };
+  }
+
+  // Standard by default
+  return { tier: "standard", reason: "standard execution task" };
+}
+
+function analyzePlanComplexity(
+  unitId: string,
+  basePath: string,
+): TaskAnalysis | null {
+  // Check if this is a milestone-level plan (more complex) vs single slice
+  const parts = unitId.split("/");
+  if (parts.length === 1) {
+    // Milestone-level planning is always at least standard
+    return { tier: "standard", reason: "milestone-level planning" };
+  }
+
+  // For slice planning, try to read the context/research to gauge complexity
+  // If research exists and is large, bump to heavy
+  const [mid, sid] = parts;
+  const researchPath = join(gsdRoot(basePath), mid, "slices", sid, "RESEARCH.md");
+  try {
+    if (existsSync(researchPath)) {
+      const content = readFileSync(researchPath, "utf-8");
+      const lineCount = content.split("\n").length;
+      if (lineCount > 200) {
+        return { tier: "heavy", reason: `complex slice: ${lineCount}-line research` };
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  return null; // Use default tier
+}
+
+/**
+ * Extract task metadata from the task plan file on disk.
+ */
+function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
+  const meta: TaskMetadata = {};
+  const parts = unitId.split("/");
+  if (parts.length !== 3) return meta;
+
+  const [mid, sid, tid] = parts;
+  const taskPlanPath = join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
+
+  try {
+    if (!existsSync(taskPlanPath)) return meta;
+    const content = readFileSync(taskPlanPath, "utf-8");
+    const lines = content.split("\n");
+
+    // Count files mentioned in "Files:" or "- Files:" lines
+    const fileLines = lines.filter(l => /^\s*-?\s*files?\s*:/i.test(l));
+    if (fileLines.length > 0) {
+      // Count comma-separated or bullet-pointed files
+      const allFiles = new Set<string>();
+      for (const line of fileLines) {
+        const filesStr = line.replace(/^\s*-?\s*files?\s*:\s*/i, "");
+        const files = filesStr.split(/[,;]/).map(f => f.trim()).filter(Boolean);
+        files.forEach(f => allFiles.add(f));
+      }
+      meta.fileCount = allFiles.size;
+    }
+
+    // Check for "new file" or "create" keywords
+    meta.isNewFile = lines.some(l => /\b(create|new file|scaffold|bootstrap)\b/i.test(l));
+
+    // Look for tags/labels in frontmatter or content
+    const tags: string[] = [];
+    if (content.match(/\b(refactor|migration|architect)/i)) tags.push("refactor");
+    if (content.match(/\b(test|spec|coverage)\b/i)) tags.push("test");
+    if (content.match(/\b(doc|readme|comment|jsdoc)\b/i)) tags.push("docs");
+    if (content.match(/\b(config|env|setting)\b/i)) tags.push("config");
+    if (content.match(/\b(rename|typo|spelling)\b/i)) tags.push("rename");
+    meta.tags = tags;
+
+    // Try to extract estimated lines from content
+    const estimateMatch = content.match(/~?\s*(\d+)\s*lines?\b/i);
+    if (estimateMatch) {
+      meta.estimatedLines = parseInt(estimateMatch[1], 10);
+    }
+
+    // Phase 4: Deeper introspection signals
+
+    // Count fenced code blocks (```) — more code blocks = more complex implementation
+    const codeBlockMatches = content.match(/^```/gm);
+    meta.codeBlockCount = codeBlockMatches ? Math.floor(codeBlockMatches.length / 2) : 0;
+
+    // Detect complexity keywords that suggest harder tasks
+    const complexityKeywords: string[] = [];
+    if (content.match(/\b(migration|migrate|schema change)\b/i)) complexityKeywords.push("migration");
+    if (content.match(/\b(architect|design pattern|system design)\b/i)) complexityKeywords.push("architecture");
+    if (content.match(/\b(security|auth|encrypt|credential|vulnerability)\b/i)) complexityKeywords.push("security");
+    if (content.match(/\b(performance|optimize|cache|index)\b/i)) complexityKeywords.push("performance");
+    if (content.match(/\b(concurrent|parallel|race condition|mutex|lock)\b/i)) complexityKeywords.push("concurrency");
+    if (content.match(/\b(backward.?compat|breaking change|deprecat)\b/i)) complexityKeywords.push("compatibility");
+    meta.complexityKeywords = complexityKeywords;
+  } catch {
+    // Non-fatal — metadata extraction is best-effort
+  }
+
+  return meta;
+}
+
+// ─── Budget Pressure ─────────────────────────────────────────────────────────
+
+/**
+ * Apply budget pressure to a classification result.
+ * As budget usage increases, more aggressively downgrade tiers.
+ *
+ * - <50%:   Normal classification (no change)
+ * - 50-75%: Tier 2 → Tier 1 where possible
+ * - 75-90%: Only heavy tasks keep configured model
+ * - >90%:   Everything except replan-slice gets cheapest model
+ */
+function applyBudgetPressure(
+  result: ClassificationResult,
+  budgetPct?: number,
+): ClassificationResult {
+  if (budgetPct === undefined || budgetPct < 0.5) return result;
+
+  const original = result.tier;
+
+  if (budgetPct >= 0.9) {
+    // >90%: almost everything goes to light
+    if (result.tier !== "heavy") {
+      result.tier = "light";
+    } else {
+      // Even heavy gets downgraded to standard
+      result.tier = "standard";
+    }
+  } else if (budgetPct >= 0.75) {
+    // 75-90%: only heavy stays, everything else goes to light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  } else {
+    // 50-75%: standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  }
+
+  if (result.tier !== original) {
+    result.downgraded = true;
+    result.reason = `${result.reason} (budget pressure: ${Math.round(budgetPct * 100)}%)`;
+  }
+
+  return result;
+}

package/dist/resources/extensions/gsd/context-budget.ts

@@ -0,0 +1,243 @@
+/**
+ * Context budget engine — proportional allocation, section-boundary truncation,
+ * and executor context window resolution.
+ *
+ * All functions are pure or near-pure (dependency-injected). No global state, no I/O.
+ * Budget ratios are module-level constants for easy tuning.
+ *
+ * @see D001 (module location), D002 (200K fallback), D003 (section-boundary truncation)
+ */
+
+// ─── Budget ratio constants ──────────────────────────────────────────────────
+// Percentages of total context window allocated to each budget category.
+// These are applied after tokens→chars conversion.
+
+/** Proportion of context window for dependency/prior-task summaries */
+const SUMMARY_RATIO = 0.15;
+
+/** Proportion of context window for inline context (plans, decisions, code) */
+const INLINE_CONTEXT_RATIO = 0.40;
+
+/** Proportion of context window for verification sections in prompts */
+const VERIFICATION_RATIO = 0.10;
+
+/** Approximate chars-per-token conversion factor */
+const CHARS_PER_TOKEN = 4;
+
+/** Default context window when none can be resolved (D002) */
+const DEFAULT_CONTEXT_WINDOW = 200_000;
+
+/** Percentage of context consumed before suggesting a continue-here checkpoint */
+const CONTINUE_THRESHOLD_PERCENT = 70;
+
+// ─── Task count bounds ───────────────────────────────────────────────────────
+// Task count range scales with context window. Smaller windows get fewer tasks
+// to avoid overloading the executor.
+
+const TASK_COUNT_MIN = 2;
+
+/** Task count ceiling tiers: [contextWindowThreshold, maxTasks] */
+const TASK_COUNT_TIERS: [number, number][] = [
+  [500_000, 8],   // 500K+ tokens → up to 8 tasks
+  [200_000, 6],   // 200K+ tokens → up to 6 tasks
+  [128_000, 5],   // 128K+ tokens → up to 5 tasks
+  [0, 3],         // anything smaller → up to 3 tasks
+];
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TruncationResult {
+  /** The (possibly truncated) content string */
+  content: string;
+  /** Number of sections dropped during truncation; 0 when content fits */
+  droppedSections: number;
+}
+
+export interface BudgetAllocation {
+  /** Character budget for dependency/prior-task summaries */
+  summaryBudgetChars: number;
+  /** Character budget for inline context (plans, decisions, code snippets) */
+  inlineContextBudgetChars: number;
+  /** Recommended task count range for the executor at this context window */
+  taskCountRange: { min: number; max: number };
+  /** Percentage of context consumed before suggesting a continue-here checkpoint */
+  continueThresholdPercent: number;
+  /** Character budget for verification sections */
+  verificationBudgetChars: number;
+}
+
+// ─── Minimal interface slices for dependency injection ───────────────────────
+// These avoid coupling to full ModelRegistry/GSDPreferences types in tests.
+
+export interface MinimalModel {
+  id: string;
+  provider: string;
+  contextWindow: number;
+}
+
+export interface MinimalModelRegistry {
+  getAll(): MinimalModel[];
+}
+
+export interface MinimalPreferences {
+  models?: {
+    execution?: string | { model: string; fallbacks?: string[] };
+  };
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Compute proportional budget allocations from a context window size (in tokens).
+ *
+ * Returns deterministic output for any given input. Invalid inputs (≤ 0)
+ * silently default to 200K (D002).
+ */
+export function computeBudgets(contextWindow: number): BudgetAllocation {
+  const effectiveWindow = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
+  const totalChars = effectiveWindow * CHARS_PER_TOKEN;
+
+  return {
+    summaryBudgetChars: Math.floor(totalChars * SUMMARY_RATIO),
+    inlineContextBudgetChars: Math.floor(totalChars * INLINE_CONTEXT_RATIO),
+    verificationBudgetChars: Math.floor(totalChars * VERIFICATION_RATIO),
+    continueThresholdPercent: CONTINUE_THRESHOLD_PERCENT,
+    taskCountRange: {
+      min: TASK_COUNT_MIN,
+      max: resolveTaskCountMax(effectiveWindow),
+    },
+  };
+}
+
+/**
+ * Truncate content at markdown section boundaries to fit within a character budget.
+ *
+ * Splits on `### ` headings and `---` dividers. Keeps whole sections that fit.
+ * Appends `[...truncated N sections]` when content is dropped.
+ * Returns content unchanged when it fits within budget.
+ *
+ * @see D003 — section-boundary truncation is mandatory; mid-section cuts are unacceptable.
+ */
+export function truncateAtSectionBoundary(content: string, budgetChars: number): TruncationResult {
+  if (!content || content.length <= budgetChars) {
+    return { content, droppedSections: 0 };
+  }
+
+  // Split on section markers: ### headings or --- dividers (on their own line)
+  const sections = splitIntoSections(content);
+
+  if (sections.length <= 1) {
+    // No section markers — keep as much as fits from the start
+    const truncated = content.slice(0, budgetChars);
+    return { content: truncated + "\n\n[...truncated 1 sections]", droppedSections: 1 };
+  }
+
+  // Greedily keep sections that fit
+  let usedChars = 0;
+  let keptCount = 0;
+
+  for (const section of sections) {
+    const sectionLen = section.length;
+    if (usedChars + sectionLen > budgetChars && keptCount > 0) {
+      break;
+    }
+    // Always keep at least the first section (even if it exceeds budget)
+    usedChars += sectionLen;
+    keptCount++;
+    if (usedChars >= budgetChars) break;
+  }
+
+  const droppedCount = sections.length - keptCount;
+  if (droppedCount === 0) {
+    return { content, droppedSections: 0 };
+  }
+
+  const kept = sections.slice(0, keptCount).join("");
+  return {
+    content: kept.trimEnd() + `\n\n[...truncated ${droppedCount} sections]`,
+    droppedSections: droppedCount,
+  };
+}
+
+/**
+ * Resolve the executor model's context window size using a fallback chain:
+ *
+ * 1. Look up the configured executor model ID in preferences → find in registry → return contextWindow
+ * 2. Fall back to sessionContextWindow if provided
+ * 3. Fall back to 200K default (D002)
+ *
+ * Supports "provider/model" format in preferences for explicit provider targeting.
+ */
+export function resolveExecutorContextWindow(
+  registry: MinimalModelRegistry | undefined,
+  preferences: MinimalPreferences | undefined,
+  sessionContextWindow?: number,
+): number {
+  // Step 1: Try configured executor model
+  if (preferences?.models?.execution && registry) {
+    const executionConfig = preferences.models.execution;
+    const modelId = typeof executionConfig === "string"
+      ? executionConfig
+      : executionConfig.model;
+
+    if (modelId) {
+      const model = findModelById(registry, modelId);
+      if (model && model.contextWindow > 0) {
+        return model.contextWindow;
+      }
+    }
+  }
+
+  // Step 2: Fall back to session context window
+  if (sessionContextWindow && sessionContextWindow > 0) {
+    return sessionContextWindow;
+  }
+
+  // Step 3: Fall back to default (D002)
+  return DEFAULT_CONTEXT_WINDOW;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Resolve task count ceiling from context window size.
+ * Larger windows support more tasks per slice.
+ */
+function resolveTaskCountMax(contextWindow: number): number {
+  for (const [threshold, max] of TASK_COUNT_TIERS) {
+    if (contextWindow >= threshold) return max;
+  }
+  return 3; // fallback — unreachable given tiers include 0
+}
+
+/**
+ * Split content into sections at `### ` headings or `---` dividers.
+ * Each section includes its leading marker.
+ */
+function splitIntoSections(content: string): string[] {
+  // Match section boundaries: ### heading or --- divider at start of line
+  const pattern = /^(?=### |\-{3,}\s*$)/m;
+  const parts = content.split(pattern).filter(p => p.length > 0);
+  return parts;
+}
+
+/**
+ * Find a model in the registry by ID string.
+ * Supports "provider/model" format for explicit provider targeting,
+ * or bare model ID (first match wins).
+ */
+function findModelById(registry: MinimalModelRegistry, modelId: string): MinimalModel | undefined {
+  const allModels = registry.getAll();
+  const slashIdx = modelId.indexOf("/");
+
+  if (slashIdx !== -1) {
+    const provider = modelId.substring(0, slashIdx).toLowerCase();
+    const id = modelId.substring(slashIdx + 1).toLowerCase();
+    return allModels.find(
+      m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === id,
+    );
+  }
+
+  // Bare ID — first match
+  return allModels.find(m => m.id === modelId);
+}