gsd-pi 2.19.0 → 2.20.0

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

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

@@ -0,0 +1,195 @@
+// GSD Context Store — Query Layer & Formatters
+//
+// Typed query functions for decisions and requirements from the DB views,
+// with optional filtering. Format functions produce prompt-injectable markdown.
+// All functions degrade gracefully: return empty results when DB unavailable, never throw.
+
+import { isDbAvailable, _getAdapter } from './gsd-db.js';
+import type { Decision, Requirement } from './types.js';
+
+// ─── Query Functions ───────────────────────────────────────────────────────
+
+export interface DecisionQueryOpts {
+  milestoneId?: string;
+  scope?: string;
+}
+
+export interface RequirementQueryOpts {
+  sliceId?: string;
+  status?: string;
+}
+
+/**
+ * Query active (non-superseded) decisions with optional filters.
+ * - milestoneId: filters where when_context LIKE '%milestoneId%'
+ * - scope: filters where scope = :scope (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryDecisions(opts?: DecisionQueryOpts): Decision[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = ['superseded_by IS NULL'];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.milestoneId) {
+      clauses.push('when_context LIKE :milestone_pattern');
+      params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+    }
+
+    if (opts?.scope) {
+      clauses.push('scope = :scope');
+      params[':scope'] = opts.scope;
+    }
+
+    const sql = `SELECT * FROM decisions WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+    const rows = adapter.prepare(sql).all(params);
+
+    return rows.map(row => ({
+      seq: row['seq'] as number,
+      id: row['id'] as string,
+      when_context: row['when_context'] as string,
+      scope: row['scope'] as string,
+      decision: row['decision'] as string,
+      choice: row['choice'] as string,
+      rationale: row['rationale'] as string,
+      revisable: row['revisable'] as string,
+      superseded_by: null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Query active (non-superseded) requirements with optional filters.
+ * - sliceId: filters where primary_owner LIKE '%sliceId%' OR supporting_slices LIKE '%sliceId%'
+ * - status: filters where status = :status (exact match)
+ *
+ * Returns [] if DB is not available. Never throws.
+ */
+export function queryRequirements(opts?: RequirementQueryOpts): Requirement[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = ['superseded_by IS NULL'];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.sliceId) {
+      clauses.push('(primary_owner LIKE :slice_pattern OR supporting_slices LIKE :slice_pattern)');
+      params[':slice_pattern'] = `%${opts.sliceId}%`;
+    }
+
+    if (opts?.status) {
+      clauses.push('status = :status');
+      params[':status'] = opts.status;
+    }
+
+    const sql = `SELECT * FROM requirements WHERE ${clauses.join(' AND ')} ORDER BY id`;
+    const rows = adapter.prepare(sql).all(params);
+
+    return rows.map(row => ({
+      id: row['id'] as string,
+      class: row['class'] as string,
+      status: row['status'] as string,
+      description: row['description'] as string,
+      why: row['why'] as string,
+      source: row['source'] as string,
+      primary_owner: row['primary_owner'] as string,
+      supporting_slices: row['supporting_slices'] as string,
+      validation: row['validation'] as string,
+      notes: row['notes'] as string,
+      full_content: row['full_content'] as string,
+      superseded_by: null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ─── Format Functions ──────────────────────────────────────────────────────
+
+/**
+ * Format decisions as a markdown table matching DECISIONS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatDecisionsForPrompt(decisions: Decision[]): string {
+  if (decisions.length === 0) return '';
+
+  const header = '| # | When | Scope | Decision | Choice | Rationale | Revisable? |';
+  const separator = '|---|------|-------|----------|--------|-----------|------------|';
+  const rows = decisions.map(d =>
+    `| ${d.id} | ${d.when_context} | ${d.scope} | ${d.decision} | ${d.choice} | ${d.rationale} | ${d.revisable} |`,
+  );
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format requirements as structured H3 sections matching REQUIREMENTS.md format.
+ * Returns empty string for empty input.
+ */
+export function formatRequirementsForPrompt(requirements: Requirement[]): string {
+  if (requirements.length === 0) return '';
+
+  return requirements.map(r => {
+    const lines: string[] = [
+      `### ${r.id}: ${r.description}`,
+      '',
+      `- **Class:** ${r.class}`,
+      `- **Status:** ${r.status}`,
+      `- **Why:** ${r.why}`,
+      `- **Source:** ${r.source}`,
+      `- **Primary Owner:** ${r.primary_owner}`,
+    ];
+
+    if (r.supporting_slices) {
+      lines.push(`- **Supporting Slices:** ${r.supporting_slices}`);
+    }
+
+    lines.push(`- **Validation:** ${r.validation}`);
+
+    if (r.notes) {
+      lines.push(`- **Notes:** ${r.notes}`);
+    }
+
+    return lines.join('\n');
+  }).join('\n\n');
+}
+
+// ─── Artifact Query Functions ──────────────────────────────────────────────
+
+/**
+ * Query a hierarchy artifact by its relative path.
+ * Returns the full_content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryArtifact(path: string): string | null {
+  if (!isDbAvailable()) return null;
+  const adapter = _getAdapter();
+  if (!adapter) return null;
+
+  try {
+    const row = adapter.prepare('SELECT full_content FROM artifacts WHERE path = :path').get({ ':path': path });
+    if (!row) return null;
+    const content = row['full_content'] as string;
+    return content || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query PROJECT.md content from the artifacts table.
+ * PROJECT.md is stored with the relative path 'PROJECT.md' by the importer.
+ * Returns the content string or null if not found/unavailable.
+ * Never throws.
+ */
+export function queryProject(): string | null {
+  return queryArtifact('PROJECT.md');
+}

package/dist/resources/extensions/gsd/dashboard-overlay.ts

@@ -15,6 +15,7 @@ import { getAutoDashboardData, type AutoDashboardData } from "./auto.js";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, formatCost, formatTokenCount, formatCostProjection,
+  type UnitMetrics,
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getActiveWorktreeName } from "./worktree-command.js";
@@ -413,11 +414,33 @@ export class GSDDashboardOverlay {
       lines.push(row(th.fg("text", th.bold("Completed"))));
       lines.push(blank());
 
+      // Build ledger lookup for budget indicators (last entry wins for retries)
+      const ledgerLookup = new Map<string, UnitMetrics>();
+      const currentLedger = getLedger();
+      if (currentLedger) {
+        for (const lu of currentLedger.units) {
+          ledgerLookup.set(`${lu.type}:${lu.id}`, lu);
+        }
+      }
+
       const recent = [...this.dashData.completedUnits].reverse().slice(0, 10);
       for (const u of recent) {
         const left = `  ${th.fg("success", "✓")} ${th.fg("muted", unitLabel(u.type))} ${th.fg("muted", u.id)}`;
+
+        // Budget indicators from ledger
+        const ledgerEntry = ledgerLookup.get(`${u.type}:${u.id}`);
+        let budgetMarkers = "";
+        if (ledgerEntry) {
+          if (ledgerEntry.truncationSections && ledgerEntry.truncationSections > 0) {
+            budgetMarkers += th.fg("warning", ` ▼${ledgerEntry.truncationSections}`);
+          }
+          if (ledgerEntry.continueHereFired === true) {
+            budgetMarkers += th.fg("error", " → wrap-up");
+          }
+        }
+
         const right = th.fg("dim", formatDuration(u.finishedAt - u.startedAt));
-        lines.push(row(joinColumns(left, right, contentWidth)));
+        lines.push(row(joinColumns(`${left}${budgetMarkers}`, right, contentWidth)));
       }
 
       if (this.dashData.completedUnits.length > 10) {
@@ -448,6 +471,18 @@ export class GSDDashboardOverlay {
         `${th.fg("dim", "cache-w:")} ${th.fg("text", formatTokenCount(totals.tokens.cacheWrite))}`,
       ], contentWidth, "  ")));
 
+      // Budget aggregate line — only when data exists
+      if (totals.totalTruncationSections > 0 || totals.continueHereFiredCount > 0) {
+        const budgetParts: string[] = [];
+        if (totals.totalTruncationSections > 0) {
+          budgetParts.push(th.fg("warning", `${totals.totalTruncationSections} sections truncated`));
+        }
+        if (totals.continueHereFiredCount > 0) {
+          budgetParts.push(th.fg("error", `${totals.continueHereFiredCount} continue-here fired`));
+        }
+        lines.push(row(budgetParts.join(`  ${th.fg("dim", "·")}  `)));
+      }
+
       const phases = aggregateByPhase(ledger.units);
       if (phases.length > 0) {
         lines.push(blank());
@@ -492,14 +527,17 @@ export class GSDDashboardOverlay {
       }
 
       const models = aggregateByModel(ledger.units);
-      if (models.length > 1) {
+      if (models.length >= 1) {
         lines.push(blank());
         lines.push(row(th.fg("dim", "By Model")));
         for (const m of models) {
           const pct = totals.cost > 0 ? Math.round((m.cost / totals.cost) * 100) : 0;
           const modelName = truncateToWidth(m.model, 38);
+          const ctxWindow = m.contextWindowTokens !== undefined
+            ? th.fg("dim", ` [${formatTokenCount(m.contextWindowTokens)}]`)
+            : "";
           const left = `  ${th.fg("text", modelName.padEnd(38))}${th.fg("warning", formatCost(m.cost).padStart(8))}`;
-          const right = th.fg("dim", `${String(pct).padStart(3)}%  ${m.units} units`);
+          const right = th.fg("dim", `${String(pct).padStart(3)}%  ${m.units} units`) + ctxWindow;
           lines.push(row(joinColumns(left, right, contentWidth)));
         }
       }