gsd-pi 2.18.0 → 2.20.0

package/src/resources/extensions/gsd/guided-flow.ts

@@ -214,7 +214,11 @@ export function findMilestoneIds(basePath: string): string[] {
     // Apply custom queue order if available, else fall back to numeric sort
     const customOrder = loadQueueOrder(basePath);
     return sortByQueueOrder(ids, customOrder);
-  } catch {
+  } catch (err) {
+    // Log why milestone scanning failed — silent [] here causes infinite loops (#456)
+    if (existsSync(dir)) {
+      console.error(`[gsd] findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${err instanceof Error ? err.message : String(err)}`);
+    }
     return [];
   }
 }
@@ -1002,6 +1006,27 @@ export async function showSmartEntry(
     }
 
     const milestoneIds = findMilestoneIds(basePath);
+
+    // Sanity check (#456): if findMilestoneIds returns [] but the milestones
+    // directory has contents, something went wrong (permissions, stale worktree
+    // cwd, etc). Warn instead of silently starting a new-project flow.
+    if (milestoneIds.length === 0) {
+      const mDir = milestonesDir(basePath);
+      if (existsSync(mDir)) {
+        try {
+          const entries = readdirSync(mDir);
+          if (entries.length > 0) {
+            ctx.ui.notify(
+              `Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +
+              `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`,
+              "warning",
+            );
+            return;
+          }
+        } catch { /* directory exists but unreadable — fall through to normal flow */ }
+      }
+    }
+
     const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
     const nextId = nextMilestoneId(milestoneIds, uniqueMilestoneIds);
     const isFirst = milestoneIds.length === 0;

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

@@ -1,6 +1,5 @@
 // GSD Extension — Session History View
 // Human-readable display of past auto-mode unit executions.
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import {

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

@@ -24,7 +24,9 @@ import type {
   ExtensionContext,
 } from "@gsd/pi-coding-agent";
 import { createBashTool, createWriteTool, createReadTool, createEditTool, isToolCallEventType } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
+import { debugLog, debugTime } from "./debug-logger.js";
 import { registerGSDCommand, loadToolApiKeys } from "./commands.js";
 import { registerExitCommand } from "./exit-command.js";
 import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
@@ -53,10 +55,39 @@ import {
 import { Key } from "@gsd/pi-tui";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError } from "./provider-error-pause.js";
 
+// ── Agent Instructions ────────────────────────────────────────────────────
+// Lightweight "always follow" files injected into every GSD agent session.
+// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
+// Both are loaded and concatenated (global first, project appends).
+
+function loadAgentInstructions(): string | null {
+  const parts: string[] = [];
+
+  const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
+  if (existsSync(globalPath)) {
+    try {
+      const content = readFileSync(globalPath, "utf-8").trim();
+      if (content) parts.push(content);
+    } catch { /* non-fatal — skip unreadable file */ }
+  }
+
+  const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
+  if (existsSync(projectPath)) {
+    try {
+      const content = readFileSync(projectPath, "utf-8").trim();
+      if (content) parts.push(content);
+    } catch { /* non-fatal — skip unreadable file */ }
+  }
+
+  if (parts.length === 0) return null;
+  return parts.join("\n\n");
+}
+
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
 
@@ -190,6 +221,235 @@ export default function (pi: ExtensionAPI) {
   };
   pi.registerTool(dynamicEdit as any);
 
+  // ── Structured LLM tools — DB-first write path (R014) ──────────────────
+
+  pi.registerTool({
+    name: "gsd_save_decision",
+    label: "Save Decision",
+    description:
+      "Record a project decision to the GSD database and regenerate DECISIONS.md. " +
+      "Decision IDs are auto-assigned — never provide an ID manually.",
+    promptSnippet: "Record a project decision to the GSD database (auto-assigns ID, regenerates DECISIONS.md)",
+    promptGuidelines: [
+      "Use gsd_save_decision when recording an architectural, pattern, library, or observability decision.",
+      "Decision IDs are auto-assigned (D001, D002, ...) — never guess or provide an ID.",
+      "All fields except revisable and when_context are required.",
+      "The tool writes to the DB and regenerates .gsd/DECISIONS.md automatically.",
+    ],
+    parameters: Type.Object({
+      scope: Type.String({ description: "Scope of the decision (e.g. 'architecture', 'library', 'observability')" }),
+      decision: Type.String({ description: "What is being decided" }),
+      choice: Type.String({ description: "The choice made" }),
+      rationale: Type.String({ description: "Why this choice was made" }),
+      revisable: Type.Optional(Type.String({ description: "Whether this can be revisited (default: 'Yes')" })),
+      when_context: Type.Optional(Type.String({ description: "When/context for the decision (e.g. milestone ID)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      // Check DB availability
+      let dbAvailable = false;
+      try {
+        const db = await import("./gsd-db.js");
+        dbAvailable = db.isDbAvailable();
+      } catch { /* dynamic import failed */ }
+
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save decision." }],
+          isError: true,
+          details: { operation: "save_decision", error: "db_unavailable" },
+        };
+      }
+
+      try {
+        const { saveDecisionToDb } = await import("./db-writer.js");
+        const { id } = await saveDecisionToDb(
+          {
+            scope: params.scope,
+            decision: params.decision,
+            choice: params.choice,
+            rationale: params.rationale,
+            revisable: params.revisable,
+            when_context: params.when_context,
+          },
+          process.cwd(),
+        );
+        return {
+          content: [{ type: "text" as const, text: `Saved decision ${id}` }],
+          details: { operation: "save_decision", id },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
+          isError: true,
+          details: { operation: "save_decision", error: msg },
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_update_requirement",
+    label: "Update Requirement",
+    description:
+      "Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md. " +
+      "Provide the requirement ID (e.g. R001) and any fields to update.",
+    promptSnippet: "Update an existing GSD requirement by ID (regenerates REQUIREMENTS.md)",
+    promptGuidelines: [
+      "Use gsd_update_requirement to change status, validation, notes, or other fields on an existing requirement.",
+      "The id parameter is required — it must be an existing RXXX identifier.",
+      "All other fields are optional — only provided fields are updated.",
+      "The tool verifies the requirement exists before updating.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({ description: "The requirement ID (e.g. R001, R014)" }),
+      status: Type.Optional(Type.String({ description: "New status (e.g. 'active', 'validated', 'deferred')" })),
+      validation: Type.Optional(Type.String({ description: "Validation criteria or proof" })),
+      notes: Type.Optional(Type.String({ description: "Additional notes" })),
+      description: Type.Optional(Type.String({ description: "Updated description" })),
+      primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })),
+      supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      let dbAvailable = false;
+      try {
+        const db = await import("./gsd-db.js");
+        dbAvailable = db.isDbAvailable();
+      } catch { /* dynamic import failed */ }
+
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot update requirement." }],
+          isError: true,
+          details: { operation: "update_requirement", id: params.id, error: "db_unavailable" },
+        };
+      }
+
+      try {
+        // Verify requirement exists
+        const db = await import("./gsd-db.js");
+        const existing = db.getRequirementById(params.id);
+        if (!existing) {
+          return {
+            content: [{ type: "text" as const, text: `Error: Requirement ${params.id} not found.` }],
+            isError: true,
+            details: { operation: "update_requirement", id: params.id, error: "not_found" },
+          };
+        }
+
+        const { updateRequirementInDb } = await import("./db-writer.js");
+        const updates: Record<string, string | undefined> = {};
+        if (params.status !== undefined) updates.status = params.status;
+        if (params.validation !== undefined) updates.validation = params.validation;
+        if (params.notes !== undefined) updates.notes = params.notes;
+        if (params.description !== undefined) updates.description = params.description;
+        if (params.primary_owner !== undefined) updates.primary_owner = params.primary_owner;
+        if (params.supporting_slices !== undefined) updates.supporting_slices = params.supporting_slices;
+
+        await updateRequirementInDb(params.id, updates, process.cwd());
+
+        return {
+          content: [{ type: "text" as const, text: `Updated requirement ${params.id}` }],
+          details: { operation: "update_requirement", id: params.id },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
+          isError: true,
+          details: { operation: "update_requirement", id: params.id, error: msg },
+        };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "gsd_save_summary",
+    label: "Save Summary",
+    description:
+      "Save a summary, research, context, or assessment artifact to the GSD database and write it to disk. " +
+      "Computes the file path from milestone/slice/task IDs automatically.",
+    promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
+    promptGuidelines: [
+      "Use gsd_save_summary to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT).",
+      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+      "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
+      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT.",
+    ],
+    parameters: Type.Object({
+      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+      task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT" }),
+      content: Type.String({ description: "The full markdown content of the artifact" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      let dbAvailable = false;
+      try {
+        const db = await import("./gsd-db.js");
+        dbAvailable = db.isDbAvailable();
+      } catch { /* dynamic import failed */ }
+
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save artifact." }],
+          isError: true,
+          details: { operation: "save_summary", error: "db_unavailable" },
+        };
+      }
+
+      // Validate artifact_type
+      const validTypes = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT"];
+      if (!validTypes.includes(params.artifact_type)) {
+        return {
+          content: [{ type: "text" as const, text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${validTypes.join(", ")}` }],
+          isError: true,
+          details: { operation: "save_summary", error: "invalid_artifact_type" },
+        };
+      }
+
+      try {
+        // Compute relative path from IDs
+        let relativePath: string;
+        if (params.task_id && params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+        } else if (params.slice_id) {
+          relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+        } else {
+          relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+        }
+
+        const { saveArtifactToDb } = await import("./db-writer.js");
+        await saveArtifactToDb(
+          {
+            path: relativePath,
+            artifact_type: params.artifact_type,
+            content: params.content,
+            milestone_id: params.milestone_id,
+            slice_id: params.slice_id,
+            task_id: params.task_id,
+          },
+          process.cwd(),
+        );
+
+        return {
+          content: [{ type: "text" as const, text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
+          details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
+        return {
+          content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
+          isError: true,
+          details: { operation: "save_summary", error: msg },
+        };
+      }
+    },
+  });
+
   // ── session_start: render branded GSD header + load tool keys + remote status ──
   pi.on("session_start", async (_event, ctx) => {
     // Theme access throws in RPC mode (no TUI) — header is decorative, skip it
@@ -257,6 +517,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
     if (!existsSync(join(process.cwd(), ".gsd"))) return;
 
+    const stopContextTimer = debugTime("context-inject");
     const systemContent = loadPrompt("system");
     const loadedPreferences = loadEffectiveGSDPreferences();
     let preferenceBlock = "";
@@ -297,6 +558,13 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    // Load agent instructions (global + project)
+    let agentInstructionsBlock = "";
+    const agentInstructions = loadAgentInstructions();
+    if (agentInstructions) {
+      agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
+    }
+
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
 
     // Worktree context — override the static CWD in the system prompt
@@ -340,8 +608,16 @@ export default function (pi: ExtensionAPI) {
       ].join("\n");
     }
 
+    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${newSkillsBlock}${worktreeBlock}`;
+    stopContextTimer({
+      systemPromptSize: fullSystem.length,
+      injectionSize: injection?.length ?? 0,
+      hasPreferences: preferenceBlock.length > 0,
+      hasNewSkills: newSkillsBlock.length > 0,
+    });
+
     return {
-      systemPrompt: `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${newSkillsBlock}${worktreeBlock}`,
+      systemPrompt: fullSystem,
       ...(injection
         ? {
           message: {