gsd-pi 2.19.0 → 2.20.0

package/src/resources/extensions/gsd/skill-telemetry.ts

@@ -0,0 +1,127 @@
+/**
+ * GSD Skill Telemetry — Track which skills are loaded per unit (#599)
+ *
+ * Captures skill names at dispatch time for inclusion in UnitMetrics.
+ * Distinguishes between "available" skills (in system prompt) and
+ * "actively loaded" skills (read via tool calls during execution).
+ *
+ * Data flow:
+ *   1. At dispatch, captureAvailableSkills() records skills from the system prompt
+ *   2. During execution, recordSkillRead() tracks explicit SKILL.md reads
+ *   3. At unit completion, getAndClearSkills() returns the loaded list for metrics
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+
+// ─── In-memory state ──────────────────────────────────────────────────────────
+
+/** Skills available in the system prompt for the current unit */
+let availableSkills: string[] = [];
+
+/** Skills explicitly read (SKILL.md loaded) during the current unit */
+const activelyLoadedSkills = new Set<string>();
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Capture the list of available skill names at dispatch time.
+ * Called before each unit starts.
+ */
+export function captureAvailableSkills(): void {
+  const skillsDir = join(getAgentDir(), "skills");
+  availableSkills = listSkillNames(skillsDir);
+  activelyLoadedSkills.clear();
+}
+
+/**
+ * Record that a skill was actively loaded (its SKILL.md was read).
+ * Call this when the agent reads a SKILL.md file.
+ */
+export function recordSkillRead(skillName: string): void {
+  activelyLoadedSkills.add(skillName);
+}
+
+/**
+ * Get the skill names for the current unit and clear state.
+ * Returns actively loaded skills if any, otherwise available skills.
+ * This gives the most useful signal: if the agent read specific skills,
+ * report those; otherwise report what was available.
+ */
+export function getAndClearSkills(): string[] {
+  const result = activelyLoadedSkills.size > 0
+    ? Array.from(activelyLoadedSkills)
+    : [...availableSkills];
+  availableSkills = [];
+  activelyLoadedSkills.clear();
+  return result;
+}
+
+/**
+ * Reset all telemetry state. Called when auto-mode stops.
+ */
+export function resetSkillTelemetry(): void {
+  availableSkills = [];
+  activelyLoadedSkills.clear();
+}
+
+/**
+ * Get last-used timestamps for all skills from metrics data.
+ * Returns a Map from skill name to most recent ms timestamp.
+ */
+export function getSkillLastUsed(units: Array<{ finishedAt: number; skills?: string[] }>): Map<string, number> {
+  const lastUsed = new Map<string, number>();
+  for (const u of units) {
+    if (!u.skills) continue;
+    for (const skill of u.skills) {
+      const existing = lastUsed.get(skill) ?? 0;
+      if (u.finishedAt > existing) {
+        lastUsed.set(skill, u.finishedAt);
+      }
+    }
+  }
+  return lastUsed;
+}
+
+/**
+ * Detect stale skills — those not used within the given threshold (in days).
+ * Returns skill names that should be deprioritized.
+ */
+export function detectStaleSkills(
+  units: Array<{ finishedAt: number; skills?: string[] }>,
+  thresholdDays: number,
+): string[] {
+  if (thresholdDays <= 0) return [];
+
+  const lastUsed = getSkillLastUsed(units);
+  const cutoff = Date.now() - (thresholdDays * 24 * 60 * 60 * 1000);
+  const stale: string[] = [];
+
+  // Check all installed skills, not just those with usage data
+  const skillsDir = join(getAgentDir(), "skills");
+  const installed = listSkillNames(skillsDir);
+
+  for (const skill of installed) {
+    const lastTs = lastUsed.get(skill);
+    if (lastTs === undefined || lastTs < cutoff) {
+      stale.push(skill);
+    }
+  }
+
+  return stale;
+}
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+function listSkillNames(skillsDir: string): string[] {
+  if (!existsSync(skillsDir)) return [];
+  try {
+    return readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith("."))
+      .filter(d => existsSync(join(skillsDir, d.name, "SKILL.md")))
+      .map(d => d.name);
+  } catch {
+    return [];
+  }
+}

