gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -8,7 +8,7 @@ import { randomUUID } from "node:crypto";
 import { symlinkSync, realpathSync } from "node:fs";
 
 import { _getAdapter, closeDatabase } from "../../../src/resources/extensions/gsd/gsd-db.ts";
-import { registerWorkflowTools, WORKFLOW_TOOL_NAMES, validateProjectDir } from "./workflow-tools.ts";
+import { _buildImportCandidates, registerWorkflowTools, WORKFLOW_TOOL_NAMES, validateProjectDir } from "./workflow-tools.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-mcp-workflow-${randomUUID()}`);
@@ -69,6 +69,19 @@ function makeMockServer() {
   };
 }
 
+function assertToolError(result: unknown, expected: RegExp | string): string {
+  const record = result as { isError?: boolean; content?: Array<{ text?: unknown }> };
+  assert.equal(record.isError, true, "tool result should be marked as an MCP error");
+  const text = record.content?.[0]?.text;
+  assert.equal(typeof text, "string", "tool error result should contain text");
+  if (expected instanceof RegExp) {
+    assert.match(text, expected);
+  } else {
+    assert.ok(text.includes(expected), `error should mention ${expected}, got: ${text}`);
+  }
+  return text;
+}
+
 describe("workflow MCP tools", () => {
   it("registers the full headless-safe workflow tool surface", () => {
     const server = makeMockServer();
@@ -78,6 +91,18 @@ describe("workflow MCP tools", () => {
     assert.deepEqual(server.tools.map((t) => t.name), [...WORKFLOW_TOOL_NAMES]);
   });
 
+  it("prefers source TypeScript before compiled dist fallbacks", () => {
+    assert.deepEqual(
+      _buildImportCandidates("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js"),
+      [
+        "../../../src/resources/extensions/gsd/tools/workflow-tool-executors.ts",
+        "../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js",
+        "../../../dist/resources/extensions/gsd/tools/workflow-tool-executors.ts",
+        "../../../dist/resources/extensions/gsd/tools/workflow-tool-executors.js",
+      ],
+    );
+  });
+
   it("gsd_summary_save writes artifact through the shared executor", async () => {
     const base = makeTmpBase();
     try {
@@ -107,6 +132,116 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("gsd_summary_save supports root-level PROJECT artifacts without milestone_id", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_summary_save");
+      assert.ok(tool, "summary tool should be registered");
+
+      const milestoneParam = tool!.params.milestone_id as { isOptional?: () => boolean };
+      assert.equal(
+        milestoneParam.isOptional?.(),
+        true,
+        "workflow MCP schema must advertise milestone_id as optional for root artifacts",
+      );
+
+      const result = await tool!.handler({
+        projectDir: base,
+        artifact_type: "PROJECT",
+        content: "# Project\n\nRoot artifact",
+      });
+
+      const text = (result as any).content[0].text as string;
+      assert.match(text, /Saved PROJECT artifact/);
+      assert.ok(
+        existsSync(join(base, ".gsd", "PROJECT.md")),
+        "root project artifact should exist on disk",
+      );
+      assert.equal(
+        readFileSync(join(base, ".gsd", "PROJECT.md"), "utf-8"),
+        "# Project\n\nRoot artifact",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_summary_save rejects milestone-scoped artifacts without milestone_id", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_summary_save");
+      assert.ok(tool, "summary tool should be registered");
+
+      const result = await tool!.handler({
+        projectDir: base,
+        artifact_type: "SUMMARY",
+        content: "# Summary\n",
+      });
+
+      const text = (result as any).content?.[0]?.text as string;
+      assert.match(
+        text,
+        /milestone_id is required for milestone-scoped artifact types/,
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_summary_save renders root REQUIREMENTS from DB rows, not provided markdown", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const requirementTool = server.tools.find((t) => t.name === "gsd_requirement_save");
+      const summaryTool = server.tools.find((t) => t.name === "gsd_summary_save");
+      assert.ok(requirementTool, "requirement tool should be registered");
+      assert.ok(summaryTool, "summary tool should be registered");
+
+      await requirementTool!.handler({
+        projectDir: base,
+        class: "primary-user-loop",
+        description: "MCP user can add a task",
+        why: "Core loop",
+        source: "user",
+        status: "active",
+        primary_owner: "M001/none yet",
+        supporting_slices: "none",
+        validation: "unmapped",
+      });
+
+      const result = await summaryTool!.handler({
+        projectDir: base,
+        artifact_type: "REQUIREMENTS",
+        content: "# Requirements\n\n## Active\n\n### R999 — Wrong markdown source\n\n- Description: This content must not become canonical.\n",
+      });
+
+      const text = (result as any).content[0].text as string;
+      assert.match(text, /Saved REQUIREMENTS artifact/);
+
+      const requirementsPath = join(base, ".gsd", "REQUIREMENTS.md");
+      const markdown = readFileSync(requirementsPath, "utf-8");
+      assert.match(markdown, /MCP user can add a task/);
+      assert.doesNotMatch(markdown, /R999|Wrong markdown source|This content must not become canonical/);
+
+      const row = _getAdapter()!
+        .prepare("SELECT id, description FROM requirements WHERE description = ?")
+        .get("MCP user can add a task") as Record<string, unknown> | undefined;
+      assert.ok(row, "requirement row should remain the canonical source");
+
+      const artifact = _getAdapter()!
+        .prepare("SELECT full_content FROM artifacts WHERE path = ?")
+        .get("REQUIREMENTS.md") as Record<string, unknown> | undefined;
+      assert.equal(artifact?.full_content, markdown);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("rejects workflow tool calls outside the configured project root", async () => {
     const base = makeTmpBase();
     const otherBase = makeTmpBase();
@@ -118,16 +253,13 @@ describe("workflow MCP tools", () => {
       const tool = server.tools.find((t) => t.name === "gsd_summary_save");
       assert.ok(tool, "summary tool should be registered");
 
-      await assert.rejects(
-        () =>
-          tool!.handler({
-            projectDir: otherBase,
-            milestone_id: "M001",
-            artifact_type: "SUMMARY",
-            content: "# Summary",
-          }),
-        /configured workflow project root/,
-      );
+      const result = await tool!.handler({
+        projectDir: otherBase,
+        milestone_id: "M001",
+        artifact_type: "SUMMARY",
+        content: "# Summary",
+      });
+      assertToolError(result, /configured workflow project root/);
     } finally {
       if (prevRoot === undefined) {
         delete process.env.GSD_WORKFLOW_PROJECT_ROOT;
@@ -152,16 +284,13 @@ describe("workflow MCP tools", () => {
       const tool = server.tools.find((t) => t.name === "gsd_summary_save");
       assert.ok(tool, "summary tool should be registered");
 
-      await assert.rejects(
-        () =>
-          tool!.handler({
-            projectDir: base,
-            milestone_id: "M001",
-            artifact_type: "SUMMARY",
-            content: "# Summary",
-          }),
-        /only supports file: URLs or filesystem paths/,
-      );
+      const result = await tool!.handler({
+        projectDir: base,
+        milestone_id: "M001",
+        artifact_type: "SUMMARY",
+        content: "# Summary",
+      });
+      assertToolError(result, /only supports file: URLs or filesystem paths/);
     } finally {
       if (prevModule === undefined) {
         delete process.env.GSD_WORKFLOW_EXECUTORS_MODULE;
@@ -192,19 +321,16 @@ describe("workflow MCP tools", () => {
       const taskTool = server.tools.find((t) => t.name === "gsd_task_complete");
       assert.ok(taskTool, "task tool should be registered");
 
-      await assert.rejects(
-        () =>
-          taskTool!.handler({
-            projectDir: base,
-            taskId: "T01",
-            sliceId: "S01",
-            milestoneId: "M001",
-            oneLiner: "Completed task",
-            narrative: "Did the work",
-            verification: "npm test",
-          }),
-        /Discussion gate .* has not been confirmed/,
-      );
+      const result = await taskTool!.handler({
+        projectDir: base,
+        taskId: "T01",
+        sliceId: "S01",
+        milestoneId: "M001",
+        oneLiner: "Completed task",
+        narrative: "Did the work",
+        verification: "npm test",
+      });
+      assertToolError(result, /Discussion gate .* has not been confirmed/);
     } finally {
       cleanup(base);
     }
@@ -225,19 +351,16 @@ describe("workflow MCP tools", () => {
       const taskTool = server.tools.find((t) => t.name === "gsd_task_complete");
       assert.ok(taskTool, "task tool should be registered");
 
-      await assert.rejects(
-        () =>
-          taskTool!.handler({
-            projectDir: base,
-            taskId: "T01",
-            sliceId: "S01",
-            milestoneId: "M001",
-            oneLiner: "Completed task",
-            narrative: "Did the work",
-            verification: "npm test",
-          }),
-        /planning tool .* not executes work|Cannot gsd_task_complete|Unknown tools are not permitted during queue mode/,
-      );
+      const result = await taskTool!.handler({
+        projectDir: base,
+        taskId: "T01",
+        sliceId: "S01",
+        milestoneId: "M001",
+        oneLiner: "Completed task",
+        narrative: "Did the work",
+        verification: "npm test",
+      });
+      assertToolError(result, /planning tool .* not executes work|Cannot gsd_task_complete|Unknown tools are not permitted during queue mode/);
     } finally {
       cleanup(base);
     }
@@ -525,18 +648,8 @@ export const executeTaskComplete = async (params, projectDir) => {
       const expectRejection = async (toolName: string, args: Record<string, unknown>, expectedField: string) => {
         const tool = server.tools.find((t) => t.name === toolName);
         assert.ok(tool, `${toolName} should be registered`);
-        let caught: unknown;
-        try {
-          await tool!.handler(args);
-        } catch (err) {
-          caught = err;
-        }
-        assert.ok(caught, `${toolName} should reject empty ${expectedField}`);
-        const message = caught instanceof Error ? caught.message : String(caught);
-        assert.ok(
-          message.includes(expectedField),
-          `${toolName} error should mention ${expectedField}, got: ${message}`,
-        );
+        const result = await tool!.handler(args);
+        assertToolError(result, expectedField);
       };
 
       // Empty sliceId top-level
@@ -674,33 +787,27 @@ export const executeTaskComplete = async (params, projectDir) => {
       const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
       assert.ok(milestoneTool, "milestone planning tool should be registered");
 
-      let caught: unknown;
-      try {
-        await milestoneTool!.handler({
-          projectDir: base,
-          milestoneId: "M001",
-          title: "Workflow MCP planning",
-          vision: "Plan milestone over MCP.",
-          slices: [
-            {
-              sliceId: "S01",
-              title: "Bridge planning",
-              risk: "medium",
-              depends: [],
-              demo: "Milestone plan persists through MCP.",
-              goal: "Persist roadmap state.",
-              successCriteria: "",
-              proofLevel: "",
-              integrationClosure: "   ",
-              observabilityImpact: "",
-            },
-          ],
-        });
-      } catch (err) {
-        caught = err;
-      }
-      assert.ok(caught, "empty slice fields should be rejected");
-      const message = caught instanceof Error ? caught.message : String(caught);
+      const result = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M001",
+        title: "Workflow MCP planning",
+        vision: "Plan milestone over MCP.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Bridge planning",
+            risk: "medium",
+            depends: [],
+            demo: "Milestone plan persists through MCP.",
+            goal: "Persist roadmap state.",
+            successCriteria: "",
+            proofLevel: "",
+            integrationClosure: "   ",
+            observabilityImpact: "",
+          },
+        ],
+      });
+      const message = assertToolError(result, "successCriteria");
       for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
         assert.ok(
           message.includes(field),
@@ -733,30 +840,24 @@ export const executeTaskComplete = async (params, projectDir) => {
 
       // Arm 1: full slice (isSketch omitted) with the heavy fields missing
       // must reject and name ALL four fields so the agent can self-correct.
-      let fullError: unknown;
-      try {
-        await milestoneTool!.handler({
-          projectDir: base,
-          milestoneId: "M001",
-          title: "Full slice path",
-          vision: "Behavioral test for isSketch conditional.",
-          slices: [
-            {
-              sliceId: "S01",
-              title: "Heavy slice",
-              risk: "medium",
-              depends: [],
-              demo: "Demo.",
-              goal: "Goal.",
-              // heavy fields intentionally omitted
-            },
-          ],
-        });
-      } catch (err) {
-        fullError = err;
-      }
-      assert.ok(fullError, "a non-sketch slice without heavy fields must reject");
-      const fullMsg = fullError instanceof Error ? fullError.message : String(fullError);
+      const fullResult = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M001",
+        title: "Full slice path",
+        vision: "Behavioral test for isSketch conditional.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Heavy slice",
+            risk: "medium",
+            depends: [],
+            demo: "Demo.",
+            goal: "Goal.",
+            // heavy fields intentionally omitted
+          },
+        ],
+      });
+      const fullMsg = assertToolError(fullResult, "successCriteria");
       for (const field of ["successCriteria", "proofLevel", "integrationClosure", "observabilityImpact"]) {
         assert.ok(
           fullMsg.includes(field),
@@ -805,32 +906,25 @@ export const executeTaskComplete = async (params, projectDir) => {
       const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone");
       assert.ok(milestoneTool, "milestone planning tool should be registered");
 
-      let caught: unknown;
-      try {
-        await milestoneTool!.handler({
-          projectDir: base,
-          milestoneId: "M001",
-          title: "Sketch milestone",
-          vision: "Sketch first, refine later.",
-          slices: [
-            {
-              sliceId: "S01",
-              title: "Sketch slice",
-              risk: "low",
-              depends: [],
-              demo: "Stub demo.",
-              goal: "Stub goal.",
-              isSketch: true,
-              sketchScope: "",
-            },
-          ],
-        });
-      } catch (err) {
-        caught = err;
-      }
-      assert.ok(caught, "empty sketchScope should be rejected when isSketch=true");
-      const message = caught instanceof Error ? caught.message : String(caught);
-      assert.ok(message.includes("sketchScope"), `expected sketchScope error, got: ${message}`);
+      const emptySketchResult = await milestoneTool!.handler({
+        projectDir: base,
+        milestoneId: "M001",
+        title: "Sketch milestone",
+        vision: "Sketch first, refine later.",
+        slices: [
+          {
+            sliceId: "S01",
+            title: "Sketch slice",
+            risk: "low",
+            depends: [],
+            demo: "Stub demo.",
+            goal: "Stub goal.",
+            isSketch: true,
+            sketchScope: "",
+          },
+        ],
+      });
+      assertToolError(emptySketchResult, "sketchScope");
 
       const sketchResult = await milestoneTool!.handler({
         projectDir: base,

package/packages/mcp-server/src/workflow-tools.ts

@@ -192,7 +192,7 @@ type WorkflowToolExecutors = {
   ) => Promise<unknown>;
   executeSummarySave: (
     params: {
-      milestone_id: string;
+      milestone_id?: string;
       slice_id?: string;
       task_id?: string;
       artifact_type: string;
@@ -428,6 +428,29 @@ function getSupportedSummaryArtifactTypes(executors: WorkflowToolExecutors): rea
   return executors.SUPPORTED_SUMMARY_ARTIFACT_TYPES;
 }
 
+function buildImportCandidates(relativePath: string): string[] {
+  const candidates: string[] = [];
+  const pushPreferredPair = (path: string | null) => {
+    if (!path) return;
+    if (path.endsWith(".js")) candidates.push(path.replace(/\.js$/, ".ts"));
+    candidates.push(path);
+  };
+
+  const sourcePath = relativePath.includes("/dist/")
+    ? relativePath.replace("/dist/", "/src/")
+    : relativePath;
+  const distPath = relativePath.includes("/src/")
+    ? relativePath.replace("/src/", "/dist/")
+    : relativePath.includes("/dist/")
+      ? relativePath
+      : null;
+
+  pushPreferredPair(sourcePath);
+  pushPreferredPair(distPath);
+
+  return [...new Set(candidates)];
+}
+
 function getWriteGateModuleCandidates(): string[] {
   const candidates: string[] = [];
   const explicitModule = process.env.GSD_WORKFLOW_WRITE_GATE_MODULE?.trim();
@@ -435,13 +458,13 @@ function getWriteGateModuleCandidates(): string[] {
     if (/^[a-z]{2,}:/i.test(explicitModule) && !explicitModule.startsWith("file:")) {
       throw new Error("GSD_WORKFLOW_WRITE_GATE_MODULE only supports file: URLs or filesystem paths.");
     }
+    warnCustomWorkflowModule("GSD_WORKFLOW_WRITE_GATE_MODULE", explicitModule);
     candidates.push(explicitModule.startsWith("file:") ? explicitModule : toFileUrl(explicitModule));
   }
 
   candidates.push(
-    new URL("../../../src/resources/extensions/gsd/bootstrap/write-gate.js", import.meta.url).href,
-    new URL("../../../dist/resources/extensions/gsd/bootstrap/write-gate.js", import.meta.url).href,
-    new URL("../../../src/resources/extensions/gsd/bootstrap/write-gate.ts", import.meta.url).href,
+    ...buildImportCandidates("../../../src/resources/extensions/gsd/bootstrap/write-gate.js")
+      .map((p) => new URL(p, import.meta.url).href),
   );
 
   return [...new Set(candidates)];
@@ -451,28 +474,37 @@ function toFileUrl(modulePath: string): string {
   return pathToFileURL(resolve(modulePath)).href;
 }
 
+const warnedCustomWorkflowModuleVars = new Set<string>();
+
+/**
+ * Emit a one-time stderr warning when GSD_WORKFLOW_EXECUTORS_MODULE or
+ * GSD_WORKFLOW_WRITE_GATE_MODULE is set. These overrides exist for dev/test
+ * use, but they let the env owner load arbitrary local modules. The warning
+ * makes accidental or hostile use loud rather than silent.
+ */
+function warnCustomWorkflowModule(varName: string, value: string): void {
+  if (warnedCustomWorkflowModuleVars.has(varName)) return;
+  warnedCustomWorkflowModuleVars.add(varName);
+  process.stderr.write(
+    `[gsd-mcp-server] WARNING: ${varName} is set (${value}). ` +
+    `Custom workflow modules will be loaded from this path. ` +
+    `Unset for production use.\n`,
+  );
+}
+
 /** @internal — exported for testing only */
 export function _buildImportCandidates(relativePath: string): string[] {
-  // Build candidate paths: try the given path first, then swap src/<->dist/
-  // and try .ts extension. This handles both dev (tsx from src/) and prod
-  // (compiled from dist/) execution contexts.
-  const candidates: string[] = [relativePath];
-  const swapped = relativePath.includes("/src/")
-    ? relativePath.replace("/src/", "/dist/")
-    : relativePath.includes("/dist/")
-      ? relativePath.replace("/dist/", "/src/")
-      : null;
-  if (swapped) candidates.push(swapped);
-  // Also try .ts variants for dev-mode tsx execution
-  if (relativePath.endsWith(".js")) {
-    candidates.push(relativePath.replace(/\.js$/, ".ts"));
-    if (swapped) candidates.push(swapped.replace(/\.js$/, ".ts"));
-  }
-  return candidates;
+  // Build candidate paths: prefer source first, including the .ts source
+  // variant, before falling back to compiled dist. In source/dev execution a
+  // stale dist/resources tree must not silently override edited source files.
+  return buildImportCandidates(relativePath);
 }
 
 async function importLocalModule<T>(relativePath: string): Promise<T> {
-  const candidates = _buildImportCandidates(relativePath)
+  const rawCandidates = _buildImportCandidates(relativePath);
+  const candidates = (import.meta.url.includes("/dist-test/") || import.meta.url.includes("\\dist-test\\")
+    ? [...rawCandidates].sort((a, b) => Number(a.endsWith(".ts")) - Number(b.endsWith(".ts")))
+    : rawCandidates)
     .map((p) => new URL(p, import.meta.url).href);
 
   let lastErr: unknown;
@@ -493,13 +525,13 @@ function getWorkflowExecutorModuleCandidates(env: NodeJS.ProcessEnv = process.en
     if (/^[a-z]{2,}:/i.test(explicitModule) && !explicitModule.startsWith("file:")) {
       throw new Error("GSD_WORKFLOW_EXECUTORS_MODULE only supports file: URLs or filesystem paths.");
     }
+    warnCustomWorkflowModule("GSD_WORKFLOW_EXECUTORS_MODULE", explicitModule);
     candidates.push(explicitModule.startsWith("file:") ? explicitModule : toFileUrl(explicitModule));
   }
 
   candidates.push(
-    new URL("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js", import.meta.url).href,
-    new URL("../../../dist/resources/extensions/gsd/tools/workflow-tool-executors.js", import.meta.url).href,
-    new URL("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.ts", import.meta.url).href,
+    ...buildImportCandidates("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js")
+      .map((p) => new URL(p, import.meta.url).href),
   );
 
   return [...new Set(candidates)];
@@ -1188,13 +1220,28 @@ const sliceCompleteSchema = z.object(sliceCompleteParams);
 
 const summarySaveParams = {
   projectDir: projectDirParam,
-  milestone_id: z.string().describe("Milestone ID (e.g. M001)"),
+  milestone_id: z.string().optional().describe("Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts."),
   slice_id: z.string().optional().describe("Slice ID (e.g. S01)"),
   task_id: z.string().optional().describe("Task ID (e.g. T01)"),
-  artifact_type: z.string().describe("Artifact type to save (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT)"),
+  artifact_type: z.string().describe("Artifact type to save (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT)"),
   content: z.string().describe("The full markdown content of the artifact"),
 };
-const summarySaveSchema = z.object(summarySaveParams);
+const ROOT_SUMMARY_ARTIFACT_TYPES = new Set([
+  "PROJECT",
+  "PROJECT-DRAFT",
+  "REQUIREMENTS",
+  "REQUIREMENTS-DRAFT",
+]);
+const summarySaveSchema = z.object(summarySaveParams).superRefine((value, ctx) => {
+  const isRootArtifact = ROOT_SUMMARY_ARTIFACT_TYPES.has(value.artifact_type);
+  if (!isRootArtifact && (!value.milestone_id || value.milestone_id.trim() === "")) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["milestone_id"],
+      message: "milestone_id is required for milestone-scoped artifact types",
+    });
+  }
+});
 
 const decisionSaveParams = {
   projectDir: projectDirParam,
@@ -1222,7 +1269,7 @@ const requirementUpdateSchema = z.object(requirementUpdateParams);
 
 const requirementSaveParams = {
   projectDir: projectDirParam,
-  class: z.string().describe("Requirement class"),
+  class: z.string().describe("Requirement class: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, or anti-feature"),
   description: z.string().describe("Short description of the requirement"),
   why: z.string().describe("Why this requirement matters"),
   source: z.string().describe("Origin of the requirement"),
@@ -1320,7 +1367,39 @@ const journalQueryParams = {
 };
 const journalQuerySchema = z.object(journalQueryParams);
 
-export function registerWorkflowTools(server: McpToolServer): void {
+/**
+ * Wrap a real McpToolServer so every handler we register catches thrown
+ * errors and returns a structured `{isError: true, content: [...]}` MCP
+ * tool result instead of letting the SDK convert the throw into a
+ * JSON-RPC error frame. Some MCP hosts (notably Cursor) surface JSON-RPC
+ * errors as a generic "tool failed" with no message, which strips the
+ * agent of the context it needs to recover (write-gate blocks, schema
+ * mismatches, downstream RPC failures).
+ *
+ * Read-only tools in server.ts use the same pattern via per-handler
+ * try/catch + errorContent(). This shim applies it uniformly to every
+ * mutation handler in this module.
+ */
+function wrapServerWithErrorHandler(realServer: McpToolServer): McpToolServer {
+  return {
+    tool(name, description, params, handler) {
+      return realServer.tool(name, description, params, async (args) => {
+        try {
+          return await handler(args);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true as const,
+            content: [{ type: "text" as const, text: message }],
+          };
+        }
+      });
+    },
+  };
+}
+
+export function registerWorkflowTools(realServer: McpToolServer): void {
+  const server = wrapServerWithErrorHandler(realServer);
   server.tool(
     "gsd_decision_save",
     "Record a project decision to the GSD database and regenerate DECISIONS.md.",
@@ -1669,12 +1748,12 @@ export function registerWorkflowTools(server: McpToolServer): void {
 
   server.tool(
     "gsd_summary_save",
-    "Save a GSD summary/research/context/assessment artifact to the database and disk.",
+    "Save a GSD summary/research/context/assessment artifact to the database and disk. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts.",
     summarySaveParams,
     async (args: Record<string, unknown>) => {
       const parsed = parseWorkflowArgs(summarySaveSchema, args);
       const { projectDir, milestone_id, slice_id, task_id, artifact_type, content } = parsed;
-      await enforceWorkflowWriteGate("gsd_summary_save", projectDir, milestone_id);
+      await enforceWorkflowWriteGate("gsd_summary_save", projectDir, milestone_id ?? null);
       const executors = await getWorkflowToolExecutors();
       const supportedArtifactTypes = getSupportedSummaryArtifactTypes(executors);
       if (!supportedArtifactTypes.includes(artifact_type)) {