gsd-pi 2.17.0 → 2.18.0

package/dist/resources/extensions/gsd/index.ts

@@ -28,10 +28,11 @@ import { createBashTool, createWriteTool, createReadTool, createEditTool, isTool
 import { registerGSDCommand, loadToolApiKeys } from "./commands.js";
 import { registerExitCommand } from "./exit-command.js";
 import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
+import { getActiveAutoWorktreeContext } from "./auto-worktree.js";
 import { saveFile, formatContinue, loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
-import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData } from "./auto.js";
+import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData, markToolStart, markToolEnd } from "./auto.js";
 import { saveActivityLog } from "./activity-log.js";
 import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId } from "./guided-flow.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
@@ -47,10 +48,11 @@ import {
   resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTaskFiles, resolveTasksDir,
   relSliceFile, relSlicePath, relTaskFile,
   buildSliceFileName, buildMilestoneFileName, gsdRoot, resolveMilestonePath,
+  resolveGsdRootFile,
 } from "./paths.js";
 import { Key } from "@gsd/pi-tui";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError } from "./provider-error-pause.js";
@@ -272,6 +274,20 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    // Load project knowledge if available
+    let knowledgeBlock = "";
+    const knowledgePath = resolveGsdRootFile(process.cwd(), "KNOWLEDGE");
+    if (existsSync(knowledgePath)) {
+      try {
+        const content = readFileSync(knowledgePath, "utf-8").trim();
+        if (content) {
+          knowledgeBlock = `\n\n[PROJECT KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${content}`;
+        }
+      } catch {
+        // File read error — skip knowledge injection
+      }
+    }
+
     // Detect skills installed during this auto-mode session
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
@@ -287,6 +303,7 @@ export default function (pi: ExtensionAPI) {
     let worktreeBlock = "";
     const worktreeName = getActiveWorktreeName();
     const worktreeMainCwd = getWorktreeOriginalCwd();
+    const autoWorktree = getActiveAutoWorktreeContext();
     if (worktreeName && worktreeMainCwd) {
       worktreeBlock = [
         "",
@@ -304,10 +321,27 @@ export default function (pi: ExtensionAPI) {
         "All file operations, bash commands, and GSD state resolve against the worktree path above.",
         "Use /worktree merge to merge changes back. Use /worktree return to switch back to the main tree.",
       ].join("\n");
+    } else if (autoWorktree) {
+      worktreeBlock = [
+        "",
+        "",
+        "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
+        `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
+        `The actual current working directory is: ${process.cwd()}`,
+        "",
+        "You are working inside a GSD auto-worktree.",
+        `- Milestone worktree: ${autoWorktree.worktreeName}`,
+        `- Worktree path (this is the real cwd): ${process.cwd()}`,
+        `- Main project: ${autoWorktree.originalBase}`,
+        `- Branch: ${autoWorktree.branch}`,
+        "",
+        "All file operations, bash commands, and GSD state resolve against the worktree path above.",
+        "Write every .gsd artifact in the worktree path above, never in the main project tree.",
+      ].join("\n");
     }
 
     return {
-      systemPrompt: `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${newSkillsBlock}${worktreeBlock}`,
+      systemPrompt: `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${newSkillsBlock}${worktreeBlock}`,
       ...(injection
         ? {
           message: {
@@ -542,6 +576,16 @@ export default function (pi: ExtensionAPI) {
     const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
     await saveFile(discussionPath, existing + newBlock);
   });
+
+  // ── tool_execution_start/end: track in-flight tools for idle detection ──
+  pi.on("tool_execution_start", async (event) => {
+    if (!isAutoActive()) return;
+    markToolStart(event.toolCallId);
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    markToolEnd(event.toolCallId);
+  });
 }
 
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {

package/dist/resources/extensions/gsd/paths.ts

@@ -15,6 +15,9 @@ import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js"
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
+/** Max entries before eviction. Prevents unbounded growth in long sessions (#611). */
+const DIR_CACHE_MAX = 200;
+
 const dirEntryCache = new Map<string, Dirent[]>();
 const dirListCache = new Map<string, string[]>();
 
@@ -85,6 +88,7 @@ function cachedReaddirWithTypes(dirPath: string): Dirent[] {
           d.isSocket = () => false;
           return d;
         });
+        if (dirEntryCache.size >= DIR_CACHE_MAX) dirEntryCache.clear();
         dirEntryCache.set(dirPath, dirents);
         return dirents;
       }
@@ -92,6 +96,7 @@ function cachedReaddirWithTypes(dirPath: string): Dirent[] {
   }
 
   const entries = readdirSync(dirPath, { withFileTypes: true });
+  if (dirEntryCache.size >= DIR_CACHE_MAX) dirEntryCache.clear();
   dirEntryCache.set(dirPath, entries);
   return entries;
 }
@@ -107,6 +112,7 @@ function cachedReaddir(dirPath: string): string[] {
       const treeEntries = nativeTreeCache.get(key);
       if (treeEntries) {
         const names = treeEntries.map(e => e.name);
+        if (dirListCache.size >= DIR_CACHE_MAX) dirListCache.clear();
         dirListCache.set(dirPath, names);
         return names;
       }
@@ -114,6 +120,7 @@ function cachedReaddir(dirPath: string): string[] {
   }
 
   const entries = readdirSync(dirPath);
+  if (dirListCache.size >= DIR_CACHE_MAX) dirListCache.clear();
   dirListCache.set(dirPath, entries);
   return entries;
 }
@@ -248,6 +255,7 @@ export const GSD_ROOT_FILES = {
   STATE: "STATE.md",
   REQUIREMENTS: "REQUIREMENTS.md",
   OVERRIDES: "OVERRIDES.md",
+  KNOWLEDGE: "KNOWLEDGE.md",
 } as const;
 
 export type GSDRootFileKey = keyof typeof GSD_ROOT_FILES;
@@ -259,6 +267,7 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   STATE: "state.md",
   REQUIREMENTS: "requirements.md",
   OVERRIDES: "overrides.md",
+  KNOWLEDGE: "knowledge.md",
 };
 
 export function gsdRoot(basePath: string): string {

package/dist/resources/extensions/gsd/preferences.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
@@ -1252,3 +1252,61 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
   return (prefs?.preferences.pre_dispatch_hooks ?? [])
     .filter(h => h.enabled !== false);
 }
+
+/**
+ * Validate a model ID string.
+ * Returns true if the ID looks like a valid model identifier.
+ */
+export function validateModelId(modelId: string): boolean {
+  if (!modelId || typeof modelId !== "string") return false;
+  const trimmed = modelId.trim();
+  if (trimmed.length === 0 || trimmed.length > 256) return false;
+  // Allow alphanumeric, hyphens, underscores, dots, slashes, colons
+  return /^[a-zA-Z0-9\-_./:]+$/.test(trimmed);
+}
+
+/**
+ * Update the models section of the global GSD preferences file.
+ * Performs a safe read-modify-write: reads current content, updates the models
+ * YAML block, and writes back. Creates the file if it doesn't exist.
+ */
+export function updatePreferencesModels(models: GSDModelConfigV2): void {
+  const prefsPath = getGlobalGSDPreferencesPath();
+
+  let content = "";
+  if (existsSync(prefsPath)) {
+    content = readFileSync(prefsPath, "utf-8");
+  }
+
+  // Build the new models block
+  const lines: string[] = ["models:"];
+  for (const [phase, value] of Object.entries(models)) {
+    if (typeof value === "string") {
+      lines.push(`  ${phase}: ${value}`);
+    } else if (value && typeof value === "object") {
+      const config = value as GSDPhaseModelConfig;
+      lines.push(`  ${phase}:`);
+      lines.push(`    model: ${config.model}`);
+      if (config.provider) {
+        lines.push(`    provider: ${config.provider}`);
+      }
+      if (config.fallbacks && config.fallbacks.length > 0) {
+        lines.push(`    fallbacks:`);
+        for (const fb of config.fallbacks) {
+          lines.push(`      - ${fb}`);
+        }
+      }
+    }
+  }
+  const modelsBlock = lines.join("\n");
+
+  // Replace existing models block or append
+  const modelsRegex = /^models:[\s\S]*?(?=\n[a-z_]|\n*$)/m;
+  if (modelsRegex.test(content)) {
+    content = content.replace(modelsRegex, modelsBlock);
+  } else {
+    content = content.trimEnd() + "\n\n" + modelsBlock + "\n";
+  }
+
+  writeFileSync(prefsPath, content, "utf-8");
+}

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -54,11 +54,12 @@ Then:
     - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
 12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined templates below if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
-13. Use the **Task Summary** output template from the inlined templates below
-14. Write `{{taskSummaryPath}}`
-15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
-16. Do not commit manually — the system auto-commits your changes after this unit completes.
-17. Update `.gsd/STATE.md`
+13. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
+14. Use the **Task Summary** output template from the inlined templates below
+15. Write `{{taskSummaryPath}}`
+16. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
+17. Do not commit manually — the system auto-commits your changes after this unit completes.
+18. Update `.gsd/STATE.md`
 
 All work stays in your working directory: `{{workingDirectory}}`.
 

package/dist/resources/extensions/gsd/prompts/system.md

@@ -65,6 +65,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
   PROJECT.md            (living doc - what the project is right now)
   REQUIREMENTS.md       (requirement contract - tracks active/validated/deferred/out-of-scope)
   DECISIONS.md          (append-only register of architectural and pattern decisions)
+  KNOWLEDGE.md          (append-only register of project-specific rules, patterns, and lessons learned)
   OVERRIDES.md          (user-issued overrides that supersede plan content via /gsd steer)
   QUEUE.md              (append-only log of queued milestones via /gsd queue)
   STATE.md
@@ -100,6 +101,7 @@ All auto-mode work happens inside a worktree at `.gsd/worktrees/<MID>/`. This is
 - **PROJECT.md** is a living document describing what the project is right now - current state only, updated at slice completion when stale
 - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change.
 - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made
+- **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow.
 - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing.
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.

package/dist/resources/extensions/gsd/queue-order.ts

@@ -0,0 +1,231 @@
+/**
+ * GSD Queue Order — Custom milestone execution ordering.
+ *
+ * Stores an explicit execution order in `.gsd/QUEUE-ORDER.json`.
+ * When present, `findMilestoneIds()` uses this order instead of
+ * the default numeric sort (milestoneIdSort).
+ *
+ * The file is committed to git (not gitignored) so ordering
+ * survives branch switches and is shared across sessions.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { milestoneIdSort } from "./guided-flow.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface QueueOrderFile {
+  order: string[];
+  updatedAt: string;
+}
+
+export interface DependencyViolation {
+  milestone: string;
+  dependsOn: string;
+  type: 'would_block' | 'circular' | 'missing_dep';
+  message: string;
+}
+
+export interface DependencyRedundancy {
+  milestone: string;
+  dependsOn: string;
+}
+
+export interface DependencyValidation {
+  valid: boolean;
+  violations: DependencyViolation[];
+  redundant: DependencyRedundancy[];
+}
+
+// ─── Path ────────────────────────────────────────────────────────────────────
+
+function queueOrderPath(basePath: string): string {
+  return join(gsdRoot(basePath), "QUEUE-ORDER.json");
+}
+
+// ─── Read / Write ────────────────────────────────────────────────────────────
+
+/**
+ * Load the custom queue order. Returns null if no file exists or if
+ * the file is corrupt/unreadable.
+ */
+export function loadQueueOrder(basePath: string): string[] | null {
+  const p = queueOrderPath(basePath);
+  if (!existsSync(p)) return null;
+  try {
+    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
+    if (!Array.isArray(data.order)) return null;
+    return data.order;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a custom queue order to disk.
+ */
+export function saveQueueOrder(basePath: string, order: string[]): void {
+  const data: QueueOrderFile = {
+    order,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+// ─── Sorting ─────────────────────────────────────────────────────────────────
+
+/**
+ * Sort milestone IDs respecting a custom order.
+ *
+ * - IDs present in `customOrder` appear in that exact sequence.
+ * - IDs on disk but NOT in `customOrder` are appended at the end,
+ *   sorted by the default `milestoneIdSort` (numeric).
+ * - IDs in `customOrder` but NOT on disk are silently skipped.
+ * - When `customOrder` is null, falls back to `milestoneIdSort`.
+ */
+export function sortByQueueOrder(ids: string[], customOrder: string[] | null): string[] {
+  if (!customOrder) return [...ids].sort(milestoneIdSort);
+
+  const idSet = new Set(ids);
+  const ordered: string[] = [];
+
+  // First: IDs from customOrder that exist on disk
+  for (const id of customOrder) {
+    if (idSet.has(id)) {
+      ordered.push(id);
+      idSet.delete(id);
+    }
+  }
+
+  // Then: remaining IDs not in customOrder, in default sort order
+  const remaining = [...idSet].sort(milestoneIdSort);
+  return [...ordered, ...remaining];
+}
+
+// ─── Pruning ─────────────────────────────────────────────────────────────────
+
+/**
+ * Remove IDs from the queue order file that are no longer valid
+ * (completed or deleted milestones). No-op if file doesn't exist.
+ */
+export function pruneQueueOrder(basePath: string, validIds: string[]): void {
+  const order = loadQueueOrder(basePath);
+  if (!order) return;
+
+  const validSet = new Set(validIds);
+  const pruned = order.filter(id => validSet.has(id));
+
+  if (pruned.length !== order.length) {
+    saveQueueOrder(basePath, pruned);
+  }
+}
+
+// ─── Validation ──────────────────────────────────────────────────────────────
+
+/**
+ * Validate a proposed queue order against dependency constraints.
+ *
+ * Checks:
+ * - would_block: A milestone is placed before one of its dependencies
+ * - circular: Two or more milestones form a dependency cycle
+ * - missing_dep: A milestone depends on an ID that doesn't exist
+ * - redundant: A dependency is satisfied by queue position (dep comes earlier)
+ */
+export function validateQueueOrder(
+  order: string[],
+  depsMap: Map<string, string[]>,
+  completedIds: Set<string>,
+): DependencyValidation {
+  const violations: DependencyViolation[] = [];
+  const redundant: DependencyRedundancy[] = [];
+
+  const positionMap = new Map<string, number>();
+  for (let i = 0; i < order.length; i++) {
+    positionMap.set(order[i], i);
+  }
+
+  const allKnownIds = new Set([...order, ...completedIds]);
+
+  for (const [mid, deps] of depsMap) {
+    const midPos = positionMap.get(mid);
+    if (midPos === undefined) continue; // not in pending order
+
+    for (const dep of deps) {
+      // Dep already completed — always satisfied
+      if (completedIds.has(dep)) continue;
+
+      // Dep doesn't exist anywhere
+      if (!allKnownIds.has(dep)) {
+        violations.push({
+          milestone: mid,
+          dependsOn: dep,
+          type: 'missing_dep',
+          message: `${mid} depends on ${dep}, but ${dep} does not exist.`,
+        });
+        continue;
+      }
+
+      const depPos = positionMap.get(dep);
+      if (depPos === undefined) continue; // dep not in pending order (edge case)
+
+      if (depPos > midPos) {
+        // Dep comes AFTER this milestone in the order — violation
+        violations.push({
+          milestone: mid,
+          dependsOn: dep,
+          type: 'would_block',
+          message: `${mid} cannot run before ${dep} — ${mid} depends_on: [${dep}].`,
+        });
+      } else {
+        // Dep comes before — satisfied by position, redundant
+        redundant.push({ milestone: mid, dependsOn: dep });
+      }
+    }
+  }
+
+  // Check for circular dependencies
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function hasCycle(node: string, path: string[]): string[] | null {
+    if (inStack.has(node)) return [...path, node];
+    if (visited.has(node)) return null;
+
+    visited.add(node);
+    inStack.add(node);
+
+    const deps = depsMap.get(node) ?? [];
+    for (const dep of deps) {
+      if (completedIds.has(dep)) continue;
+      const cycle = hasCycle(dep, [...path, node]);
+      if (cycle) return cycle;
+    }
+
+    inStack.delete(node);
+    return null;
+  }
+
+  for (const mid of order) {
+    if (!visited.has(mid)) {
+      const cycle = hasCycle(mid, []);
+      if (cycle) {
+        const cycleStr = cycle.join(' → ');
+        violations.push({
+          milestone: cycle[0],
+          dependsOn: cycle[cycle.length - 2],
+          type: 'circular',
+          message: `Circular dependency: ${cycleStr}`,
+        });
+        break; // one cycle report is enough
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+    redundant,
+  };
+}