package/src/resources/extensions/gsd/state.ts

@@ -32,8 +32,10 @@ import {
 
 import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
+import { isDbAvailable, _getAdapter } from './gsd-db.js';
 
 import { join, resolve } from 'path';
+import { debugCount, debugTime } from './debug-logger.js';
 
 // ─── Query Functions ───────────────────────────────────────────────────────
 
@@ -116,7 +118,10 @@ export async function deriveState(basePath: string): Promise<GSDState> {
     return _stateCache.result;
   }
 
+  const stopTimer = debugTime("derive-state-impl");
   const result = await _deriveStateImpl(basePath);
+  stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
+  debugCount("deriveStateCalls");
   _stateCache = { basePath, result, timestamp: Date.now() };
   return result;
 }
@@ -131,6 +136,30 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
   const fileContentCache = new Map<string, string>();
   const gsdDir = gsdRoot(basePath);
 
+  // ── DB-first content loading ──
+  // When the DB is available, load artifact content from the artifacts table
+  // (indexed SELECT instead of O(N) file I/O). Falls back to native Rust batch
+  // parser, which in turn falls back to sequential JS reads via cachedLoadFile.
+  let dbContentLoaded = false;
+  if (isDbAvailable()) {
+    const adapter = _getAdapter();
+    if (adapter) {
+      try {
+        const rows = adapter.prepare('SELECT path, full_content FROM artifacts').all();
+        for (const row of rows) {
+          const relPath = (row as Record<string, unknown>)['path'] as string;
+          const content = (row as Record<string, unknown>)['full_content'] as string;
+          const absPath = resolve(gsdDir, relPath);
+          fileContentCache.set(absPath, content);
+        }
+        dbContentLoaded = rows.length > 0;
+      } catch {
+        // DB query failed — fall through to native batch parse
+      }
+    }
+  }
+
+  if (!dbContentLoaded) {
   const batchFiles = nativeBatchParseGsdFiles(gsdDir);
   if (batchFiles) {
     for (const f of batchFiles) {
@@ -138,6 +167,7 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       fileContentCache.set(absPath, f.rawContent);
     }
   }
+  }
 
   /**
    * Load file content from batch cache first, falling back to disk read.

package/src/resources/extensions/gsd/templates/preferences.md

@@ -1,5 +1,6 @@
 ---
 version: 1
+mode:
 always_use_skills: []
 prefer_skills: []
 avoid_skills: []

package/src/resources/extensions/gsd/tests/context-budget.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Unit tests for context-budget.ts — the budget engine.
+ * Tests pure functions with dependency-injected fakes.
+ * No I/O, no extension context, no global state.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  type BudgetAllocation,
+  type MinimalModel,
+  type MinimalModelRegistry,
+  type MinimalPreferences,
+  type TruncationResult,
+  computeBudgets,
+  truncateAtSectionBoundary,
+  resolveExecutorContextWindow,
+} from "../context-budget.js";
+
+// ─── Test helpers ─────────────────────────────────────────────────────────────
+
+function makeRegistry(models: MinimalModel[]): MinimalModelRegistry {
+  return { getAll: () => models };
+}
+
+function makeModel(id: string, provider: string, contextWindow: number): MinimalModel {
+  return { id, provider, contextWindow };
+}
+
+// ─── computeBudgets ──────────────────────────────────────────────────────────
+
+describe("context-budget: computeBudgets", () => {
+  it("returns proportional allocations for 128K context window", () => {
+    const b = computeBudgets(128_000);
+    // 128K tokens × 4 chars/token = 512K chars total
+    assert.equal(b.summaryBudgetChars, Math.floor(512_000 * 0.15));
+    assert.equal(b.inlineContextBudgetChars, Math.floor(512_000 * 0.40));
+    assert.equal(b.verificationBudgetChars, Math.floor(512_000 * 0.10));
+    assert.equal(b.continueThresholdPercent, 70);
+    assert.equal(b.taskCountRange.min, 2);
+    assert.equal(b.taskCountRange.max, 5);
+  });
+
+  it("returns proportional allocations for 200K context window", () => {
+    const b = computeBudgets(200_000);
+    // 200K tokens × 4 = 800K chars
+    assert.equal(b.summaryBudgetChars, Math.floor(800_000 * 0.15));
+    assert.equal(b.inlineContextBudgetChars, Math.floor(800_000 * 0.40));
+    assert.equal(b.verificationBudgetChars, Math.floor(800_000 * 0.10));
+    assert.equal(b.taskCountRange.min, 2);
+    assert.equal(b.taskCountRange.max, 6);
+  });
+
+  it("returns proportional allocations for 1M context window", () => {
+    const b = computeBudgets(1_000_000);
+    // 1M tokens × 4 = 4M chars
+    assert.equal(b.summaryBudgetChars, Math.floor(4_000_000 * 0.15));
+    assert.equal(b.inlineContextBudgetChars, Math.floor(4_000_000 * 0.40));
+    assert.equal(b.verificationBudgetChars, Math.floor(4_000_000 * 0.10));
+    assert.equal(b.taskCountRange.min, 2);
+    assert.equal(b.taskCountRange.max, 8);
+  });
+
+  it("scales proportionally — 1M > 200K > 128K for all budget fields", () => {
+    const b128 = computeBudgets(128_000);
+    const b200 = computeBudgets(200_000);
+    const b1M = computeBudgets(1_000_000);
+
+    assert.ok(b1M.summaryBudgetChars > b200.summaryBudgetChars);
+    assert.ok(b200.summaryBudgetChars > b128.summaryBudgetChars);
+
+    assert.ok(b1M.inlineContextBudgetChars > b200.inlineContextBudgetChars);
+    assert.ok(b200.inlineContextBudgetChars > b128.inlineContextBudgetChars);
+
+    assert.ok(b1M.verificationBudgetChars > b200.verificationBudgetChars);
+    assert.ok(b200.verificationBudgetChars > b128.verificationBudgetChars);
+
+    assert.ok(b1M.taskCountRange.max >= b200.taskCountRange.max);
+    assert.ok(b200.taskCountRange.max >= b128.taskCountRange.max);
+  });
+
+  it("enforces task count floor (min ≥ 2) at all sizes", () => {
+    for (const size of [128_000, 200_000, 1_000_000, 50_000]) {
+      const b = computeBudgets(size);
+      assert.ok(b.taskCountRange.min >= 2, `min should be ≥ 2 at ${size}, got ${b.taskCountRange.min}`);
+    }
+  });
+
+  it("task count ceiling exists and is bounded", () => {
+    const b = computeBudgets(10_000_000); // very large window
+    assert.ok(b.taskCountRange.max <= 8, `max should be capped, got ${b.taskCountRange.max}`);
+    assert.ok(b.taskCountRange.max >= b.taskCountRange.min);
+  });
+
+  it("handles zero input gracefully — defaults to 200K", () => {
+    const b = computeBudgets(0);
+    const b200 = computeBudgets(200_000);
+    assert.deepStrictEqual(b, b200);
+  });
+
+  it("handles negative input gracefully — defaults to 200K", () => {
+    const b = computeBudgets(-100);
+    const b200 = computeBudgets(200_000);
+    assert.deepStrictEqual(b, b200);
+  });
+});
+
+// ─── truncateAtSectionBoundary ───────────────────────────────────────────────
+
+describe("context-budget: truncateAtSectionBoundary", () => {
+  it("returns content unchanged when under budget", () => {
+    const content = "### Section 1\nSome text.\n\n### Section 2\nMore text.";
+    const result = truncateAtSectionBoundary(content, 10_000);
+    assert.equal(result.content, content);
+    assert.equal(result.droppedSections, 0);
+  });
+
+  it("returns empty string unchanged", () => {
+    const result = truncateAtSectionBoundary("", 100);
+    assert.equal(result.content, "");
+    assert.equal(result.droppedSections, 0);
+  });
+
+  it("truncates at section boundary with ### markers", () => {
+    const content = [
+      "### Section A\nContent A is here.\n",
+      "### Section B\nContent B is here.\n",
+      "### Section C\nContent C is here.\n",
+    ].join("");
+
+    // Budget enough for section A only
+    const sectionALen = "### Section A\nContent A is here.\n".length;
+    const result = truncateAtSectionBoundary(content, sectionALen + 5);
+
+    assert.ok(result.content.includes("### Section A"), "should keep section A");
+    assert.ok(result.content.includes("Content A"), "should keep section A content");
+    assert.ok(!result.content.includes("### Section C"), "should drop section C");
+    assert.ok(result.content.includes("[...truncated"), "should include truncation indicator");
+    // Verify truncation count
+    assert.ok(result.content.includes("truncated 2 sections"), `should show 2 truncated, got: ${result.content}`);
+    assert.equal(result.droppedSections, 2);
+  });
+
+  it("truncates at --- divider boundaries", () => {
+    const content = "Intro text.\n\n---\n\nMiddle section.\n\n---\n\nFinal section.";
+    // Budget enough for intro only
+    const result = truncateAtSectionBoundary(content, 20);
+
+    assert.ok(result.content.includes("Intro text"), "should keep intro");
+    assert.ok(result.content.includes("[...truncated"), "should include truncation indicator");
+    assert.ok(result.droppedSections > 0, "should report dropped sections");
+  });
+
+  it("handles content with no section markers — keeps as much as fits", () => {
+    const content = "A".repeat(200);
+    const result = truncateAtSectionBoundary(content, 50);
+
+    assert.ok(result.content.length < 200, "should be shorter than original");
+    assert.ok(result.content.includes("[...truncated 1 sections]"), "should indicate truncation");
+    assert.ok(result.content.startsWith("AAAA"), "should keep content from the start");
+    assert.equal(result.droppedSections, 1);
+  });
+
+  it("handles content at exact boundary — returns unchanged", () => {
+    const content = "### Section 1\nText here.";
+    const result = truncateAtSectionBoundary(content, content.length);
+    assert.equal(result.content, content);
+    assert.equal(result.droppedSections, 0);
+  });
+
+  it("always keeps at least the first section even if it exceeds budget", () => {
+    const content = "### Long Section\n" + "X".repeat(500) + "\n\n### Short\nY";
+    const result = truncateAtSectionBoundary(content, 10);
+
+    // First section should be present even though it exceeds budget
+    assert.ok(result.content.includes("### Long Section"), "should keep first section");
+    assert.ok(result.content.includes("[...truncated 1 sections]"), "should indicate remaining sections dropped");
+    assert.equal(result.droppedSections, 1);
+  });
+});
+
+// ─── resolveExecutorContextWindow ────────────────────────────────────────────
+
+describe("context-budget: resolveExecutorContextWindow", () => {
+  it("returns configured executor model's contextWindow when found", () => {
+    const registry = makeRegistry([
+      makeModel("claude-opus-4-6", "anthropic", 200_000),
+      makeModel("claude-sonnet-4-20250514", "anthropic", 200_000),
+      makeModel("gpt-4o", "openai", 128_000),
+    ]);
+    const prefs: MinimalPreferences = {
+      models: { execution: "gpt-4o" },
+    };
+
+    const result = resolveExecutorContextWindow(registry, prefs);
+    assert.equal(result, 128_000);
+  });
+
+  it("supports provider/model format in preferences", () => {
+    const registry = makeRegistry([
+      makeModel("gpt-4o", "openai", 128_000),
+      makeModel("gpt-4o", "azure", 64_000),
+    ]);
+    const prefs: MinimalPreferences = {
+      models: { execution: "azure/gpt-4o" },
+    };
+
+    const result = resolveExecutorContextWindow(registry, prefs);
+    assert.equal(result, 64_000);
+  });
+
+  it("supports object format preferences with model + fallbacks", () => {
+    const registry = makeRegistry([
+      makeModel("claude-opus-4-6", "anthropic", 200_000),
+    ]);
+    const prefs: MinimalPreferences = {
+      models: { execution: { model: "claude-opus-4-6", fallbacks: ["gpt-4o"] } },
+    };
+
+    const result = resolveExecutorContextWindow(registry, prefs);
+    assert.equal(result, 200_000);
+  });
+
+  it("falls back to sessionContextWindow when executor model not found", () => {
+    const registry = makeRegistry([
+      makeModel("claude-opus-4-6", "anthropic", 200_000),
+    ]);
+    const prefs: MinimalPreferences = {
+      models: { execution: "nonexistent-model" },
+    };
+
+    const result = resolveExecutorContextWindow(registry, prefs, 300_000);
+    assert.equal(result, 300_000);
+  });
+
+  it("falls back to sessionContextWindow when no execution preference set", () => {
+    const registry = makeRegistry([
+      makeModel("claude-opus-4-6", "anthropic", 200_000),
+    ]);
+    const prefs: MinimalPreferences = { models: {} };
+
+    const result = resolveExecutorContextWindow(registry, prefs, 128_000);
+    assert.equal(result, 128_000);
+  });
+
+  it("falls back to 200K when no session and no executor model", () => {
+    const registry = makeRegistry([]);
+    const prefs: MinimalPreferences = { models: { execution: "missing" } };
+
+    const result = resolveExecutorContextWindow(registry, prefs);
+    assert.equal(result, 200_000);
+  });
+
+  it("falls back to 200K with undefined preferences", () => {
+    const result = resolveExecutorContextWindow(undefined, undefined);
+    assert.equal(result, 200_000);
+  });
+
+  it("falls back to 200K with undefined registry", () => {
+    const prefs: MinimalPreferences = { models: { execution: "claude-opus-4-6" } };
+    const result = resolveExecutorContextWindow(undefined, prefs);
+    assert.equal(result, 200_000);
+  });
+
+  it("ignores models with contextWindow ≤ 0", () => {
+    const registry = makeRegistry([
+      makeModel("broken-model", "test", 0),
+    ]);
+    const prefs: MinimalPreferences = { models: { execution: "broken-model" } };
+
+    const result = resolveExecutorContextWindow(registry, prefs, 128_000);
+    assert.equal(result, 128_000); // falls through to session
+  });
+
+  it("ignores sessionContextWindow ≤ 0", () => {
+    const registry = makeRegistry([]);
+    const prefs: MinimalPreferences = {};
+
+    const result = resolveExecutorContextWindow(registry, prefs, -1);
+    assert.equal(result, 200_000); // falls through to default
+  });
+});

package/src/resources/extensions/gsd/tests/context-compression.test.ts

@@ -128,7 +128,7 @@ test("compression: buildCompleteMilestonePrompt minimal drops root GSD files", (
   const block = promptsSrc.slice(completeMilestoneIdx, nextBuilder);
   assert.ok(
     block.includes('inlineLevel !== "minimal"') &&
-    block.includes('inlineGsdRootFile(base, "requirements.md"'),
+    (block.includes('inlineGsdRootFile(base, "requirements.md"') || block.includes('inlineRequirementsFromDb(base')),
     "complete-milestone should gate root file inlining on level",
   );
 });